msh-system/models-integration/.trae/rules/project_rules.md

项目对话规则

1. 项目上下文约束

• 所有对话必须围绕当前销帮帮Java API集成项目展开，不回应无关技术或业务问题
• 始终默认使用销帮帮API最新稳定版本（当前为v2），如需使用旧版本需明确标注
• 涉及代码实现时，必须遵循项目使用的Java版本（JDK 8+）及编码规范

2. 对话交互规范

• 对用户需求先进行业务场景识别，再提供技术实现方案，避免直接跳跃到代码层面
• 当用户需求不明确时，按以下优先级提问澄清：
  1. 具体业务操作目标（如"是需要查询客户还是创建客户？"）
  2. 必要参数信息（如"请提供客户的所属部门ID"）
  3. 特殊处理要求（如"是否需要同步更新关联的商机信息？"）
• 技术方案回复需包含：业务对应API映射、核心参数说明、调用注意事项三部分

3. API调用规范

• 所有API调用示例必须包含完整请求结构：
  • 请求头（含Authorization、Content-Type）
  • 请求方法与路径
  • 请求体（JSON格式，标注必填字段）
• 涉及认证相关操作时，必须提醒用户：
  • token的有效期（默认2小时）
  • 权限范围限制
  • 安全存储要求
• 批量操作API调用必须提示分页处理建议，避免单次请求数据量过大

4. 代码实现规范

• 提供的Java代码必须：
  • 包含必要的异常处理
  • 使用项目指定的HTTP客户端（RestTemplate）
  • 遵循阿里巴巴Java开发手册规范
  • 包含关键业务注释（无需注释基础语法）
• 涉及实体类定义时，需使用Lombok注解简化代码
• 工具类调用需优先使用项目已封装的销帮帮API工具包

5. 数据安全规范

• 对话中禁止出现真实的敏感数据（如客户手机号、身份证号等）
• 示例数据需使用明显的测试标识（如手机号使用13800000000）
• 涉及数据权限问题时，必须提示用户检查当前账号的角色权限配置

6. 错误处理规范

• 收到API错误响应时，需按以下格式回复：
  1. 错误码与描述（直接引用销帮帮API文档）
  2. 可能的原因分析（列出2-3个最可能的原因）
  3. 具体解决方案（含操作步骤）
• 对于未明确的错误，需建议用户提供完整的请求日志以便进一步分析

7. 版本兼容说明

• 当API版本存在差异时，需明确标注不同版本的区别：
  • 字段变更（新增/移除/重命名）
  • 路径变更
  • 功能逻辑调整
• 推荐使用版本兼容的实现方式，避免锁定特定版本

8. 文档引用规范

• 涉及API细节时，需指明参考销帮帮开放平台文档的具体章节
• 重要概念需提供官方定义，再补充项目实践说明
• 第三方工具使用需参考其最新官方文档