 }}){kind=icon}
```
> **⚠️ 禁止使用 CDN 引用 UI 资源**：系统已内置 layui（`public/CmsProUi/component/layui/`）、pear（`public/CmsProUi/component/pear/`）、font-awesome（`public/CmsProUi/font-awesome/`）等 UI 框架，引用这些系统资源时**必须使用本地路径**。如需使用其他第三方库（如 echarts、qrcodejs、highlight.js 等），应下载到应用的 `Assets/` 目录中，通过 `public/apps/{appId}/` 访问。禁止在视图文件中直接引用 `cdn.jsdelivr.net`、`cdnjs.cloudflare.com`、`unpkg.com` 等 CDN 域名。
### Assets 静态资源发布机制
应用的 `Assets/` 目录用于存放需要通过 Web 公开访问的静态资源（CSS、JS、字体、图片等）。系统在安装、升级、卸载时会自动管理 `Assets/` 目录与 `public/apps/{appId}/` 之间的映射关系，**应用无需自行处理资源复制**。
#### 自动发布流程
系统 `AppInstallerService` 在应用生命周期中自动处理资源发布：
| 操作 | 调用方法 | 行为 |
| ---- | -------- | ---- |
| 安装 | `createAssetSymlink()` | 将 `Assets/` 目录链接/复制到 `public/apps/{appId}/` |
| 升级 | `removeAssetSymlink()` → `createAssetSymlink()` | 先删除旧资源，再重新发布 |
| 卸载 | `removeAssetSymlink()` | 删除 `public/apps/{appId}/` 目录 |
#### 发布策略
- **Linux 环境**：优先创建符号链接（`symlink`），`public/apps/{appId}` 指向 `Assets/` 目录
- **Windows 环境**：`symlink()` 可能不可用，降级为 `File::copyDirectory()` 将 `Assets/` 内容复制到 `public/apps/{appId}/`
- **目标路径已存在时跳过**：如果 `public/apps/{appId}/` 已存在，`createAssetSymlink()` 不会重复处理
#### 目录结构映射
```
app/Apps/Blog/Assets/ → public/apps/blog/
├── css/ → ├── css/
│ └── style.css → │ └── style.css
├── js/ → ├── js/
│ └── app.js → │ └── app.js
└── fonts/ → └── fonts/
└── icon.ttf → └── icon.ttf
```
#### ⚠️ 关键注意事项
1. **禁止在 Install.php 中创建 `public/apps/{appId}/` 下的目录**：安装流程的执行顺序是先调用 `Install::install()`，再调用 `createAssetSymlink()`。如果在 `Install::install()` 中提前创建了 `public/apps/{appId}/` 下的任何目录，`createAssetSymlink()` 检测到目标路径已存在后会直接跳过，导致 `Assets/` 下的文件不会被复制/链接
```php
// ❌ 错误：提前创建目录会阻止框架的资源发布
public function install(): void
{
$this->runMigrations();
mkdir(public_path('apps/blog/uploads'), 0755, true); // 这会导致 Assets 不被复制
}
// ✅ 正确：不在 Install.php 中创建 public/apps/{appId}/ 下的目录
public function install(): void
{
$this->runMigrations();
}
```
2. **运行时上传目录不应放在 Assets 中**：`Assets/` 目录的文件由系统在安装/升级时统一管理，用户上传的文件应存放在 `storage/` 或其他独立目录中，避免升级时被 `removeAssetSymlink()` 清除
3. **升级时 Assets 内容会被刷新**：升级流程先删除 `public/apps/{appId}/` 再重新发布，因此 `Assets/` 中应只包含应用自带的静态资源，不要存放运行时生成的文件
***
## 七、数据库迁移
### 命名规范
应用创建的数据库表必须使用 `app_{app_id}_` 前缀：
```
app_blog_posts → Blog 应用的文章表
app_blog_categories → Blog 应用的分类表
app_blog_tags → Blog 应用的标签表
```
### 迁移文件
在 `Migrations/` 目录下创建迁移文件：
```php
bigIncrements('id')->comment('主键ID');
$table->string('title')->comment('文章标题');
$table->text('content')->nullable()->comment('文章内容');
$table->unsignedTinyInteger('status')->default(0)->comment('状态：0-草稿 1-已发布 2-已下架');
$table->timestamp('create_time')->nullable()->comment('创建时间');
$table->timestamp('update_time')->nullable()->comment('更新时间');
$table->index('status');
});
DB::statement("ALTER TABLE `app_blog_posts` COMMENT '博客文章表'");
}
public function down(): void
{
Schema::dropIfExists('app_blog_posts');
}
};
```
### ⚠️ 迁移幂等性规范
迁移的 `up()` 和 `down()` 方法必须具备幂等性——即重复执行不会报错。这是因为在安装、升级、卸载流程中，迁移可能被多次调用（系统 `Artisan::call('migrate')` + `Install::install()` 兜底），如果缺少幂等检查会导致 `SQLSTATE[42S01]: Table already exists` 或 `SQLSTATE[42S02]: Base table or view not found` 错误。
#### 建表迁移的幂等性
```php
public function up(): void
{
if (Schema::hasTable('app_blog_posts')) {
return;
}
Schema::create('app_blog_posts', function (Blueprint $table) {
// ...
});
}
public function down(): void
{
Schema::dropIfExists('app_blog_posts');
}
```
> `Schema::dropIfExists()` 本身已具备幂等性（表不存在时不报错），但 `Schema::create()` 不具备——重复建表会抛异常，因此 `up()` 必须添加表存在性检查。
#### 加列迁移的幂等性
当通过迁移为已有表添加字段时，`up()` 和 `down()` 都需要检查表和列的存在性：
```php
public function up(): void
{
if (!Schema::hasTable('app_blog_posts')) {
return;
}
Schema::table('app_blog_posts', function (Blueprint $table) {
if (!Schema::hasColumn('app_blog_posts', 'summary')) {
$table->string('summary', 500)->nullable()->after('title')->comment('摘要');
}
if (!Schema::hasColumn('app_blog_posts', 'sort')) {
$table->integer('sort')->default(0)->after('status')->comment('排序');
}
});
}
public function down(): void
{
if (!Schema::hasTable('app_blog_posts')) {
return;
}
Schema::table('app_blog_posts', function (Blueprint $table) {
$columns = [];
if (Schema::hasColumn('app_blog_posts', 'summary')) $columns[] = 'summary';
if (Schema::hasColumn('app_blog_posts', 'sort')) $columns[] = 'sort';
if (!empty($columns)) $table->dropColumn($columns);
});
}
```
> **关键场景**：卸载时系统先调 `Install::uninstall()` 再调 `rollbackMigrations()`。如果 `down()` 缺少表存在性检查，在表已被清理的情况下执行 `ALTER TABLE ... DROP COLUMN` 会报 `Table not found` 错误，导致卸载失败。
#### 幂等性速查表
| 操作类型 | up() 检查 | down() 检查 |
| ------- | --------- | ----------- |
| 建表 `Schema::create` | `Schema::hasTable()` → return | `Schema::dropIfExists()`（自带幂等） |
| 加列 `$table->string()` | `Schema::hasTable()` + `Schema::hasColumn()` | `Schema::hasTable()` + `Schema::hasColumn()` |
| 加索引 `$table->index()` | `Schema::hasTable()` | `Schema::hasTable()` |
| 改列 `$table->change()` | `Schema::hasTable()` + `Schema::hasColumn()` | `Schema::hasTable()` + `Schema::hasColumn()` |
### 备注规范
**表和字段必须添加备注**，这是数据库可维护性的基本要求，方便团队成员理解每个表和字段的业务含义。
#### 表备注
使用 `DB::statement()` 在 `up()` 方法中添加表备注：
```php
DB::statement("ALTER TABLE `app_blog_posts` COMMENT '博客文章表'");
```
#### 字段备注
使用 Laravel Schema Builder 的 `->comment()` 方法为每个字段添加备注：
```php
$table->string('title')->comment('文章标题');
$table->unsignedTinyInteger('status')->default(0)->comment('状态：0-草稿 1-已发布 2-已下架');
```
#### 备注编写规则
| 规则 | 说明 | 示例 |
| ----- | -------------------- | ------------------------------ |
| 语义清晰 | 备注必须说明字段的业务含义，而非数据类型 | ✅ `状态：0-禁用 1-启用` ❌ `tinyint类型` |
| 枚举值说明 | 状态、类型等枚举字段必须列出所有可选值 | `类型：1-Web 2-移动端 3-服务端` |
| 关联说明 | 外键字段需说明关联的表 | `分类ID，关联app_blog_categories表` |
| 简洁明了 | 备注应精炼，避免冗余描述 | ✅ `用户名` ❌ `用户的名字用于登录系统` |
#### 基础字段备注参考
系统规范的基础字段，备注应统一如下：
| 字段 | 推荐备注 |
| ------------- | ----------------------- |
| `id` | 主键ID |
| `status` | 状态：0-禁用 1-启用（根据业务调整枚举值） |
| `create_time` | 创建时间 |
| `update_time` | 更新时间 |
### 时间字段
遵循系统规范，使用 `create_time` 和 `update_time`（非 Laravel 默认）。
### 日期时间格式规范
**原则：数据库中的日期字段直接读取输出，禁止二次格式化加工。统一使用 `Y-m-d H:i:s` 格式，禁止 ISO 8601 格式。**
> 详细规范参见 `.trae/rules/php-coding-standards.md` 第1节「日期时间处理」。
#### 正确格式
```
2026-05-23 15:29:13
```
#### 禁止格式
```
2026-05-23T00:16:39.000000Z // ISO 8601 带时区格式（Laravel 默认序列化格式）
2026-05-23T00:16:39+08:00 // ISO 8601 带偏移格式
May 23, 2026 3:29 PM // 英文可读格式
```
#### 实现方式
**方式一：模型 `$casts` 配置（推荐，按字段控制）**
```php
protected $casts = [
'create_time' => 'datetime:Y-m-d H:i:s',
'update_time' => 'datetime:Y-m-d H:i:s',
];
```
**方式二：重写 `serializeDate` 方法（全局生效）**
> 系统基类 `App\Models\BaseModel` 已全局重写 `serializeDate()`，返回 `Y-m-d H:i:s` 格式，所有继承 `BaseModel` 的模型自动生效。
```php
protected function serializeDate(DateTimeInterface $date): string
{
return $date->format('Y-m-d H:i:s');
}
```
#### 关键陷阱：`$casts` 只在模型序列化时生效
**`$casts` 中配置的 `datetime:Y-m-d H:i:s` 仅在调用 `toArray()` / `toJson()` 时生效。直接属性访问 `$model->create_time` 仍返回 Carbon 对象，放入普通数组后 `response()->json()` 会将 Carbon 序列化为 ISO 8601 格式，导致前端显示 `2026-05-23T00:16:39.000000Z`。**
##### 错误写法
```php
// ❌ 直接从模型取属性放入数组 → Carbon 对象 → JSON 序列化为 ISO 8601
$data = array_map(function ($item) {
return [
'id' => $item->id,
'create_time' => $item->create_time, // Carbon 对象！
];
}, $notes);
```
##### 正确写法一：先 `toArray()` 再提取字段
```php
// ✅ 先转为数组（触发 $casts 格式化），再提取字段
$data = array_map(function ($item) {
$arr = $item->toArray();
return [
'id' => $arr['id'],
'create_time' => $arr['create_time'], // 已格式化为 "Y-m-d H:i:s" 字符串
];
}, $notes);
```
##### 正确写法二：显式 `format()`
```php
// ✅ 手动格式化 Carbon 对象
$data = array_map(function ($item) {
return [
'id' => $item->id,
'create_time' => $item->create_time ? $item->create_time->format('Y-m-d H:i:s') : null,
];
}, $notes);
```
##### 正确写法三：直接返回 Eloquent 模型（自动序列化）
```php
// ✅ 直接将模型放入响应，response()->json() 会调用 toArray() 触发 $casts
return response()->json($note); // 自动走 toArray() → serializeDate() → Y-m-d H:i:s
```
#### 禁止事项
- **禁止**在 Controller / Service 层对已从模型取出的日期字段再次调用 `format()` 方法（仅当直接访问 Carbon 对象需要格式化时除外，见正确写法二）
- **禁止**在前端视图或 API 响应中对日期做二次格式化
- **禁止**使用 Laravel 默认的 ISO 8601 序列化格式返回给前端
- **禁止**从 Eloquent 模型直接取日期属性放入普通数组（会丢失 `$casts` 格式化）
- 第三方 API 返回的 ISO 8601 日期写入数据库前，**必须**先解析为 `Y-m-d H:i:s` 格式
***
## 八、模型开发
### 模型模板
```php
\App\Enums\Status::class,
'create_time' => 'datetime:Y-m-d H:i:s',
'update_time' => 'datetime:Y-m-d H:i:s',
];
}
```
***
## 九、钩子系统
### 钩子类型
| 类型 | 说明 | 返回值 |
| ------ | ------------ | --------- |
| Action | 在特定节点执行自定义逻辑 | 无 |
| Filter | 在特定节点拦截并修改数据 | 必须返回修改后的值 |
### 注册钩子
创建 `Hooks.php`：
```php
registerAction('content.after_create', [$this, 'onContentCreated'], 10, 'blog');
$hooks->registerFilter('content.list.query', [$this, 'filterContentQuery'], 10, 'blog');
}
public function onContentCreated($content): void
{
// 内容创建后的自定义逻辑
}
public function filterContentQuery($query)
{
return $query->where('status', 1);
}
}
```
**重要**：注册钩子时必须传入 `app_id`（第4个参数），以便应用禁用时自动移除钩子。
### 系统内置钩子点
> 钩子点按模块分组列出。所有系统级钩子在注册时**无需**传入 `app_id`（系统不会自我卸载）；应用自定义钩子仍需传 `app_id`。
#### 已实现：应用生命周期（app.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| --------------- | ------ | ------------------- | ------------------------------------------- |
| `app.installed` | Action | $appId | `AppInstallerService::install` / `installFromPackage` |
| `app.uninstalled` | Action | $appId | `AppInstallerService::uninstall` |
| `app.upgraded` | Action | $appId, $from, $to | `AppInstallerService::upgrade` |
| `app.enabled` | Action | $appId | `AppManagerService::enable` |
| `app.disabled` | Action | $appId | `AppManagerService::disable` |
#### 已实现：前台用户认证与资料（user.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ---------------------- | ------ | ---------------- | ----------------------------- |
| `user.before_register` | Filter | $data | `Api\UserAuthController::register` |
| `user.after_register` | Action | $user | `Api\UserAuthController::register` |
| `user.before_login` | Filter | $credentials | `Api\UserAuthController::login` |
| `user.after_login` | Action | $user | `Api\UserAuthController::login` |
| `user.before_logout` | Action | $user | `Api\UserAuthController::logout` |
| `user.profile.updating` | Filter | $data, $user | `Api\UserAuthController::updateProfile` |
| `user.profile.updated` | Action | $user | `Api\UserAuthController::updateProfile` |
> **重要**：`user.*` 系列仅由**前台用户自助操作**触发（注册 / 登录 / 登出 / 修改个人资料）。以下场景**不触发**：
> - 管理员在后台管理前台用户（增删改、改状态、重置密码）—— 当前无钩子，规划使用 `front_user.*` 系列
> - 后台管理员自身的登录 / 登出 / 改密 —— 当前无钩子，规划使用 `admin.*` 系列
#### 已实现：内容管理（content.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ---------------------- | ------ | --------------- | ----------------------------- |
| `content.list.query` | Filter | $query | `ContentService::index` 查询构建后 |
| `content.before_create` | Filter | $data | `ContentService::store` 事务前 |
| `content.after_create` | Action | $content | `ContentService::store` 事务提交后 |
| `content.before_update` | Filter | $data, $content | `ContentService::update` 事务前 |
| `content.after_update` | Action | $content | `ContentService::update` 事务后 |
| `content.before_delete` | Action | $content | `ContentService::destroy` / `batchDelete` 事务前 |
| `content.after_delete` | Action | $content | `ContentService::destroy` / `batchDelete` 事务后 |
| `content.before_update_status` | Filter | $status, $content | `ContentService::updateStatus` 更新前 |
| `content.after_update_status` | Action | $content, $status | `ContentService::updateStatus` 更新后 |
> **事务边界约定**：`after_*` 钩子在 `DB::transaction` 闭包**外**触发，确保钩子内副作用不会被回滚；`before_*` 钩子在事务内触发。Filter 钩子必须接收返回值（`$data = $hookManager->applyFilter(...)`）。`batchDelete` 的 `before_delete` 在事务内逐条触发，`after_delete` 在事务提交后逐条触发。
#### 已实现：菜单渲染（menu.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| --------------- | ------ | ------ | ----------------------------------- |
| `menu.rendering` | Filter | $menus | `MenuService::tree` / `userMenus` / `homeMenus` buildTree 后 |
> 该钩子用于动态注入或隐藏菜单项，覆盖菜单管理页全量树、后台用户菜单、前台导航三个场景。
#### 已实现：后台管理员认证（admin.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| --------------------------- | ------ | ------------------- | ----------------------------- |
| `admin.before_login` | Filter | $credentials | `AuthService::login` 查询前 |
| `admin.after_login` | Action | $user | `AuthService::login` 更新登录信息后 |
| `admin.login_failed` | Action | $username, $reason | `AuthService::login` 校验失败处 |
| `admin.before_logout` | Action | $user | `AuthService::logout` 前 |
| `admin.after_password_changed` | Action | $user | `AuthService::changePassword` 后 |
#### 已实现：后台管理员管理（admin_user.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| --------------------------- | ------ | --------------- | ----------------------------------- |
| `admin_user.before_create` | Filter | $data | `UserService::store` 创建前 |
| `admin_user.after_create` | Action | $user | `UserService::store` return 前 |
| `admin_user.after_update` | Action | $user | `UserService::update` return 前 |
| `admin_user.before_delete` | Action | $user | `UserService::destroy` / `batchDelete` 事务前 |
| `admin_user.after_delete` | Action | $user | `UserService::destroy` / `batchDelete` 删除后 |
| `admin_user.status_changed` | Action | $user, $status | `UserService::updateStatus` 更新后 |
| `admin_user.password_reset` | Action | $user | `UserService::resetPassword` 更新后 |
#### 已实现：管理员操作前台用户（front_user.* 系列）
> 与 `user.*` 区分：`user.*` 是前台用户**自助**操作；`front_user.*` 是**管理员**操作前台用户。
| 钩子点 | 类型 | 参数 | 触发位置 |
| --------------------------- | ------ | --------------- | ----------------------------------- |
| `front_user.after_create` | Action | $user | `FrontUserService::store` return 前 |
| `front_user.after_update` | Action | $user | `FrontUserService::update` return 前 |
| `front_user.before_delete` | Action | $user | `FrontUserService::destroy` / `batchDelete` 事务前 |
| `front_user.after_delete` | Action | $user | `FrontUserService::batchDelete` 事务后 |
| `front_user.status_changed` | Action | $user, $status | `FrontUserService::updateStatus` 后 |
| `front_user.password_reset` | Action | $user | `FrontUserService::resetPassword` 后 |
#### 已实现：附件管理（attachment.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ------------------------- | ------ | ------------------- | ----------------------------------- |
| `attachment.before_upload` | Filter | $file, $config | `AttachmentService::upload` 校验后 |
| `attachment.after_upload` | Action | $attachment | `AttachmentService::upload` 创建后 |
| `attachment.before_delete` | Action | $attachment | `AttachmentService::destroy` 事务内 |
| `attachment.after_delete` | Action | $attachment | `AttachmentService::destroy` 事务后 |
#### 已实现：角色管理（role.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ------------------ | ------ | ---- | ----------------------------- |
| `role.after_create` | Action | $role | `RoleService::store` 缓存清理后 |
| `role.after_update` | Action | $role | `RoleService::update` 缓存清理后 |
| `role.after_delete` | Action | $role | `RoleService::destroy` 缓存清理后 |
#### 已实现：用户组管理（user_group.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ------------------------ | ------ | ----- | ----------------------------------- |
| `user_group.after_create` | Action | $group | `UserGroupService::store` return 前 |
| `user_group.after_update` | Action | $group | `UserGroupService::update` return 前 |
| `user_group.after_delete` | Action | $group | `UserGroupService::destroy` return 前 |
#### 已实现：配置项管理（config.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ------------------------- | ------ | ----- | ----------------------------------- |
| `config.after_create` | Action | $item | `ConfigItemController::store` 创建后 |
| `config.after_update` | Action | $item | `ConfigItemController::update` 更新后 |
| `config.after_batch_update` | Action | $items | `ConfigItemController::batch` 清缓存后 |
#### 已实现：仪表盘统计（dashboard.* 系列）
| 钩子点 | 类型 | 参数 | 触发位置 |
| ----------------- | ------ | ----- | ----------------------------------- |
| `dashboard.stats` | Filter | $stats | `DashboardController::stats` 汇总后 |
> 该钩子允许应用注入自定义统计卡片（如订单数、营收额等），返回的 `$stats` 数组会直接作为响应数据。
#### 文档声明但尚未实现（应用暂不可挂载）
> 当前无。所有规划的系统级钩子点均已落地。
### 触发自定义钩子
应用也可以定义自己的钩子点供其他应用使用：
```php
$hookManager = app(\App\Services\HookManager::class);
// 触发 Action
$hookManager->doAction('blog.post.published', $post);
// 触发 Filter
$query = $hookManager->applyFilter('blog.post.query', $query);
```
***
## 十、Install 脚本
### 模板
创建 `Install.php` 可在安装/卸载/升级时执行自定义逻辑：
```php
**原则**：数据库表的创建和删除完全由迁移文件的 `up()` / `down()` 方法负责，`Install::uninstall()` 只处理缓存清理、外部通知等非数据库操作。
### ⚠️ 卸载迁移回滚兜底
系统卸载流程第 2 步 `rollbackMigrations()` 使用 `Artisan::call('migrate:rollback', ['--path' => ...])` 回滚数据库。该命令依赖 `migrations` 表记录和路径解析，在 Windows 等环境下可能因路径分隔符、大小写等问题导致 `down()` 未执行，造成**卸载后数据库表和数据残留**。重装时 `up()` 的 `Schema::hasTable()` 检查发现表已存在会跳过，旧数据原封不动保留。
**解决方案**：在 `uninstall()` 中增加迁移回滚兜底，直接 `require` 迁移文件并调用 `down()` 方法，确保表一定被清理。同时删除 `migrations` 表中的对应记录，避免系统后续调 `rollbackMigrations()` 时因记录已删除而跳过（不会冲突）。
```php
public function uninstall(): void
{
$this->rollbackMigrations();
Cache::flush();
}
protected function rollbackMigrations(): void
{
$migrationsPath = __DIR__ . '/Migrations';
$migrationFiles = glob($migrationsPath . '/*.php');
foreach (array_reverse($migrationFiles) as $file) {
$migrationName = pathinfo($file, PATHINFO_FILENAME);
if (!DB::table('migrations')->where('migration', $migrationName)->exists()) {
continue;
}
$migration = require $file;
if (method_exists($migration, 'down')) {
try {
$migration->down();
DB::table('migrations')->where('migration', $migrationName)->delete();
} catch (\Throwable $e) {
Log::error('应用迁移回滚失败', [
'app' => 'blog',
'file' => basename($file),
'error' => $e->getMessage(),
]);
}
}
}
}
```
关键设计说明：
| 要点 | 说明 |
| ---- | ---- |
| 逆序回滚 | `array_reverse()` 确保后建的表先删，避免外键约束问题 |
| 检查 migrations 记录 | 仅回滚 `migrations` 表中有记录的迁移，跳过未执行的迁移 |
| 删除 migrations 记录 | 回滚成功后删除记录，避免系统 `rollbackMigrations()` 重复执行 |
| down() 幂等性 | `down()` 必须使用 `Schema::dropIfExists()` 等幂等方法，确保重复调用不报错 |
| 与系统 rollbackMigrations 不冲突 | 先删 `migrations` 记录，系统后续调 `migrate:rollback` 时找不到记录，不会重复执行 |
### 迁移兜底机制
系统安装流程会自动执行 `Migrations/` 目录下的迁移文件。但在某些环境下（如 Windows 路径分隔符问题），迁移可能未正确执行。为确保安装可靠性，建议在 `Install.php` 的 `install()` 方法中增加迁移兜底逻辑：
```php
runMigrations();
// 其他初始化逻辑（如种子数据）...
}
public function uninstall(): void
{
$this->rollbackMigrations();
Cache::flush();
}
public function upgrade(string $fromVersion, string $toVersion): void
{
$this->runMigrations();
}
protected function runMigrations(): void
{
$migrationsPath = __DIR__ . '/Migrations';
$migrationFiles = glob($migrationsPath . '/*.php');
foreach ($migrationFiles as $file) {
$migrationName = pathinfo($file, PATHINFO_FILENAME);
if (DB::table('migrations')->where('migration', $migrationName)->exists()) {
continue;
}
$migration = require $file;
if (method_exists($migration, 'up')) {
try {
$migration->up();
DB::table('migrations')->insert([
'migration' => $migrationName,
'batch' => DB::table('migrations')->max('batch') + 1,
]);
} catch (\Throwable $e) {
Log::error('应用迁移执行失败', [
'app' => 'blog',
'file' => basename($file),
'error' => $e->getMessage(),
]);
}
}
}
}
protected function rollbackMigrations(): void
{
$migrationsPath = __DIR__ . '/Migrations';
$migrationFiles = glob($migrationsPath . '/*.php');
foreach (array_reverse($migrationFiles) as $file) {
$migrationName = pathinfo($file, PATHINFO_FILENAME);
if (!DB::table('migrations')->where('migration', $migrationName)->exists()) {
continue;
}
$migration = require $file;
if (method_exists($migration, 'down')) {
try {
$migration->down();
DB::table('migrations')->where('migration', $migrationName)->delete();
} catch (\Throwable $e) {
Log::error('应用迁移回滚失败', [
'app' => 'blog',
'file' => basename($file),
'error' => $e->getMessage(),
]);
}
}
}
}
}
```
> **注意**：此兜底机制使用 `__DIR__` 定位迁移文件，避免路径分隔符兼容性问题。`require` 迁移文件后直接调用 `$migration->up()` 创建表，绕过 `Artisan::call('migrate')` 在事务上下文中可能失败的问题。执行成功后必须向 `migrations` 表插入记录，防止 `php artisan migrate` 重复执行。卸载时同理，直接调用 `$migration->down()` 删除表，绕过 `Artisan::call('migrate:rollback')` 路径解析可能失败的问题，回滚成功后删除 `migrations` 表记录，防止系统 `rollbackMigrations()` 重复执行。
### ⚠️ 配置同步规范（seedDefaultConfigs）
**应用在 `manifest.json` 中声明了 `config_groups` 时，必须在 Install.php 中实现 `seedDefaultConfigs()` 方法**，并在 `install()` 和 `upgrade()` 中调用。该方法负责以 `manifest.json` 为基准同步配置组/配置项到数据库，确保安装时初始化默认值，升级时自动更新结构且不覆盖用户已设置的值。
#### 核心规则
```
seedDefaultConfigs() 以 manifest.json 为唯一基准，执行三向同步：
新增的配置项 ──→ 创建记录，写入 manifest 默认值
保留的配置项 ──→ 更新结构（name/type/tips/sort），保留用户设置的 value
删除的配置项 ──→ 删除 DB 中对应的残留记录
```
| 时机 | 行为 | 说明 |
|------|------|------|
| 安装 | 读取 manifest 创建全部配置组和配置项 | 所有配置项写入 manifest 默认值 |
| 升级 | 以 manifest 为基准做三向同步 | 新增项写入默认值，已有项保留用户值，已删除项清理残留 |
| 卸载 | `removeConfigs()` 全量清理 | 删除该应用所有配置组和配置项 |
#### 模板
```php
/**
* 从 manifest.json 同步配置到数据库
* - 新增配置：写入默认值
* - 已有配置：仅更新结构（name/type/tips/sort），保留用户设置的 value
* - 已删除配置：清理 DB 残留
*/
protected function seedDefaultConfigs(): void
{
if (!class_exists(\App\Models\ConfigGroup::class) || !class_exists(\App\Models\ConfigItem::class)) {
return;
}
$manifestPath = __DIR__ . '/manifest.json';
if (!file_exists($manifestPath)) {
return;
}
$manifest = json_decode(file_get_contents($manifestPath), true);
$configGroups = $manifest['config_groups'] ?? [];
$appId = '你的应用ID'; // 替换为实际 app_id
// 1. 收集 manifest 中定义的所有配置项 code（用于清理残留）
$manifestCodes = [];
foreach ($configGroups as $groupDef) {
$group = \App\Models\ConfigGroup::updateOrCreate(
['code' => 'app_' . $appId . '_' . $groupDef['name']],
[
'name' => $groupDef['title'],
'app_id' => $appId,
'sort' => 0,
'status' => 1,
]
);
foreach ($groupDef['items'] as $index => $item) {
$fullCode = 'app_' . $appId . '_' . $item['name'];
$manifestCodes[] = $fullCode;
$existing = \App\Models\ConfigItem::where('code', $fullCode)->first();
if ($existing) {
// 已有记录 → 仅更新结构信息，不覆盖用户设置的 value
$existing->update([
'group_id' => $group->id,
'name' => $item['title'],
'type' => $item['type'] ?? 'text',
'tips' => $item['tips'] ?? '',
'sort' => $index,
'status' => 1,
]);
} else {
// 新增配置 → 写入默认值
\App\Models\ConfigItem::create([
'code' => $fullCode,
'group_id' => $group->id,
'name' => $item['title'],
'type' => $item['type'] ?? 'text',
'value' => $item['value'] ?? '',
'tips' => $item['tips'] ?? '',
'sort' => $index,
'status' => 1,
]);
}
}
}
// 2. 清理 manifest 中已删除的配置项（防残留）
\App\Models\ConfigItem::where('code', 'like', 'app_' . $appId . '_%')
->whereNotIn('code', $manifestCodes)
->delete();
// 3. 清理 manifest 中已删除的配置组（无子项的组）
\App\Models\ConfigGroup::where('app_id', $appId)
->whereDoesntHave('items')
->delete();
}
```
#### 强制要求
1. **manifest.json 是唯一基准**：`seedDefaultConfigs()` 必须以 `manifest.json` 的 `config_groups` 定义为唯一数据源，不得在代码中硬编码配置定义。
2. **已存在配置项禁止覆盖 value**：使用 `$existing->first()` + `update()`（不传 value），不得使用 `updateOrCreate` 第二个参数统一覆盖。
3. **必须清理删除的配置项**：manifest 移除的配置项，必须在 `seedDefaultConfigs()` 中清理 DB 残留，防止重名配置项读到旧值。
4. **install() 和 upgrade() 必须调用**：`install()` 确保首次安装写入初始化默认值；`upgrade()` 确保升级时同步新增/变更的配置结构。
5. **卸载时全量清理**：`uninstall()` 通过 `removeConfigs()` 删除该应用所有配置组和配置项，此操作不可逆。
6. **select 类型变更处理**：如果已有配置项从 select 改为其他类型（或 options 变化），由于 value 保留用户旧值可能不兼容新格式。开发者应在升级脚本中自行处理数据迁移。
***
## 十一、菜单声明
在 `manifest.json` 中声明菜单：
> **⚠️ 菜单声明硬性规范**：
> 1. **目录不声明 path**：`menus` / `user_menus` 中**含 `children` 的目录（顶级分组菜单）不得声明 `path` 字段**，禁止写 `"path": "/"`、`"path": ""` 或任何路径值。目录本身不承担路由跳转，`path` 仅由叶子菜单（children）声明。`home_menus` 为扁平结构、无目录层级，每个菜单项均为叶子导航，**必须声明 `path`**。
> 2. **code 全局唯一**：`menus` 中目录（父级）的 `code` **不得与任何子菜单的 `code` 相同**，同一 `menus` 结构内所有 `code`（含目录与子菜单）必须全局唯一，否则升级时按 `(app_id, code, terminal_type)` 幂等匹配会错乱，导致菜单被误删或角色关联丢失。
### 基本结构（独立顶级菜单）
```json
{
"menus": [
{
"code": "blog",
"title": "博客管理",
"icon": "fa fa-book",
"order": 100,
"children": [
{
"code": "blog_posts",
"title": "文章管理",
"icon": "fa fa-file-text",
"path": "/admin/blog/posts",
"order": 1
},
{
"code": "blog_categories",
"title": "分类管理",
"icon": "fa fa-folder",
"path": "/admin/blog/categories",
"order": 2
}
]
}
]
}
```
### 挂载到指定父菜单（parent 字段）
如果希望应用的菜单插入到已有的系统菜单下（而非创建新的顶级菜单），可使用 `parent` 字段：
```json
{
"menus": [
{
"code": "versionmgr",
"title": "版本管理",
"icon": "layui-icon layui-icon-refresh",
"order": 4,
"parent": 15,
"children": [
{ "code": "versionmgr_overview", "title": "版本总览", "icon": "fa fa-info-circle", "path": "/admin/versionmgr", "order": 1 },
{ "code": "versionmgr_packages", "title": "升级管理", "icon": "fa fa-upload", "path": "/admin/versionmgr/packages", "order": 2 }
]
}
]
}
```
**效果**：当指定了 `parent` 时，不会创建「版本管理」这个中间级菜单，其 `children` 会直接挂载到「系统维护」（ID=15）菜单下。
### parent 字段说明
| 值类型 | 示例 | 匹配规则 |
| -------------- | ----------- | --------------- |
| 菜单名称（字符串） | `"系统维护"` | 按 `name` 字段精确匹配 |
| 菜单路径（以 `/` 开头） | `"/system"` | 按 `path` 字段精确匹配 |
| 菜单 ID（数字） | `14` | 按 `id` 精确查找 |
**优先级**：ID > 路径 > 名称。**推荐使用 ID**，因为菜单名称可能被管理员修改导致匹配失败。
### 菜单字段说明
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ---------- | --------- | -------------------------------------------- |
| title | string | 是 | 菜单显示名称 |
| **code** | string | **否（推荐）** | **菜单稳定标识符，用于升级时幂等匹配保留菜单 ID 和角色关联。同一 `menus` 内必须全局唯一，目录 code 不得与子菜单 code 相同（硬性规范）。详见下方「菜单 code 字段」** |
| icon | string | 否 | 图标 CSS 类名 |
| path | string | 否 | 菜单路径，用于路由跳转。**目录（含 `children` 的顶级分组菜单）不得声明 `path` 字段（硬性规范，禁止写 `"path": "/"`），`path` 仅由叶子菜单声明** |
| order | integer | 否 | 排序值，越小越靠前 |
| **parent** | string/int | **否** | **父菜单标识（名称/路径/ID），指定后将 children 直接挂载到该父菜单下** |
| children | array | 否 | 子菜单列表 |
> **注意**：使用 `parent` 字段时，当前菜单项本身不会被创建为可见菜单，其 `children` 将直接成为父菜单的子项。卸载应用时仅删除 `app_id` 匹配的菜单，**不影响父菜单**。
### 菜单 code 字段（推荐）
`code` 是菜单的**稳定标识符**，用于应用升级时按 code 匹配旧菜单，保留菜单 ID 和角色关联，避免升级后管理员权限丢失。
**为什么需要 code？**
未引入 code 前，菜单升级依赖 `path + parent_id + terminal_type` 三元组做幂等匹配，存在以下问题：
- 应用调整路由 path（如 `/admin/blog` 改为 `/admin/cmspro/blog`）时，旧菜单被判定为已删除并新建菜单，导致菜单 ID 变化、`admin_role_menus` 角色关联丢失
- 部分升级路径会全量删除并重建菜单，角色权限需要管理员重新分配
引入 code 字段后：
- 升级时优先按 `(app_id, code, terminal_type)` 匹配旧菜单
- 命中则保留菜单 ID 和角色关联，仅更新 `name`/`icon`/`path`/`sort` 等属性
- path 调整不影响匹配，角色关联完整保留
- code 未命中时按 `(app_id, path, terminal_type)` 兜底匹配，命中后回写 code 字段
**命名规范**：
- 仅允许小写字母、数字、下划线：`^[a-z][a-z0-9_]*$`
- 长度 ≤ 80 字符
- 同一应用、同一 `terminal_type` 下唯一
- **同一 `menus` 结构内全局唯一（硬性规范）**：目录（父级）的 `code` 不得与任何子菜单的 `code` 相同，否则升级时按 `(app_id, code, terminal_type)` 匹配会错乱，导致菜单被误删或角色关联丢失
- 推荐使用语义化命名，如 `blog_posts`、`domainmanager_settings`、`my_blog_posts`
**可选声明与兜底机制**：
- code 字段为可选，**未声明时系统按 path 自动 slug 化生成**（如 `/admin/blog/posts` → `admin_blog_posts`）作为兜底
- 但自动生成的 code 在 path 变化时也会变化，无法保证稳定，**强烈推荐开发者主动声明 code**
- 历史应用无需改造 manifest 即可继续工作，系统会自动为已安装菜单回填 code
**完整示例**：
```json
{
"menus": [
{
"code": "blog",
"title": "博客管理",
"icon": "fa fa-book",
"order": 100,
"children": [
{ "code": "blog_posts", "title": "文章管理", "icon": "fa fa-file-text", "path": "/admin/blog/posts", "order": 1 },
{ "code": "blog_categories", "title": "分类管理", "icon": "fa fa-folder", "path": "/admin/blog/categories", "order": 2 }
]
}
],
"user_menus": [
{
"code": "my_blog",
"title": "我的博客",
"icon": "fa fa-book",
"order": 50,
"children": [
{ "code": "my_blog_posts", "title": "我的文章", "icon": "fa fa-file-text", "path": "/user/blog/posts", "order": 1 }
]
}
],
"home_menus": [
{ "code": "blog_home", "title": "博客", "path": "/blog", "order": 30 }
]
}
```
> **重要**：`menus`、`user_menus`、`home_menus` 中每个菜单项均支持 `code` 字段，命名规范一致。一旦声明 code，后续版本**不要修改 code 值**，否则会被识别为新菜单导致旧菜单被删除（角色关联同步清理）。如确需重命名 code，应在升级日志中明确告知管理员重新分配角色权限。
### 系统内置父菜单参考
| 名称 | 路径 | ID | 说明 |
| ---- | ------- | -- | ---------- |
| 系统 | - | 1 | 系统根目录 |
| 系统账号 | /system | 13 | 用户、角色管理 |
| 系统设置 | - | 14 | 站点设置、系统配置 |
| 系统维护 | - | 15 | 日志、附件、数据管理 |
| 首页 | - | 17 | 控制台首页 |
| 管理 | - | 25 | 内容管理等业务模块 |
| 应用 | - | 34 | 已装应用、应用市场 |
菜单会在安装时自动注册到 `admin_menus` 表，卸载时自动清除（仅清除 `app_id` 匹配的记录）。
### 用户端菜单声明（user\_menus）
应用可以同时注册后台管理菜单和用户端菜单。在 `manifest.json` 中使用 `user_menus` 字段声明用户端菜单，结构与 `menus` 完全一致，但注册时自动设置 `terminal_type='user'`：
```json
{
"menus": [
{
"code": "blog",
"title": "博客管理",
"icon": "fa fa-book",
"order": 100,
"children": [
{ "code": "blog_posts", "title": "文章管理", "icon": "fa fa-file-text", "path": "/admin/blog/posts", "order": 1 }
]
}
],
"user_menus": [
{
"code": "my_blog",
"title": "我的博客",
"icon": "fa fa-book",
"order": 50,
"children": [
{ "code": "my_blog_posts", "title": "我的文章", "icon": "fa fa-file-text", "path": "/user/blog/posts", "order": 1 },
{ "code": "my_blog_create", "title": "写文章", "icon": "fa fa-pencil", "path": "/user/blog/create", "order": 2 }
]
}
]
}
```
`user_menus` 同样支持 `parent` 字段，可挂载到用户端已有父菜单下。用户端内置父菜单参考：
| 名称 | 路径 | 说明 |
| ---- | -- | ------ |
| 用户中心 | - | 用户端根目录 |
> **注意**：`user_menus` 中**含 `children` 的目录不得声明 `path` 字段**（硬性规范，同 `menus`），`path` 仅由叶子菜单声明；叶子菜单的 `path` 必须以 `/user/` 开头，与用户端路由前缀对应。卸载应用时，`user_menus` 注册的菜单同样通过 `app_id` 自动清除。
### 官网前端菜单声明（home\_menus）
应用可以在 `manifest.json` 中使用 `home_menus` 字段声明官网前端导航菜单，注册时自动设置 `terminal_type='home'`：
```json
{
"home_menus": [
{ "code": "home", "title": "首页", "path": "/", "order": 1 },
{ "code": "about", "title": "系统介绍", "path": "/about", "order": 2 },
{ "code": "news", "title": "新闻动态", "path": "/news", "order": 3 },
{ "code": "help", "title": "帮助中心", "path": "/help", "order": 4 }
]
}
```
`home_menus` 与 `menus`/`user_menus` 的区别：
| 维度 | `menus` | `user_menus` | `home_menus` |
| ---- | ------- | ------------ | ------------ |
| 终端类型 | `admin` | `user` | `home` |
| 认证要求 | 需登录 | 需登录 | 公开访问 |
| 支持子菜单 | 是（children） | 是（children） | 否（扁平结构） |
| 支持父级挂载 | 是（parent） | 是（parent） | 否 |
| 支持 code 字段 | 是（推荐） | 是（推荐） | 是（推荐） |
| 路由前缀 | `/admin/{appId}` | `/user/{appId}` | 无前缀或自定义 |
> **注意**：`home_menus` 为扁平结构，不支持 `children` 和 `parent` 字段，**不存在目录层级**，每个菜单项均为叶子导航，**必须声明 `path`** 指向实际页面路由（如首页 `"path": "/"`）。官网前端菜单通常为一级导航，无需层级嵌套。卸载应用时，`home_menus` 注册的菜单同样通过 `app_id` 自动清除。
***
## 十二、配置声明
在 `manifest.json` 中声明配置组，安装时系统会自动将配置组和配置项注册到数据库。
### 基本结构
```json
{
"config_groups": [
{
"name": "blog_settings",
"title": "博客设置",
"items": [
{
"name": "posts_per_page",
"title": "每页文章数",
"type": "number",
"value": "10"
},
{
"name": "allow_comments",
"title": "允许评论",
"type": "switch",
"value": "1"
},
{
"name": "default_category",
"title": "默认分类",
"type": "select",
"value": "1",
"options": [
{ "label": "技术", "value": "1" },
{ "label": "生活", "value": "2" },
{ "label": "随笔", "value": "3" }
]
}
]
}
]
}
```
### 配置项类型
| 类型 | 说明 | value 格式 |
| -------- | ---- | ---------------- |
| text | 文本输入 | 字符串 |
| number | 数字输入 | 数字字符串（如 `"10"`） |
| switch | 开关 | `"0"` 或 `"1"` |
| select | 下拉选择 | 需配合 `options` 字段 |
| textarea | 多行文本 | 字符串 |
| image | 图片选择 | 图片路径字符串 |
| password | 密码输入 | 字符串（后台显示为掩码） |
### 字段说明
#### 配置组字段
| 字段 | 类型 | 必填 | 说明 |
| ----- | ------ | -- | -------------------- |
| name | string | 是 | 配置组标识，仅允许小写字母、数字、下划线 |
| title | string | 是 | 配置组显示名称 |
| items | array | 是 | 配置项列表 |
#### 配置项字段
| 字段 | 类型 | 必填 | 说明 |
| ------- | ------ | -- | ------------------------------------- |
| name | string | 是 | 配置项标识，仅允许小写字母、数字、下划线 |
| title | string | 是 | 配置项显示名称 |
| type | string | 是 | 配置项类型，见上方类型表 |
| value | string | 否 | 默认值，所有类型均以字符串形式存储 |
| options | array | 否 | select 类型的选项列表，每项包含 `label` 和 `value` |
| tips | string | 否 | 配置项提示信息，显示在输入框下方，用于说明配置项用途或格式要求 |
### 命名空间与存储规则
系统会自动为应用配置添加前缀，确保不同应用之间的配置不会冲突：
**配置组 code 规则：** `app_{应用id}_{配置组name}`
例如应用 `blog` 中 `name` 为 `blog_settings` 的配置组，存储到数据库的 code 为 `app_blog_blog_settings`。
**配置项 code 规则：** `app_{应用id}_{配置项name}`
例如应用 `blog` 中 `name` 为 `posts_per_page` 的配置项，存储到数据库的 code 为 `app_blog_posts_per_page`。
> **注意：** 在 `manifest.json` 中只需写原始 name，系统在安装时自动添加前缀。不要在 name 中手动添加 `app_` 前缀。
### 读取配置
在代码中通过数据库直接读取应用配置：
```php
use App\Models\ConfigItem;
$item = ConfigItem::where('code', 'app_blog_posts_per_page')->first();
$perPage = $item ? (int) $item->value : 10;
```
也可以通过应用配置服务读取：
```php
use App\Services\AppManagerService;
$manager = app(AppManagerService::class);
$result = $manager->getAppConfig('blog');
```
### ⚠️ 注意事项
1. **name 命名规范：** 配置组和配置项的 `name` 只能使用小写字母、数字和下划线，不要使用中文或特殊字符。
2. **配置项唯一性：** 不同应用的配置项 `name` 可以相同（系统会自动加前缀区分），但同一应用内的配置项 `name` 必须唯一。
3. **系统配置组不可删除：** 系统内置的配置组（基础配置、上传配置、安全配置、邮箱设置）受保护，不允许通过 API 删除或修改其 code。
4. **升级时配置同步：** 应用升级时，系统会自动同步 `manifest.json` 中新增的配置组和配置项。已有配置项的值不会被覆盖（用户修改过的配置会保留）。
5. **卸载时配置清除：** 应用卸载时，该应用的所有配置组和配置项会被级联删除，此操作不可逆。
6. **select 类型必须提供 options：** 使用 `select` 类型时，`options` 字段为必填，格式为 `[{ "label": "显示文本", "value": "存储值" }]`。
7. **value 统一为字符串：** 无论配置项类型是 number 还是 switch，`value` 字段都以字符串形式存储和声明（如 `"10"` 而非 `10`，`"1"` 而非 `true`）。
8. **tips 提示信息：** `tips` 字段会在配置表单中输入框下方显示为灰色提示文字，建议为以下类型的配置项填写 tips：
- **URL 类配置**：提示完整路径格式，如 `"路径：{域名}/api/onlinepay/v1/notify/wechat"`
- **路径类配置**：说明相对路径基准目录，如 `"相对于storage路径，如certs/wechat/apiclient_key.pem"`
- **密钥类配置**：说明密钥格式要求，如 `"RSA2私钥，不含头尾标记"`
- **数值类配置**：说明取值范围和单位，如 `"超时时间，单位：分钟，范围1-1440"`
- tips 在安装时写入数据库，升级时已有记录的 tips 会被更新为最新值（value 不会被覆盖）
9. **应用层 group_code 必须与 manifest 一致（重要，踩坑记录）：** 当应用自定义 `SettingsApiController` 等代码直接写库 `config_items` 时，使用的 `group_code` 必须与 `manifest.json` 中 `config_groups[].name` 经系统前缀化后的 `app_{应用id}_{group_name}` 完全一致。
**背景：** 系统安装/升级应用时统一走 `AppInstallerService::registerConfigGroups` 按 manifest 注册配置组和配置项。如果应用层自定义代码使用了不同的 group_code，会造成两套并存：
- 系统按 manifest 注册到 `app_xxx_dns_provider` 等标准 group 下
- 应用层保存时通过 `updateOrCreate(['code' => $code], ['group_id' => ...])` 把现有记录的 group_id 改写到自创的 `app_xxx` group 下
长期累积形成脏数据后，再次升级时触发唯一键冲突（`config_items_group_code_unique`），升级失败，错误形如：
```
SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry
'20-app_cmspro_domainmanager_dns_provider_type' for key 'config_items_group_code_unique'
```
**错误示例：**
```php
// manifest 中 config_groups 用了 dns_provider/domain_settings/expire_settings 三个 group
// 但应用层写死了一个不一致的 group_code：
private const CONFIG_GROUP_CODE = 'app_cmspro_domainmanager'; // ❌ 缺少 _dns_provider 等后缀
private function saveConfig(string $code, string $value): void
{
ConfigItem::updateOrCreate(
['code' => $code],
[
'group_id' => $this->ensureConfigGroup()->id, // ❌ 把现有记录 group_id 改到自创组
'name' => $code,
'value' => $value,
'type' => 'text',
]
);
}
```
**正确做法：**
- 应用层保存配置时，根据 code 解析对应的 manifest group_name，使用 `app_{应用id}_{group_name}` 作为 group_code
- 或使用 `updateOrCreate(['code' => $code, 'group_id' => $group->id], [...])` 同时以 code+group_id 作为匹配条件
- 写入前先清理其他 group 下相同 code 的历史残留，杜绝脏数据：
```php
ConfigItem::where('code', $code)
->where('group_id', '!=', $group->id)
->delete();
```
**诊断方法：** 当出现 `Duplicate entry 'XX-app_xxx_yyy' for key 'config_items_group_code_unique'` 错误时，用以下 SQL 检查是否存在非 manifest group 下的脏数据：
```sql
SELECT g.id, g.code AS group_code, i.id AS item_id, i.code AS item_code
FROM config_groups g
LEFT JOIN config_items i ON i.group_id = g.id
WHERE g.app_id = '{应用id}'
ORDER BY g.code, i.id;
```
**清理脚本模板：** 确认存在脏数据后，按以下步骤清理（执行前请备份数据库）：
```sql
-- 1. 删除非 manifest 标准组下的配置项残留
DELETE FROM config_items
WHERE code LIKE 'app_{应用id}_{prefix}%'
AND group_id NOT IN (
SELECT id FROM (
SELECT id FROM config_groups
WHERE app_id = '{应用id}'
AND code IN ('app_{应用id}_{group1}', 'app_{应用id}_{group2}', ...)
) AS t
);
-- 2. 删除应用自创的非 manifest 标准组
DELETE FROM config_groups
WHERE app_id = '{应用id}'
AND code NOT IN ('app_{应用id}_{group1}', 'app_{应用id}_{group2}', ...);
-- 3. 检查 manifest 标准组内是否仍有重复 code 残留
SELECT code, COUNT(*) AS cnt, GROUP_CONCAT(id) AS dup_ids
FROM config_items
WHERE code LIKE 'app_{应用id}_{prefix}%'
GROUP BY code
HAVING cnt > 1;
-- 4. 若上一步发现重复，保留 id 最小那条
DELETE FROM config_items
WHERE code LIKE 'app_{应用id}_{prefix}%'
AND id NOT IN (
SELECT min_id FROM (
SELECT MIN(id) AS min_id FROM config_items
WHERE code LIKE 'app_{应用id}_{prefix}%'
GROUP BY code
) AS t
);
```
***
## 十二A、后台设置页面开发
`manifest.json` 的 `config_groups` 仅声明配置项元数据（写入 `config_items` 表），系统不会自动为应用生成可视化的设置界面。当应用需要后台可视化配置入口时，需按本节规范自行开发「后台设置页面」。
> **参考实现**：`app/Apps/CmsproForum/Views/Admin/settings/index.blade.php` + `Controllers/Admin/SettingController.php`
### 12A.1 适用场景
| 场景 | 是否需要开发独立设置页面 |
| ---- | ---------------------- |
| 配置项少于 3 项，类型简单 | 否，可由系统通用配置管理界面维护 |
| 配置项需要分组展示、带说明文案 | 是 |
| 配置项之间存在联动（如开关控制子项是否可编辑） | 是 |
| 需要保存后执行副作用（清缓存、写日志、同步外部） | 是 |
| 配置项包含 textarea（如违禁词列表）、需自定义排版 | 是 |
### 12A.2 目录与路由约定
```
app/Apps/{AppName}/
├── Controllers/Admin/SettingController.php
├── Routes/admin.php
└── Views/Admin/settings/index.blade.php
```
**路由声明**（页面路由 + API 路由分离）：
```php
// Routes/admin.php
// 页面路由（返回 HTML 视图）
Route::get('/settings', [SettingController::class, 'index'])
->name('admin.{app_id}.settings');
// API 路由（返回 JSON）
Route::prefix('api')->group(function () {
Route::get('/settings', [SettingController::class, 'getSettings']);
Route::put('/settings', [SettingController::class, 'update']);
});
```
> **菜单声明**：在 `manifest.json` 的 `menus` 中为 `/admin/{app_id}/settings` 声明一条菜单项（如"论坛设置"），并配 `code` 字段（如 `admin_cmspro_forum_settings`），否则后台左侧导航不会出现入口。
### 12A.3 Controller 实现规范
`SettingController` 必须包含三个核心方法：`index()`（渲染页面）、`getSettings()`（API 返回当前配置）、`update()`（保存配置）。
#### 配置项 code 前缀
应用配置项 code 统一遵循 `app_{应用id}_{配置项name}` 格式（见第十二章「命名空间与存储规则」），Controller 内应定义常量复用：
```php
class SettingController extends Controller
{
/**
* 应用配置项 code 前缀（注意：应用 id 中的点号需转为下划线）
* 例：应用 id 为 cmspro.forum → 前缀为 app_cmspro_forum_
*/
private const CONFIG_PREFIX = 'app_cmspro_forum_';
}
```
#### 白名单机制（强制）
`update()` 必须维护 **`ALLOWED_KEYS` 白名单常量**，仅接受明确列出的配置项，防止前端传入任意 code 篡改其他应用配置：
```php
private const ALLOWED_KEYS = [
'access_mode', 'access_domain', 'access_path',
'topic_review', 'reply_review',
'topics_per_page', 'replies_per_page',
'home_topics_per_page', 'sub_replies_per_page',
'flood_interval', 'flood_max_per_hour',
'allow_reward', 'points_enabled', 'banned_words',
'forum_title', 'forum_description', 'forum_keywords',
];
public function update(Request $request)
{
$data = $request->only(self::ALLOWED_KEYS);
// ...后续保存逻辑
}
```
> **⚠️ 禁止**使用 `$request->all()` 或 `$request->except(...)` 接收配置项，必须用白名单显式枚举。
#### 渲染页面（index 方法）
读取配置时优先取 `ConfigItem` 表中的当前值，缺失时回退到 `config()` 默认值，避免首次安装尚未写入数据库时报错：
```php
public function index()
{
$configKeys = self::ALLOWED_KEYS;
$configs = [];
foreach ($configKeys as $key) {
$item = ConfigItem::where('code', self::CONFIG_PREFIX . $key)->first();
// 优先取数据库值，回退到 Config/{app}.php 中的默认值
$configs[$key] = $item ? $item->value : config('apps.cmspro.forum.' . $key, '');
}
return view('cmspro.forum::Admin.settings.index', compact('configs'));
}
```
#### 保存配置（update 方法）
写入时 **必须正确指定 `group_id`**（指向 manifest 中声明的配置组），不可写 `0` 或随意写一个不存在的 group，否则会触发第十二章第 9 条「group_code 必须与 manifest 一致」中描述的脏数据问题。
```php
public function update(Request $request)
{
$data = $request->only(self::ALLOWED_KEYS);
// 解析配置项所属的 group_id（按 manifest 声明匹配）
$groupMap = $this->resolveConfigGroupMap();
foreach ($data as $key => $value) {
$code = self::CONFIG_PREFIX . $key;
$groupId = $groupMap[$key] ?? 0;
ConfigItem::updateOrCreate(
['code' => $code],
[
'value' => $value,
'group_id' => $groupId,
'name' => $key,
'type' => 'text',
'status' => 1,
]
);
// 清除业务层缓存（如有）
Cache::forget("forum:config:{$key}");
}
// 涉及路由的配置（如 access_mode/access_path）变更后必须清缓存
Artisan::call('route:clear');
Artisan::call('config:clear');
return response()->json(['code' => 0, 'msg' => '配置更新成功', 'data' => null]);
}
```
> **⚠️ 踩坑提醒**：CmsproForum 早期版本的 `SettingController::update()` 直接写 `'group_id' => 0`，导致配置项脱离 manifest 声明的 group，升级时可能触发 `config_items_group_code_unique` 唯一键冲突。新开发的应用应通过 `resolveConfigGroupMap()` 查询 `config_groups` 表得到正确的 `group_id`。
### 12A.4 视图实现规范
设置页面视图位于 `Views/Admin/settings/index.blade.php`，使用 **完整 HTML 结构**（不继承 `layouts.admin`），由后台菜单 iframe 加载。
#### 完整模板
```blade