crm-backend-matt/.scratch/customer-rework/issues/12-agreement.md

12 · 战略协议单表 CRUD（F5）

• Status: resolved
• Type: task
• Blocked by: 09-audit-fixes（F5 拍板产出）

Question

原型 a4-4-6（页签）/ a4-4-9（新增）/ a4-4-10（编辑）三页有完整形态但零端点（audit-findings F5，票 09 拍板本期补、单开本票）。战略协议作为客户详情页签的单表 CRUD 全栈如何落？

设计定稿（2026-09-05）

• 表 customer_agreement（BaseEntity 范式，对齐 CustomerContact）：
  • customer_id bigint not null（所属客户，无独立 ACL 权限继承客户）
  • agreement_level tinyint not null（1~3 一级/二级/三级——值域钉在 Customer.strategicAgreementLevel 注释「快照 1~3」）
  • amount varchar(64)（签订金额，对齐 registeredCapital varchar 先例——允许区间/文字形态）
  • remark varchar(500)、file_file_id varchar(64)（附件单文件，crm-file fileId 引用，对齐 CustomerImportTask.fileFileId 先例；下载走 crm-file 通用端点零新下载口）
  • 命名策略：无孤立单大写字母，无需 @Column(name=...) 钉名
• URL（ADR-0017 扁平动作动词，对齐 contact 家族）：POST /api/customer/agreement/create、POST /edit?id=、POST /delete?id=、GET /detail?id=、GET /list?customerId=（页签卡片列表，时间倒序非分页）
• 错误码 CODE_AGREEMENT_INVALID = 67017（入参非法/等级越界/协议不存在或无权——防探测同码）
• oplog（对齐 F10 CONTACT_* 先例）：ACTION_AGREEMENT_ADD/EDIT/DELETE，detail「新增/修改/删除战略协议【三级】」
• 客户快照刷新（兑现 Customer.strategicAgreementLevel javadoc「战略协议子域写入，本图只读」承诺）：create/edit/delete 后重算该客户最新一条协议（create_time,id 倒序 limit 1）的等级回写 customer.strategic_agreement_level（无协议 → NULL=未签）；LambdaUpdateWrapper 只更新该列不 bump version（对齐跟进锚点刷新先例）
• tag A4 客户管理/战略协议（三页均在 客户>我的客户>客户详情 下，单菜单归属）
• 编辑语义：customerId 不可换（dto 值忽略，对齐 contact）；等级必填且 ∈ 1~3

验收

• mvn test crm-customer 全绿（新增 H2 集成测试：CRUD 正常路径 + 校验路径 + 快照刷新 + 权限继承客户 + oplog 三动作）
• 端点 grep 无 @PathVariable/@PutMapping/@DeleteMapping/@RequestBody
• bruno 侧新端点示例随票 10 bruno 对账步统一核补（同 F6/F8 处置）

Answer（2026-09-05）

按设计定稿全栈落地（全部与票面定稿一致，两处实现期修正见下）：

• 后端栈：CustomerAgreement 实体（customer_agreement 表：customerId / agreementLevel 1~3 / amount varchar(64) / remark / fileFileId）+ CustomerAgreementMapper（纯 CrmBaseMapper，无自定义 SQL）+ AgreementDTO 双向 DTO + ICustomerAgreementService / CustomerAgreementServiceImpl + CustomerAgreementController 五端点（POST /api/customer/agreement/create|edit?id=|delete?id=、GET /detail?id=|list?customerId=）；错误码 67017；oplog 扩 AGREEMENT_ADD/EDIT/DELETE。
• 快照刷新兑现：create/edit/delete 后重算最新协议等级回写 customer.strategic_agreement_level（删空回 NULL=未签），LambdaUpdateWrapper 不 bump version——Customer 实体 javadoc「战略协议子域写入，本图只读」的设计承诺自此闭环。
• 实现期修正两处：(1) listByCustomer 首版漏填出参 customerName（契约承诺带出），对齐 contact 的 listByCustomer 补上；(2) 测试对 @TableLogic 语义的断言修正——已删行 selectById 返回 null（非 deleted=true 行），软删位验证改原生 SQL 直读 deleted 列。
• 验证：mvn test -pl crm-customer -am BUILD SUCCESS——crm-customer 158 用例全绿（+6：create 快照 / edit 不可换客 / delete 快照回退与回 NULL / list+detail / 校验三路 / 防探测与权限继承）；规范 grep（@PathVariable|@PutMapping|@DeleteMapping|@RequestBody）零命中；BOM 扫描 NO BOM。
• bruno：menuBindings 无需新增（协议端点无 viewType/scopeKey 参数）；br 文件生成随票 10 对账步（文档仓 D:\code\crm-api-docs\A4 客户管理\）。