CLAUDE.md 最佳实践

# 项目名称

## 项目概述

这是一个 [项目类型] 项目，主要功能是 [核心功能描述]。
目标用户是 [目标用户群体]。

## 技术架构

### 前端
- **框架**: React 18 + TypeScript 5
- **状态管理**: Zustand
- **UI 组件**: shadcn/ui + Tailwind CSS
- **路由**: React Router v6

### 后端
- **运行时**: Node.js 20
- **框架**: Express.js
- **ORM**: Prisma
- **数据库**: PostgreSQL 15

## 目录结构

```
src/
├── components/    # 可复用 UI 组件
├── pages/         # 页面组件
├── hooks/         # 自定义 Hooks
├── utils/         # 工具函数
├── types/         # TypeScript 类型定义
└── api/           # API 请求层
```

## 开发规范

### 命名约定
- 组件：PascalCase（如 `UserProfile.tsx`）
- 工具函数：camelCase（如 `formatDate.ts`）
- 常量：SCREAMING_SNAKE_CASE

### 代码风格
- 使用函数式组件和 Hooks
- 优先使用 `const` 声明
- 每个文件不超过 300 行

## 常用命令

```bash
npm run dev       # 启动开发服务器 (http://localhost:3000)
npm run build     # 构建生产版本
npm run test      # 运行单元测试
npm run lint      # 代码检查
npm run db:push   # 同步数据库 schema
```

## 注意事项

- 所有 API 请求需要处理错误状态
- 敏感信息使用环境变量，不要硬编码
- 新功能需要添加对应的单元测试

# 项目名称

> 一句话描述项目核心价值

## 项目背景

### 业务目标
- 解决 [具体问题]
- 服务 [目标用户]
- 实现 [业务价值]

### 当前阶段
- [x] MVP 开发完成
- [ ] 性能优化进行中
- [ ] 国际化支持计划中

## 技术架构

### 整体架构
```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   客户端     │───▶│   API 网关   │───▶│   微服务     │
│  (React)    │    │  (Express)  │    │  (各业务)    │
└─────────────┘    └─────────────┘    └─────────────┘
                                            │
                                            ▼
                                     ┌─────────────┐
                                     │   数据库     │
                                     │ (PostgreSQL)│
                                     └─────────────┘
```

### 技术栈详情

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 前端框架 | React | 18.2 | 函数式组件 |
| 类型系统 | TypeScript | 5.3 | 严格模式 |
| 状态管理 | Zustand | 4.x | 轻量级状态 |
| UI 框架 | Tailwind CSS | 3.4 | 原子化 CSS |
| 后端框架 | Express | 4.18 | RESTful API |
| ORM | Prisma | 5.x | 类型安全查询 |
| 数据库 | PostgreSQL | 15 | 主数据存储 |
| 缓存 | Redis | 7.x | 会话和缓存 |

## 目录结构

```
├── src/
│   ├── app/              # 应用入口和路由配置
│   ├── components/       # 可复用组件
│   │   ├── ui/          # 基础 UI 组件
│   │   └── features/    # 业务功能组件
│   ├── hooks/           # 自定义 React Hooks
│   ├── lib/             # 第三方库封装
│   ├── services/        # API 服务层
│   ├── stores/          # 状态管理
│   ├── types/           # TypeScript 类型
│   └── utils/           # 工具函数
├── server/              # 后端代码
│   ├── routes/          # API 路由
│   ├── controllers/     # 控制器
│   ├── services/        # 业务逻辑
│   └── middleware/      # 中间件
├── prisma/              # 数据库 Schema
└── tests/               # 测试文件
```

## 开发规范

### Git 工作流
- 主分支：`main`（保护分支）
- 开发分支：`develop`
- 功能分支：`feature/功能名`
- 修复分支：`fix/问题描述`

### Commit 规范
```
(): 

类型：feat | fix | docs | style | refactor | test | chore
范围：组件名/模块名
描述：简短说明（不超过 50 字）
```

### 代码审查要点
1. 是否有类型安全问题
2. 是否处理了边界情况
3. 是否有性能隐患
4. 是否符合现有代码风格

### 测试要求
- 新功能需要单元测试，覆盖率 > 80%
- API 需要集成测试
- 关键路径需要 E2E 测试

## 环境配置

### 必需环境变量
```env
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
JWT_SECRET=your-secret-key
```

### 本地开发
```bash
# 安装依赖
npm install

# 启动数据库（Docker）
docker-compose up -d

# 初始化数据库
npm run db:push
npm run db:seed

# 启动开发服务器
npm run dev
```

## 常见问题

### Q: 如何添加新的 API 端点？
1. 在 `server/routes/` 添加路由
2. 在 `server/controllers/` 添加控制器
3. 在 `src/services/` 添加前端调用
4. 更新 API 文档

### Q: 如何处理数据库迁移？
```bash
npm run db:migrate    # 创建迁移
npm run db:push       # 应用到开发库
```

## 联系方式

- 技术负责人：[姓名]
- 文档地址：[链接]
- Issue 追踪：[链接]