# MCP 精准订单开放单号格式引导设计

## 背景

`query_order_exact` 通过字段说明和示例引导 AI 选择精准查询参数。现有说明虽然要求
单号类型不明确时先追问，但部分字段示例或说明仍可能让 AI 把 `USC`、`PC`、`SO`
等前缀误当成固定格式，并据此猜测号码类型。

实际业务中，订单号、客户参考号、快递单号、排舱单号、柜号、SO 号和
Shipment ID 都应视为开放格式。用户明确指定业务类型后，工具按对应字段原值精准
查询；格式、前缀、长度和字符组合不参与字段选择。

## 目标

- 所有单号只按用户明确指定的业务类型选择查询字段。
- 明确所有单号格式开放，禁止根据前缀、长度、字符组合或示例猜测类型。
- 保留含糊“单号”先追问、无结果不跨字段重试的现有规则。
- 保持 MCP 参数、PHP 查询、数据库字段和权限逻辑不变。

## 适用字段

统一规则覆盖以下单值字段及其现有批量字段：

- `order_number` / `order_numbers`
- `reference_number` / `reference_numbers`
- `tracking_number` / `tracking_numbers`
- `outbound_number` / `outbound_numbers`
- `container_code` / `container_codes`
- `so_number` / `so_numbers`
- `shipment_id`

`shipment_id` 当前没有批量字段，本次不新增。

## 方案

### 工具级规则

`query_order_exact` 总说明新增统一规则：所有单号格式均为开放格式，只能根据用户
明确说出的业务类型选择字段，不得根据号码的前缀、长度、字符组合或示例猜测。

### 字段说明

- 每个单值字段说明其业务含义，并要求用户明确指定该类型时使用。
- 批量字段继续表达“多个同类号码使用数组”，不声明固定格式。
- `outbound_number` 保留“排舱单号、不是海外仓出库单号”的业务区分，删除
  “以 `PC` 开头”的规则。
- `so_number` 说明格式不固定，只有用户明确说“SO号”时使用。

### 示例

- 示例只展示参数类型和调用形式，不代表格式规则。
- 排舱单号可继续使用 `PC...` 作为普通示例，但说明和测试不得把 `PC` 设为必要
  条件。
- SO 号单值示例使用纯数字 `97964454`；批量示例同时包含 `97964454` 和
  `OOLU12345678`，体现格式多样性。
- 其他现有示例可以保留，但不得用于推断或校验格式。

## 查询与错误处理

- 用户明确类型：直接使用对应字段精准查询。
- 用户只说“单号”或类型含糊：先追问，不调用工具猜测。
- 查询无结果：原样返回，不改用其他单号字段重试。
- Gateway 不新增正则、前缀、长度或字符集校验；现有非空、字符串长度和批量数量
  边界保持不变。

## 测试

元数据回归测试需要验证：

1. 工具总说明包含“所有单号格式开放”和禁止按前缀、长度、字符组合、示例猜测。
2. 排舱单号说明不再声明 `PC` 前缀规则，但仍使用正确业务名称并区分海外仓出库
   单号。
3. SO 号说明强调格式不固定和用户明确指定，单值/批量示例覆盖不同格式。
4. 所有单号字段名、Schema 类型和调用转发行为保持不变。

## 文档覆盖关系

本文覆盖 `2026-07-14-mcp-outbound-number-label-design.md` 中关于排舱单号必须以
`PC` 开头、示例必须全部使用 `PC` 前缀的要求。旧设计中“业务名称统一为排舱单号、
不是海外仓出库单号、字段名和查询链不变”的结论继续有效。