75 lines
5.7 KiB
Markdown
75 lines
5.7 KiB
Markdown
## 范围与目标
|
||
- 将 `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 打包流水线。 |