# 2026-10-16 拉取合并数据库变更汇总

范围：IDEA 更新前暂存基点 `cda5f3dc3` 到远程 `test` 的 `4e2ea8940`，加上本次恢复的本地改动。不是任意历史版本的一键全量升级脚本。没有连接或执行实际数据库。

## 数据库对应关系

| 服务 | 数据库 | 本次处理 |
|---|---|---|
| lastleg-service | `baiyue_lastleg` | 执行下列 V28 增量，新增表、字段、索引并放宽四个字段的可空性 |
| warehouse-overseas-service | `baiyue_lastlag_warehouse` | 仅业务代码变化，无新增表或字段，无需 SQL；数据库名称保留正式的 lastlag 拼写 |
| 其他服务 | 各服务原数据库 | 本次比较范围内无 SQL 结构新增，无需 SQL |

已有尾程库使用：[V28 可重复执行 SQL](migrations/overseas/baiyue_lastleg/V28__merge_transfer_measurement_and_compact_numbers.sql)。由单 schema 执行器选定 `baiyue_lastleg`，文件内不切库，不访问其他服务数据库。2026-10-20 按尚未执行候选的边界移除内部切库语句，其余结构内容不变；本次未执行此候选。

## 新表与字段

| 表 | 字段 | 定义/用途 |
|---|---|---|
| `ll_compact_number_clock`（新表） | `number_key` | VARCHAR(16)，主键，业务前缀及客户名称缩写 |
| 同上 | `last_second` | BIGINT NOT NULL，短单号分配逻辑秒，防止同秒及多实例重号 |
| `ll_warehouse_transfer_item` | `declared_quantity` | BIGINT NULL，SKU 申报件数，独立于箱数 |
| `ll_warehouse_transfer_carton` | `length_cm`、`width_cm`、`height_cm`、`gross_weight_kg` | DECIMAL(12,2) NULL，逐箱实测尺寸、重量 |
| 同上 | `counted_quantity` | BIGINT NULL，实点 SKU 件数 |
| 同上 | `count_idempotency_key` | VARCHAR(255) NULL，清点幂等键 |
| 同上 | `count_request_hash` | VARCHAR(64) NULL，清点请求摘要 |
| 同上 | `counted_by` | VARCHAR(128) NULL，清点操作人 |
| 同上 | `counted_at` | DATETIME(3) NULL，清点时间 |
| 同上 | `discrepancy_reason` | VARCHAR(1000) NULL，实收差异原因 |
| 同上 | `transfer_pallet_id` | BIGINT NULL，所属转运托盘事实 ID |
| 同上 | `sku_items_json` | JSON NULL，一箱多 SKU 清点明细 |
| 同上 | `customer_carton_mark` | VARCHAR(255) NULL，客户原箱唛及现场换标绑定 |

合计：1 张新表（2 列）、既有表补齐 14 列。逐箱清点等字段在旧版独立增量中已有，本次合并统一纳入 V28，避免漏执行；已存在的列会跳过。

## 索引及既有字段调整

| 表 | 调整 |
|---|---|
| `ll_cargo_discard_item` | 缺失时增加普通索引 `idx_ll_cargo_discard_return_carton(customer_id,return_carton_id)` |
| `ll_warehouse_transfer_order` | `estimated_arrival_at` 改为 DATETIME(3) NULL，库存转运无需填写预计入仓时间 |
| `ll_delivery_order` | `total_volume_cbm` 改为 DECIMAL(18,4) NULL，未知体积保持空值 |
| `ll_outbound_order`、`ll_outbound_pallet_item` | `volume_cbm` 改为 DECIMAL(18,4) NULL，未知体积保持空值 |

远程同时完善了 `ll_relabel_application.delivery_method` 的业务说明及照片、预约表的中文注释，没有新增对应字段，不需要因此另建表。照片回显和箱子订单归属校验复用已有结构。

## 执行与重跑

1. 确认连接为需要升级的 MySQL 8 实例，已有 `baiyue_lastleg` 及之前版本的业务表。通过数据库客户端打开并完整执行 V28，失败时停止，不启用忽略错误继续执行。
2. 新表采用 `CREATE TABLE IF NOT EXISTS`；每个新增字段和索引单独检查 `information_schema`，部分完成后可重跑。四个可空字段仅在当前为 NOT NULL 时调整。不会回填、删除或重算历史业务数据。
3. DDL 在 MySQL 中会自动提交，不能整体事务回滚；脚本不会修复同名但定义不一致的已有列、索引或新表，执行前应核对这些对象的结构。脚本末尾提供字段结构查询。
4. 此前 V1–V27 和其他已发布增量仍按原版本顺序管理，V28 不替代它们；缺失整个业务表的旧库应先完成对应历史升级。

空库使用原有海外统一初始化入口，已同步最终建表结构与 209 张表计数。名称含“增量”的海外统一文件仍仅用于空库，不应向已有业务库执行。

## 本地合并记录

远程分支已拉取，当前本地 HEAD 与 `origin/test` 一致。本次异常来自 IDEA 恢复更新前暂存补丁不完整；48 个文件按当前文件、原始基点、暂存内容做三方合并。唯一文本冲突保留远程 `bindingGuard` 与本地 `compactNumbers` 两项测试依赖初始化。

恢复前文件及三方版本保存在 `D:/project/.codex-temp/pull-resolution-20261016`；IDEA 原 shelf 保留。没有自动提交或推送代码。

本地验证：相关业务 Maven 定向测试通过；初始化基线、入库费用/扣货及网关路由合同共 27 项通过；Git 无未解决索引、无残留冲突标记，差异格式检查通过。SQL 仅完成离线核对，未进行 MySQL 实库执行或二次重跑验证。

指引索引检查 `scripts/agents-index-contract.ps1` 因工作区缺少 `D:/project/docs/业务快速索引.md` 而中止，此项未通过；未为消除检查错误而创建替代业务文档。