PeiFeng877 SK4 .cursorrules file for TypeScript

# SK3 项目开发规范

## 0. 核心开发原则

### 0.1 设计优先
- 任何功能实现前必须先完成设计文档
- 设计文档需要包含：
  - 功能描述
  - 技术方案
  - 接口设计
  - 数据流图
  - 可能的风险点

### 0.2 测试驱动开发（TDD）
- 先写测试，再写实现
- 测试用例要考虑：
  - 正常流程
  - 异常情况
  - 边界条件
- 确保测试覆盖率达标

### 0.3 主线任务导向
- 时刻对照开发计划书
- 每次开发前明确当前阶段目标
- 避免功能蔓延（Feature Creep）
- 如需调整计划，先讨论后执行

### 0.4 学习项目特性
- 代码注释要详尽，确保可读性
- 关键算法需要添加原理说明
- 复杂逻辑需要添加流程图
- 保持代码的教学性质

### 0.5 谨慎修改原则
- 修改前：
  - 理解现有代码的作用
  - 评估修改的影响范围
  - 确保修改的必要性
- 修改时：
  - 做好备份
  - 小步修改，频繁测试
  - 保持代码可回滚
- 修改后：
  - 完整测试
  - 更新相关文档
  - 记录修改原因

## 1. 项目结构规范

### 1.1 目录结构
```
src/
  ├── main/              # 主进程代码
  │   ├── services/      # 主进程服务
  │   └── index.ts       # 主进程入口
  ├── renderer/          # 渲染进程代码
  │   ├── components/    # Vue组件
  │   ├── composables/   # 组合式函数
  │   ├── styles/        # 样式文件
  │   └── main.ts        # 渲染进程入口
  └── shared/            # 共享代码
      ├── types/         # 类型定义
      ├── utils/         # 工具函数
      └── constants/     # 常量定义
```

### 1.2 命名规范
- 目录名：小写中划线（如：`file-watcher/`）
- 组件文件：大驼峰（如：`FileList.vue`）
- 组合式函数：驼峰，以use开头（如：`useFileWatcher.ts`）
- 工具函数：驼峰（如：`createWindow.ts`）
- 类型定义：大驼峰（如：`FileWatcherOptions.ts`）

## 2. 代码风格规范

### 2.1 Vue组件结构
```vue
<script setup lang="ts">
// 1. 类型导入
import type { FileInfo } from '@/shared/types'

// 2. 组件导入
import FileItem from './FileItem.vue'

// 3. 组合式函数
import { useFileList } from '../composables/useFileList'

// 4. Props/Emits 定义
const props = defineProps<{
  path: string
}>()

const emit = defineEmits<{
  'file-select': [file: FileInfo]
}>()

// 5. 组合式函数调用
const { files, isLoading } = useFileList(props.path)

// 6. 计算属性
const sortedFiles = computed(() => 
  [...files.value].sort((a, b) => a.name.localeCompare(b.name))
)

// 7. 事件处理
const handleFileSelect = (file: FileInfo) => {
  emit('file-select', file)
}
</script>

<template>
  <div class="file-list">
    <div v-if="isLoading">Loading...</div>
    <FileItem
      v-else
      v-for="file in sortedFiles"
      :key="file.path"
      :file="file"
      @select="handleFileSelect"
    />
  </div>
</template>
```

### 2.2 TypeScript 使用规范
```typescript
// 使用 type 而不是 interface
type FileWatcherOptions = {
  path: string
  recursive?: boolean
  ignore?: string[]
}

// 常量定义
const FILE_EVENTS = {
  CREATED: 'created',
  MODIFIED: 'modified',
  DELETED: 'deleted',
} as const

// 组合式函数
export const useFileWatcher = (options: FileWatcherOptions) => {
  const isWatching = ref(false)
  const error = ref<Error | null>(null)

  // 返回组合式函数的响应式状态
  return {
    isWatching,
    error
  }
}
```

## 3. 功能实现规范

### 3.1 错误处理
```typescript
// 使用自定义错误类型
type ErrorType = {
  code: string
  message: string
  details?: unknown
}

// 错误处理函数
const handleError = (error: ErrorType) => {
  console.error(`[${error.code}] ${error.message}`, error.details)
}
```

### 3.2 状态管理
```typescript
// 使用组合式函数管理状态
export const useFileStore = () => {
  const files = ref<FileInfo[]>([])
  const isLoading = ref(false)

  const addFile = (file: FileInfo) => {
    files.value.push(file)
  }

  return {
    files,
    isLoading,
    addFile
  }
}
```

## 4. 测试规范

### 4.1 单元测试
```typescript
import { describe, it, expect } from 'vitest'
import { useFileWatcher } from './useFileWatcher'

describe('useFileWatcher', () => {
  it('should watch files', async () => {
    const { isWatching } = useFileWatcher({
      path: './test'
    })

    expect(isWatching.value).toBe(true)
  })
})
```

## 5. Git 提交规范

### 5.1 提交消息格式
```
<type>: <description>

[optional body]
```

类型：
- feat: 新功能
- fix: 修复
- docs: 文档更新
- style: 代码格式
- refactor: 重构
- test: 测试
- chore: 构建/工具

### 5.2 分支管理
- main: 主分支
- dev: 开发分支
- feature/*: 功能分支
- fix/*: 修复分支

## 6. 性能优化规范

### 6.1 代码优化
- 使用 `shallowRef` 代替 `ref` 处理大型对象
- 使用 `v-memo` 缓存不经常变化的列表项
- 实现虚拟滚动处理大量数据

### 6.2 构建优化
- 使用动态导入拆分代码
- 优化依赖包大小
- 启用构建缓存

## 7. 文档规范

### 7.1 注释规范
```typescript
/**
 * 计算文件哈希值
 * 
 * @description
 * 使用 MD5 算法计算文件的哈希值，用于文件完整性校验
 * 对于大文件，使用流式处理避免内存占用过大
 * 
 * @param filePath - 文件路径
 * @returns Promise<string> - 返回文件的 MD5 哈希值
 * 
 * @throws {FileNotFoundError} 当文件不存在时抛出
 * @throws {PermissionError} 当没有文件读取权限时抛出
 * 
 * @example
 * ```typescript
 * const hash = await calculateFileHash('example.txt')
 * console.log(`文件哈希值: ${hash}`)
 * ```
 */
async function calculateFileHash(filePath: string): Promise<string> {
  // 实现代码...
}
```

### 7.2 学习资源
- 每个核心功能模块添加学习指南
- 包含相关的技术文档链接
- 提供进阶学习建议

### 7.3 开发日志
- 记录重要决策和原因
- 记录遇到的问题和解决方案
- 作为学习参考和经验积累

## 8. 代码审查清单

### 8.1 提交前检查
- [ ] 代码是否符合设计文档
- [ ] 测试是否全部通过
- [ ] 注释是否完整清晰
- [ ] 是否偏离主线任务
- [ ] 是否考虑了异常情况
- [ ] 是否有不必要的改动
- [ ] 相关文档是否更新

### 8.2 代码质量检查
- [ ] 代码是否简洁清晰
- [ ] 变量命名是否合适
- [ ] 是否有重复代码
- [ ] 是否有性能问题
- [ ] 是否有安全隐患
- [ ] 是否便于维护和扩展