e54c772868
对齐迁移是菜单快照进入数据库的唯一途径（新装与存量库同路径）；缺失行按显式 id 补插，框架结构行仅对齐 pid+sort，软删/用户分组跳过；新增规则文件与索引；清理 status 模块孤儿占位文件。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
3.9 KiB
初始化数据变更与迁移铁律
来源：框架内置（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，导致存量库永久缺菜单。这就是「快照变更必须配套迁移」铁律的由来。
铁律
- 已发布迁移永不编辑：
database/migrations/下已发布（进过提交/已在库中执行）的迁移文件永不编辑，任何变更只能新增迁移。 - 数据迁移必须幂等：不得依赖「恰好执行一次」。存在性检查 + 原生查询兜底：auth/quick/admin 等含
delete_time的表，判存必须用Db::name原生查询（或withTrashed）绕过软删除作用域——否则软删行被误判「缺失」导致重放时主键冲突或数据复活。参照MenuAlignServiceBase已验证模式。 - 对齐只增不删：快照行删除或 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
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 - app 层覆盖 extend/base 的三类文件