# 架构

iTi-Flask 是框架基座。
它提供后端项目的通用工程能力，不内置具体业务。

## 包定位

框架负责：

- 应用工厂。
- 配置加载。
- APIFlask 集成。
- SQLAlchemy 和 Flask-Migrate 初始化。
- JWT、缓存、限流、日志、错误处理。
- 模块注册协议。
- HTTP JSON 服务客户端。
- 单进程任务运行器。
- Copier 业务项目模板。
- 可选 SPA 静态目录承载。
- 默认 HTML 错误页。

框架不负责：

- 系统业务。
- 业务表和业务路由。
- 业务 seed。
- 业务前端构建产物。

需要系统业务时，业务项目额外依赖 `iTi-System`。

## 应用创建流程

`create_app()` 会按顺序完成这些工作：

1. 解析配置。
2. 创建 `APIFlask` 应用。
3. 初始化日志、插件、HTTP、JSON、Moment。
4. 初始化数据库、JWT、迁移、限流、缓存、事件总线。
5. 导入业务模型。
6. 初始化服务客户端和任务运行器。
7. 注册模块的 `init_app` 和 `register_commands`。
8. 注册可选 SPA 路由。
9. 注册模块路由、权限元数据和菜单元数据。
10. 初始化服务层。

## 扩展组件

常用扩展从 `iti.applications.extensions` 引入：

```python
from iti.applications.extensions import db, migrate, jwt, limiter
from iti.applications.extensions import cache_simple, cache_redis, eventbus
```

框架还提供：

- `iti.applications.common.utils.success`
- `iti.applications.common.utils.fail`
- `iti.applications.common.utils.page`
- `iti.applications.common.utils.pagination_builder`

后台 API 默认使用响应 envelope：

```json
{"data": {}, "code": 200, "message": "成功"}
```

服务间 API 应使用真实 HTTP 状态码。

## 默认错误页

框架内置 `403`、`404`、`500` HTML 错误页。

请求更偏向 HTML 时返回模板页。
请求更偏向 JSON 时返回：

```json
{"data": null, "code": 404, "message": "Not Found"}
```

## SPA 静态目录

SPA 承载默认关闭。

业务项目开启后，框架从 `FRONTEND_PATH` 读取 `index.html` 和静态文件：

```python
FRONTEND_ENABLED = True
FRONTEND_PATH = "frontend/dist"
```

`FRONTEND_PATH` 可以是绝对路径。
相对路径按业务项目配置里的 `BASE_DIR` 解析。

## 扩展框架

业务项目通过模块扩展框架：

- 注册业务蓝图。
- 注册 CLI 命令。
- 声明权限元数据。
- 声明菜单 seed 元数据。
- 增加业务模型。
- 增加业务配置。
- 配置服务客户端。
- 注册任务。

框架问题在框架仓库修复，再发布新 tag。
业务项目不复制框架源码，也不覆盖框架 import path。