4.5 KiB
iTi-Flask 框架边界
iTi-Flask 是给多个业务项目复用的轻量后端基座。
它不是业务应用。 它不是微服务平台。 它不是前端发布包。
包和模板
iTi-Flask 以 Python 包发布。 业务项目依赖 Git tag：
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：
{"code": 200, "message": "success", "data": {}}
服务间 API 必须使用真实 HTTP 状态码。 服务客户端依赖状态码做重试、熔断和监控判断。
数据库规则
业务项目只保留一条 migration 流。
迁移文件必须提交到 Git。
生产只从 main 执行迁移。
框架系统迁移会同步到业务项目 migration 流。 生产应只执行一个命令：
flask db upgrade
分支规则
推荐分支模型：
main：只用于生产发布。dev：集成分支。user/<name>：个人开发分支。
dev 发布前必须收敛成一个 migration head。
生产不能从个人分支发布。
种子数据规则
框架 seed 代码只初始化系统域数据。
seed 规则：
- 只用 Python seed。
- 必须幂等。
- 只写系统数据。
- 可以写入模块声明的菜单 seed。
- 按唯一键 upsert。
- 不删除用户数据。
- 不重置已有管理员密码。
- 输出变更摘要。
运行时数据库不是源码资产。
生成物
仓库不应跟踪：
- 运行时数据库。
- 前端构建产物。
__pycache__。- 测试缓存。
- 覆盖率产物。