18 KiB
18 KiB
虫虫出海二期开发规划：头程到仓与头程计费
创建日期：2026-07-28
更新日期：2026-07-31
状态：开发已启动，3 项计费细节确认中
流程依据：头程物流流程图中的头程物流“02 到仓”
产品确认：2026-07-31 产品确认合并记录
前置阶段：一期文档
主体模型：二期只实现“平台—客户”两级。
tenant_id > 0/tenantId是客户 ID 兼容字段，tenant_id=0是平台技术作用域；不得新增真实租户、租户选择器、租户级 RBAC 或重定义现有隔离字段。
一、二期目标
二期承接一期“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。
线下预约 / 送货预报
↓
货物到达平台收货仓
↓
实际收货、称重、测量和拍照
↓
申报与实测差异记录并通知客户
↓
仓库作业（指定库位）
↓
头程费用试算与费用明细确认
二期不建设应收应付、对账、收付款、核销、发票、利润或总账。完成标准是每票货能够回答：何时到仓、实际收到什么、实测结果是什么、与申报差多少、差异是否已通知、最终放在哪个库位，以及产生了哪些头程费用和计算依据。
二、阶段边界
纳入二期
- 客户取货或送货预报，以及线下预约结果、改期和取消记录。
- 平台收货仓到仓签到、分批收货、处理单元标签和收货冲正。
- 实收件数、重量、体积、尺寸、外包装、称重照片和测量照片。
- 申报数据与实测数据对比、差异记录、客户通知和审计。
- 最小库位档案、上架任务、指定库位和位置历史。
- 头程费用项目、计费规则版本、费用试算、人工费用、调整、确认和费用明细。
- 服务端权限、基于兼容字段
tenant_id的客户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。
明确不纳入二期
- 应收应付台账、客户/供应商对账、账单确认和争议。
- 收款、付款、退款、核销、反核销、银行流水和在线支付。
- 发票登记、开票接口、汇率结算、利润和财务报表。
- 会计科目、会计凭证和总账。
- 流程图头程“03 出仓”：智能排柜、订舱、拖车、PDA 拣货、装柜、报关和港务信息。
- 完整 WMS：可用库存、库存成本、常规移库、盘点、冻结、拣货、复核和出库。
- PDA 硬件或厂商 SDK；二期使用后台或响应式作业页。
- 独立隔离区、差异等待客户确认、无预报货物认领和待认领区。
- 时间窗容量调度、自动服务商分配、地图、GPS 和外部承运商接口。
- FBA/海外目的仓及尾程到港、到仓、出仓和签收流程。
三、已确认业务规则
| 编号 | 产品结论 | 开发规则 |
|---|---|---|
| P2-Q1 | 以实际货物重量、体积为准 | 实测结果作为后续作业和头程计费输入，申报值只用于对比 |
| P2-Q2 | 不做系统服务商调度 | 取货安排在线下完成，系统只记录结果 |
| P2-Q3 | 预约在线下完成 | 记录预约日期时间、改期/取消结果和操作日志，不建设容量调度 |
| P2-Q4 | 小数点三位向上取整 | 保存原始值和公式版本，业务结果按三位向上取整 |
| P2-Q5 | 差异同步客户，无需确认，只做记录 | 差异不阻塞上架或计费；记录通知结果和审计 |
| P2-Q6 | 不考虑隔离区 | 不建设隔离库位、隔离上架和释放流程 |
| P2-Q7 | 不做库位容量校验 | 仅校验库位启停、仓库归属和权限合法性 |
| P2-Q8 | 称重、测量照片必传，大小不限制 | 产品不设业务大小上限；系统保留文件类型校验和可配置技术安全上限 |
| P2-Q9 | PDA 暂缓 | 二期使用后台或响应式作业页 |
| P2-Q10 | 不考虑无预报货物 | 不建设无预报认领和正式订单绑定流程 |
| P2-Q11 | 永久保存 | 业务记录不自动删除；访问审计、备份和合规策略由运维补充 |
| P2-Q12 | 佳博 1324D 热敏标签打印机 | 开发前实机核验纸张、连接、驱动和指令协议 |
| P2-Q13 | 二期只做头程计费 | 费用结果不自动形成应收、应付、账单或收付款数据 |
四、角色与数据边界
| 角色 | 数据范围 | 主要操作 |
|---|---|---|
| 企业订单操作员 | 当前企业订单和到仓单 | 提交预报、查看到仓、实测、差异通知和公开费用 |
| 企业管理员 | 当前企业全部订单和到仓单 | 查看到仓、实测、差异、上架和公开费用 |
| 平台客服/运营 | 授权客户和订单范围 | 维护预约结果、处理异常、通知差异和查看头程费用 |
| 仓库收货员 | 被授权的平台收货仓 | 到仓签到、收货、测量、拍照和异常登记 |
| 仓库上架员 | 被授权的仓库和库位 | 领取上架任务、指定库位和确认完成 |
| 计费专员 | 授权客户、仓库和业务范围 | 费用试算、人工补录和发起调整 |
| 计费审核员 | 授权计费范围 | 确认费用、审核调整和作废 |
| 计费管理员 | 平台计费范围 | 维护费用项目、计费规则版本和权限 |
| 平台管理员 | 平台授权范围 | 维护仓库、库位、快递公司、往来单位和权限 |
服务端根据登录身份确定企业、平台和仓库数据范围；前端传入的订单 ID、企业 ID、仓库 ID 或操作员 ID 不能单独决定授权。
五、业务模块
1. 到仓预报与预约结果
- 订单与到仓单采用 1:N；同一订单可以分次到仓。
- 预约在线下完成，系统记录到仓方式、预约时间、联系人、平台收货仓、改期、取消和备注。
- 不建设时间窗容量、服务商自动分配和外部调度接口。
2. 到仓签到与分批收货
- 到仓单与收货批次采用 1:N；每批记录实际到仓时间、交接人、收货员、实收数量和凭证。
- 以实际货物数量、重量和体积为后续作业依据。
- 系统不接收无预报货物的正式订单绑定，不建设待认领流程。
- 错绑订单或企业通过主管冲正处理，原记录不可删除。
3. 处理单元和标签
- 收货批次拆分为箱件或托盘处理单元，生成稳定内部编码。
- 支持打印、失败重试、补打、换标和作废；同一有效标签不能绑定多个处理单元。
- 使用佳博 1324D 实机完成标签适配验证。
4. 测量和照片
- 保存原始长度、宽度、高度、重量、体积、材积重和计费重，以及单位和公式版本。
- 原始值不可覆盖；复测生成新版本并记录原因和操作者。
- 业务结果按小数点三位向上取整，同时保留未舍入原始值。
- 称重照片和测量照片必传；服务端执行格式、恶意内容、访问权限和可配置技术大小上限校验。
5. 差异记录与通知
- 自动对比申报与实测的数量、重量、体积、尺寸和包装信息。
- 差异只记录并通知客户，不需要客户确认，不暂停上架和计费。
- 保存差异类型、申报值、实测值、通知状态、通知时间和审计记录。
6. 库位与上架
- 维护仓库、库区、库位编码、名称、状态和权限范围。
- 二期不做承重、箱数或体积容量校验，也不建设隔离区和待认领区。
- 上架任务关联收货批次、目标库位、执行人、状态和完成时间。
- 上架完成后写入处理单元当前位置和历史位置，为后续出仓提供输入。
7. 头程计费
- 维护头程费用项目、计费单位、币种、税务属性、业务阶段和启停状态。
- 计费规则按已确认维度和生效区间版本化，历史费用保存规则和计算快照。
- 头程订单、到仓实测或已确认业务事件触发费用试算，重复事件不得重复计费。
- 支持自动费用、人工补录、调整、确认、作废、查询和导出。
- 已确认费用不直接覆盖，变更通过调整记录留痕。
- 详细规则见 二期头程计费模块规划。
六、状态模型
到仓单状态
| 状态 | 含义 |
|---|---|
CREATED |
已创建，等待线下预约结果 |
SCHEDULED |
已记录预约结果 |
PARTIALLY_RECEIVED |
已有收货批次，仍有计划货物待到仓 |
RECEIVED |
实际收货完成 |
PUTAWAY_PENDING |
等待指定库位 |
PUTAWAY_COMPLETED |
指定库位完成 |
CANCELLED |
到仓前取消 |
差异状态
| 状态 | 含义 |
|---|---|
DETECTED |
已检测到差异 |
NOTIFIED |
已通知客户 |
CLOSED |
差异记录已归档 |
差异状态不阻塞到仓主状态、上架或头程计费。
头程费用状态
| 状态 | 含义 |
|---|---|
DRAFT |
草稿或人工补录中 |
CALCULATED |
已试算 |
CONFIRMED |
已确认，禁止直接覆盖 |
VOIDED |
已作废，保留历史和原因 |
七、核心数据对象
| 数据对象 | 关键内容 |
|---|---|
| 到仓单 | 订单、仓库、到仓方式、预约结果、联系人、计划摘要和状态 |
| 收货批次 | 实际到仓时间、交接人、收货员、实收摘要和凭证 |
| 处理单元 | 箱件/托盘编码、标签状态、所属批次、数量和当前位置 |
| 标签记录 | 处理单元、标签编码、设备、打印结果、补打、换标、作废和原因 |
| 测量规则版本 | 单位、公式、三位向上取整、生效时间和版本状态 |
| 测量明细 | 原始尺寸/重量、换算值、舍入结果、规则版本、照片和复测版本 |
| 差异记录 | 申报值、实测值、差异类型、通知状态、通知时间和审计信息 |
| 库位 | 仓库、库区、编码、名称、状态和权限范围 |
| 上架任务/位置记录 | 收货批次、目标库位、执行人、状态、当前和历史位置 |
| 费用项目 | 编码、名称、费用性质、单位、币种、税务属性、业务阶段和状态 |
| 计费规则版本 | 适用维度、价格参数、生效区间、版本和发布状态 |
| 头程费用明细 | 业务来源、来源键、计费输入、规则快照、金额、状态和调整链 |
| 审计记录 | 操作、对象、前后值、操作者、时间、请求和结果 |
所有基础资料引用同时保存稳定 ID 和必要快照。历史到仓、测量和费用记录不得因基础资料改名、停用或规则更新而改变。
八、应用和服务范围
管理后台 apps/admin-web
- 到仓单、预约结果、签到、收货批次、标签、测量、照片和差异通知。
- 库区/库位、上架任务和当前位置查询。
- 费用项目、计费规则、费用试算、人工补录、调整、确认、作废和导出。
企业客户端 apps/client-web
- 创建取货或送货预报。
- 查看预约结果、到仓时间线、实测、公开照片、差异通知和上架结果。
- 如二期客户端展示头程费用，只显示本企业公开费用，不显示内部备注和其他企业数据。
国内头程后端 baiyue-firstleg/
- 最终保证身份、客户归属、仓库数据范围、状态转换、幂等、并发和审计。
- 管理到仓单、收货批次、处理单元、标签、测量、差异通知、库位、上架、位置和冲正事务边界。
- 管理计费规则版本、费用生成幂等、三位向上取整、费用调整和历史复算。
- 文件访问使用不可预测标识和授权下载，不信任客户端文件名与 MIME 类型。
九、里程碑
| 里程碑 | 交付目标 | 进入条件 |
|---|---|---|
| P2-M0 规则锁定 | 到仓契约、测量口径、头程计费边界和权限基线确认 | 一期订单及基础资料契约稳定 |
| P2-M1 到仓预报 | 取货/送货预报及线下预约结果可记录 | 收货仓 API 可用 |
| P2-M2 到仓收货 | 签到、分批收货、标签、照片和冲正可追溯 | 文件服务和仓库权限可用 |
| P2-M3 测量差异 | 原始测量、三位向上取整、差异记录和通知可用 | 测量公式可用 |
| P2-M4 库位上架 | 库位、上架任务和位置历史可查 | 库位编码规则确认 |
| P2-M5 头程计费 | 费用项目、规则版本、试算、调整和费用明细可用 | P2-Q14 至 Q16 确认，P2-M3 可用 |
| P2-M6 联调验收 | 跨端联调、安全、幂等、复算、性能和发布完成 | P2-M1 至 P2-M5 验收通过 |
十、开发任务
| ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 |
|---|---|---|---|---|---|
| P2-BASE-01 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 一期订单契约 |
| P2-BASE-02 | 公共 | 数据模型 | 到仓单、批次、处理单元、标签、测量、差异、库位、位置、费用和审计 | P0 | P2-BASE-01 |
| P2-ADM-01 | 后台 | 到仓列表 | 查询、筛选、分页、详情、空态和异常态 | P0 | P2-BASE-01 |
| P2-ADM-02 | 后台 | 预约结果 | 记录、调整和取消线下预约结果 | P0 | P2-ADM-01 |
| P2-CLI-01 | 客户端 | 到仓预报 | 取货/送货方式、联系人、仓库和货物摘要提交 | P0 | P2-BASE-01 |
| P2-WH-01 | 后台 | 到仓签到 | 识别到仓单、分批收货、交接和异常登记 | P0 | P2-BASE-02 |
| P2-LABEL-01 | 后台 | 处理单元标签 | 编码、佳博 1324D 适配、失败重试、补打、换标和作废 | P0 | P2-WH-01 |
| P2-REV-01 | 后台 | 收货冲正 | 错绑企业/订单/到仓单的审批、解绑和重绑 | P0 | P2-WH-01 |
| P2-WH-02 | 后台 | 入库测量 | 原始测量、三位向上取整、复测、照片和历史复算 | P0 | P2-LABEL-01 |
| P2-DIFF-01 | 公共 | 差异计算 | 申报实测对比、差异记录、通知状态和审计 | P0 | P2-WH-02 |
| P2-ADM-03 | 后台 | 差异通知 | 查看、补充说明、通知客户和关闭记录 | P0 | P2-DIFF-01 |
| P2-CLI-02 | 客户端 | 差异查看 | 查看实测、公开照片和差异通知，不提供确认动作 | P1 | P2-DIFF-01 |
| P2-HOLD-01 | 公共 | 异常记录 | 非差异类异常、责任人、证据、处理结果和审计 | P1 | P2-BASE-02 |
| P2-LOC-01 | 后台 | 库位维护 | 库区、库位编码、状态和权限范围，不做容量校验 | P0 | P2-BASE-02 |
| P2-PUT-01 | 后台 | 上架任务 | 创建、分配、拆分、异常和完成，不做隔离上架 | P0 | P2-LOC-01、P2-WH-02 |
| P2-POS-01 | 公共 | 位置记录 | 处理单元当前位置和进入/移出历史 | P0 | P2-PUT-01 |
| P2-SEC-01 | 公共 | 文件与保留 | 文件鉴权、类型/安全校验、访问审计、永久保存和备份边界 | P0 | P2-WH-01 |
| P2-TIME-01 | 公共 | 时间线通知 | 对客事件、差异通知和失败补偿记录 | P1 | 核心流程完成 |
| P2-FEE-01 | 后台 | 费用项目 | 头程费用项目、单位、币种、税务属性和启停 | P0 | P2-Q14、P2-BASE-01 |
| P2-RATE-01 | 后台/服务端 | 计费规则 | 规则维度、版本、生效区间、价格结构和发布 | P0 | P2-Q15、P2-FEE-01 |
| P2-CALC-01 | 服务端 | 计费引擎 | 规则匹配、试算、事件触发、幂等、三位向上取整和复算 | P0 | P2-Q16、P2-RATE-01、P2-WH-02 |
| P2-FEE-02 | 后台 | 头程费用明细 | 自动/人工费用、确认、调整、作废、查询、导出和审计 | P0 | P2-CALC-01 |
| P2-TEST-01 | 公共 | 自动化测试 | 越权、幂等、测量舍入、计费复算、标签、差异、位置、文件和审计 | P0 | 所有 P0 模块 |
| P2-REL-01 | 公共 | 发布验收 | 初始化仓库、库位、测量规则、标签和费用基础数据，联调、验收和发布 | P0 | P2-TEST-01 |
二期开发任务共 24 项。应收应付、对账、账单中心、收付款核销、发票和利润六项任务已根据产品确认从二期移除。
十一、测试与验收重点
- 企业 A 不能读取或操作企业 B 的到仓、测量、差异或费用数据。
- 重复预约记录、签到、标签生成、测量、上架和计费事件不产生重复有效记录。
- 实测修改保留旧版本、原因和操作者；原始值和三位向上取整结果可追溯。
- 差异能够通知客户并记录结果，但不会等待客户确认或阻塞上架、计费。
- 称重照片和测量照片必传；文件类型、恶意内容、越权访问和技术大小上限校验有效。
- 佳博 1324D 实机打印内容、尺寸、清晰度、连续打印、缺纸、断电和重试符合预期。
- 不存在隔离区、待认领区、无预报认领或库位容量拦截的隐藏流程。
- 上架完成后每个处理单元只有一个有效当前位置，停用或越权库位被拒绝。
- 相同计费事件重试不重复生成费用；历史费用能按规则版本和输入复算一致。
- 已确认费用不能静默覆盖；调整、作废和导出均有审计。
- 系统不会生成应收、应付、对账单、收付款、核销、发票或利润数据。
- 页面覆盖加载、空态、失败、无权限、重复操作、数据过期和窄屏场景。
十二、仍需确认事项
| 编号 | 待确认问题 | 当前建议 |
|---|---|---|
| P2-Q14 | 首批头程费用项目、单位、币种、税率和触发节点 | 只纳入“02 到仓”实际使用费用；白名单外人工补录需留痕 |
| P2-Q15 | 计费维度、阶梯价、最低收费、封顶、组合价和优先级 | 先支持客户、往来单位、仓库、服务和生效区间 |
| P2-Q16 | 费用试算、生成、确认、调整和作废节点 | 实测完成试算，其他费用按已确认业务事件生成 |
回传中的“63”不作为业务结论。P2-Q13 已确认仅做头程计费；P2-Q17 至 P2-Q24 不纳入二期。
十三、建议实施顺序
- 合并已确认的到仓规则，更新状态、权限和数据对象。
- 实现到仓预报、线下预约结果、签到和分批收货。
- 实现处理单元、佳博 1324D 标签、冲正和必传照片。
- 实现原始测量、三位向上取整、复测和差异通知。
- 实现库位、上架任务和位置历史，不建设隔离和容量校验。
- 确认 P2-Q14 至 Q16，建立头程费用项目和计费规则版本。
- 接入实测和业务事件，完成费用试算、人工补录、调整和费用明细。
- 完成跨客户隔离、幂等、计费复算、文件安全、审计和回归测试。
- 使用脱敏初始化数据联调、验收和发布。