iTi-Flask/docs/FRAMEWORK_BOUNDARY.md

iTi-Flask 框架边界

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

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

包和模板

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

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：

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

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

数据库规则

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

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

生产应只执行一个命令：

flask db upgrade

分支规则

推荐分支模型：

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

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

种子数据规则

iTi-Flask 不提供系统 seed。

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

seed 代码必须：

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

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

生成物

仓库不应跟踪：

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

SPA 承载

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

业务项目可以配置：

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

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