docs/海外仓业务/预约工作日历V13变更说明.md

预约工作日历 V13 变更说明

确认日期：2026-10-16。用户已确认 V13 原型，并要求按现有开发分工继续实施。本文是本轮产品行为、业务约束与验收场景的正式变更依据；确认需求不表示业务代码、部署或真实环境验收已经完成。

接口和唯一文件写者继续由开发协作契约维护。本文维护业务规则，不另建开发进度台账；实现进度由“预约”开发总控维护既有检查点，部署与整体验收事实仍归环境主契约。早期优化方案及 V11/V12 评审记录用于追溯，冲突时以本次确认和现行正式契约为准。

1. 确认范围与原型基线

本轮目标是：船已开后，运营从“预约管理 → 预约列表”进入“预约工作日历”，能看到所有应办事项，包括未预约、未定日期和变化后尚未处理的事项；每条工作直接给出当前可执行的下一步。

• 日历为默认首屏，提柜、接仓卸柜、送仓/FBA、用车、还空五类可勾选；日期格定高，按类型汇总，不随事项数量无限堆叠。点击数量查看并操作明细。
• 全部待办、今日需跟进、超期、未定日期、需复核不随日历月份、流程或类型筛选而遗漏。不同待办集合允许重叠；同一事项在一个结果集中只出现一次。
• 支持海外仓中转分批和整柜直送，支持不同客户同起运仓、同目的仓共用真实车次。多客户共车是已有业务能力，本轮重点补齐统一操作、变化后的续办和完整跟进。
• 不把本轮扩大成完整车队、库存或费用模块重构；不增加自动向仓库/车队发送预约、取消通知的承诺。登记联系结果与对方实际确认是不同动作。

已确认原型：C:/Users/BY-OY/.codex/visualizations/2026/10/14/01a13a8d-e968-7962-906b-1a514792d921/appointment-calendar-guided.html，页头 V13。确认时 SHA-256：61902e410be755aa9cbf9fcfaa9d393bfa49dd8d592cd8773af5396e78c29836。该文件为交互依据，不是生产 API、状态机或数据库结构；原型中的演示字段名、固定负责人、固定日期及示例数据不得直接当成业务合同。

2. 对象、数量与客户归属

对象	正式规则
货物来源	每条保留客户、稳定来源键、目的地、业务票号、货件/追踪号、柜次及核实数量/版本。沿用原 ORDER / BOOKING 来源身份，不因建订单、分批、换车而产生来源别名。
送货需求与批次	未约、取消安排、日期未知都不消灭仍需送货的需求。批次有稳定身份及版本；移车或重新预约不重新占一次货量。只有真实分批/合并才调整分配，并保留旧批次到当前批次的去向。
对外预约	预约确认号、有效覆盖范围、确认时段与预约身份分开保存。一个共同预约可覆盖多个客户的批次；不能用相同文本约号代替明确的共同预约关系。
运输	一个真实车次可承运多个客户、多个批次；各客户的排车/货物归属保留。送仓预约与车辆安排分别确认，不能互相冒充。后送用车待办不等于已经创建实际车次、锁定托盘或承运资源。
工作事项	关联权威业务对象，承担展示、跟进、复核和下一步引导，不再维护第二本可编辑数量账或另一份预约/实际完成结果。

按每个“客户＋稳定来源＋目的地”核对数量，而不是只核对总箱数：

核实可履约总量 = 尚未分配到批次的数量 + 当前有效批次的分配数量之和

这里的有效批次包含已经实际完成的履约数量，不能因完成后退出待办而再次变成可选余量；已被替代的历史批次不重复计入。后送批次即使没有日期或预约，其货量仍属于该批次，只能从该批次继续分配，不能再按整票新增一遍。逐来源不超分、不为负、总量不丢；未知数量保持未知，不当成 0，也不能未经核实拆分。

补箱数和各票货件号只保存预约货物核实资料，不覆盖原尾程订单；已分配数量不能被核实为更小。客户库存、托盘、订单、费用及对外可见范围仍按原客户隔离规则执行。

3. 两条履约流程

3.1 海外仓中转

开船后生成/读取本柜应办工作 → 提柜 → 海外仓接仓卸柜 → 各送货批次分别约仓及安排运输 → 真实备货、装车、发车、签收。提柜、接仓卸柜、还空按柜级稳定身份去重，不随客户数、送货批数或车次数重复生成。

实际卸柜完成后，还空按真实条件独立跟进，不等待所有送货批次完成。一柜可以分多批、多车；不同柜、不同客户的货物在符合原业务资格时也可同仓共车。

3.2 整柜直送

开船后 → 提柜安排及目的仓收货预约 → 同一运输链直送目的仓 → 真实卸货 → 还空。不得为了直送生成海外仓接仓/入库事项、库存或假卸柜事实。提柜和直送共用一趟运输时只计算一个真实车次，不重复约车；还空可由原车执行或转交明确接手方。

实际目的仓卸货未完成不能登记还空；交接责任不等于已还空。直接送往客户仓且对方无需预约时，保存明确的收货要求，不伪造 FBA 货件号、外部约号或“预约成功”。路线未知时先提供“确认路线”，确认后幂等生成应办清单。

4. 多客户同仓共车

1. “与同仓待排货物一起安排”或“按目的仓统一安排”只展示当前有资格的货物。候选以稳定起运仓/目的仓身份及真实业务资格核对，不只比较仓名；已安排或已分配的量不能重复选入。
2. 从某个后送批次进入时，只预选该批次的当前可安排量；其他客户由操作人明确加选。每票允许填写本次箱数，客户、来源和货件随货保留。
3. 共车不等于共用仓库预约。可分别保存各客户的预约结果，也可在仓库明确确认覆盖全部所选客户和数量后使用共同预约；页面必须明确显示采用哪一种方式。
4. 外部约号按目的仓执行既有唯一性规则。共约成员通过同一预约身份引用这个约号，不各自创建重复主单。其他有效预约已使用的约号不能直接填入，冒充该客户已加入共同预约。
5. 保存后逐客户显示成功、待补资料、关联失败等真实结果，提供下一步；一辆车在日历工作量中只计一次，各批送仓工作分别计数。
6. 实际车辆、司机、托盘、容量、审核、装载和发车走原 Fleet/Dispatch 资格与命令。原型中的直接登记执行仅表达流程衔接，不替代这些门槛。

5. 分批、缺货与后送

以甲 80、乙 160、丁 40，共 280 箱送 ONT8 为统一验收样例；每条场景独立恢复基准，不能将不同演示的数量相加。

变化	原车	后续需求	下一步
乙整批移出	保留甲 80＋丁 40＝120 箱；其预约不变	乙 160 箱保留原来源与需求，另期或未定日期	乙重新约仓并安排车辆；原车按剩余货量核对后继续
乙 100 箱已齐、60 箱后送	甲 80＋乙 100＋丁 40＝220 箱	60 箱单独后送；没有目标也保留待办	可单送，或选择与同仓待排货物一起安排
后送 60 再选 40 安排	原车仍为 220 箱	40 箱进入新批次，20 箱仍待排；乙 100＋40＋20＝160	原车客户卡片同时列出两份当前去向，各可直接继续
后送 60 与另一客户 40 共车	原车仍为 220 箱	新车共 100 箱，客户和来源分别保留	分别/共同约仓后确认新车，按各客户实际执行

“本次先送量”允许为 0，表示该客户全部移出原车留待后送；不得强迫留一箱。先送量等于全部原数量时，没有后送分配，不额外新建空批次。部分改变已经确认预约的货量，必须取得仓库对保留量和移出量的明确处理结果；剩余货物是否备妥按实际核对，不因仓库同意而自动标记货齐。

后送目标日期可空，但必须保留负责人和跟进入口。原车客户卡片追踪分配/替代关系直到当前批次；全量再分配后直接显示新安排，部分再分配后同时显示仍待排的量和已分配的去向。不能显示失效的“0 箱待办”，不能只在历史文字中记录去向，不能将同一后续批次重复列出。

6. 改期、取消与影响范围

普通改期、取消、缺货移出用于尚未实际执行的安排。车辆已经发车或相关货物已经执行时，进入原运输异常处理，不提供普通移车操作来抹掉事实。

6.1 仅处理某个客户

• 默认明确展示本客户、原车、货量、其他客户及是否共用预约；操作者选择本客户另期、取消本次安排或本次先送部分数量。
• 确认前保留原安排。已有有效预约，尤其是共同预约时，须明确仓库同意本次调整范围；未收到回复先记录待确认，不能把沟通中状态当成取消/改期成功。
• 确认后只移动该客户/该部分货物。其他客户的约号、确认时段和客户归属保持不变；原车对剩余货量及发车时间核对一次。车队已确认原时间可继续时，不无故要求其他客户重新约仓。
• 待确认变化进入持续待办；涉及当前装载或预约有效性尚未解决时，原车不能直接发车。保存输入与已确认的信息，重新进入直接续办；不能用“关闭复核”跳过未解决的业务条件。
• 原车无任何有效货物且尚未执行时，经原车辆业务取消/调整处理后关闭相应运输工作并保留历史，不留下空车待办。不能据此取消其他客户或其他仍有效的车次任务。

6.2 整份共同预约变更

• 页面明确区分“仅本客户”和“整份共同预约”，展示所有当前覆盖客户、数量、预约和关联车辆。以服务端当前有效成员为准，不能靠外部约号文本相等推断范围。
• 整份改期：所有覆盖成员更新为同一已确认的新时段；相关车辆核对新收货时段是否可达。无实际变化的再次保存不重复产生复核。
• 整份取消：旧预约失效，保留旧计划、确认信息、取消原因和历史；当前确认及已经失效的目标日期从活动安排中清除，未重新确定的进入未定日期。全部未完成货物需求保留，各关联车辆列为待核对。
• 已取消的预约不能选“保留原预约”直接恢复有效。车辆原安排是否仍可执行可单独核对，但发车仍须所有相关收货/备货条件成立。
• 真实变化只影响直接关联且已经安排的事项；尚未安排的继续待安排。复核动作本身不再触发另一轮复核；处理旧影响版本不得清掉后来产生的新变化。

6.3 取消后的占用边界

本轮“取消”指取消本次预约/运输安排，不是取消订单或客户撤销全部运输需求。

失效预约释放其有效预约覆盖和绑定；仍需履约的批次数量分配继续存在，或在同次变更中转到明确的后送批次。不能把同一箱数同时留在原批次并重新作为整票可选余量，也不能先清空需求再等待以后人工补建。已完成数量保持不可再次分配。

取消预约不回退库存，不自动注销整辆车。已有正式排车、托盘或运力占用时，由其权威业务按真实关联调整；工作事项仅读取结果。恢复/重新预约仍重新核对来源、当前分配、版本和唯一性。

7. 移出后的重新预约与整组重约

7.1 单客户或后送批次续办

结果页直接提供“继续给本客户约仓”和有资格时的“与同仓待排货物一起安排”。从未定日期、搜索或原车客户卡片再次进入，也到达同一份当前需求。

单送路径为：核对货物 → 记录仓库回复/确认 → 继续安排本批车辆 → 核对真实备货条件 → 原业务发车、签收和运输完成。未约成可以保存计划和联系结果，不必编造时间；已取得确认后直接进入车辆安排。确认后的货物不能重新从“待排货物”入口新增一遍；车辆关联沿既有安排继续。

重新预约不会重新生成一份相同货量。完成后退出未完成待办，原批次和运输记录仍能查到；其他尚未完成的后送、原车或还空工作继续保留。

7.2 整份取消后的重新预约

1. 提供“重新预约这组货物”，展示本次仍需重新约仓的客户、批次与数量。已退出、已单独另约、已完成或正在处理其他变化的成员不被静默纳入；页面说明其当前去向。
2. 可以一次填写一个共用的新预约，也可以一次填写各客户独立预约。共同预约必须有仓库明确确认的客户和货量覆盖依据；分别预约不能通过重复填写相同约号绕开共同预约确认。
3. 沿用现有批次及可继续使用的原车，保存新有效预约关系；不重复分批、不重复占量、不仅为重约再创建一辆车。旧取消关系留历史，新共同预约使用新的有效关联身份。
4. 退出客户不能直接填写其他客户仍使用的旧约号，生成不同时间的孤立预约。若确需加入已有共同预约，必须经显式范围调整和仓库确认；普通填写约号不完成该操作。
5. 保存后主要下一步是“核对本车发车安排”。核对全部当前客户的收货时段和车辆条件；不能让车辆先于尚未完成的重约被标记可执行。后续再次整份改期/取消只作用于新的有效覆盖范围。

8. 未定日期、跟进与操作简化

• “没有作业日期”和“没有跟进日期”是不同含义。有跟进日仍可属于未定日期；不能把催回复日期填成送货日期。
• 日期留空时保留需求、负责人、联系记录及下一步，显示在全局未定日期/全部待办；取消、分批、部分失败不能让它消失。缺负责人或下一次跟进安排时明确提示补齐，不假定原型中的固定人员是生产默认值。
• 日期有目标但未约成时，日历按目标展示并标明未落实；确认时间、目标窗口和实际时间分别保存。实际发生后按权威实际日期展示，改期不移动历史事实。时间、时区、跨日、DST 和缺失原事实的处理沿开发协作契约第三节。
• 每个结果页优先给一个主要下一步，其他去向为明确次要入口；缺货在车辆执行入口可直接打开对应客户的“调整本次装载/移出本车”，不绕到其他客户或目的仓总列表。
• 未落实且只涉及本批货物时展示普通计划表，不展示多余的共车变化表单；独立车辆按钮称“继续安排本批车辆”，实际共车才称共用车辆。
• 返回保留原日期、柜、批次、筛选、分页和原事项上下文。旧批次已全部转入新安排时直接到新安排；历史仍可独立查看。

9. 失败、重试与权限

以下是正式实现和集成验收要求，不能用原型浏览器检查代替证明：

• 按原来源核实量、批次、预约范围及车辆关系版本校验。并发编辑、分批或共车成员变化时拒绝过期提交，保留用户输入，重新展示实际范围；服务端保证不超分。
• 同一用户操作使用持久化幂等身份；同键同内容返回原结果，异内容拒绝。超时/断网导致结果未知时沿原请求查询或重试，不自动当失败新建批次、预约或车辆。
• 货物已保存但关联车辆失败时，返回成功批次及准确失败步骤；成功货物保持已占用，重试只补失败步骤，不能重新建批/建车，也不能把已退出的客户重新挂回原车。
• 一次调整中原数量、后送数量、去向和待办必须一致。跨业务步骤未全部成功时明确显示尚未完成的部分和下一步，不宣称全部成功；不得产生既无原需求又无后续需求的窗口。
• 平台列表权限包含详情只读，写权限由各权威业务核验；多客户管理仅在授权平台范围内进行，客户侧只能看自己的货物。无权限、来源不可用、校验冲突均给明确原因，不能伪造成功或“0 项”。
• 真实备货、托盘、装载、发车、签收、还空及运输完成仍由原业务事实决定。通知或联系记录不能代替这些事实。

10. 开发接口交接与唯一写者

不复制旧接口、不建立前端数量账、不直接照搬原型对象。已有工作事项 v1 继续使用开发协作契约第三节；本轮新增语义由真实业务生产者先补 DTO/OpenAPI 与定向测试，再由消费者接入。精确 HTTP 路径、字段与错误码以生产者冻结的真实合同为准，本文不虚构已可用端点。

必须交付的语义	生产者与消费边界
当前批次逐来源分配、剩余量、全部/部分再分配去向、版本	预约核心提供权威数据；工作事项只读关联，前端据其显示当前去向，不凭历史文字推断。
单客户/整份共约变更的当前范围、旧安排、新安排、受影响客户/车辆、未完成原因	预约核心与原预约写者统一业务命令和版本；工作事项返回准确受影响事项与复核版本。
整份取消后的待重约成员、已排除成员及原因、共同/独立重约结果和新的有效预约关联	预约核心主导合同；保留原批次及运输关系，消费者不能自行造共同预约身份。
幂等结果、逐步骤成功/待补/失败、后续目标及可重试动作	各命令生产者返回真实结果；前端保留输入并继续失败步骤，工作事项不制造成功兜底。
允许动作、唯一主要下一步、缺项/阻塞原因、关联与去向	工作事项后端提供白名单动作和稳定目标引用；前端映射既有入口/表单。跨域业务写入不能塞进通用“改状态”命令。

现有三任务不增加、不更换工作区、不扩大其他业务写权：

现有任务	V13 继续工作	依赖及停止点
“预约” 01a13df2-c639-7560-a3e2-30bc23a579b3	开发总控兼预约核心：核对已实现差异，先冻结数量/去向、预约范围、取消和重约合同；协调原预约写者，统一共享文件、检查点及验证窗口	InboundFbaAppointmentService 及核心预约/分批测试已明确交回总控；工作适配和 Dispatch/Fleet 仍由后端专项独占。后续移交须明确唯一写者，不按同文件不同方法并写。
“工作事项后端” 01a13e1c-9101-7a43-8445-771685ff315e	完整待办、未定日期、准确影响集合、复核版本、下一步、真实车辆/预约同步；负责本批已移交的原域适配与直接测试	不另建数量分配账；先完成可独立部分，新增核心合同冻结后接入。共享 DDL、IAM、Firstleg 和公共门禁仍归总控。
“预约页面前端” 01a13e1c-db36-73e3-a231-d6649c51664b	按 V13 完成范围选择、后送续办、当前去向、整组重约、结果与失败续办、未定日期入口和上下文；更新直接测试及操作矩阵	不猜后端字段、未交付接口不做假成功；先做现有合同可支持的部分，新增写入按冻结合同接入。保留已有页面和弹框改动。

精确文件路径、共享文件归属及串行构建窗口沿协作契约第五节。总控负责收集三个任务的差异、接口准备情况和直接验证证据，不能仅转述“已收到”。本轮用户授权文档同步和继续开发；部署、SQL、测试环境写入等不因本文新增授权，已有另行授权由对应开发总控按原范围核验。

11. 最小验收矩阵

HTTP 性能门槛（2026-10-16 用户确认）：本预约链路涉及的每个接口、每次验收请求，从客户端发起到完整响应体读取结束均不得超过 1,000ms；同时独立校验 HTTP 状态、预期业务结果和数量/状态事实。不能以平均值或 P95 代替逐请求门槛，也不能把快速返回的同步中、非预期错误或缺少计时当作通过。预期拒绝场景须核对准确业务码，仍计入耗时。保留首次、超时、失败及重试记录，网络超时结果未知时先回查，不能盲目重放写操作；报告标明场景、方法/路径、耗时、requestId/traceId、运行版本及尚未覆盖项。HTTP 通过不代替页面验收，单轮全部达标也不构成任意负载下的性能保证。

编号	场景	必须结果
V13-01	乙 160 箱取消本次安排后重新约仓、配车、发车、签收、结束运输	原车甲丁 120 箱及其预约不变；乙来源和数量唯一；完成后待办退出、记录可查。
V13-02	乙 100 先送、60 后送，后送独立执行完成	原车 220 箱；乙始终 160；后送未定日期可反复进入直到完成，不重复创建。
V13-03	从后送入口选本批 60，加另一客户 40 共车	初始只选 60；新车 100，客户来源和预约结果分开；约仓、发车、各客户签收及运输完成可衔接，原车仍 220。
V13-04	后送 60 仅选 40，另 20 待排	原车卡片各显示 20 待排和 40 新批一次，直接可操作；20 持续留在未定日期并可再次安排，乙各批始终合计 160；不显示失效 0 箱或遗漏已分配去向。
V13-05	全部后送量再分配后从旧入口返回	直接找到当前新批次及车辆；重复点击/重试不重复占量，历史可追溯。
V13-06	单客户未收到仓库回复；先记待确认再续办	原预约保留，输入可续办，相关未解决变化阻止误发车；确认后仅处理目标客户。
V13-07	单客户从共约退出，填其他客户仍使用的旧约号	服务端拒绝孤立重约，不改其他成员；正确新约可继续；校验失败保留输入。
V13-08	整份共约改期	当前全部覆盖客户一致更新，影响车辆清楚；核对一次，无变化保存不反复复核。
V13-09	整份共约取消并重新共约	清失效目标/确认，保留原批次与原车；一次确认覆盖范围，形成新有效关联；再次整份变更按新范围。
V13-10	整份取消后分别重约，或甲先单独另约再办理剩余组	独立约号/时段分别保存；已另约甲排除且不被覆盖；车辆核对所有当前时段后才能执行。
V13-11	货没齐，保留量为 0；原车最终无有效货物	全部货量继续待办，不强留一箱；其他客户不被移动；无货原车按原业务取消/调整后正确关闭。
V13-12	未定日期关闭后再进、换月、取消类型勾选、返回分页	需求和跟进不丢，送仓/用车各按稳定身份显示；下一步及返回上下文准确。
V13-13	部分成功、关联失败、超时结果未知、重复提交、并发变化	复用原成功结果，只重试未完成步骤；不超分、不挂回已退出成员，过期版本不能清除新复核。
V13-14	只读/跨客户权限、来源失败、缺时区、跨日与 DST	权限及时间按正式合同校验；未知/失败不伪造零值、日期或成功；已有真实事实保留。
V13-15	中转多批、整柜直送、还空转交及已发车异常	柜级工作不重复；中转还空不等尾程送完；直送无海外仓入库，实际卸货才可还空；转交新车队须重新明确接手，原车队结果不沿用，未落实继续跟进；发车后不走普通移车取消。

V13 本地原型已走过多客户变化、后送单送/共车、部分再分配、整份取消重约、约号冲突与返回续办，相关浏览器检查及原有 24 项原型回归通过。可追溯脚本位于原型同目录：check-v11.cjs、check-v12.cjs、review-rebook-v13.cjs、review-partial-v13.cjs、review-v13-shared-rebooking.cjs、check-v13-usability.cjs。这只是交互证据；尤其 V13-13/14 的真实权限、持久幂等、并发、外部接口和完整时区规则仍须生产代码和集成验证。

交付时分别列出业务代码、定向检查、部署清单和待真实验收项；Admin 人工视觉验收按 1920×1080、100% 缩放。不得把原型确认或本地检查通过写成环境已上线、全链已验收。