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.
52 lines
4.8 KiB
52 lines
4.8 KiB
15 hours ago
|
# HANDOFF · 客户模块返工收工（2026-09-05）
|
||
|
|
|
||
|
|
> 本文是 customer-module effort 的**正式收工篇**（对称 [HANDOFF-2026-09-03.md](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](../customer-rework/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|@RequestBody` over crm-customer）零命中。
|
||
|
|
|
||
|
|
## 2. 交付物索引
|
||
|
|
|
||
|
|
| 交付物 | 位置 |
|
||
|
|
|---|---|
|
||
|
|
| API 速查汇总（重写版） | [API-SUMMARY.md](API-SUMMARY.md)——§2.1–2.15 全端点 + §3 值域 + §5 缺口；**73 端点与代码 `@*Mapping` 脚本对账零差异**（票 11 ⑤，脚本 `.scratch/customer-rework/recon_urls.py` + `dump_api.py`） |
|
||
|
|
| spec 图（冻结+增补） | [map.md](map.md)——D1–D30 + 返工增补节 |
|
||
|
|
| 返工图 + 12 票 Answer | `.scratch/customer-rework/`（map.md + issues/01–12） |
|
||
|
|
| 回归重测报告 | `.scratch/customer-rework/RETEST-REPORT.md` |
|
||
|
|
| 规范沉淀 | [AGENTS.md](../../AGENTS.md)「新模块接口接入 checklist」（返工票 01） |
|
||
|
|
| 模块上下文 | [crm-customer/CONTEXT.md](../../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](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 是**全平台唯一 `@RequestBody` JSON 例外**。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_negotiated` NOT 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](../customer-rework/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](API-SUMMARY.md) 为契约基准；联调中发现口径偏差回写该文档并复跑对账脚本。
|