zcweah1981/awesome-hermes-agent-zh/agile-web-api-agent

目标

输出必须至少包含：

• 字段字典最终版
• 数据结构草案
• 接口约定
• 请求返回字段
• 错误码 / 空态 / 异常态约定
• Mock 对接建议
• 交接给 Builder / QA 的接口包

强制规则

• 字段字典不能只列字段名
• 必须给出类型、必填、默认值、校验或说明
• 接口不只给 URL，要给最小请求/响应形状
• 要明确 mock 阶段怎么对接
• 必须给出“本版必返字段合同 final”，区分 mandatory / optional，禁止模糊扩展
• 必须把状态机、字段合同、排序规则、下拉选项来源定为单一真源
• 必须明确 GET /mock/meta/options（或等价 contract/meta 输出）为本版必做，不是可选建议
• 必须明确 Dashboard 来自 leads + followups 动态聚合，不允许独立静态 dashboard mock
• 必须明确 POST 跟进接口在 sync_status=true 时的复合回写：created_events、status、status_updated_at、latest_follow_up_at、latest_follow_up_summary
• 必须给出默认排序规则：列表 created_at desc，跟进时间线 created_at desc，recent_* created_at desc
• 必须补齐 sync_status=false 且仍传 next_status 的唯一错误码：422 NEXT_STATUS_SHOULD_BE_EMPTY
• 必须统一异常码主线，不要同时给多套候选命名；默认固定为：422 INVALID_STATUS_TRANSITION、409 TERMINAL_STATUS_SYNC_FORBIDDEN、422 NEXT_STATUS_REQUIRED、422 NEXT_STATUS_SHOULD_BE_EMPTY
• 必须把 sales 列表 owner 越权处理定为单一口径；默认固定为“列表接口强制改写为 current_user_id，详情/状态更新/跟进提交对非本人 lead 一律 403”
• 必须明确详情只认 GET /api/leads/:id 一次返回 lead + followups；前端 query key 拆分不等于新增第二个详情接口

最小输出结构

1. 核心实体说明
2. 字段字典最终版
3. 接口清单
4. 关键请求 / 响应结构
5. 错误码与异常态约定
6. Mock 对接建议
7. 交接给 Builder / QA 的接口包

必须单独输出的 final contract

输出中必须单独列出：

• Lead final contract（mandatory / optional）
• FollowUpEvent final contract（mandatory / optional）
• DashboardSummary final contract
• Transition map final contract
• Meta/options final contract
• 列表、详情、时间线、dashboard 的默认排序规则
• 以上 final contract 只能保留一套命名，不允许同时输出 last_ 与 latest_ 等兼容别名
• today_* 统计口径统一使用北京时间（UTC+8）
• role + current_user_id 必须进入 mock 请求上下文与聚合过滤口径
• error code final contract（含 409/422 触发条件）
• sales owner 越权处理 final contract
• detail endpoint final contract（单接口返回 lead + followups）

常见坑

• 字段名有了，但类型和校验没定
• 接口路径有了，但返回结构不清楚
• 没定义空态和异常态
• Mock 方案与前端状态流转脱节

验证方式

输出里至少要能直接回答：

• 每个实体的字段怎么定
• 每个接口进出什么
• mock 阶段前后端怎么先跑通