## 对齐原则
- 以 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 自测结果与前端无改动运行说明
- 重复与废弃文件的清理清单（实际删除记录）