# iTi-System

`iti-system` 是可复用的系统业务包。

它提供后台系统常用能力。
业务项目注册后即全量引入。
不提供按功能拆分的模块选择。

## 能力范围

- 认证。
- 用户。
- 角色。
- 菜单。
- 部门。
- 字典。
- 配置。
- 文件。
- 日志。
- 用户扩展属性。

## 安装

业务项目在 `pyproject.toml` 中添加依赖：

```toml
dependencies = [
  "iti-flask @ git+ssh://git@example.com/iTi-Flask.git@v0.1.1",
  "iti-system @ git+ssh://git@example.com/iTi-System.git@v0.1.1",
]
```

同步依赖：

```bash
uv sync
```

## 注册

在业务项目的 `app.py` 中注册：

```python
from iti.applications import create_app
from iti_system import create_system_module

from config import config
from my_app.models import import_models


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

注册后会挂载系统路由、CLI 命令、日志扩展和事件处理器。

## 路由入口

系统管理路由挂在 `/sys` 下：

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

认证路由挂在 `/auth` 下。
通用上传路由挂在 `/upload` 下。
文件访问路由挂在 `/file` 下。

## Migration Sync

业务项目只保留自己的 Alembic migration 流。
系统 migration 同步到业务项目的 `migrations/versions` 目录。

```bash
uv run python -m flask --app app.py iti-system migrations sync
uv run python -m flask --app app.py db upgrade
```

自定义目标目录：

```bash
uv run python -m flask --app app.py iti-system migrations sync --target migrations/versions
```

已存在的 migration 文件会跳过。

## Seed

写入系统初始数据：

```bash
uv run python -m flask --app app.py iti-system seed system
```

seed 使用 Python 代码。
可重复执行。
已有管理员密码不会被重置。

seed 会写入：

- 默认角色。
- 默认管理员。
- 系统菜单。
- 系统配置。
- 系统字典。
- 已注册模块声明的菜单元数据。

## 本地开发

```bash
uv sync --extra dev
uv run --extra dev pytest
uv run --extra dev mypy
```

## 测试

```bash
uv run --extra dev pytest
```

指定测试文件：

```bash
uv run --extra dev pytest tests/test_modules.py
```

## 发布

发布前执行：

```bash
uv run --extra dev pytest
uv run --extra dev mypy
```

更新 `pyproject.toml` 中的版本号后打 Git tag。
业务项目通过更新依赖 tag 升级。