From 2aa99abdddcac948d71afb8d577d822d4a241a5e Mon Sep 17 00:00:00 2001 From: my_local_kimi_dev2 Date: Thu, 19 Nov 2026 09:31:19 +0800 Subject: [PATCH] =?UTF-8?q?feat(mcp):=20=E6=96=B0=E5=A2=9E=E5=90=88?= =?UTF-8?q?=E5=90=8C=E6=89=B9=E9=87=8F=E8=A1=A5=E5=BD=95=E4=B8=8A=E4=BC=A0?= =?UTF-8?q?=E4=B8=8E=E5=88=9B=E5=BB=BA=E5=B7=A5=E5=85=B7=20(REQ-20261118-0?= =?UTF-8?q?011)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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/讨论记录与工具参考文档 --- xiaoqu-agent-service/AGENTS.md | 3 +- .../doc/agent-mcp-tools-reference.md | 50 ++ .../doc/contract-create-mcp-design.md | 486 +++++++++++ ...8-0011-contract-batch-upload-discussion.md | 186 +++++ ...20261118-0011-contract-batch-upload-prd.md | 406 ++++++++++ xiaoqu-agent-service/pom.xml | 8 + .../sql/m2-contract-batch-upload-ddl.sql | 20 + .../me/iiv/agent/common/AuditService.java | 17 +- .../agent/config/ContractOssProperties.java | 33 + .../config/JacksonLargePayloadConfig.java | 47 ++ .../me/iiv/agent/entity/m2/ContractFile.java | 20 + .../iiv/agent/entity/m2/ContractFlowSet.java | 46 ++ .../iiv/agent/entity/m2/ContractFlowUser.java | 55 ++ .../me/iiv/agent/entity/m2/ContractNew.java | 20 + .../mapper/m2/ContractFlowSetMapper.java | 10 + .../mapper/m2/ContractFlowUserMapper.java | 10 + .../me/iiv/agent/mcp/GuardedToolCallback.java | 3 +- .../java/me/iiv/agent/mcp/McpErrorCode.java | 6 + .../main/java/me/iiv/agent/mcp/McpJson.java | 32 + .../agent/mcp/McpToolCallEnvelopeFilter.java | 2 +- .../agent/mcp/ToolCallEnvelopeRewriter.java | 2 +- .../mcp/tool/ContractCreateAdminTools.java | 758 ++++++++++++++++++ .../mcp/tool/ContractFileAdminTools.java | 304 +++++++ .../me/iiv/agent/mcp/tool/ContractTools.java | 6 + .../iiv/agent/service/ContractOssService.java | 108 +++ .../src/main/resources/application-dev.yml | 4 + .../src/main/resources/application.yml | 11 + .../tool/ContractCreateAdminToolsTest.java | 431 ++++++++++ .../mcp/tool/ContractFileAdminToolsTest.java | 194 +++++ 29 files changed, 3272 insertions(+), 6 deletions(-) create mode 100644 xiaoqu-agent-service/doc/contract-create-mcp-design.md create mode 100644 xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md create mode 100644 xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-prd.md create mode 100644 xiaoqu-agent-service/sql/m2-contract-batch-upload-ddl.sql create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/config/ContractOssProperties.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/config/JacksonLargePayloadConfig.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpJson.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java create mode 100644 xiaoqu-agent-service/src/main/java/me/iiv/agent/service/ContractOssService.java create mode 100644 xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java create mode 100644 xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java diff --git a/xiaoqu-agent-service/AGENTS.md b/xiaoqu-agent-service/AGENTS.md index e91b5d3..67c6d4d 100644 --- a/xiaoqu-agent-service/AGENTS.md +++ b/xiaoqu-agent-service/AGENTS.md @@ -3,7 +3,7 @@ ## ai-proj 关联信息 - **ai-proj 项目 ID:224**(项目名 xiaoqu_agent_service)。本仓所有需求/任务创建后应挂到该项目,关联任务前确保任务也在项目 224。 -- 近期需求示例:REQ-20261117-0008(id 6623,站点状态修改 district.state.update,已上线生产+只读核验通过,prod tool id 75 只绑研发专用 scope 6;576 个全量测试及 dev 真实「履约→演示→履约」/39 个资产联动恢复通过)→ 任务 27566;REQ-20261117-0003(id 6618,设备转固定资产写工具 device.lifecycle.fixed_asset.update,已上线生产+冒烟通过,prod tool id 74 只绑研发专用 scope 6;拍板:报废(4)与已是固定资产(1)守卫拒绝、null 按库存商品、只写 asset_state/memo/modify_id/modify_time 四列、不联动资产卡片/金蝶;DeviceLifeCycle 实体补 memo 映射)→ 任务 27536;REQ-20261113-0009(id 6550,短信验证码提取 sms.vercode.latest.query,已上线生产+冒烟通过;验证码=登录敏感原语,全平台唯一显式排除业务 scope:prod 只绑研发专用 scope 6(tool id 73)、dev 只绑测试专用 scope)→ 任务 27164;REQ-20261107-0003(id 6443,出库单作废写工具 warehouse.out.void,已上线生产+冒烟通过,只绑研发专用 scope 6)→ 任务 26410;REQ-20261105-0020(id 6390,仓库出入库明细+在库物品 warehouse.out/in.details.list.query、warehouse.hardstock.list.query 3 工具,approved)→ 任务 26101;REQ-20261104-0015(id 6366,清机记录 hardware.cleanlog.list.query,已上线生产+冒烟通过)→ 任务 25998;REQ-20261012-0004(id 5977,空感 toilet.airquality list/detail/metrics/statelog 4 工具,已部署生产+冒烟通过)→ 任务 23488;REQ-20261013-0006(id 5988,代理角色用户查询工具 agent.user.list.query,approved)→ 任务 23566;REQ-20261012-0002(id 5975,客户换纸记录工具 district.paper.trace.list.query,released)→ 任务 23486;REQ-20260924-0009(id 5806,人流量统计工具+统计类限一个月,implementation 完成)→ 任务 22405;REQ-20260924-0003(id 5800,设备生命周期查询工具,implementation 完成)→ 任务 22391;REQ-20260921-0007(id 5778,设备电量消息查询工具,released)→ 任务 22306;REQ-20260919-0003(id 5747,出入库工具复查修复,released)→ 任务 22123。 +- 近期需求示例:REQ-20261118-0011(id 6646,合同批量补录 `contract.file.upload`/`contract.create`,已实现、615 个全量测试通过、dev 真实 MCP 冒烟与数据清理通过;m2 DDL 脚本 `sql/m2-contract-batch-upload-ddl.sql` dev 已执行、prod 未执行;dev OSS 用 `xiaoqu-safefile/contract-dev/`;20 MiB Base64 依赖 `JacksonLargePayloadConfig` 的 32 MiB 字符串上限)→ 任务 27752;REQ-20261117-0008(id 6623,站点状态修改 district.state.update,已上线生产+只读核验通过,prod tool id 75 只绑研发专用 scope 6;576 个全量测试及 dev 真实「履约→演示→履约」/39 个资产联动恢复通过)→ 任务 27566;REQ-20261117-0003(id 6618,设备转固定资产写工具 device.lifecycle.fixed_asset.update,已上线生产+冒烟通过,prod tool id 74 只绑研发专用 scope 6;拍板:报废(4)与已是固定资产(1)守卫拒绝、null 按库存商品、只写 asset_state/memo/modify_id/modify_time 四列、不联动资产卡片/金蝶;DeviceLifeCycle 实体补 memo 映射)→ 任务 27536;REQ-20261113-0009(id 6550,短信验证码提取 sms.vercode.latest.query,已上线生产+冒烟通过;验证码=登录敏感原语,全平台唯一显式排除业务 scope:prod 只绑研发专用 scope 6(tool id 73)、dev 只绑测试专用 scope)→ 任务 27164;REQ-20261107-0003(id 6443,出库单作废写工具 warehouse.out.void,已上线生产+冒烟通过,只绑研发专用 scope 6)→ 任务 26410;REQ-20261105-0020(id 6390,仓库出入库明细+在库物品 warehouse.out/in.details.list.query、warehouse.hardstock.list.query 3 工具,approved)→ 任务 26101;REQ-20261104-0015(id 6366,清机记录 hardware.cleanlog.list.query,已上线生产+冒烟通过)→ 任务 25998;REQ-20261012-0004(id 5977,空感 toilet.airquality list/detail/metrics/statelog 4 工具,已部署生产+冒烟通过)→ 任务 23488;REQ-20261013-0006(id 5988,代理角色用户查询工具 agent.user.list.query,approved)→ 任务 23566;REQ-20261012-0002(id 5975,客户换纸记录工具 district.paper.trace.list.query,released)→ 任务 23486;REQ-20260924-0009(id 5806,人流量统计工具+统计类限一个月,implementation 完成)→ 任务 22405;REQ-20260924-0003(id 5800,设备生命周期查询工具,implementation 完成)→ 任务 22391;REQ-20260921-0007(id 5778,设备电量消息查询工具,released)→ 任务 22306;REQ-20260919-0003(id 5747,出入库工具复查修复,released)→ 任务 22123。 ## ai-proj MCP 已知限制与真实契约 @@ -33,6 +33,7 @@ 数据走内网 192.168.1.181 的 `*_d` dev 库,与生产隔离)。冒烟一律先在测试环境跑: 签 Token 用 `scopeCode=test`(「测试专用」scope,seed-dev.sql 已把所有 kind=write 工具绑到它), 验证通过后再走 remote-deploy 上生产;生产只留必要的只读核验,不做改派/作废类写冒烟。 +- 合同附件工具(REQ-20261118-0011)发布前,必须先对目标 m2 库执行 `sql/m2-contract-batch-upload-ddl.sql`(合同名称可空 + 两张表幂等列/唯一索引),否则实体查询会因未知列失败;dev 已执行,prod 未执行。20 MiB Base64 依赖 `JacksonLargePayloadConfig` 的 32 MiB Jackson 字符串上限;dev OSS 固定使用 `xiaoqu-safefile/contract-dev/`,生产为 `contract/`。 - **部署前必须先把 main 推 origin**:出现过本地 main 领先 origin 1 个修复提交、他人从 origin 构建部署导致生产跑到旧代码的情况(2026-09-22 paperuselog terms 结构 400)。 - 新工具上线后必须幂等绑 prod scope(svc 库 MySQL,tool 表唯一标识列是 `name`;scope 表是 `agent_scope`):**2026-11-07 起王恒新口径——所有工具默认绑研发专用 scope 6(code=code),现有 71 个工具已全部补绑;其他作用域不说明不分配**(此前惯例:hardware/district 系列绑 1/2/3/5,warehouse 系列绑 1/2/5)。 - prod AK 的 Authorization 头值本身已含 "Bearer " 前缀,不要再拼。 diff --git a/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md b/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md index 4e5af75..b95420b 100644 --- a/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md +++ b/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md @@ -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 diff --git a/xiaoqu-agent-service/doc/contract-create-mcp-design.md b/xiaoqu-agent-service/doc/contract-create-mcp-design.md new file mode 100644 index 0000000..2215608 --- /dev/null +++ b/xiaoqu-agent-service/doc/contract-create-mcp-design.md @@ -0,0 +1,486 @@ +# 合同附件上传与创建工具 — 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 | 是 | 至少 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 的补偿边界 + +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 名称,不能作为代码回滚的默认动作。 diff --git a/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md b/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md new file mode 100644 index 0000000..4c14f35 --- /dev/null +++ b/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md @@ -0,0 +1,186 @@ +# REQ-20261118-0011 需求讨论记录 + +## 元数据 +- Requirement:REQ-20261118-0011(id 6646,项目 224) +- ai-proj 讨论任务:27749(linkRole=documentation) +- 状态:PRD 优化中 +- 最新 PRD:待创建 +- 更新时间:2026-11-18T16:59:03+08:00 + +## 原始诉求 + +### 2026-11-18 · 初始设计请求 +> 你看下老系统的合同管理的 创建流程,打算写个工具 你先设计一下 + +### 2026-11-18 · 六项决策与批量场景补充 +> 1:附件也要上传 也得提供工具 2:不控制权限 3:提交成功就完事了 4:同意 5:默认开启 6:同意 遗留的问题 你也补上吧 使用这就是想批量上传合同 但是工具只能填写完基本信息 上传完附件 才能形成一个完成的合同 你在想想怎么设计 + +### 2026-11-18 · 文件上限与流程要求 +> 合同文件会大于10M,限制20M吧 先创建ai-proj需求 审批通过以后在开始开发 + +## 问答记录 + +### Q001 · 老系统创建流程与首版工具边界 +- 状态:已替代(由 Q002、Q003 补充) +- AI 问题(原文):首版是否按 `contract.create` 复刻“创建即提交审批”,附件复用已上传的孤儿 fileId,并显式处理越权、附件竞争和通知失败? +- 提问意图:确定创建工具的事务边界、附件来源及与老系统的差异。 +- AI 建议与权衡:建议完整复刻创建提交流程,首版不做 MCP 文件上传;增加物业行级权限。该方案上传链路不完整,不适合用户的批量场景。 +- 待确认内容:创建、附件绑定、创建记录、审批提交在一个业务闭环中完成。 +- 用户回答(原文):见“六项决策与批量场景补充”。 +- 最终决策:必须提供独立附件上传工具,不能依赖老页面预先上传。 +- 影响范围:功能清单、批量流程、工具契约、验收标准。 +- 未决项:由 Q002、Q003 收敛。 +- 记录时间:2026-11-18T16:59:03+08:00 + +### Q002 · 六项业务口径与遗留模型问题 +- 状态:已确认 +- AI 问题(原文):请对附件、权限、审批返回时点、异常数据、提醒默认值、通知失败六项建议逐项拍板。 +- 提问意图:避免 AI 自行假设权限、默认提醒和提交后的成功语义。 +- AI 建议与权衡:首版只接收孤儿 fileId、增加物业行级权限、无流程直接正常、销售或公司缺失拒绝、提醒默认关闭、通知失败成功加 warning;用户选择了不同口径。 +- 待确认内容:六项业务规则及缺失字段/schema 是否纳入本期。 +- 用户回答(原文): + > 1:附件也要上传 也得提供工具 2:不控制权限 3:提交成功就完事了 4:同意 5:默认开启 6:同意 遗留的问题 你也补上吧 +- 最终决策: + 1. 提供附件上传工具; + 2. 不增加物业行级权限; + 3. 创建并提交成功即返回,不等待审批通过; + 4. 物业销售或销售所属公司缺失时拒绝; + 5. `expireRemind` 默认 1,`remindDays` 默认 30; + 6. 数据库提交后的通知失败仍返回成功并附 warning; + 7. 补齐 `contractType/renewed`、附件 OSS 字段和合同名称可空 DDL。 +- 影响范围:业务规则、安全边界、返回契约、数据模型、验收标准。 +- 未决项:无。 +- 记录时间:2026-11-18T16:59:03+08:00 + +### Q003 · 批量上传如何避免半成品与重复资源 +- 状态:已确认 +- AI 问题(原文):批量场景如何组织上传与创建,保证基本信息和全部附件就绪后才形成完整合同,并支持超时安全重试? +- 提问意图:确定批量事务粒度、失败隔离和幂等策略。 +- AI 建议与权衡:采用 `contract.file.upload` 与 `contract.create` 两个原子工具;每份合同独立闭环,不做整批一个事务。以上传键和创建键配合数据库唯一约束实现持久化幂等,比短时锁更能处理响应丢失。 +- 待确认内容:两个原子工具、逐份编排、单份失败隔离、同键重试回放、同键不同内容冲突。 +- 用户回答(原文): + > 使用这就是想批量上传合同 但是工具只能填写完基本信息 上传完附件 才能形成一个完成的合同 你在想想怎么设计 +- 最终决策:收齐单份合同全部 fileIds 后才允许创建;创建事务同时完成合同、全部附件绑定和审批提交;任一附件失败则不调用该合同创建,其他合同继续。 +- 影响范围:用户流程、事务边界、异常恢复、幂等验收。 +- 未决项:无。 +- 记录时间:2026-11-18T16:59:03+08:00 + +### Q004 · 单文件上限与开发启动门禁 +- 状态:已确认 +- AI 问题(原文):是否将单文件解码后上限调整为 20 MiB,并先建立需求、评审通过后再开发? +- 提问意图:确认大于 10 MiB 文件的支持边界及本轮是否允许实现。 +- AI 建议与权衡:20 MiB 能覆盖更大的合同扫描件,但 Base64 请求约增加三分之一,仍需逐文件上传、限制批量并发并核对 MCP 网关请求上限。 +- 待确认内容:单文件最大 20 MiB;本轮只建需求并走评审,不开始开发。 +- 用户回答(原文): + > 合同文件会大于10M,限制20M吧 先创建ai-proj需求 审批通过以后在开始开发 +- 最终决策:单文件解码后最大 20 MiB;审批通过是开发启动前置条件。 +- 影响范围:上传契约、性能风险、测试边界、里程碑。 +- 未决项:无。 +- 记录时间:2026-11-18T16:59:03+08:00 + +## 决策变更 + +### D001 · 附件上限由 10 MiB 调整为 20 MiB +- 替代内容:设计稿初版单文件 10 MiB 上限。 +- 用户原话:见 Q004。 +- 新结论:按解码后的实际文件字节计算,最大 20 MiB;超过即拒绝,不以 Base64 字符串长度代替文件大小。 +- 同步范围:设计稿 6 处限制、需求验收标准、PRD 上传契约与测试。 + +## 当前决策快照 + +- 目标与成功条件:批量补录时逐份完成“上传全部附件 → 创建并提交完整合同”,失败可恢复、重试不重复。 +- 用户/角色及核心场景:持有有效用户委托 Token 且获工具 scope 的调用方/Agent;服务身份 Token 不允许代传代建。 +- 范围:新增 `contract.file.upload`、`contract.create`;既有合同查询补回读字段;必要 m2 DDL 与实体映射。 +- 非目标:OCR/日期识别、合同草稿、审批办理、修改再提交、续签、终止、删除、工作流配置、异步批任务、通知 outbox、自动孤儿附件清理和定时任务迁移。 +- 核心实体与归属:`contract_new`、`contract_file`、`contract_process`;m0 只读获取物业、用户和公司快照,m2 单库事务写合同业务数据;OSS 存文件。 +- 权限:不增加物业行级过滤;附件必须由当前用户上传且未绑定,防止跨用户串用和并发双绑。 +- 状态与冲突:创建提交后返回待审或正常,不等待审批结果;无审批配置等场景按老规则决定实际状态。 +- 异常与恢复:上传失败不创建;创建失败整体回滚并保留未绑定附件供重试;通知失败成功加 warning;不自动撤销正式合同。 +- 幂等与审计:`clientUploadId/clientRequestId` 在当前用户内唯一,数据库唯一索引兜底;同键同内容回放,同键不同内容冲突;审计不记录 Base64、正文或凭据。 +- 文件约束:单文件解码后 1 byte~20 MiB;逐文件调用;允许 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv,并检查文件头。 +- 提醒与历史数据:默认开启、提前 30 天;允许历史日期,调用方不希望触发历史到期提醒时须显式关闭。 +- 验收草案:20 MiB 边界、完整性、事务回滚、幂等并发、审批状态、通知 warning、默认提醒、dev 真实冒烟与生产只读核验均可检查。 +- 尚存风险:20 MiB Base64 的网关和堆内存压力、OSS/DB 补偿残留、历史日期即时提醒、老系统源码与生产版本可能不一致。 + +## 未决问题 +- 无。 + +## 方案确认 +- 确认问题:是否确认按当前设计生成 PRD 并提交需求评审?方案为两个原子工具逐份批量补录,单文件解码后上限 20 MiB,上传与创建均做持久化幂等,创建提交成功即返回。 +- 用户确认原话:方案确认通过(推荐) +- 确认时间:2026-11-18 +- 确认结果:允许生成并关联 PRD;不代表批准需求本身,也不允许提前开发。 + +## PRD / 缺陷优化记录 + +### Round 001 · 全维度基线审计 +- PRD 输入版本:本地 v0.1,SHA-256 `43f8d9985a492dfc632322022a5312aa2615c047aeec2cbdd9af9c85d8f1a264`;ai-proj 任务 27750、文档 23674、version 1、updated_at `2026-11-18T09:08:29.357845Z`。 +- 双写校验:本地与远程正文逐段一致,共 384 行;模板 1~9 章完整,8 条 AC 均含 VP-Data/VP-Steps/VP-Pass。 +- 检查维度:致命架构可行性、高级运行时/并发/资源生命周期、中级数据契约/状态/边界、低级体验/维护;沿调用方 → MCP → OSS/DB/Redis → 返回的完整数据流检查。 +- 新缺陷:5 个(致命 0、高 0、中 4、低 1)。 + +#### 缺陷 1:附件“完整性”的服务端保证边界不够明确(中) +- 问题:服务端只能保证本次提交的 fileIds 全部绑定,无法发现调用方遗漏且未声明的文件。 +- 场景:调用方某合同实际上有 3 个文件,但只向 create 传入 2 个 fileIds。 +- 后果:若把“完整合同”理解为服务端能识别缺失文件,会形成错误验收预期。 +- 解决:接受。PRD 明确完整性以调用方声明的 fileIds 集合为边界;调用方负责收齐,服务端保证该集合内不少绑、不部分绑。 +- 验收:功能说明与 AC2 均包含该边界,无新增产品行为。 + +#### 缺陷 2:AC1 假设附件表存在文件大小字段(中) +- 问题:现有设计和变更清单没有 `contract_file.file_size` 字段,但 AC1 要求核对“DB 大小”。 +- 场景:按 AC 执行时无对应数据库字段可核验。 +- 后果:验收不可执行,或被迫扩大 schema 范围。 +- 解决:接受。改为核对 OSS 实际字节数恰好 20 MiB,以及 DB 文件名/bucket/folder/URL 与 OSS 对象一致,不新增大小字段。 +- 验收:AC1 不再引用不存在的字段。 + +#### 缺陷 3:AC4 的“一次通知”未限定待审场景(中) +- 问题:直接正常合同按老规则没有审批通知,统一要求一次通知与功能 5 冲突。 +- 场景:使用无审批工作流的数据执行幂等验收。 +- 后果:正常实现也可能被误判不通过。 +- 解决:接受。AC4 明确使用有层级待审工作流;该用例首次提交只通知一次,回放不补发,直接正常场景仍由 AC5 验证零审批通知。 +- 验收:AC4 前置数据与通过判定一致。 + +#### 缺陷 4:dev OSS 隔离被当作已确认事实(中) +- 问题:PRD 直接写“dev OSS”,但当前调研只确认 dev 数据库隔离,未核实 OSS 是否独立 bucket。 +- 场景:dev 与生产共用 bucket 时,测试对象可能影响生产文件清单。 +- 后果:测试隔离假设失真,清理边界不清。 +- 解决:接受。改为实现前核对 dev OSS 配置;优先使用 dev 专用 bucket,若共用则强制独立测试 prefix/runId 并按本次对象 key 精确清理,不触碰既有对象。 +- 验收:AC1、性能/兼容性和发布门禁均体现该条件。 + +#### 缺陷 5:AC8 的声明环境与验证步骤不一致(低) +- 问题:VP-Data 仅声明 localhost,但步骤同时要求生产核验。 +- 场景:按模板执行时无法判断应在哪个环境建数据。 +- 后果:验收证据归属不清。 +- 解决:接受。拆为 AC8(localhost 全量质量与 dev 冒烟)和 AC9(production 只读发布核验),分别提供 VP 三件套。 +- 验收:每条 AC 环境单一、步骤与通过判定一致。 + +- PRD 修订:上述 5 项全部接受,形成 v0.2;不改变已确认目标、权限、工具范围或默认业务规则。 +- 剩余风险:20 MiB 网关/内存、OSS/DB 补偿、孤儿附件、历史日期提醒和老系统版本差异继续保留为已识别风险;需在实现及验收阶段处理。 + +## HTML 原型记录 +### Prototype v1 · 不适用 +- PRD 基线:待 PRD 收敛后填写 +- 是否适用:否。需求仅包含后端 MCP 工具、数据库和 OSS 行为,没有页面、表单、列表或可视交互界面;调用方批量编排不属于本系统 UI。 +- 原型 URL:不适用 +- Requirement 关联校验:不适用 +- iframe / 可访问性 / 关键交互验证:不适用 +- 用户反馈:已确认纯后端无 UI;用户指令“继续推进”并要求按自审自签流程交付 +- 行为性变更回流:无 +- 状态:已确认,不适用(纯后端 MCP 工具) + +## 收敛结论 +- PRD 版本:v0.2(2026-11-18)。 +- 缺陷收敛:Round 001 的 5 项全部接受并已落到 PRD:完整性边界(AC2)、20 MiB 校验不依赖不存在的 file_size(AC1)、通知验收限定待审场景(AC4)、dev OSS 隔离改为实现前核对+独立 prefix/runId(功能 1、5.1、AC1、6.2)、生产只读核验拆出 AC9。 +- 最终确认:用户已确认方案并要求“建 → allow_self_approve=true → 设自审 → 自签”,不再等待外部审批人;该指令同时作为无 UI 跳过与进入开发的确认。 +- 开放风险:20 MiB 网关/内存、OSS/DB 补偿残留、孤儿附件、历史日期提醒、老系统源码与生产版本差异;均保留并在实现及验收阶段处理。 +- 结论:文档与验收口径已收敛,允许提交需求评审并按用户指令自审自签。 + +## 实现与验证记录(2026-11-18) + +- 需求:REQ-20261118-0011 已按用户指令自审自签(allow_self_approve=true,评审人/提交人均为 wangheng,status=approved)。 +- dev schema:`contract_name` 已改为可空;`contract_new/contract_file` 已新增幂等列与唯一索引(`uk_contract_client_request`、`uk_file_client_upload`);执行脚本 `sql/m2-contract-batch-upload-ddl.sql`。 +- 实现:`contract.file.upload`、`contract.create`、工作流实体/Mapper、OSS 服务与配置、Jackson 32 MiB 大载荷约束、合同查询补 `contractType/renewed` 回读。 +- 全量构建:`./mvnw clean package` 通过,615 个测试、0 失败。 +- dev 冒烟:小文件上传与同键回放、恰好 20 MiB 上传(约 7 秒)、20 MiB+1 byte 拒绝、正常合同(无工作流,status=2)、待审合同(status=0,1 条层级待办 + 2 条抄送)、同键创建回放、软删销售拒绝且无合同残留,均通过。 +- 清理:按合同/附件/流程精确删除 2 份测试合同、4 个附件和 5 条流程记录,OSS 删除 4 个 `contract-dev/` 对象;Redis 待审通知在检查时已被 dev 消费端取走。 +- 未完成:提交、推送、生产 DDL、remote-deploy、prod scope 6 绑定与只读核验;生产变更前需按设计先执行 additive DDL。 diff --git a/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-prd.md b/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-prd.md new file mode 100644 index 0000000..c010d34 --- /dev/null +++ b/xiaoqu-agent-service/docs/product/REQ-20261118-0011-contract-batch-upload-prd.md @@ -0,0 +1,406 @@ +# 合同批量补录:附件上传与创建提交 MCP 工具 PRD + +- Requirement:REQ-20261118-0011(id 6646,项目 224) +- ai-proj PRD 任务:27750(linkRole=prd) +- 版本:v0.2(已审批;开发完成,全量测试与 dev 冒烟通过,待发布) +- 日期:2026-11-18 +- 技术设计基线:`doc/contract-create-mcp-design.md` + +## 1. 概述 + +### 1.1 背景 + +批量补录合同目前需要在老页面逐份填写基本信息、上传附件并提交,重复操作多。若只把老接口简单暴露为工具,调用方仍需自行解决文件上传、附件归属、超时重试和审批提交,可能产生重复附件、重复合同、部分附件绑定或没有附件的正式合同。 + +本期面向批量补录场景提供两个 MCP 原子工具:先逐个上传附件,收齐单份合同的全部附件句柄后,再创建并提交完整合同。每份合同独立成功或失败,不做整批一个事务。 + +### 1.2 目标 + +- 业务目标:让调用方可以逐份自动完成合同附件上传、基本信息录入和审批提交,减少老页面重复操作。 +- 用户目标:单份数据或文件失败不影响其他合同;失败后可从原阶段安全重试,不需要整批重跑。 +- 技术目标:以单份合同 m2 事务保证完整性,以数据库持久化幂等保证响应丢失后的重试安全;创建提交成功即返回,不等待审批结果。 + +### 1.3 成功指标 + +| 指标 | 当前值 | 目标值 | 衡量方式 | +|---|---|---|---| +| 单文件支持上限 | 老接口未限制;MCP 初版设计为 10 MiB | 解码后恰好 20 MiB 可上传,20 MiB + 1 byte 拒绝 | dev 真实 MCP 边界测试 | +| 无附件或部分附件绑定的正式合同 | 无 MCP 批量创建能力 | 0 份 | 失败注入后查询合同、附件和流程记录 | +| 同用户同幂等键重复创建 | 无持久化创建幂等 | 串行/并发重试均只产生 1 份合同、1 套流程、1 次通知 | 并发测试及数据库/Redis 核对 | +| 批量失败隔离 | 人工逐份处理 | 单份失败不阻塞其他合同 | 3 份合同混合成败场景验证 | +| 生产写冒烟 | 新工具未上线 | 0 次;生产仅只读核验 | 发布记录与工具调用审计 | + +### 1.4 客户原始诉求 + +- 场景 1(提出人:wangheng / 时间:2026-11-18 / 出处:Slark 当前需求讨论): + > 你看下老系统的合同管理的 创建流程,打算写个工具 你先设计一下 +- 场景 2(提出人:wangheng / 时间:2026-11-18 / 出处:Slark 当前需求讨论): + > 1:附件也要上传 也得提供工具 2:不控制权限 3:提交成功就完事了 4:同意 5:默认开启 6:同意 遗留的问题 你也补上吧 使用这就是想批量上传合同 但是工具只能填写完基本信息 上传完附件 才能形成一个完成的合同 你在想想怎么设计 +- 场景 3(提出人:wangheng / 时间:2026-11-18 / 出处:Slark 当前需求讨论): + > 合同文件会大于10M,限制20M吧 先创建ai-proj需求 审批通过以后在开始开发 + +## 2. 用户分析 + +### 2.1 目标用户 + +- 主要使用者:获得本工具授权、持有有效用户委托 Token 的内部研发或 Agent 调用方。 +- 业务受影响角色:合同创建人、审批人、抄送人;其身份和消息均沿用老系统用户及工作流数据。 +- 运维/研发角色:负责 schema 核验、dev 数据清理、工具 scope 绑定及生产只读核验。 + +### 2.2 用户痛点 + +1. 老页面逐份上传和录入,批量补录效率低。 +2. 上传与创建分开后,任一阶段失败都可能让调用方不知道应重传、重用附件还是重新创建。 +3. 请求超时但服务端已成功时,普通重试会产生重复附件、合同或审批通知。 +4. 老接口的部分宽松校验和缺失映射可能产生脏数据或静默跳过审批。 +5. 数据库已提交而通知失败时,如果工具整体报错,会诱导调用方重复创建。 + +### 2.3 用户场景 + +调用方准备一批历史合同,每份包含完整基本信息、至少一个文件和稳定幂等键。对每份合同依次上传全部文件;全部成功后调用创建工具。某份文件超限或基本信息非法时,只记录该份失败并继续其他合同;网络超时时使用相同幂等键和相同内容重试。创建工具返回合同 id、编号、提交后状态及可能的通知 warning,批量任务按创建幂等键对账。 + +## 3. 功能需求 + +### 3.1 功能清单 + +| 功能 | 优先级 | 描述 | 验收标准 | +|---|---|---|---| +| 单附件上传 `contract.file.upload` | P0 | Base64 上传一个文件到 OSS 并生成未绑定附件句柄 | AC1、AC4 | +| 完整合同创建 `contract.create` | P0 | 校验完整信息和附件,单事务创建、绑定并提交审批 | AC2、AC3、AC5、AC6 | +| 批量逐份编排 | P0 | 每份合同独立闭环,失败按份隔离,不设置整批事务 | AC2 | +| 上传/创建持久化幂等 | P0 | 同键同内容回放,同键不同内容冲突,唯一索引兜底 | AC4 | +| 审批与通知兼容 | P0 | 按公司匹配老工作流;提交即返回;通知失败附 warning | AC5 | +| 提醒及历史补录 | P0 | 默认开启并提前 30 天,允许历史日期 | AC6 | +| 既有模型/schema 补齐 | P0 | 补二期字段、附件 OSS 字段、名称可空和幂等列/索引 | AC7 | +| 合同查询字段回读 | P1 | 既有列表/详情补合同类型与文案,不改变查询权限 | AC7 | +| 测试、发布与只读核验 | P0 | dev 完成真实写冒烟,生产不写业务数据,只绑研发 scope 6 | AC8、AC9 | + +### 3.2 功能详细说明 + +#### 功能 1:单附件上传 + +- 功能描述:新增 `contract.file.upload`,每次只接收一个文件,上传 OSS 后在 `contract_file` 生成 `contract_id=0` 的附件记录并返回 `fileId`。 +- 触发条件:有效用户委托 Token、工具 scope、`clientUploadId + fileName + contentBase64` 完整且合法。 +- 业务规则: + - 解码后实际大小为 1 byte~20 MiB(20,971,520 bytes);以字节数为准,不以 Base64 字符串长度代替。 + - 允许 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv;文件名不得包含路径分隔符。 + - 严格 Base64 解码,不带 data URL 前缀;对 PDF/JPEG/PNG、OLE、ZIP 检查文件头,CSV 拒绝含 NUL 的二进制内容。 + - OSS 对象名采用 UUID 加小写扩展名;保存 bucket、folder、URL 和上传人,初始不绑定合同。 + - 上传成功不返回文件正文;审计不记录 Base64、文件正文或 OSS 凭据。 + - dev OSS 配置在实现前核对;开发/测试与生产共用 bucket 时必须使用独立测试 prefix 或 runId,并按本次对象 key 精确清理。 +- 异常处理:OSS 未确认成功则不插附件记录;OSS 成功后 DB 失败时尽力删除本次新对象,删除失败保留对象 key 告警。不得误删既有附件。 + +#### 功能 2:完整合同创建与提交 + +- 功能描述:新增 `contract.create`,接收 `clientRequestId`、完整合同基本信息和至少一个 `fileId`,一次完成创建和审批提交。 +- 触发条件:该合同全部附件已上传成功,且调用方已收齐全部 `fileIds`。 +- 必填信息:`contractType`、`customerAgentId`、`propertyId`、`fileIds`、`startDate`、`endDate`、`clientRequestId`。 +- 可选信息:`contractName`、`amount`、`contact`、`expireRemind`、`remindDays`;空白名称归一为 null,不用空字符串绕过 schema。 +- 业务规则: + - 不增加物业行级数据权限;仍校验物业存在、未软删、编号可用,客户所属公司为有效总部/分公司。 + - 从物业及销售反解客户、销售和合同所属公司快照;销售或销售所属公司缺失时拒绝。 + - `expireRemind` 默认 1,`remindDays` 默认 30;允许历史日期,结束日期不得早于开始日期。 + - 附件必须存在、未软删、未绑定、由当前用户上传且列表不重复;条件更新每条必须影响 1 行。 + - 完整性以调用方声明的 `fileIds` 集合为边界:服务端保证该集合内全部绑定,不负责识别调用方遗漏且未声明的文件。 + - 合同编号沿用“物业编号 + C + 三位流水”,唯一冲突时以独立完整事务最多尝试 3 次。 + - 在 m2 单事务内完成合同、全部附件绑定、创建流程记录、当前待办和抄送;m0 只读,不做跨库分布式事务。 + - 创建提交成功即返回 id、编号、状态、附件、幂等键和 warnings,不等待审批通过。 +- 异常处理:任一校验或事务写入失败则整体回滚,不留合同、部分附件绑定或流程残留;已上传附件保持未绑定,可修正后重用。 + +#### 功能 3:批量逐份编排 + +- 功能描述:由调用方/Agent 循环调用两个原子工具,不新增 `contract.batch.create`,不设置异步批任务。 +- 业务规则:每份合同独立闭环;任一附件失败则不调用该合同创建;其他合同继续;建议最多 3 份合同并行,单份合同内文件串行。 +- 对账:成功项记录合同 id/编号,失败项记录 UPLOAD/CREATE 阶段、错误码和可重试性;批量结束输出未使用附件清单,自动清理另立需求。 +- 异常处理:单份失败只重试该份;不得因超时更换幂等键。 + +#### 功能 4:上传与创建持久化幂等 + +- 功能描述:`contract_file` 增加 `client_upload_id/request_hash`,`contract_new` 增加 `client_request_id/request_hash`,分别建立当前用户范围内的唯一索引。 +- 业务规则:键长 1~64,仅允许字母、数字、点、下划线、冒号和连字符;requestHash 使用 SHA-256。 +- 上传哈希:规范化原文件名加内容摘要;创建哈希:全部规范化业务字段加排序后的 fileIds。 +- 异常处理:同键同内容返回原资源且不重复写 OSS、合同、流程或通知;同键不同内容返回 `IDEMPOTENCY_CONFLICT`;唯一冲突后先回滚再查询分流,不能靠解析数据库错误文本判断。 + +#### 功能 5:审批与提交后通知 + +- 功能描述:按物业销售所属公司匹配老工作流,保持无配置、空层级、部门审批和层级审批的业务分支。 +- 业务规则:待审时创建待办/抄送记录,Redis 消息仅在数据库提交后发送;直接正常时不生成待办或审批消息。 +- 配置异常:所需岗位字典缺失、有效工作流多条或层级损坏时拒绝,不以 `limit 1` 或直接生效掩盖异常。 +- 异常处理:提交后的通知失败逐条记录,工具仍返回创建成功并附 warning;幂等回放不补发消息。通知必达 outbox 不在本期。 + +#### 功能 6:既有模型与 schema 兼容 + +- 功能描述:补 `ContractNew.contractType/renewed`、`ContractFile.ossBucket/ossFolder`、工作流实体和 Mapper;既有合同列表/详情补合同类型回读。 +- schema:正式处理合同名称可空,并为两张既有表增加可空幂等列和唯一索引;m2 DDL 不混入 svc Flyway。 +- 兼容要求:实现前先只读核对 dev/prod 实际表结构;老系统插入时新增幂等列保持 null;先库后代码,回归老系统新增合同。 +- 回滚:代码回滚保留 additive 列,不自动 DROP;已创建正式业务数据不自动删除。 + +#### 非目标 + +本期不做 OCR/日期识别、合同草稿、审批办理、修改再提交、续签、终止、删除、工作流配置、异步批任务、通知 outbox、自动孤儿附件清理、定时任务迁移或前端页面。 + +## 4. 交互设计 + +### 4.1 用户流程 + +```text +为每份合同准备基本信息、稳定 clientRequestId + → 为每个文件准备稳定 clientUploadId + → 逐个调用 contract.file.upload + → 任一失败:记录该合同 UPLOAD 失败,不调用创建;继续其他合同 + → 全部成功:收齐 fileIds + → 调用 contract.create + → 校验/事务失败:记录 CREATE 失败,修正后用原幂等键重试 + → 提交成功:返回合同 id、编号、实际状态及 warnings + → 按 clientRequestId 汇总批量结果和未使用附件清单 +``` + +超时恢复:上传超时以相同 `clientUploadId`、文件名和内容重试;创建超时以相同 `clientRequestId` 和相同规范化参数重试。同键不同内容不得覆盖第一次结果。 + +### 4.2 界面原型 + +本需求为纯后端 MCP 工具、数据库和 OSS 能力,没有本系统页面、表单、列表、可视状态或跨页面流程,HTML 原型不适用。调用方的批量编排属于工具调用流程,已在 4.1 描述,不构成本系统 UI。 + +- 讨论记录:`docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md` 的“HTML 原型记录”。 +- 用户确认:方案确认问题明确为“两个原子工具逐份批量补录”,用户已选择“方案确认通过(推荐)”;最终 PRD 与无 UI 跳过结论的联合确认待取得,未确认前不提交评审。 + +## 5. 技术要求 + +### 5.1 性能要求 + +- 文件大小:单文件解码后最大 20 MiB;20 MiB 文件 Base64 编码约 26.67 MiB,另有 JSON 开销。 +- 调用粒度:每次上传仅一个文件;建议批量最多 3 份合同并行,单份合同内文件串行,避免请求体和内存叠加。 +- 超时:实现前必须核对 MCP 网关请求体上限和超时配置;dev 使用恰好 20 MiB 文件完成真实调用,记录上传及创建耗时,不允许仅以小文件代替边界验收。 +- dev OSS 隔离:实现前核对 dev 实际 OSS 配置;若与生产共用 bucket,则必须使用 dev 专用 prefix/runId,验收结束时按对象 key 精确清理,不触碰既有对象。 +- 资源释放:实现阶段必须覆盖流/连接关闭及大对象释放;具体实现约束由开发设计承接,不在 PRD 预设未经验证的响应时延 SLA。 + +### 5.2 安全要求 + +- 两个工具均要求用户委托 Token 和工具 scope;服务身份 Token 不允许代传代建。 +- 按拍板不增加物业行级权限;附件仍校验当前上传人和原子绑定,防止跨用户串用及并发双绑。 +- 生产只绑研发专用 scope 6,不绑业务 scope 1/2/3/5;已有合同查询权限不自动获得写权限。 +- 文件校验同时看扩展名、Base64、文件头和实际字节数;对象 key 随机,不覆盖既有对象。 +- OSS 凭据通过环境配置/密钥管理注入;日志、工具返回和审计不得包含凭据、Base64 或文件正文。 +- 已提交合同不自动撤销;回滚只停用工具和回滚服务版本,业务数据逐笔审计处理。 + +### 5.3 兼容性要求 + +- 浏览器/设备:不适用,无前端改动。 +- 数据兼容:新增幂等列可空,历史行及老系统新插入行可为 null;合同名称可空须与二期口径一致。 +- 审批兼容:沿用老系统按公司匹配工作流、待办/抄送记录和消息字段;配置损坏改为明确拒绝。 +- 查询兼容:既有 `contract.list/detail.query` 只新增返回字段,不改变既有筛选和权限。 +- 发布兼容:先执行并验证 additive DDL,再发布工具;生产只做只读核验,不做上传或创建写冒烟。 + +## 6. 上线计划 + +### 6.1 里程碑 + +| 阶段 | 内容 | 完成标准 | +|---|---|---| +| 需求评审 | 讨论记录、PRD、缺陷收敛和最终确认 | REQ-20261118-0011 审批通过;此前不开始开发或执行 DDL | +| 开发设计 | 核对真实代码、dev/prod schema、网关限制和 OSS 配置 | 设计约束与现状一致,差异回到需求确认 | +| 数据库准备 | 名称可空、幂等列和唯一索引 | dev/prod 只读核对后按环境正式变更;老系统新增回归通过 | +| 工具实现 | 实体、Mapper、OSS、上传、创建和查询回读 | 单元/集成测试覆盖本 PRD 验收项 | +| dev 验证 | 本机测试环境真实 MCP 写冒烟 | 全量构建通过;20 MiB、批量、回滚、幂等和审批场景通过;dev OSS 使用独立 prefix/runId 并精确清理 | +| 发布 | push main、remote-deploy、绑定 scope 6 | 发布记录可追溯,工具仅研发专用 scope 可用 | +| 生产核验 | tools/list、未授权、无写入参数错误和查询回读 | 只读核验通过,无生产合同/附件写入 | + +### 6.2 灰度策略 + +先在本机 dev profile 使用隔离的 dev 数据库、专用测试物业/用户和一次性附件验证;写工具全部冒烟及数据恢复完成后才允许部署生产。生产仅绑定研发专用 scope 6,不开放业务范围。出现异常先解绑/停用两个工具并回滚服务版本,保留 additive schema 和正式业务数据。 + +## 7. 验收标准 + +### AC1:20 MiB 文件边界与内容校验 + +**目标**:合法且恰好 20 MiB 的文件可以上传,超限或伪造内容被明确拒绝。 + +**VP-Data(前置测试数据)**: +- 环境:localhost(dev profile、隔离 dev 数据库);OSS 使用 dev 专用 prefix/runId(实现前核对配置,若与生产共用 bucket 则强制隔离前缀)。 +- 数据:测试用户 Token/scope;恰好 20 MiB 的合法 PDF 测试文件、20 MiB + 1 byte 文件、空文件、错误 Base64、扩展名与文件头不符文件;每个用例独立 clientUploadId。 +- 建数据方式:本地生成测试文件,仅通过 MCP `contract.file.upload` 上传,不直接插附件记录。 + +**VP-Steps(验证步骤)**: +1. 对恰好 20 MiB 文件执行真实 MCP 上传并记录 fileId、DB 附件和 OSS 对象。 +2. 分别上传超限、空文件、错误 Base64、非法扩展名和文件头不符文件。 +3. 查询 `contract_file` 和 OSS,核对失败用例没有新增登记对象。 + +**VP-Pass(通过判定)**: +- 恰好 20 MiB 返回 fileId;OSS 实际字节数与内容一致,DB 文件名/bucket/folder/URL 与 OSS 对象一致(不新增 file_size 字段)。 +- 20 MiB + 1 byte 及其他非法用例均返回明确参数错误,无新增附件记录。 +- 仅单元测试或小文件成功而缺少 20 MiB 真实 MCP 证据 = 不通过。 + +### AC2:批量完整性与失败隔离 + +**目标**:每份合同只有基本信息和全部附件就绪后才创建,单份失败不影响其他合同。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:3 份测试合同 A/B/C 及各自独立幂等键;A 文件和参数合法,B 一个文件超限,C 附件合法但缺少必填基本信息。 +- 建数据方式:调用方按两个 MCP 原子工具逐份编排,不直接写合同表。 + +**VP-Steps(验证步骤)**: +1. 对 A 上传全部附件后创建;B 上传至超限失败即停止该份;C 收齐附件后提交非法创建参数。 +2. 继续处理后续合同,模拟批量调用方汇总结果。 +3. 查询三份的 `contract_new/contract_file/contract_process` 及批量结果。 + +**VP-Pass(通过判定)**: +- A 只有 1 份完整合同且声明提交的 `fileIds` 全部绑定;B、C 均无合同和流程记录。 +- B 的上传失败不阻塞 A/C 的独立处理;C 的附件保持未绑定且可修正后重用。 +- 出现无附件正式合同、声明集合内附件部分绑定或整批因单份失败中止 = 不通过;调用方遗漏且未声明的文件不属于服务端可发现范围。 + +### AC3:创建事务回滚与通知边界 + +**目标**:任一创建写入失败均不产生半成品,通知只在数据库提交后发生。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:合法测试合同及未绑定附件;通过测试故障注入分别模拟合同、附件条件更新、流程记录失败,以及提交后的 Redis 通知失败。 +- 建数据方式:集成测试故障注入加真实 MCP 调用;不用手工删表制造失败。 + +**VP-Steps(验证步骤)**: +1. 分别触发三类事务内失败并查询合同、附件和流程。 +2. 检查失败期间 Redis 没有新增审批/抄送消息。 +3. 单独触发 commit 后通知失败,检查工具返回和数据库结果。 + +**VP-Pass(通过判定)**: +- 事务内失败时合同和流程均回滚,附件仍未绑定,Redis 无消息。 +- commit 后通知失败返回创建成功、合同 id 和 warning,不返回“未创建”。 +- 任一失败留下部分附件绑定或合同 = 不通过。 + +### AC4:上传与创建幂等及并发 + +**目标**:响应丢失后的同键重试不重复,误用同键不同内容能被发现。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:同一测试用户、固定上传/创建键、合法文件及合同参数;创建幂等涉及通知的用例必须使用有层级待审工作流;另准备同键不同文件/参数用例和不同用户同键用例。 +- 建数据方式:通过 MCP 串行及并发调用;唯一索引已通过正式 DDL 创建。 + +**VP-Steps(验证步骤)**: +1. 对上传和创建分别模拟首次成功但客户端未收到响应,再用同键同内容重试。 +2. 并发发送多个相同上传/创建请求,核对 OSS、合同、附件、流程和通知数量。 +3. 使用同键不同内容重试,再用不同用户相同键调用。 + +**VP-Pass(通过判定)**: +- 同用户同键同内容串行/并发均返回原资源,只有 1 个登记附件或 1 份合同、1 套流程;待审场景首次提交只发送 1 次通知,回放不补发(直接正常场景无审批通知,由 AC5 验证)。 +- 同键不同内容返回 `IDEMPOTENCY_CONFLICT`;不同用户同键互不影响。 +- 仅依赖前置查询、没有唯一索引或并发产生重复资源 = 不通过。 + +### AC5:审批状态与异常配置 + +**目标**:创建提交后的状态符合老规则,异常配置不能静默跳过审批。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:专用公司及工作流,覆盖无配置、有层级待审、部门审批、空层级、所需岗位字典缺失、多有效配置和层级损坏;测试后恢复原配置。 +- 建数据方式:dev 测试夹具准备配置,合同仅通过 MCP 创建。 + +**VP-Steps(验证步骤)**: +1. 分别创建各场景合同并读取返回状态、流程记录和消息。 +2. 对岗位字典缺失、多配置和层级损坏场景尝试创建。 +3. 核对返回时点,不执行审批办理。 + +**VP-Pass(通过判定)**: +- 无配置/空层级等按老规则返回正常;有效待审场景返回待审并生成正确待办/抄送。 +- 异常配置明确拒绝且无合同残留;工具不等待或代做审批通过。 +- 多配置被 `limit 1` 掩盖或字典缺失直接生效 = 不通过。 + +### AC6:默认提醒、历史日期与快照校验 + +**目标**:提醒默认值和关键快照符合拍板,异常销售数据被拒绝。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:有效物业/销售/公司;销售缺失、销售软删、销售所属公司缺失的异常夹具;历史日期用例显式关闭提醒,默认提醒用例选择不会触发即时通知的日期。 +- 建数据方式:dev 测试夹具准备 m0 数据,合同通过 MCP 创建。 + +**VP-Steps(验证步骤)**: +1. 不传 `expireRemind/remindDays` 创建合同,读取提醒字段和快照。 +2. 传入历史日期并显式关闭提醒,确认允许补录。 +3. 对异常销售/公司数据尝试创建。 + +**VP-Pass(通过判定)**: +- 缺省为开启且提前 30 天,提醒时间计算正确;历史日期在显式关闭提醒时可补录。 +- 物业、客户、销售和双公司快照正确;销售或其所属公司缺失均拒绝,无合同残留。 +- 默认提醒被测试数据意外触发即时通知仍未记录和处置 = 不通过。 + +### AC7:schema 与老系统兼容、查询回读 + +**目标**:新增字段不破坏老系统,名称可空和合同类型回读与二期口径一致。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:dev/prod 实际表结构只读核对记录;dev 老系统新增合同用例;包含空名称、contractType 和附件 OSS 字段的 MCP 合同。 +- 建数据方式:正式 additive DDL、老系统测试入口及 MCP 工具分别建数,禁止隐式 DDL。 + +**VP-Steps(验证步骤)**: +1. 核对名称可空、幂等列和唯一索引;使用老系统创建一条合同并检查新增列兼容。 +2. 通过 MCP 创建空名称合同并查询列表/详情。 +3. 检查附件 bucket/folder/URL、contractType/renewed 和既有查询筛选权限。 + +**VP-Pass(通过判定)**: +- 老系统新增回归正常,历史 null 幂等列不冲突;空名称不使用空字符串绕过。 +- 列表/详情能回读合同类型及文案,附件 OSS 字段与实际上传一致,既有权限不变。 +- 未经 dev/prod 只读核对直接执行假设 schema = 不通过。 + +### AC8:全量质量与 dev 冒烟清理 + +**目标**:只有完整验证通过才允许进入发布,且 dev 测试数据与临时对象全部清理。 + +**VP-Data(前置测试数据)**: +- 环境:localhost。 +- 数据:全量构建结果、dev MCP 冒烟记录、dev OSS runId/prefix、数据清理记录、工具 scope 绑定清单。 +- 建数据方式:项目标准构建、测试环境脚本和真实 MCP 调用。 + +**VP-Steps(验证步骤)**: +1. 执行 `./mvnw clean package` 及 dev 全量写冒烟。 +2. 按本次合同 id、附件 id、流程记录和 OSS 对象 key 精确清理,核对恢复原状。 +3. 审批通过且前述 AC 全过后才允许按标准流程发布并绑定研发专用 scope 6。 + +**VP-Pass(通过判定)**: +- 构建和 dev 冒烟全绿,dev 数据与 OSS 对象精确清理完成。 +- 文档登记需求号、提交和部署结果。 +- 审批前开发、测试未全绿即发布、dev 对象未清理或绑业务 scope = 不通过。 + +### AC9:生产只读发布核验 + +**目标**:生产环境只做只读核验,不写合同、附件、流程或通知。 + +**VP-Data(前置测试数据)**: +- 环境:production。 +- 数据:发布记录、工具列表、生产 Token 可用 scope 清单;不准备合同或附件测试数据。 +- 建数据方式:标准发布流程与只读 MCP 调用。 + +**VP-Steps(验证步骤)**: +1. 生产执行 tools/list,确认两个工具可见且仅研发专用 scope 6 可调用。 +2. 执行未授权调用和缺参/非法参数的失败核验。 +3. 用既有 `contract.list.query`/`detail.query` 做只读回读,确认无写入副作用。 + +**VP-Pass(通过判定)**: +- 工具可见且仅研发 scope 6 可用;未授权和非法参数返回明确错误。 +- 生产无合同、附件、流程或通知写入。 +- 生产上传/创建写冒烟、绑定业务 scope 或写入测试数据 = 不通过。 + +## 8. 风险评估 + +| 风险 | 影响 | 概率 | 应对措施 | +|---|---|---|---| +| 20 MiB Base64 超过网关限制或造成堆内存压力 | 高 | 中 | 实现前核对网关;逐文件上传、限制并发;恰好 20 MiB 真实验收并记录耗时 | +| OSS 成功而 DB 失败产生未登记对象 | 中 | 中 | 只删除本次新对象进行补偿;失败告警并保留对象 key | +| 上传后放弃创建产生未绑定附件 | 中 | 高 | 保留供重试;批量结束输出未使用清单;自动清理另立需求 | +| 超时后更换幂等键造成重复资源 | 高 | 中 | 契约要求同键同内容重试;唯一索引兜底;批量按幂等键对账 | +| 创建并发导致合同编号或附件冲突 | 高 | 中 | 编号独立完整事务最多 3 次;附件条件更新影响行数强校验;失败整体回滚 | +| 无审批配置或配置损坏导致状态不符合预期 | 高 | 中 | 老规则分支测试;异常配置 fail fast,不自动生效 | +| 历史日期默认提醒触发即时通知 | 中 | 中 | 默认规则和风险明示;历史补录不希望提醒时显式传 `expireRemind=0` | +| DDL 与老系统不兼容 | 高 | 中 | 先只读核对 dev/prod;可空新增列、先库后代码、老系统新增回归;回滚不 DROP | +| 老系统源码尚未提交,实际生产行为可能不同 | 高 | 中 | 实现前确认目标版本;差异影响产品行为时回到用户确认,不冒充生产调研 | +| 通知失败但合同已提交引发重试 | 中 | 中 | 返回成功加 warning;幂等回放不补发;通知必达另立需求 | + +## 9. 附录 + +- 技术设计:`doc/contract-create-mcp-design.md` +- 需求讨论记录:`docs/product/REQ-20261118-0011-contract-batch-upload-discussion.md` +- 老系统代码依据:`ContractController.java`、`ContractDealService.java`、`ContractTask.java`,具体行号以技术设计调研记录为准。 +- 发布约束:`AGENTS.md` 的“新 MCP 工具上线标准流程”。 +- 当前状态:需求已自审通过;工具已实现,全量 615 个测试通过,本机 dev 真实 MCP 冒烟(含 20 MiB 边界、幂等回放、事务回滚、待审与通知)通过;尚未提交、部署或执行生产 DDL。 diff --git a/xiaoqu-agent-service/pom.xml b/xiaoqu-agent-service/pom.xml index c5612b9..3c0ca9b 100644 --- a/xiaoqu-agent-service/pom.xml +++ b/xiaoqu-agent-service/pom.xml @@ -93,6 +93,14 @@ 7.17.29 + + + com.aliyun.oss + aliyun-sdk-oss + 3.18.5 + + org.projectlombok lombok diff --git a/xiaoqu-agent-service/sql/m2-contract-batch-upload-ddl.sql b/xiaoqu-agent-service/sql/m2-contract-batch-upload-ddl.sql new file mode 100644 index 0000000..a2b8ef5 --- /dev/null +++ b/xiaoqu-agent-service/sql/m2-contract-batch-upload-ddl.sql @@ -0,0 +1,20 @@ +-- REQ-20261118-0011 合同批量补录 MCP 工具 +-- 目标库:m2(老系统业务库 xiaoqu_franchisee / xiaoqu_franchisee_d),不属于 svc Flyway 管理范围。 +-- 执行顺序:dev/prod 只读核对 → 本脚本 → 新工具发布。全部为 additive/放宽变更,代码回滚不 DROP。 +-- 2026-11-18 dev 核对:contract_type/renewed/renew_source_id、oss_bucket/oss_folder 已存在; +-- contract_name 仍为 NOT NULL;client_* 幂等列与唯一索引不存在。 + +-- 1. 合同名称可空(二期口径:名称非必填,禁止用空字符串冒充 null) +ALTER TABLE contract_new MODIFY contract_name VARCHAR(128) NULL; + +-- 2. 创建幂等:同一用户 + client_request_id 唯一;历史行与老系统插入保持 NULL +ALTER TABLE contract_new + ADD COLUMN client_request_id VARCHAR(64) NULL COMMENT 'MCP 创建幂等键(当前用户内唯一)', + ADD COLUMN request_hash CHAR(64) NULL COMMENT 'MCP 创建参数规范化 SHA-256', + ADD UNIQUE KEY uk_contract_client_request (create_id, client_request_id); + +-- 3. 上传幂等:同一用户 + client_upload_id 唯一;历史行与老系统插入保持 NULL +ALTER TABLE contract_file + ADD COLUMN client_upload_id VARCHAR(64) NULL COMMENT 'MCP 上传幂等键(当前用户内唯一)', + ADD COLUMN request_hash CHAR(64) NULL COMMENT 'MCP 上传文件名+内容 SHA-256', + ADD UNIQUE KEY uk_file_client_upload (create_id, client_upload_id); diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/common/AuditService.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/common/AuditService.java index 8ae08a6..ea63449 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/common/AuditService.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/common/AuditService.java @@ -34,7 +34,7 @@ public class AuditService { auditLog.setUserId(ctx == null ? null : ctx.getUserId()); auditLog.setTokenId(ctx == null ? null : ctx.getTokenId()); auditLog.setToolName(toolName); - auditLog.setParamsDigest(truncate(MaskingUtil.maskPhones(paramsJson), PARAMS_DIGEST_MAX)); + auditLog.setParamsDigest(digest(paramsJson)); auditLog.setResultStatus(resultStatus); auditLog.setResultMessage(truncate(MaskingUtil.maskPhones(resultMessage), PARAMS_DIGEST_MAX)); auditLog.setCostMs(costMs); @@ -54,6 +54,21 @@ public class AuditService { return s.length() <= max ? s : s.substring(0, max); } + /** + * 入参摘要:截断 + 手机号脱敏;附件 Base64 只保留键名占位, + * 避免 20 MiB 文件内容进入审计或占用内存(REQ-20261118-0011)。 + */ + private static String digest(String paramsJson) { + if (paramsJson == null) { + return null; + } + int base64Key = paramsJson.indexOf("\"contentBase64\""); + String safe = base64Key >= 0 + ? paramsJson.substring(0, base64Key) + "\"contentBase64\":\"***\"" + : paramsJson; + return truncate(MaskingUtil.maskPhones(safe), PARAMS_DIGEST_MAX); + } + private static HttpServletRequest currentRequest() { if (RequestContextHolder.getRequestAttributes() instanceof ServletRequestAttributes attrs) { return attrs.getRequest(); diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/ContractOssProperties.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/ContractOssProperties.java new file mode 100644 index 0000000..fcce302 --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/ContractOssProperties.java @@ -0,0 +1,33 @@ +package me.iiv.agent.config; + +import lombok.Getter; +import lombok.Setter; +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.stereotype.Component; + +/** + * 合同附件 OSS 配置(REQ-20261118-0011)。 + * 凭据只从环境变量/密钥管理注入,不写入仓库、日志或工具返回。 + */ +@Getter +@Setter +@Component +@ConfigurationProperties(prefix = "app.contract.oss") +public class ContractOssProperties { + + /** OSS endpoint,如 https://oss-cn-beijing.aliyuncs.com */ + private String endpoint; + + private String accessKeyId; + + private String accessKeySecret; + + /** 桶名,默认与老系统 xiaoqu-safefile 一致 */ + private String bucket = "xiaoqu-safefile"; + + /** 目录前缀,必须以 / 结尾;dev 覆盖为独立前缀避免与生产对象混淆 */ + private String folder = "contract/"; + + /** 可选公网地址前缀;为空时按 endpoint + bucket 推导 */ + private String publicUrlPrefix; +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/JacksonLargePayloadConfig.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/JacksonLargePayloadConfig.java new file mode 100644 index 0000000..945184d --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/config/JacksonLargePayloadConfig.java @@ -0,0 +1,47 @@ +package me.iiv.agent.config; + +import me.iiv.agent.mcp.McpJson; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.springframework.ai.util.json.JsonParser; +import org.springframework.beans.factory.config.BeanPostProcessor; +import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +import jakarta.annotation.PostConstruct; + +/** + * 放宽 MCP 大载荷的 Jackson 字符串上限(REQ-20261118-0011)。 + * Spring MVC/MCP SDK 使用容器 ObjectMapper,Spring AI MethodToolCallback 使用 + * JsonParser 的静态 ObjectMapper,两处都必须覆盖,20 MiB Base64 才能进入工具方法。 + */ +@Configuration +public class JacksonLargePayloadConfig { + + @Bean + public Jackson2ObjectMapperBuilderCustomizer mcpLargePayloadJacksonCustomizer() { + return builder -> builder.postConfigurer(McpJson::applyReadConstraints); + } + + /** + * 兜底保证所有 ObjectMapper bean(包括 MCP SDK 注入的容器 mapper)都放宽上限, + * 不依赖 Jackson2ObjectMapperBuilder 的 postConfigurer 装配时序。 + */ + @Bean + static BeanPostProcessor objectMapperReadConstraintsPostProcessor() { + return new BeanPostProcessor() { + @Override + public Object postProcessAfterInitialization(Object bean, String beanName) { + if (bean instanceof ObjectMapper mapper) { + McpJson.applyReadConstraints(mapper); + } + return bean; + } + }; + } + + @PostConstruct + void raiseSpringAiJsonParserLimit() { + McpJson.applyReadConstraints(JsonParser.getObjectMapper()); + } +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFile.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFile.java index 773c556..dd3d680 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFile.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFile.java @@ -64,8 +64,28 @@ public class ContractFile implements Serializable { */ private String fileName; + /** + * OSS 桶名 + */ + private String ossBucket; + + /** + * OSS 目录(含尾部斜杠) + */ + private String ossFolder; + /** * 文件访问地址 */ private String fileUrl; + + /** + * MCP 上传幂等键(当前用户内唯一,历史/老系统行为 NULL) + */ + private String clientUploadId; + + /** + * MCP 上传文件名+内容 SHA-256 + */ + private String requestHash; } diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java new file mode 100644 index 0000000..75a9250 --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java @@ -0,0 +1,46 @@ +package me.iiv.agent.entity.m2; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Getter; +import lombok.Setter; +import lombok.ToString; + +import java.io.Serializable; +import java.util.Date; + +/** + * 合同工作流设置(contract_flow_set,m2 老系统业务库)。 + */ +@Getter +@Setter +@ToString +@TableName("contract_flow_set") +public class ContractFlowSet implements Serializable { + + private static final long serialVersionUID = 1L; + + @TableId(value = "id", type = IdType.AUTO) + private Long id; + + private Long createId; + + private Date createTime; + + private Long modifyId; + + private Date modifyTime; + + private Integer softDelete; + + /** + * 所属公司 id(合同审批流按 contract_new.contract_agent_id 匹配) + */ + private Long agentId; + + /** + * 部门内审批开关0:关;1:开 + */ + private Integer departAuditSwitch; +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java new file mode 100644 index 0000000..c92903a --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java @@ -0,0 +1,55 @@ +package me.iiv.agent.entity.m2; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Getter; +import lombok.Setter; +import lombok.ToString; + +import java.io.Serializable; +import java.util.Date; + +/** + * 合同工作流人员(contract_flow_user,m2 老系统业务库)。 + */ +@Getter +@Setter +@ToString +@TableName("contract_flow_user") +public class ContractFlowUser implements Serializable { + + private static final long serialVersionUID = 1L; + + @TableId(value = "id", type = IdType.AUTO) + private Long id; + + private Long createId; + + private Date createTime; + + private Long modifyId; + + private Date modifyTime; + + private Integer softDelete; + + /** + * 关联 contract_flow_set.id + */ + private Long flowSetId; + + /** + * 人员类型0:审核人;1:抄送人 + */ + private Integer userType; + + /** + * 审核层级 + */ + private Integer auditLevel; + + private Long userId; + + private String userName; +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractNew.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractNew.java index a098098..3cf9e75 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractNew.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/m2/ContractNew.java @@ -65,6 +65,11 @@ public class ContractNew implements Serializable { */ private String contractName; + /** + * 合同类型0:租赁;1:售卖;2:其他(二期新增) + */ + private Integer contractType; + /** * 合同所属公司(=物业所属销售所属公司,审批流按此公司匹配) */ @@ -165,4 +170,19 @@ public class ContractNew implements Serializable { * 2026-10-15 核对:表实际存在 renew_source_id 列,此前遗漏导致续约关联未进入同步报文。 */ private Long renewSourceId; + + /** + * 已被续签标记0:未被续签;1:已被续签(二期新增) + */ + private Integer renewed; + + /** + * MCP 创建幂等键(当前用户内唯一,历史/老系统行为 NULL) + */ + private String clientRequestId; + + /** + * MCP 创建参数规范化 SHA-256 + */ + private String requestHash; } diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java new file mode 100644 index 0000000..4e729bd --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java @@ -0,0 +1,10 @@ +package me.iiv.agent.mapper.m2; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import me.iiv.agent.entity.m2.ContractFlowSet; + +/** + * 合同工作流设置 Mapper。 + */ +public interface ContractFlowSetMapper extends BaseMapper { +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java new file mode 100644 index 0000000..2cb8fa4 --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java @@ -0,0 +1,10 @@ +package me.iiv.agent.mapper.m2; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import me.iiv.agent.entity.m2.ContractFlowUser; + +/** + * 合同工作流人员 Mapper。 + */ +public interface ContractFlowUserMapper extends BaseMapper { +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/GuardedToolCallback.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/GuardedToolCallback.java index d5d1ff7..84ef68a 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/GuardedToolCallback.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/GuardedToolCallback.java @@ -36,8 +36,7 @@ public class GuardedToolCallback implements ToolCallback { private final ToolGuard toolGuard; private final AuditService auditService; private final RateLimitService rateLimitService; - private final com.fasterxml.jackson.databind.ObjectMapper objectMapper = - new com.fasterxml.jackson.databind.ObjectMapper(); + private final com.fasterxml.jackson.databind.ObjectMapper objectMapper = McpJson.newMapper(); public GuardedToolCallback(ToolCallback delegate, ToolGuard toolGuard, AuditService auditService, RateLimitService rateLimitService) { diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpErrorCode.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpErrorCode.java index 43c0d18..3ef064d 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpErrorCode.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpErrorCode.java @@ -31,6 +31,12 @@ public enum McpErrorCode { /** 工具入参格式、数量或取值不符合公开契约 */ INVALID_ARGUMENT, + /** 同一用户复用了相同幂等键,但请求内容与第一次不同 */ + IDEMPOTENCY_CONFLICT, + + /** 合同附件已绑定、非当前用户上传或并发绑定导致状态变化 */ + ATTACHMENT_NOT_BINDABLE, + /** 数据处理过程中发现不一致或未预期异常(兜底码,内部细节只落服务端日志) */ DATA_INTEGRITY_ERROR } diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpJson.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpJson.java new file mode 100644 index 0000000..978b02c --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpJson.java @@ -0,0 +1,32 @@ +package me.iiv.agent.mcp; + +import com.fasterxml.jackson.core.StreamReadConstraints; +import com.fasterxml.jackson.databind.ObjectMapper; + +/** + * MCP 大载荷 JSON 约束(REQ-20261118-0011)。 + * 合同附件单文件 20 MiB,Base64 后约 28 MB 字符,超过 Jackson 2.15+ 默认 + * maxStringLength=20,000,000 的限制。MCP SDK、Spring AI 工具参数解析和本服务的 + * 中间层 ObjectMapper 都必须放宽到 32 MiB,否则 20 MiB 文件在到达工具前就会被拒绝。 + */ +public final class McpJson { + + /** 32 MiB,覆盖 20 MiB 原始文件的标准 Base64(约 27.96 MB 字符)并留出余量。 */ + public static final int MAX_STRING_LENGTH = 32 * 1024 * 1024; + + private McpJson() { + } + + public static ObjectMapper newMapper() { + ObjectMapper mapper = new ObjectMapper(); + applyReadConstraints(mapper); + return mapper; + } + + public static void applyReadConstraints(ObjectMapper mapper) { + StreamReadConstraints constraints = StreamReadConstraints.builder() + .maxStringLength(MAX_STRING_LENGTH) + .build(); + mapper.getFactory().setStreamReadConstraints(constraints); + } +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpToolCallEnvelopeFilter.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpToolCallEnvelopeFilter.java index 7dfac63..94971cd 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpToolCallEnvelopeFilter.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/McpToolCallEnvelopeFilter.java @@ -28,7 +28,7 @@ import java.nio.charset.StandardCharsets; @Order(15) public class McpToolCallEnvelopeFilter extends OncePerRequestFilter { - private final ObjectMapper objectMapper = new ObjectMapper(); + private final ObjectMapper objectMapper = McpJson.newMapper(); @Override protected boolean shouldNotFilter(HttpServletRequest request) { diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/ToolCallEnvelopeRewriter.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/ToolCallEnvelopeRewriter.java index edf09c4..75592c8 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/ToolCallEnvelopeRewriter.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/ToolCallEnvelopeRewriter.java @@ -15,7 +15,7 @@ import com.fasterxml.jackson.databind.node.ObjectNode; */ public final class ToolCallEnvelopeRewriter { - private static final ObjectMapper MAPPER = new ObjectMapper(); + private static final ObjectMapper MAPPER = McpJson.newMapper(); private ToolCallEnvelopeRewriter() { } diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java new file mode 100644 index 0000000..03a9342 --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java @@ -0,0 +1,758 @@ +package me.iiv.agent.mcp.tool; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import me.iiv.agent.entity.m0.Agent; +import me.iiv.agent.entity.m0.Properyt; +import me.iiv.agent.entity.m0.User; +import me.iiv.agent.entity.m2.ContractFile; +import me.iiv.agent.entity.m2.ContractFlowSet; +import me.iiv.agent.entity.m2.ContractFlowUser; +import me.iiv.agent.entity.m2.ContractNew; +import me.iiv.agent.entity.m2.ContractProcess; +import me.iiv.agent.mapper.m0.AgentMapper; +import me.iiv.agent.mapper.m0.ProperytMapper; +import me.iiv.agent.mapper.m0.UserMapper; +import me.iiv.agent.mapper.m2.ContractFileMapper; +import me.iiv.agent.mapper.m2.ContractFlowSetMapper; +import me.iiv.agent.mapper.m2.ContractFlowUserMapper; +import me.iiv.agent.mapper.m2.ContractNewMapper; +import me.iiv.agent.mapper.m2.ContractProcessMapper; +import me.iiv.agent.mcp.McpCallContextHolder; +import me.iiv.agent.mcp.McpErrorCode; +import me.iiv.agent.mcp.ToolCallException; +import me.iiv.agent.mcp.ToolObject; +import me.iiv.agent.mcp.XqTool; +import me.iiv.agent.security.AuthContextHolder; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.ai.tool.annotation.Tool; +import org.springframework.ai.tool.annotation.ToolParam; +import org.springframework.beans.factory.annotation.Qualifier; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.data.redis.core.StringRedisTemplate; +import org.springframework.stereotype.Component; +import org.springframework.transaction.PlatformTransactionManager; +import org.springframework.transaction.support.TransactionSynchronization; +import org.springframework.transaction.support.TransactionSynchronizationManager; +import org.springframework.transaction.support.TransactionTemplate; +import org.springframework.util.StringUtils; + +import java.math.BigDecimal; +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.time.LocalDate; +import java.time.ZoneId; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.Calendar; +import java.util.Date; +import java.util.HashSet; +import java.util.LinkedHashMap; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.regex.Pattern; +import java.util.stream.Collectors; + +/** + * 合同创建工具(REQ-20261118-0011,设计文档 doc/contract-create-mcp-design.md)。 + * 对齐老系统 ContractController#add + ContractDealService#add: + * 校验并反解物业/销售快照 → 生成合同编号 → m2 单事务写合同、绑定全部附件、写创建记录并提交审批。 + * 提交成功即返回,不等待审批通过;通知在事务提交后推送,失败只附 warning。 + * 必须用户身份 Token;零行级权限,门禁靠「研发专用」scope;创建幂等键为 clientRequestId。 + */ +@Component +public class ContractCreateAdminTools implements ToolObject { + + private static final Logger log = LoggerFactory.getLogger(ContractCreateAdminTools.class); + + private static final Pattern CLIENT_REQUEST_ID = Pattern.compile("^[A-Za-z0-9._:-]{1,64}$"); + private static final Set CONTRACT_TYPES = Set.of(0, 1, 2); + private static final Set CUSTOMER_AGENT_CHANNELS = Set.of("Z", "F"); + private static final Map STATUS_TEXT = Map.of( + 0, "待审", 1, "驳回", 2, "正常", 3, "过期", 4, "终止"); + + private static final int STATUS_PENDING = 0; + private static final int STATUS_NORMAL = 2; + private static final int MAX_NAME_LENGTH = 128; + private static final int MAX_CONTACT_LENGTH = 64; + private static final int MAX_ATTEMPTS = 3; + private static final int MSG_TODO = 12; + private static final int MSG_CC = 13; + private static final String MSG_QUEUE = "InvoiceMessageNotice"; + private static final String DICT_KEY = "Dictionary"; + private static final String DEPT_LEADER_POST_FIELD = "authDeptPostId"; + + private static final ObjectMapper JSON = new ObjectMapper(); + + final ContractNewMapper contractNewMapper; + final ContractFileMapper contractFileMapper; + final ContractProcessMapper contractProcessMapper; + final ContractFlowSetMapper contractFlowSetMapper; + final ContractFlowUserMapper contractFlowUserMapper; + final ProperytMapper properytMapper; + final UserMapper userMapper; + final AgentMapper agentMapper; + final StringRedisTemplate redisTemplate; + final TransactionTemplate m2Tx; + + public ContractCreateAdminTools(ContractNewMapper contractNewMapper, + ContractFileMapper contractFileMapper, + ContractProcessMapper contractProcessMapper, + ContractFlowSetMapper contractFlowSetMapper, + ContractFlowUserMapper contractFlowUserMapper, + ProperytMapper properytMapper, + UserMapper userMapper, + AgentMapper agentMapper, + StringRedisTemplate redisTemplate, + @Qualifier("m2TransactionManager") PlatformTransactionManager m2TransactionManager) { + this.contractNewMapper = contractNewMapper; + this.contractFileMapper = contractFileMapper; + this.contractProcessMapper = contractProcessMapper; + this.contractFlowSetMapper = contractFlowSetMapper; + this.contractFlowUserMapper = contractFlowUserMapper; + this.properytMapper = properytMapper; + this.userMapper = userMapper; + this.agentMapper = agentMapper; + this.redisTemplate = redisTemplate; + this.m2Tx = new TransactionTemplate(m2TransactionManager); + } + + @XqTool(category = "admin", kind = "write") + @Tool(name = "contract.create", description = "【写操作·合同批量补录】用完整基本信息和已上传附件创建并提交一份合同。" + + "必须先通过 contract.file.upload 上传该合同全部附件,fileIds 至少 1 个且不得重复;" + + "服务端在同一 m2 事务内创建合同、绑定全部附件、写创建记录并按合同所属公司匹配老审批流," + + "提交成功即返回合同 id/编号/状态,不等待审批通过,也不代做审核、续签或终止。" + + "不增加物业行级权限:只校验物业有效、编号可用、客户所属公司为有效总部/分公司、销售及销售所属公司存在;" + + "销售或销售所属公司缺失时拒绝。expireRemind 默认开启(1),remindDays 默认 30,允许历史日期。" + + "clientRequestId 为当前用户内稳定的创建幂等键:同键同参数重试返回原合同(idempotentReplay=true,不重复写流程/通知)," + + "同键不同参数返回 IDEMPOTENCY_CONFLICT。提交后通知失败仍返回成功并附 warnings。" + + "必须用户身份 Token;访问控制靠 scope 绑定。") + public Map contractCreate( + @ToolParam(description = "当前用户内稳定的创建幂等键,1~64 位字母/数字/点/下划线/冒号/连字符;一份逻辑合同一个键") String clientRequestId, + @ToolParam(description = "合同类型:0=租赁 1=售卖 2=其他") Integer contractType, + @ToolParam(description = "客户所属公司 id,必须是有效、未软删的总部/分公司(channel_no 为 Z 或 F)") Long customerAgentId, + @ToolParam(description = "所属物业 id;只校验存在、未软删和编号可用,不做行级数据权限过滤") Long propertyId, + @ToolParam(description = "已上传附件 id 列表,至少 1 个、不得重复,且须为当前用户上传的未绑定附件") List fileIds, + @ToolParam(required = false, description = "合同名称,最长 128 字符;空白按 null 保存") String contractName, + @ToolParam(required = false, description = "合同金额(元),非负,最多 2 位小数,decimal(14,2)") BigDecimal amount, + @ToolParam(required = false, description = "联系人,最长 64 字符;空白按 null 保存") String contact, + @ToolParam(description = "合同开始日期,严格 yyyy-MM-dd;允许早于今天(补录历史合同)") String startDate, + @ToolParam(description = "合同结束日期,严格 yyyy-MM-dd,不得早于开始日期") String endDate, + @ToolParam(required = false, description = "到期提醒开关:0=关 1=开;缺省 1(开启)") Integer expireRemind, + @ToolParam(required = false, description = "到期提醒天数,正整数;缺省 30") Integer remindDays) { + User caller = AuthContextHolder.get().getUser(); + if (caller == null) { + throw new ToolCallException(McpErrorCode.PERMISSION_DENIED, + "该工具要求用户身份 Token 调用(创建人需可追溯),服务身份 Token 不可用"); + } + CreateCommand command = validate(clientRequestId, contractType, customerAgentId, propertyId, fileIds, + contractName, amount, contact, startDate, endDate, expireRemind, remindDays); + String requestHash = requestHash(command); + + ContractNew existing = findByRequestKey(caller.getId(), command.clientRequestId); + if (existing != null) { + return replayOrConflict(existing, requestHash); + } + + List warnings = new ArrayList<>(); + for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) { + try { + CreateOutcome outcome = m2Tx.execute(status -> doCreate(command, caller, warnings)); + return success(outcome, command.clientRequestId, warnings, false); + } catch (DuplicateKeyException e) { + ContractNew concurrent = findByRequestKey(caller.getId(), command.clientRequestId); + if (concurrent != null) { + return replayOrConflict(concurrent, requestHash); + } + log.warn("合同编号冲突重试 {}/{} propertyId={}", attempt, MAX_ATTEMPTS, command.propertyId); + } + } + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "合同编号生成冲突,已重试 " + MAX_ATTEMPTS + " 次仍未成功,请稍后重试"); + } + + // ------------------------------------------------------------------ 参数校验 + + private CreateCommand validate(String clientRequestId, Integer contractType, Long customerAgentId, + Long propertyId, List fileIds, String contractName, BigDecimal amount, + String contact, String startDate, String endDate, + Integer expireRemind, Integer remindDays) { + if (!StringUtils.hasText(clientRequestId) || !CLIENT_REQUEST_ID.matcher(clientRequestId).matches()) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "clientRequestId 必须为 1~64 位字母、数字、点、下划线、冒号或连字符"); + } + if (contractType == null || !CONTRACT_TYPES.contains(contractType)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "contractType 必须为 0=租赁、1=售卖、2=其他"); + } + if (customerAgentId == null) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "customerAgentId 不能为空"); + } + if (propertyId == null) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "propertyId 不能为空"); + } + if (fileIds == null || fileIds.isEmpty()) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "fileIds 至少需要 1 个附件"); + } + Set uniqueFileIds = new LinkedHashSet<>(); + for (Long fileId : fileIds) { + if (fileId == null || fileId <= 0) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "fileIds 不能包含空值或非正数"); + } + if (!uniqueFileIds.add(fileId)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "fileIds 不得重复: " + fileId); + } + } + List orderedFileIds = new ArrayList<>(uniqueFileIds); + orderedFileIds.sort(Long::compareTo); + String name = normalizeText(contractName, MAX_NAME_LENGTH, "contractName"); + String contactText = normalizeText(contact, MAX_CONTACT_LENGTH, "contact"); + if (amount != null) { + if (amount.signum() < 0) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "amount 不能为负数"); + } + BigDecimal normalized = amount.stripTrailingZeros(); + if (normalized.scale() > 2) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "amount 最多 2 位小数"); + } + if (normalized.precision() - normalized.scale() > 12) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "amount 超出 decimal(14,2) 范围"); + } + } + Date start = parseDate(startDate, "startDate"); + Date end = parseDate(endDate, "endDate"); + if (end.before(start)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "合同结束日期不能早于开始日期"); + } + int remindSwitch = expireRemind == null ? 1 : expireRemind; + if (remindSwitch != 0 && remindSwitch != 1) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "expireRemind 必须为 0=关 或 1=开"); + } + int remindDayCount = remindDays == null ? 30 : remindDays; + if (remindDayCount <= 0) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "remindDays 必须为正整数"); + } + Date remindTime = remindSwitch == 1 ? buildRemindTime(end, remindDayCount) : null; + return new CreateCommand(clientRequestId, contractType, customerAgentId, propertyId, + orderedFileIds, name, amount, contactText, start, end, + remindSwitch, remindDayCount, remindTime); + } + + private static String normalizeText(String value, int maxLength, String field) { + if (value == null) { + return null; + } + String trimmed = value.trim(); + if (trimmed.isEmpty()) { + return null; + } + if (trimmed.length() > maxLength) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, field + " 不能超过 " + maxLength + " 字符"); + } + return trimmed; + } + + private static Date parseDate(String value, String field) { + if (!StringUtils.hasText(value)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, field + " 不能为空"); + } + try { + LocalDate date = LocalDate.parse(value.trim()); + return Date.from(date.atStartOfDay(ZoneId.systemDefault()).toInstant()); + } catch (DateTimeParseException e) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + field + " 必须是合法的 yyyy-MM-dd 日期: " + value); + } + } + + private static Date buildRemindTime(Date endDate, int remindDays) { + Calendar calendar = Calendar.getInstance(); + calendar.setTime(endDate); + calendar.add(Calendar.DAY_OF_MONTH, -remindDays); + calendar.set(Calendar.HOUR_OF_DAY, 9); + calendar.set(Calendar.MINUTE, 30); + calendar.set(Calendar.SECOND, 0); + calendar.set(Calendar.MILLISECOND, 0); + return calendar.getTime(); + } + + private static String requestHash(CreateCommand c) { + String canonical = c.contractType + "\n" + + c.customerAgentId + "\n" + + c.propertyId + "\n" + + c.fileIds.stream().map(String::valueOf).collect(Collectors.joining(",")) + "\n" + + nullSafe(c.contractName) + "\n" + + (c.amount == null ? "" : c.amount.stripTrailingZeros().toPlainString()) + "\n" + + nullSafe(c.contact) + "\n" + + isoDate(c.startDate) + "\n" + + isoDate(c.endDate) + "\n" + + c.expireRemind + "\n" + + c.remindDays; + return sha256Hex(canonical); + } + + private static String nullSafe(String value) { + return value == null ? "" : value; + } + + private static String isoDate(Date date) { + return date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate().toString(); + } + + // ------------------------------------------------------------------ 事务内创建 + + private CreateOutcome doCreate(CreateCommand command, User caller, List warnings) { + Date now = new Date(); + + Properyt property = properytMapper.selectById(command.propertyId); + if (property == null || isDeleted(property.getSoftDelete())) { + throw new ToolCallException(McpErrorCode.NOT_FOUND_OR_FORBIDDEN, + "所属物业不存在: propertyId=" + command.propertyId); + } + String customerNo = property.getSerialnumber(); + if (!StringUtils.hasText(customerNo) || "null".equalsIgnoreCase(customerNo.trim())) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "所选物业未配置物业编号,无法生成合同编号: propertyId=" + command.propertyId); + } + customerNo = customerNo.trim(); + + Agent customerAgent = agentMapper.selectById(command.customerAgentId); + if (customerAgent == null || isDeleted(customerAgent.getSoftDelete())) { + throw new ToolCallException(McpErrorCode.NOT_FOUND_OR_FORBIDDEN, + "客户所属公司不存在: customerAgentId=" + command.customerAgentId); + } + String channel = customerAgent.getChannelNo() == null + ? "" : customerAgent.getChannelNo().trim().toUpperCase(Locale.ROOT); + if (!CUSTOMER_AGENT_CHANNELS.contains(channel)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "客户所属公司不是有效的总部/分公司: customerAgentId=" + command.customerAgentId); + } + + if (property.getCreateId() == null) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "物业未记录所属销售,无法确定合同所属公司: propertyId=" + command.propertyId); + } + User sale = userMapper.selectById(property.getCreateId()); + if (sale == null || isDeleted(sale.getSoftDelete())) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "物业所属销售不存在或已删除: saleId=" + property.getCreateId()); + } + if (sale.getAgentId() == null) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "物业所属销售未配置所属公司,拒绝创建: saleId=" + sale.getId()); + } + + List files = loadBindableFiles(command.fileIds, caller.getId()); + + Long count = contractNewMapper.selectCount(new LambdaQueryWrapper() + .eq(ContractNew::getCustomerNo, customerNo)); + String contractNo = customerNo + "C" + String.format("%03d", count + 1); + + ContractNew contract = new ContractNew(); + contract.setContractNo(contractNo); + contract.setContractName(command.contractName); + contract.setContractType(command.contractType); + contract.setContractAgentId(sale.getAgentId()); + contract.setCustomerAgentId(command.customerAgentId); + contract.setPropertyId(property.getId()); + contract.setPropertyName(property.getName()); + contract.setCustomerNo(customerNo); + contract.setCustomerName(property.getJinideName()); + contract.setAmount(command.amount); + contract.setContact(command.contact); + contract.setStartDate(command.startDate); + contract.setEndDate(command.endDate); + contract.setExpireRemind(command.expireRemind); + contract.setRemindDays(command.remindDays); + contract.setRemindTime(command.remindTime); + contract.setReminded(0); + contract.setSaleId(property.getCreateId()); + contract.setSaleName(property.getCreateName()); + contract.setRenewSourceId(0L); + contract.setRenewed(0); + contract.setSoftDelete(0); + contract.setCreateId(caller.getId()); + contract.setCreateTime(now); + contract.setModifyId(caller.getId()); + contract.setModifyTime(now); + contract.setClientRequestId(command.clientRequestId); + contract.setRequestHash(requestHash(command)); + contractNewMapper.insert(contract); + + bindFiles(contract, files, caller.getId(), now); + + insertProcess(contract, caller.getId(), caller.getName(), 0, 0, 0, 0, null, now); + + int status = submitFlow(contract, caller, now, warnings); + contractNewMapper.update(null, new LambdaUpdateWrapper() + .eq(ContractNew::getId, contract.getId()) + .set(ContractNew::getContractStatus, status) + .set(ContractNew::getModifyId, caller.getId()) + .set(ContractNew::getModifyTime, new Date())); + contract.setContractStatus(status); + + log.info("contract.create 事务完成 contractId={} contractNo={} status={} propertyId={} files={} caller={}", + contract.getId(), contractNo, status, contract.getPropertyId(), files.size(), caller.getId()); + return new CreateOutcome(contract.getId(), contractNo, status, command.fileIds); + } + + private List loadBindableFiles(List fileIds, Long callerId) { + List files = contractFileMapper.selectBatchIds(fileIds); + Map byId = files.stream() + .collect(Collectors.toMap(ContractFile::getId, f -> f, (a, b) -> a)); + for (Long fileId : fileIds) { + ContractFile file = byId.get(fileId); + if (file == null || isDeleted(file.getSoftDelete())) { + throw new ToolCallException(McpErrorCode.NOT_FOUND_OR_FORBIDDEN, + "附件不存在或已删除: fileId=" + fileId); + } + if (file.getContractId() != null && file.getContractId() != 0L) { + throw new ToolCallException(McpErrorCode.ATTACHMENT_NOT_BINDABLE, + "附件已被其他合同绑定: fileId=" + fileId); + } + if (!callerId.equals(file.getCreateId())) { + throw new ToolCallException(McpErrorCode.ATTACHMENT_NOT_BINDABLE, + "附件不是当前用户上传: fileId=" + fileId); + } + } + return files; + } + + private void bindFiles(ContractNew contract, List files, Long callerId, Date now) { + for (ContractFile file : files) { + int updated = contractFileMapper.update(null, new LambdaUpdateWrapper() + .eq(ContractFile::getId, file.getId()) + .eq(ContractFile::getSoftDelete, 0) + .eq(ContractFile::getCreateId, callerId) + .and(w -> w.eq(ContractFile::getContractId, 0L).or().isNull(ContractFile::getContractId)) + .set(ContractFile::getContractId, contract.getId()) + .set(ContractFile::getModifyId, callerId) + .set(ContractFile::getModifyTime, now)); + if (updated != 1) { + throw new ToolCallException(McpErrorCode.ATTACHMENT_NOT_BINDABLE, + "附件绑定失败(可能已被并发使用): fileId=" + file.getId()); + } + } + } + + // ------------------------------------------------------------------ 审批流 + + private int submitFlow(ContractNew contract, User submitUser, Date now, List warnings) { + List flows = contractFlowSetMapper.selectList(new LambdaQueryWrapper() + .eq(ContractFlowSet::getSoftDelete, 0) + .eq(ContractFlowSet::getAgentId, contract.getContractAgentId())); + if (flows.size() > 1) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "合同所属公司存在多条有效工作流配置,拒绝创建: contractAgentId=" + contract.getContractAgentId()); + } + if (flows.isEmpty()) { + return STATUS_NORMAL; + } + ContractFlowSet flow = flows.get(0); + List auditUsers = contractFlowUserMapper.selectList( + new LambdaQueryWrapper() + .eq(ContractFlowUser::getSoftDelete, 0) + .eq(ContractFlowUser::getFlowSetId, flow.getId()) + .eq(ContractFlowUser::getUserType, 0) + .orderByAsc(ContractFlowUser::getAuditLevel) + .orderByAsc(ContractFlowUser::getId)); + List ccUsers = contractFlowUserMapper.selectList( + new LambdaQueryWrapper() + .eq(ContractFlowUser::getSoftDelete, 0) + .eq(ContractFlowUser::getFlowSetId, flow.getId()) + .eq(ContractFlowUser::getUserType, 1) + .orderByAsc(ContractFlowUser::getId)); + boolean hasLevels = !auditUsers.isEmpty(); + + boolean needAudit; + int todoNodeType = 2; + int todoLevel = 1; + List todoUsers = new ArrayList<>(); + + Integer switchValue = flow.getDepartAuditSwitch(); + if (switchValue != null && switchValue == 1) { + Set leaderPostIds = deptLeaderPostIds(); + if (isDeptLeader(submitUser, leaderPostIds)) { + needAudit = hasLevels; + if (hasLevels) { + todoUsers = levelOneUsers(auditUsers); + } + } else { + List leaders = findDeptLeaders(submitUser.getDeptId(), leaderPostIds); + if (leaders.isEmpty()) { + needAudit = hasLevels; + if (hasLevels) { + todoUsers = levelOneUsers(auditUsers); + } + } else { + needAudit = true; + todoNodeType = 1; + todoLevel = 0; + todoUsers = leaders; + } + } + } else { + needAudit = hasLevels; + if (hasLevels) { + todoUsers = levelOneUsers(auditUsers); + } + } + + if (!needAudit || todoUsers.isEmpty()) { + return STATUS_NORMAL; + } + createTodosAndNotify(contract, submitUser, todoNodeType, todoLevel, todoUsers, + ccUsers, now, warnings); + return STATUS_PENDING; + } + + private Set deptLeaderPostIds() { + Object value = redisTemplate.opsForHash().get(DICT_KEY, DEPT_LEADER_POST_FIELD); + if (value == null || !StringUtils.hasText(value.toString())) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "Redis Dictionary 缺少 " + DEPT_LEADER_POST_FIELD + ",无法判断部门负责人,拒绝创建"); + } + Set postIds = new LinkedHashSet<>(); + for (String part : value.toString().split(",")) { + String trimmed = part.trim(); + if (trimmed.isEmpty()) { + continue; + } + try { + postIds.add(Long.parseLong(trimmed)); + } catch (NumberFormatException e) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "Redis Dictionary." + DEPT_LEADER_POST_FIELD + " 含非数字岗位: " + trimmed); + } + } + if (postIds.isEmpty()) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "Redis Dictionary." + DEPT_LEADER_POST_FIELD + " 为空,无法判断部门负责人,拒绝创建"); + } + return postIds; + } + + private static boolean isDeptLeader(User user, Set leaderPostIds) { + return user.getPostId() != null && leaderPostIds.contains(user.getPostId()); + } + + private List findDeptLeaders(Long deptId, Set leaderPostIds) { + if (deptId == null) { + return List.of(); + } + return userMapper.selectList(new LambdaQueryWrapper() + .eq(User::getSoftDelete, 0) + .eq(User::getDeptId, deptId) + .in(User::getPostId, leaderPostIds) + .orderByAsc(User::getId)) + .stream() + .map(u -> new TodoUser(u.getId(), u.getName())) + .collect(Collectors.toList()); + } + + private List levelOneUsers(List auditUsers) { + List levelOne = auditUsers.stream() + .filter(u -> u.getAuditLevel() != null && u.getAuditLevel() == 1) + .toList(); + if (levelOne.isEmpty()) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "工作流存在审核人但缺少 1 级审核人,拒绝创建"); + } + List result = new ArrayList<>(); + Set seen = new HashSet<>(); + for (ContractFlowUser user : levelOne) { + if (user.getUserId() == null || seen.add(user.getUserId()) == false) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "工作流 1 级审核人数据损坏或重复,拒绝创建"); + } + result.add(new TodoUser(user.getUserId(), user.getUserName())); + } + return result; + } + + private void createTodosAndNotify(ContractNew contract, User submitUser, int nodeType, int auditLevel, + List todoUsers, List ccUsers, Date now, + List warnings) { + for (TodoUser todo : todoUsers) { + insertProcess(contract, todo.userId, todo.userName, nodeType, auditLevel, 0, 1, null, null); + } + String todoNames = todoUsers.stream() + .map(TodoUser::userName) + .filter(StringUtils::hasText) + .collect(Collectors.joining("、")); + String propertyName = contract.getPropertyName() == null ? "" : contract.getPropertyName(); + String ccContent = "【合同审核】" + submitUser.getName() + "提交的" + propertyName + + "的待审合同,合同编号为:" + contract.getContractNo() + + ",已提交" + todoNames + "进行审批。"; + for (ContractFlowUser cc : ccUsers) { + if (cc.getUserId() == null) { + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "工作流抄送人数据损坏,拒绝创建"); + } + insertProcess(contract, cc.getUserId(), cc.getUserName(), 4, 0, 5, 0, ccContent, now); + } + + String todoContent = "【合同审核】您收到" + submitUser.getName() + "提交的" + propertyName + + "的待审合同,合同编号为:" + contract.getContractNo() + + ",请您及时在 SaaS 或 APP 的合同管理中进行审批处理。"; + Map messages = new LinkedHashMap<>(); + for (TodoUser todo : todoUsers) { + messages.putIfAbsent(todo.userId, new Notice(MSG_TODO, contract.getContractNo(), + todoContent, todo.userId)); + } + for (ContractFlowUser cc : ccUsers) { + messages.putIfAbsent(cc.getUserId(), new Notice(MSG_CC, contract.getContractNo(), + ccContent, cc.getUserId())); + } + pushAfterCommit(messages, warnings); + } + + private void insertProcess(ContractNew contract, Long userId, String userName, int nodeType, + int auditLevel, int operationType, int scheduleState, String remark, + Date operateTime) { + ContractProcess process = new ContractProcess(); + process.setContractId(contract.getId()); + process.setContractNo(contract.getContractNo()); + process.setNodeType(nodeType); + process.setAuditLevel(auditLevel); + process.setOperationType(operationType); + process.setUserId(userId); + process.setUserName(userName); + process.setScheduleState(scheduleState); + process.setRemark(remark); + process.setOperateTime(operateTime); + process.setCreateId(contract.getCreateId()); + process.setCreateTime(new Date()); + process.setSoftDelete(0); + contractProcessMapper.insert(process); + } + + private void pushAfterCommit(Map messages, List warnings) { + if (messages.isEmpty()) { + return; + } + Runnable push = () -> { + for (Notice message : messages.values()) { + try { + redisTemplate.opsForList().leftPush(MSG_QUEUE, + JSON.writeValueAsString(message.asPayload())); + log.info("合同审批通知已推送 type={} userId={} contractNo={}", + message.type, message.userId, message.no); + } catch (Exception e) { + log.warn("合同审批通知推送失败 type={} userId={} error={}", + message.type, message.userId, e.getMessage()); + warnings.add("合同已创建,但审批通知发送失败(type=" + message.type + + ", userId=" + message.userId + ")"); + } + } + }; + if (TransactionSynchronizationManager.isSynchronizationActive()) { + TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { + @Override + public void afterCommit() { + push.run(); + } + }); + } else { + push.run(); + } + } + + // ------------------------------------------------------------------ 幂等回放 + + private ContractNew findByRequestKey(Long createId, String clientRequestId) { + return contractNewMapper.selectOne(new LambdaQueryWrapper() + .eq(ContractNew::getCreateId, createId) + .eq(ContractNew::getClientRequestId, clientRequestId) + .last("LIMIT 1")); + } + + private Map replayOrConflict(ContractNew existing, String requestHash) { + if (!requestHash.equals(existing.getRequestHash())) { + throw new ToolCallException(McpErrorCode.IDEMPOTENCY_CONFLICT, + "clientRequestId 已被相同用户用于不同创建参数,请换新键或使用原参数重试"); + } + if (isDeleted(existing.getSoftDelete())) { + throw new ToolCallException(McpErrorCode.IDEMPOTENCY_CONFLICT, + "clientRequestId 对应的合同已删除,不能回放,请换新键创建"); + } + List boundFileIds = contractFileMapper.selectList(new LambdaQueryWrapper() + .eq(ContractFile::getContractId, existing.getId()) + .eq(ContractFile::getSoftDelete, 0) + .orderByAsc(ContractFile::getId)) + .stream().map(ContractFile::getId).toList(); + Map result = new LinkedHashMap<>(); + result.put("id", existing.getId()); + result.put("contractNo", existing.getContractNo()); + result.put("contractStatus", existing.getContractStatus()); + result.put("contractStatusText", STATUS_TEXT.getOrDefault(existing.getContractStatus(), "未知")); + result.put("fileIds", boundFileIds); + result.put("clientRequestId", existing.getClientRequestId()); + result.put("idempotentReplay", true); + result.put("warnings", List.of()); + result.put("requestId", McpCallContextHolder.currentOrCreateRequestId()); + return result; + } + + private Map success(CreateOutcome outcome, String clientRequestId, + List warnings, boolean replay) { + Map result = new LinkedHashMap<>(); + result.put("id", outcome.id); + result.put("contractNo", outcome.contractNo); + result.put("contractStatus", outcome.status); + result.put("contractStatusText", STATUS_TEXT.getOrDefault(outcome.status, "未知")); + result.put("fileIds", outcome.fileIds); + result.put("clientRequestId", clientRequestId); + result.put("idempotentReplay", replay); + result.put("warnings", warnings); + result.put("requestId", McpCallContextHolder.currentOrCreateRequestId()); + return result; + } + + private static boolean isDeleted(Integer softDelete) { + return softDelete != null && softDelete == 1; + } + + private static String sha256Hex(String value) { + try { + MessageDigest digest = MessageDigest.getInstance("SHA-256"); + byte[] bytes = digest.digest(value.getBytes(StandardCharsets.UTF_8)); + StringBuilder sb = new StringBuilder(bytes.length * 2); + for (byte b : bytes) { + sb.append(Character.forDigit((b >> 4) & 0xF, 16)) + .append(Character.forDigit(b & 0xF, 16)); + } + return sb.toString(); + } catch (NoSuchAlgorithmException e) { + throw new IllegalStateException("JVM 缺少 SHA-256", e); + } + } + + private record CreateCommand(String clientRequestId, Integer contractType, Long customerAgentId, + Long propertyId, List fileIds, String contractName, BigDecimal amount, + String contact, Date startDate, Date endDate, Integer expireRemind, + Integer remindDays, Date remindTime) { + } + + private record CreateOutcome(Long id, String contractNo, Integer status, List fileIds) { + } + + private record TodoUser(Long userId, String userName) { + } + + private record Notice(int type, String no, String content, Long userId) { + Map asPayload() { + Map payload = new LinkedHashMap<>(); + payload.put("type", type); + payload.put("no", no); + payload.put("content", content); + payload.put("userId", userId); + return payload; + } + } +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java new file mode 100644 index 0000000..f32dbe7 --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java @@ -0,0 +1,304 @@ +package me.iiv.agent.mcp.tool; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import me.iiv.agent.entity.m0.User; +import me.iiv.agent.entity.m2.ContractFile; +import me.iiv.agent.mapper.m2.ContractFileMapper; +import me.iiv.agent.mcp.McpCallContextHolder; +import me.iiv.agent.mcp.McpErrorCode; +import me.iiv.agent.mcp.ToolCallException; +import me.iiv.agent.mcp.ToolObject; +import me.iiv.agent.mcp.XqTool; +import me.iiv.agent.security.AuthContextHolder; +import me.iiv.agent.service.ContractOssService; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.ai.tool.annotation.Tool; +import org.springframework.ai.tool.annotation.ToolParam; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.stereotype.Component; +import org.springframework.util.StringUtils; + +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.Base64; +import java.util.Date; +import java.util.LinkedHashMap; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +import java.util.regex.Pattern; + +/** + * 合同附件上传工具(REQ-20261118-0011,设计文档 doc/contract-create-mcp-design.md)。 + * 每次上传一个文件到 OSS,并生成 contract_id=0 的附件句柄;不创建合同。 + * 必须用户身份 Token;零行级权限,门禁靠「研发专用」scope。 + * 上传与 DB 登记通过 clientUploadId 持久化幂等;DB 失败只补偿删除本次新对象。 + */ +@Component +public class ContractFileAdminTools implements ToolObject { + + private static final Logger log = LoggerFactory.getLogger(ContractFileAdminTools.class); + + static final long MAX_FILE_BYTES = 20L * 1024 * 1024; + private static final Pattern CLIENT_UPLOAD_ID = Pattern.compile("^[A-Za-z0-9._:-]{1,64}$"); + private static final Set ALLOWED_EXTENSIONS = Set.of( + "jpg", "jpeg", "png", "doc", "docx", "pdf", "xls", "xlsx", "csv"); + + private static final byte[] PDF_MAGIC = {'%', 'P', 'D', 'F', '-'}; + private static final byte[] PNG_MAGIC = {(byte) 0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A}; + private static final byte[] OLE_MAGIC = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0, + (byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1}; + private static final byte[] ZIP_MAGIC = {'P', 'K', 0x03, 0x04}; + + final ContractFileMapper contractFileMapper; + final ContractOssService contractOssService; + + public ContractFileAdminTools(ContractFileMapper contractFileMapper, ContractOssService contractOssService) { + this.contractFileMapper = contractFileMapper; + this.contractOssService = contractOssService; + } + + @XqTool(category = "admin", kind = "write") + @Tool(name = "contract.file.upload", description = "【写操作·合同批量补录】上传一个合同附件到 OSS," + + "并在 m2.contract_file 生成 contract_id=0 的未绑定附件句柄,供 contract.create 绑定。" + + "每次只传一个文件:contentBase64 为标准 Base64(不带 data URL 前缀),解码后 1 byte~20 MiB;" + + "允许 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv,服务端校验扩展名、Base64、文件头和实际字节数。" + + "clientUploadId 为当前用户内稳定的上传幂等键(1~64 位字母/数字/点/下划线/冒号/连字符):" + + "同键同文件名同内容重试返回原 fileId(idempotentReplay=true,不重复上传 OSS),同键不同内容返回 IDEMPOTENCY_CONFLICT。" + + "必须用户身份 Token;审计不记录 Base64、文件正文或 OSS 凭据。" + + "本工具只准备附件,不创建合同;全部附件收齐后再调用 contract.create。") + public Map contractFileUpload( + @ToolParam(description = "当前用户内稳定的上传幂等键,1~64 位,重试必须保持不变") String clientUploadId, + @ToolParam(description = "原始文件名(含扩展名),1~255 字符,不得包含路径分隔符") String fileName, + @ToolParam(description = "标准 Base64 文件内容,不带 data URL 前缀;解码后 1 byte~20 MiB") String contentBase64) { + User caller = AuthContextHolder.get().getUser(); + if (caller == null) { + throw new ToolCallException(McpErrorCode.PERMISSION_DENIED, + "该工具要求用户身份 Token 调用(上传人需可追溯),服务身份 Token 不可用"); + } + String uploadId = requireUploadId(clientUploadId); + String originalName = requireFileName(fileName); + String extension = extensionOf(originalName); + byte[] content = decodeBase64(contentBase64); + if (content.length == 0) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "文件内容不能为空"); + } + if (content.length > MAX_FILE_BYTES) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "文件解码后 " + content.length + " bytes,超过上限 20 MiB(20971520 bytes)"); + } + validateFileHeader(extension, content); + + String requestHash = sha256Hex(originalName.trim() + "\n" + sha256Hex(content)); + + ContractFile existing = findByUploadKey(caller.getId(), uploadId); + if (existing != null) { + return replayOrConflict(existing, requestHash); + } + + String objectName = UUID.randomUUID().toString().replace("-", "") + + "." + extension.toLowerCase(Locale.ROOT); + String url = contractOssService.upload(objectName, content, contentTypeOf(extension)); + + Date now = new Date(); + ContractFile file = new ContractFile(); + file.setContractId(0L); + file.setFileName(originalName); + file.setOssBucket(contractOssService.bucket()); + file.setOssFolder(contractOssService.folder()); + file.setFileUrl(url); + file.setCreateId(caller.getId()); + file.setCreateTime(now); + file.setModifyId(caller.getId()); + file.setModifyTime(now); + file.setSoftDelete(0); + file.setClientUploadId(uploadId); + file.setRequestHash(requestHash); + + try { + contractFileMapper.insert(file); + } catch (DuplicateKeyException e) { + contractOssService.deleteQuietly(objectName); + ContractFile concurrent = findByUploadKey(caller.getId(), uploadId); + if (concurrent != null) { + return replayOrConflict(concurrent, requestHash); + } + throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR, + "附件登记唯一冲突但未查到幂等记录,请携带 request_id 联系运维排查"); + } catch (RuntimeException e) { + contractOssService.deleteQuietly(objectName); + log.error("合同附件登记失败并已补偿删除 OSS 对象 uploadId={} object={} error={}", + uploadId, objectName, e.getMessage()); + throw new ToolCallException(McpErrorCode.UPSTREAM_UNAVAILABLE, + "附件登记失败,请稍后使用相同 clientUploadId 重试"); + } + + String requestId = McpCallContextHolder.currentOrCreateRequestId(); + log.info("contract.file.upload 完成 requestId={} uploadId={} fileId={} size={} caller={}", + requestId, uploadId, file.getId(), content.length, caller.getId()); + + Map result = new LinkedHashMap<>(); + result.put("fileId", file.getId()); + result.put("fileName", originalName); + result.put("contractId", file.getContractId()); + result.put("idempotentReplay", false); + result.put("requestId", requestId); + return result; + } + + private Map replayOrConflict(ContractFile existing, String requestHash) { + if (!requestHash.equals(existing.getRequestHash())) { + throw new ToolCallException(McpErrorCode.IDEMPOTENCY_CONFLICT, + "clientUploadId 已被相同用户用于不同文件内容或文件名,请换新键上传"); + } + if (existing.getSoftDelete() != null && existing.getSoftDelete() == 1) { + throw new ToolCallException(McpErrorCode.IDEMPOTENCY_CONFLICT, + "clientUploadId 对应的附件已删除,不能回放,请换新键上传"); + } + Map result = new LinkedHashMap<>(); + result.put("fileId", existing.getId()); + result.put("fileName", existing.getFileName()); + result.put("contractId", existing.getContractId()); + result.put("idempotentReplay", true); + result.put("requestId", McpCallContextHolder.currentOrCreateRequestId()); + return result; + } + + private ContractFile findByUploadKey(Long createId, String uploadId) { + return contractFileMapper.selectOne(new LambdaQueryWrapper() + .eq(ContractFile::getCreateId, createId) + .eq(ContractFile::getClientUploadId, uploadId) + .last("LIMIT 1")); + } + + private static String requireUploadId(String value) { + if (!StringUtils.hasText(value) || !CLIENT_UPLOAD_ID.matcher(value).matches()) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "clientUploadId 必须为 1~64 位字母、数字、点、下划线、冒号或连字符"); + } + return value; + } + + static String requireFileName(String value) { + if (!StringUtils.hasText(value)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "fileName 不能为空"); + } + String name = value.trim(); + if (name.length() > 255) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "fileName 不能超过 255 字符"); + } + if (name.contains("/") || name.contains("\\") + || name.chars().anyMatch(Character::isISOControl)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "fileName 不得包含路径分隔符或控制字符"); + } + if (!ALLOWED_EXTENSIONS.contains(extensionOf(name))) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "仅支持 jpg、jpeg、png、doc、docx、pdf、xls、xlsx、csv 格式"); + } + return name; + } + + private static String extensionOf(String fileName) { + int dot = fileName.lastIndexOf('.'); + if (dot <= 0 || dot == fileName.length() - 1) { + return ""; + } + return fileName.substring(dot + 1).toLowerCase(Locale.ROOT); + } + + private static byte[] decodeBase64(String value) { + if (!StringUtils.hasText(value)) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "contentBase64 不能为空"); + } + if (value.startsWith("data:")) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "contentBase64 不能带 data URL 前缀,请只传标准 Base64 内容"); + } + try { + return Base64.getDecoder().decode(value); + } catch (IllegalArgumentException e) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "contentBase64 不是合法的标准 Base64 内容"); + } + } + + static void validateFileHeader(String extension, byte[] content) { + switch (extension) { + case "pdf" -> requireMagic(content, PDF_MAGIC, "PDF"); + case "jpg", "jpeg" -> { + if (content.length < 3 || (content[0] & 0xFF) != 0xFF + || (content[1] & 0xFF) != 0xD8 || (content[2] & 0xFF) != 0xFF) { + throw headerMismatch("JPEG"); + } + } + case "png" -> requireMagic(content, PNG_MAGIC, "PNG"); + case "doc", "xls" -> requireMagic(content, OLE_MAGIC, "OLE(doc/xls)"); + case "docx", "xlsx" -> requireMagic(content, ZIP_MAGIC, "ZIP(docx/xlsx)"); + case "csv" -> { + for (byte b : content) { + if (b == 0) { + throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "CSV 文件包含二进制 NUL 字节,疑似伪造扩展名"); + } + } + } + default -> throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "不支持的扩展名: " + extension); + } + } + + private static void requireMagic(byte[] content, byte[] magic, String label) { + if (content.length < magic.length) { + throw headerMismatch(label); + } + for (int i = 0; i < magic.length; i++) { + if (content[i] != magic[i]) { + throw headerMismatch(label); + } + } + } + + private static ToolCallException headerMismatch(String label) { + return new ToolCallException(McpErrorCode.INVALID_ARGUMENT, + "文件头与扩展名不符,不是有效的 " + label + " 文件"); + } + + private static String contentTypeOf(String extension) { + return switch (extension) { + case "jpg", "jpeg" -> "image/jpeg"; + case "png" -> "image/png"; + case "pdf" -> "application/pdf"; + case "doc" -> "application/msword"; + case "docx" -> "application/vnd.openxmlformats-officedocument.wordprocessingml.document"; + case "xls" -> "application/vnd.ms-excel"; + case "xlsx" -> "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"; + case "csv" -> "text/csv"; + default -> "application/octet-stream"; + }; + } + + static String sha256Hex(byte[] content) { + try { + MessageDigest digest = MessageDigest.getInstance("SHA-256"); + return toHex(digest.digest(content)); + } catch (NoSuchAlgorithmException e) { + throw new IllegalStateException("JVM 缺少 SHA-256", e); + } + } + + static String sha256Hex(String value) { + return sha256Hex(value.getBytes(StandardCharsets.UTF_8)); + } + + private static String toHex(byte[] bytes) { + StringBuilder sb = new StringBuilder(bytes.length * 2); + for (byte b : bytes) { + sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16)); + } + return sb.toString(); + } +} diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractTools.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractTools.java index 3d8b838..ffb2dff 100644 --- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractTools.java +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/mcp/tool/ContractTools.java @@ -45,6 +45,8 @@ public class ContractTools implements ToolObject { private static final Map CONTRACT_STATUS_TEXT = Map.of( 0, "待审", 1, "驳回", 2, "正常", 3, "过期", 4, "终止"); + private static final Map CONTRACT_TYPE_TEXT = Map.of( + 0, "租赁", 1, "售卖", 2, "其他"); private static final Map NODE_TYPE_TEXT = Map.of( 0, "创建", 1, "部门内审核", 2, "层级审核", 3, "终止", 4, "抄送"); private static final Map OPERATION_TYPE_TEXT = Map.of( @@ -293,6 +295,10 @@ public class ContractTools implements ToolObject { record.put("contractId", contract.getId()); record.put("contractNo", contract.getContractNo()); record.put("contractName", contract.getContractName()); + record.put("contractType", contract.getContractType()); + record.put("contractTypeText", contract.getContractType() == null + ? "未设置" : CONTRACT_TYPE_TEXT.getOrDefault(contract.getContractType(), "未知")); + record.put("renewed", contract.getRenewed()); record.put("status", contract.getContractStatus()); record.put("startAt", ChangesEngine.iso(contract.getStartDate())); record.put("endAt", ChangesEngine.iso(contract.getEndDate())); diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/service/ContractOssService.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/service/ContractOssService.java new file mode 100644 index 0000000..5da7d7a --- /dev/null +++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/service/ContractOssService.java @@ -0,0 +1,108 @@ +package me.iiv.agent.service; + +import com.aliyun.oss.OSS; +import com.aliyun.oss.OSSClientBuilder; +import com.aliyun.oss.model.ObjectMetadata; +import me.iiv.agent.config.ContractOssProperties; +import me.iiv.agent.mcp.McpErrorCode; +import me.iiv.agent.mcp.ToolCallException; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.stereotype.Service; +import org.springframework.util.StringUtils; + +/** + * 合同附件 OSS 上传与本次新对象补偿删除(REQ-20261118-0011)。 + * 只负责对象存储,不写数据库;DB 失败时的删除范围由调用方限定为本次新对象。 + */ +@Service +public class ContractOssService { + + private static final Logger log = LoggerFactory.getLogger(ContractOssService.class); + + private final ContractOssProperties properties; + + private volatile OSS client; + + public ContractOssService(ContractOssProperties properties) { + this.properties = properties; + } + + /** 上传并返回可访问 URL;任何未确认成功都抛 UPSTREAM_UNAVAILABLE,调用方不得写附件记录。 */ + public String upload(String objectName, byte[] content, String contentType) { + if (!StringUtils.hasText(properties.getEndpoint()) || !StringUtils.hasText(properties.getBucket()) + || !StringUtils.hasText(properties.getAccessKeyId()) + || !StringUtils.hasText(properties.getAccessKeySecret())) { + throw new ToolCallException(McpErrorCode.UPSTREAM_UNAVAILABLE, + "合同附件 OSS 未配置,无法上传"); + } + String key = folder() + objectName; + try { + ObjectMetadata metadata = new ObjectMetadata(); + metadata.setContentLength(content.length); + metadata.setCacheControl("no-cache"); + metadata.setContentType(contentType); + client().putObject(properties.getBucket(), key, new java.io.ByteArrayInputStream(content), metadata); + return publicUrl(key); + } catch (Exception e) { + log.error("合同附件 OSS 上传失败 key={} error={}", key, e.getMessage()); + throw new ToolCallException(McpErrorCode.UPSTREAM_UNAVAILABLE, + "合同附件 OSS 上传失败,请稍后重试"); + } + } + + /** + * 仅用于删除本次上传但未落库的新对象;失败只告警,不影响主流程。 + * 调用方必须先确认 objectName 由本次请求生成,禁止删除既有对象。 + */ + public void deleteQuietly(String objectName) { + String key = folder() + objectName; + try { + client().deleteObject(properties.getBucket(), key); + } catch (Exception e) { + log.warn("合同附件 OSS 补偿删除失败,需运维清理 bucket={} key={} error={}", + properties.getBucket(), key, e.getMessage()); + } + } + + public String bucket() { + return properties.getBucket(); + } + + public String folder() { + String folder = properties.getFolder(); + if (!StringUtils.hasText(folder)) { + return "contract/"; + } + return folder.endsWith("/") ? folder : folder + "/"; + } + + private String publicUrl(String key) { + if (StringUtils.hasText(properties.getPublicUrlPrefix())) { + String prefix = properties.getPublicUrlPrefix(); + return (prefix.endsWith("/") ? prefix : prefix + "/") + key; + } + String endpoint = properties.getEndpoint().trim(); + String scheme = endpoint.startsWith("https://") ? "https" : "http"; + String host = endpoint.replaceFirst("^https?://", ""); + if (host.endsWith("/")) { + host = host.substring(0, host.length() - 1); + } + return scheme + "://" + properties.getBucket() + "." + host + "/" + key; + } + + private OSS client() { + OSS current = client; + if (current == null) { + synchronized (this) { + current = client; + if (current == null) { + current = new OSSClientBuilder().build(properties.getEndpoint(), + properties.getAccessKeyId(), properties.getAccessKeySecret()); + client = current; + } + } + } + return current; + } +} diff --git a/xiaoqu-agent-service/src/main/resources/application-dev.yml b/xiaoqu-agent-service/src/main/resources/application-dev.yml index 8c37d3a..d44a087 100644 --- a/xiaoqu-agent-service/src/main/resources/application-dev.yml +++ b/xiaoqu-agent-service/src/main/resources/application-dev.yml @@ -2,6 +2,10 @@ # 账号密码明文写在本文件(内网 dev 库,与 xiaoqu-franchisee pom.xml dev profile 同一惯例); # 生产/测试环境不得在配置文件中写明文密码,改用环境变量 app: + # 合同附件 OSS:dev 与生产共用 bucket 时,用独立目录隔离本次测试对象(验收后按 key 精确清理) + contract: + oss: + folder: ${SVC_CONTRACT_OSS_FOLDER:contract-dev/} open: # Open API(/api/open/**)服务间静态密钥,dev 明文;调用方放 header X-Open-Key # 旧密钥:不限作用域,仅存量用户 Token ensure 可用(不可签发 service Token) diff --git a/xiaoqu-agent-service/src/main/resources/application.yml b/xiaoqu-agent-service/src/main/resources/application.yml index 91a2b6e..7e2634b 100644 --- a/xiaoqu-agent-service/src/main/resources/application.yml +++ b/xiaoqu-agent-service/src/main/resources/application.yml @@ -28,6 +28,17 @@ app: query-timeout-seconds: ${SYNC_QUERY_TIMEOUT_SECONDS:10} default-limit: ${SYNC_DEFAULT_LIMIT:100} max-limit: ${SYNC_MAX_LIMIT:200} + # 合同附件 OSS(REQ-20261118-0011):凭据只从环境变量注入; + # dev 在 application-dev.yml 覆盖为独立 folder 前缀,避免与生产对象混淆 + contract: + oss: + endpoint: ${SVC_CONTRACT_OSS_ENDPOINT:https://oss-cn-beijing.aliyuncs.com} + access-key-id: ${SVC_CONTRACT_OSS_ACCESS_KEY_ID:} + access-key-secret: ${SVC_CONTRACT_OSS_ACCESS_KEY_SECRET:} + bucket: ${SVC_CONTRACT_OSS_BUCKET:xiaoqu-safefile} + folder: ${SVC_CONTRACT_OSS_FOLDER:contract/} + public-url-prefix: ${SVC_CONTRACT_OSS_PUBLIC_URL_PREFIX:} + # 工具调用限流(每 Token 每分钟):SYNC 与 QUERY 分档互不占配额;0=关闭该档位 rate-limit: query-per-minute: ${QUERY_RATE_LIMIT_PER_MINUTE:600} diff --git a/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java b/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java new file mode 100644 index 0000000..15e3389 --- /dev/null +++ b/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java @@ -0,0 +1,431 @@ +package me.iiv.agent.mcp.tool; + +import com.baomidou.mybatisplus.core.MybatisConfiguration; +import com.baomidou.mybatisplus.core.conditions.Wrapper; +import com.baomidou.mybatisplus.core.metadata.TableInfoHelper; +import me.iiv.agent.entity.m0.Agent; +import me.iiv.agent.entity.m0.Properyt; +import me.iiv.agent.entity.m0.User; +import me.iiv.agent.entity.m2.ContractFile; +import me.iiv.agent.entity.m2.ContractFlowSet; +import me.iiv.agent.entity.m2.ContractFlowUser; +import me.iiv.agent.entity.m2.ContractNew; +import me.iiv.agent.entity.m2.ContractProcess; +import me.iiv.agent.mapper.m0.AgentMapper; +import me.iiv.agent.mapper.m0.ProperytMapper; +import me.iiv.agent.mapper.m0.UserMapper; +import me.iiv.agent.mapper.m2.ContractFileMapper; +import me.iiv.agent.mapper.m2.ContractFlowSetMapper; +import me.iiv.agent.mapper.m2.ContractFlowUserMapper; +import me.iiv.agent.mapper.m2.ContractNewMapper; +import me.iiv.agent.mapper.m2.ContractProcessMapper; +import me.iiv.agent.mcp.McpErrorCode; +import me.iiv.agent.mcp.ToolCallException; +import me.iiv.agent.security.AuthContext; +import me.iiv.agent.security.AuthContextHolder; +import org.apache.ibatis.builder.MapperBuilderAssistant; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import org.mockito.junit.jupiter.MockitoSettings; +import org.mockito.quality.Strictness; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.data.redis.core.HashOperations; +import org.springframework.data.redis.core.ListOperations; +import org.springframework.data.redis.core.StringRedisTemplate; +import org.springframework.transaction.PlatformTransactionManager; +import org.springframework.transaction.TransactionDefinition; +import org.springframework.transaction.support.AbstractPlatformTransactionManager; +import org.springframework.transaction.support.DefaultTransactionStatus; + +import java.math.BigDecimal; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +@ExtendWith(MockitoExtension.class) +@MockitoSettings(strictness = Strictness.LENIENT) +class ContractCreateAdminToolsTest { + + @Mock ContractNewMapper contractNewMapper; + @Mock ContractFileMapper contractFileMapper; + @Mock ContractProcessMapper contractProcessMapper; + @Mock ContractFlowSetMapper contractFlowSetMapper; + @Mock ContractFlowUserMapper contractFlowUserMapper; + @Mock ProperytMapper properytMapper; + @Mock UserMapper userMapper; + @Mock AgentMapper agentMapper; + @Mock StringRedisTemplate redisTemplate; + @Mock ListOperations listOperations; + @Mock HashOperations hashOperations; + + ContractCreateAdminTools tools; + + @BeforeEach + void setUp() { + MapperBuilderAssistant assistant = new MapperBuilderAssistant(new MybatisConfiguration(), ""); + for (Class type : List.of(ContractNew.class, ContractFile.class, ContractProcess.class, + ContractFlowSet.class, ContractFlowUser.class, Properyt.class, User.class, Agent.class)) { + TableInfoHelper.initTableInfo(assistant, type); + } + tools = new ContractCreateAdminTools(contractNewMapper, contractFileMapper, contractProcessMapper, + contractFlowSetMapper, contractFlowUserMapper, properytMapper, userMapper, agentMapper, + redisTemplate, txManager()); + User caller = new User(); + caller.setId(812L); + caller.setName("提交人"); + caller.setDeptId(5L); + caller.setPostId(3L); + caller.setSoftDelete(0); + AuthContextHolder.set(new AuthContext(null, caller)); + } + + @AfterEach + void tearDown() { + AuthContextHolder.clear(); + } + + @Test + void deniesServiceTokenWithoutUser() { + AuthContextHolder.set(new AuthContext(null, null)); + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.PERMISSION_DENIED, e.getCode()); + } + + @Test + void rejectsInvalidParameters() { + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", null, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(), null, null, null, + "2026-01-01", "2026-12-31", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L, 101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-02-30", "2026-12-31", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-12-31", "2026-01-01", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), null, + new BigDecimal("1.234"), null, "2026-01-01", "2026-12-31", null, null)).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), null, + new BigDecimal("-1"), null, "2026-01-01", "2026-12-31", null, null)).getCode()); + } + + @Test + void createsNormalContractWithoutFlowAndAppliesDefaults() { + stubBaseData(); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of()); + + Map result = tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L, 102L), + " ", new BigDecimal("1200.50"), " 张三 ", "2026-01-01", "2026-12-31", null, null); + + assertEquals(500L, result.get("id")); + assertEquals("452542C001", result.get("contractNo")); + assertEquals(2, result.get("contractStatus")); + assertFalse((Boolean) result.get("idempotentReplay")); + assertTrue(((List) result.get("warnings")).isEmpty()); + + ArgumentCaptor captor = ArgumentCaptor.forClass(ContractNew.class); + verify(contractNewMapper).insert(captor.capture()); + ContractNew saved = captor.getValue(); + assertNull(saved.getContractName()); + assertEquals("张三", saved.getContact()); + assertEquals(0, saved.getContractType()); + assertEquals(20L, saved.getContractAgentId()); + assertEquals(30L, saved.getCustomerAgentId()); + assertEquals("452542", saved.getCustomerNo()); + assertEquals("客户A", saved.getCustomerName()); + assertEquals(77L, saved.getSaleId()); + assertEquals("销售A", saved.getSaleName()); + assertEquals(1, saved.getExpireRemind()); + assertEquals(30, saved.getRemindDays()); + assertEquals(0, saved.getRenewed()); + assertEquals(0L, saved.getRenewSourceId()); + assertEquals(0, saved.getSoftDelete()); + verify(contractProcessMapper, times(1)).insert(any(ContractProcess.class)); + verify(redisTemplate, never()).opsForList(); + } + + @Test + void createsPendingContractAndPushesTodoAndCcAfterCommit() { + stubBaseData(); + ContractFlowSet flow = flow(1L, 0); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of(flow)); + when(contractFlowUserMapper.selectList(any())).thenReturn( + List.of(flowUser(91L, "审核人甲", 1)), List.of(flowUser(92L, "抄送乙", null))); + when(redisTemplate.opsForList()).thenReturn(listOperations); + when(listOperations.leftPush(eq("InvoiceMessageNotice"), anyString())).thenReturn(1L); + + Map result = tools.contractCreate("req-1", 1, 30L, 10L, List.of(101L), + "合同A", null, null, "2026-01-01", "2026-12-31", 1, 30); + + assertEquals(0, result.get("contractStatus")); + ArgumentCaptor payload = ArgumentCaptor.forClass(String.class); + verify(listOperations, times(2)).leftPush(eq("InvoiceMessageNotice"), payload.capture()); + assertTrue(payload.getAllValues().get(0).contains("\"type\":12")); + assertTrue(payload.getAllValues().get(0).contains("\"userId\":91")); + assertTrue(payload.getAllValues().get(1).contains("\"type\":13")); + assertTrue(payload.getAllValues().get(1).contains("\"userId\":92")); + verify(contractProcessMapper, times(3)).insert(any(ContractProcess.class)); + } + + @Test + void departmentLeaderSwitchFailsFastWhenDictionaryMissing() { + stubBaseData(); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of(flow(1L, 1))); + when(redisTemplate.opsForHash()).thenReturn(hashOperations); + when(hashOperations.get("Dictionary", "authDeptPostId")).thenReturn(null); + + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.DATA_INTEGRITY_ERROR, e.getCode()); + assertTrue(e.getRawMessage().contains("authDeptPostId")); + } + + @Test + void rejectsWorkflowMissingLevelOne() { + stubBaseData(); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of(flow(1L, 0))); + when(contractFlowUserMapper.selectList(any())).thenReturn( + List.of(flowUser(91L, "二级审核人", 2)), List.of()); + + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.DATA_INTEGRITY_ERROR, e.getCode()); + assertTrue(e.getRawMessage().contains("1 级")); + } + + @Test + void rejectsSaleWithoutAgent() { + stubBaseData(); + User sale = user(77L, "销售A", null); + when(userMapper.selectById(77L)).thenReturn(sale); + + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.DATA_INTEGRITY_ERROR, e.getCode()); + } + + @Test + void rejectsAttachmentUploadedByAnotherUser() { + stubBaseData(); + ContractFile foreign = file(101L, 999L); + when(contractFileMapper.selectBatchIds(any())).thenReturn(List.of(foreign)); + + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.ATTACHMENT_NOT_BINDABLE, e.getCode()); + } + + @Test + void retriesWhenContractNoConflicts() { + stubBaseData(); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of()); + when(contractNewMapper.selectCount(any())).thenReturn(0L, 1L); + when(contractNewMapper.insert(any(ContractNew.class))) + .thenThrow(new DuplicateKeyException("uk_contract_no")) + .thenAnswer(inv -> { + ((ContractNew) inv.getArgument(0)).setId(501L); + return 1; + }); + + Map result = tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), + null, null, null, "2026-01-01", "2026-12-31", null, null); + + assertEquals(501L, result.get("id")); + assertEquals("452542C002", result.get("contractNo")); + verify(contractNewMapper, times(2)).insert(any(ContractNew.class)); + } + + @Test + void replayReturnsExistingContractWithoutWriting() { + ContractNew existing = new ContractNew(); + existing.setId(700L); + existing.setContractNo("452542C007"); + existing.setContractStatus(2); + existing.setSoftDelete(0); + existing.setClientRequestId("req-1"); + existing.setRequestHash(hashOf("req-1")); + when(contractNewMapper.selectOne(any())).thenReturn(existing); + ContractFile bound = file(101L, 812L); + bound.setContractId(700L); + when(contractFileMapper.selectList(any())).thenReturn(List.of(bound)); + + Map result = tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), + null, null, null, "2026-01-01", "2026-12-31", null, null); + + assertEquals(700L, result.get("id")); + assertTrue((Boolean) result.get("idempotentReplay")); + verify(contractNewMapper, never()).insert(any(ContractNew.class)); + verify(contractProcessMapper, never()).insert(any(ContractProcess.class)); + } + + @Test + void rejectsSameRequestKeyWithDifferentParameters() { + ContractNew existing = new ContractNew(); + existing.setId(700L); + existing.setSoftDelete(0); + existing.setRequestHash("different"); + when(contractNewMapper.selectOne(any())).thenReturn(existing); + + ToolCallException e = assertThrows(ToolCallException.class, () -> tools.contractCreate( + "req-1", 0, 30L, 10L, List.of(101L), null, null, null, + "2026-01-01", "2026-12-31", null, null)); + assertEquals(McpErrorCode.IDEMPOTENCY_CONFLICT, e.getCode()); + } + + @Test + void notificationFailureStillReturnsSuccessWithWarning() { + stubBaseData(); + when(contractFlowSetMapper.selectList(any())).thenReturn(List.of(flow(1L, 0))); + when(contractFlowUserMapper.selectList(any())).thenReturn( + List.of(flowUser(91L, "审核人甲", 1)), List.of()); + when(redisTemplate.opsForList()).thenReturn(listOperations); + when(listOperations.leftPush(eq("InvoiceMessageNotice"), anyString())) + .thenThrow(new IllegalStateException("redis down")); + + Map result = tools.contractCreate("req-1", 0, 30L, 10L, List.of(101L), + null, null, null, "2026-01-01", "2026-12-31", null, null); + + assertEquals(0, result.get("contractStatus")); + List warnings = (List) result.get("warnings"); + assertEquals(1, warnings.size()); + assertTrue(String.valueOf(warnings.get(0)).contains("审批通知发送失败")); + } + + // ------------------------------------------------------------------ helpers + + private void stubBaseData() { + Properyt property = new Properyt(); + property.setId(10L); + property.setName("测试物业"); + property.setJinideName("客户A"); + property.setSerialnumber("452542"); + property.setCreateId(77L); + property.setCreateName("销售A"); + property.setSoftDelete(0); + when(properytMapper.selectById(10L)).thenReturn(property); + when(userMapper.selectById(77L)).thenReturn(user(77L, "销售A", 20L)); + Agent agent = new Agent(); + agent.setId(30L); + agent.setChannelNo("Z"); + agent.setSoftDelete(0); + when(agentMapper.selectById(30L)).thenReturn(agent); + when(contractFileMapper.selectBatchIds(any())).thenReturn(List.of(file(101L, 812L), file(102L, 812L))); + when(contractNewMapper.selectCount(any())).thenReturn(0L); + when(contractNewMapper.insert(any(ContractNew.class))).thenAnswer(inv -> { + ((ContractNew) inv.getArgument(0)).setId(500L); + return 1; + }); + when(contractNewMapper.update(any(), any())).thenReturn(1); + when(contractFileMapper.update(any(), any())).thenReturn(1); + when(contractProcessMapper.insert(any(ContractProcess.class))).thenReturn(1); + } + + private static User user(Long id, String name, Long agentId) { + User user = new User(); + user.setId(id); + user.setName(name); + user.setAgentId(agentId); + user.setSoftDelete(0); + return user; + } + + private static ContractFile file(Long id, Long createId) { + ContractFile file = new ContractFile(); + file.setId(id); + file.setCreateId(createId); + file.setContractId(0L); + file.setSoftDelete(0); + return file; + } + + private static ContractFlowSet flow(Long id, int departSwitch) { + ContractFlowSet flow = new ContractFlowSet(); + flow.setId(id); + flow.setSoftDelete(0); + flow.setAgentId(20L); + flow.setDepartAuditSwitch(departSwitch); + return flow; + } + + private static ContractFlowUser flowUser(Long userId, String userName, Integer level) { + ContractFlowUser user = new ContractFlowUser(); + user.setId(userId); + user.setFlowSetId(1L); + user.setUserId(userId); + user.setUserName(userName); + user.setUserType(level == null ? 1 : 0); + user.setAuditLevel(level); + user.setSoftDelete(0); + return user; + } + + private static String hashOf(String clientRequestId) { + String canonical = 0 + "\n" + 30L + "\n" + 10L + "\n" + "101\n\n\n\n2026-01-01\n2026-12-31\n1\n30"; + return sha256(canonical); + } + + private static String sha256(String value) { + try { + java.security.MessageDigest digest = java.security.MessageDigest.getInstance("SHA-256"); + byte[] bytes = digest.digest(value.getBytes(java.nio.charset.StandardCharsets.UTF_8)); + StringBuilder sb = new StringBuilder(bytes.length * 2); + for (byte b : bytes) { + sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16)); + } + return sb.toString(); + } catch (Exception e) { + throw new IllegalStateException(e); + } + } + + private static PlatformTransactionManager txManager() { + return new AbstractPlatformTransactionManager() { + @Override + protected Object doGetTransaction() { + return new Object(); + } + + @Override + protected void doBegin(Object transaction, TransactionDefinition definition) { + } + + @Override + protected void doCommit(DefaultTransactionStatus status) { + } + + @Override + protected void doRollback(DefaultTransactionStatus status) { + } + }; + } +} diff --git a/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java b/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java new file mode 100644 index 0000000..111a570 --- /dev/null +++ b/xiaoqu-agent-service/src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java @@ -0,0 +1,194 @@ +package me.iiv.agent.mcp.tool; + +import com.baomidou.mybatisplus.core.MybatisConfiguration; +import com.baomidou.mybatisplus.core.metadata.TableInfoHelper; +import me.iiv.agent.entity.m0.User; +import me.iiv.agent.entity.m2.ContractFile; +import me.iiv.agent.mapper.m2.ContractFileMapper; +import me.iiv.agent.mcp.McpErrorCode; +import me.iiv.agent.mcp.ToolCallException; +import me.iiv.agent.security.AuthContext; +import me.iiv.agent.security.AuthContextHolder; +import me.iiv.agent.service.ContractOssService; +import org.apache.ibatis.builder.MapperBuilderAssistant; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import org.springframework.dao.DuplicateKeyException; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +@ExtendWith(MockitoExtension.class) +class ContractFileAdminToolsTest { + + @Mock ContractFileMapper contractFileMapper; + @Mock ContractOssService contractOssService; + + ContractFileAdminTools tools; + + private static final byte[] PDF = "%PDF-1.4\n1 0 obj\n<<>>\nendobj\n".getBytes(StandardCharsets.UTF_8); + + @BeforeEach + void setUp() { + MapperBuilderAssistant assistant = new MapperBuilderAssistant(new MybatisConfiguration(), ""); + TableInfoHelper.initTableInfo(assistant, ContractFile.class); + tools = new ContractFileAdminTools(contractFileMapper, contractOssService); + User caller = new User(); + caller.setId(812L); + AuthContextHolder.set(new AuthContext(null, caller)); + } + + @AfterEach + void tearDown() { + AuthContextHolder.clear(); + } + + @Test + void deniesServiceTokenWithoutUser() { + AuthContextHolder.set(new AuthContext(null, null)); + ToolCallException e = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", base64(PDF))); + assertEquals(McpErrorCode.PERMISSION_DENIED, e.getCode()); + verify(contractFileMapper, never()).insert(any(ContractFile.class)); + } + + @Test + void rejectsBadUploadIdAndFileName() { + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("bad id", "a.pdf", base64(PDF))).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "../a.pdf", base64(PDF))).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.exe", base64(PDF))).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", "data:application/pdf;base64,AAAA")).getCode()); + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", "!!!")).getCode()); + } + + @Test + void rejectsEmptyOversizeAndHeaderMismatch() { + assertEquals(McpErrorCode.INVALID_ARGUMENT, assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", "")).getCode()); + + byte[] oversize = new byte[(int) ContractFileAdminTools.MAX_FILE_BYTES + 1]; + System.arraycopy(PDF, 0, oversize, 0, PDF.length); + ToolCallException tooBig = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", base64(oversize))); + assertEquals(McpErrorCode.INVALID_ARGUMENT, tooBig.getCode()); + assertTrue(tooBig.getRawMessage().contains("20 MiB")); + + ToolCallException mismatch = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.pdf", base64("not a pdf".getBytes(StandardCharsets.UTF_8)))); + assertEquals(McpErrorCode.INVALID_ARGUMENT, mismatch.getCode()); + + ToolCallException csvBinary = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "a.csv", base64(new byte[]{'a', 0, 'b'}))); + assertEquals(McpErrorCode.INVALID_ARGUMENT, csvBinary.getCode()); + } + + @Test + void uploadsAndInsertsOrphanAttachment() { + when(contractFileMapper.selectOne(any())).thenReturn(null); + when(contractOssService.bucket()).thenReturn("xiaoqu-safefile"); + when(contractOssService.folder()).thenReturn("contract-dev/"); + when(contractOssService.upload(anyString(), any(), anyString())) + .thenReturn("http://xiaoqu-safefile.oss-cn-beijing.aliyuncs.com/contract-dev/x.pdf"); + when(contractFileMapper.insert(any(ContractFile.class))).thenAnswer(inv -> { + ((ContractFile) inv.getArgument(0)).setId(900L); + return 1; + }); + + Map result = tools.contractFileUpload("up-1", "合同.pdf", base64(PDF)); + + assertEquals(900L, result.get("fileId")); + assertEquals(0L, result.get("contractId")); + assertFalse((Boolean) result.get("idempotentReplay")); + verify(contractOssService).upload(anyString(), any(), anyString()); + } + + @Test + void replaysSameKeySameContentWithoutNewObject() { + ContractFile existing = existing(901L, hash("合同.pdf", PDF)); + when(contractFileMapper.selectOne(any())).thenReturn(existing); + + Map result = tools.contractFileUpload("up-1", "合同.pdf", base64(PDF)); + + assertEquals(901L, result.get("fileId")); + assertTrue((Boolean) result.get("idempotentReplay")); + verify(contractOssService, never()).upload(anyString(), any(), anyString()); + verify(contractFileMapper, never()).insert(any(ContractFile.class)); + } + + @Test + void rejectsSameKeyDifferentContent() { + when(contractFileMapper.selectOne(any())).thenReturn(existing(901L, hash("合同.pdf", PDF))); + byte[] other = "%PDF-1.7\nother".getBytes(StandardCharsets.UTF_8); + ToolCallException e = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "合同.pdf", base64(other))); + assertEquals(McpErrorCode.IDEMPOTENCY_CONFLICT, e.getCode()); + } + + @Test + void deletesNewObjectWhenDbInsertFails() { + when(contractFileMapper.selectOne(any())).thenReturn(null); + when(contractOssService.bucket()).thenReturn("xiaoqu-safefile"); + when(contractOssService.folder()).thenReturn("contract-dev/"); + when(contractOssService.upload(anyString(), any(), anyString())).thenReturn("http://url"); + when(contractFileMapper.insert(any(ContractFile.class))).thenThrow(new IllegalStateException("db down")); + + ToolCallException e = assertThrows(ToolCallException.class, + () -> tools.contractFileUpload("up-1", "合同.pdf", base64(PDF))); + assertEquals(McpErrorCode.UPSTREAM_UNAVAILABLE, e.getCode()); + verify(contractOssService).deleteQuietly(anyString()); + } + + @Test + void duplicateKeyReplaysConcurrentWinnerAndDeletesThisObject() { + ContractFile winner = existing(902L, hash("合同.pdf", PDF)); + when(contractFileMapper.selectOne(any())).thenReturn(null, winner); + when(contractOssService.bucket()).thenReturn("xiaoqu-safefile"); + when(contractOssService.folder()).thenReturn("contract-dev/"); + when(contractOssService.upload(anyString(), any(), anyString())).thenReturn("http://url"); + when(contractFileMapper.insert(any(ContractFile.class))).thenThrow(new DuplicateKeyException("uk")); + + Map result = tools.contractFileUpload("up-1", "合同.pdf", base64(PDF)); + + assertEquals(902L, result.get("fileId")); + assertTrue((Boolean) result.get("idempotentReplay")); + verify(contractOssService).deleteQuietly(anyString()); + } + + private static ContractFile existing(Long id, String hash) { + ContractFile file = new ContractFile(); + file.setId(id); + file.setFileName("合同.pdf"); + file.setContractId(0L); + file.setSoftDelete(0); + file.setRequestHash(hash); + return file; + } + + private static String hash(String name, byte[] content) { + return ContractFileAdminTools.sha256Hex(name.trim() + "\n" + ContractFileAdminTools.sha256Hex(content)); + } + + private static String base64(byte[] bytes) { + return Base64.getEncoder().encodeToString(bytes); + } +}