# 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 {} // 更新个人资料 async updateProfile(memberId: number, data: UpdateProfileDto): Promise {} // 会员签到 async signIn(memberId: number): Promise {} } ``` ### **Admin服务层（后台管理服务）** ```typescript // 职责：后台管理相关的业务逻辑 export class AdminMemberService { constructor(private coreService: CoreMemberService) {} // 获取会员列表 async getMemberList(query: QueryMemberDto): Promise> {} // 创建会员 async createMember(data: CreateMemberDto): Promise {} // 更新会员 async updateMember(id: number, data: UpdateMemberDto): Promise {} // 删除会员 async deleteMember(id: number): Promise {} } ``` ## 🔗 **模块间依赖规范** ### **依赖注入原则** 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 { if (memberId !== currentMemberId) { throw new ForbiddenException('无权访问其他用户数据'); } return this.memberRepository.findOne({ where: { memberId } }); } // 后台管理员可以访问所有数据 async getMemberList(query: QueryMemberDto): Promise> { 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 { 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开发时必须严格遵循此规范，确保代码质量和架构一致性！**