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.
82 lines
12 KiB
82 lines
12 KiB
2 days ago
|
# 交接篇：票 11 API-SUMMARY 重写进行中（SESSION 2，2026-09-05）
|
||
|
|
|
||
|
|
> 换机交接。上篇 `.scratch/customer-rework/HANDOFF-2026-09-05.md` 交接到本会话已完成票 09/12/10；
|
||
|
|
> 本篇从**票 11 第 2 项（API-SUMMARY.md 整篇重写，素材已采齐、正文未落笔）**处交接。
|
||
|
|
|
||
|
|
## 0. 会话框架（先读）
|
||
|
|
|
||
|
|
- **模式**：wayfinder「Work through the map」，地图 `.scratch/customer-rework/map.md`。
|
||
|
|
- **用户既定指令**：「继续做，把整张 map 做完」。票据在 `.scratch/customer-rework/issues/`。
|
||
|
|
- **纪律**：每票收尾=票内追加 `## Answer` + `Status: resolved` → rework map.md「Decisions so far」追加一行索引。
|
||
|
|
- **Do not**：票据/ADR/map 已记录的内容不重述，按路径引用（下同）。
|
||
|
|
|
||
|
|
## 1. 当前进度
|
||
|
|
|
||
|
|
| 票 | 状态 |
|
||
|
|
|---|---|
|
||
|
|
| 09（F6/F7/F8/F10）、12（战略协议） | resolved（Answer 见各票文件） |
|
||
|
|
| 10 回归重测 | **resolved**——五项验收全过，报告 `.scratch/customer-rework/RETEST-REPORT.md`；冒烟 `tmp/smoke-t10.py` 43 步全绿；服务已停、环境已还原 |
|
||
|
|
| **11 文档同步** | **进行中**（五项清单见 `issues/11-docs-sync.md`）：<br>① customer-module/map.md 返工增补段 —— 未做<br>② **API-SUMMARY.md 重写 —— 素材齐备，正文未落笔（本篇 §2 是全部素材）**<br>③ `.scratch/customer-module/HANDOFF-2026-09-05.md` 新篇（旧篇不改写）—— 未做<br>④ crm-customer/CONTEXT.md 同步 —— 未做<br>⑤ URL 对账脚本零差异 + 票 11 Answer/resolved + rework map 加 11 行 + map Status 收官 —— 未做 |
|
||
|
|
|
||
|
|
## 2. API-SUMMARY 重写素材包（核心交接，事实均已在源码/冒烟实证）
|
||
|
|
|
||
|
|
### 2.1 权威端点清单
|
||
|
|
|
||
|
|
脚本产物 `tmp/dump_api_out.txt`（crm-customer + crm-rule + crm-preference 全部 controller：类级前缀 + 动词 + 路径 + 参数行），`tmp/dump_params_out.txt` 为路径-only 版。要点：
|
||
|
|
|
||
|
|
**crm-customer**（写=POST 表单、读=GET 查询参数；全部无 @PathVariable/PUT/DELETE）：
|
||
|
|
|
||
|
|
- `CustomerWorkspaceController /api/customer/workspace`：POST `/page`、POST `/board/summary`、POST `/board/cards`——表单绑定 `CustomerWorkspacePageParam`
|
||
|
|
- `CustomerController /api/customer`：POST `/create`(CustomerCreateDTO)、POST `/edit`(**id + CustomerUpdateDTO**)、GET `/detail?id=`、POST `/page`(CustomerPageParam)、POST `/search`(CustomerSearchParam)、POST `/quick-create`(CustomerQuickCreateDTO)、GET `/contacts?customerId=`、GET `/check-name?name=&excludeId=`、GET `/check-credit-code?creditCode=`、GET `/company-lookup?companyName=`、POST `/company-lookup/batch-update?ids=`(F6)
|
||
|
|
- `CustomerDetailController /api/customer`：GET `/detail-head?id=`、GET `/member/list?id=`、POST `/member/add`(**id + MemberAddDTO{memberUserIds[]}**)、POST `/member/remove?id=&memberUserId=`、GET `/opportunity/page?id=`、GET `/oplog/page?id=`(+OplogPageParam)、POST `/follow/add`(id + FollowCreateDTO)、GET `/follow/page?id=`
|
||
|
|
- `CustomerContactController /api/customer/contact`：POST `/create`(ContactDTO)、POST `/edit`(**id + ContactDTO**)、POST `/delete?id=`、GET `/detail?id=`、GET `/page`(ContactPageParam=BaseParam，keyword 匹配姓名/电话/所属客户名)、GET `/search?keyword=&limit=`(**limit 默认 20**)、GET `/check-phone?phone=&excludeId=`(D26 软提示，受查重设置电话开关控制)
|
||
|
|
- `CustomerFocusController /api/customer`：POST `/focus|/unfocus|/star|/unstar?id=`、POST `/focus-batch?ids=`
|
||
|
|
- `CustomerOwnershipController /api/customer`：POST `/claim|/claim-batch`、`/assign`(**id+userId**)|`/assign-batch`(**ids+userId**)、`/release-pool|/release-pool-batch`、`/archive|/archive-batch`、`/restore?id=`（单数 id、批量 ids）
|
||
|
|
- `CustomerTransferController /api/customer/transfer`：GET `/preview`、POST `/initiate`(TransferInitiateDTO：reason 必填 resign/transfer_post/region_adjust + toDirectorId 选填 + remark)、GET `/detail?id=`、GET `/page`(TransferPageParam)、POST `/assign`(**id + customerIds + assignUserId**，BatchResult 行级部分成功)、GET `/assignable?id=`（**D-07 P1 超时已知缺陷**）
|
||
|
|
- `CustomerImportController /api/customer/import`：POST `/upload`(**MultipartFile file + importMode + duplicateStrategy 可选**)、GET `/template`、POST `/confirm?taskId=`、GET `/result?taskId=`、GET `/failures?taskId=`、GET `/page`(ImportPageParam：status/importMode)
|
||
|
|
- `CustomerAgreementController /api/customer/agreement`（票 12 五端点）：POST `/create`(AgreementDTO)、POST `/edit`(**id + AgreementDTO**，归属不可换客户)、POST `/delete?id=`、GET `/detail?id=`、GET `/list?customerId=`
|
||
|
|
- `CustomerPingController`：GET `/api/customer/ping`
|
||
|
|
|
||
|
|
**crm-rule 客户规则族**：GET `/api/rule/customer/reminder` + POST `/api/rule/customer/reminder/save`(CustomerReminderRuleDTO 表单：masterEnabled/firstTriggerEnabled/firstTriggerDays/secondIntervalEnabled/secondIntervalDays)；GET `/api/rule/customer/dedup` + POST `/api/rule/customer/dedup/save`(CustomerDedupRuleDTO 表单：masterEnabled/nameEnabled/nameMatchMode(1精确2模糊)/similarityThreshold/phoneEnabled)。（crm-rule 其余族=线索池/商机池规则/方案卡模板/阶段模板/地区——**不在客户域文档范围**，勿抄进客户 API-SUMMARY）
|
||
|
|
|
||
|
|
**crm-preference 平台偏好**（不在 ADR-0017 改造范围，**saved-view save 例外用 @RequestBody JSON**）：GET `/api/preference/get?scopeKey=` + POST `/api/preference/save`(scopeKey + visibleKeys + columnOrder 可空 List)；GET `/api/preference/view/list?scopeKey=` + POST `/api/preference/view/save`(scopeKey + JSON SavedView) + POST `/api/preference/view/delete?scopeKey=&viewId=` + POST `/api/preference/view/set-default?scopeKey=&viewId=`；GET `/api/preference/view-form/get?scopeKey=` + POST `/api/preference/view-form/save`(scopeKey + viewForm)（返工票 05）
|
||
|
|
|
||
|
|
### 2.2 关键值域/事实（源码锚点）
|
||
|
|
|
||
|
|
- **错误码 67001-67017** 全表见 `crm-customer/.../constant/CustomerConstants.java` L13-29（67017=CODE_AGREEMENT_INVALID 票 12 新增）。
|
||
|
|
- **oplog action 值域 17 种**（同文件 L85-101）：CREATE/UPDATE/FOLLOW/ARCHIVE/RESTORE/TRANSFER/CLAIM/POOL/STAGE_CHANGE/MEMBER_ADD/MEMBER_REMOVE + CONTACT_ADD/CONTACT_EDIT/CONTACT_DELETE(F10) + AGREEMENT_ADD/AGREEMENT_EDIT/AGREEMENT_DELETE(票 12)。⚠ `OplogPageParam` 的 @Schema 描述仍写 11 种（滞后，未改——票 11 不动代码，文档按 17 种真值写）。
|
||
|
|
- **F7 终态**（票 09 Answer 澄清）：ownerOnly 等布尔字段**未做**，viewType 单参数承载五内置视图 `CustomerWorkspaceViewType`：ASSIGNED/COLLABORATING/FOLLOW_UP_DUE/FOCUSED/RECENT；workspace 适配 mine 全五、overview 无 FOLLOW_UP_DUE、pool 仅 RECENT/FOCUSED；越界视图 SQL 自然空集不硬拒；savedViewId 叠加自定义视图（RECENT 不接）。customer_view_log 生产侧零写入 → detailHead upsert touchViewLog 收口（票 04 建壳挂账）。
|
||
|
|
- **F8 duplicateStrategy**（票 09 Answer）：upload 可选参数，SKIP 缺省/OVERWRITE，非法值 67013 拦；D24 冻结语义=作用面仅文件内重复组、overwrite=组内最后一条通过校验的行 UPDATE 生效、不触名称相似 SUSPECT；响应回显 duplicateStrategy。
|
||
|
|
- **F6 batch-update**：`POST /api/customer/company-lookup/batch-update?ids=`（ids 表单绑定、上限 100、§C2 只补空缺、五种状态软处置、port stub 恒 NO_HIT、真实企查查接入自动激活）。
|
||
|
|
- **groupColumn 白名单**（CustomerWorkspaceServiceImpl L185-191）：`stage`→customer_stage / `star`→customer_star_level / 其他→relation_star_level；board/cards 必传 groupValue 否则 67001；**pool 看板 67001 拒绝**（「公海无卡片视图」，票 03）。
|
||
|
|
- **scopeKey 清单**（CustomerConstants L53-81）：saved-view/列/形态共用 `customer.overview` / `customer.mine` / `customer.pool`；列/形态另有 `contact.list`；view-form 公海仅 list/split（board 被拒）；商机侧 `opportunity.mine`（冒烟实测）等。
|
||
|
|
- **company-lookup 参数 = `companyName`**（旧 API-SUMMARY 写 `keyword=` 是错的，以代码为准）。
|
||
|
|
- **AgreementDTO 字段**：customerId(新增必填，编辑以库内归属为准)/agreementLevel(1~3 必填)/amount(文本可空)/remark/fileFileId + customerName(仅出参)；删协议联动清主表 strategic_agreement_level 快照。
|
||
|
|
- **67017 语义**：等级缺失或越界/协议不存在或无权访问。
|
||
|
|
- **旧文档 §0/§1/§5 骨架保留**：通用约定（Bearer/Result/PageResult/雪花串化/fail-open/脱敏现状/时间格式）+ 错误码表扩到 67017 + §5 销账（1 confirmSimilar、2 查重设置端点保持删除线；3 改为「页签 5 关联项目仍 --、页签 6 战略协议已上线→§2.x」；4/5 保持划出项；**新增 D-07 assignable 超时已知缺陷条目**）。
|
||
|
|
- **计划段落结构**（重写时沿用旧骨架编号顺延）：§2.1 三 workspace（含 F7 表格式 Param 说明）→ 2.2 公海与归属动作 → 2.3 新增/编辑/查重/工商(含 F6) → 2.4 商机快建+商机侧依赖 → 2.5 详情公共头部+8 页签（页签 6 引战略协议节）→ 2.6 战略协议五端点 → 2.7 联系人独立菜单 → 2.8 团队成员 → 2.9 关注/重点 → 2.10 归档/恢复 → 2.11 交割 → 2.12 导入(含 F8) → 2.13 规则设置 → 2.14 偏好三件套+scopeKey+JSON 例外 → 2.15 ping；§3 值域附录、§4 联调速查（冒烟范式改 `tmp/smoke-t10.py`）、§5 缺口。目标 <1000 行，旧文档 `.scratch/customer-module/API-SUMMARY.md`（194 行）供对照。
|
||
|
|
|
||
|
|
### 2.3 票 11 后续步骤细节
|
||
|
|
|
||
|
|
- **① map 增补段**：`.scratch/customer-module/map.md` 末尾（L140-142 已有「返工增补指针」一行段）扩为完整段：R1-R11 决策指针（→ rework map）+ 每张返工票（01-10、12）一行增量决策。素材=rework map「Decisions so far」11 行索引 + 各票 Answer。
|
||
|
|
- **③ HANDOFF 新篇**：`.scratch/customer-module/HANDOFF-2026-09-05.md`（正式收工篇，区别于 customer-rework 下的交接篇）；链接 RETEST-REPORT；旧 HANDOFF 不改写。
|
||
|
|
- **④ CONTEXT.md**：`crm-customer/CONTEXT.md` 若有接口清单段，同步新 URL 契约 + 偏好能力（列/形态/saved-view）+ 战略协议。
|
||
|
|
- **⑤ URL 对账**：写脚本从新 API-SUMMARY.md 提取全部 URL 与 `@*Mapping` 对账（可复用 `tmp/dump_api.py` 输出做基准）；零差异后票 11 Answer/resolved + rework map 加 11 索引行 + 检查 map「Not yet specified」清空 → **整图收官**。
|
||
|
|
|
||
|
|
## 3. 工具坑（本机实证，勿重蹈）
|
||
|
|
|
||
|
|
- **PowerShell**：`-Command` 双引号串里 `$_`/`$env:` 被吞 → 一律写 .ps1 文件用 `-File`；语句分隔用 `;` 不用 `&&`。
|
||
|
|
- **写文件范围**：Write/SearchReplace 只限 workspace（`d:\code\crm-backend-matt`）内；docs 仓 `D:\code\crm-api-docs` 等外部路径 → 先写 workspace 内 staging 再 python 复制（先例 `.scratch/customer-rework/deploy_bru.py`）。
|
||
|
|
- **py**：统一 `py -3 -X utf8`；`-c` 内嵌脚本引号易炸 → 落 .py 文件再跑。
|
||
|
|
- **服务起停**（如需复跑冒烟）：先例 `.scratch/customer-e2e/map.md` L29（verify profile；MINIO 凭据见该处，不在本文档重复）；重打包 `tmp/pack-crmapp.ps1`（fat jar 会落后源码，核对时间戳）；`tmp/run-crmapp.ps1` / `tmp/stop-crmapp.ps1`。**当前服务已停**。
|
||
|
|
- **冒烟实测参数**（写文档校对用）：`tmp/smoke-t10.py`——edit 必带 `version`+`isBizNegotiated`+`isChild`；contact/create 必填 `name/jobTitleName/phone`；preference save 用 visibleKeys/columnOrder 逗号串。
|
||
|
|
|
||
|
|
## 4. Suggested skills
|
||
|
|
|
||
|
|
- `wayfinder`：Work through the map 模式续作，地图 `.scratch/customer-rework/`，从票 11 接续。
|
||
|
|
- `bruno-sync`：仅当对账再需要时（当前 321=321 已闭环，无需重跑）。
|
||
|
|
|
||
|
|
## 5. 验收线（票 11）
|
||
|
|
|
||
|
|
文档-代码对账零差异；旧 HANDOFF 不改写（历史只增）；五项清单全勾 + Answer/resolved + rework map 11 行 → 整张 map 收官。
|