---
name: {{ project_slug | lower | replace('_', '-') }}-project
description: "{{ project_name }} 业务项目 skill。用于当前由 iTi-Flask Copier 模板生成的业务后端项目，包括 main.py、config.py、app.sh/app.cmd、pyproject.toml、migrations、tests、modules、models、服务客户端、iTi-Flask 集成{% if include_system %}、iTi-System 注册{% endif %}和项目本地文档。不要写入具体业务域知识。"
---

# {{ project_name }} 业务项目

用于当前业务项目。
本项目由 iTi-Flask Copier 模板生成。

这个 skill 只描述当前项目的通用工程结构。
具体业务知识写在项目 README/docs 或对应业务模块文档里。

## 边界

- 保持为当前业务后端项目的工程规则。
- 不加入具体业务域或客户专属业务知识。
- 框架行为看 iTi-Flask 依赖和项目当前代码。
{% if include_system -%}
- 系统域能力来自 iTi-System，当前项目已注册系统包。
{% else -%}
- 当前项目未默认注册 iTi-System。需要系统域能力时再显式引入。
{% endif -%}
- 修改代码、架构、目录结构、脚本命令或测试方式后，同步更新这个 skill。
- 同步框架依赖用 `./app.sh framework-sync`。
- 检查和同步框架模板用 `./app.sh template-check`、`./app.sh template-update`。

## 项目结构

- `main.py`：ASGI 入口，导出 `app`。
- `app/app_factory.py`：导入 `config`，注册模块，创建 FastAPI app。
- `config.py`：项目本地配置映射。
- `app/modules/`：业务模块。
- `app/models/`：项目 SQLAlchemy 模型。
- `migrations/`：项目自己的 Alembic migration 流。
- `tests/`：pytest 路由和行为测试。
- `app.sh`：Linux/macOS/Git Bash 命令入口。
- `app.cmd`：Windows CMD 命令入口。
- `Dockerfile`：容器镜像构建入口。
- `docker-compose.yml`：本地 Compose 部署入口。
- `docker-compose.with-db.yml`：本地 MySQL 叠加部署入口。
- `.env.example`：本地和 Compose 环境变量样例。
- `.vscode/launch.json`：VSCode FastAPI 调试配置。
- `.dockerignore`：Docker 构建排除规则。
- `pyproject.toml`：包信息和依赖。
- `.copier-answers.yml`：Copier 模板更新锚点。

## 模块模式

业务模块通过 iTi 模块协议注册：

- `register_routes(app)`：挂载 FastAPI router。
- `register_permissions(app)`：用 `ModulePermission` 声明权限元数据。
- `register_menu_seed(app)`：用 `ModuleMenuSeed` 声明后台菜单 seed 元数据。
- `register_tasks(app)`：按需注册本地任务。
- `init_app(app)`：按需接入配置或服务客户端。

业务模块优先放在 `app/modules/<module_name>/`。

## 运行规则

- 业务路由放在项目模块内。
- 项目表和 migration 留在当前项目。
- 默认使用框架 envelope，除非路由明确 raw。
- 服务间内部 API 使用 service token。
- 项目级测试使用 `fastapi.testclient.TestClient`。
- 请求体使用 Pydantic schema。
{{ "- seed 前先同步 iTi-System migration。\n" if include_system else "" }}

## 命令

- 安装开发依赖：`./app.sh install`
- 同步框架依赖：`./app.sh framework-sync`
- 检查模板更新：`./app.sh template-check`
- 同步模板骨架：`./app.sh template-update`
- 运行测试：`./app.sh test`
- 本地启动：`./app.sh serve 8000`
- 构建 Docker 镜像：`./app.sh docker-build`
- 启动 Docker Compose：`./app.sh docker-up`
- 启动 Docker Compose 和 MySQL：`./app.sh docker-up-db`
- 停止 Docker Compose：`./app.sh docker-down`
- 停止 Docker Compose 和 MySQL：`./app.sh docker-down-db`
- 查看应用容器日志：`./app.sh docker-logs`
- 创建 migration：`./app.sh migration "alice add order table"`
- 执行 migration：`./app.sh migrate`
- 查看 Alembic heads：`./app.sh heads`
- 查看当前 Alembic 版本：`./app.sh current`
- 初始化项目：`./app.sh init`

{{ "系统包相关命令：\n\n- 同步系统 migration：`./app.sh system-sync`\n- 初始化或更新系统 seed：`./app.sh system-seed`\n- 初始化系统项目：`./app.sh init-system`\n\n" if include_system else "" -}}
Windows 使用 `app.cmd`。