如何打造带有专属业务逻辑的管理后台

官方管理后台的界面与通用逻辑集中在 packages/nuxt-admin-layer 中，该包由 ZShip 维护并会持续更新（路由、组件、权限相关衔接等）。

请勿修改 nuxt-admin-layer

请把 packages/nuxt-admin-layer 视为只读：

• 直接改 layer 里的代码，会在我们发布模板更新时难以合并。
• 该包相当于「官方提供的通用管理端」，应保持与上游一致。

若您有 特殊业务（独立页面、定制流程、与内部系统对接等），请 不要 在 layer 里改，而应放在 应用层 实现。

正确做法：在 apps/admin 中实现

默认的管理端应用是 apps/admin。它已在 nuxt.config.ts 中通过 extends 引用官方 layer，例如：

export default defineNuxtConfig({
  extends: ['../../packages/nuxt-admin-layer'],
  // ...
})

请把 您的业务逻辑写在这里（或复制 apps/admin 为自有管理端应用后，同样使用 extends 引用 layer）：

• 在应用目录下新增页面（如 app/pages/ 等，以您项目中的 Nuxt 目录约定为准）
• 应用内组件、组合式函数、中间件
• 品牌、runtimeConfig、环境相关配置

这样 您的代码属于自有应用，nuxt-admin-layer 仍是可随官方升级的通用层。

Nuxt Layer 的覆盖关系

使用 extends 时，子应用（您的 apps/admin）与 layer 若定义了同名资源（例如同路径页面、同名组件），通常 子应用中的实现优先生效：

• 您在 apps/admin 中提供了覆盖 → 使用您的实现。
• 您未覆盖 → 使用 nuxt-admin-layer 中的官方实现。

因此您可以 只覆盖需要定制的部分，其余仍跟随官方更新，避免与上游大面积冲突。

实践建议

• 优先在应用内 新增 路由与模块，而不是去改 packages/nuxt-admin-layer 里的文件。
• 权限与 API 仍以服务端为准；前端展示可参考 管理后台 RBAC 与操作员，但 安全边界在 Worker 与 JWT。
• 若需要 单独的管理端工程，可使用 .cursor/skills/ 中的 create-admin 技能：从官方 admin 模板复制并配置好对 layer 的 extends。

官方管理端界面（参考截图）

以下截图为 nuxt-admin-layer 自带的官方管理界面。您的 apps/admin 通过 extends 引用该层；业务定制请在应用内新增或覆盖页面，不要直接改 layer 包内文件。

工作台与项目

AI 与网关

运维与观测

操作员（RBAC）

用户与访问

支持与计费

内容与存储

另见

• 管理后台 RBAC 与操作员
• 开发技能（含 create-admin）