iTi-Flask/docs/EXCHANGE.md

模板与导入导出

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

业务范围

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

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

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

system.user.import

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

业务规格

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

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。