# iTi-Flask 框架边界

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

它不是业务应用。
它不是微服务平台。
它不是前端发布包。

## 包和模板

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

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

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

## 核心职责

框架负责：

- 应用工厂。
- 配置加载。
- APIFlask 集成。
- SQLAlchemy、迁移、缓存、限流、JWT、日志、错误处理集成。
- 系统域 API。
- 模块协议。
- 运行时插件加载。
- HTTP JSON 服务客户端。
- 单进程任务注册表和运行器。
- 框架系统种子数据。
- 框架迁移同步辅助能力。

## 系统域

系统域属于框架核心，并默认启用。

系统域包括：

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

业务项目可以直接使用用户扩展属性。
不需要额外声明属性使用范围。

## 扩展规则

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

允许：

- 注册业务模块。
- 跨模块调用时只调用公开 facade 函数。
- 注册业务蓝图。
- 注册业务权限和菜单。
- 在业务项目中增加业务模型。
- 使用用户扩展属性。
- 配置服务和插件。
- 安装框架 optional extras。

禁止：

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

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

## 模块和服务

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

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

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

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

ERP 是服务候选。
它应当作为 ERP Gateway 服务存在，不属于框架核心。

模块菜单可以通过 `ModuleMenuSeed` 声明。
`flask iti seed system` 会把模块菜单写入系统菜单表，并默认绑定给 `ADMIN`。
模块权限通过 `ModulePermission` 声明，实际授权仍然由菜单 `auth_code` 生效。

## 服务客户端边界

第一版服务客户端只支持 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` 执行迁移。

框架系统迁移会同步到业务项目 migration 流。
生产应只执行一个命令：

```bash
flask db upgrade
```

## 分支规则

推荐分支模型：

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

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

## 种子数据规则

框架 seed 代码只初始化系统域数据。

seed 规则：

- 只用 Python seed。
- 必须幂等。
- 只写系统数据。
- 可以写入模块声明的菜单 seed。
- 按唯一键 upsert。
- 不删除用户数据。
- 不重置已有管理员密码。
- 输出变更摘要。

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

## 生成物

仓库不应跟踪：

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