docs: 文档整理

README.md

@@ -1,66 +1,149 @@
 # iTi-System
 
-`iti-system` 是 `iTi-Flask` 的可选系统业务包。
+`iti-system` 是可复用的系统业务包。
 
-它提供认证、用户、角色、菜单、部门、字典、配置、文件、日志、用户扩展属性等系统域能力。
-引入即全量引入。
-不提供模块选择。
-不拆分 migration。
+它提供后台系统常用能力。
+业务项目注册后即全量引入。
+不提供按功能拆分的模块选择。
 
-ERP Service 这类服务不需要依赖本包。
-MES 这类主业务项目可以依赖本包。
+## 能力范围
+
+- 认证。
+- 用户。
+- 角色。
+- 菜单。
+- 部门。
+- 字典。
+- 配置。
+- 文件。
+- 日志。
+- 用户扩展属性。
 
 ## 安装
 
-业务项目依赖：
+业务项目在 `pyproject.toml` 中添加依赖：
 
 ```toml
 dependencies = [
-  "iti-flask @ git+https://git.noahlan.cn/iti-framework/iTi-Flask.git@v0.1.1",
-  "iti-system @ git+https://git.noahlan.cn/iti-framework/iTi-System.git@v0.1.1",
+  "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 --extra dev
-uv run --extra dev pytest
-uv run --extra dev mypy
+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` 下。
 
-业务项目只保留一条 Alembic migration 流。
-系统 migration 同步到业务项目的 `migrations/versions`。
+## 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
 ```
 
-系统 migration 是全量系统表集合。
-轻服务如果不需要系统表，应不依赖 `iti-system`。
+自定义目标目录：
+
+```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 升级。