iTi-Flask/docs/ARCHITECTURE_REFACTOR_PLAN.md

架构重构决策日志

当前决策

iTi-Flask 收敛为框架底座。 系统业务拆到独立包 iti-system。 ERP Service 作为独立业务项目，只依赖 iti-flask。

当前整体形态：

• iTi-Flask：框架基座。
• iTi-System：可选系统业务包。
• erp-service：ERP 中转服务。
• MES 主项目：按需依赖 iti-flask + iti-system。

iTi-Flask 边界

保留：

• 应用工厂。
• 配置加载。
• APIFlask 集成。
• SQLAlchemy / Flask-Migrate。
• JWT 基础集成。
• 缓存、限流、日志、错误处理。
• module 协议。
• service client。
• 单进程 task runner。
• 可选 SPA 静态目录承载。
• Copier 业务项目模板。

移出：

• sys_* 模型。
• 系统路由。
• 系统 service。
• 系统 seed。
• 系统 migration。
• 系统事件处理器。
• 权限校验装饰器。
• 系统日志入库扩展。

iTi-System 边界

iti-system 提供系统域能力：

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

业务项目只决定是否引入 iti-system。 引入即全量引入。 不提供 profile。 不提供系统模块选择。 不拆分系统 migration。

示例：

from iti_system import create_system_module

modules = [
    create_system_module(),
]

微服务边界

当前不是强微服务平台。

不做：

• 服务注册发现。
• Kubernetes service mesh。
• 分布式事务。
• Saga。
• gRPC。
• 消息总线全家桶。
• 自动弹性伸缩。
• 多租户网关。

保留轻量服务协作：

• HTTP JSON。
• service token。
• 超时。
• 保守重试。
• 可选熔断。
• trace id 透传。

ERP Service 决策

ERP Service 不属于框架。 它是独立业务项目。

职责：

• 调用既有 Monitor ERP API。
• 调用既有 Monitor ERP ODBC 数据源。
• 承担必要的 ERP 数据同步任务。
• 对其它业务项目提供 HTTP JSON 中转能力。

它不依赖 iti-system。 它不共享 MES 系统库。

数据库和迁移

每个业务项目只保留一条 Alembic migration 流。

iTi-Flask 不提供系统 migration。 需要系统能力时，由 iti-system 同步系统 migration：

uv run python -m flask --app app.py iti-system migrations sync
uv run python -m flask --app app.py db upgrade

iti-system 系统迁移是全量系统表集合。 不按 auth、user、role 等能力拆分。 轻服务不需要系统表时，直接不依赖 iti-system。

Seed

iTi-Flask 不提供系统 seed。

iti-system 提供系统 seed：

uv run python -m flask --app app.py iti-system seed system

业务 seed 由业务项目自己维护。

当前实施状态

已完成：

• iTi-Flask 移除系统域代码。
• iTi-Flask 移除系统 seed 和系统 migration 命令。
• iTi-Flask 保留默认 HTML 错误页。
• iTi-Flask 保留可配置 SPA 承载。
• iTi-System 独立成包。
• iTi-System 提供全量系统包注册入口。
• iTi-System 提供系统 seed 命令。
• iTi-System 提供系统 migration 同步命令。
• ERP Service 文档去掉系统 seed / migration 初始化步骤。
• 三个项目都改为 uv 虚拟环境工作流。

验证结果：

iTi-Flask: 60 passed
iTi-System: 7 passed
erp-service: 4 passed