208 lines
9.3 KiB
Plaintext
208 lines
9.3 KiB
Plaintext
---
|
||
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/`
|