3.5 KiB
3.5 KiB
对齐原则
- 以 Java 项目为唯一权威：路由、参数、响应结构、状态码、事务、副作用严格一致
- 数据一致：TypeORM 实体字段与现有数据库一致，不修改表名/字段/索引；禁用 schema 同步
- 禁止占位与过度设计：每次改动先查阅 Java 对应文件并逐行迁移
执行方法
- 逐接口迁移：按域分组（adminapi/api），为每个接口建立 Java→Nest 对照清单（Controller→Service→DTO→Entity）
- DTO/VO 严格对齐：以 Java 方法签名与校验逻辑为准，生成/修正 NestJS DTO/VO；响应包装与国际化保持一致
- 事务与副作用：迁移 Java 事务边界、队列事件、副作用写入（日志、统计、缓存失效），保证一致性
- TypeORM 使用规范：统一
findOne({where})、非空分支更新、QueryBuilder 替代不支持用法；实体映射严格按库字段
模块迁移顺序
- sys（配置/菜单/区域/附件/协议/打印/调度）：优先修复公共基础契约
- site（站点/分组/账户日志/用户）：统一
site_id上下文 - member（会员/等级/标签/地址/账户日志/签到/提现）：对齐状态机与事务
- pay（支付/退款/转账/渠道）：通知路由与签名校验一致
- upload（上传/存储）：各模型与通道配置
- wechat/weapp（公众号/小程序）：回调入口、登录/注册/JSSDK、扫码登录
- diy/diy_form：页面/表单配置与数据
- addon（插件）：安装/升级/备份/日志
- notice/sms：模板/记录与驱动加载
- channel（多端）：渠道配置与场景域名
- 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 自测结果与前端无改动运行说明
- 重复与废弃文件的清理清单（实际删除记录）