bim_engine/docs-old/AI代码规范模板.md

# AI 代码规范模板

> 本文档是通用的 AI 协作与代码规范模板，适用于 TypeScript、Java、React、Vue 等技术栈。
> 使用时请根据项目实际情况进行调整。

---

## 📋 目录

### 第一部分：通用规范
- [1. AI 协作基本原则](#1-ai-协作基本原则)
- [2. 通用编码规范](#2-通用编码规范)
- [3. 文件与文档管理](#3-文件与文档管理)

### 第二部分：语言特定规范
- [4. TypeScript 规范](#4-typescript-规范)
- [5. Java 规范](#5-java-规范)

### 第三部分：框架特定规范
- [6. React 规范](#6-react-规范)
- [7. Vue 规范](#7-vue-规范)

### 第四部分：工程化规范
- [8. Git 提交规范](#8-git-提交规范)
- [9. API 设计规范](#9-api-设计规范)
- [10. 测试规范](#10-测试规范)

### 附录
- [附录 A：代码审查清单](#附录-a代码审查清单)
- [附录 B：常见任务快速参考](#附录-b常见任务快速参考)
- [附录 C：模板使用说明](#附录-c模板使用说明)

---

# 第一部分：通用规范

## 1. AI 协作基本原则

### 1.1 语言要求（强制）

#### 输出语言
- **所有输出必须使用中文**，包括：
  - 代码注释（**强制：所有代码注释必须使用中文，解释清晰详细**）
  - 文档说明
  - 与用户交流
  - 错误信息和日志输出

#### 思考语言
- **思考过程也必须使用中文**：
  - 分析问题时用中文思考
  - 解释代码逻辑时用中文
  - 讨论设计方案时用中文

#### 代码中的字符串
- 根据业务需求决定（支持国际化的项目使用翻译键）
- 注释和文档必须使用中文

### 1.2 思考与沟通方式

#### 思考过程要求
- 分析问题时，用中文描述问题、分析思路、得出结论
- 解释代码时，用中文说明逻辑、设计意图、实现方式
- 讨论方案时，用中文描述优缺点、选择理由

#### 工作流程
1. **理解需求**：用中文理解用户需求，明确任务目标
2. **分析问题**：用中文分析问题，梳理相关代码和架构
3. **设计方案**：用中文设计解决方案，考虑边界情况
4. **实现代码**：编写代码，添加中文注释
5. **测试验证**：用中文描述测试结果和发现的问题
6. **更新文档**：用中文更新相关文档

### 1.3 问答与开发流程

#### 用户询问"如何实现"时的处理流程

**当用户询问如何实现某个功能时，必须遵循以下流程：**

1. **分析需求**：用中文理解用户需求，明确要实现的功能

2. **制定详细开发计划**：必须包含以下内容：
   - **需要修改的文件列表**
   - **需要新增的文件列表**
   - **需要删除的文件列表**
   - **每个文件的作用说明**
   - **对整体结构的影响**

3. **展示开发计划**：以清晰的格式展示给用户

4. **等待用户确认**：**在用户明确同意之前，绝对不能修改任何代码**

5. **用户同意后执行**：只有在用户明确表示同意后，才能开始修改代码

#### 开发计划格式模板

```markdown
## 开发计划

### 需要修改的文件
1. `src/xxx/xxx.ts`
   - 修改：添加新的 `xxxMethod()` 方法
   - 作用：提供某某功能

### 需要新增的文件
1. `src/xxx/index.ts`
   - 作用：实现某某功能
   - 内容：包含 XxxClass 类

### 需要删除的文件
1. `src/old/xxx.ts`
   - 原因：已被新组件替代
   - **处理方式**：移动到 `.recycle/YYYY-MM-DD/` 文件夹

### 对整体结构的影响
- **架构影响**：说明对现有架构的影响
- **功能影响**：说明对现有功能的影响
- **文档更新**：需要更新哪些文档
- **风险点**：可能的风险和注意事项

请确认是否按照此计划进行开发？
```

#### 用户直接要求修改时的处理

**当用户直接要求修改代码时**（如"帮我修改XXX"、"实现XXX功能"），可以：
- 直接执行代码修改
- 但仍需遵循其他规范
- 删除文件时仍需移动到回收文件夹

---

## 2. 通用编码规范

### 2.1 代码可读性

#### 基本原则
- **优先保证代码可读性**，有时可以不使用高级函数，使用低级函数
- **必须添加详细的中文注释**，解释代码逻辑和设计意图
- 函数、类、接口必须有文档注释（使用中文）
- 复杂逻辑必须添加行内注释说明

#### 代码组织
- 单个文件不宜超过 **500 行**
- 单个函数不宜超过 **50 行**
- 单行代码不宜超过 **120 字符**
- 嵌套层级不宜超过 **4 层**

### 2.2 命名规范

#### 通用命名规则

| 类型 | 命名方式 | 示例 |
|-----|---------|------|
| 类名 | 大驼峰 (PascalCase) | `UserManager`, `OrderService` |
| 接口名 | 大驼峰，可选 `I` 前缀 | `IUserService`, `UserRepository` |
| 类型/枚举 | 大驼峰 | `UserStatus`, `OrderType` |
| 函数/方法 | 小驼峰 (camelCase) | `getUserInfo`, `handleSubmit` |
| 变量 | 小驼峰 | `userName`, `isActive`, `itemCount` |
| 常量 | 全大写下划线 | `MAX_COUNT`, `API_BASE_URL` |
| 私有属性 | 下划线前缀或 `#` | `_cache`, `#privateField` |
| 文件名 | 小写短横线或小写 | `user-manager.ts`, `index.ts` |
| CSS 类名 | 小写短横线 (kebab-case) | `user-card`, `btn-primary` |

#### 命名语义化

```typescript
// ✅ 好的命名 - 语义清晰
const userList: User[] = [];
const isLoading: boolean = false;
const maxRetryCount: number = 3;
function calculateTotalPrice(items: Item[]): number { }
function validateUserInput(input: string): boolean { }

// ❌ 不好的命名 - 语义不清
const list: any[] = [];
const flag: boolean = false;
const num: number = 3;
function calc(arr: any[]): number { }
function check(str: string): boolean { }
```

#### 布尔值命名
- 使用 `is`、`has`、`can`、`should`、`will` 等前缀
- 例如：`isActive`、`hasPermission`、`canEdit`、`shouldUpdate`

#### 函数命名
- 动词开头，表明行为
- 查询：`get`、`find`、`query`、`fetch`、`load`
- 创建：`create`、`add`、`insert`、`save`
- 更新：`update`、`modify`、`set`、`change`
- 删除：`delete`、`remove`、`clear`、`reset`
- 判断：`is`、`has`、`can`、`should`、`validate`、`check`
- 转换：`to`、`convert`、`parse`、`format`
- 事件：`handle`、`on`、`trigger`、`emit`

### 2.3 注释规范

#### 文档注释（JSDoc / JavaDoc）

**TypeScript / JavaScript：**
```typescript
/**
 * 计算订单总价
 * 
 * @description 根据商品列表计算总价，包含折扣计算
 * @param items - 商品列表
 * @param discount - 折扣比例（0-1），默认为 1（无折扣）
 * @returns 计算后的总价
 * @throws {Error} 当商品列表为空时抛出错误
 * @example
 * const total = calculateTotal(items, 0.8); // 8折
 */
function calculateTotal(items: CartItem[], discount: number = 1): number {
    if (items.length === 0) {
        throw new Error('商品列表不能为空');
    }
    // 计算原价总和
    const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    // 应用折扣
    return subtotal * discount;
}
```

**Java：**
```java
/**
 * 计算订单总价
 * 
 * <p>根据商品列表计算总价，包含折扣计算</p>
 *
 * @param items 商品列表
 * @param discount 折扣比例（0-1），默认为 1（无折扣）
 * @return 计算后的总价
 * @throws IllegalArgumentException 当商品列表为空时抛出
 * @since 1.0.0
 * @author AI Assistant
 */
public BigDecimal calculateTotal(List<CartItem> items, BigDecimal discount) {
    // 实现逻辑
}
```

#### 行内注释
```typescript
// 单行注释：解释接下来一行或几行代码的作用

/*
 * 多行注释：
 * 用于解释复杂的逻辑块
 * 或临时禁用代码
 */

// TODO: 待完成的功能
// FIXME: 需要修复的问题
// HACK: 临时解决方案，需要优化
// NOTE: 重要说明
// DEPRECATED: 已废弃，请使用新方法
```

#### 注释原则
- **解释为什么，而不是是什么**：代码本身说明做什么，注释说明为什么
- **保持注释与代码同步**：代码修改后必须更新注释
- **不要注释显而易见的代码**：避免无意义的注释
- **复杂业务逻辑必须注释**：特别是涉及特定业务规则的代码

### 2.4 错误处理

#### 基本原则
- 所有异步操作必须有错误处理
- 错误信息必须清晰、有意义，使用中文
- 区分可恢复错误和不可恢复错误
- 不要吞掉异常（空 catch 块）

#### TypeScript 错误处理
```typescript
// ✅ 正确的错误处理
async function fetchUserData(userId: string): Promise<User> {
    try {
        const response = await fetch(`/api/users/${userId}`);
        
        if (!response.ok) {
            // 根据状态码抛出具体错误
            if (response.status === 404) {
                throw new Error(`用户不存在：${userId}`);
            }
            throw new Error(`请求失败：${response.status}`);
        }
        
        return await response.json();
    } catch (error) {
        // 记录错误日志
        console.error('获取用户数据失败：', error);
        // 重新抛出或返回默认值
        throw error;
    }
}

// ❌ 错误的错误处理
async function badFetch(userId: string) {
    try {
        const res = await fetch(`/api/users/${userId}`);
        return await res.json();
    } catch (e) {
        // 空 catch 块，吞掉了错误
    }
}
```

#### Java 错误处理
```java
// ✅ 正确的错误处理
public User getUserById(Long id) {
    try {
        return userRepository.findById(id)
            .orElseThrow(() -> new BusinessException("用户不存在：" + id));
    } catch (DataAccessException e) {
        log.error("查询用户失败，ID：{}", id, e);
        throw new ServiceException("数据库查询异常", e);
    }
}

// 自定义业务异常
public class BusinessException extends RuntimeException {
    private final String code;
    
    public BusinessException(String message) {
        super(message);
        this.code = "BUSINESS_ERROR";
    }
    
    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
    }
}
```

### 2.5 日志规范

#### 日志级别
| 级别 | 使用场景 |
|-----|---------|
| `ERROR` | 错误，影响功能正常运行 |
| `WARN` | 警告，潜在问题但不影响运行 |
| `INFO` | 重要业务信息，如用户操作、接口调用 |
| `DEBUG` | 调试信息，开发环境使用 |
| `TRACE` | 详细追踪信息，极少使用 |

#### 日志内容要求
```typescript
// ✅ 好的日志
logger.info(`用户登录成功，用户ID：${userId}，IP：${clientIp}`);
logger.error(`订单创建失败，订单号：${orderId}，原因：${error.message}`, error);
logger.warn(`库存不足，商品ID：${productId}，当前库存：${stock}，请求数量：${quantity}`);

// ❌ 不好的日志
logger.info('success');           // 信息不完整
logger.error(error);              // 缺少上下文
console.log('here');              // 调试代码未清理
```

#### 日志原则
- 包含足够的上下文信息（ID、参数等）
- 敏感信息脱敏（密码、手机号等）
- 生产环境不使用 `console.log`
- 异常日志要包含堆栈信息

### 2.6 安全规范

#### 输入验证
```typescript
// ✅ 验证所有外部输入
function processUserInput(input: unknown): string {
    // 类型检查
    if (typeof input !== 'string') {
        throw new Error('输入必须是字符串');
    }
    // 长度检查
    if (input.length > 1000) {
        throw new Error('输入长度超出限制');
    }
    // 内容清理
    return sanitize(input);
}
```

#### XSS 防护
```typescript
// ❌ 危险：直接插入 HTML
element.innerHTML = userInput;

// ✅ 安全：使用 textContent 或转义
element.textContent = userInput;
// 或
element.innerHTML = escapeHtml(userInput);
```

#### 敏感数据处理
```typescript
// ❌ 不要在日志中输出敏感信息
console.log(`用户密码：${password}`);

// ✅ 脱敏处理
console.log(`手机号：${phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2')}`);
```

---

## 3. 文件与文档管理

### 3.1 文件删除规范（强制）

**严禁直接删除文件，必须遵循以下流程：**

#### 步骤 1：创建回收文件夹
在项目根目录创建 `.recycle/` 文件夹（如果不存在）

#### 步骤 2：按日期组织
- 在 `.recycle/` 下按日期创建子文件夹
- 格式：`YYYY-MM-DD`（如 `2024-01-15`）
- 同一天删除的文件存放在同一个日期文件夹中

#### 步骤 3：移动文件而非删除

```bash
# ❌ 错误方式
rm src/old-file.ts

# ✅ 正确方式
DATE=$(date +%Y-%m-%d)
mkdir -p .recycle/$DATE/src
mv src/old-file.ts .recycle/$DATE/src/old-file.ts
```

#### 步骤 4：保持目录结构
在日期文件夹中保持原文件的目录结构

例如：`src/components/old.ts` → `.recycle/2024-01-15/src/components/old.ts`

#### 回收文件夹结构示例
```
.recycle/
├── 2024-01-15/
│   ├── README.md          # 可选：记录删除原因
│   └── src/
│       └── components/
│           └── old-component.ts
└── 2024-02-20/
    └── src/
        └── services/
            └── old-service.ts
```

### 3.2 文档更新规则

#### 必须更新的情况

| 操作 | 需要更新的文档 |
|-----|--------------|
| 新增文件 | 在相关文档中添加文件描述 |
| 删除文件 | 从文档中移除对应条目 |
| 修改文件功能 | 更新对应文件的描述 |
| 新增组件/模块 | 添加说明，创建详细文档 |
| 修改 API | 同步更新 API 文档 |
| 修改架构 | 更新架构设计部分 |
| 修改配置 | 更新配置说明 |

#### 更新方式
1. 修改代码后，**立即**更新相关文档
2. 确保文档与代码保持一致
3. 如果发现文档过时，优先更新文档

---

# 第二部分：语言特定规范

## 4. TypeScript 规范

### 4.1 类型定义规范

#### 优先使用 interface 定义对象类型
```typescript
// ✅ 推荐：使用 interface
interface UserInfo {
    id: string;
    name: string;
    email: string;
    age?: number;           // 可选属性
    readonly createdAt: Date; // 只读属性
}

// 接口继承
interface AdminUser extends UserInfo {
    role: 'admin';
    permissions: string[];
}
```

#### 使用 type 定义联合类型、交叉类型
```typescript
// 联合类型
type Status = 'pending' | 'processing' | 'completed' | 'failed';
type ID = string | number;

// 交叉类型
type UserWithMeta = UserInfo & {
    metadata: Record<string, unknown>;
};

// 工具类型
type PartialUser = Partial<UserInfo>;
type RequiredUser = Required<UserInfo>;
type ReadonlyUser = Readonly<UserInfo>;
type UserKeys = keyof UserInfo;
```

### 4.2 避免 any，使用正确的类型

```typescript
// ❌ 避免使用 any
function processData(data: any): any {
    return data.value;
}

// ✅ 使用 unknown + 类型守卫
function processData(data: unknown): string {
    if (typeof data === 'object' && data !== null && 'value' in data) {
        return String((data as { value: unknown }).value);
    }
    throw new Error('无效的数据格式');
}

// ✅ 使用泛型
function processData<T extends { value: string }>(data: T): string {
    return data.value;
}
```

### 4.3 泛型使用

```typescript
// 基础泛型
function identity<T>(value: T): T {
    return value;
}

// 泛型约束
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key];
}

// 泛型接口
interface Repository<T> {
    findById(id: string): Promise<T | null>;
    findAll(): Promise<T[]>;
    save(entity: T): Promise<T>;
    delete(id: string): Promise<void>;
}

// 泛型类
class BaseService<T> {
    constructor(private repository: Repository<T>) {}
    
    async getById(id: string): Promise<T | null> {
        return this.repository.findById(id);
    }
}
```

### 4.4 模块导入导出

```typescript
// ✅ 导入顺序（按此顺序组织）
// 1. Node.js 内置模块
import path from 'path';
import fs from 'fs';

// 2. 第三方库
import React from 'react';
import axios from 'axios';

// 3. 项目内部模块 - 绝对路径
import { UserService } from '@/services/user';
import { formatDate } from '@/utils/date';

// 4. 项目内部模块 - 相对路径
import { Button } from '../components/Button';
import { useAuth } from './hooks/useAuth';

// 5. 类型导入
import type { User, UserRole } from '@/types';

// 6. 样式文件
import './styles.css';
```

```typescript
// ✅ 导出方式
// 命名导出 - 推荐用于工具函数、类型等
export function formatDate(date: Date): string { }
export interface UserInfo { }
export const MAX_COUNT = 100;

// 默认导出 - 推荐用于组件、类
export default class UserService { }
export default function UserCard() { }

// 重新导出
export { UserService } from './user-service';
export * from './types';
export { default as Button } from './Button';
```

### 4.5 异步编程

```typescript
// ✅ 使用 async/await
async function fetchUserData(userId: string): Promise<User> {
    try {
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) {
            throw new Error(`HTTP error: ${response.status}`);
        }
        return await response.json();
    } catch (error) {
        console.error('获取用户数据失败：', error);
        throw error;
    }
}

// ✅ 并行请求
async function fetchMultipleUsers(ids: string[]): Promise<User[]> {
    const promises = ids.map(id => fetchUserData(id));
    return Promise.all(promises);
}

// ✅ 带超时的请求
async function fetchWithTimeout<T>(
    promise: Promise<T>,
    timeoutMs: number
): Promise<T> {
    const timeout = new Promise<never>((_, reject) => {
        setTimeout(() => reject(new Error('请求超时')), timeoutMs);
    });
    return Promise.race([promise, timeout]);
}
```

### 4.6 枚举与常量

```typescript
// ✅ 字符串枚举 - 推荐
enum OrderStatus {
    Pending = 'PENDING',
    Processing = 'PROCESSING',
    Completed = 'COMPLETED',
    Cancelled = 'CANCELLED'
}

// ✅ const 枚举 - 编译时内联
const enum Direction {
    Up = 'UP',
    Down = 'DOWN',
    Left = 'LEFT',
    Right = 'RIGHT'
}

// ✅ 常量对象 + as const - 更灵活
const HTTP_STATUS = {
    OK: 200,
    CREATED: 201,
    BAD_REQUEST: 400,
    UNAUTHORIZED: 401,
    NOT_FOUND: 404,
    INTERNAL_ERROR: 500
} as const;

type HttpStatusCode = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];
```

---

## 5. Java 规范

### 5.1 包结构与命名

#### 标准包结构
```
com.company.project
├── controller/          # 控制器层
│   └── UserController.java
├── service/             # 服务层
│   ├── UserService.java          # 接口
│   └── impl/
│       └── UserServiceImpl.java  # 实现
├── repository/          # 数据访问层
│   └── UserRepository.java
├── model/               # 数据模型
│   ├── entity/          # 数据库实体
│   │   └── User.java
│   ├── dto/             # 数据传输对象
│   │   ├── UserDTO.java
│   │   └── UserCreateRequest.java
│   └── vo/              # 视图对象
│       └── UserVO.java
├── config/              # 配置类
│   └── WebConfig.java
├── common/              # 公共模块
│   ├── exception/       # 异常类
│   ├── util/            # 工具类
│   └── constant/        # 常量类
└── Application.java     # 启动类
```

#### 类命名规范

| 类型 | 命名规则 | 示例 |
|-----|---------|------|
| 控制器 | `Xxx Controller` | `UserController` |
| 服务接口 | `XxxService` | `UserService` |
| 服务实现 | `XxxServiceImpl` | `UserServiceImpl` |
| 数据访问 | `XxxRepository` / `XxxMapper` | `UserRepository` |
| 实体类 | `Xxx` | `User`, `Order` |
| DTO | `XxxDTO` / `XxxRequest` / `XxxResponse` | `UserDTO` |
| VO | `XxxVO` | `UserVO` |
| 工具类 | `XxxUtil` / `XxxUtils` / `XxxHelper` | `DateUtils` |
| 常量类 | `XxxConstants` | `ApiConstants` |
| 枚举 | `XxxEnum` / `XxxType` / `XxxStatus` | `OrderStatus` |
| 异常 | `XxxException` | `BusinessException` |

### 5.2 类设计原则

#### 实体类
```java
/**
 * 用户实体
 * 
 * @author AI Assistant
 * @since 1.0.0
 */
@Data
@Entity
@Table(name = "t_user")
public class User implements Serializable {
    
    private static final long serialVersionUID = 1L;
    
    /**
     * 用户ID
     */
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    /**
     * 用户名
     */
    @Column(nullable = false, length = 50)
    private String username;
    
    /**
     * 邮箱
     */
    @Column(nullable = false, unique = true)
    private String email;
    
    /**
     * 状态：0-禁用，1-启用
     */
    private Integer status;
    
    /**
     * 创建时间
     */
    @CreatedDate
    private LocalDateTime createdAt;
    
    /**
     * 更新时间
     */
    @LastModifiedDate
    private LocalDateTime updatedAt;
}
```

#### 服务类
```java
/**
 * 用户服务实现
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    
    /**
     * 根据ID获取用户
     *
     * @param id 用户ID
     * @return 用户信息
     * @throws BusinessException 用户不存在时抛出
     */
    @Override
    @Transactional(readOnly = true)
    public UserVO getUserById(Long id) {
        log.info("查询用户信息，ID：{}", id);
        
        User user = userRepository.findById(id)
            .orElseThrow(() -> new BusinessException("用户不存在：" + id));
        
        return convertToVO(user);
    }
    
    /**
     * 创建用户
     *
     * @param request 创建请求
     * @return 用户ID
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long createUser(UserCreateRequest request) {
        log.info("创建用户，用户名：{}", request.getUsername());
        
        // 检查用户名是否存在
        if (userRepository.existsByUsername(request.getUsername())) {
            throw new BusinessException("用户名已存在");
        }
        
        // 创建用户实体
        User user = new User();
        user.setUsername(request.getUsername());
        user.setEmail(request.getEmail());
        user.setPassword(passwordEncoder.encode(request.getPassword()));
        user.setStatus(1);
        
        // 保存并返回ID
        User saved = userRepository.save(user);
        log.info("用户创建成功，ID：{}", saved.getId());
        
        return saved.getId();
    }
}
```

### 5.3 异常处理

#### 自定义异常体系
```java
/**
 * 基础业务异常
 */
@Getter
public class BusinessException extends RuntimeException {
    
    private final String code;
    private final String message;
    
    public BusinessException(String message) {
        super(message);
        this.code = "BUSINESS_ERROR";
        this.message = message;
    }
    
    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
        this.message = message;
    }
}

/**
 * 全局异常处理器
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    /**
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        log.warn("业务异常：{}", e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }
    
    /**
     * 处理参数校验异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.joining(", "));
        log.warn("参数校验失败：{}", message);
        return Result.fail("VALIDATION_ERROR", message);
    }
    
    /**
     * 处理未知异常
     */
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("系统异常：", e);
        return Result.fail("SYSTEM_ERROR", "系统繁忙，请稍后重试");
    }
}
```

### 5.4 Controller 规范

```java
/**
 * 用户管理接口
 */
@Slf4j
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {
    
    private final UserService userService;
    
    /**
     * 获取用户详情
     *
     * @param id 用户ID
     * @return 用户信息
     */
    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情")
    public Result<UserVO> getUser(@PathVariable Long id) {
        return Result.success(userService.getUserById(id));
    }
    
    /**
     * 获取用户列表
     *
     * @param query 查询条件
     * @return 用户列表
     */
    @GetMapping
    @Operation(summary = "获取用户列表")
    public Result<PageResult<UserVO>> listUsers(@Valid UserQuery query) {
        return Result.success(userService.listUsers(query));
    }
    
    /**
     * 创建用户
     *
     * @param request 创建请求
     * @return 用户ID
     */
    @PostMapping
    @Operation(summary = "创建用户")
    public Result<Long> createUser(@Valid @RequestBody UserCreateRequest request) {
        return Result.success(userService.createUser(request));
    }
    
    /**
     * 更新用户
     *
     * @param id 用户ID
     * @param request 更新请求
     * @return 操作结果
     */
    @PutMapping("/{id}")
    @Operation(summary = "更新用户")
    public Result<Void> updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UserUpdateRequest request) {
        userService.updateUser(id, request);
        return Result.success();
    }
    
    /**
     * 删除用户
     *
     * @param id 用户ID
     * @return 操作结果
     */
    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户")
    public Result<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return Result.success();
    }
}
```

### 5.5 统一响应格式

```java
/**
 * 统一响应结果
 *
 * @param <T> 数据类型
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> implements Serializable {
    
    private static final long serialVersionUID = 1L;
    
    /**
     * 状态码
     */
    private String code;
    
    /**
     * 消息
     */
    private String message;
    
    /**
     * 数据
     */
    private T data;
    
    /**
     * 时间戳
     */
    private long timestamp = System.currentTimeMillis();
    
    /**
     * 成功响应
     */
    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode("SUCCESS");
        result.setMessage("操作成功");
        result.setData(data);
        return result;
    }
    
    /**
     * 成功响应（无数据）
     */
    public static <T> Result<T> success() {
        return success(null);
    }
    
    /**
     * 失败响应
     */
    public static <T> Result<T> fail(String code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        return result;
    }
}
```

---

# 第三部分：框架特定规范

## 6. React 规范

### 6.1 组件设计原则

#### 函数组件 + TypeScript
```tsx
/**
 * 用户卡片组件
 * 
 * @description 展示用户基本信息的卡片组件
 */
interface UserCardProps {
    /** 用户信息 */
    user: User;
    /** 是否显示详情 */
    showDetails?: boolean;
    /** 编辑回调 */
    onEdit?: (user: User) => void;
    /** 删除回调 */
    onDelete?: (userId: string) => void;
    /** 子元素 */
    children?: React.ReactNode;
}

const UserCard: React.FC<UserCardProps> = ({
    user,
    showDetails = false,
    onEdit,
    onDelete,
    children
}) => {
    // 组件逻辑
    return (
        <div className="user-card">
            {/* 组件内容 */}
        </div>
    );
};

export default UserCard;
```

#### 组件文件结构
```
components/
└── UserCard/
    ├── index.tsx           # 组件主文件
    ├── UserCard.tsx        # 组件实现（可选，复杂组件时分离）
    ├── UserCard.module.css # 样式文件（CSS Modules）
    ├── UserCard.test.tsx   # 测试文件
    ├── types.ts            # 类型定义（复杂时分离）
    └── hooks.ts            # 组件专用 Hooks（可选）
```

### 6.2 Hooks 使用规范

#### Hooks 使用顺序
```tsx
function UserProfile({ userId }: { userId: string }) {
    // 1. useState - 状态定义
    const [user, setUser] = useState<User | null>(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState<Error | null>(null);
    
    // 2. useRef - 引用
    const containerRef = useRef<HTMLDivElement>(null);
    
    // 3. useContext - 上下文
    const { theme } = useContext(ThemeContext);
    
    // 4. 自定义 Hooks
    const { data, isLoading } = useQuery(['user', userId], fetchUser);
    
    // 5. useCallback - 缓存回调
    const handleEdit = useCallback(() => {
        // 处理编辑
    }, [userId]);
    
    // 6. useMemo - 缓存计算结果
    const displayName = useMemo(() => {
        return user ? `${user.firstName} ${user.lastName}` : '';
    }, [user]);
    
    // 7. useEffect - 副作用
    useEffect(() => {
        // 副作用逻辑
        return () => {
            // 清理函数
        };
    }, [userId]);
    
    // 8. 条件渲染和返回
    if (loading) return <Loading />;
    if (error) return <Error message={error.message} />;
    
    return <div ref={containerRef}>{/* 内容 */}</div>;
}
```

#### 自定义 Hook 规范
```tsx
/**
 * 用户数据获取 Hook
 * 
 * @param userId 用户ID
 * @returns 用户数据、加载状态、错误信息
 */
function useUser(userId: string) {
    const [user, setUser] = useState<User | null>(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState<Error | null>(null);
    
    useEffect(() => {
        let cancelled = false;
        
        async function fetchUser() {
            try {
                setLoading(true);
                setError(null);
                const data = await userApi.getUser(userId);
                if (!cancelled) {
                    setUser(data);
                }
            } catch (err) {
                if (!cancelled) {
                    setError(err instanceof Error ? err : new Error('未知错误'));
                }
            } finally {
                if (!cancelled) {
                    setLoading(false);
                }
            }
        }
        
        fetchUser();
        
        // 清理函数：防止组件卸载后设置状态
        return () => {
            cancelled = true;
        };
    }, [userId]);
    
    return { user, loading, error };
}
```

### 6.3 状态管理

#### 本地状态 vs 全局状态
```tsx
// ✅ 本地状态：组件内部使用，不需要共享
const [isOpen, setIsOpen] = useState(false);
const [inputValue, setInputValue] = useState('');

// ✅ 全局状态：多个组件共享，使用状态管理库
// 例如：用户信息、主题设置、购物车等
```

#### 使用 Zustand（推荐）
```tsx
import { create } from 'zustand';

/**
 * 用户状态 Store
 */
interface UserStore {
    user: User | null;
    isAuthenticated: boolean;
    login: (user: User) => void;
    logout: () => void;
    updateUser: (updates: Partial<User>) => void;
}

const useUserStore = create<UserStore>((set) => ({
    user: null,
    isAuthenticated: false,
    
    login: (user) => set({ user, isAuthenticated: true }),
    
    logout: () => set({ user: null, isAuthenticated: false }),
    
    updateUser: (updates) => set((state) => ({
        user: state.user ? { ...state.user, ...updates } : null
    }))
}));

// 使用
function UserProfile() {
    const { user, logout } = useUserStore();
    // ...
}
```

### 6.4 性能优化

```tsx
// ✅ 使用 React.memo 避免不必要的重渲染
const UserCard = React.memo(function UserCard({ user }: UserCardProps) {
    return <div>{user.name}</div>;
});

// ✅ 使用 useCallback 缓存回调函数
const handleClick = useCallback((id: string) => {
    // 处理点击
}, [/* 依赖项 */]);

// ✅ 使用 useMemo 缓存计算结果
const sortedItems = useMemo(() => {
    return [...items].sort((a, b) => a.name.localeCompare(b.name));
}, [items]);

// ✅ 列表渲染使用稳定的 key
{items.map((item) => (
    <ListItem key={item.id} item={item} />  // ✅ 使用唯一 ID
    // <ListItem key={index} item={item} />  // ❌ 避免使用索引
))}

// ✅ 懒加载组件
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

function App() {
    return (
        <Suspense fallback={<Loading />}>
            <HeavyComponent />
        </Suspense>
    );
}
```

---

## 7. Vue 规范

### 7.1 组件设计（Vue 3 Composition API）

#### 单文件组件结构
```vue
<script setup lang="ts">
/**
 * 用户卡片组件
 * 
 * @description 展示用户基本信息的卡片组件
 */
import { ref, computed, onMounted, watch } from 'vue';
import type { User } from '@/types';

// ============ Props 定义 ============
interface Props {
    /** 用户信息 */
    user: User;
    /** 是否显示详情 */
    showDetails?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
    showDetails: false
});

// ============ Emits 定义 ============
const emit = defineEmits<{
    /** 编辑事件 */
    (e: 'edit', user: User): void;
    /** 删除事件 */
    (e: 'delete', userId: string): void;
}>();

// ============ 响应式数据 ============
const isExpanded = ref(false);
const loading = ref(false);

// ============ 计算属性 ============
const displayName = computed(() => {
    return `${props.user.firstName} ${props.user.lastName}`;
});

const cardClasses = computed(() => ({
    'user-card': true,
    'user-card--expanded': isExpanded.value,
    'user-card--loading': loading.value
}));

// ============ 方法 ============
function handleEdit() {
    emit('edit', props.user);
}

function handleDelete() {
    emit('delete', props.user.id);
}

function toggleExpand() {
    isExpanded.value = !isExpanded.value;
}

// ============ 生命周期 ============
onMounted(() => {
    console.log('组件已挂载');
});

// ============ 侦听器 ============
watch(
    () => props.user.id,
    (newId, oldId) => {
        console.log(`用户ID变更：${oldId} -> ${newId}`);
    }
);

// ============ 暴露给父组件的方法 ============
defineExpose({
    toggleExpand
});
</script>

<template>
    <div :class="cardClasses">
        <div class="user-card__header">
            <h3>{{ displayName }}</h3>
            <button @click="toggleExpand">
                {{ isExpanded ? '收起' : '展开' }}
            </button>
        </div>
        
        <div v-if="showDetails || isExpanded" class="user-card__details">
            <p>邮箱：{{ user.email }}</p>
            <p>电话：{{ user.phone }}</p>
        </div>
        
        <div class="user-card__actions">
            <button @click="handleEdit">编辑</button>
            <button @click="handleDelete">删除</button>
        </div>
        
        <!-- 插槽 -->
        <slot name="footer" />
    </div>
</template>

<style scoped>
.user-card {
    padding: 16px;
    border: 1px solid #e0e0e0;
    border-radius: 8px;
}

.user-card--expanded {
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

.user-card--loading {
    opacity: 0.6;
    pointer-events: none;
}
</style>
```

### 7.2 组合式函数（Composables）

```typescript
// composables/useUser.ts
import { ref, computed, watch } from 'vue';
import type { Ref } from 'vue';
import type { User } from '@/types';
import { userApi } from '@/api';

/**
 * 用户数据组合式函数
 * 
 * @param userId 用户ID（响应式引用）
 * @returns 用户数据、加载状态、错误信息、刷新方法
 */
export function useUser(userId: Ref<string> | string) {
    const user = ref<User | null>(null);
    const loading = ref(false);
    const error = ref<Error | null>(null);
    
    // 获取用户数据
    async function fetchUser(id: string) {
        loading.value = true;
        error.value = null;
        
        try {
            user.value = await userApi.getUser(id);
        } catch (err) {
            error.value = err instanceof Error ? err : new Error('获取用户失败');
            user.value = null;
        } finally {
            loading.value = false;
        }
    }
    
    // 刷新数据
    function refresh() {
        const id = typeof userId === 'string' ? userId : userId.value;
        return fetchUser(id);
    }
    
    // 计算属性
    const displayName = computed(() => {
        if (!user.value) return '';
        return `${user.value.firstName} ${user.value.lastName}`;
    });
    
    // 侦听 userId 变化
    if (typeof userId !== 'string') {
        watch(userId, (newId) => {
            if (newId) {
                fetchUser(newId);
            }
        }, { immediate: true });
    } else {
        // 立即获取数据
        fetchUser(userId);
    }
    
    return {
        user,
        loading,
        error,
        displayName,
        refresh
    };
}
```

### 7.3 Pinia 状态管理

```typescript
// stores/user.ts
import { defineStore } from 'pinia';
import type { User } from '@/types';
import { userApi } from '@/api';

/**
 * 用户状态 Store
 */
export const useUserStore = defineStore('user', {
    // 状态
    state: () => ({
        currentUser: null as User | null,
        isAuthenticated: false,
        loading: false
    }),
    
    // 计算属性
    getters: {
        /** 用户显示名称 */
        displayName(): string {
            if (!this.currentUser) return '游客';
            return `${this.currentUser.firstName} ${this.currentUser.lastName}`;
        },
        
        /** 是否是管理员 */
        isAdmin(): boolean {
            return this.currentUser?.role === 'admin';
        }
    },
    
    // 方法
    actions: {
        /**
         * 用户登录
         */
        async login(credentials: { username: string; password: string }) {
            this.loading = true;
            try {
                const user = await userApi.login(credentials);
                this.currentUser = user;
                this.isAuthenticated = true;
            } finally {
                this.loading = false;
            }
        },
        
        /**
         * 用户登出
         */
        logout() {
            this.currentUser = null;
            this.isAuthenticated = false;
        },
        
        /**
         * 更新用户信息
         */
        updateUser(updates: Partial<User>) {
            if (this.currentUser) {
                this.currentUser = { ...this.currentUser, ...updates };
            }
        }
    }
});

// 使用 Setup Store 语法（更灵活）
export const useUserStore2 = defineStore('user', () => {
    // 状态
    const currentUser = ref<User | null>(null);
    const isAuthenticated = ref(false);
    
    // 计算属性
    const displayName = computed(() => {
        return currentUser.value?.name ?? '游客';
    });
    
    // 方法
    async function login(credentials: LoginCredentials) {
        const user = await userApi.login(credentials);
        currentUser.value = user;
        isAuthenticated.value = true;
    }
    
    function logout() {
        currentUser.value = null;
        isAuthenticated.value = false;
    }
    
    return {
        currentUser,
        isAuthenticated,
        displayName,
        login,
        logout
    };
});
```

---

# 第四部分：工程化规范

## 8. Git 提交规范

### 8.1 提交信息格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### 8.2 Type 类型说明

| 类型 | 说明 | 示例 |
|-----|------|------|
| `feat` | 新功能 | `feat(user): 添加用户登录功能` |
| `fix` | 修复 Bug | `fix(cart): 修复购物车数量计算错误` |
| `docs` | 文档更新 | `docs: 更新 README 安装说明` |
| `style` | 代码格式（不影响功能） | `style: 格式化代码` |
| `refactor` | 重构（不是新功能也不是修复） | `refactor(api): 重构请求封装` |
| `perf` | 性能优化 | `perf: 优化列表渲染性能` |
| `test` | 测试相关 | `test(user): 添加用户服务单元测试` |
| `chore` | 构建/工具/依赖更新 | `chore: 升级 webpack 到 5.x` |
| `revert` | 回滚提交 | `revert: 回滚 feat(user) 提交` |
| `ci` | CI/CD 配置 | `ci: 添加 GitHub Actions 配置` |
| `build` | 构建系统或外部依赖 | `build: 更新构建脚本` |

### 8.3 提交示例

```bash
# 简短提交
git commit -m "feat(user): 添加用户注册功能"

# 详细提交
git commit -m "feat(user): 添加用户注册功能

- 实现用户名密码注册
- 添加邮箱验证
- 添加表单校验

Closes #123"

# 修复 Bug
git commit -m "fix(order): 修复订单金额计算错误

订单金额在应用折扣后计算不正确，
原因是折扣百分比未正确转换。

Fixes #456"

# 破坏性变更
git commit -m "feat(api): 重构用户 API 接口

BREAKING CHANGE: 用户 API 响应格式已变更
- data 字段改为 result
- 添加 pagination 字段"
```

### 8.4 分支命名规范

| 分支类型 | 命名格式 | 示例 |
|---------|---------|------|
| 主分支 | `main` / `master` | `main` |
| 开发分支 | `develop` / `dev` | `develop` |
| 功能分支 | `feature/<name>` | `feature/user-login` |
| 修复分支 | `fix/<name>` 或 `bugfix/<name>` | `fix/cart-calculation` |
| 发布分支 | `release/<version>` | `release/1.2.0` |
| 热修复分支 | `hotfix/<name>` | `hotfix/security-patch` |

---

## 9. API 设计规范

### 9.1 RESTful API 设计

#### URL 设计原则
```
# 资源命名使用复数名词
GET    /api/v1/users           # 获取用户列表
GET    /api/v1/users/:id       # 获取单个用户
POST   /api/v1/users           # 创建用户
PUT    /api/v1/users/:id       # 更新用户（全量）
PATCH  /api/v1/users/:id       # 更新用户（部分）
DELETE /api/v1/users/:id       # 删除用户

# 资源关联
GET    /api/v1/users/:id/orders        # 获取用户的订单
POST   /api/v1/users/:id/orders        # 为用户创建订单

# 查询参数
GET    /api/v1/users?page=1&size=10             # 分页
GET    /api/v1/users?sort=createdAt&order=desc  # 排序
GET    /api/v1/users?status=active&role=admin   # 筛选
GET    /api/v1/users?keyword=john               # 搜索
```

#### HTTP 状态码
| 状态码 | 说明 | 使用场景 |
|-------|------|---------|
| 200 | OK | 请求成功 |
| 201 | Created | 创建成功 |
| 204 | No Content | 删除成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未认证 |
| 403 | Forbidden | 无权限 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 参数校验失败 |
| 500 | Internal Server Error | 服务器错误 |

### 9.2 请求/响应格式

#### 统一响应格式
```typescript
// 成功响应
{
    "code": "SUCCESS",
    "message": "操作成功",
    "data": {
        // 业务数据
    },
    "timestamp": 1642234567890
}

// 分页响应
{
    "code": "SUCCESS",
    "message": "操作成功",
    "data": {
        "list": [...],
        "pagination": {
            "page": 1,
            "size": 10,
            "total": 100,
            "totalPages": 10
        }
    },
    "timestamp": 1642234567890
}

// 错误响应
{
    "code": "VALIDATION_ERROR",
    "message": "参数校验失败",
    "errors": [
        { "field": "email", "message": "邮箱格式不正确" },
        { "field": "password", "message": "密码长度至少6位" }
    ],
    "timestamp": 1642234567890
}
```

### 9.3 错误码设计

```typescript
// 错误码枚举
enum ErrorCode {
    // 成功
    SUCCESS = 'SUCCESS',
    
    // 客户端错误 (4xx)
    BAD_REQUEST = 'BAD_REQUEST',
    UNAUTHORIZED = 'UNAUTHORIZED',
    FORBIDDEN = 'FORBIDDEN',
    NOT_FOUND = 'NOT_FOUND',
    VALIDATION_ERROR = 'VALIDATION_ERROR',
    
    // 业务错误
    USER_NOT_FOUND = 'USER_NOT_FOUND',
    USER_ALREADY_EXISTS = 'USER_ALREADY_EXISTS',
    INVALID_PASSWORD = 'INVALID_PASSWORD',
    ORDER_NOT_FOUND = 'ORDER_NOT_FOUND',
    INSUFFICIENT_STOCK = 'INSUFFICIENT_STOCK',
    
    // 服务端错误 (5xx)
    INTERNAL_ERROR = 'INTERNAL_ERROR',
    SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
    DATABASE_ERROR = 'DATABASE_ERROR'
}
```

---

## 10. 测试规范

### 10.1 单元测试

#### 测试文件命名
```
src/
├── utils/
│   ├── format.ts
│   └── format.test.ts      # 或 format.spec.ts
├── components/
│   └── UserCard/
│       ├── index.tsx
│       └── UserCard.test.tsx
```

#### 测试用例命名
```typescript
// 使用 describe + it 结构
describe('formatDate', () => {
    it('应该正确格式化日期', () => {
        // 测试代码
    });
    
    it('当输入为空时应该返回空字符串', () => {
        // 测试代码
    });
    
    it('当输入无效时应该抛出错误', () => {
        // 测试代码
    });
});

// 使用中文描述测试场景
describe('用户服务', () => {
    describe('创建用户', () => {
        it('应该成功创建用户并返回用户ID', async () => {
            // 测试代码
        });
        
        it('当用户名已存在时应该抛出错误', async () => {
            // 测试代码
        });
    });
});
```

#### 测试结构（AAA 模式）
```typescript
it('应该正确计算订单总价', () => {
    // Arrange（准备）
    const items = [
        { name: '商品A', price: 100, quantity: 2 },
        { name: '商品B', price: 50, quantity: 3 }
    ];
    
    // Act（执行）
    const total = calculateTotal(items);
    
    // Assert（断言）
    expect(total).toBe(350);
});
```

### 10.2 React 组件测试

```tsx
import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import UserCard from './UserCard';

describe('UserCard 组件', () => {
    const mockUser = {
        id: '1',
        name: '张三',
        email: 'zhangsan@example.com'
    };
    
    it('应该正确渲染用户信息', () => {
        render(<UserCard user={mockUser} />);
        
        expect(screen.getByText('张三')).toBeInTheDocument();
        expect(screen.getByText('zhangsan@example.com')).toBeInTheDocument();
    });
    
    it('点击编辑按钮应该触发 onEdit 回调', async () => {
        const handleEdit = jest.fn();
        render(<UserCard user={mockUser} onEdit={handleEdit} />);
        
        await userEvent.click(screen.getByRole('button', { name: '编辑' }));
        
        expect(handleEdit).toHaveBeenCalledWith(mockUser);
    });
    
    it('当 showDetails 为 false 时不应该显示详情', () => {
        render(<UserCard user={mockUser} showDetails={false} />);
        
        expect(screen.queryByText('详情')).not.toBeInTheDocument();
    });
});
```

### 10.3 Vue 组件测试

```typescript
import { mount } from '@vue/test-utils';
import { describe, it, expect, vi } from 'vitest';
import UserCard from './UserCard.vue';

describe('UserCard 组件', () => {
    const mockUser = {
        id: '1',
        name: '张三',
        email: 'zhangsan@example.com'
    };
    
    it('应该正确渲染用户信息', () => {
        const wrapper = mount(UserCard, {
            props: { user: mockUser }
        });
        
        expect(wrapper.text()).toContain('张三');
        expect(wrapper.text()).toContain('zhangsan@example.com');
    });
    
    it('点击编辑按钮应该触发 edit 事件', async () => {
        const wrapper = mount(UserCard, {
            props: { user: mockUser }
        });
        
        await wrapper.find('[data-test="edit-btn"]').trigger('click');
        
        expect(wrapper.emitted('edit')).toBeTruthy();
        expect(wrapper.emitted('edit')![0]).toEqual([mockUser]);
    });
});
```

---

# 附录

## 附录 A：代码审查清单

### A.1 开发流程检查
- [ ] 如果是询问"如何实现"，是否先提供了详细的开发计划
- [ ] 是否在用户同意后才修改代码
- [ ] 删除的文件是否移动到 `.recycle/` 文件夹而非直接删除

### A.2 代码质量检查
- [ ] 命名是否清晰、语义化
- [ ] 注释是否完整且为中文
- [ ] 错误处理是否完善
- [ ] 类型定义是否完整（TypeScript）
- [ ] 是否有重复代码可以抽取

### A.3 TypeScript 检查
- [ ] 是否避免使用 `any`
- [ ] 接口和类型是否正确定义
- [ ] 泛型使用是否恰当
- [ ] 导入导出是否规范

### A.4 React/Vue 检查
- [ ] 组件职责是否单一
- [ ] Props 和事件是否正确定义
- [ ] Hooks 使用是否规范
- [ ] 是否有性能问题（不必要的重渲染）

### A.5 Java 检查
- [ ] 包结构是否规范
- [ ] 类命名是否符合约定
- [ ] 是否正确使用注解
- [ ] 异常处理是否完善

### A.6 安全检查
- [ ] 是否验证了所有外部输入
- [ ] 是否避免了 XSS 风险
- [ ] 敏感数据是否正确处理
- [ ] 错误信息是否避免泄露敏感信息

### A.7 文档检查
- [ ] 是否更新了相关文档
- [ ] API 文档是否同步更新
- [ ] README 是否需要更新

---

## 附录 B：常见任务快速参考

### B.1 添加新文件
1. 创建文件，添加必要的类型定义
2. 添加中文注释
3. 在相关入口文件中导出（如需要）
4. 更新文档

### B.2 删除文件
1. 确认文件不再使用
2. 创建回收目录：`.recycle/YYYY-MM-DD/`
3. 移动文件到回收目录（保持目录结构）
4. 更新相关导入和引用
5. 更新文档

### B.3 重构代码
1. 先与用户确认重构范围
2. 制定详细的重构计划
3. 分步骤执行，每步验证
4. 确保测试通过
5. 更新文档

### B.4 添加新 API
1. 设计 API 接口（URL、参数、响应）
2. 定义 TypeScript 类型
3. 实现后端接口
4. 实现前端调用
5. 添加错误处理
6. 编写测试
7. 更新 API 文档

---

## 附录 C：模板使用说明

本模板可直接复制到新项目中使用。使用时请注意：

1. **根据项目调整**：
   - 删除不适用的语言/框架章节
   - 根据团队习惯调整具体规范

2. **补充项目特定内容**：
   - 项目特定的架构规范
   - 项目特定的命名规范
   - 项目特定的目录结构

3. **定期更新**：
   - 随着项目发展，及时更新规范内容
   - 根据团队反馈优化规范

4. **配合其他文档使用**：
   - 项目 README
   - API 文档
   - 架构设计文档
   - 部署文档

---

**文档版本**：v2.0
**最后更新**：2026-01-21