# {{ project_name }}

FastAPI 业务后端项目。
由 iTi-Flask Copier 模板生成。

AI 修改本项目时优先读：

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

该 skill 只描述本项目的通用工程规则。
具体业务知识写在本项目自己的 README/docs。

## 依赖

默认使用私有 Git 依赖。
推荐固定 tag，也允许 branch。
`file://` 只建议框架开发者本机验证模板时使用。

## 初始化

```bash
./app.sh init
```

Windows：

```bat
app.cmd init
```

{% if include_system %}
同步系统 migration 和 seed：

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

Windows：

```bat
app.cmd init-system
```
{% endif %}

## 开发

```bash
./app.sh serve
./app.sh test
```

不同环境直接在命令前设 `APP_ENV`，或把环境名作为 `serve` 的第一个参数：

```bash
./app.sh serve
./app.sh serve test 8000
APP_ENV=prod ./app.sh migrate
```

## 同步更新

同步框架包：

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

检查模板：

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

按模板更新项目骨架：

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

模板更新会改 `main.py`、`config.py`、`app.sh`、`app.cmd`、示例模块、测试和项目 skill 等模板拥有的文件。
该命令跟随模板仓库 `HEAD`。
执行前先提交或暂存当前项目改动，执行后检查 diff。

## 数据库迁移

```bash
./app.sh migration "alice add example table"
./app.sh migrate
```

规则：

- `migrations/versions` 必须提交。
- migration message 第一个词写作者名。
- 生产只从 `main` 执行 `alembic -c migrations/alembic.ini upgrade head`。