# 开发指南

## 🚀 快速开始

### 前置要求
- Docker & Docker Compose
- Node.js 18+
- Python 3.12+
- Git

### 一键启动
```bash
# Linux/Mac
./scripts/start.sh

# Windows
scripts\start.bat
```

### 手动启动

#### 后端开发
```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements-dev.txt

# 运行测试
pytest

# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

#### 前端开发
```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

# 构建生产版本
npm run build
```

## 🏗️ 项目结构

```
full-stack-doc/
├── backend/                 # FastAPI后端
│   ├── app/
│   │   ├── api/            # API路由
│   │   ├── core/           # 核心配置
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务逻辑
│   │   └── utils/          # 工具函数
│   ├── tests/              # 测试文件
│   ├── database/           # 数据库脚本
│   └── main.py             # 应用入口
├── frontend/               # React前端
│   ├── src/
│   │   ├── components/     # 组件
│   │   ├── pages/          # 页面
│   │   ├── services/       # API服务
│   │   ├── hooks/          # 自定义钩子
│   │   ├── utils/          # 工具函数
│   │   └── types/          # TypeScript类型
│   └── public/             # 静态资源
├── docs/                   # 项目文档
├── scripts/                # 部署脚本
└── docker-compose.yml      # Docker编排
```

## 🔧 开发工具

### 后端
- **FastAPI**: Web框架
- **SQLAlchemy**: ORM
- **Pydantic**: 数据验证
- **Pytest**: 测试框架
- **Black**: 代码格式化
- **iSort**: 导入排序

### 前端
- **React 19**: UI框架
- **TypeScript**: 类型安全
- **Vite**: 构建工具
- **TailwindCSS**: 样式框架
- **Vitest**: 测试框架
- **ESLint**: 代码检查

## 📝 开发规范

### Git提交规范
```
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动
```

### 代码规范
- 后端遵循PEP 8
- 前端使用ESLint + Prettier
- 提交前运行测试和格式化

## 🧪 测试

### 后端测试
```bash
cd backend
pytest                      # 运行所有测试
pytest tests/test_health.py  # 运行特定测试
pytest --cov=app             # 生成覆盖率报告
```

### 前端测试
```bash
cd frontend
npm test                    # 运行测试
npm run test:e2e           # E2E测试
```

## 🚀 部署

### 开发环境
```bash
docker-compose up -d
```

### 生产环境
```bash
./scripts/deploy.sh
```

## 🔍 调试

### 查看日志
```bash
docker-compose logs -f          # 所有服务日志
docker-compose logs backend     # 后端日志
docker-compose logs frontend    # 前端日志
```

### 健康检查
```bash
curl http://localhost:8000/api/v1/health
curl http://localhost:8000/api/v1/ready
```

## 📚 API文档
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 🆘 常见问题

### 1. 端口冲突
修改docker-compose.yml中的端口映射

### 2. 数据库连接失败
检查MySQL服务是否正常启动

### 3. 前端构建失败
删除node_modules重新安装依赖

### 4. 权限问题
确保Docker有足够权限访问文件系统

## 📞 支持

如有问题请查看：
1. [项目文档](docs/)
2. [API文档](http://localhost:8000/docs)
3. [GitHub Issues](https://github.com/your-repo/issues)