--- 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 业务后端骨架。 - 模板生成项目固定使用 `app/` 作为 Python 顶层包，ASGI 入口固定为 `main.py`。 - 模板内不要写具体业务域知识。 - 模板结构、命令或生成文件变化时，同步更新： - `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` 同步模板。 - 已生成项目同步框架依赖用 `iticli sync flask`。 - 已生成项目检查和同步模板用 `iticli template check`、`iticli template update`。 - 模板项目的 Alembic 命令必须显式使用 `-c migrations/alembic.ini`。 - 模板项目的测试命令使用 `uv run --extra dev pytest -q`，避免未安装 dev extra 时找不到 pytest。 ## 命令 - 安装框架开发依赖：`iticli install` - 运行框架测试：`iticli test` - 启动最小应用：`iticli run dev 8000` - 生成业务项目：`iticli create ../my-business-app` - 生成带系统包的业务项目：`iticli create --with-system ../my-system-app` - 发布框架：`iticli release` 框架仓库不再维护 `.sh` / `.cmd` 脚本。 模板生成业务项目不再包含 `app.sh`、`app.cmd`。 ## 文档 人类文档保持短。 文档只放稳定事实和命令入口。 细节优先从代码确认。 代码、架构、命令、模块协议、模板输出或验证流程变化时，同步更新这个 skill。