java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: complete October 22 workflow feedback and request failure recovery

Browse Source
This commit is contained in:
ouyangxq
2026-10-22 23:06:00 +08:00
parent f701456de1
commit a16a85e14a
85 changed files with 1518 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
firstleg/docs/business-index.md
+2 -2
View File
@@ -79,7 +79,7 @@
- 客户箱规配置必须恰好保持四档且默认算法在四行一致；`ADD` 以实测尺寸为基准对三个维度分别增加命中箱规的尺寸值，`MULTIPLY` 使用当前客户唯一默认计费规则，并由服务端按规则中的规格档位选择系数。测量行必须保存实际尺寸、选用规则和算法快照，页面不得自行重算后覆盖服务端结果；计价使用用户确认的重量/体积选择值并纳入幂等请求哈希。
- 报关、订舱和拖车引用的供应商必须通过 `WarehouseSupplierSnapshotService` 按 ID 向 Warehouse 校验：报关使用 `CUSTOMS`，订舱使用 `BOOKING`（不区分国内/国外 scope），国内拖车使用 `TRUCKING + truckingScope=DOMESTIC`，清关提柜/目的港码头拖车使用 `TRUCKING + truckingScope=OVERSEAS`；供应商必须为 `ACTIVE`。请求中的名称只能作为一致性提示，持久化名称必须来自 Warehouse 快照，禁止用自由文本绕过 ID、类别或启用状态校验。修改任一供应商引用 DTO、OpenAPI 或内部客户端时，必须同步检查三条业务链、Warehouse `supplier-v1.yaml`、数据库快照字段和对应契约测试。
- Order 渠道变更门禁必须检查装柜或后续状态、PDA task、预装、分柜及同柜组兼容性；任何不确定结果均失败关闭。`ORDER_DECLARATION_UPDATED_V1` 消费必须校验订单号/入仓码归属，永久保留 `eventId + payload hash` 幂等历史并按版本单调更新申报投影；不得覆盖仓库实测、箱码、测量审核或已确认费用。
- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后运输、预报货量、三方和柜型需求只读；仅三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后除预计到港外的运输、预报货量、三方和柜型需求只读；预计到港允许通过 `/estimated-arrival` 按编辑权限、版本与幂等键单独维护，保留前后审计快照且不得清空或早于预计开船，不改实际到港或计划到仓；三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。预计到港草稿可留空，放舱前必填且不得早于预计开船时间；关联柜次时带入柜级到港来源，供日历和默认到仓日期解析使用。
- 订舱号遵循 `../../../docs/业务单据编号契约.md`；不得以实体 ID 拼接生成。提单号在订舱主表全局唯一，柜次表只保存快照；真实集装箱号只在同一订舱内唯一，不同提单允许复用。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
- 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。
@@ -94,7 +94,7 @@
## 国内货柜履约装柜与 PDA 资源结算
- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺，但确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺；该关联入口仅规范化空白和大小写，不以 ISO 长度、结构、设备类别或校验位阻断，数据库不设置 ISO 格式 CHECK，仍遵守同订舱唯一及已有柜号一致性。关联已接受的柜号在运输信息未改号时不重复做 ISO 校验；确认预装与创建 PDA 任务前必须校验 ISO 格式并提示在预装运输信息中纠错，避免实物作业后无法完成，PDA 完成及跨服务事件保持原有格式校验；运输或提柜首次录入及纠正为不同柜号保留原有规则。确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
- 预装进入 `CONFIRMING/CONFIRMED` 只固化确认快照，不得锁死尚未完成柜次的智能装柜分配；装柜计划仍处于 `EDITING/LOADING` 时可继续新增，未产生实物拣货的明细可调整或移除，已拣明细保持锁定。一件代发智能装柜候选以每个未被有效柜次占用的已封托托盘为独立分页、展示和分配单位；同一入仓单有多托时必须逐托返回，其中一托已分配不得隐藏或禁用其余未分配托盘。智能推荐必须逐个调用整托分配，容量不足时跳过整托，不得回退按箱分配；全局工作台传入当前 `customerId/inboundCode` 筛选范围时，服务端只能推荐同时命中的候选，同一次推荐按受影响客户统一重算费用，不得逐托重复重算。单行删除必须按该行 `palletId` 整托移除。装柜完成事件必须按计划项 `palletId` 精确冻结每托箱唛与 SKU 清单，不得仅按入仓单或货物明细关联而造成多托交叉重复。
- 客户入库费用只在登录客户范围、测量审核通过、`feeStatus=SENT` 且存在已发布明细时可见；确认必须具备 `merchant:order:edit`，携带当前 `expectedFeeVersion` 与幂等键。成功后记录确认成员和时间；客户未确认或该票尚未装柜完成时，平台仍可修改箱规规则、生成新费用版本并重新发送，新版本必须清空旧版客户确认快照。仅当“客户已确认且该票已装柜完成”同时成立时最终冻结；装柜完成不得代替客户自动确认。旧版本、未发送或重复异参确认均返回冲突，不做兼容覆盖。
- PDA 普通散箱拣货以 `fl_inbound_carton_label.box_code` 对应的稳定箱唛箱码为扫描身份；审核建单、重复打印、手工测量和墨家测量复用同一映射，版本字段只用于并发控制，不进入扫码文本。一个有效且未重复的箱码扫描表示拣出一箱，不得以 SKU、商品件数、入库单号或页面展示字段替代箱码。一件代发已封托的 `SEALED_PALLET` 是不可拆整托单元，PDA 可扫描计划快照中的 `palletNo`、用该托任一成员 `boxCode` 反查所属整托，也可在明细卡片手工确认整托；三种入口最终都必须携带权威 `palletNo` 以 `PICK_PALLET` 一次性提交，不能按成员箱逐箱累计、部分拣货或跳拣。PDA 首页从 Warehouse 主档选择启用国内仓，一件代发与装柜待办列表必须按所选 `warehouseId` 服务端过滤；装柜任务内部仍允许跨国内仓，仓库与渠道限制统一由上游装柜编排负责，PDA 只按已生成任务读取各入仓单自身的 `CONFIRMED` 库位资源，不得再用柜次仓库过滤任务明细、库存快照或拣货写入。任务下发与提交契约见 `src/main/resources/openapi/phase3-pda-convergence-v1.yaml`。