wwjcloud-nest-v1/.cursor/rules/ai.mdc

---
description: Java后端迁移到v1框架的智能体工作流程规则
globs: 
alwaysApply: true
---
## 智能体工作流程（多智能体协作 - Java迁移版）

### 角色定义（按执行顺序标注）
- S1 需求分析体(Analyzer): 解析Java项目结构、建立元数据索引、输出Java→NestJS映射关系
- S2 架构治理体(Architect): 校验分层/依赖/目录规范，确保与Java架构对齐
- S3 基建接入体(InfraOperator): 接入/校验 Kafka、Redis、队列、事务与配置，提供接入差异与示例
- S4 开发执行体(Developer): 使用迁移工具生成代码，按Java逻辑对齐业务实现
- S5 安全基线体(SecurityGuard): 检查守卫、跨租户(site_id)隔离、敏感信息暴露（开发中与提测前各执行一次）
- S6 质量门禁体(QualityGate): 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
- S7 规范审计体(Auditor): 按Java迁移清单逐项核查，确保与Java版本100%一致
- S8 上线管控体(Release): 构建、变更说明、灰度计划与回滚预案
- S9 性能优化体(PerfTuner): 建议缓存/异步化/批处理，识别大对象传输与 N+1（开发后期与上线后持续执行）

### 串联流程（带顺序）

1) S1 Analyzer (Java迁移版)
- 输入: Java项目扫描结果、业务逻辑对齐需求
- 输出: Java→NestJS映射关系、方法签名对比、依赖关系分析
- 执行: 
  - 运行迁移工具 `tools/java-to-nestjs-migration/migration-coordinator.js` 扫描Java项目
  - 构建中央数据仓库（CDR）：Service方法签名索引、DTO类型映射、实体映射关系
  - 生成映射报告：Java文件→NestJS文件映射表、方法签名对比表、依赖关系分析报告

2) S2 Architect
- 校验: 模块目录、分层结构、依赖方向（确保与Java架构对齐）
- 输出: 设计说明、端口(Repository/Provider)定义、删除/迁移建议
- 重点: 确保动态模块加载机制正确（EntityModule.register()、ServiceModule.register()、ControllerModule.register()）

3) S3 InfraOperator
- 接入: Kafka/Redis/队列/事务的工程化接入与配置
- 产物: 接入差异与示例代码，健康检查/配置项校验清单
- 注意: 使用v1框架能力（AuthService、CacheService、AppConfigService）

4) S4 Developer
- **Java迁移执行步骤**:
  1. 使用迁移工具生成代码骨架（Entity、DTO、Service、Controller）
  2. 按模块优先级逐个对齐Java业务逻辑（P0核心→P1基础→P2业务→P3扩展）
  3. 严格对齐方法签名、参数处理、返回值、异常处理、数据库操作
  4. 使用v1框架能力（AuthService、CacheService、AppConfigService、工具类）
  5. 禁止自创业务逻辑，必须完全按照Java实现
- 接入: 守卫(RBAC)、Pipes(JSON/Timestamp)、拦截器(请求日志)、事件与队列
- 测试: 单测/集成/e2e，构建通过

5) S5 SecurityGuard（第一次，开发阶段）
- 检查: 控制器守卫、site_id 隔离、敏感字段输出、配置权限

6) S6 QualityGate（CI 阶段）
- 指标: ESLint/TS 无报错；覆盖率≥阈值；e2e 关键路径通过
- 动作: 不达标阻断合并

7) S7 Auditor（提测前 - Java迁移版）
- **Java迁移审计检查点**:
  - 检查方法签名是否与Java完全一致
  - 检查API路径、HTTP方法、参数名是否与Java一致
  - 检查响应格式、错误码、异常消息是否与Java一致
  - 检查数据库操作是否与Java逻辑一致
  - 检查是否使用了框架能力而非自创逻辑
  - 检查表名、字段名是否与Java完全一致（禁止修改）
- 产物: 差异报告与修复任务

8) S5 SecurityGuard（第二次，提测前）
- 复检: 重要接口的鉴权/越权/敏感输出

9) S9 PerfTuner（并行/持续）
- 建议: 缓存、异步化、批量化、索引与查询优化；识别 N+1、大对象传输

10) S8 Release
- 产出: 变更日志、部署步骤、数据迁移脚本、回滚预案

### 关键约束（Java迁移）

- **核心原则**：与 Java 业务逻辑100%对齐；数据库结构100%对齐；API接口100%对齐
- **优先原则**：优先对齐Java逻辑，再优化框架特性；禁止自创业务逻辑
- **数据库约束**：禁止修改表名、字段名、字段类型、索引结构（必须与Java完全一致）
- **API约束**：路由路径、HTTP方法、参数名、响应格式、错误码必须与Java一致
- 禁止创建 DB 不存在字段；`sys_config.value(JSON)` 统一
- 管理端路由 `/adminapi`，前台 `/api`；统一守卫与响应格式

### 基础能力检查点（Kafka / Redis / 队列 / 事务)

- 事务: 仅在 Application 开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
- 队列: 用例完成后入队；载荷仅传关键 ID；处理器在 Infrastructure；按队列名分域
- 事件: 统一用 DomainEventService；事件名 `domain.aggregate.action`；默认 DB Outbox，可切 Kafka
- Redis: 短缓存配置读取、上传限流/防刷（计数器）、幂等(SETNX+TTL)

### 命名与对齐（Java迁移）

- **Java业务命名优先**（不违反 Nest/TS 规范前提下），包括服务方法、DTO 字段
- **表名、字段名必须与Java完全一致**（禁止修改）
- **Service实现类命名规则**：
  - Java `ServiceImpl` → NestJS `ServiceImpl`（保持原样，不添加Service后缀）
  - Java `IService` → NestJS `Service`（接口，去掉I前缀）
- **动态模块加载**：使用 `EntityModule.register()`、`ServiceModule.register()`、`ControllerModule.register()`
- Nest 特有类型按规范命名：`*.module.ts`、`*.controller.ts`、`*.service.ts`、`*.entity.ts`、`*.dto.ts`

### 核心链接

- **Java迁移方案**: `./java-migration.mdc`（完整迁移方案和规则）
- **迁移工具**: `tools/java-to-nestjs-migration/`（迁移工具目录）
- **迁移报告**: `tools/java-to-nestjs-migration/migration-report.json`（迁移报告）

### 执行与验收（CI/PR 建议)

- PR 必须通过: build、单测/集成/e2e
- 审计体根据 `java-migration.mdc` 自动检查Java对齐情况
- 安全基线: 管理端控制器统一 `JwtAuthGuard + RolesGuard`；/adminapi 与 /api 路由前缀

### 目录职能速查（Java迁移项目 - v1框架）

#### 核心目录结构：
- **entities/**（实体层）
  - TypeORM实体文件，表名、字段名必须与Java完全一致
  - 由迁移工具自动生成，禁止手动修改表结构
  - 文件命名：`*.entity.ts`（如 `sys-user.entity.ts`）

- **dtos/**（数据传输对象层）
  - DTO/VO/Param文件，字段名、类型必须与Java一致
  - 目录结构：`dtos/admin/*/*.dto.ts`、`dtos/api/*/*.dto.ts`、`dtos/core/*/*.dto.ts`
  - 由迁移工具自动生成，需要手动对齐验证规则

- **services/**（服务层）
  - **admin/**：管理端服务（对应Java `service.admin`）
  - **api/**：前台服务（对应Java `service.api`）
  - **core/**：核心服务（对应Java `service.core`）
  - 使用动态模块加载：`ServiceModule.register()`
  - 文件命名：`*-service-impl.service.ts`（实现类）

- **controllers/**（控制器层）
  - **adminapi/**：管理端控制器（对应Java `controller.adminapi`）
  - **api/**：前台控制器（对应Java `controller.api`）
  - 使用动态模块加载：`ControllerModule.register()`
  - 文件命名：`*.controller.ts`

- **entity.module.ts、service.module.ts、controller.module.ts**
  - 动态模块文件，由迁移工具自动生成
  - 自动扫描并注册所有实体、服务、控制器
  - 必须使用 `.register()` 方法注册

- **jobs/**（定时任务层）
  - 定时任务文件，对应Java `job.*`
  - 使用 `JobProviderRegistry` 注册

- **listeners/**（监听器层）
  - 事件监听器文件，对应Java `listener.*`

- **enums/**（枚举层）
  - 枚举文件，对应Java枚举类

#### 模块优先级（对齐顺序）：

1. **P0 核心模块**：认证、权限、用户管理
   - `services/admin/auth/*`
   - `services/admin/user/*`
   - `services/admin/rbac/*`

2. **P1 基础模块**：配置、菜单、字典
   - `services/admin/sys/*`
   - `services/core/config/*`

3. **P2 业务模块**：业务功能模块
   - `services/admin/member/*`
   - `services/admin/order/*`
   - `services/admin/pay/*`

4. **P3 扩展模块**：插件、扩展功能
   - `services/admin/addon/*`

### 对齐检查清单（每个Service方法）

- [ ] **方法签名对齐**：与Java方法签名完全一致
- [ ] **参数处理对齐**：参数类型、参数名与Java一致
- [ ] **返回值对齐**：返回值类型与Java一致
- [ ] **异常处理对齐**：异常类型、异常消息与Java一致
- [ ] **数据库操作对齐**：查询逻辑与Java一致
- [ ] **事务处理对齐**：事务范围与Java一致
- [ ] **使用框架能力**：使用AuthService、CacheService等，不重复造轮子

### 迁移工具使用

```bash
# 运行迁移工具
cd tools/java-to-nestjs-migration
node migration-coordinator.js

# 输出：
# - 扫描Java项目（1215个文件）
# - 生成NestJS代码骨架
# - 生成映射报告
```

### 质量控制检查点

1. **编译通过**：`npm run build` - 无TypeScript编译错误
2. **服务启动**：`docker-compose up -d` - 所有模块正确加载
3. **API测试**：测试接口与Java版本一致
4. **数据库验证**：CRUD操作与Java一致

---

**参考文档**：
- 完整迁移方案：`./java-migration.mdc`
- 迁移工具目录：`tools/java-to-nestjs-migration/`