docs: 记录船期顺延真实 HTTP 验收结果

国内货柜履约/船期日历功能规划.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. 页面不提供货量异常改配、手工绑定实收、订舱关联/解除等操作；这些操作留在现有业务流程。
 
-因此，本轮验收重点从“自动归班正确”改为：船期维护正确、展示口径透明、已收/预计/已订柜/建议柜数不重复、取消或截止只影响展示标签、不会改变原收货和智能排柜数据。后续如果需要让管理人员在页面上确认“合并到哪一班”，再单独增加人工确认动作和正式归属模型。
+因此，本轮验收重点从“自动归班正确”改为：船期维护正确、展示口径透明、未发货量顺延且不重复、建议柜数向上取整、取消或截止只影响只读展示，不会改变原收货和智能排柜数据。后续如果需要让管理人员在页面上确认“合并到哪一班”，再单独增加人工确认动作和正式归属模型。

测试环境单机部署与配置契约.md

@@ -1,5 +1,14 @@
 # 测试环境单机部署与配置契约
 
+## 2026-10-27 船期日历顺延与订柜建议：已发布 TEST
+
+- 用户授权部署本轮已提交的船期日历修改。Firstleg 最终提交 `57cd211973a87176a902eafdc6c68b4b501acb58`，`baiyue-firstleg-firstleg #523` SUCCESS；Admin 提交 `3464f35a010582fd7f86807d4db3b01c82dd6cb6`，`admin-web-test #721` SUCCESS。实际镜像标签分别为 `57cd211973a8`、`3464f35a0105`，均 running/healthy；发布前后仅这两个应用容器变化，环境变量及挂载摘要未变，Admin 临时 SCM 固定已逐字恢复。
+- 首次 Firstleg `#522` 容器健康，但真实 11 月月历查询发现跨表排序规则冲突（MySQL 1267）。已在 Mapper 中按字段完整长度统一文本比较，保留完整渠道、港口、船名和航次匹配；修复后 48 项后端定向测试通过，再发布 `#523`。另有 28 项发布静态合同通过；复用 Admin 27 项业务测试，Jenkins 类型检查及生产构建通过。
+- 发布后 12 次只读业务 HTTP 检查均成功，覆盖历史月、当前月、下月、四个有效船期的货量汇总和订柜建议，以及原货物渠道筛选。10 月五个过去船期已从月历隐藏，11 月四个船期正常返回，并提供下一刷新时间。Admin 健康入口、船期页面及船期脚本均返回 200，页面和脚本摘要与运行容器一致；独立验收会话已退出。
+- 原截图船期 `SL202610210001` 的渠道为 `EXX_RAIL_NY`；首次发布时 11 月四个船期均属于另一渠道，同仓同渠道筛选为空。随后用户授权真实 HTTP 验收，按该仓库、渠道创建五个带 TEST 标记的临时船期；验收时实际未发货量为 123.986 m³，40GP/40HQ/45HQ 分别建议及待补 3/2/2 柜。等待真实截仓时间后，前班体积归零、下个月承接全部 123.986 m³、后续班为零；再取消承接班，体积完整进入下一班，没有重复统计。顺延仅改变只读货量投影，没有迁移正式订舱或排柜归属。
+- 本轮专项正式执行 46 次 HTTP 请求、29 项断言全部通过，另有 6 次只读预检请求；覆盖过去船期隐藏、今天保留、三柜型向上取整、跨月筛选的刷新边界、真实截仓与取消顺延、未登录/不存在船期/陈旧版本拒绝，以及原业务船期及其历史不变。五个临时船期 `SL202610270001` 至 `SL202610270005` 全部取消并保留审计，未留下开放验收计划，独立会话已退出；因此该渠道仍需业务人员配置正式后续船期。没有在真实环境操作已订容量、离仓或撤销离仓，相关边界仍以定向测试为证，人工页面验收待完成。
+- 部署阶段未造业务数据，后续验收只创建、编辑拒绝探测和取消自有临时船期；未执行业务 SQL、修改 Nacos、改动货物/订舱/排柜或发布其他服务，验收前后两应用容器版本及健康保持不变。部署证据在本机私有临时目录 `codex-sailing-release-20261027-iZrD1t`；HTTP 专项证据在 `codex-sailing-http-20261027-raL6DD` 的 `preflight.json`、`execute.json` 和 `summary.json`，含逐请求诊断及写入前检查点，不含凭据。
+
 ## PDA H5 发布方式（2026-10-23 当前约束）
 
 - 国内、海外 PDA H5 在 TEST 与既有灰度统一采用宿主机 Nginx/宝塔站点直接托管构建产物。两端独立根目录，`location /` 读取上传的静态文件；`/gateway-api/` 独立转发当前环境统一 Gateway `/api/`。PDA H5 不再作为容器发布单元，不构建、恢复或发布旧 H5 镜像/Compose 服务；Admin、Client 与后端发布方式不受本条影响。