chore(release): unify to wwjcloud across backend/frontend; routes, DTO/VO paths, docs/links; remove niucloud; naming fixes

2025-11-13 19:26:41 +08:00
parent 5c1647df7c
commit 3163f56894
1192 changed files with 89154 additions and 9118 deletions
--- a/框架（严格对齐前端与数据库）.md
+++ b/框架（严格对齐前端与数据库）.md
@@ -0,0 +1,84 @@
+# 迁移总体方案
+
+## 目标与约束
+- 目标：将 Java 后端的全部业务功能按域迁移到 v1（NestJS 11），保持前端与数据库完全兼容。
+- 约束：业务逻辑以 PHP 项目为唯一权威（接口与流程 100% 一致），数据库结构与字段 100% 一致，不使用默认值，不硬编码业务数据。
+- 成果：路由、请求/响应结构、鉴权与多租户（site_id）、数据库读写、副作用行为与 Java/PHP 保持一致；可直接替换现有前端。
+
+## 基线核验（准备阶段）
+- 收集权威数据源：引入 `./sql/wwjcloud.sql`、PHP 控制器/服务/验证器源码到规定目录，作为业务对齐基线。
+- 前端路径清单：以现有前端使用的路由表为对齐目标（如 `/adminapi/*`、`/api/*`）。
+- Java 端点盘点：按域输出 Java 的 Controller/Service 端点与签名（包括 `adminapi` 与 `api`）。
+- 响应结构基线：统一使用响应包装（code/msg_key/msg/data/timestamp），确认与 Java/PHP 一致。
+
+## 框架装配（Boot 层与全局能力）
+- 全局预设：启用平台预设（APP_GUARD/APP_INTERCEPTOR/APP_FILTER/APP_PIPE），统一鉴权、RBAC、限流、日志、指标、响应包装、异常处理。
+- 配置校验：通过 Joi 校验环境变量；禁止默认值；数据库/Redis/队列等由环境配置驱动。
+- 多租户：基于 `site_id` 的租户解析策略（header/subdomain/path 配置化），为所有域服务提供 `RequestContext`。
+
+## 迁移方法论（按业务域逐步迁移）
+- 迁移单位：以业务域为单位，域内完整分层（Controller → Service → Repository → Entity → DTO/Validator）。
+- 路由前缀：严格沿用 Java/PHP 路由前缀与路径（`/adminapi/**`、`/api/**`）。
+- 服务方法：方法名与行为与 Java/PHP 保持一致；数据库读写操作与事务、缓存、副作用一致。
+- 实体与仓储：TypeORM Entity 映射严格遵循数据库表与字段命名；禁用 `synchronize`；使用 `InjectRepository`。
+- 验证与管道：按 PHP 验证器规则实现 DTO 验证；不引入默认值与推测。
+
+## 域级迁移清单（先核心后外围）
+1. sys（系统配置/菜单/区域/附件/打印/调度/协议/海报）
+- 控制器路由与方法对齐；配置读取与 JSON 解析与 Java/PHP 一致；附件与导出使用同结构。
+- 打印与调度：品牌枚举、调度配置与任务执行链路迁移。
+
+2. site（站点/分组/账户日志/用户）
+- 站点信息聚合（apps/addons）与分组策略读取；严格使用 `site_id` 上下文；前端 API 路由保持不变。
+
+3. member（会员/等级/标签/地址/账户日志/签到/提现）
+- 账户与日志写入、签到积分、提现流程与状态机对齐；路由与参数一致。
+
+4. pay（支付/退款/转账/渠道）
+- `/api/pay/notify/{site_id}/{channel}/{type}/{action}` 任意方法映射；支付场景与渠道配置读取；异步通知与签名验签。
+
+5. upload/storage（上传/存储）
+- 文件上传（图片/视频/抓取/Base64/缩略图）与存储通道配置；返回结构与 Java/PHP 相同。
+
+6. wechat/weapp/wxoplatform（公众号/小程序/开放平台）
+- 登录/注册/用户信息/同步/JSSDK 配置；模板与菜单管理；开放平台版本与配置。
+
+7. diy/diy_form（搭建/路由/主题/表单）
+- 页面/路由/主题 CRUD，表单配置与数据写入；与前端路由保持兼容。
+
+8. addon（插件）
+- 插件安装/升级/备份/日志；插件开发接口与站点插件初始化记录。
+
+9. notice/sms（通知/短信）
+- 通知模板/记录与短信通道；供应商适配与发送策略，失败重试与限流。
+
+10. channel（多端渠道 app/h5/pc）
+- 渠道配置与前端适配；应用列表输出与路由映射。
+
+11. auth/login（登录/验证码/配置）
+- 管理端登录、验证码获取与校验、登录配置读取；JWT 与 RBAC 对齐。
+
+12. verify（核销）
+- 核销员与核销记录；权限与租户处理一致。
+
+## 交叉关注点实现
+- 事务一致性：按 Java/PHP 的事务边界实现；批处理与并发控制一致。
+- 缓存与失效：对齐 Java/PHP 的缓存键与失效策略；禁止缓存默认值推测。
+- 文件与外部依赖：上传与第三方存储/SMS/支付/微信客户端使用统一适配层并开启熔断/重试。
+- 性能与指标：关键路径埋点与指标输出；限流与隔离策略。
+
+## 验证与验收
+- 路由契约测试：基于前端使用的 API 路径逐端点对比 Java/PHP 响应（结构与语义）。
+- 数据一致性：对常用读写场景进行数据库断言；索引与软删除字段核验。
+- e2e 测试：覆盖主流程（登录、站点、会员、支付、上传、微信）与管理端关键路径。
+- 性能基线：k6 压测对比 Java 后端 QPS 与 P99，并优化热点路径。
+
+## 发布与回滚
+- 灰度发布：双后端并行（只读验证），切换 API 基地址至 v1；观察指标与日志。
+- 回滚预案：切回 Java/PHP 后端的入口地址；避免数据库结构变更。
+
+## 里程碑
+- M1：基线核验（SQL/PHP/Java 端点清单）
+- M2：sys/site/member/pay/上传 模块对齐
+- M3：wechat/weapp/wxoplatform/diy/addon/notice/channel/auth/verify 对齐
+- M4：契约/e2e/性能验收与灰度上线
--- a/权威的迁移与校验计划.md
+++ b/权威的迁移与校验计划.md
@@ -0,0 +1,54 @@
+## 对齐原则
+- 以 Java 项目为唯一权威：路由、参数、响应结构、状态码、事务、副作用严格一致
+- 数据一致：TypeORM 实体字段与现有数据库一致，不修改表名/字段/索引；禁用 schema 同步
+- 禁止占位与过度设计：每次改动先查阅 Java 对应文件并逐行迁移
+
+## 执行方法
+- 逐接口迁移：按域分组（adminapi/api），为每个接口建立 Java→Nest 对照清单（Controller→Service→DTO→Entity）
+- DTO/VO 严格对齐：以 Java 方法签名与校验逻辑为准，生成/修正 NestJS DTO/VO；响应包装与国际化保持一致
+- 事务与副作用：迁移 Java 事务边界、队列事件、副作用写入（日志、统计、缓存失效），保证一致性
+- TypeORM 使用规范：统一 `findOne({where})`、非空分支更新、QueryBuilder 替代不支持用法；实体映射严格按库字段
+
+## 模块迁移顺序
+1. sys（配置/菜单/区域/附件/协议/打印/调度）：优先修复公共基础契约
+2. site（站点/分组/账户日志/用户）：统一 `site_id` 上下文
+3. member（会员/等级/标签/地址/账户日志/签到/提现）：对齐状态机与事务
+4. pay（支付/退款/转账/渠道）：通知路由与签名校验一致
+5. upload（上传/存储）：各模型与通道配置
+6. wechat/weapp（公众号/小程序）：回调入口、登录/注册/JSSDK、扫码登录
+7. diy/diy_form：页面/表单配置与数据
+8. addon（插件）：安装/升级/备份/日志
+9. notice/sms：模板/记录与驱动加载
+10. channel（多端）：渠道配置与场景域名
+11. auth/verify：登录/验证码/核销
+
+## 数据一致性策略
+- 实体与库字段对齐：字段名、类型、索引一致；不新增/修改库结构
+- 禁用 `synchronize`；迁移仅在代码层面实现，不触碰数据库结构
+- 所有 JSON 配置按 Java 的序列化/反序列化格式处理（大小写/驼峰与存储保持一致）
+
+## 工具归一与清理
+- 公共工具统一在 boot 层 `vendor/utils`；core 层仅保留域专用（如 `request-utils`、`json-module-loader`）
+- 扫描并替换 core/common/utils 的公共工具引用为 `@wwjBoot`，完成后删除重复文件
+- 严格避免双份实现与临时占位，逐文件对齐 Java 行为
+
+## 契约与测试
+- 路由契约测试：基于前端路由与 Java 控制器，逐端点比对请求/响应结构与状态码
+- 事务与副作用测试：覆盖写入、事件、缓存失效与日志记录
+- e2e 测试：登录、站点、会员、支付、上传、微信路径全链路；构建 k6 冒烟脚本
+- 错误码与异常消息：与 Java 一致（包括 message 与 code）
+
+## 构建与 Docker 自测
+- 编译零错误后，构建 Docker 镜像与 compose（API+MySQL+Redis）；前端 `.env.production` 指向后端服务地址
+- 冒烟：关键端点 200/401/400/500 行为与 Java 一致；记录性能与错误日志
+
+## 里程碑与时间表
+- D1：工具替换与目录清理（完成 100% 引用替换与重复文件删除）；修复 sys/site 的契约与编译
+- D2：member/pay/upload/wechat/weapp 的接口与事务对齐；完成编译零错误与 Docker 冒烟
+- D3：diy/addon/notice/channel/auth/verify 的契约测试与边缘场景修复；输出最终差异报告与自测结果
+
+## 交付物
+- 对照清单（Java→Nest）与迁移日志
+- 编译通过的代码、契约与 e2e 测试报告
+- Docker 自测结果与前端无改动运行说明
+- 重复与废弃文件的清理清单（实际删除记录）
--- a/.trae/documents/批次二修复计划：编译零错误与Java接口全面对齐.md
+++ b/.trae/documents/批次二修复计划：编译零错误与Java接口全面对齐.md
@@ -0,0 +1,53 @@
+## 目标
+- 修复现存编译错误，确保所有接口与 Java 行为完全一致
+- 保持 TypeORM 实体字段与数据库一致；不改表结构/索引
+- 完成工具归一替换并删除重复文件，目录保持干净
+
+## 待修复清单（按模块）
+### DIY 模块
+- 枚举迁移：从 Java 复制 `TemplateEnum`、`PagesEnum` 到 `libs/wwjcloud-core/src/enums/`
+- DTO 属性风格统一：将 `DiyInfoParam/DiyTabbarParam/DiyTabbarListParam/DiyShareParam` 的 `siteId()/memberId()` 改为属性访问，字段与 Java 对齐
+- 日志打印：将 `JsonUtils.stringify(...)` 改为 `JSON.stringify(...)`（或在工具中补齐 `stringify`，参考 Java 的 JSON 输出位置）
+- 返回包装：统一使用项目已有返回构造，替换不匹配的 `Result<T>(...)` 构造
+
+### 登录与渠道（auth/login/channel）
+- 注入与导入修正：补充 `Site` 实体与 `CoreSiteServiceImpl/CoreH5ServiceImpl/CorePcServiceImpl` 的注入与导入
+- 枚举迁移：复制 Java 的 `SiteStatusEnum/ChannelEnum` 到 `enums/` 并按值一致
+- DTO 字段：`MemberInfoParam` 使用属性风格 `memberId/siteId`
+
+### 会员模块（member）
+- `memberId` 非空校验：在提现、地址、信息修改、签到等接口赋值/查询前统一校验未登录；抛出与 Java 一致的错误消息
+- 空值更新路径：所有 `update/save` 的入参做严格非空判定，避免 `null` 传入（对齐 Java 空分支逻辑）
+- JSON 校验：替代 `JsonUtils.isJson` 为安全解析或在工具内按 Java 行为实现
+
+### 验证与核销（captcha/verify）
+- Captcha 工具已兼容 `ResponseModel` 字段；对调用方统一读取 `isSuccess/repData/repMsg`，移除不兼容字段
+- Verify 查询：`SysVerifyRecordsParam` 属性访问统一；移除 `take: 1`；补充 `createVerifyCode` 相关的 `memberId` 非空校验
+
+### TypeORM 用法与空值
+- 全仓移除 `findOne({ take: 1 })`，统一 `findOne({ where })` 或 QueryBuilder
+- 所有可能为 `null` 的对象在更新前进行非空收窄；与 Java 分支一致的抛错或新建/返回逻辑
+
+### 工具归一与清理
+- 将剩余约 16 处 `core/common/utils` 引用替换为 `@wwjBoot/vendor/utils`（qrcode/collect/distance/ip/tree/language/wechat/notice）
+- 删除重复工具文件：`core/common/utils/system-utils.ts`、`core/common/utils/captcha-utils.ts` 及其他迁移后的公共工具
+- 保留域专用：`request-utils.ts`、`json/json-module-loader.ts`
+
+## 对齐依据（Java 源文件）
+- 公众号/小程序 Serve：`ServeController.java`、`ServeServiceImpl.java`
+- jscode2session/手机号：`WeappServiceImpl.java`（login/register 流程）
+- 验证码：`CoreCaptchaImgServiceImpl.java`（ResponseModel 字段读取）
+- 短信驱动：`SmsLoader.java`、`BaseSms.java`（forName 驱动加载）
+- 插件安装列表 VO：`InstallAddonListVo.java`（icon/cover/supportApp 等字段）
+- DIY 表单配置：`CoreDiyFormConfigServiceImpl.java`（编辑/提交配置与空值逻辑）
+
+## 验证与交付
+- 编译：确保零错误
+- 契约：逐端点比对 Java 响应结构与状态码；事务与副作用对齐（日志/缓存失效/事件）
+- Docker：构建 API+MySQL+Redis，前端 `.env.production` 指向后端；执行 k6 冒烟与路由契约测试
+- 清理：输出已删除与替换清单，确认目录干净
+
+## 时间表
+- D1：完成工具替换与重复文件删除；修复 DIY/登录 的编译与契约
+- D2：修复会员/验证/TypeORM 用法与空值路径；完成编译零错误与 Docker 冒烟
+- 并行：枚举/DTO 迁移与接口对齐同步进行，压缩至 1.5–2 天
--- a/.trae/documents/迁移
+++ b/.trae/documents/迁移
@@ -0,0 +1,71 @@
+## 目标
+- 将 `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 与验收、部署脚本更新。
--- a/.trae/documents/迁移
+++ b/.trae/documents/迁移
@@ -0,0 +1,75 @@
+## 范围与目标
+- 将 `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 打包流水线。