iTi-Flask/.codex/skills/iti-flask-framework/SKILL.md

name	description
iti-flask-framework	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 加载、数据库默认连接串。
• 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 update framework。
• 已生成项目检查和同步模板用 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。