# 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 客户管理\`）。