# 模块协议

模块是同一个 FastAPI 进程内的业务边界。
它不是独立服务。

## 注册

```python
from iti import create_app
from my_app.modules.example import ExampleModule

app = create_app(modules=[ExampleModule()])
```

## 模块类

```python
class ExampleModule:
    name = "example"

    def init_app(self, app):
        pass

    def register_routes(self, app):
        app.include_router(router)

    def register_permissions(self, app):
        pass

    def register_menu_seed(self, app):
        pass

    def register_tasks(self, app):
        pass
```

执行顺序：

1. `init_app`
2. `register_tasks`
3. `register_routes`
4. `register_permissions`
5. `register_menu_seed`

## 路由

使用 FastAPI 原生 `APIRouter`。

```python
from fastapi import APIRouter
from iti.responses import ok

router = APIRouter(prefix="/example", tags=["example"])


@router.get("/ping")
def ping():
    return ok({"pong": True})
```

API 文档会按 tag 前缀生成分组。
例如 `tags=["system.user"]` 会归入 `system` 分组，显示名为 `user`。

## 权限元数据

```python
from iti.modules import ModulePermission

def register_permissions(self, app):
    app.state.iti_modules.register_permission(
        ModulePermission("example:item:list", "示例列表")
    )
```

框架负责收集元数据。
具体授权由 `PermissionProvider` 决定。
单独使用 `iti-flask` 时可注入自己的 provider。
使用 `iti-system` 时由系统包提供数据库 provider。

## 模板与导入导出

框架内置的交换能力由 `iti.exchange.module.create_exchange_module()` 提供。
业务模块可以直接复用它，也可以只复用 `ExchangeService`、`ExchangeSource`、`register_exchange_source()`、`register_exchange_task()` 和 `router`。
模板中心可以由 `system` 承载，也可以由业务模块自建。框架侧能力不依赖 `system` 是否存在。

```python
from iti.exchange.module import create_exchange_module

app = create_app(modules=[create_exchange_module()])
```