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/讨论记录与工具参考文档
This commit is contained in:
@@ -1336,6 +1336,56 @@
|
||||
|
||||
---
|
||||
|
||||
## 57. contract.file.upload
|
||||
|
||||
合同附件上传(写操作,REQ-20261118-0011),合同批量补录专用。
|
||||
|
||||
- 分类:admin | 类型:写(readOnlyHint=false)
|
||||
- 入参:`clientUploadId`(必填,1~64 位字母/数字/点/下划线/冒号/连字符,当前用户内唯一)、
|
||||
`fileName`(必填,1~255 字符,不得含路径分隔符/控制字符,扩展名限 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv)、
|
||||
`contentBase64`(必填,标准 Base64,不带 data URL 前缀,解码后 1 byte~20 MiB)。
|
||||
- 校验:严格 Base64 解码;PDF/JPEG/PNG/OLE/ZIP 校验文件头,CSV 拒绝 NUL 二进制;服务端计算实际字节数,
|
||||
不信任调用方声明的大小。
|
||||
- 写入:OSS 对象名 `UUID.扩展名`(不覆盖既有对象),`contract_file` 写 bucket/folder/URL/上传人、
|
||||
`contract_id=0` 和幂等字段;OSS 或 DB 失败不产生可用附件。
|
||||
- 幂等:同用户同 `clientUploadId` 同文件名+内容返回原 `fileId`(`idempotentReplay=true`,不重复上传);
|
||||
同键不同内容返回 `IDEMPOTENCY_CONFLICT`。DB 失败只补偿删除本次新对象。
|
||||
- 返回:`fileId/fileName/contractId/idempotentReplay/requestId`;审计不含 Base64、正文或凭据。
|
||||
- 权限:零行级权限,prod 只绑研发专用 scope 6(code=code)、dev 只绑测试专用 scope(code=test);
|
||||
必须用户身份 Token,服务身份 Token 拒绝。
|
||||
|
||||
详细设计见 [contract-create-mcp-design](contract-create-mcp-design.md)。
|
||||
|
||||
---
|
||||
|
||||
## 58. contract.create
|
||||
|
||||
合同创建并提交审批(写操作,REQ-20261118-0011),合同批量补录专用。
|
||||
|
||||
- 分类:admin | 类型:写(readOnlyHint=false)
|
||||
- 入参:`clientRequestId`(必填,当前用户内唯一)、`contractType`(0租赁/1售卖/2其他)、
|
||||
`customerAgentId`(有效总部/分公司,channel_no∈{Z,F})、`propertyId`、`fileIds`(至少 1 个、不重复)、
|
||||
`contractName`/`amount`/`contact`(可选)、`startDate`/`endDate`(严格 yyyy-MM-dd,end≥start)、
|
||||
`expireRemind`(默认 1)、`remindDays`(默认 30)。
|
||||
- 快照:物业名称、客户编号/名称、销售取自 `properyt`;合同所属公司取销售 `agent_id`;
|
||||
销售不存在/软删/所属公司为空时拒绝。
|
||||
- 事务:m2 单事务完成合同(编号=物业编号+C+三位流水)、全部附件条件绑定、创建记录、审批待办/抄送;
|
||||
任一条附件条件更新影响行数≠1 时整体回滚。
|
||||
- 审批:按合同所属公司匹配 `contract_flow_set/contract_flow_user`;无配置/无层级按老规则直接正常,
|
||||
待审时返回状态 0;多配置、层级损坏、岗位字典缺失时 fail fast。
|
||||
- 通知:仅在待审时推送 Redis `InvoiceMessageNotice`(type=12 待办/13 抄送),在事务提交后发送;
|
||||
发送失败仍返回成功并附 `warnings`;幂等回放不补发。
|
||||
- 幂等:同用户同 `clientRequestId` 同参数返回原合同(`idempotentReplay=true`),同键不同参数返回
|
||||
`IDEMPOTENCY_CONFLICT`;编号唯一冲突以独立完整事务最多重试 3 次。
|
||||
- 返回:`id/contractNo/contractStatus/contractStatusText/fileIds/clientRequestId/idempotentReplay/warnings/requestId`;
|
||||
提交完成即返回,不等待审批通过。
|
||||
- 权限:零行级权限,prod 只绑研发专用 scope 6(code=code)、dev 只绑测试专用 scope(code=test);
|
||||
必须用户身份 Token,服务身份 Token 拒绝。
|
||||
|
||||
详细设计见 [contract-create-mcp-design](contract-create-mcp-design.md)。
|
||||
|
||||
---
|
||||
|
||||
## 附录:在线查看工具清单
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user