---
name: iti-flask-framework
description: iTi-Flask 框架 skill。用于当前 iTi-Flask 框架仓库内的框架代码、框架文档、Copier 模板行为、应用工厂、配置、模块协议、鉴权、响应 envelope、服务客户端、任务、迁移、审计、存储、日志、测试和发布打包。不要用于 iTi-System 系统域业务修改，也不要用于模板生成项目的具体业务逻辑。
---

# iTi-Flask 框架

只用于 iTi-Flask 框架仓库。

iTi-Flask 是 FastAPI 后端框架基座。

## 边界

- iTi-Flask 只写框架能力。
- 不把系统域业务放进框架。
- 不把具体模板生成项目写成框架行为。
- `iti-system` 是外部可选系统业务包。
- Copier 模板会为生成项目渲染独立项目 skill。

## 代码入口

- `iti/app.py`：`create_app`、中间件、错误处理、自动 envelope、生命周期。
- `iti/config.py`：dataclass 配置、`.env` 加载、MySQL 默认值。
- `iti/db/*`：SQLAlchemy 2 base/session、Alembic metadata。
- `iti/auth/*`：JWT、Principal、Actor、权限依赖、服务 token 依赖。
- `iti/modules/*`：模块协议、权限元数据、菜单 seed 元数据。
- `iti/responses/*`：envelope、raw response 逃逸。
- `iti/service_client/*`：同步 HTTP JSON 客户端和注册表。
- `iti/tasks/*`：单进程任务注册和 runner。
- `iti/audit.py`：审计事件发送器，不拥有系统日志表。
- `iti/storage/*`：存储后端接口和实现。
- `copier-template/`：业务项目模板。
- `docs/`：人类阅读的精简参考。

## 修改规则

- 先读现有代码，再改文档或行为。
- 配置继续使用当前 dataclass 风格。
- JSON API 默认兼容 envelope，除非路由明确 raw。
- 保留 raw 默认值：`/health`、`/ready`、`/docs`、`/openapi.json`。
- `/docs` 是文档入口，按 `docs_ui_enabled` 展示 Swagger、Scalar、ReDoc 等已启用 UI。
- 模块元数据使用 `ModulePermission` 和 `ModuleMenuSeed`。
- migration 归生成项目所有。框架不要静默接管业务项目 migration 流。
- 审计保持异步、非阻塞。框架只发事件，接收方在框架外。
- 不为未发生的需求加宽泛兼容层。

## 模板规则

- 模板变更在 `copier-template/`。
- Copier 模板源入口是仓库根目录 `copier.yml`，实际模板目录由 `_subdirectory: copier-template` 指定。
- 模板输出保持通用 FastAPI 业务后端骨架。
- 模板内不要写具体业务域知识。
- 模板结构、命令或生成文件变化时，同步更新：
  - `copier.yml`
  - `copier-template/README.md.jinja`
  - `docs/COPIER_TEMPLATE.md`
  - `copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md.jinja`
  - 需要保持一致的已生成项目 skill 副本
- 生成项目必须保留 `.copier-answers.yml`，否则不能用 `copier update` 同步模板。
- 已生成项目同步框架依赖用 `./app.sh framework-sync`。
- 已生成项目检查和同步模板用 `./app.sh template-check`、`./app.sh template-update`。

## 命令

- 安装框架开发依赖：`./scripts/iti.sh install`
- 运行框架测试：`./scripts/iti.sh test`
- 运行检查：`./scripts/iti.sh check`
- 启动最小应用：`./scripts/iti.sh serve 8000`
- 生成业务项目：`./scripts/iti.sh make-app ../my-business-app my_business_app`
- 生成带系统包的业务项目：`./scripts/iti.sh make-system-app ../my-system-app my_system_app`

Windows 使用 `scripts\iti.cmd`。

## 文档

人类文档保持短。
文档只放稳定事实和命令入口。
细节优先从代码确认。

代码、架构、命令、模块协议、模板输出或验证流程变化时，同步更新这个 skill。