first commit

2025-12-21 00:20:27 +08:00
commit 6fb3c6c23d
42 changed files with 2265 additions and 0 deletions
--- a/USAGE.md
+++ b/USAGE.md
@@ -0,0 +1,290 @@
+# 模板使用说明
+
+## 模板特性
+
+本模板基于aitsc项目的最佳实践，抽取了以下核心特性：
+
+### ✅ 已实现的功能
+
+1. **标准化项目结构**
+   - 清晰的目录组织（src/、config/、tests/等）
+   - 模块化设计，易于扩展
+
+2. **多环境配置管理**
+   - 支持development/production/testing/local四种环境
+   - 通过环境变量自动选择配置
+   - 配置继承机制，减少重复
+
+3. **依赖分类管理**
+   - base.txt: 核心依赖
+   - development.txt: 开发工具
+   - production.txt: 生产服务器
+   - test.txt: 测试框架
+
+4. **应用工厂模式**
+   - 灵活的Flask应用创建方式
+   - 支持测试和不同环境
+
+5. **数据库迁移支持**
+   - 使用Flask-Migrate管理数据库版本
+   - 支持多数据库（SQLite/MySQL/PostgreSQL）
+
+6. **环境变量管理**
+   - 使用python-dotenv加载.env文件
+   - 提供env.example模板
+
+7. **完整的测试框架**
+   - pytest配置
+   - 测试fixtures
+   - 示例测试用例
+
+8. **文档结构**
+   - API文档模板
+   - 开发文档模板
+   - 部署文档模板
+
+9. **代码质量工具**
+   - flake8配置
+   - pytest配置
+   - 支持代码格式化（Black、isort）
+
+10. **生产环境支持**
+    - Gunicorn配置
+    - 日志系统
+    - 错误处理
+
+## 使用流程
+
+### 1. 复制模板
+
+```bash
+cp -r template my_new_project
+cd my_new_project
+```
+
+### 2. 运行初始化（推荐）
+
+```bash
+python scripts/init_project.py
+```
+
+脚本会自动：
+- 生成SECRET_KEY
+- 创建.env文件
+- 创建必要目录
+- 可选：重命名应用目录
+
+### 3. 手动配置（如果未使用脚本）
+
+```bash
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# 或 .venv\Scripts\activate  # Windows
+
+# 安装依赖
+pip install -r requirements/base.txt
+pip install -r requirements/development.txt
+
+# 配置环境变量
+cp env.example .env
+# 编辑.env文件，至少设置SECRET_KEY和DATABASE_URL
+```
+
+### 4. 初始化数据库
+
+```bash
+flask db init
+flask db migrate -m "Initial migration"
+flask db upgrade
+```
+
+### 5. 运行项目
+
+```bash
+python run_dev.py
+```
+
+## 自定义项目
+
+### 重命名应用
+
+1. 重命名目录: `src/your_app` -> `src/my_app`
+2. 更新导入路径：
+   - `run_dev.py`: `from src.your_app` -> `from src.my_app`
+   - `run_production.py`: 同上
+   - `gunicorn.conf.py`: `"src.your_app:create_app()"` -> `"src.my_app:create_app()"`
+   - `tests/conftest.py`: 同上
+   - 所有测试文件中的导入
+
+### 添加新功能
+
+#### 添加路由
+
+1. 在 `src/your_app/routes/` 创建新文件，例如 `api.py`:
+
+```python
+from flask import Blueprint, jsonify
+
+api_bp = Blueprint('api', __name__, url_prefix='/api/v1')
+
+@api_bp.route('/users')
+def get_users():
+    return jsonify({'users': []})
+```
+
+2. 在 `src/your_app/__init__.py` 注册：
+
+```python
+from src.your_app.routes.api import api_bp
+app.register_blueprint(api_bp)
+```
+
+#### 添加模型
+
+1. 在 `src/your_app/models/` 创建新文件，例如 `user.py`:
+
+```python
+from datetime import datetime
+from src.your_app import db
+
+class User(db.Model):
+    __tablename__ = 'users'
+    
+    id = db.Column(db.Integer, primary_key=True)
+    username = db.Column(db.String(80), unique=True, nullable=False)
+    email = db.Column(db.String(120), unique=True, nullable=False)
+    created_at = db.Column(db.DateTime, default=datetime.utcnow)
+```
+
+2. 在 `src/your_app/models/__init__.py` 导入：
+
+```python
+from .user import User
+
+__all__ = ['db', 'User']
+```
+
+3. 创建迁移：
+
+```bash
+flask db migrate -m "Add User model"
+flask db upgrade
+```
+
+#### 添加服务
+
+在 `src/your_app/services/` 创建业务逻辑：
+
+```python
+from src.your_app.models import User, db
+
+class UserService:
+    @staticmethod
+    def create_user(username, email):
+        user = User(username=username, email=email)
+        db.session.add(user)
+        db.session.commit()
+        return user
+```
+
+## 环境配置
+
+### 开发环境
+
+```bash
+export FLASK_ENV=development
+python run_dev.py
+```
+
+- 启用调试模式
+- 使用开发数据库
+- 详细错误信息
+
+### 生产环境
+
+```bash
+export FLASK_ENV=production
+gunicorn -c gunicorn.conf.py "src.your_app:create_app()"
+```
+
+- 关闭调试模式
+- 使用生产数据库
+- 安全配置
+
+### 测试环境
+
+```bash
+export FLASK_ENV=testing
+pytest
+```
+
+- 使用内存数据库
+- 关闭CSRF保护
+- 快速测试
+
+## 常见任务
+
+### 运行测试
+
+```bash
+pip install -r requirements/test.txt
+pytest
+pytest --cov=src tests/  # 带覆盖率
+```
+
+### 代码检查
+
+```bash
+pip install -r requirements/development.txt
+flake8 src/
+pylint src/
+black src/  # 格式化
+isort src/  # 排序导入
+```
+
+### 数据库操作
+
+```bash
+# 创建迁移
+flask db migrate -m "描述"
+
+# 应用迁移
+flask db upgrade
+
+# 回滚迁移
+flask db downgrade
+
+# 查看迁移历史
+flask db history
+```
+
+## 注意事项
+
+1. **不要提交敏感信息**
+   - `.env` 文件已加入.gitignore
+   - 不要将密钥、密码等提交到代码库
+
+2. **环境变量必需项**
+   - `SECRET_KEY`: Flask密钥（必需）
+   - `DATABASE_URL`: 数据库连接（必需）
+   - `FLASK_ENV`: 运行环境（可选，默认development）
+
+3. **生产环境安全**
+   - 必须设置强SECRET_KEY
+   - 必须使用非SQLite数据库
+   - 必须配置CORS_ORIGINS限制
+   - 必须启用HTTPS
+
+4. **数据库迁移**
+   - 始终使用Flask-Migrate管理数据库变更
+   - 不要直接修改数据库结构
+   - 迁移文件应该提交到代码库
+
+## 获取帮助
+
+- 查看 [README.md](README.md) 了解完整文档
+- 查看 [QUICK_START.md](QUICK_START.md) 快速开始
+- 查看 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) 了解项目结构
+- 查看 [docs/](docs/) 目录了解详细文档
+