feat: support secure XFT submission attachments

README.md

@@ -21,8 +21,8 @@ Agent → 远程 Streamable HTTP MCP / OAuth 统一网关
 - `approval_list_submission_templates`：实时列出当前用户的提单候选模板。
 - `approval_get_submission_schema`：返回结构化可填写字段，不传输巨大原始 Schema。
 - `approval_get_submission_options`：实时查询当前用户可用的薪福通部门、城市和费用类型；所有选项面向用户只展示业务名称，内部映射正式接口值。
-- `approval_prepare_submission`：校验内容，自动查重本人近 30 天跨钉钉/薪福通的发票，并在安全时生成完整预览及短期确认引用；不创建单据。
-- `approval_submit`：用户确认预览后，使用相同内容正式发起审批。
+- `approval_prepare_submission`：校验内容和本机附件元数据，自动查重本人近 30 天跨钉钉/薪福通的发票，并在安全时生成完整预览及短期确认引用；不创建单据，也不上传附件。
+- `approval_submit`：用户确认预览后，签名本地 Bridge 才上传已确认的薪福通附件，并使用相同内容正式发起审批。
 - `approval_revoke_submission`：使用提单成功后返回的 `revokeId` 撤销本人刚通过 MCP 发起的钉钉或薪福通审批。
 - `approval_get_submission_status`：只读核验本人已发起薪福通单据的实时状态。
 
@@ -46,19 +46,19 @@ Agent 不传 `userId`、员工号或单据所有者。网关从 OAuth Token 确
 - 薪福通：可安全构造的申请和报销模板通过正式创建 API 发起，并在创建后实时核验状态。结果可能进入待审批，也可能因企业流程中没有其他有效审批人等规则即时完成；后者返回 `completed`，不会错误地当成接口失败，也不会签发不可用的撤回引用。用车申请不属于 MCP 发起范围，不会出现在候选模板中。
 - 钉钉：当前 6 个候选模板均返回 `client_only`，必须在钉钉客户端发起。其中 5 个包含企业 OpenAPI 无法可靠构造的 `DDBizSuite` 考勤或费控套件；`业务招待申请_北极大`虽是普通明细表，但真实创建时新版企业接口返回系统异常、旧版接口拒绝组件格式，因此同样安全降级。
 
-发起审批固定为“列模板 → 取 Schema → 自动查重/预览 → 用户确认 → 正式提交”。准备阶段从新表单提取发票代码与号码、数电票唯一编号、票据号码、附件哈希；没有唯一编号时，金额、日期与商户组合只作为疑似提示。网关实时刷新当前用户本人近 30 天的钉钉和薪福通已发起审批：原单待审批、已通过或状态未知时默认阻止，原单拒绝、撤回、作废或弱匹配时警告。任一来源查询不完整也不会当成“没有重复”。只有用户看过匹配单号、状态和覆盖情况并明确要求继续后，Agent 才能以 `allowDuplicateInvoices=true` 重新准备。
+发起审批固定为“列模板 → 取 Schema → 自动查重/预览 → 用户确认 → 正式提交”。准备阶段从新表单提取发票代码与号码、数电票唯一编号、票据号码、附件哈希；没有唯一编号时，金额、日期与商户组合只作为疑似提示。本机附件在准备阶段只读取并复核普通文件、大小、类型和 SHA-256，网关只收到不含路径的元数据；用户最终确认后才通过签名 Bridge 上传。网关实时刷新当前用户本人近 30 天的钉钉和薪福通已发起审批：原单待审批、已通过或状态未知时默认阻止，原单拒绝、撤回、作废或弱匹配时警告。任一来源查询不完整也不会当成“没有重复”。只有用户看过匹配单号、状态和覆盖情况并明确要求继续后，Agent 才能以 `allowDuplicateInvoices=true` 重新准备。
 
 用户不需要理解薪福通的任何内部选择值。实时 Schema 会把部门、城市、费用类型、出行方式、往返、时间范围、币种和酒店星级等字段标记为名称优先的选择项；Agent 只展示“深圳市”“交通费”“飞机”“往返”“人民币”等业务名称，选定后仅在内部写入正式接口值。动态下拉框也会标准化成 `label/code`，表格子字段同样递归处理。准备阶段的最终确认预览会再次按实时选项反向解析，只返回业务字段名和业务名称，不回显城市码、费用编码、字段号或表格列号；任何值无法可靠反向解析时，不生成 `confirmationId`。无法取得可靠名称映射时安全停止或允许跳过可选项，不退化为向用户索取工号、城市码、组织码、档案编号、数字舱位值或其他内部 ID。
 
 薪福通正式 OpenAPI 当前没有独立的费用类型目录查询。费用类型会先从模板实时字段读取，再检查企业自定义多级数据源；两处都没有可用选项时，MCP 返回具体的实时检查结果并引导在费用管理页面确认或使用薪福通客户端，不会把空目录误报为网络 `fetch` 故障。
 
-人员、企业自定义档案、关联前置单据、分摊及文档未给出可靠名称映射的舱位字段目前标记为 `client_only`。必填时不生成提交预览并引导薪福通客户端；可选时不会作为普通问题打扰用户。单据公司、部门、字段引用和行程序号等服务器管理或内部派生值也不会作为用户输入项展示。
+人员、企业自定义档案、关联前置单据、分摊及文档未给出可靠名称映射的舱位字段目前标记为 `client_only`。薪福通附件字段则由本机 Bridge 支持：PDF、OFD、JPG、PNG、XML 或 ZIP，单文件及单次提单附件总量均不超过 50MB，最多 10 个。必填附件可以由草稿引用满足；本地路径、文件内容和薪福通附件编号都不会出现在预览或对话中。单据公司、部门、字段引用和行程序号等服务器管理或内部派生值也不会作为用户输入项展示。
 
 服务端临时保留不可逆的用户/发票 HMAC 指纹。首次使用时只为最近 30 天尚未索引的审批读取详情；以后准备提单会刷新精简历史状态，并只为新增审批补建指纹，不会重复逐张下载已索引发票。指纹和最小审批索引最多保留 35 天，过期后自动级联删除；10 分钟提单预留到期即删除。
 
 安全准备后，确认引用绑定登录用户、模板版本、完整表单内容、重复风险决定和发票预留，10 分钟有效且只能使用一次；相同发票在另一个有效确认中时不会再签发确认，避免并发重复创建。正文和发票原号不落库。钉钉企业 OpenAPI 支持通过 `POST /v1.0/workflow/processes/forecast` 进行无副作用的流程预测；网关只在预测成功并补齐所有自选处理人后才生成提交确认。薪福通在正式提交时完成最终业务校验，并由网关写后读取 `billSts`：状态 `1（待审批）` 返回 `submitted` 和 `revokeId`，状态 `2（审批通过）` 返回 `completed` 且不提供撤回引用。
 
-用户可以让 Agent 把尚未填完的提单保存为本机草稿。它不是钉钉或薪福通的官方草稿：只写入运行 Agent 的当前 OS 用户私有数据目录，不上传网关，也不跨设备同步。草稿保存用户填写值、可选项决定以及附件的本地路径和 SHA-256，不保存 Token、身份 ID、短期模板/确认/撤回引用或完整上游 Schema；附件在正式准备前重新验哈希。恢复时重新实时列模板和读取 Schema，超过 90 天未更新的普通草稿在下次草稿操作时清理。提交结果不确定的草稿会冻结，核验清楚前禁止重试。宿主没有本地文件能力时不提供持久草稿，也不会改存服务器。当前 MCP 不提供附件上传工具；若实时 Schema 要求上游附件编号，本机路径不能代替，需保留草稿并在原生客户端完成。
+用户可以让 Agent 把尚未填完的提单保存为本机草稿。它不是钉钉或薪福通的官方草稿：只写入运行 Agent 的当前 OS 用户私有数据目录，不上传网关，也不跨设备同步。草稿保存用户填写值、可选项决定，以及附件所属表单字段、显示名、本地路径、大小、修改时间和 SHA-256；不保存 Token、身份 ID、短期模板/确认/撤回引用、薪福通附件编号或完整上游 Schema，也不复制或预上传文件。恢复时重新实时列模板和 Schema，并重新检查附件普通文件属性、类型、大小与 SHA-256。准备预览只发送不含路径的附件元数据；用户最终确认后，签名 Bridge 才把文件实时转发给薪福通，并把短时、不透明、用户与本次确认绑定的上传引用交给网关创建单据。网关和 Nginx 都不落盘附件。超过 90 天未更新的普通草稿在下次草稿操作时清理；提交结果不确定的草稿会冻结，核验清楚前禁止重试。宿主没有签名本地 Bridge 或安全文件能力时不提供附件上传或持久草稿，也不会改存服务器。
 
 > 发布候选版限制：薪福通 `approve/recall` 撤回接口已经接入并具备本人归属校验与写后复核，但当前企业的真实待审批单仍返回 `XFTSYS9999`，尚无撤回成功样本。因此薪福通撤回属于实验能力；失败或结果不确定时绝不自动重试。查询、处理和发起审批不受此限制。