Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/contract-create-mcp-design.md
T
my_local_kimi_dev2 2aa99abddd feat(mcp): 新增合同批量补录上传与创建工具 (REQ-20261118-0011)
- contract.file.upload:单文件 Base64 上传(20 MiB 上限),OSS+DB 补偿,clientUploadId 持久化幂等
- contract.create:单事务创建合同/绑定附件/写创建记录/提交审批,clientRequestId 持久化幂等
- 补齐 ContractNew.contractType/renewed、ContractFile OSS 与幂等字段、审批流实体与 Mapper
- 新增 JacksonLargePayloadConfig,放宽 20 MiB Base64 的 Jackson 字符串上限至 32 MiB
- 附 m2 DDL 脚本(dev 已执行、prod 待执行)、设计稿、PRD/讨论记录与工具参考文档
2026-11-19 09:31:19 +08:00

487 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 合同附件上传与创建工具 — MCP 设计文档(决策已拍板)
- 工具:`contract.file.upload`、`contract.create`(均为 kind=write,category=admin)
- 对标老接口:`POST /contract/uploadFile`、`POST /contract/add`
- 调研日期:2026-11-18
- 当前状态:**已实现并通过全量测试与本机 dev 真实 MCP 冒烟;尚未提交、部署或执行生产 DDL**
- 目标场景:批量补录合同;每份合同必须在基本信息完整、全部附件上传成功后,才形成一份完整合同并提交审批
> 本设计基于当前工作区行号级实查。老系统 `ContractController.java`、`ContractDealService.java` 等合同模块文件在当前 Git 工作区中仍是新增未提交文件;本文描述的是这份代码的行为,不据此断言老系统生产环境已经部署该版本。
## 1. 拍板结论与范围
1. 新增 `contract.file.upload`,MCP 直接接收文件内容并上传 OSS,不再要求调用方先从老页面上传。
2. 创建时不增加物业行级数据权限;只保留用户 Token、工具 scope、物业及关联数据有效性校验。
3. `contract.create` 完成“创建并提交”即返回,不等待审批通过,不代做审核、续签或其他后续动作。
4. 物业销售或销售所属公司缺失时拒绝创建,避免空公司绕过审批。
5. `expireRemind` 默认 **1(开启)**,`remindDays` 默认 30。
6. 数据库已提交但审批通知失败时,仍返回创建成功并附 warning,不诱导重复创建。
7. 实现范围补齐主工程缺失的 `contractType`、`renewed`、附件 OSS 字段,并正式处理合同名称可空的 schema 冲突。
8. 为批量调用的超时重试补上**持久化幂等**,取代上一版“只有短时并发锁、超时后人工查重”的方案。
本期不包含:附件 OCR/日期识别、合同草稿、审批办理、修改再提交、续签、终止、删除、工作流配置、异步批任务和定时任务迁移。
## 2. 批量使用总体设计
### 2.1 两个原子工具,不引入半成品合同
系统没有独立合同草稿状态。`contract.create` 不允许只插 `contract_new` 而不绑定附件或不走审批,也不允许 `fileIds` 为空。
批量导入由调用方按“一份合同一个闭环”编排:
```text
准备该合同基本信息和稳定的 clientRequestId
│
├─ 为每个文件生成稳定的 clientUploadId
│ ↓
│ contract.file.upload(逐文件,可重试)
│ ↓
│ 收齐该合同全部 fileId
│
├─ 任一文件上传失败:本合同不调用 create,记录失败;其他合同可继续
│
└─ 全部文件上传成功
↓
contract.create(基本信息 + fileIds + clientRequestId)
↓
单事务创建合同、绑定全部附件、提交审批
↓
返回合同 id / 编号 / 状态;通知异常只附 warning
```
**完整性保证:**上传工具只产生可复用的未绑定附件,不产生合同;只有创建工具才产生合同,而创建事务要么“合同 + 全部附件绑定 + 创建/审批流程”一起成功,要么整体回滚。因此不会出现“有合同但没有附件”或“只绑了部分附件”的正式合同。
### 2.2 批量不是整批一个事务
首版不另设 `contract.batch.create`,由客户端/Agent 循环调用两个原子工具:
- 每份合同独立提交,某一份数据或文件失败不阻塞其他合同。
- 单份失败只重试该份,不需要回滚或重传整批。
- 避免一个大批量请求长期占用数据库事务、超过 MCP 超时后整批结果不明。
- 调用方保存每份合同及每个文件的稳定幂等键;建议最多 3 份合同并行,单份合同内文件串行,防止 OSS/DB 瞬时压力过高。
批量结果按 `clientRequestId` 对账:成功项记录合同 id/编号,失败项记录阶段(UPLOAD/CREATE)、错误码和可重试性。创建成功后不强制再调用详情查询。
### 2.3 超时重试规则
- 上传超时:用**相同 `clientUploadId`、相同文件名和文件内容**重试 `contract.file.upload`。
- 创建超时:用**相同 `clientRequestId` 和相同规范化参数**重试 `contract.create`。
- 不得因为超时就换幂等键;换键会被视为新的业务意图,可能生成重复附件或合同。
- 同一幂等键对应不同内容/参数时返回 `IDEMPOTENCY_CONFLICT`,不覆盖第一次结果。
- 幂等回放只返回已存在资源,不再次绑附件、写流程或发送审批消息。
## 3. 老系统流程实查
### 3.1 附件先于合同存在
- `ContractController.java:616-660`:`POST /contract/uploadFile` 支持 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv,上传 OSS 后插入 `contract_file`,初始 `contract_id=0`,返回 `fileId/url`。
- OSS 对象位于 `xiaoqu-safefile` 的 `contract/` 目录;数据库同时保存 `oss_bucket/oss_folder/file_url`。
- 老接口仅按扩展名校验,未限制文件大小;对象名使用毫秒时间戳。MCP 不复制这两个宽松/并发风险点。
- `ContractController.java:662-704`:`parseContractDate` 是独立辅助接口,新增接口不会自动调用;本期也不自动识别日期。
- `ContractAddInput.java:20-54`:新增提交只接收附件 `fileIds`,不接收文件二进制或 URL。
### 3.2 Controller 入参校验和快照
`ContractController.java:286-310` 是新增入口,登录后调用 `buildContract`,再进入 `ContractDealService.add`。
`ContractController.java:755-812` 的实际行为:
| 项目 | 当前代码行为 |
|---|---|
| 合同类型 | `contractType` 必填,但只判非 null,没有限制在 0/1/2 |
| 合同名称、金额 | 二期已放开为非必填 |
| 客户所属公司 | `customerAgentId` 必填;此处不校验公司是否存在或渠道类型 |
| 所属物业 | `propertyId` 必填;按 id 查 m0 `properyt`,不存在或软删则拒绝 |
| 物业编号 | `properyt.serialnumber` 空白或字符串 `null` 时拒绝,因为它用于合同编号 |
| 合同日期 | `startDate/endDate` 必填,`endDate >= startDate`;不限制是否早于当天 |
| 到期提醒 | 老后端缺省 `expireRemind=0`;本工具按拍板改为默认 1 |
| 提醒天数 | 缺省或非正数时取 30;MCP 缺省 30,显式传入必须为正整数 |
| 提醒时间 | 开关开启时,取 `endDate-remindDays` 当天 09:30:00 |
| 客户快照 | `propertyName=properyt.name`、`customerNo=properyt.serialnumber`、`customerName=properyt.jinideName` |
| 销售快照 | `saleId/saleName=properyt.createId/createName` |
| 合同所属公司 | 再按 `properyt.createId` 查 m0 `user`,取该销售的 `agentId`;老代码查不到销售时留空 |
注意:`customerAgentId`(表单选择的客户所属公司)与 `contractAgentId`(物业销售所属公司、用于审批流)是两个不同字段,不能互相覆盖,也不能默认二者相等。
### 3.3 m2 事务内的写入顺序
`ContractDealService.java:200-224` 使用 `txManager2` 编程式事务:
1. `checkFilesBindable`:附件必须存在、未软删且 `contract_id=0`(`:742-758`)。
2. 写合同创建/修改审计字段。
3. `saveWithContractNo` 保存合同(`:590-605`)。
4. `bindFiles`:逐条把未绑定附件关联到新合同(`:764-777`);老代码没有检查每条更新的影响行数。
5. `submitFlow`:写创建记录并决定审批状态(`:612-675`)。
### 3.4 合同编号
`ContractDealService.java:587-605`:
- 格式:`properyt.serialnumber + "C" + %03d`;流水 = 同一 `customer_no` 下合同数 + 1。
- 计数包含软删合同,避免编号复用。
- `contract_no` 有唯一索引;捕获 `DuplicateKeyException` 后最多尝试 3 次。
- 老实现把计数和重试放在同一个事务里;MCP 改为每次尝试使用独立完整事务。
### 3.5 审批流判断
工作流按 `contractAgentId` 查 m2 `contract_flow_set`,再查 `contract_flow_user`(`ContractDealService.java:824-850`)。
| 场景 | 当前代码结果 |
|---|---|
| 无工作流配置 | `contract_status=2 正常`,只有创建记录,不生成待办/抄送,不发审批消息 |
| 有关闭部门内审批的配置,且有层级审核人 | 待审;待办人为 1 级审核人,`node_type=2,audit_level=1` |
| 有配置但无层级审核人 | 正常 |
| 部门内审批开启,提交人是部门负责人 | 跳过部门负责人节点;有层级则进入 1 级审核,无层级则正常 |
| 部门内审批开启,提交人不是负责人,且能查到本部门负责人 | 待审;全部部门负责人为待办人,`node_type=1,audit_level=0` |
| 部门内审批开启,提交人不是负责人,但查不到负责人 | 跳过部门节点;有层级则进入 1 级审核,无层级则正常 |
部门负责人岗位来自 Redis db5 `Dictionary.authDeptPostId`。老代码在字典缺失时按“无负责人”继续,可能使合同直接正常;MCP 改为 fail fast。
待审时(`:680-707`):
- 创建记录:`node_type=0, operation_type=0, schedule_state=0`,创建人为提交人。
- 当前待办:`operation_type=0,schedule_state=1`,每个待办人一行。
- 抄送:`node_type=4,operation_type=5,schedule_state=0`,每个抄送人一行。
- 消息按 userId 去重:待办 type=12、抄送 type=13,写 Redis list `InvoiceMessageNotice`。
- 只有进入待审分支才生成抄送记录和消息;直接正常时即使配置了抄送人也不发送。
### 3.6 提交后副作用与后续任务
- `ContractDealService.java:925-947` 使用 `afterCommit` 推送 Redis,避免数据库回滚后仍发消息。
- `ContractTask.java` 的过期扫描、到期提醒和合同上传提醒由老系统定时任务异步执行,不是本次 MCP 调用内的同步写入。
- 创建本身不联动资产、库存、商城订单或金蝶。
- 当前老系统源码未找到实际清理 `contract_file` 未绑定附件的任务;表注释中的“定时清理”不能当成已有保障。
## 4. 数据模型与 schema 前置变更
### 4.1 涉及资源
| 库/服务 | 表/资源 | 访问 | 用途 |
|---|---|---|---|
| m0 | `properyt` | 读 | 物业有效性、客户与销售快照、编号前缀;不做行级权限过滤 |
| m0 | `user` | 读 | 当前提交人、销售所属公司、部门负责人 |
| m0 | `agent` | 读 | 客户所属公司有效性 |
| m2 | `contract_new` | 读/写 | 编号计数、创建幂等、合同主记录 |
| m2 | `contract_file` | 读/写 | 上传幂等、附件记录、创建时绑定 |
| m2 | `contract_process` | 写 | 创建、待办、抄送记录 |
| m2 | `contract_flow_set` / `contract_flow_user` | 读 | 审批流配置和人员 |
| svc | `audit_log` | 自动写 | 现有 `GuardedToolCallback` 工具审计 |
| Redis | `Dictionary`、`InvoiceMessageNotice` | 读/写 | 部门岗位字典;提交后的审批/抄送消息 |
| OSS | 配置化 bucket,默认兼容 `xiaoqu-safefile/contract/` | 写/删 | 文件存储;仅在本次上传后的 DB 失败补偿中删除新对象 |
m0 只读;m2 的合同、附件绑定和流程记录放在一个本地事务中,不做跨库分布式事务。OSS 上传与附件 DB 插入不是同一事务,按第 6 节补偿。
### 4.2 必须补齐的既有映射
- 主工程 `entity/m2/ContractNew.java` 缺少二期字段 `contractType`、`renewed`,实现时补齐;`renewSourceId` 已存在。
- 主工程 `entity/m2/ContractFile.java` 缺少 `ossBucket`、`ossFolder`,实现时补齐。
- 主工程需新增 `ContractFlowSet`、`ContractFlowUser` 实体和 Mapper。
### 4.3 合同名称可空
仓库 DDL `contract-management-ddl.sql:24` 仍写 `contract_name VARCHAR(128) NOT NULL`,而二期设计与当前 Controller 均允许名称为空。
实现前只读核对 dev/prod 实际表结构。若仍为 NOT NULL,先执行正式变更:
```sql
ALTER TABLE contract_new MODIFY contract_name VARCHAR(128) NULL;
```
不得用空字符串冒充 null 绕过。该 DDL 属于 m2 老系统业务库,不混入 MCP 的 svc Flyway migration。
### 4.4 为批量重试增加持久化幂等字段
只用 Redis 锁无法解决“DB/OSS 已成功但响应丢失”。为两个现有表增加可空字段;老系统插入时保持 null,不影响既有逻辑,MySQL 唯一索引允许多个 null 历史行。
| 表 | 新字段 | 约束/用途 |
|---|---|---|
| `contract_new` | `client_request_id VARCHAR(64) NULL`、`request_hash CHAR(64) NULL` | `UNIQUE(create_id, client_request_id)`;防止同一用户重复创建,识别同键不同参数 |
| `contract_file` | `client_upload_id VARCHAR(64) NULL`、`request_hash CHAR(64) NULL` | `UNIQUE(create_id, client_upload_id)`;防止同一用户重复上传,识别同键不同文件 |
- 两个幂等键均为 1~64 位,只允许字母、数字、点、下划线、冒号和连字符;推荐 UUID。
- `request_hash` 为 SHA-256。上传按“规范化原文件名 + 内容 SHA-256”计算;创建按“全部规范化业务字段 + 排序后的 fileIds”计算。
- 唯一索引是最终防线,前置查询只用于快速回放,不能代替唯一约束。
- 上线顺序:dev/prod 只读核对 → 执行 additive DDL 和名称可空变更 → dev 验证 → 再发布新工具。回滚代码时保留新增列,不随代码回滚 DROP。
## 5. MCP 工具契约
### 5.1 `contract.file.upload`
描述:上传一个合同附件到 OSS,并生成 `contract_id=0` 的附件句柄。它只是准备附件,不创建合同。
#### 入参
| 参数 | 类型 | 必填 | 校验与说明 |
|---|---|---|---|
| clientUploadId | string | 是 | 当前用户范围内稳定唯一的上传幂等键;重试必须不变 |
| fileName | string | 是 | 原始文件名,1~255 字符;不得包含路径分隔符;扩展名属于 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv |
| contentBase64 | string | 是 | 标准 Base64 文件内容,不带 data URL 前缀;严格解码,解码后 1 byte~20 MiB |
约束:
- 每次只传一个文件,避免多文件 Base64 导致请求体和内存占用叠加;20 MiB 文件编码后约增加 33% 体积。
- 服务端计算实际字节数、内容 SHA-256 和 requestHash,不信任调用方声明的大小或摘要。
- 除扩展名外,对 PDF/JPEG/PNG、OLE(doc/xls)及 ZIP(docx/xlsx)检查文件头;CSV 拒绝包含 NUL 的二进制内容。
- OSS 对象名使用 `UUID + 小写扩展名`,不照搬毫秒时间戳,避免并发同名覆盖。
- OSS endpoint、bucket、folder 和凭据走环境配置/密钥管理;不把密钥写入代码、日志、工具返回或 MCP 审计内容。
#### 返回
| 字段 | 类型 | 说明 |
|---|---|---|
| fileId | long | 附件句柄,供 `contract.create` 使用 |
| fileName | string | 原始文件名 |
| contractId | long | 当前绑定合同 id;刚上传为 0,幂等回放时可能已大于 0 |
| idempotentReplay | boolean | 是否命中已有上传结果 |
| requestId | string | 本次 MCP 请求追踪 id,不是幂等键 |
上传成功不返回文件内容;审计日志不记录 Base64、文件正文或 OSS 凭据。
### 5.2 `contract.create`
描述:用完整基本信息和已上传附件创建并提交一份合同。提交成功即返回,不等待审批通过。
#### 入参
| 参数 | 类型 | 必填 | 校验与说明 |
|---|---|---|---|
| clientRequestId | string | 是 | 当前用户范围内稳定唯一的创建幂等键;一份逻辑合同一个键 |
| contractType | int | 是 | 0 租赁 / 1 售卖 / 2 其他 |
| customerAgentId | long | 是 | 客户所属公司 id;必须是有效、未软删的总部/分公司(`agent.channel_no ∈ {Z,F}`) |
| propertyId | long | 是 | 所属物业 id;校验存在、未软删和编号可用,**不做行级数据权限过滤** |
| fileIds | array<long> | 是 | 至少 1 个、不得重复;必须全部存在、未软删、`contract_id=0`,且由当前用户通过 MCP 或老系统上传 |
| contractName | string | 否 | 最长 128;空白归一为 null;实际 schema 必须允许 null |
| amount | decimal | 否 | 单位元,非负,最多 2 位小数并满足 `decimal(14,2)` |
| contact | string | 否 | 最长 64;空白归一为 null |
| startDate | string | 是 | 严格 `yyyy-MM-dd` 合法日历日期 |
| endDate | string | 是 | 严格 `yyyy-MM-dd`,且不得早于 startDate |
| expireRemind | int | 否 | 0 关 / 1 开;**默认 1** |
| remindDays | int | 否 | 默认 30;显式传入必须为正整数 |
其他约束:
- 普通新建固定写 `renewSourceId=0`、`renewed=0`、`reminded=0`、`softDelete=0`,不接受调用方指定合同编号、状态、创建人、销售或快照字段。
- 日期不因早于今天而拒绝,保持补录历史合同能力。
- `expireRemind=0` 时 `remindTime=null`;开启时为结束日期减提醒天数后的当天 09:30:00。
- 附件的上传人校验是归属和并发一致性约束,不是物业数据权限;不得把一个 `fileId` 同时用于两份合同。
- 创建失败时已上传附件保持未绑定,可在修正数据后重试;不会留下半份合同。
#### 返回
| 字段 | 类型 | 说明 |
|---|---|---|
| id | long | 新合同或幂等回放合同 id |
| contractNo | string | 服务端生成的合同编号 |
| contractStatus / contractStatusText | int / string | 提交后的状态:0 待审或 2 正常;不代表已经审批通过 |
| fileIds | array<long> | 本次成功绑定的附件 id |
| clientRequestId | string | 创建幂等键,供批量对账 |
| idempotentReplay | boolean | 是否命中已有合同;true 时没有再次执行写入和通知 |
| warnings | array<string> | 提交后通知异常等警告;无警告为空数组 |
| requestId | string | 本次 MCP 请求追踪 id,不是幂等键 |
### 5.3 错误码
- `PERMISSION_DENIED`:服务身份 Token、缺少用户上下文或无工具 scope。
- `INVALID_ARGUMENT`:必填缺失、幂等键非法、枚举/日期/金额/长度非法、Base64/文件头非法、文件为空或超过 20 MiB、附件列表为空或重复。
- `NOT_FOUND`:物业、客户所属公司或附件不存在/已删除。
- `DATA_INTEGRITY_ERROR`:物业编号缺失、销售或销售所属公司缺失、工作流配置损坏、附件条件更新影响行数异常、编号重试耗尽。
- `ATTACHMENT_NOT_BINDABLE`:附件已绑定、非当前用户上传,或并发绑定导致状态已变化。
- `IDEMPOTENCY_CONFLICT`:同一用户复用了相同幂等键,但文件内容/文件名或创建参数与第一次不同。
- `UPSTREAM_UNAVAILABLE`:OSS、创建所需 DB 或 Redis 字典暂时不可用;数据库已提交后的通知异常不使用此错误伪装失败。
## 6. 核心实现行为
### 6.1 上传:OSS 与 DB 的补偿边界
1. 校验用户 Token、scope、参数和文件内容,计算 requestHash。
2. 按 `create_id + client_upload_id` 查询(含已绑定行):
- 已存在且 hash 相同:返回已有 fileId,`idempotentReplay=true`,不上传新对象。
- 已存在但 hash 不同:`IDEMPOTENCY_CONFLICT`。
3. 用随机 UUID 对象名上传 OSS;OSS 未确认成功时不插 DB。
4. 插入 `contract_file`,写原文件名、bucket/folder、HTTPS URL、创建/修改人、时间、`contract_id=0`、`soft_delete=0` 和幂等字段。
5. 若 DB 插入失败或唯一冲突:先查询是否已有同键记录。
- 同键同 hash:删除**本次刚上传的冗余 OSS 对象**,回放已有 fileId。
- 同键不同 hash:删除本次对象,返回冲突。
- 其他 DB 失败:尽力删除本次对象后返回失败;删除失败记录对象 key 供运维清理。
6. 不让 DB 失败触发对已存在附件或其他合同文件的删除。
OSS 成功而 DB 未提交时最多遗留一个未登记对象,不会生成不完整合同;该对象通过告警和运维清单补偿清理。
### 6.2 创建:前置校验
1. 必须为用户委托 Token,创建人、修改人均取 Token 用户 id。
2. 校验完整入参并计算规范化 requestHash;按 `create_id + client_request_id` 查询(含软删行),存在时按 hash 回放或拒绝冲突。
3. 物业只校验存在、未软删、编号可用,**不调用 `applyPropertyRowFilter`,不新增其他物业行级权限判断**。
4. 校验客户所属公司为有效 Z/F 公司,但不强制它等于物业或销售所属公司。
5. 反解物业、销售快照;销售不存在、软删或 `agentId` 为空时明确拒绝。
6. 校验附件列表;Redis 岗位字典在工作流需要时 fail fast。
### 6.3 编号冲突、幂等冲突与 m2 事务
每次尝试都在一个**独立完整 m2 事务**中执行:
1. 统计同一 `customer_no` 的全部合同(含软删),生成编号。
2. 插入合同主记录,包含审计字段、`client_request_id` 和 `request_hash`。
3. 逐附件执行条件更新:`id匹配 AND soft_delete=0 AND contract_id=0 AND create_id=当前用户`,同时写合同 id、修改人和修改时间;每条影响行数必须为 1,否则整体回滚。
4. 写创建流程记录。
5. 读取并校验工作流,写最终合同状态、当前待办和抄送记录。
6. 注册事务提交后的 Redis 消息动作。
异常分类:
- 唯一冲突后先回滚,再按 `create_id + client_request_id` 查询。若查到同 hash 合同,按幂等成功返回;若 hash 不同,返回 `IDEMPOTENCY_CONFLICT`。
- 若不是创建幂等键冲突,而是 `contract_no` 冲突,则在事务外重新计数并开启下一次完整尝试,最多 3 次。
- 不能靠解析数据库错误文本区分冲突;以回滚后的幂等记录查询和后续编号重试为准。
- 有效工作流按 `agent_id + soft_delete=0` 应最多一条;多配置、层级损坏或所需岗位字典缺失时拒绝,不以 `limit 1` 或自动生效掩盖异常。
### 6.4 提交后消息与返回时点
- 仅在待审时发送,JSON 字段保持 `type/no/content/userId`,队列和文案与老系统一致。
- 同事务待办与抄送按 userId 去重消息,但流程记录仍按各自业务语义写入。
- Redis 推送发生在 m2 成功提交之后。
- 推送异常逐条记录日志,工具仍返回合同创建成功及 warnings;不等待审批通过,不做额外审批操作。
- 幂等回放不补发消息,避免一次逻辑提交产生重复待办通知。
- 首版不新增通知 outbox;若以后要求通知必达,另立需求。
### 6.5 大载荷 JSON 约束(实现补充)
20 MiB 文件的标准 Base64 约 27.96 MB 字符,超过 Jackson 2.15+ 默认 `maxStringLength=20,000,000`。
实现通过 `JacksonLargePayloadConfig` 将容器 `ObjectMapper`、Spring AI `JsonParser` 静态 mapper 及 MCP 中间层
mapper 的上限统一放宽到 32 MiB;否则请求会在 MCP SDK 反序列化阶段被拒绝,尚未进入工具方法。
该配置只放宽字符串长度,不改变其他解析限制。
### 6.6 未绑定附件生命周期
- 上传成功但创建未调用/失败:附件保持 `contract_id=0`,可用原 fileId 继续创建,不属于正式合同。
- 创建事务失败:已条件更新的附件随事务回滚,仍可重试。
- 创建成功:全部 fileIds 同事务绑定,不允许继续被其他合同使用。
- 首版不假设已有孤儿附件定时清理,也不提供自动删除工具。批量任务结束后按 `create_id/create_time/client_upload_id/contract_id=0` 输出未使用附件清单,由运维审计后清理;自动清理必须另做任务并避开进行中的导入。
## 7. 权限与 scope
- 两个工具都必须用户身份 Token;服务身份 Token 不允许代传或代建,保证上传人、创建人可追溯。
- 按拍板,不增加物业行级数据权限,也不改变既有 `contract.list/detail.query` 的查询权限。
- 保留附件当前上传人约束和原子条件更新,防止串用附件及并发双绑。
- prod 只绑研发专用 **scope 6(code=code)**;dev 只绑测试专用 scope。
- 不绑业务 scope 1/2/3/5;已有合同查询权限不自动获得上传或创建权限。
## 8. 与老系统差异汇总
| 差异 | 原因 |
|---|---|
| MCP 新增 Base64 附件上传工具 | 支持不经过老页面的批量合同补录 |
| 单文件最大 20 MiB、严格 Base64 和文件头校验 | 控制请求/内存风险,不只依赖可伪造的扩展名 |
| OSS 对象名使用 UUID | 避免毫秒时间戳并发冲突 |
| 上传与创建均有数据库持久化幂等 | 解决批量超时重试产生重复文件/合同的问题 |
| 不增加物业行级权限 | 按拍板复刻老新增接口只登录、直接传物业 id 的口径 |
| 枚举、字符串长度、金额和日期严格校验 | 避免非法数据静默入库 |
| 客户所属公司有效性和 Z/F 渠道校验 | 与老公司选择口径一致,避免脏 id |
| 销售/所属公司缺失拒绝 | 防止空公司被当成无审批配置 |
| `expireRemind` 默认开启 | 按拍板采用二期前端默认口径,而非老后端默认关闭 |
| 附件条件更新必须影响 1 行 | 防止并发创建时两份合同都成功但其中一份没有附件 |
| 编号冲突按完整独立事务重试 | 避免同事务快照重复冲突及部分写入 |
| Redis 岗位字典缺失、工作流多配置或层级损坏时拒绝 | 防止审批被静默跳过 |
| 通知失败透出 warning | 防止数据库已提交但整体响应失败造成重复创建 |
| 创建返回精简为 id/编号/状态/附件/警告 | 提交完成即结束,不要求调用方处理审批人列表或等待审批结果 |
## 9. 变更文件清单(实现阶段)
### 新增
| 文件 | 层级 | 改动说明 |
|---|---|---|
| `src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java` | MCP Tool | 单文件上传、校验、OSS/DB 补偿和上传幂等 |
| `src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java` | MCP Tool | 参数、快照、编号、附件绑定、创建幂等和审批提交 |
| `src/main/java/me/iiv/agent/config/ContractOssProperties.java` | Config | OSS endpoint/bucket/folder 和凭据配置映射 |
| `src/main/java/me/iiv/agent/service/ContractOssService.java` | Service | OSS 上传与本次新对象补偿删除 |
| `src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java` | Entity | 工作流设置实体 |
| `src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java` | Entity | 工作流人员实体 |
| `src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java` | Mapper | 工作流设置查询 |
| `src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java` | Mapper | 工作流人员查询 |
| `src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java` | Test | 上传及幂等测试 |
| `src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java` | Test | 创建、附件、审批及幂等测试 |
| m2 正式 DDL 变更脚本 | Schema | 名称可空、两张表的幂等字段和唯一索引;按环境执行并留核验结果 |
### 修改
| 文件 | 层级 | 改动说明 |
|---|---|---|
| `pom.xml` | Build | 显式引入 `com.aliyun.oss:aliyun-sdk-oss:3.18.5`(JDK17 兼容,避免 3.8.0 的旧传递依赖;已实测 20 MiB 上传) |
| `src/main/resources/application-dev.yml` / `application-prod.yml` | Config | 只增加配置键引用;凭据通过安全注入,不在文档或日志展开 |
| `src/main/java/me/iiv/agent/entity/m2/ContractNew.java` | Entity | 补 `contractType`、`renewed`、创建幂等字段 |
| `src/main/java/me/iiv/agent/entity/m2/ContractFile.java` | Entity | 补 `ossBucket`、`ossFolder`、上传幂等字段 |
| `src/main/java/me/iiv/agent/mcp/tool/ContractTools.java` | 既有查询工具 | 列表/详情补合同类型及文案,便于需要时回读;不改变既有筛选和权限 |
| `src/test/java/me/iiv/agent/mcp/tool/ContractToolsTest.java` | Test | 补合同类型回读断言 |
| `doc/agent-mcp-tools-reference.md` | 文档 | 上线时追加两个工具契约及查询新增字段 |
| `AGENTS.md` | 项目指引 | 上线收尾时登记正式需求号、提交和部署结果 |
没有前端改动,没有 MyBatis-Plus 分页需求。m2 DDL 不走 svc Flyway,不新增异步批任务或通知表。
## 10. 开发任务拆分
| # | 任务 | 完成标准 |
|---|---|---|
| 1 | 核对 dev/prod schema,执行并验证正式 DDL | 名称可空、幂等字段/索引存在;老系统插入回归正常 |
| 2 | 补实体、Mapper、OSS 配置和依赖 | 不泄露凭据;OSS 连接及小文件 dev 验证通过 |
| 3 | 实现上传工具 | 格式/大小校验、OSS+DB 补偿、上传幂等及并发测试通过 |
| 4 | 实现创建工具 | 快照、编号、附件全绑、审批路由、创建幂等及通知 warning 测试通过 |
| 5 | 批量编排与失败恢复验证 | 多份合同部分失败互不影响;同键重试无重复;无半成品合同 |
| 6 | 全量测试、dev MCP 冒烟、文档与上线 | `./mvnw clean package` 全绿;dev 真实写冒烟及清理完成后才走标准发布 |
## 11. 测试要点
### 11.1 上传工具
1. 用户 Token 守卫、scope、write annotations 和审计;审计不含 Base64。
2. 每种允许扩展名;无扩展名、非法扩展名、路径文件名、错误 Base64、空文件、20 MiB 边界和超限。
3. PDF/图片/OLE/ZIP 文件头与扩展名不符时拒绝;CSV 二进制 NUL 拒绝。
4. OSS 失败不插 DB;DB 失败删除本次新对象;补偿删除失败有对象 key 告警。
5. 同用户同 `clientUploadId` 同文件串行/并发只保留一个 DB 附件,返回同一 fileId。
6. 同键不同文件名或内容返回冲突;不同用户可使用相同键但互不影响。
7. 幂等回放不产生新 OSS 对象;已绑定附件回放可返回当前 contractId。
8. 对象 key 随机且不覆盖既有对象,bucket/folder/URL 与数据库一致。
### 11.2 创建工具
1. 所有必填、合同类型、公司、文本长度、金额精度、日期和提醒参数校验;缺省提醒为开启 + 30 天。
2. 物业不存在/软删拒绝;确认不调用 `applyPropertyRowFilter`。
3. 物业、客户、销售和双公司快照正确;销售或所属公司缺失拒绝。
4. 附件为空、重复、不存在、软删、已绑定、他人上传、条件更新 0 行;任一种均无合同或流程残留。
5. 编号计数包含软删,格式正确;编号唯一冲突完整重试,耗尽后整体无写入。
6. 无配置、空层级、部门开关、负责人/非负责人、无部门负责人、1 级会签和抄送分支。
7. 岗位字典缺失、有效工作流多条、审核层级缺 1 级时 fail fast。
8. 任意 DB 写入失败时 m2 全回滚,附件仍未绑定,Redis 没有消息。
9. 消息只在 commit 后发送;type/no/content/userId、接收人去重和文案正确。
10. Redis 通知失败时数据库仍已提交,返回合同 id 和 warning,不返回“未创建”。
11. 同用户同 `clientRequestId` 同参数串行/并发只产生一份合同、一套流程和一次通知;回放不重新绑附件。
12. 同键不同参数返回冲突;创建幂等唯一冲突与合同编号冲突能正确分流。
13. `contract.list/detail.query` 能回读合同类型,既有查询权限和测试不回归。
### 11.3 批量场景与 dev 真实 MCP 冒烟
- 至少模拟 3 份合同:一份完整成功、一份上传失败、一份创建校验失败;验证后两份没有合同记录,且不影响成功份。
- 对上传和创建分别模拟响应丢失后同键重试,核对 OSS 对象数、`contract_new/contract_file/contract_process` 和 Redis 不重复。
- 修正失败基本信息后可复用原未绑定 fileIds;成功合同的附件不能再被另一合同使用。
- 使用 dev 专用测试物业、用户和小型一次性附件,核对 create/modify 人、提醒时间、合同状态及附件绑定。
- 历史合同默认开启提醒时,确认老任务可能立即发送到期提醒;测试需关闭该用例提醒或选择不会触发通知的日期,生产不做写冒烟。
- 测试结束后按本次 id 精确清理 dev 合同、流程、附件和 OSS 对象,恢复工作流,不触碰既有行。
- 全量构建通过后,才允许按标准流程 push main、remote-deploy、绑 prod scope 6;生产只做 tools/list、未授权和无写入参数错误核验。
## 12. 风险与回退
| 风险 | 等级 | 应对 |
|---|---|---|
| 老系统合同代码尚未提交,实际生产行为可能不同 | 高 | 实现前确认目标老系统版本及 dev/prod schema;本设计不冒充生产调研 |
| Base64 增大请求体与堆内存 | 高 | 单文件 20 MiB 上限、逐文件调用、限制批量并发;实现时核对 MCP 网关请求上限 |
| OSS 成功而 DB 失败产生未登记对象 | 中 | 删除本次新对象补偿;失败告警并保留对象 key |
| 上传后放弃创建产生未绑定附件 | 中 | 创建失败保留以便重试;输出未使用清单;不虚构已有自动清理能力 |
| 客户端超时后换幂等键造成重复 | 高 | 契约要求同键同内容重试;唯一索引防同键重复,换键属于新业务意图 |
| 无审批配置导致直接正常 | 高 | 保持老规则,返回实际状态;销售公司缺失不得静默走此分支 |
| 合同编号并发冲突 | 中 | 唯一索引 + 完整独立事务重试 + 幂等冲突分流 |
| 附件被并发绑定 | 高 | 上传人约束 + 条件更新影响行数强校验 + m2 回滚 |
| DB 成功而通知失败 | 中 | 成功返回带 warning;幂等回放不补发;通知必达另做 outbox |
| 历史日期 + 默认提醒开启造成即时通知 | 中 | 契约和风险明示;不希望提醒的历史数据须显式传 `expireRemind=0` |
| 新 DDL 与老系统兼容性 | 高 | 只用可空新增列并先验证;名称可空按二期口径;先库后代码,禁止隐式 DDL |
回退时先解绑/停用两个工具并回滚服务版本,阻止新增调用。保留 additive 幂等列,不随代码回滚删除。已经创建的合同和附件是正式业务数据,不自动删除;受影响记录需逐笔审计并通过老系统业务操作处理。若需恢复合同名称为 NOT NULL,必须先审计并处理所有 null 名称,不能作为代码回滚的默认动作。