MCP 异步导出任务设计

背景

export_pending_outbound_orders 和 export_out_of_province_port_data 当前都在一次 MCP tools/call 内同步完成查询、文件生成、上传并返回下载链接。未排舱导出固定 is_sync=1；省外进港资料同步调用 Support 模板导出。数据量较大时整个请求可能持续一分钟以上。

MCP Gateway 调用 fmsoperate 的默认 HTTP 超时为 10 秒，外层反向代理和 Workbuddy 也可能提前关闭长连接。单纯增加超时无法保证整条链路稳定，而且会长期占用 Gateway 并发名额和 PHP 请求进程。

本设计将两个导出工具改成短请求提交任务，并新增独立状态查询工具。文件生成继续复用 fmsoperate 现有导出算法、Redis 队列、st_download_list 和文件存储，不把业务逻辑迁移到 Gateway。

本设计替代 2026-07-14-mcp-export-pending-outbound-orders-design.md 中关于同步等待、直接返回文件 URL 和“不改造成任务轮询协议”的结论；原文件只作为当时设计记录保留。

目标

两个导出提交请求在完成参数、权限和数据存在性校验后快速返回，不等待文件生成。
新增 query_export_task，通过新的短 MCP 调用查询等待、执行、完成或失败状态。
完成状态返回与当前合同相同的安全文件链接。
复用现有导出实现，不复制 Excel 字段、模板、业务查询或 OSS 上传算法。
保持工具注册、菜单权限、公司隔离和员工数据范围校验。
防止客户端重试造成同一员工短时间内重复创建相同导出任务。
不暴露 st_download_list.id、内部异常、队列载荷或原始失败备注。

非目标

不通过一个 MCP 调用在 Gateway 内持续轮询。
不使用流式响应、SSE 或 WebSocket 传输导出进度。
不通过提高 Gateway、Nginx 或 Workbuddy 超时解决长任务。
不修改后台页面现有导出交互。
不改变两个导出的筛选条件、号码匹配、文件内容或模板。
不新增业务导出任务表；继续使用 st_download_list。

方案选择

采用：全异步提交和独立查询

两个导出工具一律创建任务并返回任务引用，调用方稍后单独调用 query_export_task。该方案使每次 HTTP 请求都保持短时、可重试，并且不依赖数据量阈值或调用端连接时长。

不采用：按数据量混合同步与异步

导出耗时不仅取决于行数，还取决于关联查询、模板服务、文件写入和上传。预估阈值不稳定，会让同一个工具出现两套时序和输出分支，增加调用方及测试复杂度。

不采用：只增加超时

Gateway、PHP、反向代理和 Workbuddy 任一层仍可能先超时。长请求还会占用每工具并发配额，超时重试可能重复生成文件，因此只可作为临时排障手段。

对外工具合同

导出提交工具

保留两个现有工具名及输入 Schema：

export_pending_outbound_orders
export_out_of_province_port_data

成功提交后统一返回：

{
  "code": "MCP_0000",
  "msg": "导出任务已提交",
  "data": {
    "task_ref": "mexp_xxx",
    "status": "queued",
    "retry_after_seconds": 10
  },
  "meta": {
    "request_id": "rq_xxx"
  }
}

task_ref 是带完整性校验的不可枚举引用，不是数据库主键。retry_after_seconds 只是调用建议，不代表精确完成时间，也不允许 Gateway 在原请求内等待。

提交阶段仍完成以下同步检查：

MCP Token、动态工具注册和 route_code。
对应后台菜单权限。
参数格式和组合关系。
当前公司和员工数据范围。
未排舱导出的单行数据存在性探测，或省外进港资料的全部号码解析和授权。

因此参数错误、无权限、目标不存在或无可导出数据仍立即返回现有安全业务错误，不创建队列任务。

`query_export_task`

新增工具：

工具名：query_export_task
路由：POST /mcp/tools/queryExportTask
必填参数：task_ref，字符串，最长 512 字符
每次只查询一个任务，不接受任务 ID、员工 ID、公司 ID 或批量数组

返回状态：

内部状态	对外状态	对外数据
`st_download_list.status=1`	`queued`	`task_ref`、建议重试秒数
`status=4`	`running`	`task_ref`、建议重试秒数
`status=2`	`completed`	`task_ref`、`files[].label/url`
`status=3`	`failed`	`task_ref`、固定安全失败提示

任务不存在、引用签名无效、任务不属于当前员工或公司、来源工具权限失效时，统一返回 “导出任务不可用”，不区分具体原因，避免枚举和越权探测。不得返回 st_download_list.remark。

query_export_task 自身先经过动态注册校验。Logic 再根据任务中记录的来源工具执行该导出的菜单权限检查；只有任务所属员工、公司和来源权限均仍有效时才返回状态或文件链接。

Gateway 展示

两个提交工具的 Presenter 白名单改为：

task_ref
status=queued
retry_after_seconds

query_export_task 的 Presenter 只接受四个已知状态。完成时复用现有导出 URL 和主机白名单校验；其他状态不得携带文件链接。未知字段、未知状态、畸形 URL 或未知错误继续关闭失败。

工具说明明确：

导出工具只负责提交任务。
收到 queued 后应告知用户任务已提交。
用户要求查看结果或经过建议等待时间后，才调用 query_export_task。
不得在一次工具调用内睡眠、循环轮询或并行创建相同任务。

CLI 保留 fmsoperate 原始 code/msg/data/meta 信封。

任务引用

task_ref 使用 mexp_ 前缀和 URL-safe Base64 编码，载荷至少包含：

task_id
create_user_id
company_id
source_tool
issued_at

载荷使用从 fmsoperate 专用 MCP_EXPORT.TASK_REF_SECRET 分别派生的 AES-256-CBC 加密密钥和 HMAC-SHA256 认证密钥，按 encrypt-then-MAC 生成不暴露内部 ID 的引用。密钥少于 32 字节、为空、解密失败或引用验签失败时关闭访问。验签使用恒定时间比较；解析失败不得记录完整引用。引用有效期固定为 7 天，超过有效期后要求用户重新提交导出。

签名只防止引用伪造，不替代数据库授权。查询时仍必须按以下条件读取：

id=task_id
create_user_id=当前员工
system_id=当前系统
export_params.company_id=当前公司
export_params.mcp_source_tool=source_tool

日志只记录任务数据库 ID 或引用短哈希中的一种内部关联值，不记录完整 task_ref。

fmsoperate 数据流

未排舱订单

McpPendingOutboundExportLogic 保留当前权限检查、参数归一化和单行探测。
服务端固定写入 export_type=EXPORT_PEND_OUTBOUND_ORDER、is_sync=0、当前员工和公司上下文及 mcp_source_tool。
创建 st_download_list 等待任务。
通过现有 RedisAction::EXPORT_PEND_OUTBOUND_ORDER 和 ExportPendOutboundOrder Handler 入队。
Worker 复用 ExportPendOutboundOrderLogic，按现有约定将状态从等待更新为执行中、完成或失败。
提交接口返回由任务 ID 和可信会话生成的 task_ref。

省外进港资料

McpOutOfProvincePortExportLogic 保留四类号码严格四选一、全部匹配和全部授权。
把已授权排舱 ID、资料类型、可信员工/公司上下文及 mcp_source_tool 写入任务参数。
创建 st_download_list 等待任务并推送新的专用 Redis Action/Handler。
Worker 把任务标记为执行中，调用从现有 ExportLogic::shangHaiExport() 抽出的可复用模板导出方法。
新的内部方法接受既有 task_id 作为 down_record_id，不得再次创建第二条 st_download_list 记录；后台现有 shangHaiExport() 对外行为保持不变。
Worker 根据模板响应更新同一任务的文件 URL、文件名、完成时间或安全失败状态。

省外进港 Worker 只接收提交阶段已经全部授权并固定下来的排舱 ID，不重新根据原始号码做模糊匹配。状态查询和链接交付阶段再次验证当前员工、公司及来源菜单权限。

队列失败

创建任务与入队不能组成单个数据库事务，因此采用补偿：

任务插入失败：不入队，返回系统繁忙。
入队返回失败或抛出异常：把任务标记为失败并返回系统繁忙。
Worker 异常：先把任务标记为失败，再重新抛给队列框架记录队列 Action、任务 ID 和内部异常；提交与查询的 request ID 继续由 st_mcp_access_log 保留，公共响应不返回异常。
Worker 重试必须以任务状态为门禁，完成任务不得重复生成文件。

去重与并发

提交前基于以下内容生成稳定 SHA-256 指纹：

当前公司 ID
当前员工 ID
来源工具
归一化后的业务参数

使用 Redis 原子 SET NX EX 建立 60 秒提交锁，并把已创建的任务 ID 保存为值。同一指纹在锁有效期内再次提交时返回同一个 task_ref，不重复插入或入队。入队失败时释放锁。

去重只覆盖客户端超时或快速重试，不缓存导出结果，不跨员工复用文件，也不改变用户在 60 秒后主动再次导出的能力。

安全边界

身份、公司、员工、超级管理员、时区和数据范围只来自 MCP Token 恢复的 Session。
外部请求不能提交 task_id、company_id、operator_id、is_super 或队列参数。
导出提交时做完整业务授权；状态查询和链接交付时再次检查任务归属和来源菜单权限。
任务引用验签、Redis、数据库或菜单查询失败时关闭访问。
Presenter 只输出固定状态、建议等待时间和安全文件链接。
不返回队列名、内部 Action、数据库主键、导出参数、失败备注、SQL 或异常栈。
st_mcp_access_log 继续记录每次提交和查询的独立 request ID 与安全响应。

注册与部署

新增 query_export_task 后，本地和公网 Gateway 候选工具由 12 个变为 13 个。需要同步：

Python 工具 metadata、双注册表、CLI 转发和 Presenter。
fmsoperate 路由、Validate、Controller、Logic、任务查询 Model。
fmsoperate 动态工具注册 SQL，首次插入默认 status=0，重复执行保留管理员现有状态。
新省外进港导出 Redis Action、配置和 Handler。
README 与集中仓当前需求、技术规格、用户流程和里程碑。

部署顺序：

部署 fmsoperate 代码及持续运行的 fmsoperate:inside Worker。
执行并核验新工具注册 SQL，由管理员决定是否启用。
部署并重启 MCP Gateway。
让 Workbuddy 重新连接；tools.listChanged=false 不会热更新 Schema。
分别用小数据和超过一分钟的数据验证提交、状态查询及下载。

不执行新的业务表 DDL。队列 Worker、Redis 和文件存储不可用时不得启用新合同。

测试与验收

fmsoperate

两个提交 Logic 验证参数、菜单、公司和数据范围后快速返回任务引用。
未排舱无数据、省外号码缺失/越权时不创建任务。
外部身份字段、任务 ID 和队列字段不能覆盖服务端值。
入队失败会把任务置为失败且不留下可再次执行的等待任务。
Worker 状态完整覆盖 queued -> running -> completed/failed。
省外进港异步导出只创建一条下载任务并复用原模板结果。
状态查询覆盖有效引用、篡改、过期、跨员工、跨公司、来源工具权限失效和任务不存在。
失败响应不包含 remark、异常或内部 ID。
相同员工和参数 60 秒内重试返回同一任务；不同员工或公司不共享。

MCP Gateway

stdio 和公网均注册 13 个同序工具，并受动态启用列表控制。
两个导出工具只接受规范的 queued 响应。
状态查询 Presenter 覆盖四种状态及完成文件链接。
非完成状态携带 URL、未知状态、未知字段和非法 URL 时关闭失败。
CLI 原样保留新的后端信封。
全量 unittest、语句和分支覆盖率继续为 100%。

时序验收

提交接口不等待实际文件生成，在正常数据库和 Redis 条件下应在短请求时间内返回。
模拟导出耗时超过 60 秒时，原提交 MCP 请求仍已正常结束。
导出过程中多次状态查询不会重复入队或生成文件。
完成后新的状态查询返回可下载文件，失败后返回固定安全提示。

回滚

先在动态注册表中关闭 query_export_task 和两个导出工具，阻止产生新合同调用。
已入队任务允许 Worker 完成；不要删除等待或执行中的 st_download_list 记录。
回滚 Gateway 和 fmsoperate 代码后重启 Gateway，并让客户端重新连接。
不依赖回滚 SQL；注册表状态由管理员保留，代码回滚期间关闭相关工具即可。

2026-07-22-mcp-async-export-task-design.md 13 KB Historia Czysty