wwjcloud/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          # 模块定义
```

### **命名规范**
```typescript
// 实体类：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
```

## 🛣️ **路由设计规范**

### **路由前缀规范**
```typescript
// 前台API路由
@Controller('api/member')
export class ApiMemberController {
  // 前台用户访问的接口
}

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

### **API路径规范**
```typescript
// 前台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分组规范**
```typescript
// 前台API文档
@ApiTags('前台-会员管理')
@Controller('api/member')
export class ApiMemberController {}

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

### **认证和权限规范**

#### **基础认证规范**
```typescript
// 前台用户认证
@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控制字段显示

##### **权限装饰器规范**
```typescript
// 角色权限
@Roles('admin', 'manager')
@Controller('admin/member')

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

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

##### **权限验证流程**
```
请求到达 → 验证JWT → 检查角色 → 检查权限 → 访问资源
```

## 🔧 **服务层职责规范**

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

### **API服务层（前台API服务）**
```typescript
// 职责：前台用户相关的业务逻辑
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服务层（后台管理服务）**
```typescript
// 职责：后台管理相关的业务逻辑
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服务 → 数据库
```

### **数据隔离规范**
```typescript
// 前台用户只能访问自己的数据
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,
  });
}
```

## ❌ **错误处理规范**

### **统一错误码**
```typescript
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,
}
```

### **统一响应格式**
```typescript
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开发时必须严格遵循此规范，确保代码质量和架构一致性！**