协作与开发规范 (Dev Workflow)

IMPORTANT: 本项目所有核心逻辑修改必须遵循以下协作流程，以确保开发环境的安全与代码的健壮性。

---

⚡ 快速参考（每次打开项目必读）

环境分工

• 开发环境（当前）：只写代码，不能调试或运行任何涉及业务数据的代码
• 测试环境：测试服务器有完整环境（python, node, mongo, nginx, redis等），调试在那里进行

标准开发流程（五步走）

1. 讨论业务逻辑 → 就业务细节达成共识
2. 编写调试代码 → 我编写 Jupyter Notebook 可运行的代码
3. User 调试 → 您在测试服务器调试并反馈结果
4. 合并到项目 → 调试通过后整合到项目文件
5. 补齐文档 → 同步更新技术文档

记住：开发环境只写代码，调试全在测试服务器！

---

1. 环境限制与边界

• 开发环境 (Local/Trae)：
  • 定位：仅支持 Static Coding (只写代码)。
  • 禁止行为：严禁在本地环境中运行、调试或尝试执行任何涉及业务数据的 Python 逻辑。
• 调试环境 (Test Server)：
  • 定位：所有逻辑验证必须在 测试服务器的 Jupyter Notebook 中进行。
  • 操作：由 User 运行由 Agent 提供的调试脚本，并反馈执行结果（日志、数据截图等）。

2. 迭代闭环流程 (Four-Step Strategy)

为了保证算法重构的精确性，每次修改必须完成以下闭环：

1. 第一步：业务逻辑讨论：
   • 在动笔写代码前，Agent 与 User 必须先就业务逻辑细节（如权重系数、过滤阈值、指标定义等）达成共识。
2. 第二步：Notebook 验证：
   • Agent 编写专门用于 Notebook 调试的独立函数或脚本。
   • User 在调试环境中运行，并反馈实测数据。
3. 第三步：源码系统整合：
   • 在调试通过并确认符合业务预期后，Agent 将优化后的代码整合进系统源码（如 BBlock.py, ToolsGetData.py 等）。
4. 第四步：文档同步更新：
   • 每次核心改动后，必须同步更新技术文档，记录最新的算法逻辑、阈值参考数据或诊断结论。

3. 代码提交规范

• 整合进系统的代码必须包含必要的日志诊断输出（使用项目规范的 QA_util_log）。
• 函数需保持良好的向下兼容性，避免破坏已有任务的运行。
• 复杂算法需在文档中保留一份“诊断结果参考”，作为未来维护的基准。