# 模块协议

模块用于业务项目内的代码边界。
模块运行在同一个 Flask 进程内，不是独立服务。

## 适用场景

适合做模块：

- 业务项目内部的业务域。
- 需要独立路由、service、schema 的功能。
- 共享同一个部署单元和数据库的功能。

不适合做模块：

- 需要独立部署的能力。
- 有独立数据源的能力。
- 多个项目跨进程复用的能力。

这类能力应通过 HTTP JSON 服务提供。

## 注册模块

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

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

模块类：

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

    def init_app(self, app):
        pass

    def register_commands(self, app):
        pass

    def register_routes(self, app):
        pass

    def register_permissions(self, app):
        pass

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

执行顺序：

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

## 权限元数据

```python
from iti.modules import ModulePermission, get_module_registry


def register_permissions(self, app):
    registry = get_module_registry(app)
    registry.register_permission(
        ModulePermission(
            code="example:item:list",
            name="示例列表",
            description="查看示例数据",
        )
    )
```

框架只收集权限元数据。
授权写库由业务项目或系统业务包处理。

## 菜单元数据

```python
from iti.applications.common.enums import MenuTypeEnum
from iti.modules import ModuleMenuSeed, get_module_registry


def register_menu_seed(self, app):
    registry = get_module_registry(app)
    registry.register_menu_seed(
        ModuleMenuSeed(
            id="example-menu-root",
            name="Example",
            type=MenuTypeEnum.MENU.value,
            path="/example",
            component="/example/list",
            auth_code="example:item:list",
            meta={"title": "示例模块", "icon": "carbon:application"},
            sort=100,
        )
    )
```

框架只收集菜单元数据。
是否写入数据库由业务项目决定。

## 边界

模块可以：

- 注册蓝图。
- 注册 CLI 命令。
- 声明权限和菜单元数据。
- 使用业务项目自己的 model。

模块不应：

- 修改框架内部实现。
- 直接导入其它模块的内部 model 或 service。
- 自建独立 migration 流。
- 在框架包里写业务数据。