You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
49 lines
2.7 KiB
49 lines
2.7 KiB
3 days ago
|
# 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](docs/adr/0017-controller-io-param-dto-conventions.md) 与 [ADR-0024](docs/adr/0024-bruno-docs-grouping-by-menu.md)；节首一句话记录踩坑案例（crm-customer 整模块 RESTful 偏航——规范存在但实现会话没读），未开新 ADR。
|
||
|
|
|
||
|
|
同步动作已完成：`.scratch/customer-module/map.md` 末尾增补「返工增补指针」段（返工图 + 本 checklist 出处）。
|
||
|
|
|
||
|
|
验收自检：
|
||
|
|
|
||
|
|
- [x] 节落在 AGENTS.md「Coding standards」区，内链 ADR-0017/0024；
|
||
|
|
- [x] 踩坑案例一句话带过，未单开 ADR；
|
||
|
|
- [x] 08 号票（复核）规范镜头原文即以「AGENTS.md 新 checklist」为据，无需改动。
|