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()

配置

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 只处理模板结构和格式。