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.
4.8 KiB
4.8 KiB
HANDOFF · 客户模块返工收工（2026-09-05）
本文是 customer-module effort 的正式收工篇（对称 HANDOFF-2026-09-03.md，旧篇不改写）。 返工过程性的交接见
.scratch/customer-rework/HANDOFF-2026-09-05.md与HANDOFF-2026-09-05-API-SUMMARY-WIP.md（会话 1/2/3 的推进记录）。
1. 收工摘要
- 返工图
.scratch/customer-rework/map.md：12 张票（01–10、12）全部 resolved，R1–R11 决策闭环，整图收官。 - spec 图（本目录 map.md）：D1–D29 冻结不变 + [D30 形态偏好增补]；末尾新增「返工增补（2026-09-05 收官版）」节 = R1–R11 指针 + 每票一行增量决策。
- 测试结果（详见 RETEST-REPORT.md）：三模块
mvn test全绿（crm-rule 152 / crm-customer 158 / crm-opportunity 242）；冒烟 43 步 0 fail（新端点全覆盖 + DB 快照断言）；bruno 对账 321=321 终态；BOM 扫描零命中；风格 grep（@PathVariable|@PutMapping|@DeleteMapping|@RequestBodyover crm-customer）零命中。
2. 交付物索引
| 交付物 | 位置 |
|---|---|
| API 速查汇总（重写版） | API-SUMMARY.md——§2.1–2.15 全端点 + §3 值域 + §5 缺口；73 端点与代码 @*Mapping 脚本对账零差异（票 11 ⑤，脚本 .scratch/customer-rework/recon_urls.py + dump_api.py） |
| spec 图（冻结+增补） | map.md——D1–D30 + 返工增补节 |
| 返工图 + 12 票 Answer | .scratch/customer-rework/（map.md + issues/01–12） |
| 回归重测报告 | .scratch/customer-rework/RETEST-REPORT.md |
| 规范沉淀 | AGENTS.md「新模块接口接入 checklist」（返工票 01） |
| 模块上下文 | crm-customer/CONTEXT.md（本篇同步：规则族两族/战略协议/偏好接线） |
| bruno 文档仓 | E:\code\crm-api-docs（A4 树与 v29 七节点+战略协议对齐，票 07/12 终态） |
3. 接口契约速览（前端对接注意）
- URL 形态：扁平动作动词 + 查询参数传 id（
POST /edit?id=、GET /detail?id=）；写端点全 POST 表单绑定，读端点 GET；零@PathVariable/PUT/DELETE。全量清单以 API-SUMMARY.md 为准。 - 编辑必带：
POST /api/customer/edit须提交version（CAS）+isBizNegotiated+isChild（冒烟实测，缺省因 DB NOT NULL 无默认而失败，关联 D-05）。 - 联系人必填：contact create/edit 必填
name/jobTitleName/phone。 - 偏好三件套：列偏好
POST /api/preference/save（visibleKeys/columnOrder 逗号分隔表单串）；形态偏好 view-form get/save；saved-view save 是全平台唯一@RequestBodyJSON 例外。scopeKey 清单见 API-SUMMARY §2.14。 - 查重确认口径：命中相似 →
needConfirm=true + similarHits（未落库），确认后带confirmSimilar=true重发（create / quick-create 通用）。 - 导入重复策略：upload 可选
duplicateStrategy（SKIP 缺省 / OVERWRITE），响应回显。 - 雪花 ID：JSON 全部串化，前端勿做 Number 运算。
4. 已知缺陷与遗留（均不阻塞收工）
- D-07（P1）：
GET /api/customer/transfer/assignable稳定超时（根部门全树递归 + 逐用户 getDeptNames N+1）——修复排期独立 effort。 - D-04（P2）/ D-05（P1）：导入失败明细
fail_reason超长写不进 /is_biz_negotiatedNOT NULL 无默认——已知缺陷记档（返工票 09 audit），维持原状。 - 范围外维持划出：客户导出、联系人导入、客户查重/合并、OCR 快捷新增、敏感信息三档脱敏——见
.scratch/customer-rework/map.md「范围外」节。 - 代码侧
OplogPageParam@Schema 描述仍写 11 种 action（真值 17 种，滞后未改——票 11 不动代码，文档按真值记录于 API-SUMMARY §3）。
5. 环境 / 复跑备忘（换机后）
- 服务起停：verify profile 起动范式与 MINIO 凭据见
.scratch/customer-e2e/map.md环境事实段（本篇不重复敏感值）。 - 重打包：fat jar 会落后源码（Maven 增量构建静默跳过 jar 重建）——重打包后核对 jar 时间戳再起服务。
- 冒烟脚本：
tmp/smoke-t10.py本体未随仓（换机）；覆盖清单与修正记录（edit 必带字段等）见 RETEST-REPORT.md §2。 - 对账脚本：
.scratch/customer-rework/dump_api.py（端点 dump）+recon_urls.py（文档-代码对账），py -3 -X utf8运行。
6. 下一步建议
- D-07 assignable 超时修复（独立 effort，先做 N+1 消除）。
- 前端联调以 API-SUMMARY.md 为契约基准；联调中发现口径偏差回写该文档并复跑对账脚本。