mcp/docs/mcp-api.md

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。

表格工具

{
  "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

{
  "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

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

筛选项

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

异步导出

提交：

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

查询完成：

{
  "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 或异常堆栈等敏感内部信息。