# 项目结构说明

## 目录结构

```
template/
├── src/                          # 源代码目录
│   └── your_app/                # 主应用包（需要重命名为你的应用名）
│       ├── __init__.py          # 应用工厂，创建Flask应用实例
│       ├── app.py               # 应用入口（可选，可直接运行）
│       ├── models/              # 数据模型
│       │   ├── __init__.py      # 导出db实例和所有模型
│       │   └── example.py       # 示例模型
│       ├── routes/              # 路由定义
│       │   ├── __init__.py      # 主路由蓝图
│       │   └── *.py             # 其他路由模块
│       ├── services/            # 业务逻辑层
│       │   └── __init__.py      # 服务模块初始化
│       ├── utils/               # 工具函数
│       │   ├── __init__.py      # 工具模块初始化
│       │   └── helpers.py       # 辅助函数
│       ├── forms/               # 表单定义（可选，如果使用WTForms）
│       │   └── __init__.py
│       ├── static/              # 静态资源（CSS、JS、图片等）
│       │   ├── css/
│       │   ├── js/
│       │   └── images/
│       └── templates/           # Jinja2模板文件
│           ├── base.html        # 基础模板
│           └── *.html           # 其他模板
│
├── config/                       # 配置管理
│   ├── __init__.py              # 配置选择器，根据环境变量选择配置
│   ├── base.py                  # 基础配置类，所有环境通用配置
│   ├── development.py           # 开发环境配置
│   ├── production.py            # 生产环境配置
│   ├── testing.py               # 测试环境配置
│   └── local.py                 # 本地环境配置
│
├── requirements/                 # 依赖管理（分类管理）
│   ├── base.txt                 # 基础依赖（项目运行必需）
│   ├── development.txt          # 开发依赖（开发工具）
│   ├── production.txt           # 生产依赖（WSGI服务器等）
│   └── test.txt                 # 测试依赖（测试框架）
│
├── tests/                        # 测试目录
│   ├── __init__.py
│   ├── conftest.py              # pytest配置和fixtures
│   └── test_*.py                # 测试文件
│
├── migrations/                   # 数据库迁移（Flask-Migrate自动生成）
│   ├── versions/                # 迁移版本文件
│   ├── env.py                   # 迁移环境配置
│   └── alembic.ini              # Alembic配置
│
├── logs/                         # 日志目录（自动生成）
│   └── app.log                  # 应用日志
│
├── uploads/                      # 上传文件目录（自动生成）
│
├── docs/                         # 文档目录
│   ├── README.md                # 文档索引
│   ├── api/                     # API文档
│   │   └── README.md
│   ├── development/             # 开发文档
│   │   └── README.md
│   └── deployment/              # 部署文档
│       └── README.md
│
├── scripts/                      # 工具脚本
│   └── init_project.py          # 项目初始化脚本
│
├── .gitignore                    # Git忽略文件
├── .flake8                       # flake8代码检查配置
├── pytest.ini                   # pytest测试配置
├── env.example                   # 环境变量模板
├── gunicorn.conf.py             # Gunicorn生产服务器配置
├── run_dev.py                   # 开发环境启动脚本
├── run_production.py            # 生产环境启动脚本（测试用）
├── README.md                     # 项目说明文档
├── QUICK_START.md               # 快速开始指南
└── PROJECT_STRUCTURE.md         # 本文件
```

## 核心文件说明

### 应用工厂 (`src/your_app/__init__.py`)

使用工厂模式创建Flask应用，支持：
- 多环境配置
- 扩展初始化
- 蓝图注册
- 错误处理

### 配置管理 (`config/`)

- **base.py**: 所有环境通用的配置
- **development.py**: 开发环境（调试模式开启）
- **production.py**: 生产环境（安全配置）
- **testing.py**: 测试环境（内存数据库）
- **local.py**: 本地环境（可自定义）

通过 `FLASK_ENV` 环境变量自动选择配置。

### 依赖管理 (`requirements/`)

分类管理依赖，便于不同环境安装：
- **base.txt**: 核心依赖
- **development.txt**: 开发工具
- **production.txt**: 生产服务器
- **test.txt**: 测试框架

### 测试 (`tests/`)

使用pytest框架：
- **conftest.py**: 定义测试fixtures
- **test_*.py**: 测试用例

## 使用建议

### 1. 项目命名

将 `your_app` 替换为你的实际项目名称：
- 目录: `src/your_app` -> `src/my_project`
- 导入: `from src.your_app import ...` -> `from src.my_project import ...`

### 2. 添加新功能

- **路由**: 在 `routes/` 创建新文件，定义蓝图，在 `__init__.py` 注册
- **模型**: 在 `models/` 创建新文件，运行迁移
- **服务**: 在 `services/` 创建业务逻辑
- **工具**: 在 `utils/` 创建辅助函数

### 3. 环境配置

通过 `.env` 文件管理配置，不要提交到Git。

### 4. 数据库迁移

始终使用Flask-Migrate管理数据库变更：
```bash
flask db migrate -m "描述"
flask db upgrade
```

## 最佳实践

1. **代码组织**: 按功能模块组织代码，保持单一职责
2. **配置管理**: 所有配置通过环境变量，不要硬编码
3. **错误处理**: 统一错误处理，返回标准格式
4. **日志记录**: 重要操作记录日志
5. **测试覆盖**: 关键功能编写测试
6. **文档更新**: 及时更新文档，保持同步