71 lines
5.4 KiB
Markdown
71 lines
5.4 KiB
Markdown
## 目标
|
||
- 将 `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 与验收、部署脚本更新。 |