template/USAGE.md

# 模板使用说明

## 模板特性

本模板基于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/) 目录了解详细文档