iTi-Flask/docs/COPIER_TEMPLATE.md

Copier 模板

当前框架仓库根目录是 Copier 模板源。 copier.yml 通过 _subdirectory: copier-template 指向实际模板目录。 copier-template 生成 FastAPI 业务后端骨架。 模板只引用框架包，不复制框架源码。 模板会为生成项目渲染项目 skill。 生成后的路径是：

.codex/skills/<project-slug>-project/SKILL.md

模板源文件是：

copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md.jinja

模板结构、脚本命令或模块约定变化时，同步更新该模板 skill。 现有模板生成项目需要按当前项目名刷新自己的 skill。

生成

iticli create ../my-business-app
iticli create --database postgresql ../my-postgres-app
cd ../my-business-app
cp .env.example .env
iticli init
iticli run dev 8000

Windows：

iticli create ..\my-business-app
cd ..\my-business-app
iticli init
iticli run dev 8000

参数

参数	说明
project_name	业务项目显示名称
project_slug	业务项目发行包名来源
framework_git	iTi-Flask Git 地址
framework_tag	iTi-Flask Git tag
include_system	是否引入 iTi-System
database_dialect	默认数据库类型，mysql 或 postgresql
system_git	iTi-System Git 地址
system_tag	iTi-System Git tag

默认推荐私有 Git tag。 允许改成 branch 或 file://，但多人协作项目不建议依赖本机路径。

生成内容

• main.py
• app/app_factory.py
• config.py
• pyproject.toml
• migrations/
• Dockerfile
• docker-compose.yml
• docker-compose.with-db.yml
• .dockerignore
• .vscode/launch.json
• .env.example
• 示例 FastAPI 模块
• 示例 SQLAlchemy 模型
• 示例测试

系统业务

选择 include_system=true 时，模板会注册 create_system_module()。 生成后执行：

iticli init system

Windows：

iticli init system

命令

常用命令：

iticli help
iticli install
iticli test
iticli run dev 8000
iticli docker up
iticli docker up --db
iticli docker logs
iticli docker down
iticli docker down --db
iticli migrate revision "alice add order table"
iticli migrate

iticli migrate 在业务项目内使用项目自己的 migrations/alembic.ini。

带 iti-system 的项目还会有：

iticli update system
iticli init system

同步更新

业务项目同步框架依赖：

iticli update framework

该命令会更新 pyproject.toml 中的框架 tag，并执行 uv sync --upgrade-package iti-flask。 需要同时升级框架和系统包时使用 iticli update all。

业务项目检查模板版本：

iticli template check

该命令执行 uvx copier update --defaults --pretend --vcs-ref HEAD。

业务项目按模板更新项目骨架：

iticli template update

该命令执行 uvx copier update --defaults --vcs-ref HEAD。 它依赖 .copier-answers.yml 里的 _src_path 和 _commit。 模板更新前，业务项目工作区必须干净。 执行后检查 diff，再运行测试。

模板拥有的文件包括 main.py、app/app_factory.py、config.py、Dockerfile、docker-compose.yml、docker-compose.with-db.yml、.dockerignore、.env.example、.vscode/launch.json、pyproject.toml、migrations/、示例模块、示例测试、README 和项目 skill。 业务项目自己的模块、模型、API 文档和业务 README 由业务项目维护。

Docker

模板生成：

• Dockerfile：基于 python:3.11-slim，使用 uv sync --frozen --no-dev 安装运行依赖。
• docker-compose.yml：启动应用，默认连接外部数据库。
• docker-compose.with-db.yml：按 database_dialect 叠加启动 MySQL 8.4 或 PostgreSQL 16。
• .env.example：Compose 和本地运行共用的环境变量样例。
• .dockerignore：排除虚拟环境、运行数据和本地密钥。

应用容器启动时会执行业务 migration。 带 iti-system 的项目还会先同步 system migration，并执行 system seed。

VSCode

模板生成 .vscode/launch.json。 默认调试配置以 uvicorn main:app --reload 启动，使用 APP_ENV=dev。