# iTi-Flask 架构重构计划

## 目标

把当前仓库整理成可被多个业务项目长期复用的后端基座。

第一阶段采用 hard-cut 重构。
不保留当前未成型框架形态的兼容行为。

## 第一阶段范围

第一阶段必须产出可运行的基础能力，而不是只写文档。

交付内容：

- `pyproject.toml` 成为依赖真相源。
- 不使用 Hatch 管理环境，统一使用 `uv`。
- Python 基线调整为 `>=3.11`。
- ERP 从 core 默认初始化中移出。
- 前端 `static/dist` 从框架包内容中移出。
- 运行时文件和生成物被忽略。
- Alembic migration 文件名模板包含日期、时间、revision 和 message slug。
- module protocol 可用，并能注册业务模块。
- 运行时插件加载保留，但定位为部署时插件能力。
- HTTP JSON service client 可用。
- 单进程 task registry 和 runner 可用。
- Python system seed 命令可用。
- 最小 Copier 模板可用。
- 边界文档完成更新。

## 第一阶段文件计划

打包配置：

- `pyproject.toml`
- `.gitignore`

框架边界：

- `iti/applications/__init__.py`
- `iti/applications/extensions/__init__.py`
- `iti/applications/extensions/plugins.py`
- `iti/applications/routes/__init__.py`
- `iti/applications/service/__init__.py`

新增模块支持：

- `iti/modules/__init__.py`
- `iti/modules/base.py`
- `iti/modules/registry.py`

新增服务客户端：

- `iti/service_client/__init__.py`
- `iti/service_client/config.py`
- `iti/service_client/client.py`
- `iti/service_client/errors.py`
- `iti/service_client/registry.py`

新增任务支持：

- `iti/tasks/__init__.py`
- `iti/tasks/registry.py`
- `iti/tasks/runner.py`

seed 和命令：

- `iti/cli.py`
- `iti/seeds/__init__.py`
- `iti/seeds/system.py`

模板：

- `copier-template/copier.yml`
- `copier-template/pyproject.toml.jinja`
- `copier-template/app.py.jinja`
- `copier-template/config.py.jinja`
- `copier-template/modules/example/*`
- `copier-template/models/example/*`
- `copier-template/tests/*`
- `copier-template/.gitignore`
- `copier-template/README.md.jinja`

文档：

- `docs/FRAMEWORK_BOUNDARY.md`
- `docs/ARCHITECTURE_REFACTOR_PLAN.md`
- `docs/MIGRATIONS.md`
- `docs/SERVICE_CLIENT.md`
- `docs/TASKS.md`
- `docs/SEEDS.md`

## 打包规则

运行依赖放到 `[project.dependencies]`。
可选集成放到 `[project.optional-dependencies]`。

核心依赖只覆盖框架运行需要。
云存储、ODBC、Excel、图片处理和开发工具都放到 extras。

推荐 extras：

- `mysql`
- `storage-aliyun`
- `storage-tencent`
- `storage-qiniu`
- `storage-huawei`
- `storage-s3`
- `storage-minio`
- `erp`
- `excel`
- `image`
- `dev`

## 迁移规则

每个业务项目只有一条 migration 流。

迁移文件必须提交。
`migrations/versions` 不忽略。

文件名模板：

```ini
file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
```

migration message 第一个词是作者名，后面自由描述：

```bash
uv run python -m flask --app app.py db migrate -m "alice add workorder priority"
```

生产只从 `main` 执行迁移。

## 服务客户端规则

第一版只支持 HTTP JSON。

默认行为：

- 必须配置超时。
- 重试策略保守。
- 默认只重试幂等方法。
- 熔断可选。
- 服务失败使用真实 HTTP 状态码。
- trace id 会透传。

## 任务运行器规则

任务运行器是单进程能力。

适用场景：

- 小型定时同步任务。
- 手动触发的后台操作。
- ERP Gateway 在专用实例中做轮询。

它不是分布式任务平台。

## Seed 规则

系统 seed 使用 Python 代码。

seed 必须幂等。
seed 不得删除已有用户数据。
seed 不得重置已有管理员密码。

命令：

```bash
flask iti seed system
```

## 验证计划

第一阶段最低验证：

```bash
uv run --extra dev pytest
uv run --extra dev mypy
python -m flask --app iti/app.py --help
python -m flask --app iti/app.py iti --help
python -m flask --app iti/app.py db --help
```

如果可选依赖缺失，测试应跳过可选集成路径，而不是让核心框架检查失败。

v0.1.0 的 mypy 门禁只覆盖新增框架基础层。
历史系统域 model、schema、route 仍是动态 Flask / SQLAlchemy / Marshmallow 写法，不作为本阶段类型门禁。

## 第二阶段范围

第二阶段把第一阶段的可用能力收口成业务项目可复制的初始化流程。

状态：已完成。

交付内容：

- 框架 migration 源文件进入包内容。
- `flask iti migrations sync` 可用。
- system seed 对齐当前系统域默认数据。
- seed 使用 `ADMIN`、`COMMON`、系统菜单、系统配置。
- seed 不写入业务菜单。
- 无请求上下文时审计字段可安全写入。
- Copier 模板内置 migration 目录和初始化说明。
- 根 README 和 docs README 中文化。
- 新增迁移同步与 seed 幂等测试。

验证命令：

```bash
uv run --extra dev --extra mysql --extra image --extra excel pytest
```

当前结果：

```text
48 passed, 1 skipped
```

## 第三阶段建议

第三阶段应处理“业务项目真实接入”的问题。

建议范围：

- 用 Copier 生成一个临时业务项目并跑通初始化。
- 补 module 注册业务菜单、权限和 seed 扩展的正式协议。
- 补 service client 的 mock transport 测试和失败语义测试。
- 补 task runner 的调度与防重复执行测试。
- 明确 ERP Gateway 的独立仓库结构和 API 契约草案。

## 第三阶段范围

状态：已完成。

交付内容：

- 修复框架包环境文件加载边界。
- 框架包不再携带 `iti/.env*`。
- Copier 生成项目可跑通 migration sync、db upgrade、system seed。
- module 协议补充 `ModulePermission` 和 `ModuleMenuSeed`。
- `flask iti seed system` 支持写入模块菜单 seed。
- service client 覆盖 token、trace、重试、非 2xx、熔断测试。
- task runner 覆盖成功、失败、防重复执行和调度解析测试。
- ERP Gateway 契约草案成文。

第三阶段验证命令：

```bash
uv run --extra dev --extra mysql --extra image --extra excel pytest
```

模板验证：

```bash
uvx copier copy -l /path/to/copier-template /tmp/iti-flask-template-check
uv run --refresh-package iti-flask python -m flask --app app.py iti migrations sync
uv run --refresh-package iti-flask python -m flask --app app.py db upgrade
uv run --refresh-package iti-flask python -m flask --app app.py iti seed system
uv run --refresh-package iti-flask --with pytest pytest
```

当前结果：

```text
仓库测试：61 passed, 1 skipped
模板测试：1 passed
```

## 当前收口结果

状态：已完成。

本轮处理：

- 版本号统一为 `0.1.0`。
- `pyproject.toml` 只保留一套项目管理配置。
- `hatch.toml` 已移除。
- `uv.lock` 作为本地解析结果处理，不进入框架仓库版本控制。
- v0.1.0 mypy 门禁已建立。
- ERP Gateway 已定位为 iTi-Flask 仓库外的独立业务项目。

验证结果：

```text
uv run --extra dev mypy
Success: no issues found in 13 source files

uv run --extra dev --extra mysql --extra image --extra excel pytest
61 passed, 1 skipped

iTi-ERP-Gateway: uv run --extra dev pytest
4 passed

ERP Gateway 正式依赖 iTi-Flask Git tag。
本地验证时临时把依赖替换为 `/root/Projects/iTi/iTi-Flask`。

Copier 模板初始化验证
1 passed

python -m build
生成 iti_flask-0.1.0.tar.gz 和 iti_flask-0.1.0-py3-none-any.whl
```