120 lines
14 KiB
Markdown
120 lines
14 KiB
Markdown
# 单测试环境数据库空库初始化
|
||
|
||
## 唯一入口与区域边界
|
||
|
||
两个统一 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` | 153 |
|
||
|
||
- 所有服务位于同一测试环境；两份文件只分组组织服务 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`，服务启动不执行这些文件。
|
||
|
||
## 执行前提与失败边界
|
||
|
||
1. 获得目标环境、精确数据库范围的当轮授权。初始化授权不等于清库授权；两个 SQL 本身不删除数据库、表或业务数据。
|
||
2. MySQL 8.0+，目标区域 schema 必须不存在或为空。已有同名表时报错，不使用 `CREATE TABLE IF NOT EXISTS` 绕过旧结构。
|
||
3. 执行用户需要目标区域建库、建表、索引、引用、触发器及种子插入权限，不需要另一地区的访问权。
|
||
4. 客户端须支持 `DELIMITER`。完整执行文件，关闭“遇错继续”，禁止 `mysql --force`。不要选中片段执行，不要前后串行执行模块 SQL。
|
||
5. DDL 隐式提交，不可整体回滚。失败后停止并保留错误；经另行授权准备空库后从头执行，不针对半初始化库追加迁移或从失败行续跑。
|
||
6. Firstleg 测量项与拆分项互为外键：建空表期间暂设会话 `foreign_key_checks=0`，随后立即恢复 `1`，再插入种子。失败时关闭连接。两边外键完整保留在 CREATE TABLE 内。
|
||
|
||
成功时只在最末输出一行 `initialization_status=PASS`，并带 `region=CN/OVERSEAS`、`initialized_tables=226/153`。必须同时确认客户端退出码 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 个系统角色及企业管理员模板、392 个权限、573 条角色权限、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` | 收敛一件代发托盘码非空定义；补齐墨家测量和人工报价字段、报关行回执/申报事实、船期日历事实表；V2 保留未上报重量为 NULL，放宽已有非空重量列，不回填或删除收件记录 |
|
||
| 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` | 补齐尾程字段并收敛字段定义；放宽退货出库和预入仓批量 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`，生产执行必须单独授权并确认无外部依赖 |
|
||
|
||
上述迁移候选只完成编写和离线检查，尚未在测试或生产执行。`db-migrations.mjs plan --services iam,firstleg,lastleg-service,warehouse-overseas-service --regions CN,OVERSEAS` 生成的 manifest 目标版本应为 `baiyue_iam=3`、`baiyue_firstleg=4`、`baiyue_lastleg=5`、`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` 仅用于保留空目录，不是迁移文件。
|
||
|
||
完整操作请先读 [数据库迁移操作手册](数据库迁移操作手册.md)。离线入口为 `scripts/db-migrations.mjs`：
|
||
|
||
编号统一采用每个 schema 独立递增的 `V1、V2、V3……`，有 SQL 变更才由工具新增，成功执行后不改内容和编号。功能分支从最新 `main` 创建，进入测试前同步 main 并解决草稿编号冲突。生产发布另记 `release-1、release-2……`；该发布编号及分支门禁尚待流水线实现，完整流程见操作手册“编号与功能分支规则”。
|
||
|
||
```powershell
|
||
# 自动取得该 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 编辑接口仍要求正数重量，向领星推送也需要完整测量值。
|
||
|
||
## 本地验证
|
||
|
||
离线合同不连接数据库：
|
||
|
||
```powershell
|
||
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 车队邮件](../../firstleg/docs/terminal-drayage-mail.md)。
|