- 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/讨论记录与工具参考文档
34 KiB
合同附件上传与创建工具 — 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. 拍板结论与范围
- 新增
contract.file.upload,MCP 直接接收文件内容并上传 OSS,不再要求调用方先从老页面上传。 - 创建时不增加物业行级数据权限;只保留用户 Token、工具 scope、物业及关联数据有效性校验。
contract.create完成“创建并提交”即返回,不等待审批通过,不代做审核、续签或其他后续动作。- 物业销售或销售所属公司缺失时拒绝创建,避免空公司绕过审批。
expireRemind默认 1(开启),remindDays默认 30。- 数据库已提交但审批通知失败时,仍返回创建成功并附 warning,不诱导重复创建。
- 实现范围补齐主工程缺失的
contractType、renewed、附件 OSS 字段,并正式处理合同名称可空的 schema 冲突。 - 为批量调用的超时重试补上持久化幂等,取代上一版“只有短时并发锁、超时后人工查重”的方案。
本期不包含:附件 OCR/日期识别、合同草稿、审批办理、修改再提交、续签、终止、删除、工作流配置、异步批任务和定时任务迁移。
2. 批量使用总体设计
2.1 两个原子工具,不引入半成品合同
系统没有独立合同草稿状态。contract.create 不允许只插 contract_new 而不绑定附件或不走审批,也不允许 fileIds 为空。
批量导入由调用方按“一份合同一个闭环”编排:
准备该合同基本信息和稳定的 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 编程式事务:
checkFilesBindable:附件必须存在、未软删且contract_id=0(:742-758)。- 写合同创建/修改审计字段。
saveWithContractNo保存合同(:590-605)。bindFiles:逐条把未绑定附件关联到新合同(:764-777);老代码没有检查每条更新的影响行数。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,先执行正式变更:
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 | 是 | 至少 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 | 本次成功绑定的附件 id |
| clientRequestId | string | 创建幂等键,供批量对账 |
| idempotentReplay | boolean | 是否命中已有合同;true 时没有再次执行写入和通知 |
| warnings | array | 提交后通知异常等警告;无警告为空数组 |
| 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 的补偿边界
- 校验用户 Token、scope、参数和文件内容,计算 requestHash。
- 按
create_id + client_upload_id查询(含已绑定行):- 已存在且 hash 相同:返回已有 fileId,
idempotentReplay=true,不上传新对象。 - 已存在但 hash 不同:
IDEMPOTENCY_CONFLICT。
- 已存在且 hash 相同:返回已有 fileId,
- 用随机 UUID 对象名上传 OSS;OSS 未确认成功时不插 DB。
- 插入
contract_file,写原文件名、bucket/folder、HTTPS URL、创建/修改人、时间、contract_id=0、soft_delete=0和幂等字段。 - 若 DB 插入失败或唯一冲突:先查询是否已有同键记录。
- 同键同 hash:删除本次刚上传的冗余 OSS 对象,回放已有 fileId。
- 同键不同 hash:删除本次对象,返回冲突。
- 其他 DB 失败:尽力删除本次对象后返回失败;删除失败记录对象 key 供运维清理。
- 不让 DB 失败触发对已存在附件或其他合同文件的删除。
OSS 成功而 DB 未提交时最多遗留一个未登记对象,不会生成不完整合同;该对象通过告警和运维清单补偿清理。
6.2 创建:前置校验
- 必须为用户委托 Token,创建人、修改人均取 Token 用户 id。
- 校验完整入参并计算规范化 requestHash;按
create_id + client_request_id查询(含软删行),存在时按 hash 回放或拒绝冲突。 - 物业只校验存在、未软删、编号可用,不调用
applyPropertyRowFilter,不新增其他物业行级权限判断。 - 校验客户所属公司为有效 Z/F 公司,但不强制它等于物业或销售所属公司。
- 反解物业、销售快照;销售不存在、软删或
agentId为空时明确拒绝。 - 校验附件列表;Redis 岗位字典在工作流需要时 fail fast。
6.3 编号冲突、幂等冲突与 m2 事务
每次尝试都在一个独立完整 m2 事务中执行:
- 统计同一
customer_no的全部合同(含软删),生成编号。 - 插入合同主记录,包含审计字段、
client_request_id和request_hash。 - 逐附件执行条件更新:
id匹配 AND soft_delete=0 AND contract_id=0 AND create_id=当前用户,同时写合同 id、修改人和修改时间;每条影响行数必须为 1,否则整体回滚。 - 写创建流程记录。
- 读取并校验工作流,写最终合同状态、当前待办和抄送记录。
- 注册事务提交后的 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 上传工具
- 用户 Token 守卫、scope、write annotations 和审计;审计不含 Base64。
- 每种允许扩展名;无扩展名、非法扩展名、路径文件名、错误 Base64、空文件、20 MiB 边界和超限。
- PDF/图片/OLE/ZIP 文件头与扩展名不符时拒绝;CSV 二进制 NUL 拒绝。
- OSS 失败不插 DB;DB 失败删除本次新对象;补偿删除失败有对象 key 告警。
- 同用户同
clientUploadId同文件串行/并发只保留一个 DB 附件,返回同一 fileId。 - 同键不同文件名或内容返回冲突;不同用户可使用相同键但互不影响。
- 幂等回放不产生新 OSS 对象;已绑定附件回放可返回当前 contractId。
- 对象 key 随机且不覆盖既有对象,bucket/folder/URL 与数据库一致。
11.2 创建工具
- 所有必填、合同类型、公司、文本长度、金额精度、日期和提醒参数校验;缺省提醒为开启 + 30 天。
- 物业不存在/软删拒绝;确认不调用
applyPropertyRowFilter。 - 物业、客户、销售和双公司快照正确;销售或所属公司缺失拒绝。
- 附件为空、重复、不存在、软删、已绑定、他人上传、条件更新 0 行;任一种均无合同或流程残留。
- 编号计数包含软删,格式正确;编号唯一冲突完整重试,耗尽后整体无写入。
- 无配置、空层级、部门开关、负责人/非负责人、无部门负责人、1 级会签和抄送分支。
- 岗位字典缺失、有效工作流多条、审核层级缺 1 级时 fail fast。
- 任意 DB 写入失败时 m2 全回滚,附件仍未绑定,Redis 没有消息。
- 消息只在 commit 后发送;type/no/content/userId、接收人去重和文案正确。
- Redis 通知失败时数据库仍已提交,返回合同 id 和 warning,不返回“未创建”。
- 同用户同
clientRequestId同参数串行/并发只产生一份合同、一套流程和一次通知;回放不重新绑附件。 - 同键不同参数返回冲突;创建幂等唯一冲突与合同编号冲突能正确分流。
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 名称,不能作为代码回滚的默认动作。