wwjcloud-nest-v1/.trae/documents/迁移 Java Admin 至 admin-vben（基于 Vben 框架）.md

目标

• 将 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 与验收、部署脚本更新。