单测试环境数据库空库初始化

migrations/overseas/baiyue_lastleg/V13__widen_inbound_plan_creation_mode.sql 仅将 ll_inbound_plan.creation_mode 从旧统一基线的 VARCHAR(16) 扩至模块基线已有的 VARCHAR(32)，容纳实际来货审核写入的 WAREHOUSE_TRANSFER（18字符）。保留 utf8mb4_unicode_ci、非空及 AUTO 默认值；不更新已有计划或状态。执行前核对目标库该列的长度、排序规则、可空性和默认值，已符合最终定义则核对后跳过；执行结果不确定时先只读复查，不盲目重试。统一空库基线同步最终定义，不重放模块历史初始化脚本。

migrations/overseas/baiyue_lastleg/V12__preserve_unknown_pool_order_fields.sql 仅放开散板打盘需求及两类本土订单柜型三列为空、默认空，供未提供这些事实的拼车商业订单使用；普通订单输入校验仍由原服务端请求合同执行。对应源及统一空库基线同步最终定义，不回填已生成订单或把托盘数量解释成打盘服务需求。

内部拼车需求池的当前结构在 Lastleg 源基线和海外统一空库基线同步维护，独立五项权限在 IAM 源种子和国内统一基线维护。已存在基础表的指定环境结构补齐使用 migrations/overseas/baiyue_lastleg/V10__fleet_capacity_pool.sql 与 migrations/cn/baiyue_iam/V4__fleet_capacity_offer_permissions.sql；执行前确认三张新表、六个新增字段均未存在，并单独核对目标环境。随后 V11__align_capacity_pool_collation.sql 将预订与商业桥的客户关联字段显式统一为 utf8mb4_unicode_ci，与原订单域一致，避免依赖MySQL实例默认排序规则导致JOIN失败。它们不回填、删除或重置业务数据，不能重放整个空库基线。候选文件存在不表示已经执行。

唯一入口与区域边界

两个统一 SQL 文件仍只用于空库初始化，名称中的“增量”不表示可向已有业务库重放。已有生产库的受控结构补齐单独放在 migrations/，只允许明确审阅过的增量变更；不提供存量数据回填、清理或兼容入口。

区域	完整入口	服务 schema	表数
国内	`头程数据库统一增量-MySQL8.sql`	`baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_finance`	226
海外	`海外区域统一增量-MySQL8.sql`	`baiyue_lastleg`、`baiyue_lastlag_warehouse`	159

所有服务位于同一测试环境；两份文件只分组组织服务 schema，不代表两个部署区域。baiyue_lastlag_warehouse 保留当前正式的 lastlag 拼写。
两份文件必须在同一测试数据库实例中完成初始化；业务服务仍只访问本服务 schema，经内部接口访问 IAM/Warehouse。已移除事件桥两个 schema 的创建，不对已有数据库执行 DROP。
国内 IAM 是全部平台与客户权限的唯一权威，包括海外仓、海外业务、海外主数据及财务权限；这些权限保留在国内种子中。
车辆成本、报价、出车实测及在途交接表对应Lastleg模块基线；公司车辆费用三表对应Finance模块基线。公司财务权限源为iam/src/main/resources/db/fleet-finance-permissions.sql，已合入国内统一种子，不以模块文件代替完整空库初始化。
外接预订的quote_source_json保存可选销售报价来源版本快照，实际成交价仍在货物快照及agreed_amount中；手填成交价时无报价来源。该字段随Lastleg模块基线与海外统一入口维护，执行状态只见正式部署契约。
异常退回的return_context_json保存取消时所需的原始业务状态；逐来源received_packages累计实际入仓量且不得超过批准退回量。同一派送可以保留多张已取消/已结束的历史退回单，活动退回仍由派送行锁内校验；普通idx_ll_exception_delivery_return替代跨全部历史的唯一索引。数量和状态不能通过回填旧单据伪造。
派送ll_delivery_order.signed_packages保存签收资料确认时冻结的实际签收箱数；NULL表示未确认，不当作全量签收，数量须在0到本次实发箱数之间。后续退回保留原签收历史，不用当前退回量倒改实签。
ll_return_stock_receipt与真实退回库存入账同事务保存，按客户/入账流水唯一，保留原订单和出库位置以及实际入仓位置。重派候选、草稿锁及拣货显式引用该凭据；拣货receipt_id与return_receipt_id恰有一个非空。退回不增加原订单箱数，不回退历史出库流水；可重新发运量由实际退回及已消耗凭据核平。
国内 Warehouse 管理包括海外仓在内的公共仓库主档；海外 Warehouse 只保存资源与主档 ID 引用。
Gateway、Print、Integration 不新增数据库。Compose 继续使用 SPRING_SQL_INIT_MODE=never，服务启动不执行这些文件。

执行前提与失败边界

获得目标环境、精确数据库范围的当轮授权。初始化授权不等于清库授权；两个 SQL 本身不删除数据库、表或业务数据。
MySQL 8.0+，目标区域 schema 必须不存在或为空。已有同名表时报错，不使用 CREATE TABLE IF NOT EXISTS 绕过旧结构。
执行用户需要目标区域建库、建表、索引、引用、触发器及种子插入权限，不需要另一地区的访问权。
客户端须支持 DELIMITER。完整执行文件，关闭“遇错继续”，禁止 mysql --force。不要选中片段执行，不要前后串行执行模块 SQL。
DDL 隐式提交，不可整体回滚。失败后停止并保留错误；经另行授权准备空库后从头执行，不针对半初始化库追加迁移或从失败行续跑。
Firstleg 测量项与拆分项互为外键：建空表期间暂设会话 foreign_key_checks=0，随后立即恢复 1，再插入种子。失败时关闭连接。两边外键完整保留在 CREATE TABLE 内。

成功时只在最末输出一行 initialization_status=PASS，并带 region=CN/OVERSEAS、initialized_tables=226/157。必须同时确认客户端退出码 0；忽略错误后出现的 PASS 不算成功。

平台管理员密码

国内只初始化一个 platform_admin 及对应 IAM 用户、成员和角色关系，不创建测试客户或客户账号。密码不在源码内置。

在同一连接中，先由安全外部配置设置会话变量 @platform_admin_password_hash，再执行国内文件。值须为实际初始密码生成的 bcrypt 哈希（60 字符）；不要传明文、示例哈希或把真实值存进仓库。password_change_required=1，初次登录必须改密。

变量缺失或格式错误会在 Auth 账号插入时被非空约束拒绝；Auth 表可能已创建，属于失败的半初始化，应停止。海外文件不需要密码变量。

本地验收入口读取当前进程环境变量 INIT_PLATFORM_ADMIN_PASSWORD_HASH，经标准输入传入同一 MySQL 会话，不写入命令行、暂存 SQL 或日志。数据库连接认证独立由外部登录配置或 MYSQL_PWD 提供，不要与平台账号密码混淆。

审核保留的系统种子

所属库	保留内容	不包含
Auth / IAM	平台主体、唯一平台管理员、8 个系统角色及企业管理员模板、417 个权限、598 条角色权限、7 个数据范围、客户编号起点；无人工完成订单权限	测试客户、固定客户账号、额外扩权
Warehouse	既有公共仓目录 318 条及地址；义乌、东莞、洛杉矶、纽约 4 个作业仓收货能力	示例供应商、快递、往来单位、托盘、库位、预占、库存
Firstleg	112 个费用项目、15 个渠道目录、7 个始发地别名、4 个公共仓映射	客户报价、订单、入库、实测或履约记录
File / Finance	导出互斥键 `GLOBAL_CREATE`、默认平台财务主体	文件任务、资金、账单或交易流水
Lastleg	无身份或授权种子；复用统一Auth/IAM会话	客户、订单、库存、发运门禁事实或独立账号

IAM保留subject/tenant持久版本表；安全事件专用Outbox及Lastleg授权投影表已退出新空库基线。旧库不在本次脚本中执行删除或历史回填。

扣货写权限只默认授予平台管理员，与 IAM 扣货权限合同一致；旧脚本重放时通过范围授权额外授予订单运营的那一条关联不进入新基线。

示例 TP-001、TP-002、YW-TP-002、DG-TP-002、A1/A0 库位、EXP-TEST、CAR-001 不再初始化。验收资源通过业务入口配置；既有只复用托盘和库位的造数脚本须先满足各自前置条件，不能默认清库后已存在。

维护规则

空库基线的最终字段、类型、默认值、索引、外键、CHECK、注释直接维护在 CREATE TABLE；64 个国内业务触发器保留最终定义。统一初始化文件不追加 ALTER、迁移过程、动态 DDL、UPDATE 回填或 DELETE 清理段；已有库的受控增量只能放入对应 schema 的 migrations/ 文件，并保持不删数据。
系统种子直接维护最终 INSERT，不保留退役 ID 清理或 ON DUPLICATE KEY UPDATE 升级。权限变更联查 IAM 来源、Controller、OpenAPI 与调用端。
原 权限点初始化-MySQL8.sql 独立补丁已撤销，订单申报权限和默认授权已纳入国内 IAM 基线，不另设存量权限发布入口。
模块 src/main/resources/db/ 用作结构来源和开发追溯，不是区域部署前置；不再向历史迁移文件追加发布步骤。修改当前字段时同步模块有效建表定义及其合同。
不在 SQL 中写入真实客户数据、环境地址、固定密码或 Token。

后续迁移工具（已开始实施）

机制启用前，以上两份统一 SQL 仍是空库初始化入口；本节工具不会把当前可丢弃的开发/测试存量自动转换成迁移链。现有候选迁移包括：

区域 / schema	迁移	目的
CN / `baiyue_iam`	`migrations/cn/baiyue_iam/V1__align_schema_baseline.sql`、`V2__add_pda_release_permissions.sql`、`V3__align_domestic_pda_mojia_sailing_permissions.sql`	收敛客户编号、昵称和资质原文件名定义；补齐 PDA 发布、国内作业仓绑定、墨家 SKU 同步、仓管 PDA 和船期日历权限
CN / `baiyue_firstleg`	`migrations/cn/baiyue_firstleg/V1__align_schema_baseline.sql`、`V2__align_measurement_and_fee_schema.sql`、`V3__add_customs_receipt_declaration_schema.sql`、`V4__add_sailing_calendar_schema.sql`、`V5__event_delivery_retry_audit.sql`、`V6__event_delivery_attempt.sql`、`V7__settle_partial_loaded_cargo.sql`	收敛一件代发托盘码非空定义；补齐测量/报价、报关、船期和事件重试审计；V7 仅更新装柜明细保护触发器，允许普通箱件按冻结分配和实际拣货精确收敛件数、重量、体积和托数，保留身份及已完成冻结保护，不回填原事件或库存
CN / `baiyue_file`	`migrations/cn/baiyue_file/V1__align_schema_baseline.sql`、`V2__widen_business_type.sql`	补齐 PDA 发布表和固定渠道，并支持正式长业务类型
OVERSEAS / `baiyue_lastleg`	`migrations/overseas/baiyue_lastleg/V1__align_lastleg_production_schema.sql`、`V2__align_schema_baseline.sql`、`V3__relax_valid_nullable_fields.sql`、`V4__cargo_discard_return_inventory.sql`、`V5__allow_multiple_relabel_applications.sql`、`V6__event_delivery_retry_audit.sql`、`V7__event_delivery_attempt.sql`、`V8__bind_stock_transfer_relabel_sources.sql`	补齐尾程字段、退货/换标/废弃结构与事件投递审计；V8 保存已有库存转运的实际 SKU、原分配和换标明细关联，允许同位置历史与当前分配共存，保留活动占用唯一约束，不回填旧业务或库存
OVERSEAS / `baiyue_lastlag_warehouse`	`migrations/overseas/baiyue_lastlag_warehouse/V1__add_shared_overflow_location.sql`、`V2__retire_location_zone_and_rebuild_query_index.sql`	补齐共享溢出库位并移除退役 `zone_code`；V2 含 `DROP COLUMN`，生产执行必须单独授权并确认无外部依赖

候选编写和离线检查不证明环境已执行；测试环境执行事实只维护在 ../../../docs/测试环境单机部署与配置契约.md，生产执行须另有明确授权。db-migrations.mjs plan --services iam,firstleg,lastleg-service,warehouse-overseas-service --regions CN,OVERSEAS 生成的 manifest 目标版本应为 baiyue_iam=3、baiyue_firstleg=7、baiyue_lastleg=8、baiyue_lastlag_warehouse=2。测试通过后必须复用同一份 SQL 和 manifest 晋级生产，不得重新生成或修改候选。scripts/prod-database-schema-acceptance.mjs 仍只负责历史尾程 V1 的专用只读核对/受控执行，不代表本批跨 schema 发布入口；本批按迁移 manifest 管理，实际执行须等待环境执行器接入或当前轮明确授权后的受控人工执行。

迁移范围映射位于 migration-scopes.json，按区域、schema、所属服务和顺序登记。迁移文件位于 migrations/{cn|overseas}/<schema>/，一个文件只允许修改一个 schema。目录中的 .gitkeep 仅用于保留空目录，不是迁移文件。

完整操作请先读数据库迁移操作手册。离线入口为 scripts/db-migrations.mjs：

编号统一采用每个 schema 独立递增的 V1、V2、V3……，有 SQL 变更才由工具新增，成功执行后不改内容和编号。功能分支从最新 main 创建，进入测试前同步 main 并解决草稿编号冲突。生产发布另记 release-1、release-2……；该发布编号及分支门禁尚待流水线实现，完整流程见操作手册“编号与功能分支规则”。

# 自动取得该 schema 的下一个整数序号并创建草稿；不连接数据库
node deploy/sql/scripts/db-migrations.mjs new --region CN --schema baiyue_auth --description add_login_audit

# 校验范围、文件名、跨 schema 引用及受保护文件；不连接数据库
node deploy/sql/scripts/db-migrations.mjs check

# 由选中服务自动生成逐库目标和 SQL 哈希；不手填发布 JSON
node deploy/sql/scripts/db-migrations.mjs plan --services auth,iam --regions CN --out release-manifest.json

# 当前只提供安全的只读计划；实际 Flyway 执行需后续阶段显式配置并授权
node deploy/sql/scripts/db-migrations.mjs run --manifest release-manifest.json --dry-run

new 使用独占创建避免并发覆盖；成功历史或已冻结制品不能由普通命令改写。plan 只打包选中服务及评审确认的 schema，不会因为同一提交存在其他区域或服务 SQL 就自动扩大范围。run 的真实 Flyway 执行仍未接入测试数据库和 Jenkins；生产增量由专用验收脚本在当前轮明确授权后执行，不把统一初始化文件用于生产。

墨家原始收件表允许未收到的 weight_kg 为空，不把未知重量补成 0。数据库可空仅用于如实保存收件数据，不代表 SKU 同步已支持无重量；当前上传及 SKU 编辑接口仍要求正数重量，向领星推送也需要完整测量值。

本地验证

离线合同不连接数据库：

node --test scripts/admin-test-env-modules/initialization-baseline-contract.test.mjs scripts/inbound-fee-unified-sql-contract.test.mjs scripts/inbound-hold-unified-sql-contract.test.mjs
.\scripts\local-db-full-acceptance.ps1 -DryRun

获得精确本地库清理授权并配置认证、管理员哈希后，可用 local-db-full-acceptance.ps1 -Port <已授权端口> -ConfirmResetProjectSchemas -Rounds 2。它删除列出的 12 个项目 schema，不得在有待保留数据的实例运行；详见 scripts/README.md。该入口不会自动启动隔离实例。

本次整理使用隔离 MySQL 8.4，国内与海外分别在不存在对方区域 schema 的空库执行两轮，逐表比对整理前最终字段、默认值、索引、约束、注释及业务触发器。SHOW CREATE 的冗余字符集显示与运行态自增计数不视为结构差异；移除示例种子和强制改密是明确行为变更。这不代表已部署或完成真实 HTTP 验收。

码头车队邮件配置见 Firstleg 车队邮件。

16 KiB Raw Blame History Unescape Escape