## 目标
- 将 `niucloud-java/admin` 管理面板完整迁移到 `admin-vben` 项目中，采用 Vben 的工程与路由权限框架。
- 保持界面风格与交互一致（沿用现有 Element Plus 视觉与交互），功能100%对齐。
- 保持接口、数据结构与 PHP 项目一致，无业务逻辑改动。

## 现状梳理
- 源：`niucloud-java/admin/src` 已包含完整模块（`app/auth/channel/dict/diy/...`）、动态路由与权限、i18n、请求封装、存储等。
- 目标：`admin-vben` 为 Vben monorepo，框架与工具链完善；其 `src` 已具备同构的动态路由与权限实现。
  - 路由与权限：`admin-vben/src/router/index.ts` 与 `niucloud-java/admin/src/router/index.ts` 基本一致（动态菜单、守卫、首路由计算）。
  - 请求封装：`admin-vben/src/utils/request.ts` 已支持 Token、SiteId 头与错误处理。
  - 目录结构：`admin-vben/src/app/api`、`admin-vben/src/app/views` 已对齐分层，利于无损迁移。

## 迁移范围
- 代码：`src/app/views/*` 页面与组件、`src/app/api/*` API 模块、`src/stores/*`、`src/lang/*`、`src/utils/*`、`src/layout/*`、`src/app/assets/*`。
- 资源：图片、图标、样式（含 `element-plus.scss` 与全局样式）。
- 配置：环境变量（`VITE_APP_BASE_URL`、请求头 key 等）、路由免登录清单、动态菜单接入。

## 技术方案
- 框架对齐：保留现有 Element Plus 视觉；接入/复用 Vben 的工程与路由权限框架（monorepo、turbo、vitest、动态路由、store 结构）。
- 动态路由与权限：继续使用服务端菜单 -> 动态路由的模式，复用 `formatRouters/findFirstValidRoute` 与 `getAuthMenusFn` 流程。
- API 无改动：保持 `src/app/api/*.ts` 方法签名与路径不变，沿用 `request.ts` 封装与头部约定（Token、SiteId）。
- i18n 与多语言：迁移 `zh-cn/en` JSON 与 key 命名，维持页面按 `meta.view` 懒加载语言包策略。
- Store 与状态：迁移 `system/user/app/...` 模块，维持登录态、站点信息、菜单、按钮权限的读取方式。
- 资源与样式：迁移所有静态资源与主题变量；校验全局样式覆盖生效。

## 实施步骤
1. 代码清点与映射
   - 按模块列出页面与 API 清单：`app/auth/channel(dict/wechat/weapp/pc/h5/aliapp)/diy/dict/poster/setting/site/home/login/error`。
   - 盘点 `stores`、`utils`、`lang`、`layout`、`assets` 依赖关系与引用路径。
2. 基座准备（admin-vben）
   - 核对 `admin-vben` 的别名、环境变量、router 守卫、请求封装与存储接口；确认与源项目一致。
   - 校验 `NO_LOGIN_ROUTES/STATIC_ROUTES/ADMIN_ROUTE/HOME_ROUTE/SITE_ROUTE` 与懒加载视图映射（`routers.ts:105-154`）。
3. 逐模块迁移（保持路径与命名不变）
   - `src/app/api/*`：原样迁移；如已有同名文件，做差异合并，保留真实接口与入参。
   - `src/app/views/*`：原样迁移页面与子组件；统一 import 路径别名与样式引用。
   - `src/stores/modules/*`：迁移并校验与 router/权限流程一致（`user/system/app/style/tabbar/poster/diy`）。
   - `src/lang/*`：迁移中英文 JSON；保留 key 命名与页面 `meta.view` 对应关系。
   - `src/layout/*` 与 `src/app/assets/*`：迁移布局与资源，确保视觉一致。
4. 动态菜单与首路由
   - 对接 `getAuthMenusFn` 返回菜单；使用 `formatRouters` 转为 `RouteRecordRaw` 并注入。
   - 校验首路由计算与各 appType 首页跳转（`routers.ts:178-190`、`router/index.ts:111-135`）。
5. 权限与按钮规则
   - 迁移按钮权限收集 `findRules`；页面内使用一致的权限判断。
6. 配置与环境
   - 迁移/对齐 `.env.development/.env.production` 中 `VITE_APP_BASE_URL` 与请求头 key。
   - 保持 `lang`、`siteId` 的存取一致（`request.ts:31-45`）。
7. 验证与对齐
   - 路由覆盖：全量路由可访问且元信息（标题、图标、显示）一致。
   - 用例走查：核心流程（登录、站点选择、菜单加载、各频道配置、DIY/海报/字典/设置）端到端可用。
   - 语言包：切换语言后所有页面文案正确。
   - 接口对齐：对照 `niucloud-php` 控制器与 `sql/wwjcloud.sql`，确保请求路径/参数/返回结构一致。
   - 样式一致：关键页面对比像素级差异（允许小幅度但需体验一致）。
8. 文档与脚本
   - 更新启动与构建说明（dev/preview/build），保留 Docker 与 Nginx 配置适配。

## 验收标准
- 路由与页面：源项目所有页面在 `admin-vben` 中可进入且功能正常；首页与登录流程一致。
- 接口与数据：所有 API 返回正确；无 401/403/500 异常；按钮权限与菜单显示一致。
- 视觉风格：布局、配色、组件交互与源项目一致；多语言切换正常。
- 约束遵循：数据库、接口命名与 PHP 项目保持 100% 一致；无自创逻辑与硬编码。

## 风险与回滚
- 风险：路径别名差异、环境变量未对齐、组件库差异导致样式偏差、动态菜单字段变化。
- 缓解：逐模块迁移与联调；对照 PHP 代码与 SQL；提供对比脚本与可视化走查。
- 回滚：保留 `niucloud-java/admin` 原代码；迁移采用增量合并策略，可随时切回原工程。

## 里程碑
- M1：基座对齐与 2 个模块试迁（auth、site）。
- M2：频道与 DIY 全量迁移与联调。
- M3：设置/字典/海报等模块迁移完成。
- M4：QA 与验收、部署脚本更新。