|
|
# 模板与导入导出
|
|
|
|
|
|
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`。
|