# Copier 模板

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

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

模板源文件是：

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

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

## 生成

```bash
./scripts/iti.sh make-app ../my-business-app my_business_app
cd ../my-business-app
./app.sh init
./app.sh serve 8000
```

Windows：

```bat
scripts\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` | 业务项目 Python 包名 |
| `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://`，但多人协作项目不建议依赖本机路径。

## 生成内容

- `app.py`
- `config.py`
- `pyproject.toml`
- `migrations/`
- 示例 FastAPI 模块
- 示例 SQLAlchemy 模型
- 示例测试
- `app.sh`
- `app.cmd`

## 系统业务

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

```bash
./app.sh init-system
```

Windows：

```bat
app.cmd init-system
```

## 生成项目脚本

模板会生成两份脚本：

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

常用命令：

```bash
./app.sh help
./app.sh install
./app.sh test
./app.sh serve 8000
./app.sh migration "alice add order table"
./app.sh migrate
```

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

带 `iti-system` 的项目还会有：

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

## 同步更新

业务项目同步框架依赖：

```bash
./app.sh framework-sync
```

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

业务项目检查模板版本：

```bash
./app.sh template-check
```

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

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

```bash
./app.sh template-update
```

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

模板拥有的文件包括 `app.py`、`config.py`、`app.sh`、`app.cmd`、`pyproject.toml`、`migrations/`、示例模块、示例测试、README 和项目 skill。
业务项目自己的模块、模型、API 文档和业务 README 由业务项目维护。