技术规格

技术栈与边界

Gateway：Python 3，核心运行模块只使用标准库；stdio 使用逐行 JSON-RPC，公网使用 ThreadingHTTPServer。
后端：ThinkPHP 6.0 + PHP 7.1+，按 Controller / Logic / Model / Validate 分层实现业务工具。
存储：Redis 保存本地 token 或公网 Gateway session；MySQL、MongoDB 和文件存储只由所属业务系统访问。
Gateway 不连接业务数据库；跨仓调用只通过明确的 HTTP 路由和服务端会话进行。

组件

组件	职责
`app.py`	本地 `GatewayApp`、stdio/CLI 入口、12 个工具注册与参数转发
`public_gateway.py`	公网 `PublicGatewayApp`、设备会话解析后的 scoped 调用、同组 12 个工具注册
`public_server.py`	`/mcp` HTTP JSON-RPC、可信追踪号、审计上下文、限流和 `/health`
`mcp_protocol.py`	MCP 握手、`tools/list`、`tools/call`、旧/新结果分流和协议错误
`services/api_client.py`	本地 token 上下文下的 ThinkPHP 工具请求与动态列表请求
`services/scoped_api_client.py`	公网请求级 `mcp_token` 转发，避免进程级身份串用
`services/gateway_session_store.py`	`GWS_xxx` 到服务端员工会话的 Redis 映射
`services/output_presenter.py`	11 个安全工具的白名单 DTO、错误映射和文本渲染
`tools/*.py`	工具名称、说明、输入 Schema、路由和调用封装

本地与公网会话

本地 stdio 流程：

GatewayApp 从 Redis 或开发用文件 store 读取本机 session。
token 临近过期时通过 base 刷新。
tools/list 和 tools/call 携带该 token 请求 fmsoperate。

公网流程：

Workbuddy 通过 Header、Bearer 或 Cookie 提交 GWS_xxx。
RequestContextParser 提取设备凭据，GatewaySessionStore 从 Redis 获取服务端 mcp_token。
PublicGatewayApp 为单次请求创建 scoped API 调用上下文，不把 token 放进进程全局状态。
fmsoperate 再校验 token、员工状态、公司、工具权限和业务数据范围。

会话缺失、过期或后端动态列表不可用时关闭访问。公网不得使用文件 token store、固定 FMS_SESSION_KEY 或共享进程级员工 token。

动态工具可见性

GatewayApp 与 PublicGatewayApp 的候选注册顺序和名称必须完全一致，当前各为 12 个。
tools/list 调用 /mcp/tools/listEnabledTools，只返回本地注册与后端启用代码的交集。
tools/call 重新读取启用集合，避免工具被禁用后继续调用。
MCP 返回 tools.listChanged=false，因此工具或 Schema 变更必须通过 Gateway 重启和客户端重连刷新。

Presenter 分类

query_order 走旧协议分支，保留 columns/records/meta 和既有文本行为。OutputPresenter.SAFE_TOOLS 显式处理其余 11 个工具：

类型	工具	DTO
表格	`query_order_exact`、`query_track`、`query_customs_declaration_files`、`query_outbound_list`	`headers + rows + pagination`
排舱详情	`query_outbound_detail`	`summary + details`，分页位于 `details.pagination`
订单详情	`query_order_detail`	中文订单号、详情模块、固定概览分组或明细及分页
筛选项	`list_order_filter_options`、`list_outbound_filter_options`、`list_pending_outbound_export_filter_options`	`value + label + code` 三列
导出	`export_pending_outbound_orders`、`export_out_of_province_port_data`	`files[].label + files[].url`

Presenter 对列定义、记录类型、详情汇总、附件结构和导出 URL 做白名单校验。未知工具、未允许列、畸形响应或未知异常返回安全 isError=true；真实异常仅记录在服务端日志。后端业务错误映射为固定消息，不透传原始 msg/data。

订单详情 Presenter 不依赖原始请求参数，而是校验后端规范 section、固定分组及每行完整键集合。“全部”响应校验概览和十个明细分组，并将每个明细分组的分页信息独立展示。状态和时间类型只接受已知枚举；入库重量根据后端固定模式显示为单箱重量或总重量。

追踪、日志与限流

stdio 自动生成 rq_*；公网入口始终生成可信 rq_http_*，不采信调用方 X-Request-Id。
调用方 X-Request-Id 只记录 SHA-256 短哈希 client_request_id_hash，用于关联客户端反馈。
追踪号贯穿动态工具列表、工具调用、MCP _meta 和结构化日志。
审计日志只记录必要的 request/jsonrpc ID、协议方法、工具代码、员工/公司标识和脱敏客户端标识；禁止记录凭据与原始响应。
initialize 与 tools/list 不进入限流器；tools/call 使用 gateway_session_id + tool_name 分桶，并通过 FMS_MAX_IN_FLIGHT_PER_TOOL 控制可释放的同时执行数。FMS_RATE_LIMIT_MAX_REQUESTS=0 时关闭累计窗口限制，超限统一返回 JSON-RPC -32029。
限流配置为 FMS_RATE_LIMIT_ENABLED、FMS_RATE_LIMIT_MAX_REQUESTS、FMS_RATE_LIMIT_WINDOW_SECONDS；生产环境还应在反向代理层限流。

关键业务参数

query_outbound_list.outbound_status 必填，只暴露后台业务阶段；shipping_method 无默认值，未传表示全部运输方式。
query_order_detail.order_number 必填；section 接受 11 个中文模块或“全部”，页码和每页数量均为 1 至 100。
query_outbound_list.warehouse_id 接受正整数或 -1（客户仓），拒绝 0 与其他负数。
list_outbound_filter_options.filter_type 使用七个中文枚举；仓库分支由 fmsoperate 复用 OrderModel::getSortWarehouse()，所有分支先校验 admin/Outbound/index。
排舱筛选响应保留 value/label/code 供跨工具传参，面向用户只展示中文标签。

验证基线

python -m unittest discover -s tests -p "test_*.py"
python -m coverage run -m unittest discover -s tests -p "test_*.py"
python -m coverage report -m --fail-under=100
git diff --check

运行 coverage 会更新本地 .coverage 文件；只做文档治理时使用已有只读报告，不应制造覆盖率产物变更。

tech-specs.md 6.1 KB Historia Czysty