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。

生成

./iti.sh make-app ../my-business-app my-business-app
cd ../my-business-app
cp .env.example .env
./app.sh init
./app.sh serve 8000

Windows：

iti.cmd make-app ..\my-business-app my-business-app
cd ..\my-business-app
app.cmd init
app.cmd serve 8000

参数

参数	说明
project_name	业务项目显示名称
project_slug	业务项目发行包名来源
framework_git	iTi-Flask Git 地址
framework_tag	iTi-Flask Git tag
include_system	是否引入 iTi-System
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 模型
• 示例测试
• app.sh
• app.cmd

系统业务

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

./app.sh init-system

Windows：

app.cmd init-system

生成项目脚本

模板会生成两份脚本：

• app.sh：Linux / macOS / Git Bash。
• app.cmd：Windows CMD。

常用命令：

./app.sh help
./app.sh install
./app.sh test
./app.sh serve 8000
./app.sh docker-up
./app.sh docker-up-db
./app.sh docker-logs
./app.sh docker-down
./app.sh docker-down-db
./app.sh migration "alice add order table"
./app.sh migrate

app.sh / app.cmd 内部使用项目自己的 migrations/alembic.ini。

带 iti-system 的项目还会有：

./app.sh system-sync
./app.sh system-seed
./app.sh init-system

同步更新

业务项目同步框架依赖：

./app.sh framework-sync

该命令执行 uv sync --upgrade-package iti-flask。 带 iti-system 的模板项目会同时升级 iti-system。

业务项目检查模板版本：

./app.sh template-check

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

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

./app.sh 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、app.sh、app.cmd、pyproject.toml、migrations/、示例模块、示例测试、README 和项目 skill。 业务项目自己的模块、模型、API 文档和业务 README 由业务项目维护。

Docker

模板生成：

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

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

VSCode

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