api文档

docs/mcp-api.md

@@ -0,0 +1,976 @@
+# 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 个；号码类型必须明确 |
+
+### 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
+
+只提交异步任务，不返回文件。结构：
+
+| 展示名 | 字段 | 说明 |
+|---|---|---|
+| 提示文案 | `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 或异常堆栈等敏感内部信息。