---
name: iti-system-project
description: iTi-System 系统业务包 skill。用于当前 iTi-System 仓库内的认证、用户、角色、菜单、部门、字典、配置、文件、日志、用户扩展属性、系统 migration、seed、权限和 create_system_module 注册的路由。不要用于 iTi-Flask 框架内部，也不要用于模板生成项目的具体业务逻辑。
---

# iTi-System 项目

只用于 iTi-System 系统业务包。

iTi-System 通过 `create_system_module()` 注册到 iTi-Flask FastAPI 应用。

## 边界

- 这里只写系统域业务。
- 不重复 iTi-Flask 框架规则。
- 不放模板生成项目的业务逻辑。
- iTi-Flask 是宿主框架。

## 业务范围

iTi-System 拥有可复用后台系统能力：

- 认证。
- 用户。
- 角色。
- 菜单。
- 部门。
- 字典。
- 配置。
- 文件和上传。
- 日志查询和审计接收。
- 用户扩展属性。

## 代码入口

- `iti_system/module.py`：`SystemModule`、路由注册、权限元数据、菜单 seed 元数据。
- `iti_system/routes/`：系统接口路由。
- `iti_system/models/`：SQLAlchemy 模型。
- `iti_system/schemas.py`：请求和响应 schema。
- `iti_system/services.py`：系统域服务逻辑和权限 provider。
- `iti_system/seeds/system.py`：默认角色、用户、字典、配置、菜单、角色菜单关系，要求幂等。
- `iti_system/migrations/versions/`：同步到宿主项目的系统 migration。
- `iti_system/cli.py`：migration sync 和 seed 命令。

## 运行契约

宿主项目注册：

```python
from iti_system import create_system_module

app = create_app(config_mapping=config, modules=[create_system_module()])
```

注册后挂载系统路由，并把权限 provider 换成数据库实现。

主要路由根：

- `/auth`
- `/sys/user`
- `/sys/role`
- `/sys/menu`
- `/sys/dept`
- `/sys/dict`
- `/sys/config`
- `/sys/file`
- `/sys/log`
- `/sys/user-attributes`
- `/upload`
- `/file`

## Migration 和 Seed

宿主项目拥有自己的 Alembic migration 流。
iTi-System 提供可同步的系统 migration：

```bash
uv run iti-system migrations sync --target migrations/versions
uv run alembic upgrade head
uv run iti-system seed system app:app
```

seed 必须可重复执行。
已有管理员不重置。

## 修改规则

- 权限码放在 `SYSTEM_PERMISSIONS`。
- 菜单 seed 放在 `SYSTEM_MENU_SEEDS`。
- 默认 seed 数据放在 `iti_system/seeds/system.py`。
- 运行时权限判断以数据库状态为准。
- 不改路由组和前缀，除非同步更新所有调用方。
- 不把 envelope、应用工厂、DB engine 创建、服务客户端等框架职责搬进这个包。

## 命令

- 安装开发依赖：`uv sync --extra dev`
- 运行测试：`uv run pytest -q`
- 通过外部工具安装开发依赖：`iticli install`
- 通过外部工具运行测试：`iticli test`
- 发布系统包：`iticli release`
- 同步 migration 到宿主项目：`uv run iti-system migrations sync --target migrations/versions`
- 初始化或更新宿主项目 seed：`uv run iti-system seed system app:app`

系统路由、seed 数据、权限码、菜单元数据、migration sync 或 CLI 行为变化时，同步更新这个 skill。