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「海外提柜列表与筛选」

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