mcp/project-docs/overview.md

项目概述

项目定位

mcp 是物流货运系统面向 Workbuddy 的 Python MCP Gateway。它负责 MCP 工具 Schema 与注册、stdio/public 协议适配、设备会话转发、安全展示 DTO、追踪日志和运行手册，不拥有物流业务规则。

Gateway 保持薄边界：不直连业务数据库，不在 Python 中复制员工、公司、菜单或数据权限。员工身份、工具权限和业务数据范围由 ThinkPHP 在每次请求中最终校验。

当前能力

本地 GatewayApp 与公网 PublicGatewayApp 注册同一组 12 个候选工具：

类别	工具
订单与轨迹	query_order、query_order_exact、query_order_detail、query_track
报关与排舱	query_customs_declaration_files、query_outbound_list、query_outbound_detail
筛选项	list_outbound_filter_options、list_order_filter_options、list_pending_outbound_export_filter_options
导出	export_pending_outbound_orders、export_out_of_province_port_data

候选注册不代表员工一定可见。实际工具集合是本地注册集合与 fmsoperate 动态启用列表的交集，并继续受员工权限与数据范围约束。动态列表不可用或格式异常时关闭访问。

query_order 保持旧响应兼容；其余 11 个工具由 services/output_presenter.py 转为中文白名单展示 DTO。订单详情按固定中文模块展示，图片附件保留文件名和安全链接，机器字段及内部 ID 关闭失败。所有工具遵守零推断边界：结果意图或号码业务类型不明确时先询问，禁止按格式猜测、并行试查或失败后跨字段、跨工具重试。

跨仓职责

仓库	所有权
Y:/mcp	工具 Schema、双注册表、协议、展示、Gateway 会话转发、运行与排障入口
Y:/fmsoperate	工具路由、Validate/Logic/Model、动态注册表、业务权限、数据范围、导出和访问日志
Y:/base	员工身份、设备会话、MCP token 生命周期和认证决策
Y:/home	员工入口 UI 与薄代理，不承载认证或物流业务逻辑
Y:/settlement_tests	跨仓 PHP 合同测试

文档权威层

1. 代码与运行时数据决定真实行为：代码给出候选注册和合同，fmsoperate 当前启用值决定实际可见工具。
2. README.md 是接入、工具目录、配置、运维和排障入口。
3. project-docs/ 五件套记录现行产品、协议、架构、流程和短里程碑。
4. AGENTS.md 只记录 AI 必须遵守的所有权、红线和协作规则。
5. 临时规划和已完成的执行计划不属于权威层；交付后把稳定事实并回上述入口，并清理过程文件。

当前交接状态

用户已确认 Y:/fmsoperate/sql 原有 10 个 MCP SQL 与 Y:/base/sql 的 5 个 MCP SQL 均已执行。订单详情注册 SQL 尚待目标环境执行；仓库仍无法静态判断动态注册表当前启用值、运行中 Gateway 是否已重启、Workbuddy 是否已重新连接，这些状态必须从部署环境核验。