101 lines
9.4 KiB
Markdown
101 lines
9.4 KiB
Markdown
# 区域数据库空库初始化
|
||
|
||
## 唯一入口与区域边界
|
||
|
||
两个统一 SQL 文件仍只用于空库初始化，名称中的“增量”不表示可向已有业务库重放。已有生产库的受控结构补齐单独放在 `migrations/`，只允许明确审阅过的增量变更；不提供存量数据回填、清理或兼容入口。
|
||
|
||
| 区域 | 完整入口 | 服务 schema | 表数 |
|
||
|---|---|---|---:|
|
||
| 国内 | `头程数据库统一增量-MySQL8.sql` | `baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_event_bridge`、`baiyue_finance` | 208 |
|
||
| 海外 | `海外区域统一增量-MySQL8.sql` | `baiyue_lastleg`、`baiyue_lastlag_warehouse`、`baiyue_event_bridge_overseas` | 138 |
|
||
|
||
- 国内和海外是两个部署区域，不是把微服务合并为两个 schema。`baiyue_lastlag_warehouse` 保留当前正式的 `lastlag` 拼写。
|
||
- 两区域可分别在独立空实例执行，没有跨区域 SQL 依赖。海外不访问国内 IAM/Warehouse；国内不创建、查询或修改海外业务表。
|
||
- 国内 IAM 是全部平台与客户权限的唯一权威，包括海外仓、海外业务、海外主数据及财务权限；这些权限保留在国内种子中。
|
||
- 国内 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=208/138`。必须同时确认客户端退出码 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 个系统角色及企业管理员模板、364 个权限、539 条角色权限、7 个数据范围、客户编号起点 | 测试客户、固定客户账号、额外扩权 |
|
||
| Warehouse | 既有公共仓目录 318 条及地址；义乌、东莞、洛杉矶、纽约 4 个作业仓收货能力 | 示例供应商、快递、往来单位、托盘、库位、预占、库存 |
|
||
| Firstleg | 112 个费用项目、15 个渠道目录、7 个始发地别名、4 个公共仓映射 | 客户报价、订单、入库、实测或履约记录 |
|
||
| File / Finance | 导出互斥键 `GLOBAL_CREATE`、默认平台财务主体 | 文件任务、资金、账单或交易流水 |
|
||
| Lastleg | 国内固定管理员对应的 USER/AUTHORIZATION version=0 安全投影，当前角色及完整 106 项海外权限 | 客户、订单、库存、发运门禁事实或新账号 |
|
||
|
||
海外管理员投影只是国内已定义身份的初始化快照，不是独立账号或权限中心。后续变更仍由 IAM 事件同步，不提供历史投影回填。
|
||
|
||
扣货写权限只默认授予平台管理员，与 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 仍是空库初始化入口；本节工具不会把当前可丢弃的开发/测试存量转换成迁移链。当前已登记一份生产尾程结构补齐迁移 `migrations/overseas/baiyue_lastleg/V1__align_lastleg_production_schema.sql`，由 `scripts/prod-database-schema-acceptance.mjs` 默认只读核对，只有显式确认参数才执行；它只新增字段、放宽生成后才确定字段的可空性并创建缺失表，不执行 DML。
|
||
|
||
迁移范围映射位于 `migration-scopes.json`，按区域、schema、所属服务和顺序登记。迁移文件位于 `migrations/{cn|overseas}/<schema>/`，一个文件只允许修改一个 schema。目录中的 `.gitkeep` 仅用于保留空目录，不是迁移文件。
|
||
|
||
完整操作请先读 [数据库迁移操作手册](数据库迁移操作手册.md)。离线入口为 `scripts/db-migrations.mjs`：
|
||
|
||
```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；生产增量由专用验收脚本在当前轮明确授权后执行，不把统一初始化文件用于生产。
|
||
|
||
## 本地验证
|
||
|
||
离线合同不连接数据库：
|
||
|
||
```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)。
|