12 KiB

Raw Blame History

交接篇：票 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`）： ① customer-module/map.md 返工增补段 —— 未做 ② API-SUMMARY.md 重写 —— 素材齐备，正文未落笔（本篇 §2 是全部素材） ③ `.scratch/customer-module/HANDOFF-2026-09-05.md` 新篇（旧篇不改写）—— 未做 ④ crm-customer/CONTEXT.md 同步 —— 未做 ⑤ 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 收官。

12 KiB Raw Blame History