# 模板与导入导出

iTi-Flask 提供模板中心、模板文件、导入导出任务和业务规格注册能力。
具体业务字段、变量含义和执行逻辑由业务模块提供。

## 业务范围

一个导入导出能力由三段业务键定位：

- `biz_domain`：业务域，例如 `system`、`mes`、`qos`。
- `biz_obj`：业务对象，例如 `user`、`work_order`。
- `operation`：操作，目前是 `import` 或 `export`。

模板编码默认由这三段生成：

```text
system.user.import
```

前端可以调用 `/exchange/templates/code` 生成，也可以创建模板时不传 `code`，后端自动生成。

## 业务规格

模板变量不是运维动态维护的字典。
变量由业务模块注册，模板中心只展示和保存版本快照。

```python
from iti.exchange import (
    ExchangeBusinessSpec,
    ExchangeOperation,
    ExchangeScope,
    ExchangeTemplateLayout,
    ExchangeTaskResult,
    ExchangeVariable,
    register_exchange_spec,
)


def import_users(context):
    return ExchangeTaskResult(success_count=1)


def register_tasks(self, app):
    register_exchange_spec(
        app,
        ExchangeBusinessSpec(
            scope=ExchangeScope("system", "user", ExchangeOperation.IMPORT),
            name="用户导入",
            description="导入系统用户",
            layout=ExchangeTemplateLayout(title="用户导入", sheet_name="用户", header_row=2),
            variables=(
                ExchangeVariable(key="username", label="用户名", required=True, example="alice"),
                ExchangeVariable(key="mobile", label="手机号"),
            ),
        ),
        handler=import_users,
    )
```

前端维护模板时，先从 `/exchange/catalog` 聚合查询业务范围。
选定范围后，页面展示该范围的变量、示例和使用方式。

## 模板

模板记录保存：

- `code`
- `name`
- `biz_domain`
- `biz_obj`
- `operation`
- `layout`
- `current_version`
- `status`

`layout` 只保存解析需要的标记，例如 `title_row`、`header_row`、`data_start_row`。
样式属于 Excel 文件本身，不进入导入导出数据模型。

版本记录保存：

- 模板文件位置
- 校验值
- 布局快照
- 变量快照

变量快照用于保证历史版本可复现。
业务模块改了变量定义，不会影响已发布版本。

## 执行

创建任务时传业务范围和可选模板版本。
框架解析模板计划后创建 `exchange_tasks`。
调用 `/exchange/tasks/{task_id}/run` 时，框架按业务范围找到注册的 handler，并把 `ExchangeTaskContext` 交给业务模块。

框架只管理任务状态、行结果和文件读写。
业务模块负责真实导入、导出、校验、回执和业务事务。

## Source

模板计划可来自：

- 本地模板中心：默认。
- 远程模板中心：`sourceKind=remote`。
- 自定义 source：注册 `register_exchange_source()`。
- 纯映射输入：显式 `sourceKind=mapping`。

## 主要对象

- `ExchangeBusinessSpec`
- `ExchangeScope`
- `ExchangeOperation`
- `ExchangeVariable`
- `ExchangeTemplateLayout`
- `ExchangeTemplatePlan`
- `ExchangeTemplateSnapshot`
- `ExchangeTaskContext`
- `ExchangeTaskResult`
- `ExchangeSource`

Excel 数据处理走 `pandas`。
模板文件生成和上传解析走 `openpyxl`。