5.1 KiB
业务单据编号契约
格式与分配
纳入本契约的新建业务单据采用 前缀 + yyyyMMdd + 四位流水，无分隔符。前缀为 2～4 位大写英文字母，总长度为 14～16 位，例如 FL202610200001。
- 业务日期统一按
Asia/Shanghai计算；每个前缀每天独立分配0001至9999。 - 同一前缀不按客户或仓库分段；服务内所有创建入口共用同一个序列。前缀按下表归属，禁止在不同服务重复分配同一前缀。
- 单号由服务端生成并保持不变。编辑、审核、作废、重复提交不换号；幂等重放返回原业务记录及原号，不重新取号。
- 序列在所属服务数据库内以原子更新和独立短事务分配；外层业务回滚允许断号，已分配号不回收。不以最大业务编号加一、时间戳、随机串、实体 ID 或其截断值生成。
- 单日四位流水用尽时明确失败，不改为五位、不循环或随机回退。日期在取号前确定，不能在格式化时重新读取日期。
- 本契约不授权对已有测试数据改号、回填、重置或执行 SQL；数据库与部署操作须独立授权。
前缀登记
| 服务 | 前缀与单据 |
|---|---|
| Order | FL 头程主订单 |
| Warehouse | ZGRK 国内整柜入库、ZGCK 国内整柜出库 |
| Firstleg | OB 订舱、TA 国内拖车派车、LP 预装/正式装柜计划、DECL 报关申报批次、BR 报关行批次、PS 船节点船期、SL 船期日历航次、ST 船期周模板、CLG 同柜组 |
| Lastleg 入出库 | WC 头程来源尾程订单、IP 入仓计划、CK 普通出库、DFCK 一件代发出库、HBCK 换标出库、THCK 退货出库、PDA 出库作业任务、DL 派送、EX 异常、CD 废弃 |
| Lastleg 库内服务 | TB 换标、ZY 转运、TH 退货、THHB 退货换标、RR 退货收货、RB 收货批次、HX 合箱计划、YY 送仓预约 |
| Lastleg 商业业务 | TR 本土卡车、LB 散板、CG 采购订单、PR 采购实收、PJ 采购交寄、PF 采购费用（含更正与退款费用）、PN 采购说明、PX 采购关闭、PG 采购更正记录 |
| Lastleg 车队 | PC 海外排车（原规则已符合）、CT 车次、FB 车队预订、FO 运力发布、VR 车辆运维记录 |
| Finance | REC 对账单、AR 应收结算、AP 应付结算、RC 充值申请、AC 账户流水、VC 车辆成本、VP 车辆付款、PAY 结算付款流水 |
同柜组按入仓码查询的公开摘要返回 groupNo；结算详情的付款流水返回 transactionNo，均取已生成的业务号。应收结算引用的收款凭证不生成 PAY 号，其 transactionNo 为空，不以内部 ID 或银行参考号替代。
同一类型的所有创建入口共用序列：例如普通卡车下单与车队商业池创建均使用 TR；正常车次与取货车次均使用 CT。预装和正式装柜清单继续使用同一个 LP 计划编号。
海外出库作业任务统一使用 PDA + yyyyMMdd + 四位流水，例如 PDA202610230001；一件代发、退货、转运和换标出库共用该序列，不拼接内部实体 ID。PDA 出库列表及详情以出库单号为主标识，任务号标明“任务号”作为辅助信息；扫描出库单号或任务号均可定位当前任务。入仓任务编号不在此规则范围内。
头程来源尾程订单采用 WC + yyyyMMdd + 四位流水，共14位，例如 WC202610210001，按来源柜 sourceContainerBookingId 复用：该来源柜首次创建尾程订单时在柜级行锁内取号，后续同柜的入仓单、不同客户或跨日交接事件复用原号；事件重放不重新取号。真实集装箱号 containerNo 不作为复用身份，不同来源柜即使使用相同集装箱号也不能共用尾程编号。
明确保留的规则
- 入仓码、拆分子订单号和子入仓码不变。子订单继续使用主订单号加拆分后缀；新主订单改号后子单自然继承主号，但不改拆分算法或重新分配独立流水。
- 柜次号继续使用全局连续的
D0001，不按日期重置，超过四位自然增长。 - 实物箱码、散货托盘码、退货/转运箱码及一件代发
DP-yyMMdd-####托盘标签不纳入本次改号。 - 换标、转运、退货来源尾程订单继续沿用对应业务单号，不增加第二套业务身份。
- 自营采集任务号、主数据编码及未列入登记表的其他编号不在本次范围。
- 外部提单号、真实集装箱号、运单号、FBA 货件号、银行流水号等保留外部原号。
实现与验收
通用格式由 baiyue-firstleg/common-core/.../number/DailyDocumentNumber.java 提供；各服务通过自己的 DocumentSequenceRepository → DocumentSequenceMapper 访问本库编号表。海外排车继续复用原 DispatchNumberSequence。
验证覆盖北京时间跨日、前缀独立、并发唯一、外层回滚不复用、缓存绕过、9999 上限、业务重放及保留编号规则。数据库变更同步模块空库基线和 deploy/sql/ 统一空库入口；本地测试不代表已执行数据库变更或已部署。