# 初始化数据变更与迁移铁律

> 来源：框架内置（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 的三类文件