# 后端开发规范指南

## 一、文档概述

### 1.1 文档目的

本文档定义了 Datawhale Town 后端开发的编码规范、注释标准、业务逻辑设计原则和日志记录要求，确保代码质量、可维护性和系统稳定性。

### 1.2 适用范围

- 所有后端开发人员
- 代码审查人员
- 系统维护人员

---

## 二、注释规范

### 2.1 模块注释

每个功能模块文件必须包含模块级注释，说明模块用途、主要功能和依赖关系。

**格式要求：**

```typescript
/**
 * 玩家管理模块
 * 
 * 功能描述：
 * - 处理玩家注册、登录、信息更新等核心功能
 * - 管理玩家角色皮肤和个人资料
 * - 提供玩家数据的 CRUD 操作
 * 
 * 依赖模块：
 * - AuthService: 身份验证服务
 * - DatabaseService: 数据库操作服务
 * - LoggerService: 日志记录服务
 * 
 * @author 开发者姓名
 * @version 1.0.0
 * @since 2025-12-13
 */
```

### 2.2 类注释

每个类必须包含类级注释，说明类的职责、主要方法和使用场景。

**格式要求：**

```typescript
/**
 * 玩家服务类
 * 
 * 职责：
 * - 处理玩家相关的业务逻辑
 * - 管理玩家状态和数据
 * - 提供玩家操作的统一接口
 * 
 * 主要方法：
 * - createPlayer(): 创建新玩家
 * - updatePlayerInfo(): 更新玩家信息
 * - getPlayerById(): 根据ID获取玩家信息
 * 
 * 使用场景：
 * - 玩家注册登录流程
 * - 个人陈列室数据管理
 * - 广场玩家状态同步
 */
@Injectable()
export class PlayerService {
  // 类实现
}
```

### 2.3 方法注释

每个方法必须包含详细的方法注释，说明功能、参数、返回值、异常和业务逻辑。

**格式要求：**

```typescript
/**
 * 创建新玩家
 * 
 * 功能描述：
 * 根据邮箱创建新的玩家账户，包含基础信息初始化和默认配置设置
 * 
 * 业务逻辑：
 * 1. 验证邮箱格式和白名单
 * 2. 检查邮箱是否已存在
 * 3. 生成唯一玩家ID
 * 4. 初始化默认角色皮肤和个人信息
 * 5. 创建对应的个人陈列室
 * 6. 记录创建日志
 * 
 * @param email 玩家邮箱地址，必须符合邮箱格式且在白名单中
 * @param nickname 玩家昵称，长度3-20字符，不能包含特殊字符
 * @param avatarSkin 角色皮肤ID，必须是1-8之间的有效值
 * @returns Promise<Player> 创建成功的玩家对象
 * 
 * @throws BadRequestException 当邮箱格式错误或不在白名单中
 * @throws ConflictException 当邮箱已存在时
 * @throws InternalServerErrorException 当数据库操作失败时
 * 
 * @example
 * ```typescript
 * const player = await playerService.createPlayer(
 *   'user@datawhale.club',
 *   '数据鲸鱼',
 *   '1'
 * );
 * ```
 */
async createPlayer(
  email: string,
  nickname: string,
  avatarSkin: string
): Promise<Player> {
  // 方法实现
}
```

### 2.4 复杂业务逻辑注释

对于复杂的业务逻辑，必须添加行内注释说明每个步骤的目的和处理逻辑。

**示例：**

```typescript
async joinRoom(roomId: string, playerId: string): Promise<Room> {
  // 1. 参数验证 - 确保房间ID和玩家ID格式正确
  if (!roomId || !playerId) {
    this.logger.warn(`房间加入失败：参数无效`, { roomId, playerId });
    throw new BadRequestException('房间ID和玩家ID不能为空');
  }

  // 2. 获取房间信息 - 检查房间是否存在
  const room = await this.roomRepository.findById(roomId);
  if (!room) {
    this.logger.warn(`房间加入失败：房间不存在`, { roomId, playerId });
    throw new NotFoundException('房间不存在');
  }

  // 3. 检查房间状态 - 只有等待中的房间才能加入
  if (room.status !== RoomStatus.WAITING) {
    this.logger.warn(`房间加入失败：房间状态不允许加入`, { 
      roomId, 
      playerId, 
      currentStatus: room.status 
    });
    throw new BadRequestException('游戏已开始，无法加入房间');
  }

  // 4. 检查房间容量 - 防止超过最大人数限制
  if (room.players.length >= room.maxPlayers) {
    this.logger.warn(`房间加入失败：房间已满`, { 
      roomId, 
      playerId, 
      currentPlayers: room.players.length,
      maxPlayers: room.maxPlayers
    });
    throw new BadRequestException('房间已满');
  }

  // 5. 检查玩家是否已在房间中 - 防止重复加入
  if (room.players.includes(playerId)) {
    this.logger.info(`玩家已在房间中，跳过加入操作`, { roomId, playerId });
    return room;
  }

  // 6. 执行加入操作 - 更新房间玩家列表
  try {
    room.players.push(playerId);
    const updatedRoom = await this.roomRepository.save(room);
    
    // 7. 记录成功日志
    this.logger.info(`玩家成功加入房间`, {
      roomId,
      playerId,
      currentPlayers: updatedRoom.players.length,
      maxPlayers: updatedRoom.maxPlayers
    });

    return updatedRoom;
  } catch (error) {
    // 8. 异常处理 - 记录错误并抛出
    this.logger.error(`房间加入操作数据库错误`, {
      roomId,
      playerId,
      error: error.message,
      stack: error.stack
    });
    throw new InternalServerErrorException('房间加入失败，请稍后重试');
  }
}
```

---

## 三、业务逻辑设计原则

### 3.1 全面性原则

每个业务方法必须考虑所有可能的情况，包括正常流程、异常情况和边界条件。

**必须考虑的情况：**

| 类别 | 具体情况 | 处理方式 |
|------|---------|---------|
| **输入验证** | 参数为空、格式错误、超出范围 | 参数校验 + 异常抛出 |
| **权限检查** | 未登录、权限不足、令牌过期 | 身份验证 + 权限验证 |
| **资源状态** | 资源不存在、状态不正确、已被占用 | 状态检查 + 业务规则验证 |
| **并发控制** | 同时操作、数据竞争、锁冲突 | 事务处理 + 乐观锁/悲观锁 |
| **系统异常** | 数据库连接失败、网络超时、内存不足 | 异常捕获 + 降级处理 |
| **业务规则** | 违反业务约束、超出限制、状态冲突 | 业务规则验证 + 友好提示 |

### 3.2 防御性编程

采用防御性编程思想，对所有外部输入和依赖进行验证和保护。

**实现要求：**

```typescript
/**
 * 更新玩家信息 - 防御性编程示例
 */
async updatePlayerInfo(
  playerId: string,
  updateData: UpdatePlayerDto
): Promise<Player> {
  // 1. 输入参数防御性检查
  if (!playerId) {
    this.logger.warn('更新玩家信息失败：玩家ID为空');
    throw new BadRequestException('玩家ID不能为空');
  }

  if (!updateData || Object.keys(updateData).length === 0) {
    this.logger.warn('更新玩家信息失败：更新数据为空', { playerId });
    throw new BadRequestException('更新数据不能为空');
  }

  // 2. 数据格式验证
  if (updateData.nickname) {
    if (updateData.nickname.length < 3 || updateData.nickname.length > 20) {
      this.logger.warn('更新玩家信息失败：昵称长度不符合要求', { 
        playerId, 
        nicknameLength: updateData.nickname.length 
      });
      throw new BadRequestException('昵称长度必须在3-20字符之间');
    }
  }

  if (updateData.avatarSkin) {
    const validSkins = ['1', '2', '3', '4', '5', '6', '7', '8'];
    if (!validSkins.includes(updateData.avatarSkin)) {
      this.logger.warn('更新玩家信息失败：角色皮肤ID无效', { 
        playerId, 
        avatarSkin: updateData.avatarSkin 
      });
      throw new BadRequestException('角色皮肤ID必须在1-8之间');
    }
  }

  // 3. 玩家存在性检查
  const existingPlayer = await this.playerRepository.findById(playerId);
  if (!existingPlayer) {
    this.logger.warn('更新玩家信息失败：玩家不存在', { playerId });
    throw new NotFoundException('玩家不存在');
  }

  // 4. 昵称唯一性检查（如果更新昵称）
  if (updateData.nickname && updateData.nickname !== existingPlayer.nickname) {
    const nicknameExists = await this.playerRepository.findByNickname(updateData.nickname);
    if (nicknameExists) {
      this.logger.warn('更新玩家信息失败：昵称已存在', { 
        playerId, 
        nickname: updateData.nickname 
      });
      throw new ConflictException('昵称已被使用');
    }
  }

  // 5. 执行更新操作（使用事务保证数据一致性）
  try {
    const updatedPlayer = await this.playerRepository.update(playerId, updateData);
    
    this.logger.info('玩家信息更新成功', {
      playerId,
      updatedFields: Object.keys(updateData),
      timestamp: new Date().toISOString()
    });

    return updatedPlayer;
  } catch (error) {
    this.logger.error('更新玩家信息数据库操作失败', {
      playerId,
      updateData,
      error: error.message,
      stack: error.stack
    });
    throw new InternalServerErrorException('更新失败，请稍后重试');
  }
}
```

### 3.3 异常处理策略

建立统一的异常处理策略，确保所有异常都能被正确捕获和处理。

**异常分类和处理：**

| 异常类型 | HTTP状态码 | 处理策略 | 日志级别 |
|---------|-----------|---------|---------|
| **BadRequestException** | 400 | 参数验证失败，返回具体错误信息 | WARN |
| **UnauthorizedException** | 401 | 身份验证失败，要求重新登录 | WARN |
| **ForbiddenException** | 403 | 权限不足，拒绝访问 | WARN |
| **NotFoundException** | 404 | 资源不存在，返回友好提示 | WARN |
| **ConflictException** | 409 | 资源冲突，如重复创建 | WARN |
| **InternalServerErrorException** | 500 | 系统内部错误，记录详细日志 | ERROR |

---

## 四、日志系统使用指南

### 4.1 日志服务简介

项目使用统一的 `AppLoggerService` 提供日志记录功能，集成了 Pino 高性能日志库，支持自动敏感信息过滤和请求上下文绑定。

### 4.2 在服务中使用日志

**依赖注入：**

```typescript
import { Injectable } from '@nestjs/common';
import { AppLoggerService } from '../core/utils/logger/logger.service';

@Injectable()
export class UserService {
  constructor(
    private readonly logger: AppLoggerService
  ) {}
}
```

### 4.3 日志级别和使用场景

| 级别 | 使用场景 | 示例 |
|------|---------|------|
| **ERROR** | 系统错误、异常情况、数据库连接失败 | 数据库连接超时、第三方服务调用失败 |
| **WARN** | 业务警告、参数错误、权限不足 | 用户输入无效参数、尝试访问不存在的资源 |
| **INFO** | 重要业务操作、状态变更、关键流程 | 用户登录成功、房间创建、玩家加入广场 |
| **DEBUG** | 调试信息、详细执行流程 | 方法调用参数、中间计算结果 |
| **FATAL** | 致命错误、系统不可用 | 数据库完全不可用、关键服务宕机 |
| **TRACE** | 极细粒度调试信息 | 循环内的变量状态、算法执行步骤 |

### 4.4 标准日志格式

**推荐的日志上下文格式：**

```typescript
// 成功操作日志
this.logger.info('操作描述', {
  operation: '操作类型',
  userId: '用户ID',
  resourceId: '资源ID',
  params: '关键参数',
  result: '操作结果',
  duration: '执行时间(ms)',
  timestamp: new Date().toISOString()
});

// 警告日志
this.logger.warn('警告描述', {
  operation: '操作类型',
  userId: '用户ID',
  reason: '警告原因',
  params: '相关参数',
  timestamp: new Date().toISOString()
});

// 错误日志
this.logger.error('错误描述', {
  operation: '操作类型',
  userId: '用户ID',
  error: error.message,
  params: '相关参数',
  timestamp: new Date().toISOString()
}, error.stack);
```

### 4.5 请求上下文绑定

**在 Controller 中使用：**

```typescript
@Controller('users')
export class UserController {
  constructor(private readonly logger: AppLoggerService) {}

  @Get(':id')
  async getUser(@Param('id') id: string, @Req() req: Request) {
    // 绑定请求上下文
    const requestLogger = this.logger.bindRequest(req, 'UserController');
    
    requestLogger.info('开始获取用户信息', { userId: id });
    
    try {
      const user = await this.userService.findById(id);
      requestLogger.info('用户信息获取成功', { userId: id });
      return user;
    } catch (error) {
      requestLogger.error('用户信息获取失败', error.stack, { 
        userId: id, 
        reason: error.message 
      });
      throw error;
    }
  }
}
```

### 4.6 业务方法日志记录最佳实践

**完整的业务方法日志记录示例：**

```typescript
async createPlayer(email: string, nickname: string): Promise<Player> {
  const startTime = Date.now();
  
  this.logger.info('开始创建玩家', {
    operation: 'createPlayer',
    email,
    nickname,
    timestamp: new Date().toISOString()
  });

  try {
    // 1. 参数验证
    if (!email || !nickname) {
      this.logger.warn('创建玩家失败：参数无效', {
        operation: 'createPlayer',
        email,
        nickname,
        reason: 'invalid_parameters'
      });
      throw new BadRequestException('邮箱和昵称不能为空');
    }

    // 2. 邮箱格式验证
    if (!this.isValidEmail(email)) {
      this.logger.warn('创建玩家失败：邮箱格式无效', {
        operation: 'createPlayer',
        email,
        nickname
      });
      throw new BadRequestException('邮箱格式不正确');
    }

    // 3. 检查邮箱是否已存在
    const existingPlayer = await this.playerRepository.findByEmail(email);
    if (existingPlayer) {
      this.logger.warn('创建玩家失败：邮箱已存在', {
        operation: 'createPlayer',
        email,
        nickname,
        existingPlayerId: existingPlayer.id
      });
      throw new ConflictException('邮箱已被使用');
    }

    // 4. 创建玩家
    const player = await this.playerRepository.create({
      email,
      nickname,
      avatarSkin: '1', // 默认皮肤
      createTime: new Date()
    });

    const duration = Date.now() - startTime;
    
    this.logger.info('玩家创建成功', {
      operation: 'createPlayer',
      playerId: player.id,
      email,
      nickname,
      duration,
      timestamp: new Date().toISOString()
    });

    return player;

  } catch (error) {
    const duration = Date.now() - startTime;
    
    if (error instanceof BadRequestException || 
        error instanceof ConflictException) {
      // 业务异常，重新抛出
      throw error;
    }

    // 系统异常，记录详细日志
    this.logger.error('创建玩家系统异常', {
      operation: 'createPlayer',
      email,
      nickname,
      error: error.message,
      duration,
      timestamp: new Date().toISOString()
    }, error.stack);

    throw new InternalServerErrorException('创建玩家失败，请稍后重试');
  }
}
```

### 4.7 必须记录日志的操作

| 操作类型 | 日志级别 | 记录内容 |
|---------|---------|---------|
| **用户认证** | INFO/WARN | 登录成功/失败、令牌生成/验证 |
| **数据变更** | INFO | 创建、更新、删除操作 |
| **权限检查** | WARN | 权限验证失败、非法访问尝试 |
| **系统异常** | ERROR | 异常堆栈、错误上下文、影响范围 |
| **性能监控** | INFO | 慢查询、高并发操作、资源使用 |
| **安全事件** | WARN/ERROR | 恶意请求、频繁操作、异常行为 |

### 4.8 敏感信息保护

日志系统会自动过滤以下敏感字段：
- `password` - 密码
- `token` - 令牌
- `secret` - 密钥
- `authorization` - 授权信息
- `cardNo` - 卡号

**注意：** 包含这些关键词的字段会被自动替换为 `[REDACTED]`

---

## 五、代码审查检查清单

### 5.1 注释检查

- [ ] 模块文件包含完整的模块级注释
- [ ] 每个类都有详细的类级注释
- [ ] 每个公共方法都有完整的方法注释
- [ ] 复杂业务逻辑有行内注释说明
- [ ] 注释内容准确，与代码实现一致

### 5.2 业务逻辑检查

- [ ] 考虑了所有可能的输入情况
- [ ] 包含完整的参数验证
- [ ] 处理了所有可能的异常情况
- [ ] 实现了适当的权限检查
- [ ] 考虑了并发和竞态条件

### 5.3 日志记录检查

- [ ] 关键业务操作都有日志记录
- [ ] 日志级别使用正确
- [ ] 日志格式符合规范
- [ ] 包含足够的上下文信息
- [ ] 敏感信息已脱敏处理

### 5.4 异常处理检查

- [ ] 所有异常都被正确捕获
- [ ] 异常类型选择合适
- [ ] 异常信息对用户友好
- [ ] 系统异常有详细的错误日志
- [ ] 不会泄露敏感的系统信息

---

## 六、最佳实践示例

### 6.1 完整的服务类示例

```typescript
/**
 * 广场管理服务
 * 
 * 功能描述：
 * - 管理中央广场的玩家状态和位置同步
 * - 处理玩家进入和离开广场的逻辑
 * - 维护广场在线玩家列表（最多50人）
 * 
 * 依赖模块：
 * - PlayerService: 玩家信息服务
 * - WebSocketGateway: WebSocket通信网关
 * - RedisService: 缓存服务
 * - LoggerService: 日志记录服务
 * 
 * @author 开发团队
 * @version 1.0.0
 * @since 2025-12-13
 */
@Injectable()
export class PlazaService {
  private readonly logger = new Logger(PlazaService.name);
  private readonly MAX_PLAYERS = 50;

  constructor(
    private readonly playerService: PlayerService,
    private readonly redisService: RedisService,
    private readonly webSocketGateway: WebSocketGateway
  ) {}

  /**
   * 玩家进入广场
   * 
   * 功能描述：
   * 处理玩家进入中央广场的逻辑，包括人数限制检查、位置分配和状态同步
   * 
   * 业务逻辑：
   * 1. 验证玩家身份和权限
   * 2. 检查广场当前人数是否超限
   * 3. 为玩家分配初始位置
   * 4. 更新Redis中的在线玩家列表
   * 5. 向其他玩家广播新玩家进入消息
   * 6. 向新玩家发送当前广场状态
   * 
   * @param playerId 玩家ID，必须是有效的已注册玩家
   * @param socketId WebSocket连接ID，用于消息推送
   * @returns Promise<PlazaPlayerInfo> 玩家在广场的信息
   * 
   * @throws UnauthorizedException 当玩家身份验证失败时
   * @throws BadRequestException 当广场人数已满时
   * @throws InternalServerErrorException 当系统操作失败时
   */
  async enterPlaza(playerId: string, socketId: string): Promise<PlazaPlayerInfo> {
    const startTime = Date.now();
    
    this.logger.info('玩家尝试进入广场', {
      operation: 'enterPlaza',
      playerId,
      socketId,
      timestamp: new Date().toISOString()
    });

    try {
      // 1. 验证玩家身份
      const player = await this.playerService.getPlayerById(playerId);
      if (!player) {
        this.logger.warn('进入广场失败：玩家不存在', {
          operation: 'enterPlaza',
          playerId,
          socketId
        });
        throw new UnauthorizedException('玩家身份验证失败');
      }

      // 2. 检查广场人数限制
      const currentPlayers = await this.redisService.scard('plaza:online_players');
      if (currentPlayers >= this.MAX_PLAYERS) {
        this.logger.warn('进入广场失败：人数已满', {
          operation: 'enterPlaza',
          playerId,
          currentPlayers,
          maxPlayers: this.MAX_PLAYERS
        });
        throw new BadRequestException('广场人数已满，请稍后再试');
      }

      // 3. 检查玩家是否已在广场中
      const isAlreadyInPlaza = await this.redisService.sismember('plaza:online_players', playerId);
      if (isAlreadyInPlaza) {
        this.logger.info('玩家已在广场中，更新连接信息', {
          operation: 'enterPlaza',
          playerId,
          socketId
        });
        
        // 更新Socket连接映射
        await this.redisService.hset('plaza:player_sockets', playerId, socketId);
        
        // 获取当前位置信息
        const existingInfo = await this.redisService.hget('plaza:player_positions', playerId);
        return JSON.parse(existingInfo);
      }

      // 4. 为玩家分配初始位置（广场中心附近随机位置）
      const initialPosition = this.generateInitialPosition();
      
      const playerInfo: PlazaPlayerInfo = {
        playerId: player.id,
        nickname: player.nickname,
        avatarSkin: player.avatarSkin,
        position: initialPosition,
        lastUpdate: new Date(),
        socketId
      };

      // 5. 更新Redis中的玩家状态
      await Promise.all([
        this.redisService.sadd('plaza:online_players', playerId),
        this.redisService.hset('plaza:player_positions', playerId, JSON.stringify(playerInfo)),
        this.redisService.hset('plaza:player_sockets', playerId, socketId),
        this.redisService.expire('plaza:player_positions', 3600), // 1小时过期
        this.redisService.expire('plaza:player_sockets', 3600)
      ]);

      // 6. 向其他玩家广播新玩家进入消息
      this.webSocketGateway.broadcastToPlaza('player_entered', {
        playerId: player.id,
        nickname: player.nickname,
        avatarSkin: player.avatarSkin,
        position: initialPosition
      }, socketId); // 排除新进入的玩家

      // 7. 向新玩家发送当前广场状态
      const allPlayers = await this.getAllPlazaPlayers();
      this.webSocketGateway.sendToPlayer(socketId, 'plaza_state', {
        players: allPlayers.filter(p => p.playerId !== playerId),
        totalPlayers: allPlayers.length
      });

      const duration = Date.now() - startTime;
      
      this.logger.info('玩家成功进入广场', {
        operation: 'enterPlaza',
        playerId,
        socketId,
        position: initialPosition,
        totalPlayers: currentPlayers + 1,
        duration,
        timestamp: new Date().toISOString()
      });

      return playerInfo;

    } catch (error) {
      const duration = Date.now() - startTime;
      
      if (error instanceof UnauthorizedException || 
          error instanceof BadRequestException) {
        throw error;
      }

      this.logger.error('玩家进入广场系统异常', {
        operation: 'enterPlaza',
        playerId,
        socketId,
        error: error.message,
        stack: error.stack,
        duration,
        timestamp: new Date().toISOString()
      });

      throw new InternalServerErrorException('进入广场失败，请稍后重试');
    }
  }

  /**
   * 生成初始位置
   * 
   * 功能描述：
   * 在广场中心附近生成随机的初始位置，避免玩家重叠
   * 
   * @returns Position 包含x、y坐标的位置对象
   * @private
   */
  private generateInitialPosition(): Position {
    // 广场中心坐标 (400, 300)，在半径100像素范围内随机分配
    const centerX = 400;
    const centerY = 300;
    const radius = 100;
    
    const angle = Math.random() * 2 * Math.PI;
    const distance = Math.random() * radius;
    
    const x = Math.round(centerX + distance * Math.cos(angle));
    const y = Math.round(centerY + distance * Math.sin(angle));
    
    return { x, y };
  }

  /**
   * 获取所有广场玩家信息
   * 
   * @returns Promise<PlazaPlayerInfo[]> 广场中所有玩家的信息列表
   * @private
   */
  private async getAllPlazaPlayers(): Promise<PlazaPlayerInfo[]> {
    try {
      const playerIds = await this.redisService.smembers('plaza:online_players');
      const playerInfos = await Promise.all(
        playerIds.map(async (playerId) => {
          const info = await this.redisService.hget('plaza:player_positions', playerId);
          return info ? JSON.parse(info) : null;
        })
      );
      
      return playerInfos.filter(info => info !== null);
    } catch (error) {
      this.logger.error('获取广场玩家列表失败', {
        operation: 'getAllPlazaPlayers',
        error: error.message
      });
      return [];
    }
  }
}
```

---

## 七、工具和配置

### 7.1 推荐的开发工具

| 工具 | 用途 | 配置说明 |
|------|------|---------|
| **ESLint** | 代码规范检查 | 配置注释规范检查规则 |
| **Prettier** | 代码格式化 | 统一代码格式 |
| **TSDoc** | 文档生成 | 从注释生成API文档 |
| **SonarQube** | 代码质量分析 | 检查代码覆盖率和复杂度 |

### 7.2 日志配置示例

```typescript
// logger.config.ts
export const loggerConfig = {
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ 
      filename: 'logs/error.log', 
      level: 'error' 
    }),
    new winston.transports.File({ 
      filename: 'logs/combined.log' 
    })
  ]
};
```

---

## 八、总结

本规范文档定义了后端开发的核心要求：

1. **完整的注释体系**：模块、类、方法三级注释，确保代码可读性
2. **全面的业务逻辑**：考虑所有可能情况，实现防御性编程
3. **规范的日志记录**：关键操作必须记录，便于问题排查和系统监控
4. **统一的异常处理**：分类处理不同类型异常，提供友好的用户体验

遵循本规范将显著提高代码质量、系统稳定性和团队协作效率。所有开发人员必须严格按照本规范进行开发，代码审查时将重点检查这些方面的实现。