From 33d3b171abdffd4eaebfe43a56457c44726c0fcd Mon Sep 17 00:00:00 2001
From: NoahLan <6995syu@163.com>
Date: Sun, 10 May 2026 05:24:25 +0800
Subject: [PATCH] Add system package project skill

---
 .codex/skills/iti-system-project/SKILL.md     | 102 ++++++++++++++++++
 .../iti-system-project/agents/openai.yaml     |   4 +
 README.md                                     |   6 ++
 3 files changed, 112 insertions(+)
 create mode 100644 .codex/skills/iti-system-project/SKILL.md
 create mode 100644 .codex/skills/iti-system-project/agents/openai.yaml

diff --git a/.codex/skills/iti-system-project/SKILL.md b/.codex/skills/iti-system-project/SKILL.md
new file mode 100644
index 0000000..90f0cf3
--- /dev/null
+++ b/.codex/skills/iti-system-project/SKILL.md
@@ -0,0 +1,102 @@
+---
+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`
+- 同步 migration 到宿主项目：`uv run iti-system migrations sync --target migrations/versions`
+- 初始化或更新宿主项目 seed：`uv run iti-system seed system app:app`
+
+系统路由、seed 数据、权限码、菜单元数据、migration sync 或 CLI 行为变化时，同步更新这个 skill。
diff --git a/.codex/skills/iti-system-project/agents/openai.yaml b/.codex/skills/iti-system-project/agents/openai.yaml
new file mode 100644
index 0000000..1b12c27
--- /dev/null
+++ b/.codex/skills/iti-system-project/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "iTi-System 项目"
+  short_description: "iTi-System 系统业务包指南"
+  default_prompt: "使用 $iti-system-project 修改或审查 iTi-System 系统域代码。"
diff --git a/README.md b/README.md
index cd8110b..67bf9e6 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,12 @@
 `iti-system` 是可复用的系统业务包。
 它注册到 `iti-flask` FastAPI 应用后，提供后台系统常用能力。
 
+AI 修改本项目时优先读：
+
+```text
+.codex/skills/iti-system-project/SKILL.md
+```
+
 ## 能力范围
 
 - 认证。