# iTi-Flask

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

它只提供工程底座和架构约束。
它不是业务应用。
它不内置用户、角色、菜单等系统业务。
它不内置前端产物。
它可以按配置承载业务项目自己的 SPA 静态目录。

## 当前边界

框架内置：

- 应用工厂和配置加载。
- SQLAlchemy、Flask-Migrate、JWT、缓存、限流、日志、错误处理。
- 进程内 module 协议。
- HTTP JSON service client。
- 单进程 task runner。
- 可选 SPA 静态目录承载。
- Copier 业务项目模板。

框架不内置：

- `sys_*` 表。
- 认证、用户、角色、菜单、部门、字典、配置、文件、日志等系统业务。
- 系统 seed。
- 系统 migration。
- ERP 能力。
- 前端构建产物。

系统业务放在独立包 `iti-system`。
MES 这类主业务项目按需依赖 `iti-flask + iti-system`。
ERP Service 这类服务只依赖 `iti-flask`。

## 开发

```bash
uv sync --extra dev
uv run --extra dev pytest
uv run --extra dev mypy
```

需要覆盖可选依赖时：

```bash
uv run --extra dev --extra mysql --extra image --extra excel pytest
```

## 业务项目生成

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

业务项目依赖 iTi-Flask 的 Git tag。
框架升级后，业务项目更新依赖 tag。

## 系统业务

需要用户、角色、菜单等能力时，业务项目额外依赖 `iti-system`，并在 `modules` 中注册：

```python
from iti_system import create_system_module

modules = [
    create_system_module(),
]
```

`iti-system` 引入即全量引入。
不提供系统模块选择。
不拆分系统 migration。

`iti-system` 自己提供系统 seed 和系统 migration 同步命令。

## 文档

- [框架边界](docs/FRAMEWORK_BOUNDARY.md)
- [架构重构计划](docs/ARCHITECTURE_REFACTOR_PLAN.md)
- [模块协议](docs/MODULES.md)
- [数据库迁移](docs/MIGRATIONS.md)
- [种子数据](docs/SEEDS.md)
- [服务客户端](docs/SERVICE_CLIENT.md)
- [任务运行器](docs/TASKS.md)