|
|
---
|
|
|
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`。
|
|
|
- 模板项目的 Alembic 命令必须显式使用 `-c migrations/alembic.ini`。
|
|
|
- 模板项目的测试命令使用 `uv run --extra dev pytest -q`，避免未安装 dev extra 时找不到 pytest。
|
|
|
|
|
|
## 命令
|
|
|
|
|
|
- 安装框架开发依赖：`./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。
|