# 迁移总体方案

## 目标与约束
- 目标：将 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/性能验收与灰度上线