mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-11-08 20:10:50 +08:00
e54c772868
对齐迁移是菜单快照进入数据库的唯一途径（新装与存量库同路径）；缺失行按显式 id 补插，框架结构行仅对齐 pid+sort，软删/用户分组跳过；新增规则文件与索引；清理 status 模块孤儿占位文件。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
71 lines
3.9 KiB
Markdown
71 lines
3.9 KiB
Markdown
# 初始化数据变更与迁移铁律
|
||
|
||
> 来源：框架内置（ulthon-）
|
||
> 作用域：`extend/base/admin/service/adminInitData/` 下全部初始化快照（SystemMenu、SystemConfig、SystemAdmin 等）及其配套数据迁移
|
||
> 触发条件：新增/修改/重组任何初始化数据、快照或相关迁移时加载
|
||
|
||
## 背景：迁移是唯一安装命令
|
||
|
||
`php think migrate:run` 是唯一的安装命令，一条命令完成建表 + 全部初始数据（超管、角色、权限节点、配置、快捷入口、商城演示、菜单）。种子机制已退役：框架自身零种子，`seed:run` 成为空操作，仅保留给下游业务项目放自己的种子。
|
||
|
||
| 路径 | 机制 |
|
||
|------|------|
|
||
| 全新安装 | `migrate:run` 建表并写入全部初始数据（phinxlog 记账，幂等） |
|
||
| 存量库 | 数据型 migration 经 `migrate:run` 对齐（admin:update 检测到 migrations 变更会提示） |
|
||
|
||
历史教训：定时器/主机菜单（2026-05 c169646）、XHProf 菜单与运行管理重组（2026-08 8cbe62a）都曾只改快照不带 migration，导致存量库永久缺菜单。这就是「快照变更必须配套迁移」铁律的由来。
|
||
|
||
## 铁律
|
||
|
||
1. **已发布迁移永不编辑**：`database/migrations/` 下已发布（进过提交/已在库中执行）的迁移文件永不编辑，任何变更只能新增迁移。
|
||
2. **数据迁移必须幂等**：不得依赖「恰好执行一次」。存在性检查 + 原生查询兜底：auth/quick/admin 等含 `delete_time` 的表，判存必须用 `Db::name` 原生查询（或 `withTrashed`）绕过软删除作用域——否则软删行被误判「缺失」导致重放时主键冲突或数据复活。参照 `MenuAlignServiceBase` 已验证模式。
|
||
3. **对齐只增不删**：快照行删除或 id 复用属破坏性变更，必须显式编写删除迁移 + 人工确认。既定语义：快照文案/icon 变更与 config value 修改**不自动传播**到已装库，不视为缺陷。
|
||
|
||
## 快照数据源
|
||
|
||
`extend/base/admin/service/adminInitData/*.php` 是唯一初始数据源（9 个文件：SystemAdmin、SystemAuth、SystemAuthNode、SystemConfig、SystemQuick、SystemMenu、MallCate、MallGoods、MallTag）。
|
||
|
||
新增初始数据 = 新增快照 + 新增迁移（或纳入对齐服务），migration 不得硬编码快照数据副本，必须复用快照文件或调用对齐服务（如 `MenuAlignServiceBase`、`InitDataAlignServiceBase`），避免两份数据漂移。
|
||
|
||
## migration 模板
|
||
|
||
```php
|
||
<?php
|
||
|
||
use app\admin\service\MenuAlignService;
|
||
use think\console\Output;
|
||
use think\migration\Migrator;
|
||
|
||
/**
|
||
* 菜单快照对齐 - <本次变更说明>
|
||
*/
|
||
class SystemMenuAlign extends Migrator
|
||
{
|
||
public function up()
|
||
{
|
||
(new MenuAlignService(new Output()))->align('SystemMenu');
|
||
}
|
||
|
||
public function down()
|
||
{
|
||
// 数据对齐迁移不提供对称回滚，见规则 ulthon-init-data-migration.md
|
||
}
|
||
}
|
||
```
|
||
|
||
新增菜单时同步操作：`adminInitData/SystemMenu.php` 追加条目（显式 id 接续现有序列）+ 按模板新增迁移（时间戳接续）。其他类型快照需要类似对齐能力时，参照 `MenuAlignServiceBase` 扩展对应服务，不硬编码数据。
|
||
|
||
## 相关文件
|
||
|
||
- `extend/base/admin/service/adminInitData/` - 初始化数据快照目录（唯一数据源）
|
||
- `extend/base/admin/service/InitDataAlignServiceBase.php` - 六域初始数据对齐编排（超管/角色/配置/快捷入口/商城演示/菜单）
|
||
- `app/admin/service/InitDataAlignService.php` - app 层入口（可覆盖）
|
||
- `extend/base/admin/service/MenuAlignServiceBase.php` - 菜单对齐服务
|
||
- `app/admin/service/MenuAlignService.php` - app 层入口（可覆盖）
|
||
- `database/migrations/20260909120000_system_menu_align.php` - 菜单对齐迁移（范本）
|
||
- `database/migrations/20260909130000_system_init_data.php` - 全量初始数据迁移
|
||
|
||
## 相关规则
|
||
|
||
- [ulthon-file-override-mechanism.md](./ulthon-file-override-mechanism.md) - app 层覆盖 extend/base 的三类文件
|