You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.
# 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
```
## 分支规则
推荐分支模型：
- `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` 。