初次提交

2025-10-14 20:05:29 +08:00
commit 6e4e48fdd2
673 changed files with 437006 additions and 0 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,188 @@
+# 开发指南
+
+## 🚀 快速开始
+
+### 前置要求
+- 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)