iTi-System/.codex/skills/iti-system-project/SKILL.md

name	description
iti-system-project	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 命令。

运行契约

宿主项目注册：

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：

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。