升鲜宝业务功能导入模块PRD 开发文档(一）---升鲜宝生鲜配送供应链管理系统源代码服务

升鲜宝业务功能导入模块

PRD 开发文档

|----------|-----------------------------------|
| 文档版本 | V1.0 |
| 产品名称 | 升鲜宝业务功能导入通用模块 |
| 文档属性 | PRD / 开发实施 / 测试验收 |
| 编写日期 | 2025-06-09 |
| 适用对象 | 产品、研发、测试、实施 |
| 依据资料 | 12 张模块原型效果图 + 导入中心表设计 + 业务表示例数据字典 |

本文档用于指导升鲜宝业务功能导入模块的产品设计、后端开发、前端开发、联调测试与上线验收。

1. 产品背景与建设目标

升鲜宝需要沉淀统一的"业务功能导入模块"，让订单、客户、商品、库存、采购、财务等业务在同一套导入框架下运行。
目标不是单纯做一个上传 Excel 的入口，而是建设可配置、可审计、可版本化、可发布回滚、可绑定方案与模板的导入平台能力。
本模块以"导入模块管理"为核心枢纽，对接导入字段、导入方案、导入模板、导入预览、导入任务、失败报告中心。
以销售订单导入为主示例，要求支撑主表/明细表导入、客户引用校验、唯一键/分组键配置、失败报告输出和任务追踪。

2. 范围定义

2.1 本期范围

导入模块管理：新增、修改、详情、预览、版本历史、发布预览、发布回滚、审计日志。
能力配置：模板、预览、异步、失败报告、允许部分成功、覆盖导入等。
资源绑定：绑定导入方案与模板。
与导入字段管理、导入方案管理、导入模板管理、导入任务中心联动。

2.2 非本期范围

不包含导出模块 PRD。
不包含第三方数据同步器的详细设计。
不包含完整的所有业务表导入规则，仅以销售订单作为完整示例。

3. 角色与权限

|--------|----------|--------------------------|-------------|
| 角色 | 典型用户 | 主要职责 | 核心权限 |
| 产品经理 | 产品/业务负责人 | 定义模块边界、字段能力、资源绑定、发布策略 | 查看/编辑/发布/回滚 |
| 后端开发 | Java 开发 | 实现模块配置、规则执行、任务状态、日志与数据落库 | 查看/编辑/联调 |
| 前端开发 | Vue 前端 | 实现页面、交互、校验提示、联动预览 | 查看/编辑/联调 |
| 测试工程师 | 测试/QA | 验证配置正确性、异常场景、回滚与审计 | 查看/执行/下载报告 |
| 实施/运维 | 实施顾问/运维 | 环境配置、发布审批、回滚执行、生产巡检 | 查看/发布/回滚 |

4. 总体流程

第一步：创建导入模块，确定模块编码、名称、业务类型、处理器 Bean 与基础开关。
第二步：配置模块能力，明确是否支持模板、预览、异步、失败报告、部分成功等。
第三步：绑定导入方案与模板，建立模块---方案---模板的资源关系。
第四步：发布预览，检查变更内容、资源依赖与风险提示。
第五步：正式发布，生成新版本并进入可执行状态。
第六步：通过导入中心使用模块执行业务导入，任务中心与失败报告中心承接执行结果。

5. 功能架构

|----------|--------------|----------------------------|
| 一级能力 | 二级能力 | 说明 |
| 模块基础信息 | 新增/修改/详情 | 维护模块标识、处理器、业务类型、状态、路径等基础信息 |
| 模块能力 | 能力配置 | 维护模板、预览、异步、失败报告、任务中心等能力开关 |
| 资源关联 | 绑定方案/模板 | 选择当前模块可用的导入方案和导入模板，并设置默认资源 |
| 版本管理 | 版本历史/发布/回滚 | 记录版本变化、执行发布检查、支持安全回滚 |
| 审计治理 | 审计日志 | 记录关键配置的前后差异、审批信息与高风险变更 |
| 联动预览 | 字段/方案/模板联动预览 | 在发布前查看最终执行视图与字段绑定效果 |

6.1 导入模块管理列表页（第二版）

**页面定位：**作为导入模块管理入口页，承载模块筛选、统计分析、模块启停与跳转到下级功能页面。

支持按模块编码、模块名称、业务类型、状态、是否支持模板、是否支持异步等条件检索。
顶部统计卡片显示模块总数、已启用、草稿、已发布、待审核、最近更新等信息。
列表必须展示处理器 Bean、是否支持模板、是否支持异步、关联方案数、关联模板数、当前版本、状态。
操作区必须固定提供：详情、修改、配置能力、绑定方案、绑定模板、版本历史、审计日志。
分页、排序、批量启停、批量发布能力必须明确。

图 1：导入模块管理列表页（第二版）

6.2 新增导入模块页（第二版）

**页面定位：**用于新增一个可执行的导入模块，配置基础资料、导入能力、业务规则、安全权限与扩展属性。

模块编码保存后不可修改，建议采用英文、数字、下划线组合。
处理器 Bean、页面路径、权限前缀、业务类型、所属系统为必填项。
导入能力配置需明确：是否支持模板、是否支持异步、是否支持预览、是否支持失败报告、是否允许部分成功、是否支持覆盖导入。
业务规则区需明确唯一键、分组键、重复策略、事务策略、默认批处理大小、默认审核方式。
保存后应进入草稿态，支持"保存""保存并继续""提交审核"。

图 2：新增导入模块页（第二版）

6.3 修改导入模块页（第二版）

**页面定位：**用于对已创建模块进行标签化编辑，避免在一个页面堆叠所有配置。

页面采用标签页：基础信息、导入能力、方案与模板、发布与版本、审计日志。
模块编码只读，其他属性允许按权限修改。
右侧需展示当前版本、创建人、更新时间、关联资源统计。
默认导入规则可与校验模板、字段映射模板、事务策略绑定。
保存修改后应生成版本变更记录。

图 3：修改导入模块页（第二版）

6.4 导入模块详情页（第二版）

**页面定位：**从资源概览角度查看模块当前状态、已绑定资源、近期任务表现。

展示模块基础信息、默认导入能力、业务规则、接口与处理器信息。
卡片区显示当前版本、状态、关联方案数、关联模板数、最近导入次数、失败率。
资源概览区域展示关联方案、关联模板、最近版本记录、最近审计日志。
底部需展示最近导入任务结果样例，帮助产品、开发、测试快速回溯。

图 4：导入模块详情页（第二版）

6.5 导入模块联动预览页（第二版）

**页面定位：**用于预览模块与字段、方案、模板之间的联动关系和最终入参映射效果。

左侧字段清单、中间方案列表、右侧模板映射预览三栏联动。
切换方案或模板时，下方数据映射预览实时刷新。
必须明确哪些模板列已绑定字段、哪些列未绑定、哪些为必填。
适合测试人员进行模板-字段-方案联调验证。

图 5：导入模块联动预览页（第二版）

6.6 导入模块能力配置页（第二版）

**页面定位：**集中配置模块级能力开关，并生成可发布的 JSON 配置快照。

基础能力：模板、预览、字段映射、失败报告、任务中心、异步任务。
导入控制：覆盖导入、自动创建引用数据、允许部分成功、默认批次大小、超时。
校验规则：强校验/弱校验、唯一键校验、分组键校验、跨表校验。
文件处理：最大文件大小、支持格式、Sheet 策略、表头识别策略。
通知与日志：站内信、邮件通知、审计日志、操作日志。

图 6：导入模块能力配置页（第二版）

6.7 绑定导入方案页

**页面定位：**为模块选择可用的导入方案，并支持指定默认方案。

页面分为"已绑定方案"和"可绑定方案"两部分。
支持按方案编码、名称、所属类型、状态、是否默认过滤。
允许一次绑定多个方案，但同一模块只允许一个默认方案。
右侧需展示当前选中方案的参数摘要与适用说明。

图 7：绑定导入方案页

6.8 绑定导入模板页

**页面定位：**为模块选择可用模板，并明确模板列结构与示例数据。

模板列表必须展示模板编码、版本、关联方案、列数、状态、最近更新时间。
支持设置默认模板、下载示例、预览模板全部字段。
右侧展示当前选中模板的字段预览、示例数据与模板说明。

图 8：绑定导入模板页

6.9 模块版本历史页

**页面定位：**用于查看模块的版本演进记录与版本对比信息。

显示版本号、变更类型、变更摘要、发布时间、发布人、是否可回滚。
左侧时间线需展示关键版本。
右侧版本详情需展示发布说明与资源影响摘要。
支持查看详情、版本对比、回滚预演。

图 9：模块版本历史页

6.10 模块发布预览页

**页面定位：**正式发布前用于检查本次变更内容与资源依赖是否完整。

按"基础信息变更、能力配置变更、关联方案变更、关联模板变更"分签展示。
必须有发布检查清单：依赖资源检查、权限检查、模板检查、字段规则检查。
发布说明必填。
支持确认发布、保存草稿、返回修改。

图 10：模块发布预览页

6.11 模块发布记录与回滚页

**页面定位：**用于查看发布批次和执行安全回滚。

展示发布批次、版本、发布时间、发布类型、影响范围、发布状态。
右侧必须提供回滚操作区和风险影响评估。
回滚前需进行依赖检查、兼容性检查和确认清单勾选。

图 11：模块发布记录与回滚页

6.12 模块审计日志页

**页面定位：**用于查看模块配置变更全生命周期审计记录。

日志列表必须展示操作时间、操作人、操作类型、变更对象、变更字段数、风险级别、来源IP、结果。
右侧需展示选中日志的变更前后对比、字段变更明细、审批信息、关联版本/方案/模板。
高风险操作必须单独标识。

图 12：模块审计日志页

7. 数据库表结构与数据字典

7.1 业务表示例数据字典（升鲜宝销售订单导入）

mall_shop（客户/门店主体表，导入引用匹配示例）

|---------------|---------|----------|---------------|
| 字段 | 类型 | 中文含义 | 说明 |
| id | BIGINT | 主键ID | 客户/门店主键 |
| shop_code | VARCHAR | 客户/门店编码 | 导入时可作为客户匹配键 |
| shop_name | VARCHAR | 客户/门店名称 | 导入时可作为客户模糊匹配键 |
| contact | VARCHAR | 联系人 | 导入预览与引用校验提示用 |
| mobile | VARCHAR | 联系电话 | 客户识别与后续通知 |
| address | VARCHAR | 地址 | 客户资料字段 |
| trade_type_id | INT | 交易主体类型 | 区分店铺/客户 |
| workhouse_id | BIGINT | 默认仓库ID | 用于订单导入默认仓库匹配 |
| enabled | TINYINT | 启停状态 | 引用数据有效性校验 |
| del_flag | TINYINT | 删除标记 | 逻辑删除控制 |

oms_order_bill（订单主表，导入业务单头示例）

|--------------------|-----------------|----------|----------------|
| 字段 | 类型 | 中文含义 | 说明 |
| id | BIGINT | 主键ID | 订单主表主键 |
| order_code | VARCHAR | 订单号 | 推荐作为导入唯一键与分组键 |
| order_date | BIGINT/DATE | 订单日期 | 导入时日期格式校验 |
| shop_id | BIGINT | 客户ID | 与 mall_shop 关联 |
| workhouse_id | BIGINT | 仓库ID | 单头仓库字段 |
| payment_id | BIGINT | 支付方式ID | 订单支付方式 |
| delivery_date_time | BIGINT/DATETIME | 交付时间 | 配送/交付字段 |
| bill_state | INT | 单据状态 | 影响覆盖导入与回滚规则 |
| order_amount | DECIMAL | 订单金额 | 主表金额汇总字段 |
| remark | VARCHAR | 备注 | 导入备注 |

oms_order_bill_info（订单明细表，导入业务单身示例）

|-------------|---------|----------|-----------|
| 字段 | 类型 | 中文含义 | 说明 |
| id | BIGINT | 主键ID | 订单明细主键 |
| order_code | VARCHAR | 订单号 | 与主表按订单号关联 |
| sku_unit_id | BIGINT | 规格单位ID | 明细商品唯一识别 |
| pre_num | DECIMAL | 预定数量 | 数量字段 |
| unit_price | DECIMAL | 单价 | 价格字段 |
| pre_amount | DECIMAL | 金额 | 数量*单价 |
| sendout_num | DECIMAL | 实发数量 | 履约数量字段 |
| remark | VARCHAR | 明细备注 | 扩展说明 |

7.2 导入中心支撑表数据字典（建议设计）

sys_import_module（导入模块定义表）

|------------------|--------------|---------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| module_code | VARCHAR(64) | 模块编码，唯一 |
| module_name | VARCHAR(128) | 模块名称 |
| biz_type | VARCHAR(64) | 业务类型 |
| handler_bean | VARCHAR(128) | 处理器Bean |
| template_enabled | TINYINT | 是否支持模板 |
| async_enabled | TINYINT | 是否支持异步 |
| status | TINYINT | 状态 |
| remark | VARCHAR(500) | 备注 |

sys_import_field（导入字段元数据表）

|--------------------|--------------|---------------------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| module_code | VARCHAR(64) | 所属模块 |
| field_code | VARCHAR(64) | 字段编码 |
| field_name | VARCHAR(128) | 字段名称 |
| field_path | VARCHAR(256) | 字段路径 |
| db_field | VARCHAR(128) | 数据库字段 |
| data_type | VARCHAR(32) | 字段类型 |
| scope_type | VARCHAR(32) | MAIN/DETAIL/VIRTUAL |
| required_flag | TINYINT | 默认必填 |
| validate_rule_json | TEXT | 校验规则 |
| convert_rule_json | TEXT | 转换规则 |

sys_import_field_alias（字段别名表）

|-------------|--------------|-----------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| module_code | VARCHAR(64) | 所属模块 |
| field_code | VARCHAR(64) | 字段编码 |
| alias_name | VARCHAR(128) | Excel列头别名 |
| lang_code | VARCHAR(32) | 语言 |
| system_flag | TINYINT | 系统别名 |
| status | TINYINT | 状态 |

sys_import_scheme（导入方案主表）

|--------------|--------------|----------------------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| module_code | VARCHAR(64) | 所属模块 |
| scheme_code | VARCHAR(64) | 方案编码 |
| scheme_name | VARCHAR(128) | 方案名称 |
| owner_type | VARCHAR(32) | SYSTEM/USER/ROLE/ORG |
| public_flag | TINYINT | 是否公共 |
| default_flag | TINYINT | 是否默认 |
| version_no | INT | 版本号 |
| status | TINYINT | 状态 |

sys_import_scheme_config（导入方案参数表）

|-----------------------|--------------|---------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| scheme_id | BIGINT | 方案ID |
| sheet_name | VARCHAR(128) | Sheet名称 |
| header_row_no | INT | 表头行号 |
| data_start_row_no | INT | 数据起始行号 |
| group_key | VARCHAR(64) | 分组键 |
| unique_key | VARCHAR(64) | 唯一键 |
| overwrite_mode | TINYINT | 是否覆盖 |
| auto_create_ref | TINYINT | 自动创建引用 |
| allow_partial_success | TINYINT | 允许部分成功 |
| duplicate_strategy | VARCHAR(32) | 重复策略 |

sys_import_scheme_field（导入方案字段明细表）

|---------------|--------------|--------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| scheme_id | BIGINT | 方案ID |
| field_code | VARCHAR(64) | 字段编码 |
| display_name | VARCHAR(128) | 模板显示名 |
| checked_flag | TINYINT | 是否启用 |
| required_flag | TINYINT | 是否必填 |
| sort_no | INT | 顺序 |
| default_value | VARCHAR(256) | 默认值 |
| example_value | VARCHAR(256) | 示例值 |
| rule_json | TEXT | 字段级规则 |

sys_import_template（导入模板表）

|-----------------|--------------|--------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| module_code | VARCHAR(64) | 所属模块 |
| template_code | VARCHAR(64) | 模板编码 |
| template_name | VARCHAR(128) | 模板名称 |
| scheme_id | BIGINT | 关联方案 |
| version_no | INT | 版本号 |
| file_url | VARCHAR(512) | 模板文件地址 |
| sample_file_url | VARCHAR(512) | 示例文件地址 |
| status | TINYINT | 状态 |

sys_import_task（导入任务表）

|------------------|--------------|--------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| task_no | VARCHAR(64) | 任务编号 |
| module_code | VARCHAR(64) | 所属模块 |
| scheme_id | BIGINT | 方案ID |
| source_file_name | VARCHAR(256) | 源文件名 |
| source_file_url | VARCHAR(512) | 源文件地址 |
| fail_file_url | VARCHAR(512) | 失败文件地址 |
| total_count | INT | 总记录数 |
| success_count | INT | 成功数 |
| fail_count | INT | 失败数 |
| status | VARCHAR(32) | 任务状态 |

sys_import_task_detail（导入任务明细表）

|------------|---------------|---------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| task_id | BIGINT | 任务ID |
| row_no | INT | Excel行号 |
| field_code | VARCHAR(64) | 字段编码 |
| raw_value | VARCHAR(2000) | 原始值 |
| error_code | VARCHAR(64) | 错误编码 |
| error_msg | VARCHAR(1000) | 错误信息 |
| row_json | LONGTEXT | 整行数据 |

sys_import_task_log（导入任务日志表）

|-------------|---------------|-----------------------|
| 字段 | 类型 | 说明 |
| id | BIGINT | 主键 |
| task_id | BIGINT | 任务ID |
| log_type | VARCHAR(32) | INFO/WARN/ERROR/AUDIT |
| log_content | VARCHAR(2000) | 日志内容 |
| ext_json | TEXT | 扩展JSON |
| create_time | BIGINT | 创建时间 |

8. 页面功能详细说明

|--------|----------|---------------------|----------------|
| 序号 | 页面 | 核心动作 | 输出结果 |
| 1 | 列表页（第二版） | 筛选、统计、查看模块列表、跳转下级功能 | 模块清单、统计卡片、导航入口 |
| 2 | 新增页（第二版） | 创建模块、保存草稿、提交审核 | 新模块草稿/待审核记录 |
| 3 | 修改页（第二版） | 标签化编辑基础信息与默认规则 | 生成变更版本待发布 |
| 4 | 详情页（第二版） | 查看资源概览与最近任务 | 模块全景信息 |
| 5 | 联动预览页 | 查看字段-方案-模板联动结果 | 确认绑定关系与映射效果 |
| 6 | 能力配置页 | 开启/关闭能力、保存 JSON 快照 | 能力配置版本 |
| 7 | 绑定方案页 | 绑定/解绑方案、设置默认方案 | 模块可用方案列表 |
| 8 | 绑定模板页 | 绑定/解绑模板、设置默认模板 | 模块可用模板列表 |
| 9 | 版本历史页 | 查询版本、查看对比、回滚预演 | 版本记录与差异 |
| 10 | 发布预览页 | 发布前检查依赖与变更 | 可发布确认单 |
| 11 | 发布回滚页 | 查看发布批次、执行安全回滚 | 回滚结果与风险提示 |
| 12 | 审计日志页 | 查询操作审计、查看前后值 | 审计追踪链路 |

9. 接口清单（建议）

|--------|--------------------------------------|-----------|-----------------------------|
| 方法 | 接口 | 用途 | 主要入参/出参 |
| GET | /import/module/list | 导入模块列表查询 | 模块编码、名称、业务类型、状态、能力开关、关联资源统计 |
| POST | /import/module/save | 新增/修改导入模块 | 模块基础信息、能力配置、规则配置、扩展属性 |
| GET | /import/module/{id} | 导入模块详情 | 基础信息、资源概览、审计摘要 |
| GET | /import/module/{id}/preview | 导入模块预览 | 字段/方案/模板联动预览 |
| POST | /import/module/{id}/capability/save | 能力配置保存 | 模板、预览、异步、失败报告等能力项 |
| POST | /import/module/{id}/bind-schemes | 绑定导入方案 | 绑定列表、默认方案标识 |
| POST | /import/module/{id}/bind-templates | 绑定导入模板 | 绑定列表、默认模板标识 |
| GET | /import/module/{id}/versions | 版本历史查询 | 版本号、摘要、发布时间、回滚状态 |
| POST | /import/module/{id}/publish-preview | 发布前预检查 | 变更差异、依赖检查、风险提示 |
| POST | /import/module/{id}/publish | 模块发布 | 发布说明、目标版本 |
| POST | /import/module/{id}/rollback-preview | 回滚预览 | 回滚目标、影响范围 |
| POST | /import/module/{id}/rollback | 执行回滚 | 目标版本、确认参数 |
| GET | /import/module/{id}/audit-logs | 审计日志查询 | 操作时间、操作人、变更对象、差异内容 |

10. 状态与版本流转

模块状态建议：草稿 → 待审核 → 已发布 → 停用。
版本状态建议：草稿版 → 已发布版 → 已回滚版。
资源绑定状态建议：未绑定 → 已绑定 → 已设默认。
导入任务状态建议：INIT → WAITING → RUNNING → SUCCESS / PART_SUCCESS / FAILED。

11. 开发要点

模块编码在保存后不可修改，避免下游方案、模板、任务、日志关联断裂。
发布与回滚动作必须单独入审计日志，并记录操作人、时间、版本、差异摘要。
模块能力开关与实际运行逻辑必须一致，例如关闭失败报告时，导入任务不可再提供失败报告下载入口。
绑定方案与绑定模板必须支持默认资源设置，但同一模块同一时刻只能存在一个默认方案与一个默认模板。
联动预览页需要真实读取字段、方案、模板的绑定关系，不能只展示静态信息。
对 oms_order_bill / oms_order_bill_info 示例场景，推荐使用 order_code 作为唯一键和分组键。
对 mall_shop 示例场景，推荐优先使用 shop_id / shop_code / shop_name 作为客户引用匹配键。

12. 测试范围与验收标准

|---------|-----------------------------------------------------------------------------------------------|
| 验收项 | 通过标准 |
| 模块基础信息 | 模块编码唯一且保存后不可修改；必填字段校验齐全；业务类型、处理器Bean、页面路径与权限前缀可正确保存。 |
| 能力配置 | 能力开关保存后实时生效；JSON 快照可生成；关闭能力后前台入口与执行逻辑同步受控。 |
| 绑定方案/模板 | 支持多选绑定；仅可存在一个默认方案和一个默认模板；解绑后模块不再可用对应资源。 |
| 版本与发布 | 发布预检查必须通过；发布后产生版本记录；回滚前需进行影响检查并有日志。 |
| 审计日志 | 所有新增、修改、发布、回滚、绑定操作均产生可追溯日志，支持查看字段变更前后值。 |
| 与业务表联动 | 以 oms_order_bill / oms_order_bill_info 为例，可基于唯一键 order_code 完成单头单身导入配置；客户可按 mall_shop 进行引用校验。 |

13. 里程碑建议

第一阶段：完成模块基础信息、列表查询、新增/修改/详情页面。
第二阶段：完成能力配置、方案绑定、模板绑定与联动预览。
第三阶段：完成版本历史、发布预览、发布回滚、审计日志。
第四阶段：结合真实业务方案联调销售订单导入，打通任务中心与失败报告中心。

14. 附录：原型页面清单

1. 导入模块管理列表页（第二版）
1. 新增导入模块页（第二版）
1. 修改导入模块页（第二版）
1. 导入模块详情页（第二版）
1. 导入模块联动预览页（第二版）
1. 导入模块能力配置页（第二版）
1. 绑定导入方案页
1. 绑定导入模板页
1. 模块版本历史页
1. 模块发布预览页
1. 模块发布记录与回滚页
1. 模块审计日志页

附录A 菜单结构图

本附录用于补充导入中心与导入模块管理相关菜单结构，帮助开发、测试、实施及产品在同一视角下理解功能归属与入口路径。

图 A-1 导入中心菜单结构图

附录B 测试用例矩阵

以下测试用例矩阵用于指导测试人员围绕导入模块管理、导入预览、正式导入执行、失败回溯和发布回滚等关键功能开展功能、联调及回归验证。

|-------|--------|--------------|---------------| | 编号 | 模块 | 场景 | TC-01 | 导入模块管理 | 新增模块-必填校验 | TC-02 | 导入模块管理 | 新增模块-编码唯一 | TC-03 | 导入模块管理 | 新增模块-能力 | TC-04 | 导入模块管理 | 修改模块-基础信息保存 | TC-05 | 导入模块管理 | 修改模块-标签页切换 | TC-06 | 导入模块管理 | 详情页-资源概览 | TC-07 | 导入模块管理 | 预览页-联动预览 | TC-08 | 导入模块管理 | 能力配置-开关保存 | TC-09 | 导入模块管理 | 绑定导入方案 | TC-10 | 导入模块管理 | 绑定导入模板 | TC-11 | 导入模块管理 | 版本历史查看 | TC-12 | 导入模块管理 | 发布预览校验 | TC-13 | 导入模块管理 | 发布确认 | TC-14 | 导入模块管理 | 发布记录与回滚 | TC-15 | 导入模块管理 | 审计日志追踪 | TC-16 | 导入预览中心 | 字段映射预览 | TC-17 | 导入预览中心 | 校验结果页 | TC-18 | 导入任务中心 | 异步任务执行 | TC-19 | 导入任务中心 | 失败任务详情 | TC-20 | 失败报告中心 | 失败报告下载 ------------------------|---------------------------------------|-----|-------|
| 前置条件 | 输入/操作 | 预期结果 | 优先级 | 建议方式 |
| 进入新增页 | 模块编码/名称为空 | 前端阻止提交并给出必填提示 | P0 | UI+接口 |
| 系统无同名模块 | 重复输入已存在模块编码 | 后端返回编码已存在，不落库 | P0 | 接口自动化 |
开关默认值 | 进入新增页 | 支持模板/预览/异步等默认配置 | 默认值与PRD一致 | P1 | UI |
| 模块已存在 | 修改名称、排序、备注 | 保存成功，列表与详情同步更新 | P0 | UI+接口 |
| 进入修改页 | 切换基础信息/导入能力/方案与模板/审计日志 | 各标签数据正常加载，无报错 | P1 | UI |
| 模块已配置字段/方案/模板 | 打开详情页 | 资源统计、最近任务、版本信息正确展示 | P1 | UI |
| 已绑定字段、方案、模板 | 打开预览页 | 字段→方案→模板联动信息正确，未绑定项有提示 | P0 | UI+接口 |
| 模块已存在 | 开启失败报告/异步任务/允许部分成功 | 配置保存并在详情页可见 | P0 | 接口自动化 |
| 存在多个方案 | 勾选方案并设默认 | 绑定成功，默认方案唯一 | P0 | UI+接口 |
| 存在多个模板 | 绑定模板并设置默认模板 | 绑定成功，可在模块详情显示 | P0 | UI+接口 |
| 存在多个版本 | 打开版本历史页 | 版本列表、状态、摘要与发布时间准确 | P1 | UI |
| 有待发布修改 | 进入发布预览页 | 展示基础信息差异、风险检查、检查清单 | P0 | UI+接口 |
| 通过预检查 | 点击确认发布 | 生成新版本，状态更新为已发布 | P0 | 接口自动化 |
| 存在历史版本 | 选择历史版本回滚 | 生成回滚任务/记录，当前版本回退 | P0 | 接口+回归 |
| 存在新增/修改/发布记录 | 查看审计日志 | 记录完整含操作者、时间、变更前后值 | P1 | 接口 |
| 已上传文件和方案 | 执行预览 | 正确显示精确匹配/别名匹配/未映射状态 | P0 | UI+接口 |
| 预览完成 | 查看校验结果 | 错误/警告/自动处理提示统计正确 | P0 | UI |
| 已发起正式导入 | 轮询任务 | 任务状态按 INIT→WAITING→RUNNING→SUCCESS 流转 | P0 | 接口自动化 |
| 存在失败任务 | 查看失败详情 | 展示错误字段、原始值、错误原因、建议处理 | P0 | UI+接口 |
| 失败报告已生成 | 下载报告 | 文件可下载且内容与页面明细一致 | P1 | 接口+人工 |

测试执行建议：P0 用例必须覆盖开发自测、联调测试、回归测试三轮；涉及版本发布、回滚、失败报告下载的场景建议在测试环境与预发布环境分别验证一次。

附录C 接口时序图

本附录补充导入预览与正式导入两条核心链路的接口时序，帮助开发人员识别关键参与方，帮助测试人员设计联调用例和断点检查点。

图 C-1 导入预览接口时序图

说明：导入预览链路不直接落业务表，核心目标是基于 schemeId 读取导入方案、字段映射、表头别名与规则配置，生成样例预览、错误清单与自动处理提示。

图 C-2 正式导入执行接口时序图

说明：正式导入链路以任务中心为核心，采用异步执行模式。控制层负责创建任务与入参落库，执行器路由到模块处理器完成主从聚合、引用匹配、入库与失败报告生成。

关键接口断点检查点

|----------|-------------------------------|----------------------------------------------------|---------------------------|
| 阶段 | 接口/服务 | 检查点 | 失败表现 |
| 导入预览 | POST /import/preview | schemeId 有效；文件可读取；字段映射结果生成 | 返回 4xx/5xx；字段映射为空；预览摘要缺失 |
| 方案解析 | SchemeResolveService.resolve | 读取模块、字段、别名、方案参数成功 | 提示方案不存在或字段不完整 |
| Excel 解析 | EasyExcel 引擎 | 表头识别、行数统计、样例行解析 | 表头空白、总行数不正确、样例数据显示异常 |
| 正式导入 | POST /import/execute | 任务创建成功，返回 taskId | 前端无法跳转任务详情，任务表无记录 |
| 任务流转 | TaskService / AsyncExecutor | 状态按 WAITING→RUNNING→SUCCESS/PART_SUCCESS/FAILED 更新 | 任务长时间停留 WAITING / RUNNING |
| 失败报告 | FailReportService + OSS/MinIO | 失败报告文件上传成功并记录 URL | 任务失败但无 failFileUrl 或下载为空 |