|
|
---
|
|
|
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。
|