商户信息校验控制台需求文档 V1.0

版本：V1.0 | 创建日期：2025年10月16日 | 创建人：呼博 | 状态：已评审

最后更新：2025年10月20日

📋 快速导航：

1. 项目概述

1.1 项目背景

为提升商户信息数据校验的效率和准确性，需要开发一个专门的校验控制台系统。该系统将支持批量文件上传、实时校验、历史记录查询等功能，为运营人员提供便捷的数据校验管理工具。

1.2 项目目标

1.3 目标用户

2. 功能需求

2.1 核心功能模块

2.1.1 数据校验功能

功能描述：支持上传商户信息文件并进行数据校验

具体需求：

校验规则详情：

校验项目 校验规则 错误级别
银行ID 非空 错误
商户号 非空，822开头 错误

2.1.2 批量上传功能

功能描述：支持批量上传商户信息文件并进行校验

批量上传按钮实现要求：

模态框功能组件：

2.1.3 历史记录管理

功能描述：查询和管理历史校验记录

具体需求：

查询筛选条件：

2.1.4 状态字段定义和流转逻辑

校验状态字段：

状态值 状态名称 显示样式 说明
completed 已完成 绿色标签 校验已完成
failed 校验失败 红色标签 校验过程中发生错误

状态流转逻辑：

  1. 文件上传 → 直接进行校验处理
  2. 校验完成 → completed（已完成）或 failed（校验失败）
  3. completed 状态下显示校验结果：pass、fail

2.1.5 操作栏功能和交互逻辑

主表格操作栏：

批量上传模态框操作栏：

2.1.6 模版下载功能

功能描述：提供标准的数据导入模版

具体需求：

模版字段：

字段名 字段类型 是否必填 说明
机构银行 文本 是 银行全称
商户号 文本 是 822开头的商户号

2.2 模态框功能详细说明

2.2.1 批量上传模态框

模态框结构：

批量上传模态框 (800px × 100vh)
├── 头部区域
│ ├── 标题：批量上传商户信息
│ └── 关闭按钮
├── 主体区域
│ ├── 筛选条件区域
│ │ ├── 文件名输入框
│ │ ├── 机构银行下拉选择
│ │ ├── 校验状态下拉选择
│ │ ├── 开始日期选择器
│ │ └── 结束日期选择器
│ ├── 操作按钮区域
│ │ ├── 上传文件按钮（主按钮）
│ │ ├── 导出记录按钮
│ │ ├── 查询按钮
│ │ └── 重置按钮
│ └── 上传记录表格区域
│ ├── 表格头部（文件名、机构银行、上传时间、状态、操作）
│ ├── 表格内容（动态加载）
│ └── 空状态提示
└── 底部区域（无）

模态框交互逻辑：

  1. 打开模态框：
    • 点击"批量上传"按钮
    • 模态框从右侧滑入，背景显示遮罩层
    • 自动加载历史上传记录
  2. 上传文件流程：
    • 点击"上传文件"按钮
    • 弹出文件选择对话框
    • 选择文件后自动开始上传
    • 显示上传进度（可选）
    • 上传成功后在表格中新增记录
  3. 筛选功能：
    • 支持按文件名模糊查询
    • 支持按机构银行筛选
    • 支持按校验状态筛选
    • 支持按日期范围筛选
    • 点击"查询"按钮应用筛选条件
    • 点击"重置"按钮清空所有筛选条件
  4. 导出功能：
    • 点击"导出记录"按钮
    • 导出当前筛选条件下的所有记录
    • 格式：CSV文件
    • 文件名：批量上传记录_日期.csv
  5. 记录操作：
    • 刷新：针对处理中和待处理状态的记录
    • 下载：针对已完成和失败状态的记录
    • 重试：针对失败状态的记录
  6. 关闭模态框：
    • 点击关闭按钮或遮罩层
    • 模态框滑出到右侧，遮罩层消失
    • 恢复页面滚动

2.3 辅助功能

2.2.1 统计面板

功能描述：实时显示校验统计数据

统计指标：

2.2.2 操作日志

功能描述：记录所有用户操作行为

日志内容：

3. 数据表格字段定义和业务逻辑

3.1 主数据表格字段定义

字段名 字段类型 数据来源 显示规则 业务逻辑
ID 数值 数据库自增 数字 唯一标识符
机构银行 文本 文件数据 银行全称 支持模糊查询
商户号 文本 文件数据 822开头 必填，格式校验
结算卡号（脱敏） 文本 三代系统查询 6227********1234 敏感信息脱敏显示
校验状态 枚举 校验结果 彩色标签 completed/failed
校验结果 枚举 校验结果 彩色标签 pass/fail
文件名 文本 上传文件 完整文件名 支持模糊查询
校验时间 日期时间 系统生成 YYYY-MM-DD HH:mm:ss 默认当前时间
操作人 文本 系统获取 用户姓名 当前登录用户

3.2 批量上传记录表格字段定义

字段名 字段类型 数据来源 显示规则 业务逻辑
文件名 文本 上传文件 完整文件名 支持模糊查询
机构银行 文本 文件数据或筛选条件 银行全称 支持筛选
上传时间 日期时间 系统生成 YYYY-MM-DD HH:mm:ss 上传完成时间
商户号 文本 上传文件 完整商户号
结算卡号 文本 三代系统查询 6227********1234前四后
状态 枚举 处理结果 彩色标签 success/processing/failed/pending

3.3 数据表格业务逻辑

3.3.1 数据加载逻辑

1. 初始加载：
- 页面加载时查询最近30天的记录
- 默认按校验时间倒序排列
- 每页显示10条记录

2. 查询逻辑：
- 支持多条件组合查询
- 所有条件均为AND关系
- 文本字段支持模糊匹配
- 日期范围包含边界值

3. 分页逻辑：
- 支持动态调整每页显示条数（10/20/50/100）
- 分页器显示当前页前后2页
- 总记录数实时更新

3.3.2 数据校验逻辑

1. 文件格式校验：
```javascript // 支持的文件格式 const allowedFormats = ['.xlsx', '.xls', '.csv']; const maxSize = 5 * 1024 * 1024; // 5MB ```

2. 数据格式校验：
- 商户号：必须以822开头，长度15-20位
- 银行名称：必须在支持的银行列表中
- 结算卡号：符合银行卡号格式规则

3. 业务逻辑校验：
```javascript // 校验流程 1. 根据银行ID查找可用查询接口 2. 使用商户号查询三代系统获取结算卡号 3. 调用对应银行校验接口验证卡号 4. 记录校验结果并更新状态 ```

3.3.3 状态更新逻辑

1. 实时状态更新：
- 使用WebSocket或定时轮询更新状态
- 处理中的记录每30秒刷新一次状态
- 用户手动刷新立即更新状态

2. 状态持久化：
- 所有状态变更记录到数据库
- 支持状态变更历史查询
- 异常状态自动告警

4. 校验逻辑设计

4.1 核心校验流程

校验逻辑说明：商户信息校验采用多步骤验证机制，确保数据的准确性和完整性。

4.1.1 校验流程设计

步骤1：银行接口可用性校验
├─ 输入：银行ID
├─ 处理：查询系统配置中的银行接口映射表
├─ 判断：是否存在对应的查询接口
└─ 输出：接口可用状态

步骤2：商户信息查询
├─ 输入：商户号
├─ 处理：调用三代系统查询商户结算卡卡号
├─ 验证：商户号有效性检查
└─ 输出：商户结算卡信息

步骤3：银行校验接口调用
├─ 输入：商户结算卡卡号 + 银行ID
├─ 处理：调用对应银行的校验接口
├─ 验证：卡号与银行匹配性校验
└─ 输出：校验结果详情

步骤4：结果记录与反馈
├─ 处理：记录校验结果到数据库
├─ 反馈：向控制台返回校验状态
└─ 展示：实时更新校验进度和结果

4.1.2 校验规则矩阵

校验阶段 校验项目 校验规则 错误级别 处理方式
前置校验 银行ID 非空 + 系统支持性检查 错误 终止校验，返回错误信息
商户号 非空 + 格式验证 错误 终止校验，返回错误信息
系统查询 商户存在性 三代系统中商户号存在 错误 记录失败，继续下一项
结算卡信息 商户结算卡号不为空 警告 记录警告，继续校验
银行校验 卡号有效性 银行接口验证卡号有效 错误 记录失败结果
银行匹配性 卡号归属银行与输入银行ID匹配 错误 记录失败结果

4.1.3 异常处理机制

异常场景处理：

4.2 数据流转设计

4.2.1 校验数据流程

文件上传 → 数据解析 → 批量入队 → 逐条校验 → 结果汇总 → 状态更新

详细说明：
1. 文件上传：用户上传CSV文件，系统验证文件格式
2. 数据解析：解析文件内容，提取银行ID和商户号
3. 批量入队：将校验任务加入消息队列，支持并发处理
4. 逐条校验：按照校验逻辑对每条记录进行处理
5. 结果汇总：收集所有校验结果，生成统计报告
6. 状态更新：更新数据库状态，向前端推送实时结果

4.2.2 状态机设计

状态 触发条件 后续状态 说明
待处理 文件上传完成 处理中 / 校验失败 初始状态，等待开始校验
处理中 开始校验流程 校验成功 / 校验失败 / 系统异常 正在执行校验逻辑
校验成功 所有校验步骤通过 - 最终成功状态
校验失败 任一校验步骤失败 - 最终失败状态，可查看失败原因
系统异常 接口调用失败或超时 处理中 / 校验失败 可重试状态，超过重试次数则标记为失败

5. 交互设计需求

5.1 用户操作流程

5.1.1 批量上传流程

1. 点击"批量上传"按钮
2. 右侧滑出模态框（800px宽度）
3. 在模态框中点击"上传文件"按钮
4. 选择文件（支持.xlsx、.xls、.csv格式）
5. 系统验证文件格式和大小（最大5MB）
6. 开始上传，在表格中新增记录，状态为"处理中"
7. 后台异步执行校验逻辑
8. 校验完成后更新记录状态
9. 可通过"刷新"按钮手动更新状态

5.1.2 校验逻辑

1. 接口可用性检查：
- 根据银行ID查找可用的查询接口
- 如果不存在可用接口，直接返回"当前银行不支持校验"

2. 商户信息查询：
- 使用商户号调用三代系统查询接口
- 获取商户结算卡号
- 如果查询失败，记录错误信息

3. 银行校验调用：
- 根据商户结算卡号和银行ID
- 调用对应银行的校验接口
- 获取校验结果（通过/未通过）

4. 结果记录：
- 将校验结果记录到数据库
- 更新记录状态和校验结果
- 在控制台界面展示最新状态

5.1.3 数据查询流程

1. 在查询表单中设置筛选条件
2. 点击"查询"按钮
3. 系统执行查询并返回数据
4. 分页展示查询结果
5. 支持记录的刷新和下载操作

5.1.4 记录操作流程

1. 批量导出：
- 点击"批量导出"按钮
- 导出所有符合条件的记录
- 生成包含所有记录的CSV文件

2. 状态自动更新：
- 校验状态通过后台异步更新
- 用户可通过重新查询查看最新状态
- 不需要手动刷新操作

5.2 交互反馈

5.2.1 操作反馈

- 成功操作：绿色提示信息（Toast或Alert）
- 失败操作：红色错误信息（Toast或Alert）
- 警告信息：黄色提示信息（Toast或Alert）
- 加载状态：转圈动画+文字提示
- 模态框：右侧滑入动画，背景遮罩层

5.2.2 表单验证

- 实时验证：输入时即时验证格式
- 提交验证：查询时统一验证所有条件
- 错误提示：具体字段错误信息
- 成功提示：操作成功的确认信息

5.2.3 状态标识

- 待校验：灰色圆点标签
- 校验中：橙色圆点标签
- 已完成：绿色圆点标签
- 校验失败：红色圆点标签
- 通过：绿色圆点标签
- 未通过：红色圆点标签
- 部分通过：黄色圆点标签

6. 界面设计需求

6.1 整体布局

6.2 页面结构

商户信息校验控制台
├── 查询表单区域
│ ├── 筛选条件行（机构银行、商户号、文件名）
│ ├── 筛选条件行（校验时间、校验状态、校验结果）
│ └── 操作按钮行（批量上传、批量导出、查询、重置）
├── 数据表格区域
│ ├── 表格头部（标题）
│ ├── 表格内容（数据行）
│ └── 分页控件
└── 批量上传模态框（隐藏状态）

7. 枚举值定义

7.1 校验状态 (validation_status)

枚举值 中文名称 说明
completed 已完成 校验已完成
failed 校验失败 校验过程中发生错误

7.2 校验结果 (validation_result)

枚举值 中文名称 说明
pass 通过 所有校验项目均通过
fail 未通过 至少一个校验项目未通过

7.3 批次状态 (status)

枚举值 中文名称 说明
pending 待处理 批次创建完成，等待处理
processing 处理中 正在处理批次数据
success 已完成 批次处理完成
failed 失败 批次处理失败

© 2025 商户信息校验控制台需求

文档版本：V1.0 | 最后更新：2025年10月20日

文档维护：产品团队