# iTi-Flask

iTi-Flask 是基于 APIFlask / Flask 的后端框架基座。

它只提供应用创建、配置、扩展、模块协议、服务调用、任务运行、迁移集成和基础工具。
它不是业务系统。
系统业务能力不在框架内。
需要系统业务时，业务项目使用独立包 `iTi-System`。

## 技术栈

- Python 3.11+
- APIFlask / Flask
- SQLAlchemy / Flask-Migrate
- Flask-JWT-Extended
- Flask-Limiter
- Flask-Caching
- Marshmallow
- httpx
- uv
- Copier

## 安装

框架本地开发：

```bash
uv sync --extra dev
```

业务项目通过 Git tag 依赖框架：

```toml
dependencies = [
  "iti-flask @ git+ssh://git@example.com/iTi-Flask.git@v0.1.1",
]
```

可选依赖按需启用：

```bash
uv sync --extra dev --extra mysql --extra image --extra excel
```

## 应用工厂

业务项目使用 `iti.applications.create_app()` 创建 Flask 应用：

```python
from iti.applications import create_app

from config import config
from my_app.models import import_models
from my_app.modules.example.module import ExampleModule

app = create_app(
    config_mapping=config,
    model_imports=[import_models],
    modules=[ExampleModule()],
)
```

`config_mapping` 用于传入业务项目自己的配置类。
`model_imports` 用于让 Alembic 自动发现业务模型。
`modules` 用于注册进程内业务模块。

## 业务项目生成

```bash
uvx copier copy ./copier-template ../my-business-app
```

生成后进入业务项目：

```bash
cd ../my-business-app
uv sync --extra dev
uv run python -m flask --app app.py db upgrade
uv run python -m flask --app app.py run --debug
```

## 文档

- [文档索引](docs/README.md)
- [架构](docs/ARCHITECTURE.md)
- [配置](docs/CONFIGURATION.md)
- [模块协议](docs/MODULES.md)
- [服务客户端](docs/SERVICE_CLIENT.md)
- [任务运行器](docs/TASKS.md)
- [数据库迁移](docs/MIGRATIONS.md)
- [种子数据](docs/SEEDS.md)
- [Copier 模板](docs/COPIER_TEMPLATE.md)