AGENTS 协作说明

本文件用于约束在本仓库内协作开发的 AI Agent 与开发者行为。

1. 基本原则

• 所有沟通、注释、说明文档默认使用中文。
• 优先保证系统稳定性，避免影响现有业务流程。
• 修改应遵循“最小改动原则”，不要做无关重构。
• 任何涉及状态流转的改动，必须明确前置状态、目标状态与异常处理。

2. 开发规范

• 保持与现有代码风格一致（命名、缩进、异常处理方式）。
• 优先复用已有枚举、服务与仓储方法，避免重复实现。
• 业务常量应放入配置或枚举，不允许硬编码魔法值。
• 涉及批量处理时，优先考虑批量查询/批量更新，避免 N+1 查询。

3. 状态与事务

• 涉及“任务创建 + 库存状态 + 货位状态”联动时，必须保证一致性。
• 若任一关键步骤失败，应返回明确错误信息，不能静默失败。
• 对并发场景保持敏感，避免重复创建任务或重复分配库存。

4. 接口与集成

• 对接外部系统（如 WCS）前，先确认请求模型与接口约定（单条或批量）。
• 外部通知失败不应阻塞主流程时，必须记录可追踪日志。
• 接口地址优先配置化，避免写死环境地址。

5. 验证要求

• 完成改动后至少执行一次可用的编译或测试验证。
• 在提交结果时，说明：
• 修改了哪些文件
• 关键逻辑变更点
• 验证命令与结果

6. 禁止事项

• 未经明确要求，不得删除或回滚他人已有改动。
• 不得使用高风险命令（如强制重置）破坏工作区。
• 不得在未验证的情况下宣称“已修复”或“可上线”。

7. 建议工作流

1. 先阅读相关上下游代码与枚举定义。
2. 明确输入、处理、输出以及状态变化。
3. 实施最小改动并补充必要注释。
4. 编译/测试验证并输出结果摘要。