docs: 明确船期日历顺延和订柜统计口径

国内货柜履约/船期日历功能规划.md

@@ -6,7 +6,7 @@
 
 > **当前展示版范围已重新冻结：只做船期维护和只读展示，不做自动归班、不消费预报、不改写收货审核、不自动改绑，也不改变现有智能排柜流程。** 首版只需要让管理人员看到每个航次的已收/预计货量、可用容量、按柜型初算的建议柜数、已订柜和待补柜，并据此人工判断是否合并到其他船。后续若要增加货物归班，再单独立项评审。第 15.8 节覆盖本文此前关于自动归班和异常改配的旧口径。
 
-> **展示版统计口径**：每个船期按“收货仓 + 渠道 + 起运港 + 目的港”展示；已收使用现有收货/测量结果，预计量使用现有入仓和智能排柜可读数据；不创建或变更船期归班事实。收货截止时间只用于标记“截止前参考量/截止后风险”，不触发自动分配。订柜数只做只读初算，最终以现有智能排柜和人工确认结果为准。
+> **展示版统计口径**：日历仅展示上海时区今天及以后开船的计划。未离仓审核实测货量优先保留有效订舱和排柜对应的船期，未安排或原安排失效的余量按“收货仓 + 渠道”展示在最近一班尚未截仓的有效船期；各船期继续展示自身起运港和目的港。顺延只改变日历货量和订柜参考，不创建或变更船期归班、订舱或排柜事实。订柜数按统一柜型容量向上取整，已离仓柜的容量不再抵扣余货需求，最终以现有智能排柜和人工确认结果为准，详细规则以第 15.8 节为准。
 
 ## 1. 输入来源与现状边界
 
@@ -652,20 +652,21 @@ Phase 1 不提供正常货量的批量改绑、强制赶截止和容量预占；
 
 当前版本允许运营人员维护渠道、周模板和具体船期；货量相关能力全部只读：
 
-- **已收 CBM**：读取现有收货/测量流程已经产生的有效实测结果，不在船期页面重新生成收货事实。
+- **有效船期与过期**：按 `Asia/Shanghai` 自然日，月历和汇总只纳入今天及以后开船的计划；今天之前的计划自然过期并从日历移除，不删除记录、不伪造已开船状态。服务端返回上海本地时间 `nextRefreshAt`，取下一零点和同仓、同渠道范围内最近截仓时刻之后 1 毫秒的较早值；截仓查询不受展示月份、船名、港口或状态筛选限制。页面据此自动刷新，失败后延迟 60 秒重试，避免跨月顺延后货量停留在旧值。
+- **已收 CBM 与未发货顺延**：读取现有收货/测量流程已经产生且尚未确认国内离仓的有效实测体积。已排柜且关联有效 `RELEASED` 订舱的部分，保留在其开船日期不早于今天、状态为 `OPEN/CLOSED` 的船期，截仓后仍保留；支持既有跨仓、跨渠道安排。未安排或原安排取消、日期过期的余量，按原收货仓和渠道选取 `OPEN`、开船日期不早于今天且截止时间不早于当前时刻的最近一班，按开船时间、船期编号、ID 稳定排序。同一份货量只计入一班，部分排柜按体积分开，不受原收货月份限制；没有下一有效船期时保留原货物事实，后续新增有效计划即可承接。这里只改变只读展示，不改已确认订舱、排柜或真实运输安排。
 - **预计 CBM**：读取现有入仓预报或智能排柜可读数据；没有可靠来源时显示“暂无数据”，不凭渠道名称或订单分页猜测。
-- **截止前参考量**：按船期的收货仓、渠道、起运港、目的港和 `warehouseCutoffAt` 做查询口径，只用于显示“理论上可供管理人员参考的货量池”，不表示货物已经归入该船。
+- **截止前参考量**：对顺延后的待发货量按收货时间与 `warehouseCutoffAt` 区分参考量和风险量，不表示货物已经绑定该船。每次月历查询共用一个业务时刻，避免跨过截仓瞬间造成重复。
 - **已明确本船量**：只读取现有系统已经明确关联到该船名/航次或现有订舱/柜次事实的数据；日历不新增关联。
-- **建议订柜数**：按可展示货量和统一柜型容量做初算，显示计算时间、柜型和“最终以智能排柜/人工确认结果为准”；不创建订舱、不锁舱位、不改柜次。
+- **建议订柜数**：对展示的待发实测与可核验预计体积之和，除以统一柜型容量向上取整；正货量不足一柜也算一柜，零货量为零柜。晚到/风险标签不直接抹除已收货量。待补柜按货量先扣除未离仓柜的可用订舱容量，再按对应柜型向上取整，下限为零；已离仓柜的容量不能抵扣仓内余货。日历卡片、汇总和各柜型方案保持一致。不创建订舱、不锁舱位、不改柜次。
 - **合船判断**：页面只提供“本船未满、建议关注相邻船期”的提示，并展示相邻船的可用容量和货量对比；不自动合并、不自动改绑。
 
-展示版的数据实现口径再明确一层：已收实测只统计测量审核为 `APPROVED` 且有 `actual_volume_cbm` 的有效入库单，按上一班截止时间到当前班截止时间的窗口汇总；主单只在未拆分时统计，拆分后的有效余量子单单独统计，避免父子单重复。当前没有可核验的预计体积来源时，预计量按 0 展示并在页面提示“暂无可核验数据”，不得把申报体积、原始体积或分页列表合计冒充预计量。已订柜读取已放舱订舱的柜型需求，优先识别已有船期关联，同时允许用仓库、渠道、港口、船名、航次和开船日期做确定性只读匹配；日历页面不创建关联。建议柜数只按统一柜型容量计算，待补柜只做提示。
+展示版的数据实现口径再明确一层：已收实测只统计测量审核为 `APPROVED` 且有 `actual_volume_cbm` 的有效入库单，限定 `WAIT_PALLETIZE/WAIT_SPLIT/LOADING/LOADED`。未拆分单与拆分后的余量单各按自身实测体积统计；PDA 拣货结算后处于 `FULLY_SPLIT + LOADING/LOADED` 的源单已归一化为实际装柜部分，未离仓前同样保留，不能与整票原始体积重复。每票按有效装柜明细拆分为已离仓体积、有效订舱占用体积与未安排余量；已离仓要求客户、入库单和柜次一致，离仓状态为 `WAITING_FOR_LOADING` 且存在确认时间。扣除已离仓和有效订舱占用后，余量最低为零；订舱占用部分单独计入对应船期，撤销离仓后按现有运输安排重新纳入。当前没有可核验的预计体积来源时，预计量按 0 展示并在页面提示“暂无可核验数据”，不得把申报体积、原始体积或分页列表合计冒充预计量。已订柜读取已放舱订舱的柜型需求，存在有效显式关联时只认该关联；没有有效显式关联才用仓库、渠道、港口、船名、航次和开船日期做确定性只读匹配，每条订舱只选一班。已订总容量保存在 `bookedPlanningCapacityCbm`，扣除已离仓柜后的可用容量为 `availableBookedCapacityCbm`；按订舱需求中的柜型容量整柜扣除，同柜多票只扣一次，撤销离仓后恢复。日历页面不创建关联，待补柜只做提示。
 
 当前版本明确不做以下写操作：
 
 1. 收货审核通过时，不调用船期日历服务，不写入 `fl_sailing_assignment`、预报消费或船期实收事实。
 2. 创建或修订预报不自动生成船期归班；预报维护接口不作为本轮页面入口。
-3. 取消船期不自动把任何货物转到下一班；货物归属仍由原智能排柜和订舱流程维护。
+3. 取消船期后未离仓货量按上述规则顺延展示；不改写货物实际归属，仍由原智能排柜和订舱流程维护。
 4. 页面不提供货量异常改配、手工绑定实收、订舱关联/解除等操作；这些操作留在现有业务流程。
 
-因此，本轮验收重点从“自动归班正确”改为：船期维护正确、展示口径透明、已收/预计/已订柜/建议柜数不重复、取消或截止只影响展示标签、不会改变原收货和智能排柜数据。后续如果需要让管理人员在页面上确认“合并到哪一班”，再单独增加人工确认动作和正式归属模型。
+因此，本轮验收重点从“自动归班正确”改为：船期维护正确、展示口径透明、未发货量顺延且不重复、建议柜数向上取整、取消或截止只影响只读展示，不会改变原收货和智能排柜数据。后续如果需要让管理人员在页面上确认“合并到哪一班”，再单独增加人工确认动作和正式归属模型。