# iTi-Flask 框架边界

iTi-Flask 是给多个业务项目复用的轻量后端基座。

它不是业务应用。
它不是微服务平台。
它不是前端发布包。
它可以按配置承载业务项目自己的 SPA 静态目录。
框架包本身不携带前端构建产物。

## 包和模板

iTi-Flask 以 Python 包发布。
业务项目依赖 Git tag：

```toml
dependencies = [
  "iti-flask @ git+https://git.noahlan.cn/iti-framework/iTi-Flask.git@v0.1.1",
]
```

Copier 只负责生成项目骨架。
模板不会把框架源码复制到业务项目里。

## 核心职责

框架负责：

- 应用工厂。
- 配置加载。
- APIFlask 集成。
- SQLAlchemy、迁移、缓存、限流、JWT、日志、错误处理集成。
- 模块协议。
- 运行时插件加载。
- HTTP JSON 服务客户端。
- 单进程任务注册表和运行器。
- 可选 SPA 静态目录承载。

框架不负责：

- 系统域业务。
- `sys_*` 表。
- 系统域迁移。
- 系统域 seed。
- ERP 中转能力。
- 统一网关。
- 服务注册发现。
- 前端构建产物。

## 系统域

系统域不属于 iTi-Flask。
系统域放在独立包 `iti-system`。

`iti-system` 可以提供：

- 认证。
- 用户。
- 角色。
- 菜单。
- 部门。
- 字典。
- 系统配置。
- 文件。
- 审计日志。
- 用户扩展属性。

业务项目是否引入系统域，由业务项目依赖和 `modules=[create_system_module()]` 注册决定。
`iti-system` 引入即全量引入。
不提供系统模块选择。
不拆分系统 migration。
不引入 `iti-system` 时，不会有系统路由、系统模型、系统 migration、系统 seed。

ERP Service 这类服务不依赖 `iti-system`。
MES 这类主业务项目可以依赖 `iti-flask + iti-system`。
A 工厂 MES 和 B 工厂 MES 可以各自独立部署，各自使用自己的数据库。
这不是多租户。

## 扩展规则

业务项目只能扩展框架。
不能修改或覆盖框架实现。

允许：

- 注册业务模块。
- 跨模块调用时只调用公开 facade 函数。
- 注册业务蓝图。
- 注册业务权限和菜单元数据。
- 在业务项目中增加业务模型。
- 配置服务和插件。
- 安装框架 optional extras。
- 按需安装 `iti-system`。

禁止：

- 复制并修改框架模块。
- 导入其它模块的内部 model、repository 或私有 service 层。
- shadow 框架 import path。
- monkey patch 框架函数。
- 直接修改已安装的包源码。

框架问题必须在框架仓库修复，并通过新的 Git tag 发布。

## 模块和服务

模块是代码边界。
模块运行在同一个 Flask 进程内。

服务是部署边界。
服务通过 HTTP JSON 调用。

默认使用模块。
只有同时满足以下条件时，才拆成服务：

- 至少两个业务项目需要复用这个能力。
- 该能力有外部系统、独立数据源或独立发布诉求。
- 业务项目不应该理解该能力的内部细节。

ERP 是服务。
它应当作为 ERP Service 独立项目存在，不属于框架核心。

## 服务客户端边界

第一版服务客户端只支持 HTTP JSON。

提供：

- base URL 配置。
- service token 鉴权。
- 超时。
- 保守重试。
- 可选熔断。
- trace id 透传。
- 结构化调用日志。
- JSON 编码和解码。
- 测试用 mock transport。

不提供：

- 服务发现。
- 负载均衡。
- gRPC。
- streaming。
- async client。
- service mesh。

## 任务运行器边界

第一版任务运行器是单进程能力。

提供：

- 任务注册。
- 手动触发。
- interval 和简单 cron-like 调度。
- 单进程内防重复执行。
- 运行日志。
- 状态查询。

不提供：

- 分布式锁。
- 多实例 exactly-once。
- 默认 Celery 或 RQ。

多进程生产部署时，只在一个专用实例中启用 scheduler。

## API 状态码规则

面向后台前端的 API 可以保留现有响应 envelope：

```json
{"code": 200, "message": "success", "data": {}}
```

服务间 API 必须使用真实 HTTP 状态码。
服务客户端依赖状态码做重试、熔断和监控判断。

## 数据库规则

业务项目只保留一条 migration 流。
迁移文件必须提交到 Git。
生产只从 `main` 执行迁移。

引入 `iti-system` 的业务项目，由 `iti-system` 同步系统迁移到业务项目 migration 流。
不引入 `iti-system` 的业务项目，不同步系统迁移。

生产应只执行一个命令：

```bash
flask db upgrade
```

## 分支规则

推荐分支模型：

- `main`：只用于生产发布。
- `dev`：集成分支。
- `user/<name>`：个人开发分支。

`dev` 发布前必须收敛成一个 migration head。
生产不能从个人分支发布。

## 种子数据规则

iTi-Flask 不提供系统 seed。

业务 seed 放在业务项目。
系统 seed 放在 `iti-system`。

seed 代码必须：

- 只用 Python seed。
- 幂等。
- 按唯一键 upsert。
- 不删除用户数据。
- 不重置已有管理员密码。
- 输出变更摘要。

运行时数据库不是源码资产。

## 生成物

仓库不应跟踪：

- 运行时数据库。
- 前端构建产物。
- `__pycache__`。
- 测试缓存。
- 覆盖率产物。

## SPA 承载

框架内置 SPA 承载能力，但默认关闭。

业务项目可以配置：

```python
FRONTEND_ENABLED = True
FRONTEND_PATH = "/path/to/business/dist"
```

`FRONTEND_PATH` 指向业务项目自己的前端构建目录。
相对路径按业务项目配置里的 `BASE_DIR` 解析。
框架不会内置 `static/dist`。