---
description: JSDoc 注释规范和代码文档
globs: ["**/*.ts", "**/*.vue", "**/services/**/*", "**/components/**/*"]
alwaysApply: false
---

# JSDoc 注释规范

## 📝 函数和类注释

### 服务类注释
```typescript
/**
 * 用户服务类，负责用户相关的业务逻辑处理
 * 
 * @description 提供用户的增删改查、认证授权等功能
 * @example
 * ```typescript
 * const userService = new UserService(userRepository);
 * const user = await userService.createUser(userData);
 * ```
 * 
 * @author AI 编码助手
 * @since 1.0.0
 * @version 1.2.0
 */
export class UserService {
  /**
   * 创建新用户
   * 
   * @param userData - 用户数据对象
   * @param userData.email - 用户邮箱地址
   * @param userData.password - 用户密码（明文）
   * @param userData.firstName - 用户名字
   * @param userData.lastName - 用户姓氏
   * 
   * @returns Promise<IUser> 创建成功的用户对象
   * 
   * @throws {ValidationError} 当用户数据验证失败时抛出
   * @throws {ConflictError} 当邮箱已存在时抛出
   * 
   * @example
   * ```typescript
   * const newUser = await userService.createUser({
   *   email: 'user@example.com',
   *   password: 'password123',
   *   firstName: 'John',
   *   lastName: 'Doe'
   * });
   * ```
   */
  async createUser(userData: CreateUserInput): Promise<IUser> {
    // 实现逻辑
  }

  /**
   * 根据 ID 查找用户
   * 
   * @param userId - 用户唯一标识符
   * @returns Promise<IUser | null> 找到的用户对象或 null
   * 
   * @example
   * ```typescript
   * const user = await userService.findById('123e4567-e89b-12d3-a456-426614174000');
   * if (user) {
   *   console.log(`找到用户: ${user.firstName} ${user.lastName}`);
   * }
   * ```
   */
  async findById(userId: string): Promise<IUser | null> {
    // 实现逻辑
  }
}
```

## 🏗️ 接口和类型注释

### 接口定义注释
```typescript
/**
 * 用户数据接口
 * 
 * @interface IUser
 * @description 定义用户实体的数据结构
 */
interface IUser {
  /** 用户唯一标识符 */
  readonly id: string;
  
  /** 用户邮箱地址 */
  email: string;
  
  /** 用户名字 */
  firstName: string;
  
  /** 用户姓氏 */
  lastName: string;
  
  /** 用户角色 */
  role: UserRole;
  
  /** 账户创建时间 */
  createdAt: Date;
  
  /** 最后更新时间 */
  updatedAt?: Date;
}

/**
 * 用户角色常量对象
 * 
 * @constant {object} USER_ROLE
 * @description 定义系统中可用的用户角色常量
 * @example
 * ```typescript
 * const currentRole = USER_ROLE.ADMIN;
 * const hasPermission = (role: UserRole) => role === USER_ROLE.ADMIN;
 * ```
 */
const USER_ROLE = {
  /** 普通用户 */
  USER: 'user',
  /** 管理员用户 */
  ADMIN: 'admin',
  /** 访客用户 */
  GUEST: 'guest',
} as const;

/**
 * 用户角色类型定义
 * 
 * @typedef {string} UserRole
 * @description 用户角色的联合类型
 */
type UserRole = typeof USER_ROLE[keyof typeof USER_ROLE];

/**
 * 创建用户输入类型
 * 
 * @type {CreateUserInput}
 * @description 创建用户时需要的输入数据
 */
type CreateUserInput = Pick<IUser, 'email' | 'firstName' | 'lastName'> & {
  /** 用户密码（明文） */
  password: string;
};
```

## 🎨 Vue 组件注释

### 组件文档注释
```vue
<template>
  <!-- 用户卡片组件 -->
  <div class="user-card">
    <div class="user-avatar">
      <img :src="user.avatar" :alt="`${user.firstName} ${user.lastName} 的头像`" />
    </div>
    <div class="user-info">
      <h3 class="user-name">{{ fullName }}</h3>
      <p class="user-email">{{ user.email }}</p>
    </div>
    <div class="user-actions" v-if="canEdit">
      <BaseButton variant="primary" @click="handleEdit">编辑</BaseButton>
      <BaseButton variant="destructive" @click="handleDelete">删除</BaseButton>
    </div>
  </div>
</template>

<script setup lang="ts">
/**
 * 用户卡片组件
 * 
 * @component UserCard
 * @description 显示用户基本信息的卡片组件，支持编辑和删除操作
 * 
 * @example
 * ```vue
 * <UserCard 
 *   :user="currentUser" 
 *   :can-edit="true"
 *   @edit="handleUserEdit"
 *   @delete="handleUserDelete"
 * />
 * ```
 */

// Props 接口定义
interface Props {
  /** 用户数据对象 */
  user: IUser;
  /** 是否允许编辑 */
  canEdit?: boolean;
}

// Props 定义
const props = withDefaults(defineProps<Props>(), {
  canEdit: false,
});

// Events 定义
const emit = defineEmits<{
  /** 编辑用户事件 */
  edit: [user: IUser];
  /** 删除用户事件 */
  delete: [userId: string];
}>();

/**
 * 计算用户全名
 * 
 * @computed fullName
 * @description 组合用户的名字和姓氏
 * @returns {string} 用户的全名
 */
const fullName = computed(() => {
  return `${props.user.firstName} ${props.user.lastName}`;
});

/**
 * 处理编辑用户操作
 * 
 * @function handleEdit
 * @description 触发编辑用户事件
 */
const handleEdit = () => {
  emit('edit', props.user);
};

/**
 * 处理删除用户操作
 * 
 * @function handleDelete
 * @description 触发删除用户事件
 */
const handleDelete = () => {
  emit('delete', props.user.id);
};
</script>
```

## 🎯 JSDoc 最佳实践

### 必需配置项
- ✅ 所有公共 API 必须包含 JSDoc 注释
- ✅ 复杂逻辑必须有中文注释
- ✅ 接口和类型定义要有详细说明
- ✅ 示例代码要完整可运行
- ✅ 使用 @param、@returns、@throws 等标签

### 参考文件
- `services/user.service.ts` - 服务类注释示例
- `types/user.types.ts` - 类型定义注释示例
- `components/UserCard.vue` - 组件注释示例