iTi-Flask/docs/EXCHANGE.md

# 模板与导入导出

iTi-Flask 提供统一的数据模板、导入和导出基础能力。
框架提供模板源抽象、对象、存储、任务和文件处理。
业务系统自己决定入口、字段语义、模板中心和回调处理。

## 设计边界

- 模板按业务实体建模，不按单表字段映射建模。
- 导入模板和导出模板独立。
- 模板支持编辑和版本管理。
- 模板也支持上传 Excel 作为来源。
- 执行时按任务显式选择已发布版本。
- 导入和导出都走任务。
- 没有模板时，框架按字段映射兜底。
- 模板源可来自本地表、远程模板中心、业务自定义 provider 或纯映射输入。
- `system` 不是能力开关。
- 业务项目可以自建模板中心，也可以挂远程模板中心 RPC。
- 只要实现 `ExchangeSource` 并注册进 `app.state.iti_exchange`，就能接入同一套计划解析和模板文件生成入口。

## 框架对象

- `ExchangeTemplate`
- `ExchangeTemplateSnapshot`
- `ExchangePlan`
- `ExchangeTemplateBinding`
- `ExchangeField`
- `ExchangePlaceholder`
- `ExchangeTemplateSource`
- `ExchangeTemplateSourceKind`
- `ExchangeTaskKind`
- `ExchangeSource`

## 入口

- `iti.exchange`
- `iti.exchange.service.ExchangeService`
- `iti.exchange.routes.router`
- `iti.exchange.module.create_exchange_module()`

## 配置

```python
class DevConfig(BaseDevConfig):
    def __init__(self) -> None:
        super().__init__()
        self.exchange_enabled = True
```

需要文件存储时复用 `file_storage`。

## 业务接法

业务项目可直接注册 `create_exchange_module()`，也可以自己写模块，只复用 `ExchangeService`、`ExchangeSource`、`register_exchange_source()` 和任务注册接口。

业务通常要自己补：

- 模板字段和 placeholder 定义。
- 模板发布流程。
- 模板中心 RPC、本地表维护方式，或自定义 source 注册方式。
- 导入回执和导出文件命名。
- 任务执行器里的实际业务处理。
- 菜单和页面入口。

模板中心可以由 `system` 提供，也可以由业务项目自建。框架只提供统一的计划解析、模板文件生成、Excel 读写和 source 接入层。

Excel 数据处理走 `pandas`。`openpyxl` 只处理模板结构和格式。