wwjcloud-nest-v1/AI-DEVELOPMENT-GUIDE.md

WWJ Cloud AI 开发规范

本文档为AI开发WWJ Cloud项目时必须遵循的规范，确保代码质量和架构一致性

🏗️ 架构分层规范

微服务架构原则

1. 按业务领域拆分，不是按技术层级拆分
2. 每个微服务 = 一个完整的业务模块
3. 服务内部保持分层架构（Controller/Service/Entity）
4. 服务间通过接口通信，避免直接依赖

微服务迁移路径

• 阶段1：模块化重构（当前）
• 阶段2：服务边界定义
• 阶段3：微服务拆分部署

目录结构规范

wwjcloud/src/common/{module}/
├── entities/                    # 实体层（数据模型）
│   ├── {Entity}.ts            # 主实体
│   └── {SubEntity}.ts         # 子实体
├── services/                    # 服务层
│   ├── core/                   # 核心业务逻辑（共用）
│   │   └── Core{Entity}Service.ts
│   ├── api/                    # 前台API服务
│   │   └── {Entity}Service.ts
│   └── admin/                  # 后台管理服务
│       └── {Entity}Service.ts
├── controllers/                 # 控制器层
│   ├── api/                    # 前台API控制器
│   │   └── {Entity}Controller.ts
│   └── admin/                  # 后台管理控制器
│       └── {Entity}Controller.ts
├── dto/                        # 数据传输对象
│   ├── api/                    # 前台API DTO
│   │   ├── create-{entity}.dto.ts
│   │   └── update-{entity}.dto.ts
│   └── admin/                  # 后台管理 DTO
│       ├── create-{entity}.dto.ts
│       └── update-{entity}.dto.ts
└── {module}.module.ts          # 模块定义

命名规范

// 实体类：PascalCase
export class Member {}
export class MemberLevel {}

// 服务类：PascalCase + Service
export class CoreMemberService {}
export class MemberService {}
export class AdminMemberService {}

// 控制器类：PascalCase + Controller
export class ApiMemberController {}
export class AdminMemberController {}

// 文件名：kebab-case
// member.service.ts
// member.controller.ts

🛣️ 路由设计规范

路由前缀规范

// 前台API路由
@Controller('api/member')
export class ApiMemberController {
  // 前台用户访问的接口
}

// 后台管理路由
@Controller('admin/member')
export class AdminMemberController {
  // 后台管理员访问的接口
}

API路径规范

// 前台API路径
GET    /api/member/profile          # 获取个人资料
PUT    /api/member/profile          # 更新个人资料
POST   /api/member/sign             # 会员签到
GET    /api/member/orders           # 获取订单列表

// 后台管理路径
GET    /admin/member                # 获取会员列表
POST   /admin/member                # 创建会员
GET    /admin/member/:id            # 获取会员详情
PUT    /admin/member/:id            # 更新会员
DELETE /admin/member/:id            # 删除会员

📚 OpenAPI 文档规范

API分组规范

// 前台API文档
@ApiTags('前台-会员管理')
@Controller('api/member')
export class ApiMemberController {}

// 后台管理文档
@ApiTags('后台-会员管理')
@Controller('admin/member')
export class AdminMemberController {}

认证和权限规范

基础认证规范

// 前台用户认证
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
@Controller('api/member')

// 后台管理员认证
@UseGuards(JwtAuthGuard, AdminGuard)
@ApiBearerAuth()
@Controller('admin/member')

// 公开接口
@Public()
@Controller('api/member')

RBAC权限控制规范

权限模型设计

用户(User) → 角色(Role) → 权限(Permission) → 资源(Resource)

权限控制层次

1. 接口级权限：通过Guard控制API访问
2. 数据级权限：通过Service控制数据访问
3. 字段级权限：通过DTO控制字段显示

权限装饰器规范

// 角色权限
@Roles('admin', 'manager')
@Controller('admin/member')

// 权限点
@Permissions('member:create', 'member:update')
@Post('member')

// 数据权限
@DataScope('site_id')
async getMemberList() {}

权限验证流程

请求到达 → 验证JWT → 检查角色 → 检查权限 → 访问资源

🔧 服务层职责规范

Core服务层（核心业务逻辑）

// 职责：纯业务逻辑，不涉及HTTP请求
export class CoreMemberService {
  // 会员等级计算
  calculateMemberLevel(points: number): MemberLevel {}
  
  // 会员积分计算
  calculateMemberPoints(actions: MemberAction[]): number {}
  
  // 会员状态验证
  validateMemberStatus(member: Member): boolean {}
}

API服务层（前台API服务）

// 职责：前台用户相关的业务逻辑
export class MemberService {
  constructor(private coreService: CoreMemberService) {}
  
  // 获取个人资料
  async getProfile(memberId: number): Promise<MemberProfile> {}
  
  // 更新个人资料
  async updateProfile(memberId: number, data: UpdateProfileDto): Promise<MemberProfile> {}
  
  // 会员签到
  async signIn(memberId: number): Promise<SignResult> {}
}

Admin服务层（后台管理服务）

// 职责：后台管理相关的业务逻辑
export class AdminMemberService {
  constructor(private coreService: CoreMemberService) {}
  
  // 获取会员列表
  async getMemberList(query: QueryMemberDto): Promise<PaginatedResult<Member>> {}
  
  // 创建会员
  async createMember(data: CreateMemberDto): Promise<Member> {}
  
  // 更新会员
  async updateMember(id: number, data: UpdateMemberDto): Promise<Member> {}
  
  // 删除会员
  async deleteMember(id: number): Promise<void> {}
}

🔗 模块间依赖规范

依赖注入原则

1. 禁止循环依赖：A模块不能依赖B模块，B模块也不能依赖A模块
2. 单向依赖：只能从上层依赖下层，不能从下层依赖上层
3. 接口隔离：通过接口定义模块间的契约

模块依赖关系

Auth模块 ← Admin模块 ← RBAC模块
  ↓           ↓         ↓
Core模块 ← Common模块 ← 其他模块

共享服务规范

• Core服务：可以被多个模块共享
• Common服务：提供通用功能（如工具类、常量等）
• 避免跨模块直接调用：通过接口或事件通信

🔄 数据流规范

前台用户数据流

前台用户 → API控制器 → API服务 → Core服务 → 数据库

后台管理数据流

后台管理员 → Admin控制器 → Admin服务 → Core服务 → 数据库

数据隔离规范

// 前台用户只能访问自己的数据
async getProfile(memberId: number, currentMemberId: number): Promise<MemberProfile> {
  if (memberId !== currentMemberId) {
    throw new ForbiddenException('无权访问其他用户数据');
  }
  return this.memberRepository.findOne({ where: { memberId } });
}

// 后台管理员可以访问所有数据
async getMemberList(query: QueryMemberDto): Promise<PaginatedResult<Member>> {
  return this.memberRepository.findAndCount({
    where: query,
    skip: (query.page - 1) * query.limit,
    take: query.limit,
  });
}

❌ 错误处理规范

统一错误码

export enum ErrorCode {
  // 通用错误
  SUCCESS = 200,
  BAD_REQUEST = 400,
  UNAUTHORIZED = 401,
  FORBIDDEN = 403,
  NOT_FOUND = 404,
  
  // 业务错误
  MEMBER_NOT_FOUND = 1001,
  MEMBER_ALREADY_EXISTS = 1002,
  INSUFFICIENT_PERMISSIONS = 1003,
}

统一响应格式

export interface ApiResponse<T = any> {
  code: number;
  message: string;
  data: T;
  timestamp: string;
  path: string;
}

🚀 开发流程规范

第一步：创建实体

1. 根据数据库表结构创建实体类
2. 确保字段名与数据库一致
3. 添加必要的装饰器和验证

第二步：创建Core服务

1. 实现纯业务逻辑
2. 不涉及HTTP请求和响应
3. 可被其他服务复用

第三步：创建API服务

1. 实现前台用户相关逻辑
2. 调用Core服务
3. 处理前台特定的业务需求
4. 必须完整实现所有业务逻辑，禁止TODO和Mock

第四步：创建Admin服务

1. 实现后台管理相关逻辑
2. 调用Core服务
3. 处理后台管理需求
4. 必须完整实现所有业务逻辑，禁止TODO和Mock

第五步：创建控制器

1. 实现HTTP接口
2. 调用对应的服务
3. 处理请求和响应

第六步：配置模块

1. 导入所有依赖
2. 配置提供者和控制器
3. 导出必要的服务

第七步：代码审查

1. 检查是否还有TODO标记
2. 检查是否还有Mock数据
3. 检查是否还有空实现
4. 确保所有业务逻辑完整

📋 必须遵循的规则

1. 数据库字段一致性

• 所有实体字段名必须与 sql/wwjcloud.sql 中的表结构完全一致
• 使用 @Column({ name: 'field_name' }) 确保字段映射正确

2. 多租户支持

• 所有业务表必须包含 site_id 字段
• 独立版模式 site_id = 0
• SaaS模式 site_id > 0

3. 认证和权限

• 前台API使用 JwtAuthGuard
• 后台API使用 JwtAuthGuard + AdminGuard
• 公开接口使用 @Public() 装饰器

4. 错误处理

• 使用统一的错误码和响应格式
• 前台用户只能访问自己的数据
• 后台管理员可以访问所有数据

5. 代码质量

• 遵循TypeScript严格模式
• 使用ESLint和Prettier规范
• 编写完整的JSDoc注释
• 实现单元测试

6. 业务逻辑完整性

• 禁止TODO标记：所有方法必须完整实现
• 禁止Mock数据：必须使用真实数据库数据
• 禁止空实现：所有方法必须包含完整业务逻辑
• 禁止硬编码：配置值必须从配置文件读取

⚠️ 禁止事项

1. 禁止硬编码：所有配置值必须从配置文件或环境变量读取
2. 禁止Mock数据：生产环境必须使用真实数据库，禁止返回硬编码的测试数据
3. 禁止TODO标记：所有业务逻辑必须完整实现，不允许留下TODO注释
4. 禁止混合职责：每个服务层必须职责单一
5. 禁止跳过验证：所有输入必须进行验证
6. 禁止忽略错误：必须正确处理所有异常情况
7. 禁止空实现：所有方法必须包含完整的业务逻辑实现

---

注意：AI开发时必须严格遵循此规范，确保代码质量和架构一致性！