优化

2026-10-26 17:27:32 +08:00
parent 5b53be23e8
commit 2927fbee06
22 changed files with 512 additions and 38 deletions
@@ -38,10 +38,27 @@
 - 后端：Firstleg 公共目录内部接口、Warehouse 客户仓租内部报价接口、Lastleg 费用/仓租及真实收发货挂钩。Finance 继续作为余额、授信、冻结和实扣的唯一权威；不得绕过 Outbox/Inbox 链路。
 - 前端：Admin 海外费用管理与海外 PDA 出库预校验同时发布，不能只更新一端。
 - 数据库文件：本次五份版本脚本及两份专项汇总 SQL 已收敛到 [国内统一空库基线](../../deploy/sql/头程数据库统一增量-MySQL8.sql) 和 [海外统一空库基线](../../deploy/sql/海外区域统一增量-MySQL8.sql)。海外基线完整包含资金与仓租四表、拆柜成本可空费用引用、退货 SKU 换标仓租份额快照、审核人名称及采购退款请求幂等字段和唯一索引，国内基线包含菜单和默认管理员授权。内容清单见 [数据库变更汇总](../../deploy/sql/20261022-海外费用仓租数据库变更汇总.md)。
- 已有库：不能重放统一空库初始化；须按实际结构和明确授权审阅增量。[免费仓租定向结构修复](../../deploy/sql/overseas-storage-rent-zero-fee-repair.sql) 仅解决自动仓租双零金额和空汇率入费用源表，保留人工正额与正常费用有效汇率约束，不更新业务数据。独立的 [既有费用写权限修复](../../deploy/sql/overseas-fee-canonical-write-permissions-repair.sql) 仍只处理已有管理员两项 canonical 写权限，不能代替结构升级或菜单初始化。
+- 已有库：不能重放统一空库初始化；须按实际结构和明确授权审阅增量。指定 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 写权限，不能代替结构升级或菜单初始化。
 - 新空库：Lastleg 源基线与海外统一初始化脚本同步新表和字段；国内统一基线同步菜单。菜单查询权限 `platform:overseas-fee:list`，编辑与审核分别沿用 `platform:finance:fee-source:edit/review`，仅有查询权限不能写费用。
 - 配置：核对 Firstleg、Warehouse 内部服务地址及内部令牌、客户仓租阶梯、有效 USD/CNY 月度汇率、Finance 资金与费用事件直投及回执配置。当前结算支持 USD、CNY，CNY 按1:1结算，其他币种必须先调整为受支持币种。不得在材料中记录密钥。
- 发布顺序：先发布 Warehouse 客户计租接口与 Finance，再发布 Lastleg，配套更新 Admin 与海外 PDA。成功扣款引用新增可选的 `walletBusinessType/walletBusinessNo`，分别指向人工费用冻结编号或仓租出库预占编号；外层业务编号仍是实际服务单。Finance 校验客户、金额、成功命令、冻结与流水一致且不可重复关联，接收后标记已结清。旧版 Finance 不识别这两个字段，不得先发生产者。
+- 发布顺序：先发布 Firstleg 公共费用目录、Warehouse 客户计租接口与 Finance，再发布 Lastleg，配套更新 Admin 与海外 PDA。成功扣款引用新增可选的 `walletBusinessType/walletBusinessNo`，分别指向人工费用冻结编号或仓租出库预占编号；外层业务编号仍是实际服务单。Finance 校验客户、金额、成功命令、冻结与流水一致且不可重复关联，接收后标记已结清。旧版 Finance 不识别这两个字段，不得先发生产者。
+
+### TEST 配套发布清单
+
+本清单用于准备和审阅，不表示环境已完成执行。实际版本、部署结果及未关闭验收项仍只维护于[测试环境主契约](../../../docs/测试环境单机部署与配置契约.md)。发布前冻结后端、Admin、海外 PDA 的精确提交和产物摘要；执行期间任一版本变化都需重新核对受影响项，不使用浮动分支头替代审阅版本。
+
+| 顺序 | 对象 | 执行前提与通过标准 |
+|---|---|---|
+| 1 | 规则与执行窗口 | 确认人工应收是否开放“推送结算/余额扣费”选择：当前前后端已支持显式选择，未选择才按业务默认规则；本文件首版固定分流描述不能作为该选择功能已获确认的依据。明确本批 TEST SQL、服务发布及测试客户写入授权，切换期间暂停相关收费与出库操作 |
+| 2 | Lastleg 结构 | 按数据库变更汇总审阅并执行两个定向文件，核对新增表/字段及免费仓租约束；不重新初始化已有资金、计租表，不重放已有权限种子，不改现行汇率 |
+| 3 | Firstleg、Warehouse、Finance | 用匹配后端提交分别发布，核对容器镜像与健康；Firstleg 具备 `/internal/firstleg/v1/fee-items`，Warehouse 具备客户计租 `/pricing`，Finance 接受应收结算方式及独立扣款引用；内部服务地址、统一服务令牌及事件回传配置匹配 |
+| 4 | Lastleg | 依赖就绪后发布费用/仓租编排及收发货挂钩；统一 Gateway 下费用分页、项目目录、仓租列表与仓库选项均返回业务成功，不能只检查 HTTP 200 |
+| 5 | Admin、海外 PDA | Admin 包含海外费用管理和单据费用操作；海外 PDA 包含 `/pda/v1/last-leg/storage-rent/preparations` 出库预校验。H5 按宿主机静态站点规则发布并核验资源摘要；APK/WGT 按实际设备另行核对，H5 通过不等于设备已更新 |
+| 6 | 最小业务验收 | 使用明确授权的新测试样本完成下表；逐笔核对业务单、费用、冻结/消费/退款流水及事件回执。查询成功、表为空或历史事件已投递不能替代新功能闭环 |
+
+第一轮最小样本按以下顺序执行：人工余额收费的登记冻结、审核实扣、原请求重放与驳回释放；账单收费审核入池且钱包不变；免费仓租记录无冻结/扣款；非零仓租出库预占、审核前调价及审核实扣；头程同单同仓补入库不重置库龄、重复实收不增加计租数量。供应商账期/直付与采购专用资金链继续按下表分别验收，不由人工收费样本推定通过。
+
+若结构、服务、页面或设备任一项不匹配，保持相关收费/出库操作暂停并记录失败，不通过补零、伪造回执或重建费用继续；DDL 不做自动回滚，服务回滚仅限明确核对过的同协议同 Schema 版本。页面布局由人工按 1920×1080、100% 缩放提供截图核对。

 ## 实际环境验收

@@ -65,7 +82,7 @@

 ## 验证记录

-本地验证结果在本次交付说明中列出；真实环境 SQL、部署、HTTP 联调与 PDA 设备验收尚未执行。上线前逐项填写环境、版本、执行时间与证据，未通过项不得标成通过。
+本地验证结果在本次交付说明中列出；真实环境 SQL、部署、HTTP 联调及 PDA 验收状态统一维护在[测试环境单机部署与配置契约](../../../docs/测试环境单机部署与配置契约.md)。该主契约逐项记录环境、版本、执行时间与证据，未通过项不得标成通过。

 2026-10-22 本地验证记录（使用最终受影响文件；复用已通过且输入未变的结果）：