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 是给多个业务项目复用的轻量后端基座。
它不是业务应用。
它不是微服务平台。
它不是前端发布包。
## 包和模板
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
```
## 分支规则
推荐分支模型：
- `main` ：只用于生产发布。
- `dev` ：集成分支。
- `user/<name>` ：个人开发分支。
`dev` 发布前必须收敛成一个 migration head。
生产不能从个人分支发布。
## 种子数据规则
框架 seed 代码只初始化系统域数据。
seed 规则：
- 只用 Python seed。
- 必须幂等。
- 只写系统数据。
- 可以写入模块声明的菜单 seed。
- 按唯一键 upsert。
- 不删除用户数据。
- 不重置已有管理员密码。
- 输出变更摘要。
运行时数据库不是源码资产。
## 生成物
仓库不应跟踪：
- 运行时数据库。
- 前端构建产物。
- `__pycache__` 。
- 测试缓存。
- 覆盖率产物。