# MCP 工具接口文档

> 本文仅描述当前 Gateway 注册的工具接口。实际可用工具是本地注册集合与服务端启用列表的交集；员工、公司、权限和数据范围由当前设备会话决定。

## 订单与轨迹

### query_order（订单兼容搜索）

路由：`POST /mcp/tools/queryOrder`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 搜索关键词 | `keyword` | string | 是 | 非空；仅用户明确接受跨字段搜索时使用 |
| 页码 | `page` | integer | 否 | 最小 1 |
| 每页数量 | `limit` | integer | 否 | 1-100 |

### query_order_exact（订单精准筛选）

路由：`POST /mcp/tools/queryOrderExact`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 订单号 / 客户参考号 / 快递单号 / 排舱单号 / 柜号 / SO号 / Shipment ID | `order_number`、`reference_number`、`tracking_number`、`outbound_number`、`container_code`、`so_number`、`shipment_id` | string | 否 | 单值精准条件；号码类型必须明确 |
| 收货国家 | `receiver_country` | string | 否 | 国家代码，值来自订单筛选项 |
| 入库开始日期 / 入库结束日期 | `inbound_date_start`、`inbound_date_end` | string | 否 | `YYYY-MM-DD` |
| 出库开始日期 / 出库结束日期 | `outbound_date_start`、`outbound_date_end` | string | 否 | `YYYY-MM-DD` |
| 产品ID / 客户ID / 仓库ID | `product_ids`、`customer_ids`、`warehouse_ids` | integer[] | 否 | ID 数组，值来自订单筛选项 |
| 订单号数组 / 客户参考号数组 / 快递单号数组 / 排舱单号数组 / 柜号数组 / SO号数组 | `order_numbers`、`reference_numbers`、`tracking_numbers`、`outbound_numbers`、`container_codes`、`so_numbers` | string[] | 否 | 同类号码批量查询；不能与对应单值字段混用 |
| 销售人员ID / 事业部ID | `sales_id`、`department_id` | integer | 否 | 最小 1，值来自订单筛选项 |
| 页码 | `page` | integer | 否 | 1-100 |
| 每页数量 | `limit` | integer | 否 | 1-100 |

至少提供一个业务筛选条件。

### query_order_detail（订单详情）

路由：`POST /mcp/tools/queryOrderDetail`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 订单号 | `order_number` | string | 是 | 非空，最长 100；只接受订单号 |
| 详情模块 | `section` | string | 否 | 默认“全部”；可选订单概览、箱单信息、箱单商品、DW授权信息、附件信息、入库信息、查验信息、订单轨迹、操作日志、应收与结算日志、派送信息、全部 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_track（物流轨迹）

路由：`POST /mcp/tools/queryTrack`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 内部订单ID | `order_id` | integer | 否 | 最小 1；仅可信系统上下文可用 |
| 订单号 | `order_number` | string | 否 | 用户明确提供订单号时使用 |
| 快递/物流跟踪号 | `tracking_number` | string | 否 | 用户明确提供跟踪号时使用 |
| 页码 | `page` | integer | 否 | 默认 1，最小 1 |
| 每页数量 | `limit` | integer | 否 | 默认 5，1-100 |

三种定位参数应选择一种，不能猜测号码类型。

### query_order_receivable_cost_details（订单应收费用明细）

路由：`POST /mcp/tools/queryOrderReceivableCostDetails`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 订单号 | `order_number` | string | 是 | 非空，最长 100 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_receivable_cost_list（应收费用单列表）

路由：`POST /mcp/tools/queryReceivableCostList`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 参考号 / 跟踪号 / 订单号 / 账单号数组 | `reference_numbers`、`tracking_numbers`、`order_numbers`、`bill_numbers` | string[] | 条件必填 | 同类 OR、不同类 AND；合计最多 200 项，每项最长 100；号码类型必须明确 |
| 业务日期开始 / 结束 | `business_date_start`、`business_date_end` | string | 条件必填 | 无号码数组时必须成对提供；员工时区 `YYYY-MM-DD` 闭区间，最多 31 天 |
| 主客户 / 子客户 | `customer_id`、`sub_customer_id` | integer | 否 | 严格正整数；子客户要求同时提供主客户 |
| 出账状态 | `billing_status` | integer | 否 | `0` 未出账（DB 0/1）、`1` 已出账（DB 1/2） |
| 核销状态 | `verification_status` | integer | 否 | `-1`、`0`、`1` |
| 单据类型 / 费用项 | `document_type`、`cost_type_id` | integer | 否 | 单据类型可为 0；费用项为正整数；值来自筛选工具 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

## 客户与回款

### query_customer_list（客户列表）

路由：`POST /mcp/tools/queryCustomerList`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 客户ID / 事业部ID / 商务经理ID / 客户经理ID | `customer_id`、`department_id`、`sales_id`、`merchandiser_id` | integer | 否 | 最小 1；ID 来自客户筛选项 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_customer_payment_followup（客户回款跟进）

路由：`POST /mcp/tools/queryCustomerPaymentFollowup`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 客户ID / 事业部ID / 商务经理ID / 客户经理ID | `customer_id`、`department_id`、`sales_id`、`merchandiser_id` | integer | 否 | 最小 1，值来自客户筛选项 |
| 仅看有未核销应收 | `has_unverified_receivable_only` | boolean | 否 | 默认 `true` |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_customer_unverified_bill_details（未核销账单明细）

路由：`POST /mcp/tools/queryCustomerUnverifiedBillDetails`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 客户ID | `customer_id` | integer | 是 | 最小 1，先从客户筛选项取得 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_customer_payment_records（客户逐笔回款记录）

路由：`POST /mcp/tools/queryCustomerPaymentRecords`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 客户ID | `customer_id` | integer | 是 | 最小 1，先从客户名称筛选取得 |
| 收款开始日期 / 收款结束日期 | `receive_date_start`、`receive_date_end` | string | 否 | `YYYY-MM-DD`；闭区间最多 366 天 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### list_customer_filter_options（客户筛选项）

路由：`POST /mcp/tools/listCustomerFilterOptions`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 筛选类型 | `filter_type` | string | 是 | 客户名称、事业部、商务经理、客户经理 |
| 关键词 | `keyword` | string | 否 | 最长 100 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### list_receivable_cost_filter_options（应收费用单筛选项）

路由：`POST /mcp/tools/listReceivableCostFilterOptions`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 筛选类型 | `filter_type` | string | 是 | 主客户、子客户、出账状态、核销状态、单据类型、费用项 |
| 主客户ID | `customer_id` | integer | 条件必填 | `filter_type=子客户` 时必填，其他类型禁止传入 |
| 关键词 | `keyword` | string | 否 | 最长 100 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

## 排舱与报关

### query_outbound_list（排舱列表）

路由：`POST /mcp/tools/queryOutboundList`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 排舱阶段 | `outbound_status` | integer | 是 | 枚举 20、30、60、70、80、90、100、110、120；必须明确阶段 |
| 排舱单号数组 / 订单号数组 / 柜号数组 / SO号数组 / 提单号数组 | `outbound_numbers`、`order_numbers`、`container_codes`、`so_numbers`、`bl_numbers` | string[] | 否 | 各 1-100 项；号码类型必须明确 |
| 运输方式 | `shipping_method` | integer | 否 | 枚举 1、2、3 |
| 集货仓库 | `warehouse_id` | integer/string | 否 | 值来自排舱筛选项 |
| 是否直送柜 | `is_direct_send` | integer | 否 | 枚举 0、1 |
| 拖车方式 / 报关方式 / 清关方式 | `trailer_types`、`declaration_types`、`clearance_types` | integer[] | 否 | 每项 1-2 个 |
| 截关时间、预计装柜时间、创建时间、装柜时间（开始/结束） | `closing_time_start`、`closing_time_end`、`est_loading_time_start`、`est_loading_time_end`、`create_date_start`、`create_date_end`、`loading_time_start`、`loading_time_end` | string | 否 | 时间字符串最长 19 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### query_outbound_detail（排舱详情）

路由：`POST /mcp/tools/queryOutboundDetail`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 排舱单号 | `outbound_number` | string | 是 | 非空，最长 100 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 10，1-20 |

### query_customs_declaration_files（报关资料文件）

路由：`POST /mcp/tools/queryCustomsDeclarationFiles`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 订单号数组 | `order_numbers` | string[] | 条件必填 | 与排舱单号数组二选一；1-100 项 |
| 排舱单号数组 | `outbound_numbers` | string[] | 条件必填 | 与订单号数组二选一；1-100 项 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### list_outbound_filter_options（排舱筛选项）

路由：`POST /mcp/tools/listOutboundFilterOptions`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 筛选类型 | `filter_type` | string | 是 | 排舱阶段、运输方式、集货仓库、是否直送柜、拖车方式、报关方式、清关方式 |
| 关键词 | `keyword` | string | 否 | 最长 100 |
| 页码 | `page` | integer | 否 | 默认 1，1-100 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

### list_order_filter_options（订单筛选项）

路由：`POST /mcp/tools/listOrderFilterOptions`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 筛选类型 | `filter_type` | string | 是 | `country`、`product`、`customer`、`sales`、`warehouse`、`department` |
| 关键词 | `keyword` | string | 否 | 关键词 |
| 页码 | `page` | integer | 否 | 最小 1 |
| 每页数量 | `limit` | integer | 否 | 1-100 |

## 导出

### export_pending_outbound_orders（未排舱订单异步导出）

路由：`POST /mcp/tools/exportPendingOutboundOrders`

所有字段均为非必填；筛选名称或 ID 必须先通过 `list_pending_outbound_export_filter_options` 获取。

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 订单号或客户参考号 | `number` | string | 否 | 多值用空格、英文逗号或换行分隔 |
| 产品分类ID / 集货仓库ID / 进口商ID | `product_type_id`、`order_warehouse_id`、`importer_id` | integer | 否 | 筛选 ID |
| 物流产品ID数组 / 订单状态数组 | `product_id`、`status` | integer[] | 否 | 筛选数组 |
| 目的国 / 派送地址 / 入库时间范围 / 合并报关单号 / 货物类型 | `receiver_country`、`address`、`inbound_date`、`merge_declare_number`、`packing_type` | string | 否 | 入库时间格式 `YYYY-MM-DD - YYYY-MM-DD` |
| 是否装柜剔除 | `is_remove` | integer | 否 | 枚举 0、1 |
| 商品属性（带电、带磁、带木、其它、FDA、玩具、超长超重、敏感货、食品、无属性） | `is_battery`、`is_magnetic`、`is_wood`、`is_other`、`is_fda`、`is_toy`、`is_ultra_limit`、`is_sensitive`、`is_food`、`no_property` | string | 否 | 选中时传 `Y` |

### export_out_of_province_port_data（省外进港资料异步导出）

路由：`POST /mcp/tools/exportOutOfProvincePortData`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 资料类型 | `file_type` | string | 是 | `NB` 宁波、`SH` 上海、`MS` 美森 |
| 排舱单号数组 / 柜号数组 / 提单号数组 / SO号数组 | `outbound_numbers`、`container_codes`、`bl_numbers`、`so_numbers` | string[] | 条件必填 | 四选一；每项 1-100 个；号码类型必须明确 |

### export_receivable_cost_list（应收费用单列表异步导出）

路由：`POST /mcp/tools/exportReceivableCostList`

筛选合同与 `query_receivable_cost_list` 相同，但不接受 `page/limit/ids`。成功只返回 `task_ref + queued + retry_after_seconds`；稍后单独调用 `query_export_task`，禁止一次调用内轮询。

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 参考号 / 跟踪号 / 订单号 / 账单编号 | `reference_numbers`、`tracking_numbers`、`order_numbers`、`bill_numbers` | string[] | 条件必填 | 四类合计最多 200；或改用业务日期 |
| 业务发生开始/结束日期 | `business_date_start`、`business_date_end` | date | 条件必填 | 无号码时必填；闭区间最多 31 天 |
| 主客户 / 子客户 / 出账状态 / 核销状态 / 单据类型 / 费用项 | `customer_id`、`sub_customer_id`、`billing_status`、`verification_status`、`document_type`、`cost_type_id` | integer | 否 | 子客户必须带主客户；筛选值来自列表筛选项工具 |

### query_export_task（查询导出任务）

路由：`POST /mcp/tools/queryExportTask`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 导出任务引用 | `task_ref` | string | 是 | 只能使用导出工具返回值，1-512 字符 |

### list_pending_outbound_export_filter_options（未排舱导出筛选项）

路由：`POST /mcp/tools/listPendingOutboundExportFilterOptions`

| 中文参数名 | 参数名 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|---|
| 筛选项类型 | `filter_type` | string | 是 | `product_type`、`product`、`warehouse`、`country`、`importer`、`packing_type`、`order_status`、`goods_attribute`、`is_remove` |
| 产品分类ID | `product_type_id` | integer | 否 | 查询物流产品时使用 |
| 关键词 | `keyword` | string | 否 | 名称或编码关键词 |
| 页码 | `page` | integer | 否 | 默认 1，最小 1 |
| 每页数量 | `limit` | integer | 否 | 默认 20，1-100 |

## 返回参数

展示字段以 `services/output_presenter.py` 白名单为准：除 `query_order` 外，其余工具只暴露白名单中文键；未知字段关闭失败。成功结果位于 `tools/call` 的 `result.structuredContent`（另有文本 `content`），并带 `_meta.request_id`。

通用分页（多数表格工具）：

| 展示名 | 字段 | 类型 | 说明 |
|---|---|---|---|
| 页码 | `page` | integer | 当前页，1-100 |
| 每页数量 | `limit` | integer | 当前页大小 |
| 是否还有更多 | `has_more` | boolean | 是否还有下一页 |

订单详情工具内的分页键为中文：`页码`、`每页数量`、`是否还有更多`。

### query_order

兼容旧格式，不经 Presenter 白名单：`columns`（列名数组）、`records`（记录数组）；具体列由后端旧接口决定。

### query_order_exact

结构：`summary`（可选文本）、`headers`、`rows`、`pagination`、`tips`（可选）。`rows` 与 `headers` 列序一一对应；后端可返回白名单子集。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 订单号 | `order_number` | |
| 客户参考号 | `reference_number` | |
| 状态 | `status_txt_name` | |
| 是否已查验 | `check_status_txt_name` | |
| 客户名称 | `customer_name` | |
| 客户属性 | `customer_account_type_name` | |
| 入库时间 | `inbound_date` | |
| 未完成工单 | `wo_num` | |
| 物流产品 | `product_name` | |
| 件数 | `inbound_pieces` | |
| 体积(CBM) | `inbound_volume` | |
| 重量(KG) | `inbound_weight` | |
| 品名 | `pro_cn_name` | |
| 报关方式 | `export_declaration_type` | |
| 合并报关单号 | `merge_declare_number` | |
| 派送地址 | `delivery_address` | |
| 柜号 | `container_code` | |
| 排舱单状态 | `out_status_txt` | |
| 目的港 | `hinge_of_destination` | |
| ETD | `etd` | |
| ATD | `atd` | |
| ETA | `eta` | |
| ATA | `ata` | |
| 清关放行时间 | `release_time` | |
| 海外入库时间 | `oversea_inbound_date` | |
| APPT时间 | `appt_time` | |
| 预计装柜时间 | `est_loading_time` | |
| 海外提柜时间 | `pickup_time` | |
| 派送方式 | `delivery_way_title` | |
| 快递单号 | `tracking_number` | header 可带 description：承运商跟踪号码 |
| Shipment ID | `shipment_id` | |
| 商品属性 | `goods_attribute` | |
| SKU | `sku` | |
| 商务经理 | `sales_user` | |
| 客户经理 | `service_user` | |
| 事业部 | `department_name` | |
| 订单备注 | `remark` | |
| 进口商 | `importer_name` | |
| 交货仓库 | `warehouse_name` | |
| 付款状态 | `paid_status_name` | |

### query_track

结构：`headers`、`rows`、`pagination`、`tips`（可选）。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 轨迹节点 | `status` | 轨迹状态，如开始集港、离港放行等 |
| 轨迹地点 | `location` | 发生地点 |
| 时间 | `time` | 已转换为用户时区 |
| 轨迹内容 | `content` | 详细描述 |
| 跟踪号 | `tracking_number` | 快递单号 |
| Shipment ID | `shipment_id` | 包裹 ID |

### query_customs_declaration_files

结构：`headers`、`rows`、`pagination`、`tips`（可选）。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 排舱单号 | `outbound_number` | |
| 订单号 | `order_number` | |
| 文件名 | `file_name` | |
| 文件类型 | `file_type` | |
| 文件链接 | `file_url` | 安全下载/预览链接 |

### query_outbound_list

结构：`headers`、`rows`、`pagination`、`tips`（可选）。固定白名单 31 列（后端返回子集时按实际列展示）。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 排舱单号 | `outbound_number` | |
| 直送柜 | `direct_send` | |
| 备注 | `remark` | |
| 超长超重 | `cargo_type` | |
| 集货仓库 | `warehouse_name` | |
| 状态 | `status` | |
| SO号 | `so_number` | |
| 柜号 | `container_code` | |
| 封条号 | `seal_number` | |
| 柜型 | `container_type` | |
| 运输方式 | `shipping_method` | |
| 体积(CBM) | `total_volume` | |
| 重量(KG) | `total_weight` | |
| 船期 | `ship_schedule` | |
| 截关时间 | `closing_time` | |
| 预计装柜时间 | `est_loading_time` | |
| 操作人 | `operator` | |
| 拖报清方式 | `operation_modes` | |
| 操作时间 | `operation_time` | |
| 船司 | `ship_company` | |
| 船名航次 | `vessel_name` | |
| 截SI时间 | `cutoff_time_si` | |
| 清关口岸 | `clearance_port` | |
| 起运港 | `loading_port` | |
| 目的港 | `destination_port` | |
| 中转港 | `transit_port` | |
| ETD | `etd` | |
| ETA | `eta` | |
| 是否含FDA认证商品 | `has_fda` | |
| 是否含CPSC商品 | `has_cpsc` | |
| 是否含食品 | `has_food` | |

### query_outbound_detail

结构：

| 顶层键 | 说明 |
|---|---|
| `summary.headers` / `summary.row` | 排舱汇总：11 项，headers 与 row 一一对应 |
| `details.headers` / `details.rows` | 订单明细表 |
| `details.pagination` | 明细分页（英文键） |
| `details.tips` | 可选提示 |

汇总字段：

| 展示名 | 后端字段 |
|---|---|
| 提单号 | `bl_number` |
| 柜号 | `container_code` |
| 柜型 | `container_type` |
| 总体积 | `total_volume` |
| 总重量 | `total_weight` |
| 总件数 | `total_pieces` |
| SKU | `sku` |
| 买单报关数量 | `buy_declaration_count` |
| 一般贸易报关数量 | `general_declaration_count` |
| 必装单量/体积 | `must_load` |
| 备装单量/体积 | `backup_load` |

明细字段：

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 订单号 | `order_number` | |
| 超长超重 | `cargo_type` | |
| 报关资料 | `customs_files` | 数组，每项含 `文件名称`、`文件类型`、`文件链接` |
| 客户参考号 | `reference_number` | |
| 客户名称 | `customer_name` | |
| 报关方式 | `declaration_type` | |
| 合并报关单号 | `merge_declare_number` | |
| 订单备注 | `order_remark` | |
| 提单号 | `bl_number` | |
| 柜号 | `container_code` | |
| 客户经理 | `customer_service` | |
| 预计入库时间 | `est_inbound_date` | |
| 实际入库时间 | `inbound_date` | |
| 状态 | `status` | |
| 预报件数 / 入库件数 | `pieces` | |
| 预报实重(KG) / 入库实重(KG) | `weight` | |
| 预报体积(m³) / 入库体积(m³) | `volume` | |
| 交货地 | `pickup_place` | |
| 物流产品 | `product_name` | |
| 品名 | `goods_name` | |
| 截关时间 | `closing_time` | |
| 报关备注 | `clearance_remark` | |
| 清关备注 | `import_clearance_remark` | |
| 派送地址 | `delivery_address` | |
| 派送类型 | `delivery_type` | |
| 派送方式 | `delivery_way` | |
| 派送渠道 | `channel` | |
| 目的国 | `country_name` | |
| 进口商 | `importer_name` | |
| 清关税号 | `vat_type` | |
| 货物类型 | `packing_type` | |
| 是否问题件 | `is_abnormal` | |
| 包装类型 | `package_method` | |
| 到货回复 | `order_reply` | |
| 订单是否必装 | `is_must_load` | |
| 是否含FDA认证商品 | `has_fda` | |
| 是否含CPSC商品 | `has_cpsc` | |
| 是否含食品 | `has_food` | |

### query_order_detail

顶层固定：`订单号`、`详情模块`；再按 `section` 展开中文模块。分页键为 `页码` / `每页数量` / `是否还有更多`。

| section 入参 | 详情模块展示名 | 主要返回块 |
|---|---|---|
| `overview` | 订单概览 | `状态节点`、`订单信息`、`货运信息`、`箱单汇总`、`进出口商` |
| `packages` | 箱单信息 | `明细`、`分页` |
| `package_items` | 箱单商品 | `明细`、`分页` |
| `dw_auth` | DW授权信息 | `明细`、`分页` |
| `attachments` | 附件信息 | `明细`、`分页` |
| `inbound` | 入库信息 | `入库概况`、`明细`、`分页` |
| `checks` | 查验信息 | `明细`、`分页` |
| `tracks` | 订单轨迹 | `明细`、`分页` |
| `operation_logs` | 操作日志 | `明细`、`分页` |
| `cost_logs` | 应收与结算日志 | `明细`、`分页` |
| `delivery` | 派送信息 | `派送汇总`、`明细`、`分页` |
| `all` | 全部 | `订单概览` + 上表其余各模块 |

状态节点字段：

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 阶段 | `stage` | |
| 节点 | `label` | |
| 状态 | `state` | 映射为：已完成 / 进行中 / 待完成 / 不展示 |
| 时间 | `occurred_at` | |
| 时间类型 | `time_kind` | 映射为：实际 / 预计 / 暂无 |

订单概览 — 订单信息：

| 展示名 | 后端字段 |
|---|---|
| 订单号 | `order_number` |
| 客户参考号 | `reference_number` |
| 客户名称 | `customer_name` |
| 起运国 | `departure_country` |
| 目的国 | `destination_country` |
| 包装类型 | `package_method` |
| 物流产品 | `product_name` |
| 预报件重体 | `forecast_pwv` |
| 入库件重体 | `inbound_pwv` |
| 应收计费重/体积 | `receivable_charge_weight` |
| 结算计费重/体积 | `settlement_charge_weight` |
| 报关类型 | `declaration_type` |
| 是否需要预录单 | `pre_recording` |
| 企业/个人姓名 | `idcard_name` |
| 社会信用代码/身份证号 | `idcard_number` |
| 排舱单号 | `outbound_number` |
| 直送柜/拼柜 | `container_mode` |
| 是否可查看轨迹地图 | `track_map_available` |
| 购买保险 | `insurance` |
| 派送方式 | `delivery_way` |
| 退运附加 | `return_shipping_surcharge` |
| 工单数量 | `work_order_count` |
| 账单备注 | `bill_remark` |
| 订单备注 | `remark` |

订单概览 — 货运信息：

| 展示名 | 后端字段 |
|---|---|
| 预计入库时间 | `estimated_inbound_time` |
| 货物类型 | `cargo_type` |
| 交货方式 | `pickup_way` |
| 交货仓库 | `warehouse` |
| 提货地址 | `pickup_address` |
| 提货联系人 | `pickup_contact` |
| 提货联系电话 | `pickup_phone` |
| 派送类型 | `delivery_type` |
| 派送地址 | `delivery_address` |
| 派送备注 | `delivery_remark` |
| 海外仓 | `oversea_warehouse` |

订单概览 — 箱单汇总：

| 展示名 | 后端字段 |
|---|---|
| 箱数 | `box_count` |
| 重量 | `total_weight` |
| 重量单位 | `weight_unit` |
| 体积 | `total_volume` |
| SKU数量 | `sku_count` |
| 清关总价 | `clearance_total_price` |
| 清关币种 | `clearance_currency` |
| 采购总价 | `purchase_total_price` |
| 采购币种 | `purchase_currency` |

订单概览 — 进出口商：

| 展示名 | 后端字段 |
|---|---|
| 出口商 | `exporter` |
| 进口商 | `importer` |
| 是否做产地证 | `coo_required` |

箱单信息明细：

| 展示名 | 后端字段 |
|---|---|
| SHIPMENT ID | `shipment_id` |
| REFERENCE ID | `reference_id` |
| SKU | `sku_summary` |
| 商品名 | `product_name_summary` |
| 箱数 | `box_quantity` |
| 单箱长(CM) | `box_length_cm` |
| 单箱宽(CM) | `box_width_cm` |
| 单箱高(CM) | `box_height_cm` |
| 单箱毛重量(KG) | `gross_weight_kg` |
| 单箱净重量(KG) | `net_weight_kg` |
| 长度是否超限 | `is_over_length` |
| 宽度是否超限 | `is_over_width` |
| 高度是否超限 | `is_over_height` |
| 重量是否超限 | `is_over_weight` |

箱单商品明细：

| 展示名 | 后端字段 |
|---|---|
| SHIPMENT ID | `shipment_id` |
| REFERENCE ID | `reference_id` |
| 箱规 | `box_specification` |
| 箱规单位 | `box_specification_unit` |
| 箱单单箱毛重(KG) | `package_gross_weight_kg` |
| 箱单单箱净重(KG) | `package_net_weight_kg` |
| 查验结果 | `inspection_result` |
| 异常原因 | `exception_reason` |
| 查验图片数量 | `inspection_photo_count` |
| SKU | `sku` |
| 单箱个数 | `units_per_box` |
| 报关类型 | `declaration_type` |
| 箱号 | `box_number` |
| 商品单箱毛重量(KG) | `item_gross_weight_kg` |
| 商品单箱净重量(KG) | `item_net_weight_kg` |
| 中文品名 | `chinese_name` |
| 英文名称 | `english_name` |
| 品牌类型 | `brand_type` |
| 品牌 | `brand` |
| 型号 | `model` |
| 材质（CN） | `material_cn` |
| 材质（EN） | `material_en` |
| 用途 | `purpose_cn` |
| 商品属性 | `goods_attributes` |
| 报关编码 | `declaration_hs_code` |
| 清关编码 | `clearance_hs_code` |
| 材质占比 | `material_ratio` |
| 清关单价 | `clearance_unit_price` |
| 清关币种 | `clearance_currency` |
| 采购单价 | `purchase_unit_price` |
| 采购币种 | `purchase_currency` |
| 商品图片数量 | `product_image_count` |
| 备注 | `remark` |

DW授权信息明细：

| 展示名 | 后端字段 |
|---|---|
| FBAID | `fba_id` |
| DW开始时间 | `dw_start` |
| DW结束时间 | `dw_end` |
| DW | `dw_display` |
| 客户授权状态 | `authorization_status` |

附件信息明细：

| 展示名 | 后端字段 |
|---|---|
| 附件分类 | `category` |
| 文件名称 | `file_name` |
| 文件类型 | `file_extension` |
| 是否图片 | `is_image` |
| 预览链接 | `preview_url` |
| 下载链接 | `download_url` |
| 收费项目 | `cost_name` |

入库概况：

| 展示名 | 后端字段 |
|---|---|
| 入库状态 | `inbound_status` |
| 入库时间 | `inbound_time` |
| 操作人 | `inbound_operator` |
| 仓库 | `warehouse` |
| 异常原因 | `abnormal_reason` |
| 入库图片数量 | `inbound_photo_count` |
| 预报件重体 | `forecast_pwv_summary` |
| 入库件重体 | `inbound_pwv_summary` |

入库明细：

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 是否贴标 | `has_label` | |
| SHIPMENT ID | `shipment_id` | |
| 入库件数 | `inbound_quantity` | |
| 测量图片数量 | `measurement_photo_count` | |
| 入库箱规 | `box_specification` | |
| 单箱入库重量 / 总重量KG | `weight` | 由 `weight_mode`=`single_box`/`total` 决定展示键名 |
| 重量单位 | `weight_unit` | |
| 长度是否超限 | `is_over_length` | |
| 宽度是否超限 | `is_over_width` | |
| 高度是否超限 | `is_over_height` | |
| 重量是否超限 | `is_over_weight` | |
| 操作时间 | `operated_at` | |

查验信息明细：

| 展示名 | 后端字段 |
|---|---|
| 货件编号 | `shipment_id` |
| SKU | `sku` |
| 箱号 | `box_number` |
| 箱数 | `box_quantity` |
| 箱规 | `box_specification` |
| 查验结果 | `inspection_result` |
| 查验图片数量 | `inspection_photo_count` |
| 备注 | `remark` |
| 查验人 | `inspector` |
| 查验时间 | `inspected_at` |

订单轨迹明细：

| 展示名 | 后端字段 |
|---|---|
| 轨迹类型 | `track_type` |
| 轨迹节点 | `status` |
| 轨迹地点 | `location` |
| 时间 | `occurred_at` |
| 跟踪号 | `tracking_number` |
| SHIPMENT ID | `shipment_id` |
| 轨迹内容 | `content` |

操作日志 / 应收与结算日志明细：

| 展示名 | 后端字段 |
|---|---|
| 操作时间 | `operated_at` |
| 操作内容 | `content` |
| 操作人 | `operator` |

派送汇总：

| 展示名 | 后端字段 |
|---|---|
| 主跟踪号 | `master_tracking_number` |
| 子单数量 | `sub_order_count` |

派送明细：

| 展示名 | 后端字段 |
|---|---|
| 子跟踪号 | `sub_tracking_number` |

### query_order_receivable_cost_details

结构：`headers`、`rows`、`pagination`。固定 13 列。

| 展示名 | 后端字段 |
|---|---|
| 订单号 | `order_number` |
| 客户名称 | `customer_name` |
| 费用项 | `cost_name` |
| 费用客户 | `cost_customer_name` |
| 计费重 | `charge_weight` |
| 计费单价 | `unit_price` |
| 原币币种 | `quote_currency` |
| 应收原币 | `receivable_original_amount` |
| 应收金额（CNY） | `receivable_amount_cny` |
| 结算金额（CNY） | `settlement_amount_cny` |
| 费用确认状态 | `cost_confirmation_status` |
| 关账状态 | `closing_status` |
| 核销状态 | `verification_status` |

### query_receivable_cost_list

结构：`headers`、`rows`、`pagination`。固定 24 列；四个金额字段为 `{"amount": number, "currency": string}`。

| 展示名 | 后端字段 |
|---|---|
| 主客户 | `main_customer_name` |
| 子客户 | `sub_customer_name` |
| 客户属性 | `customer_attribute` |
| 事业部 | `department_name` |
| 单据类型 | `document_type` |
| 仓库 | `warehouse_name` |
| 业务单号 | `business_number` |
| 参考号 | `reference_number` |
| 费用项 | `cost_name` |
| 原币金额 | `original_amount` |
| 总金额 | `total_amount` |
| 已出账金额 | `billed_amount` |
| 未出账金额 | `unbilled_amount` |
| 账单编号 | `bill_number` |
| 核销状态 | `verification_status` |
| 收款水单号 | `receipt_number` |
| 收款日期 | `receipt_date` |
| 商务经理 | `sales_name` |
| 客户经理 | `merchandiser_name` |
| 引流人 | `drainage_user_name` |
| 头程订单状态 | `first_leg_order_status` |
| 结算模式 | `settlement_mode` |
| 费用发生时间 | `cost_occurred_at` |
| 业务发生时间 | `business_occurred_at` |

### query_customer_list

结构：`summary`、`headers`、`rows`、`pagination`、`display_rules`。固定 17 列，须完整展示。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 客户名称 | `customer_name` | |
| 客户代码 | `customer_code` | |
| 开户时间 | `create_time` | |
| 业务类型 | `business_type` | |
| 客户属性 | `customer_attribute` | |
| 客户来源 | `customer_source` | |
| 首次成交时间 | `first_inbound_date` | |
| 最后一次走货时间 | `last_inbound_date` | |
| 活跃状态 | `active_status` | |
| 合同状态 | `contract_status` | |
| 合同有效期 | `contract_validity` | |
| 信用额度 | `credit_limit` | |
| 结算币种 | `currency_code` | |
| 结算模式（分业务类型） | `billing_modes` | 数组，每项含 `业务类型`、`结算模式` |
| 商务经理 | `sales_name` | |
| 客户经理 | `merchandiser_name` | |
| 事业部 | `department_name` | |

### query_customer_payment_followup

结构：`headers`、`rows`、`pagination`、`display_rules`。固定 14 列。

| 展示名 | 后端字段 | 说明 |
|---|---|---|
| 客户名称 | `customer_name` | |
| 结算币种 | `settlement_currency` | |
| 已出账未核销金额 | `billed_unverified_amount` | number |
| 未出账金额 | `unbilled_amount` | number |
| 逾期未回款金额 | `overdue_unpaid_amount` | number |
| 已出账未核销金额（人民币） | `billed_unverified_amount_cny` | number |
| 未出账金额（人民币） | `unbilled_amount_cny` | number |
| 逾期未回款金额（人民币） | `overdue_unpaid_amount_cny` | number |
| 未回款月份汇总 | `unverified_receivable_monthly_summary` | 见下表 |
| 收款单未核销金额 | `receipt_unverified_amount` | number |
| 当前余额 | `current_balance` | number |
| 信用额度 | `credit_limit` | number |
| 坏账合计 | `bad_debt_total` | number |
| 合同状态 | `contract_status` | |

未回款月份汇总子项：

| 展示名 | 后端字段 | 类型 |
|---|---|---|
| 应收月份 | `receivable_month` | string |
| 未核销金额 | `unverified_amount` | number |
| 是否逾期 | `is_overdue` | boolean |

### query_customer_unverified_bill_details

结构：`headers`、`rows`、`pagination`。固定 6 列。

| 展示名 | 后端字段 |
|---|---|
| 账单月份 | `bill_month` |
| 账单号 | `bill_no` |
| 业务类型 | `business_type` |
| 结算模式 | `settlement_mode` |
| 未核销金额 | `unverified_amount` |
| 客户应收款日期 | `customer_receivable_date` |

### query_customer_payment_records

结构：`headers`、`rows`、`pagination`。固定 8 列。

| 展示名 | 后端字段 |
|---|---|
| 客户名称 | `customer_name` |
| 收款水单号 | `payment_reference` |
| 原币到账金额 | `original_received_amount` |
| 实际收款金额 | `actual_received_amount` |
| 收款日期 | `receive_date` |
| 已核销金额 | `verified_amount` |
| 未核销金额 | `unverified_amount` |
| 收款审核状态 | `payment_approval_status` |

### 筛选项工具

`list_customer_filter_options`、`list_order_filter_options`、`list_outbound_filter_options`、`list_pending_outbound_export_filter_options`、`list_receivable_cost_filter_options` 结构相同：`headers`、`rows`、`pagination`。应收费用单筛选的 `value` 可合法为 `0` 或 `-1`。

| 展示名 | 说明 |
|---|---|
| 可传值 | 后续业务工具可直接传入的 value |
| 显示名称 | 给人看的名称 |
| 业务编码 | 辅助识别编码，可能为空 |

### export_pending_outbound_orders / export_out_of_province_port_data / export_receivable_cost_list

只提交异步任务，不返回文件。结构：

| 展示名 | 字段 | 说明 |
|---|---|---|
| 提示文案 | `message` | 固定为「导出任务已提交」 |
| 任务 | `task.task_ref` | 不透明任务引用，供 `query_export_task` 使用 |
| 状态 | `task.status` | 固定 `queued` |
| 建议等待秒数 | `task.retry_after_seconds` | 正整数 |

### query_export_task

| 状态 | 返回结构 |
|---|---|
| `queued` / `running` | `message`、`task.task_ref`、`task.status`、`task.retry_after_seconds` |
| `failed` | `message`（导出任务失败，请重新提交）、`task.task_ref`、`task.status` |
| `completed` | `message`（文件已生成）、`task`、`files[]` |

`files` 每项：

| 展示名 | 字段 | 说明 |
|---|---|---|
| 文件名称 | `label` | |
| 安全下载链接 | `url` | 仅 http/https |

## 返回结果示例

示例值均为虚构数据；业务数据在 `structuredContent`。

### 表格工具

```json
{
  "content": [{"type": "text", "text": "订单查询结果"}],
  "structuredContent": {
    "headers": [{"label": "订单号"}, {"label": "客户名称"}],
    "rows": [["ORD202607290001", "示例客户"]],
    "pagination": {"page": 1, "limit": 20, "has_more": false}
  },
  "_meta": {"request_id": "rq_demo_001"}
}
```

### query_outbound_detail

```json
{
  "summary": {
    "headers": [{"label": "提单号"}, {"label": "柜号"}, {"label": "总体积"}],
    "row": ["BL001", "MSCU1234567", 12.5]
  },
  "details": {
    "headers": [{"label": "订单号"}, {"label": "客户名称"}],
    "rows": [["ORD202607290001", "示例客户"]],
    "pagination": {"page": 1, "limit": 10, "has_more": false}
  }
}
```

### query_order_detail

```json
{
  "订单号": "ORD202607290001",
  "详情模块": "全部",
  "订单概览": {
    "状态节点": [{"阶段": "入库", "节点": "已入库", "状态": "已完成", "时间": "2026-07-29 10:00:00", "时间类型": "实际"}],
    "订单信息": {"订单号": "ORD202607290001", "客户名称": "示例客户"}
  },
  "订单轨迹": {
    "明细": [{"轨迹节点": "已入库", "时间": "2026-07-29 10:00:00"}],
    "分页": {"页码": 1, "每页数量": 20, "是否还有更多": false}
  }
}
```

### 筛选项

```json
{
  "headers": [
    {"label": "可传值"},
    {"label": "显示名称"},
    {"label": "业务编码"}
  ],
  "rows": [[101, "示例仓库", "WH001"]],
  "pagination": {"page": 1, "limit": 20, "has_more": false}
}
```

### 异步导出

提交：

```json
{
  "message": "导出任务已提交",
  "task": {
    "task_ref": "TASK202607290001",
    "status": "queued",
    "retry_after_seconds": 5
  }
}
```

查询完成：

```json
{
  "message": "文件已生成",
  "task": {"task_ref": "TASK202607290001", "status": "completed"},
  "files": [
    {"label": "未排舱订单.xlsx", "url": "https://download.example.com/signed-url"}
  ]
}
```

## 通用返回规则

- 业务成功数据位于 JSON-RPC `result.structuredContent`；表格工具为 `headers` + `rows` + `pagination`。
- 展示名来自 Presenter 白名单；`rows` 单元格按 `headers` 列序排列，不是对象字典。
- 异步导出提交返回 `message` + `task`，稍后调用 `query_export_task` 获取状态和下载链接。
- 后端业务失败使用 `result.isError=true`；协议、参数、未知工具错误使用 JSON-RPC `error`，参数错误码为 `-32602`。
- 不向调用方返回数据库、Redis、Token、内部 ID 或异常堆栈等敏感内部信息。