mcp/CONTEXT.md

MCP Gateway

物流货运系统面向 Workbuddy 的 MCP Gateway 语境。业务规则在 fmsoperate；本文件只定义本仓对外使用的领域词。

合同入口

• 行为与验收：Y:/all_project_docs/mcp/requirements.md
• 实现边界：Y:/all_project_docs/mcp/tech-specs.md
• 物流工具与导出所有权：Y:/all_project_docs/fmsoperate/
• 海外提柜列表行为：Y:/all_project_docs/fmsoperate/requirements.md「海外提柜列表与筛选」
• 头程问题件列表行为：Y:/all_project_docs/fmsoperate/requirements.md「头程问题件列表与筛选」
• 收货量列表行为：Y:/all_project_docs/fmsoperate/requirements.md「收货量 MCP 列表与筛选」
• 柜子时效列表行为：Y:/all_project_docs/fmsoperate/requirements.md「柜子时效 MCP 查询与导出」

Language

打托批次: 海外仓侧把若干订单打成一组托盘后形成的批次，业务号为 PB 开头的打托批次号。命中批次内任一订单，导出该批次的全部订单行和全部打托附件。 Avoid: 入仓单、海外仓入库明细、打托数（件数）、勾选行内部 ID、按筛选拆成半批次

打托数据导出: 按打托批次交出的下载包：与海外仓后台「导出打托数据」相同的 Excel，若这些批次有打托附件则连同附件打成 zip。单个附件下载失败则跳过该文件，任务仍成功；没有任何附件成功下载时只交 Excel。定位条件严格三选一：柜号数组、提单号数组，或海外仓入库时间闭区间（最多 31 天）；两类号码不能混用，也不能与时间混用。由独立异步任务生成，不走后台同步导出。调用方须能进入海外仓列表并使用导出接口；数据只按当前公司隔离。 Avoid: 入仓单号、入仓单列表导出、海外仓库存导出、对话内表格查询、只要 Excel 不要附件、勾选内部 inbound_id、订单号/打托批次号混查、复用后台同步 ExportPalletLogic、套用列表的国家/运输方式范围、任一附件失败就整任务失败

柜号与提单号: 打托数据导出分别按 fms_outbound.container_code 或关联 fms_booking_detail.bl_number 精确匹配，一次只允许一种号码类型，最多 200 个且每项最多 100 个字符。用户只提供号码但未说明类型时必须先询问，不得根据格式猜测或同时试查两类字段。 Avoid: 入仓单号、订单号、打托批次号、内部 ID、跨字段试查

海外仓入库时间: 入仓明细上的入库时间，用来圈定哪些入仓单进入本次导出。起止各自可只填日期或带时间：缺时间则开始日 00:00:00、结束日 23:59:59；填了时间则用该日该时。与存储值闭区间比较，不做列上的时区转换。不按海外仓列表页签再过滤。闭区间最多 31 个日历日。 Avoid: 到仓时间、列表页签状态、预计打托日期、把入库时间列做 CONVERT_TZ

海外提柜类型: 查海外提柜列表前必须先选定的分类，对应后台六个页签：待安排拖车、待提柜、待还柜(海)、已还柜(海)、已提货(空)、DO单制作。未指定类型时先问，不得默认某一类或六类一起查。 Avoid: 把「提柜状态」当成页签名、把六类当成同一种单、跳过类型直接按柜号扫全表

DO制作记录: 「DO单制作」类型下的一行，是待处理的 DO 邮件/文件任务，不是柜子进度。固定十一列：拖车单号、出库单号、柜号、柜型、提单号、是否直送、原DO单、新DO单、邮件主题、邮件发送人、邮件接收时间。原DO/新DO只给安全链接。 Avoid: 套用进度字段、ETA、提柜时效、应付费用状态、把文件当进度列

海外提柜筛选: 提单号、柜号、拖车行、海外仓、直送柜、应付费用、整拼类型、运输方式、ETA、提柜时间、还柜时间都可选。只凭类型即可按当前页签分页。传入日期必须成对，闭区间最长 31 天。DO制作可以只凭类型查询；号码只接受提单号和/或柜号，多带其它条件报错。待安排拖车没有提柜单上的拖车行、应付费用、提柜时间、还柜时间，这些条件仍允许带，命中集为空，不报错。 Avoid: 把日期或号码当必填、DO制作用 ETA 或其他维度、待安排带提柜单条件就报错

应付费用状态: 已安排拖车的提柜单账单进度，只允许：未收到账单、待录入费用、待付款、部分付款、已付款。待安排拖车没有提柜单，此列为空；筛选仍允许带应付费用，命中集为空。DO制作没有此列，也不接受该筛选。 Avoid: 待安排带应付费用就报错、数字 10/20/30/35/40、财务备注

海外提柜号码: 海外提柜列表的提单号与柜号分开精确匹配，两类可以同时带且为同时满足。禁止一个框混查，禁止按格式猜测。两类合计最多 200 个，每项最多 100 字符。 Avoid: 订单号/拖车单号/排舱单号/SO 混查、跨字段试查、模糊 LIKE

海外提柜进度列: 待安排拖车、待提柜、待还柜(海)、已还柜(海)、已提货(空)五类固定同一套三十列：提单号、柜号、柜型、仓库名称、拖车行、提柜状态、最新操作备注、直送、整拼类型、船名航次、航线、清关查验、ETD、ATD、ETA、ATA、起运港、目的港、到港码头、APPT时间、卡车实际派送时间、预计提柜时间、实际提柜时间、到仓时间、还柜时间、提柜时效、还柜时效、码头等待时间、亚马逊等待时间、应付费用状态。还没有的格子留空，不删列。 Avoid: 排舱单号、拖车单号、POD、装柜照片、财务备注、按页签增减列、还空时间、还空时效

还柜时间: 提柜单上的还柜时刻。筛选名与进度列名相同。不是另一个「还空」时间点。 Avoid: 还空时间、拆成两个时间、待安排拖车当真实还柜时刻

提柜时效与还柜时效: 提柜时效有存值用存值，否则按实际到港到实际提柜的天数；还柜时效有存值用存值，否则按实际提柜到还柜的天数。口径与后台列表相同。 Avoid: 还空时效、当场另发明细算法

提柜状态: 海外提柜单当前进度，只允许四个中文：待提柜、已提柜、派送完成、已还柜。待安排拖车还没有提柜单，此列为空。页签名称不是提柜状态。 Avoid: 把派送完成写成已提柜、用数字 10/20/25/30、把六个页签叫提柜状态

最新操作备注: 后台点操作备注打开 outbound/viewLog 后第一行的「操作内容」。数据在 Mongo fms_outbound_log，当前公司 + 排舱单号，按 _id 倒序取第一条。不按海外提柜节点过滤。只展示操作内容，不拼节点、时间、操作人。没有日志则空。必须按当前页排舱单号一次聚合读取，禁止调用后台日志接口或逐行查 Mongo。 Avoid: 提柜单 remark 字段、fms_outbound_remark、财务备注、只取海外提柜节点、按 create_time 排序、调用 viewLog/getMongoLogList、逐行查 Mongo

仓库名称: 海外提柜进度列上的到货地点文案：非直送显示海外仓名称-代码；直送显示派送地址。筛选「海外仓」只命中非直送柜，选了海外仓等于排除直送。 Avoid: 直送柜硬套海外仓、筛海外仓仍带回直送、把派送地址改名叫仓库代码

海外提柜查询: Workbuddy 只分页查看海外提柜列表，当场出表。工具为 query_destination_trailer_list 与 list_destination_trailer_filter_options。本期不做港后数据、应付、入仓单、列表数据、POD、装柜顺序等任何导出，也不做安排拖车、确认还柜等写入。筛选项提供海外提柜类型、拖车行、海外仓、直送柜、应付费用、整拼类型、运输方式。提单号、柜号和时间段由调用方直接传入。一页最多 100 条，最多 100 页；用多读 1 条判断还有没有下一页，不数总数，不要各页签角标。调用方须能进入后台海外提柜菜单；数据范围与该页相同，含公司隔离及「其他」账号的国家/运输方式。超管只跳过角色授权。直送列只出「是」或「否」。 Avoid: 一次调用里出文件、把导出绑进列表工具、开放提柜作业操作、猜拖车行或海外仓内部 ID、COUNT 总数、页签角标、套用排舱或海外仓菜单

海外提柜当地日: ETA、提柜时间、还柜时间按每票目的港当地日历日筛选。缺时刻则开始日 00:00:00、结束日 23:59:59，闭区间最长 31 天。查询先走 UTC 时间索引窗口，再按目的港时区丢掉不是这几天的行，不在筛选列上做 CONVERT_TZ。 Avoid: 拿员工时区当目的港时区、SQL 列上 CONVERT_TZ、无号码时超过 31 天

海外提柜时间展示: 进度列里只出日期的：ETD、ATD、ETA、ATA、实际提柜时间、到仓时间、卡车实际派送时间、还柜时间。带时刻的：预计提柜时间、APPT时间。DO制作的邮件接收时间带时刻。ETD/ATD 用起运港时区，其余用目的港时区。 Avoid: 全部截到日、全部带时刻、ETD 用目的港时区

清关查验: 海外提柜进度列上的查验文案，只允许：否、是(X-RAY检查)、是(查验场查验)、是(X-RAY检查/查验场查验)。 Avoid: 只出是/否、只出检查方式、数字 1/2

头程问题件: 后台 admin/Order/abnormal 上的一条记录。一行一条，同一订单可以同时有多条。不是整张订单，不是排舱「是否问题件」，也不是作废审核页上的审核行。 Avoid: 异常件当订单列表、是否问题件、作废审核、关闭异常、重新取号

问题件状态: 查头程问题件前必须先选定的分类，对应后台六个页签：待处理、放行待审核、包裹放行、退件待审核、退件驳回、已退件。未指定时先问，不得默认待处理或六类一起查。包裹放行按处理结果「放行」过滤，不是库里的 status=50。展示列用这六个中文，不用字典里的拦截/结案文案。 Avoid: 拦截待审核、拦截驳回、已拦截、结案、处理中、作废、数字 10/15/40/45/50、-5、六类混查、默认待处理

头程问题件订单号: 头程问题件查询只接受已标明的订单号，精确匹配。不把参考号、跟踪号、柜号、SO 号放进同一个框，也不按号码样子猜测或四个字段一起试。 Avoid: 后台异常件页的单号混查、跟踪号、柜号、SO、参考号、按格式试查

头程问题件查询: Workbuddy 只分页查看头程问题件。工具为 query_order_abnormal_list 与 list_order_abnormal_filter_options。问题件状态必填；订单号可选，有则精确收窄，没有就按当前状态分页。不提供物流产品、问题件类型、客户、客户经理和时间筛选。不预填时间窗，不统计总数，不要六个页签角标。本期不做导出，也不做关闭、已读、重新取号、编辑。调用方须能进入后台异常件菜单 admin/Order/abnormal；数据范围与该页相同。超管只跳过角色授权。page/limit 为 1..100，limit+1 返回 has_more；订单号最多 200 个、每项最多 100 字符。排序与当前页签的后台列表相同。注册行已写入且首次关闭；启用与 Gateway 重启见集中仓 timeline.md / sql/README.md。 Avoid: 没单号就拒绝、偷偷加默认入库/创建时间、COUNT 总数、页签角标、按客户ID/产品/类型/时间筛、一次调用里出文件、开放关闭/已读/取号、套用订单操作台或作废审核菜单、一律按主键倒序、把六个页签只写进查询 Schema 而不提供筛选项工具、按 SQL 文件存在视为已启用

头程问题件列: 六个状态下固定九列：订单号、客户、物流产品、问题件状态、问题件类型、问题件描述、排舱单状态、入库时间、标记人。不按页签加减列。没有排舱或未入库的格子留空。客户出「名称-代码」。物流产品与页面相同，出中文名。问题件描述是标记时的说明，不是处理备注。标记人是记下这条问题件的人，不是放行/审核操作人。排舱单状态是订单当前排舱进度文案。入库时间是订单入库时刻，按员工时区出日期时间；未入库留空，不回退预计入库。 Avoid: 客户经理、运输方式、目的国、创建时间、处理备注、操作人、放行时间、申请时间、按页签换列、物流产品带代码、标记人当处理人、入库用预计入库或目的港时区

头程问题件筛选项: 只提供一类可选项：问题件状态，即六个中文页签。返回 value/label/code。订单号不经本工具。权限与头程问题件查询相同。 Avoid: 物流产品、问题件类型、客户、客户经理、时间、把筛选项当成查询条件本身

收货量: 一票已入库头程订单上的入库体积。一行一单，不是按客户、货物类型或日期折叠后的合计。 Avoid: 预报体积、散货/整柜页脚合计、按客户汇总、业务发生时间账龄、未入库订单

收货量入库时间: 收货量查询里的入库时间，是头程订单 inbound_date。筛选和展示都用这一列，按员工时区出日期，不回退预计入库。没有入库时间的单不进收货量。 Avoid: 业务发生时间、预计入库、海外仓入库时间、问题件列表带时刻的入库时间、空窗扫全历史

收货量查询: Workbuddy 分页查看已入库头程订单的收货量明细。工具为 query_receive_volume_list 与 list_receive_volume_filter_options。入库时间必填，员工时区闭区间最长 31 天；客户、商务经理、客户经理、货物类型、物流产品可选。不提供订单号筛选，不数总数，不要散/整柜页脚。本期不做导出。调用方须能进入结算收货量菜单 admin/Report/receiveForm；数据范围按账号类型卡控，不跟后台页全公司，也不套订单操作台。超管只跳过角色授权。page/limit 为 1..100，limit+1 返回 has_more；按入库时间倒序，相同再按订单 id 倒序。合同已定稿，代码与注册未准备，不得视为已上线。 Avoid: 空时间全历史、COUNT 总数、页脚 CBM、套用 getReceiveFormList、套用 Order/index 范围、一次调用里出文件、把列叫成业务发生时间、按 SQL 或文档视为已启用

收货量列: 固定九列：订单号、客户名称、货物类型、入库体积、入库时间、商务经理、客户经理、事业部、物流产品。客户只出名称。入库体积三位小数。入库时间员工时区日期，不回退预计入库。事业部是订单部门，三级显示上一级。物流产品为中文名-产品代码。 Avoid: 件数、重量、收款状态、客户类型、订单状态、客户名称带代码、按页签换列

收货量筛选项: 提供五类可选项：客户名称、商务经理、客户经理、货物类型、物流产品。返回 value/label/code。入库时间不经本工具。客户与列表同一数据范围；人员为公司启用业务员工；货物类型和物流产品走字典与头程产品。权限与收货量查询相同。 Avoid: 订单号、事业部、收款状态、从入库订单 DISTINCT 扫表、把筛选项当成查询条件本身

柜子时效统计报表: Workbuddy 分页查看已出库排舱单的柜子时效，或异步导出同口径 Excel。工具为 query_container_timeliness_list 与 export_container_timeliness_report。定位只有柜号、提单号或干线实际出发时间；两类号码可 AND，合计最多 200。没有号码时干线实际出发时间必填，起运港当地日闭区间最长 31 天。查询固定 54 列不含序号；导出 Excel 加序号。看表格用查询，明确要文件才导出。调用方须能进入结算 admin/Report/outboundReport；导出再复核 admin/Export/asyncExportData。数据只按当前公司已出库隔离。合同已定稿，注册未执行，不得视为已上线。 Avoid: 排舱列表、query_outbound_list、HTML 少列、页面混查输入框、默认出库时间、CONVERT_TZ 筛选、COUNT 总数、筛选项工具、猜 DDL、按 SQL 或文档视为已启用

干线实际出发时间: 柜子时效筛选用的日期，是起运港当地日历日。存储值在 fms_truck_transport.departure_time（UTC），按排舱单 loading_timezone 落到当地日。实现先用 UTC 窗口圈行再按当地日剔除，不在筛选列上做 CONVERT_TZ。 Avoid: 出库时间、海外仓入库时间、员工时区默认窗、空窗扫全历史