crm-backend-matt/.scratch/customer-rework/issues/01-ag-checklist.md

01 · AGENTS.md 沉淀「新模块接口接入 checklist」

• Status: resolved
• Type: task
• Blocked by: —

目标

AGENTS.md 新增一节「新模块接口接入 checklist」，把本次返工暴露的规范偏差固化为 agent 必读纪律。

checklist 内容（六条）

1. 开发前先读对称参照模块（线索/商机）的 Controller 形态，不另起风格；
2. URL 风格 = 扁平动作动词 + 查询参数传 id，禁 @PathVariable / @PutMapping / @DeleteMapping，写端点一律 POST form，读端点 GET；
3. 新 Controller 必挂深 tag（完整页面路径，一级 = 原型分区原文如 A4 客户管理，以 .scratch/api-docs-reorg/lanhu-tree-v29.md 权威树为准，跨页共用接口用方法级多值 tags）；
4. bruno-sync.config.json：sourceRoots 加新模块目录 + menuBindings 加菜单（viewType/scopeKey）；
5. 写端点禁 @RequestBody JSON，参数走 ADR-0017 表单绑定；Param/DTO 规范同 ADR-0017；
6. 出票时、收工时各对照本 checklist 跑一遍。

验收

• 节落在 AGENTS.md「Coding standards」区，内链 ADR-0017/0024；
• 一句话带过本次踩坑案例（不单独开 ADR）；
• 本图 08 号票（复核）以本节为规范镜头依据。

同步动作

.scratch/customer-module/map.md 增补一行指针（返工图与本 checklist 的出处）。

Answer

AGENTS.md「Coding standards」区新增 「新模块接口接入 checklist」 一节（位于 JPA 命名策略节之后、Tooling/harness 之前），六条纪律：

1. 动手前先读对称参照模块（线索/商机）的 Controller 形态，不另起风格；
2. URL = 扁平动作动词 + 查询参数传 id，禁 @PathVariable / @PutMapping / @DeleteMapping，写端点 POST、读端点 GET；
3. 新 Controller 必挂深 tag（一级 = 原型分区原文，权威树 lanhu-tree-v29.md，跨页共用走方法级多值 tags）；
4. bruno-sync.config.json 补 sourceRoots + menuBindings；
5. 写端点禁 @RequestBody，表单绑定，Param/DTO 规范依 ADR-0017；
6. 出票时、收工时各对照跑一遍。

内链 ADR-0017 与 ADR-0024；节首一句话记录踩坑案例（crm-customer 整模块 RESTful 偏航——规范存在但实现会话没读），未开新 ADR。

同步动作已完成：.scratch/customer-module/map.md 末尾增补「返工增补指针」段（返工图 + 本 checklist 出处）。

验收自检：

• 节落在 AGENTS.md「Coding standards」区，内链 ADR-0017/0024；
• 踩坑案例一句话带过，未单开 ADR；
• 08 号票（复核）规范镜头原文即以「AGENTS.md 新 checklist」为据，无需改动。