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