wwjcloud-nest-v1/.trae/documents/迁移 java_uni-app 到 v1 并升级为 uniapp-x.md

范围与目标

• 将 niucloud-java/uni-app 迁移至 wwjcloud-nest-v1 框架内（目标目录：wwjcloud-nest-v1/wwjcloud-web 下新建子项目）。
• 升级至 uniapp-x，满足鸿蒙/安卓/iOS 原生编译，同时保持现有目录结构与风格的平滑迁移。
• 严格遵守 uniapp-x 规范：组件原生渲染（建议 *.uvue ）、配置文件规范、平台构建流程。

现状盘点（已完成）

• 源项目：/niucloud-java/uni-app（Vue3+Vite CLI，含 manifest.json, pages.json, App.vue, main.js, uni.scss, vite.config.ts，src/pages, src/app/pages, src/components, src/app/components/diy, src/stores, src/locale）。
• v1 框架：/wwjcloud-nest-v1/wwjcloud-web（已存在发布目录），/wwjcloud-nest-v1/admin（Vue3+Vite）。
• 关键依赖：@dcloudio/vite-plugin-uni，pinia，vue-i18n，uview-plus，windicss 等。

目标目录布局（保持风格与路径映射）

• 在 wwjcloud-nest-v1/wwjcloud-web 下创建 uniapp-x/
  • 根级：App.uvue、main.ts、manifest.json、pages.json、uni.scss
  • 源码：
    • src/app/pages/**（保留）
    • src/pages/**（保留）
    • src/components/**（保留）
    • src/app/components/diy/**（保留）
    • src/stores/**（pinia 保留）
    • src/locale/**（国际化保留）
    • src/utils/**、src/assets/**（按需迁移）
  • 构建：vite.config.ts（升级 x 兼容）、package.json（新增 x 构建脚本与依赖）

迁移步骤

1. 初始化 uniapp-x 基座
   • 采用官方 x 模板初始化项目骨架（Vite 驱动，启用原生渲染），并放置至 wwjcloud-web/uniapp-x。
   • 配置 manifest.json（含 vueVersion: 3、原生渲染开关、应用标识、权限），pages.json（保留现有路由结构与 tabbar 定义）。
2. 配置与构建升级
   • 升级 @dcloudio/vite-plugin-uni 至 x 支持版本；新增/替换 x 通道相关依赖（如需 uni-app-x 套件）。
   • package.json 增加脚本：dev:h5、dev:app-x、build:h5、build:app-x(harmony/android/ios)；保留 CLI 流程，同时集成 HBuilderX 原生打包链路。
   • vite.config.ts 保留原插件（UniLayouts, WindiCSS），按平台条件启用；检查小程序专用插件在 x 场景下的兼容性。
3. 代码迁移（结构保持 + 逐步原生化）
   • 直迁阶段：复制 src/pages/**、src/app/pages/**、src/components/**、src/app/components/diy/**、src/stores/**、src/locale/**；保持路径别名（@）与导入风格。
   • 原生化阶段：优先将高频页面与全局组件改造为 *.uvue（如 tabbar、auth/login、member/index），逐批替换不兼容的 DOM/浏览器 API。
   • UI 生态适配：审查 uview-plus、uni-ui、第三方库（html2canvas, sortablejs, qrcode）；对不支持 x 的库采用：替换、条件导入或平台分支（H5 保留，app-x 原生替代）。
4. 配置文件平滑迁移
   • manifest.json：沿用源配置并补齐 x 所需字段（原生权限、平台配置）。
   • pages.json：保持页面路由与 tabbar 结构；修正路径至 x 项目根（映射 src/app/pages 与 src/pages）。
   • 样式：保留 uni.scss、windicss；验证 x 原生渲染对原子类与预处理器的支持，必要时加 platform guard。
5. 状态与国际化保留
   • pinia 模块：原样迁移，统一初始化于 main.ts；保留模块命名与使用方式。
   • vue-i18n：保留目录结构与加载策略，确保 onLaunch 期间完成语言初始化。
6. 构建与联调
   • 本地联调：dev:h5 验证功能与路由；dev:app-x 在模拟器/真机（Harmony/Android/iOS）验证原生渲染。
   • 持续迁移：按模块分批切换 *.uvue 并替换不兼容库，确保每批均可编译与运行。
7. 集成与发布
   • 与 wwjcloud-web 发布目录对齐：保留原发布产物结构，新增 x 构建产物发布路径说明（README.md 已存在目录）。
   • 提供打包指令与 CI 接入建议（H5 走 CLI，app-x 原生包走 HBuilderX/本地 CI）。

兼容性与风险清单

• 组件格式：*.vue → *.uvue 原生渲染；可分批进行，允许阶段性混用（受支持范围以官方为准）。
• 第三方库：依赖 DOM/Canvas 的库需替代或平台分支（html2canvas, sortablejs）。
• 小程序专用插件：MiniProgramTailwind 在 x 场景不适用，需条件禁用或替换。
• uni_modules：核对是否有 x 兼容版本（如 uni-popup, uni-transition, uni-scss）。

验收标准

• 目录与风格：新项目在 wwjcloud-web/uniapp-x，路径、命名、路由与国际化结构保持与原工程一致。
• 构建与运行：
  • H5 可运行，主要页面功能完整。
  • app-x 在 Harmony/Android/iOS 可编译与启动，核心页面（登录/会员/首页/TabBar）完成原生渲染。
• 依赖与配置：manifest.json、pages.json、vite.config.ts、package.json 完成 x 兼容配置。

交付物

• 迁移后的 uniapp-x 子项目（完整源码与配置）。
• 构建脚本与打包说明（含 H5 与 app-x）。
• 兼容性清单与替换方案（不可用库的处理策略）。
• 初始功能验证报告（H5 与三端真机/模拟器截图或日志）。

回滚预案

• 保留原 niucloud-java/uni-app 直至全量迁移完成；切换发布入口即可回退。
• 若某模块在 x 下阻塞，阶段性维持 H5 实现并以平台分支隔离，待替换后再切换为原生渲染。

后续工作（可选）

• 分批将剩余页面与自定义 Diy 组件原生化，并做性能调优（缓存/异步/批处理）。
• 完善 CI/CD：H5 走 Node/Vite，app-x 走 HBuilderX 打包流水线。