# {{ 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
cp .env.example .env
./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
```

## Docker

```bash
cp .env.example .env
./app.sh docker-up
./app.sh docker-logs
./app.sh docker-down
```

`docker-compose.yml` 默认只启动应用，数据库使用外部 MySQL。
需要本地 MySQL 时使用：

```bash
./app.sh docker-up-db
./app.sh docker-down-db
```

应用容器启动时会先执行 migration{% if include_system %} 和系统 seed{% endif %}。
本地运行数据写入 `runtime/`，MySQL 数据写入 Compose volume。

## 同步更新

同步框架包：

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

检查模板：

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

按模板更新项目骨架：

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

模板更新会改 `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`、示例模块、测试和项目 skill 等模板拥有的文件。
该命令跟随模板仓库 `HEAD`。
执行前先提交或暂存当前项目改动，执行后检查 diff。

## VSCode 调试

模板内置 `.vscode/launch.json`。
选择 `{{ project_name }}: FastAPI` 即可用 `uvicorn main:app --reload` 调试。

## 数据库迁移

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

规则：

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