mcp/docs/superpowers/specs/2026-07-17-order-detail-design.md

MCP 订单详情设计

目标

query_order_detail 按明确订单号读取 fmsoperate 后台订单详情页可见数据，同时保持员工菜单、公司和订单数据范围。Gateway 只定义工具 Schema 和中文展示 DTO，不复制 PHP 权限或业务查询。

调用合同

ThinkPHP 路由：POST /mcp/tools/queryOrderDetail

输入：

字段	规则
order_number	必填，去空后 1 至 100 字符
section	可选，默认“订单概览”，仅允许工具 Schema 中的中文枚举
page	1 至 100，默认 1
limit	1 至 100，默认 20

模块包括：订单概览、箱单信息、箱单商品、DW授权信息、附件信息、入库信息、查验信息、订单轨迹、操作日志、应收与结算日志、派送信息。

完整详情必须先查询订单概览，再逐一查询其他十个模块。分页模块持续查询到“是否还有更多”为否；一个模块为空不代表其他模块为空。

权限边界

每次调用都执行以下顺序：

设备/Token 会话
  -> 动态工具注册与 route_code
  -> admin/Order/index 菜单
  -> query_order_exact 同源父订单数据范围
  -> 服务端父订单 ID
  -> 目标 section

调用方不能提供订单 ID、公司/员工/角色、箱单 ID、查验 ID 或其他子资源 ID。不存在、跨公司和数据范围外订单使用相同的目标不可用结果。合作伙伴关联 ID 只能由已授权展示订单在服务端派生。

PHP 响应

PHP 使用固定机器结构供 Gateway 校验：

• 所有结果包含规范订单号、内部 section 和 payload。
• 概览 payload 固定包含状态节点、订单信息、货运信息、箱单汇总和进出口商。
• 普通模块固定包含 records。
• 入库和派送固定包含 summary 与 records。
• 分页信息只包含页码、每页数量和是否还有更多，不统计总数。

MySQL 模块在父订单重新授权后读取。Mongo 日志、轨迹接口和 track_db 无法加入同一快照，只能在授权成功后使用服务端派生参数访问。

中文展示

OutputPresenter 对顶层、分组、状态枚举和每行字段执行完整白名单校验。未知、缺失或多余字段均关闭失败。最终结构化结果和文本只使用中文业务键；机器字段、内部参数名及数据库 ID 不进入 AI 展示。

附件展示保留：附件分类、文件名称、文件类型、是否图片、预览链接、下载链接和收费项目。链接由 PHP 校验 HTTP(S) 协议与配置主机。商品图片、入库/测量照片和查验照片不返回链接或内容，只返回数量。Freight Tower 只返回地图是否可用，不返回含密钥的 iframe URL。

发布

1. 部署 fmsoperate 与 Gateway 代码。
2. 审核并执行 fmsoperate/sql/mcp_add_query_order_detail_tool.sql；首次注册默认 status=0，重复执行保留管理员状态。
3. 核对注册表 route_code 和预期 status。
4. 重启 Gateway，并让 Workbuddy 重新连接。
5. 使用有权、无权、跨公司和合作伙伴员工完成只读冒烟。

代码存在、测试通过或 SQL 文件存在均不表示目标环境已启用该工具。