# 项目概述

## 项目定位

`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 是否已重新连接，这些状态必须从部署环境核验。