提交

lastleg-service/docs/business-index.md

@@ -60,7 +60,7 @@
 | 海外采购、客户下单、采购审核、客户/采购仓候选与操作流水 | `procurement/controller/`、`procurement/service/OverseasProcurementService.java`；客户入口按 `merchant:cross-border:procurement:list/create` 拆分且只取 Token 客户范围；OpenAPI `src/main/resources/openapi/overseas-business-v1.yaml` |
 | 海外业务资金指令与结果 | `wallet/WalletCommandOutboxService.java`、`WalletCommandCompletedConsumer.java`、`WalletResultHandler.java`；采购、换标、人工海外费用和仓租通过 `WALLET_COMMAND_REQUESTED` 请求 Finance 冻结、结算或释放，并以 `WALLET_COMMAND_COMPLETED` 幂等回写业务资金状态；不得同步调用 Finance 钱包或在 Lastleg 自建余额账本 |
 | 海外业务费用来源 | `financefee/controller/PlatformOverseasFeeSourceController.java`、`financefee/service/OverseasManualFeeService.java`、`OverseasFeeSourceService.java`、`OverseasFeeBusinessGuard.java`、`OverseasFeeOutboxService.java`；费用必须匹配当前客户的真实服务单，公共费用目录通过 Firstleg 内部接口读取。头程附加费审核后进入账单；海外人工应收创建先冻结、审核后扣款，驳回或取消释放，扣款成功后仅登记本地已收来源，不再推送财务账单；采购、换标原业务收费仍按其独立资金身份处理。头程账单费用及供应商应付经直接 Outbox 投递 Finance，余额应收仅通过资金指令取得扣款回执，OpenAPI `src/main/resources/openapi/overseas-finance-fees-v1.yaml`。新菜单列表权限与财务编辑、审核按钮权限分离；本地检查不能代替真实资金、账单联调 |
-| 自动仓租及出库资金门禁 | `storagerent/`；实际 PDA 收货建立原计租批次，头程自有海外仓目的地与仓储转运用中转阶梯，退货用原托阶梯；每24小时进一天，部分出库只承担原批次份额，余货不重置库龄。实际出库命令前单独提交资金预校验，冻结成功后才允许扣库存，按真实出库部分生成待审核仓租，订单费用与海外费用管理展示实际入库、出库、原计算额及实扣额；审核前可调价且说明必填，批准后沿原冻结按实额结算，驳回释放冻结；全部仓租使用余额及授信。客户仓租配置优先，无配置按报价表默认，内部查询失败不得回退。预占保存配置版本、完整阶梯、USD/CNY 原币及结算汇率快照，实际扣款不读最新价格。发布及真实验收清单见 `docs/overseas-fees-storage-rent-release.md` |
+| 自动仓租及出库资金门禁 | `storagerent/`；实际 PDA 收货建立原计租批次，头程自有海外仓目的地与仓储转运用中转阶梯，退货用原托阶梯；每24小时进一天，中转部分出库按原批次份额计费，退货原托余一箱仍按整托计费，同托同计租日不重复收取，余货不重置库龄。退货已计费截止日与实际出库、费用生成同事务推进，后续只收新增库龄；并发推进后旧预占必须释放重建。实际出库命令前单独提交资金预校验，冻结成功后才允许扣库存并生成待审核仓租，订单费用与海外费用管理展示实际入库、出库、原计算额及实扣额；审核前可调价且说明必填，批准后沿原冻结按实额结算，驳回释放冻结；全部仓租使用余额及授信。客户仓租配置优先，无配置按报价表默认，内部查询失败不得回退。预占保存配置版本、完整阶梯、USD/CNY 原币及结算汇率快照，实际扣款不读最新价格。发布及真实验收清单见 `docs/overseas-fees-storage-rent-release.md` |
 | 美国/本土卡车订单 | `trucking/controller/PlatformUsTruckOrderController.java`、`MerchantUsTruckOrderController.java` 及同子域 Service/DTO；客户入口按 `merchant:cross-border:domestic-trucking:list/create/edit` 拆分 |
 | 本土散板订单 | `looseboard/controller/PlatformLocalLooseboardController.java`、`MerchantLocalLooseboardController.java` 及同子域 Service/DTO/Entity/Mapper；客户入口按 `merchant:cross-border:pallet-shipping:list/create/edit` 拆分；OpenAPI `src/main/resources/openapi/overseas-business-v1.yaml` |
 | 海外仓报价、月度汇率、车辆主数据 | 报价 `masterdata/quote/`、汇率 `masterdata/exchange/`；车辆入口 `masterdata/vehicle/adapter/in/web/PlatformVehicleController.java`，应用服务 `application/VehicleApplicationService.java`，持久化端口与适配器 `application/port/out/VehicleRepository.java`、`adapter/out/persistence/`；OpenAPI `src/main/resources/openapi/overseas-master-data-v1.yaml`，车辆档案不含派送履约历史 |

lastleg-service/docs/overseas-fees-storage-rent-release.md

@@ -4,24 +4,30 @@
 
 ## 首版规则
 
+仓租项目 `FEE_TYPE_077` 同时支持手动添加。尾程订单与公共费用编辑窗口均展示有效仓租项目；人工仓租沿普通人工费用的审核、结算方式及资金身份处理，可在审核前调整。自动仓租仍以 `createdBy=STORAGE_RENT` 和仓租项目共同识别，继续走出库计租、预占及仓租审核流程；同单同项目补收沿用已有费用提示和原因必填规则。
+
 费用入口为 Admin「海外业务 → 海外费用管理」，仅保留「费用明细」与「仓租库存」两个页签。仓租库存查看相关单据、入库批次、库龄、剩余数量及出库数量记录，不展示金额和审核、调价入口。仓租金额及入库/出库时间、出库批次、计算金额、应扣及实扣金额在费用明细详情查询，多入库批次分别展示实际入库时间。审核与调价统一在对应尾程单据详情的「费用明细」办理，审核前调价必须填写说明。复用 Firstleg 公共费用项目，仓租项目为 `FEE_TYPE_077 / 仓储费`；不建立第二套海外费用目录。人工费用选择真实客户、当前服务业务单、项目、金额与币种后创建，详情保留必要的审核和资金状态。
 
+海外自动仓租的详情、审核和调价共用计算过程展示：来源批次、入库与出库时间、计费规则、实际托数或出库CBM、原库龄、此前已计费天数、各档实际计费日区间、天数×计租基数×快照单价及原币小计，并显示原币金额×保存汇率的人民币换算。新费用把基数与阶梯结果固化在原预占快照中；历史费用只按原报价快照和完整原批次基数解释，旧比例费用明确标识原口径，缺少依据不按最新报价猜算。各档金额保留原始计算精度，费用总额按分四舍五入。
+
 头程附加费审核后推送 Finance 账单。其余海外人工应收创建时冻结余额及可用授信，审核通过后扣款，Finance 成功扣款回执后登记本地已收费用，直接显示已完成，不再推送财务账单；驳回、取消释放冻结。在途回执、失败重试与同键重放不能重复扣款。车辆或同车运输不能代替每笔费用对应的客户和业务订单。
 
 现有尾程订单没有权威的“原报价已含派送费”字段。首版新增头程派送费仍由审核人员核对原报价，已包含则驳回该费用；系统尚不支持自动判断报价包含关系，审核提示不能替代人工核对。
 
-头程货最终目的地为自有海外仓、仓储转运（含外来货）以及退货建立计租批次。仓租全部使用余额及可用授信。实际 PDA 入库开始、实际 PDA 出库停止本次出库份额计租，每24小时计一天，不足24小时按一天。余货保持原入库时刻，不重置免费期；移库、换标和拆合托不新增免费期。
+头程货最终目的地为自有海外仓、仓储转运（含外来货）以及退货建立计租批次。仓租全部使用余额及可用授信。实际 PDA 入库开始，每24小时计一天，不足24小时按一天。中转按实际出库份额停止计租；退货按原托整托收费，原托剩余一箱仍计一托，直到清空才停止计租。余货保持原入库时刻，不重置免费期；移库、换标和拆合托不新增免费期。
 
 头程同单同仓多次实际入库合并为一个计租批次，统一从首次实际入库起算；补入库只追加箱数和计费体积，不重置库龄、免费期或已出库记录。单位体积沿用首次入库比例，后续修改订单体积不改写既有计租比例。其他业务保留各批实际入库时间分别计龄。头程未逐箱清点时，部分出库按来源单据箱数比例估算体积，审核前可调整金额并填写原因。本次不合并历史已存在的计租批次。
 
 | 规则 | 计费阶梯（USD） | 数量口径 |
 |---|---|---|
 | 中转仓租 | 第1–7天免费；8–30天0.8；31–60天1；61–90天1.5；91天起2 | CBM/天，按阶梯累加 |
-| 退货仓租 | 第1–30天1.5；31–60天2；61–90天3；91天起4 | 原始托数向上取整，按本次出库占原托比例分摊 |
+| 退货仓租 | 第1–30天1.5；31–60天2；61–90天3；91天起4 | USD/原托/天，不足一托按一托；部分出库不按件分摊，同托同计租日仅收一次 |
 
 自动计租优先读取现有客户仓租配置；无客户配置时使用上述两张报价表。USD 配置缺少整组中转或退货阶梯时，缺失组补用对应默认报价；非 USD 配置不得直接补用美元价格。已配置阶梯须从第1天连续覆盖至无限期，有限尾阶梯、缺段、负价或不支持的币种均阻断计价，不将配置错误或服务异常当作默认报价。
 
-每次出库资金预校验保存客户、配置编号及版本、币种、完整阶梯和计算结果快照。有效预占和实际扣款使用原快照；修改配置不重算已冻结或已生成的费用。后续新预占按最新客户配置计算本次出库份额的全部库龄，仍保留最初入库时间；本版不把一次出库按历次调价日期再拆段计费。过期或货物、计租天数等依据变化时须重新预校验。
+每次出库资金预校验保存客户、配置编号及版本、币种、完整阶梯和计算结果快照。有效预占和实际扣款使用原快照；修改配置不重算已冻结或已生成的费用。中转新预占按最新客户配置计算本次出库份额的全部库龄；退货新预占只计算原托尚未生成仓租的期间。两者都保留最初入库时间，按原库龄匹配阶梯，不按历次调价日期再拆段计费。过期或货物、计租天数、退货原托已计费截止日变化时须重新预校验并释放旧冻结。
+
+退货原托的 `charged_days` 在实际出库与待审核费用生成的同一事务内推进，预占、取消、资金回执不推进。待审核费用已覆盖的期间不重复生成；审核减免或驳回属于该期间的人工处理，不因后续出库再次收取。一个扫码含同原托多个箱或 SKU 时先按原托去重；多原托分别收费。商品份额仅追踪库存数量与来源。并发扫码发现其他出库已推进截止日时阻断旧预占，重新预校验后只冻结未覆盖期间的金额。
 
 原币金额与人民币结算额分别保留，冻结时固定汇率快照。无有效汇率时不得将美元直接作为人民币扣款。免费期零仓租保留出库记录，不要求汇率、不冻结资金。仓租自动计算，出库仅登记待审核费用并保留冻结；批准后沿原资金身份按实额扣款，驳回释放原冻结。订单费用和海外费用管理均展示原批次实际入库、实际出库、原计算金额、应扣金额及实扣金额。审核前允许原币金额调整且说明必填，保存版本；调低释放多余占用，调高由Finance结算时原子检查差额，余额不足保留原冻结，不登记实扣。原零元改非零先补冻结，成功后才能审核。其余客户收费人工录入并审核。历史已扣费用保留结果，不补审、不重复扣款。
 
@@ -30,12 +36,13 @@
 ## 计租验收样例
 
 1. 中转批次10箱共2CBM，第10天出4箱：3个收费日 × 0.8CBM × 0.8 = **1.92 USD**；余6箱第31天出库：(23×0.8+1×1) × 1.2CBM = **23.28 USD**。余货仍从最初入库计龄。
-2. 退货原批次不足一托，100件按1托，第10天出40件：10×1.5×40%=**6 USD**；第40天出余60件：(30×1.5+10×2)×60%=**39 USD**。第二次出库不再次将剩余货物进位到1托。
+2. 退货原批次不足一托，100件按1托，第10天出40件：10×1.5=**15 USD**；同一计租日再出部分货不重复收费；剩余一箱仍为一托，第40天清空时补收第11–40天：20×1.5+10×2=**50 USD**，整托40天合计**65 USD**。第61天或第91天仍有货时，新增日分别按3或4 USD/托计费。
 3. 入库后恰好24小时为1天，24小时加1毫秒为2天；恰好7天仍免费，7天加1毫秒进入第8天。对金额先按份额精算，完整收费命令汇总后按结算精度取整。
 
 ## 发布配套
 
 - 后端：Firstleg 公共目录内部接口、Warehouse 客户仓租内部报价接口、Lastleg 费用/仓租及真实收发货挂钩。Finance 继续作为余额、授信、冻结和实扣的唯一权威；不得绕过 Outbox/Inbox 链路。
+- 退货整托口径更新：先对已有 Lastleg 库执行 `deploy/sql/return-storage-rent-whole-pallet.sql` 补充 `charged_days`，再配套发布 Lastleg。新库两份基线已同步。切换时暂停相关出库并取消未消费预占；既有比例计费记录需逐单确认处理方式，脚本不回填计费截止日、不追收或修改既有费用和资金。当前仅准备源码和脚本，未据此认定 TEST 已生效。
 - 前端：Admin 海外费用管理与海外 PDA 出库预校验同时发布，不能只更新一端。
 - 数据库文件：本次五份版本脚本及两份专项汇总 SQL 已收敛到 [国内统一空库基线](../../deploy/sql/头程数据库统一增量-MySQL8.sql) 和 [海外统一空库基线](../../deploy/sql/海外区域统一增量-MySQL8.sql)。海外基线完整包含资金与仓租四表、拆柜成本可空费用引用、退货 SKU 换标仓租份额快照、审核人名称及采购退款请求幂等字段和唯一索引，国内基线包含菜单和默认管理员授权。内容清单见 [数据库变更汇总](../../deploy/sql/20261022-海外费用仓租数据库变更汇总.md)。
 - 已有库：不能重放统一空库初始化；须按实际结构和明确授权审阅增量。指定 TEST 先使用[表与审核人字段补齐](../../deploy/sql/overseas-fees-storage-rent-structure-add.sql)，再使用[免费仓租定向结构修复](../../deploy/sql/overseas-storage-rent-zero-fee-repair.sql)；精确范围与失败语义只维护在[数据库变更汇总](../../deploy/sql/20261022-海外费用仓租数据库变更汇总.md)。独立的 [既有费用写权限修复](../../deploy/sql/overseas-fee-canonical-write-permissions-repair.sql) 仍只处理已有管理员两项 canonical 写权限，不能代替结构升级或菜单初始化。
@@ -70,7 +77,7 @@
 | 人工海外收费 | 创建只冻结；审核后恰好扣一次；驳回/取消释放；不足余额但授信足够可成功，二者合计不足明确失败 |
 | 头程附加费 | 审核前不入账单，批准后回到正确头程来源且不扣钱包；人工核对原报价，已含派送费的新增收费须驳回 |
 | 仓租原生入库 | 头程自有仓、外来转运和退货实际扫码均生成正确原批次；非计租范围不误收 |
-| 部分及分批出库 | 原托比例、阶梯、库龄和余量符合上例；整托/多箱/混SKU全部来源核对后才能扣库存 |
+| 部分及分批出库 | 中转保持来源比例；退货余一箱仍按整托，新期间按原库龄阶梯，同托同日不重复收费；整托/多箱/混SKU全部来源核对后才能扣库存 |
 | 客户价格与默认报价 | 客户专价优先；无配置按两张默认报价；接口超时或无效阶梯不允许默认为免费或默认报价 |
 | 调价与币种 | 有效预占及已生成费用不受调价影响，新预占使用新版本；USD、CNY 原币及分币种汇总准确，不将混合币种直接相加 |
 | 资金门禁 | 未冻结成功、资金不足、过期、未知网络结果均不放行库存写；成功后仅本次实际出库份额扣款 |