mcp/docs/superpowers/specs/2026-07-14-mcp-outbound-number-label-design.md

MCP 排舱单号字段文案统一设计

部分废止： 本文关于排舱单号“以 PC 开头”以及示例必须使用 PC 前缀的要求，已被 2026-07-14-mcp-open-number-format-guidance-design.md 覆盖。保留“业务名称统一为 排舱单号、不是海外仓出库单号、字段名和查询链不变”的结论。

背景

query_order_exact 使用 outbound_number 和 outbound_numbers 查询 fms_outbound.outbound_number。当前工具说明将该字段称为“出库单号”，但业务页面 使用的准确名称是“排舱单号”，容易使 AI 和员工误解字段含义。

目标

• 对外说明统一使用“排舱单号”。
• 说明排舱单号以 PC 开头，并使用真实格式的示例。
• 明确该字段不是海外仓出库单号，减少号码类型误判。
• 保持现有接口和查询行为不变。

方案

保留 outbound_number 和 outbound_numbers 字段名，因为它们已经与数据库字段、 Python Gateway、PHP 校验及查询逻辑对齐。仅修改以下文案和回归断言：

1. outbound_number 说明改为单个排舱单号精准查询，注明号码以 PC 开头， 示例使用 PC20210331070002001，并提示不是海外仓出库单号。
2. outbound_numbers 说明改为多个排舱单号批量精准查询，示例中的每个号码均以 PC 开头。
3. 工具总说明中的“出库单号”改为“排舱单号”。
4. 工具元数据测试断言同步改为“排舱单号”，并验证区分海外仓出库单号的提示。
5. 项目文档记录本次业务术语修正。

不在范围内

• 不根据 PC 前缀在 Gateway 增加格式校验；号码是否合法仍由精准查询结果判断， 避免阻断历史数据或特殊业务数据。
• 不修改数据库字段名。
• 不修改 MCP 入参或返回字段名。
• 不修改 PHP 查询、校验和权限逻辑。
• 不把 outbound_date_start、outbound_date_end 的“出库日期”改为“排舱日期”； 日期字段与本次单号术语修正不是同一业务概念。

验证

• 运行 tests.test_query_order_exact_tool，确认工具元数据文案正确，且单值、批量 示例都使用 PC 前缀。
• 运行 Python Gateway 全量单元测试，确认字段结构和调用行为无回归。
• 搜索 query_order_exact 相关说明，确认不再将 outbound_number(s) 标注为 “出库单号”。