新增拉取本行信息设计文档
This commit is contained in:
390
docs/plans/2026-03-11-project-detail-pull-bank-info-design.md
Normal file
390
docs/plans/2026-03-11-project-detail-pull-bank-info-design.md
Normal file
@@ -0,0 +1,390 @@
|
|||||||
|
# 项目详情拉取本行信息设计
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
本次设计面向项目详情页“上传数据”菜单中的“拉取本行信息”能力。用户在页面点击按钮后，弹出录入弹窗，支持手动输入身份证号、上传身份证 Excel 文件自动解析回填、选择时间跨度，然后提交后台异步拉取本行流水。
|
||||||
|
|
||||||
|
后端以项目现有“文件上传记录 + 线程池 + 落本地流水表”的链路为基础实现，不再新增第二套独立任务体系。每个身份证对应一条文件上传记录和一个线程任务，先调用流水分析平台“拉取行内流水”接口获取 `logId`，再复用现有“解析状态轮询 -> 获取文件上传状态 -> 获取流水列表并入库”的后半段处理链路。
|
||||||
|
|
||||||
|
## 已确认范围
|
||||||
|
|
||||||
|
- 页面入口保留在 `ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue`
|
||||||
|
- 点击“拉取本行信息”后弹出表单弹窗，不再使用简单确认框
|
||||||
|
- 弹窗字段包括：
|
||||||
|
- 证件号码文本域
|
||||||
|
- 身份证文件上传
|
||||||
|
- 时间跨度
|
||||||
|
- 身份证文件解析规则：
|
||||||
|
- 读取首个 sheet
|
||||||
|
- 只读取第一列
|
||||||
|
- 忽略表头
|
||||||
|
- 忽略空行
|
||||||
|
- 忽略重复值
|
||||||
|
- 上传身份证文件后立即自动解析，并将结果回填到文本域
|
||||||
|
- 文本域与文件解析结果合并后按输入顺序去重
|
||||||
|
- 文件上传记录表中的 `uploadUser` 使用 `SecurityUtils.getUserName()`
|
||||||
|
- 调用流水分析平台 `fetchInnerFlow` 时的 `uploadUserId` 使用 `SecurityUtils.getUserId()`
|
||||||
|
- 创建上传记录时，先将身份证号写入 `accountNos` 作为主体账号
|
||||||
|
- 每个身份证使用一个线程处理
|
||||||
|
- 在调用“获取单个文件上传后的状态”接口时，根据返回值中的文件名更新文件上传记录
|
||||||
|
- 获取 `logId` 之后的处理步骤与现有“导入流水文件”方法保持一致
|
||||||
|
|
||||||
|
## 方案对比
|
||||||
|
|
||||||
|
### 方案一：在现有文件上传服务中扩展并抽取公共流水线
|
||||||
|
|
||||||
|
- 继续使用 `CcdiFileUploadController`、`ICcdiFileUploadService`、`CcdiFileUploadServiceImpl`
|
||||||
|
- 新增身份证文件解析接口和拉取本行信息提交接口
|
||||||
|
- 将现有“文件上传成功拿到 logId 后”的处理逻辑抽成公共方法，供文件上传和本行拉取共同复用
|
||||||
|
|
||||||
|
优点：
|
||||||
|
|
||||||
|
- 与现有上传记录列表、线程池、状态轮询、流水入库逻辑完全一致
|
||||||
|
- 复用度最高，后续维护成本最低
|
||||||
|
- 记录表、状态统计、页面轮询无需新增体系
|
||||||
|
|
||||||
|
缺点：
|
||||||
|
|
||||||
|
- 需要对现有 `CcdiFileUploadServiceImpl` 做一次中等规模重构
|
||||||
|
|
||||||
|
### 方案二：新增独立的本行拉取服务
|
||||||
|
|
||||||
|
- 新建独立 Controller 和 Service
|
||||||
|
- 仅在最后复用“获取流水列表并入库”的局部能力
|
||||||
|
|
||||||
|
优点：
|
||||||
|
|
||||||
|
- 对现有文件上传代码侵入较小
|
||||||
|
|
||||||
|
缺点：
|
||||||
|
|
||||||
|
- 会出现两套高度相似的任务调度和状态回写逻辑
|
||||||
|
- 后续容易出现功能漂移和修复不一致
|
||||||
|
|
||||||
|
### 方案三：在 Controller 中直接串接已有逻辑
|
||||||
|
|
||||||
|
- Controller 直接完成记录插入、线程调度和接口调用
|
||||||
|
|
||||||
|
优点：
|
||||||
|
|
||||||
|
- 早期开发速度快
|
||||||
|
|
||||||
|
缺点：
|
||||||
|
|
||||||
|
- Controller 职责过重
|
||||||
|
- 不利于测试和后续扩展
|
||||||
|
|
||||||
|
## 选型
|
||||||
|
|
||||||
|
采用方案一：在现有文件上传服务中扩展，并抽取“拿到 `logId` 后的公共处理流水线”。
|
||||||
|
|
||||||
|
该方案最符合当前项目已经存在的上传记录表、线程池和流水落库架构，可以保证文件上传和本行拉取在状态、错误处理和数据口径上保持一致。
|
||||||
|
|
||||||
|
## 前端交互设计
|
||||||
|
|
||||||
|
页面文件仍为 `ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue`。
|
||||||
|
|
||||||
|
### 弹窗结构
|
||||||
|
|
||||||
|
新增“拉取本行信息”弹窗，包含以下控件：
|
||||||
|
|
||||||
|
1. 证件号码文本域
|
||||||
|
- 占位提示：支持逗号、中文逗号、换行分隔
|
||||||
|
- 用于展示最终待提交的身份证集合
|
||||||
|
|
||||||
|
2. 身份证文件上传
|
||||||
|
- 仅支持 `.xlsx`、`.xls`
|
||||||
|
- 选中文件后立即自动调用后端解析接口
|
||||||
|
- 解析成功后，把有效身份证集合合并回填到文本域
|
||||||
|
|
||||||
|
3. 时间跨度
|
||||||
|
- 开始日期
|
||||||
|
- 结束日期
|
||||||
|
- 提交时必填
|
||||||
|
|
||||||
|
### 前端交互规则
|
||||||
|
|
||||||
|
1. 用户选择身份证文件后：
|
||||||
|
- 立即上传到解析接口
|
||||||
|
- 前端显示“正在解析身份证文件”
|
||||||
|
- 解析成功后：
|
||||||
|
- 将文件解析出的身份证集合与文本域当前内容合并
|
||||||
|
- 去重后回填到文本域
|
||||||
|
- 提示解析成功及有效条数
|
||||||
|
- 解析失败后：
|
||||||
|
- 保留文本域现有内容
|
||||||
|
- 显示明确错误提示
|
||||||
|
|
||||||
|
2. 用户点击“确认拉取”时：
|
||||||
|
- 前端先对文本域内容做本地拆分和去重
|
||||||
|
- 校验身份证集合非空、日期范围完整
|
||||||
|
- 调用正式提交接口
|
||||||
|
- 提交成功后关闭弹窗，刷新上传记录列表和统计，并开启现有轮询
|
||||||
|
|
||||||
|
3. 页面上传记录列表无需新增新页面：
|
||||||
|
- 本行拉取创建的记录与文件上传记录共用同一列表
|
||||||
|
- 状态、上传时间、上传人展示口径保持一致
|
||||||
|
|
||||||
|
## 后端接口设计
|
||||||
|
|
||||||
|
接口统一放在 `CcdiFileUploadController` 下。
|
||||||
|
|
||||||
|
### 1. 解析身份证文件
|
||||||
|
|
||||||
|
- 路径：`POST /ccdi/file-upload/parse-id-card-file`
|
||||||
|
- 请求类型：`multipart/form-data`
|
||||||
|
- 入参：
|
||||||
|
- `file`
|
||||||
|
- 返回：
|
||||||
|
- `idCards`
|
||||||
|
- `count`
|
||||||
|
|
||||||
|
用途：
|
||||||
|
|
||||||
|
- 供弹窗选择文件后即时解析
|
||||||
|
- 只负责读取、去重、校验身份证，不创建任务
|
||||||
|
|
||||||
|
### 2. 提交拉取本行信息任务
|
||||||
|
|
||||||
|
- 路径：`POST /ccdi/file-upload/pull-bank-info`
|
||||||
|
- 请求类型：`application/json`
|
||||||
|
- 入参：
|
||||||
|
- `projectId`
|
||||||
|
- `idCards`
|
||||||
|
- `startDate`
|
||||||
|
- `endDate`
|
||||||
|
- 返回：
|
||||||
|
- `batchId`
|
||||||
|
|
||||||
|
用途：
|
||||||
|
|
||||||
|
- 正式提交本行拉取任务
|
||||||
|
- 一次请求可提交多个身份证
|
||||||
|
|
||||||
|
## DTO / VO 设计
|
||||||
|
|
||||||
|
建议新增：
|
||||||
|
|
||||||
|
- `CcdiPullBankInfoSubmitDTO`
|
||||||
|
- `Long projectId`
|
||||||
|
- `List<String> idCards`
|
||||||
|
- `String startDate`
|
||||||
|
- `String endDate`
|
||||||
|
|
||||||
|
- `CcdiIdCardParseVO`
|
||||||
|
- `List<String> idCards`
|
||||||
|
- `Integer count`
|
||||||
|
|
||||||
|
## 服务层设计
|
||||||
|
|
||||||
|
继续使用：
|
||||||
|
|
||||||
|
- `ICcdiFileUploadService`
|
||||||
|
- `CcdiFileUploadServiceImpl`
|
||||||
|
|
||||||
|
建议新增两个对外方法：
|
||||||
|
|
||||||
|
1. `parseIdCardFile(MultipartFile file)`
|
||||||
|
- 读取首个 sheet 第一列
|
||||||
|
- 忽略表头、空值、重复值
|
||||||
|
- 统一执行身份证格式校验
|
||||||
|
|
||||||
|
2. `submitPullBankInfo(Long projectId, List<String> idCards, String startDate, String endDate, Long userId, String username)`
|
||||||
|
- 校验项目和日期
|
||||||
|
- 插入上传记录
|
||||||
|
- 在事务提交后调度线程池任务
|
||||||
|
|
||||||
|
## 核心数据流设计
|
||||||
|
|
||||||
|
### 一、身份证文件解析
|
||||||
|
|
||||||
|
1. Controller 接收 Excel 文件
|
||||||
|
2. Service 使用 EasyExcel 读取首个 sheet 第一列
|
||||||
|
3. 将单元格内容转成字符串并清理空白
|
||||||
|
4. 忽略首行表头
|
||||||
|
5. 使用 `LinkedHashSet` 去重并保序
|
||||||
|
6. 对每个值执行身份证格式校验
|
||||||
|
7. 返回有效身份证集合
|
||||||
|
|
||||||
|
### 二、正式提交任务
|
||||||
|
|
||||||
|
1. 校验 `projectId`
|
||||||
|
2. 查询项目，获取 `lsfxProjectId`
|
||||||
|
3. 校验 `startDate`、`endDate`
|
||||||
|
4. 校验身份证集合非空
|
||||||
|
5. 为每个身份证创建一条 `ccdi_file_upload_record`
|
||||||
|
- `projectId = 当前项目`
|
||||||
|
- `lsfxProjectId = 项目关联流水分析ID`
|
||||||
|
- `fileStatus = uploading`
|
||||||
|
- `fileName = 身份证号`
|
||||||
|
- `accountNos = 身份证号`
|
||||||
|
- `uploadUser = SecurityUtils.getUserName()`
|
||||||
|
- `uploadTime = 当前时间`
|
||||||
|
6. 批量插入记录
|
||||||
|
7. 在事务提交后启动调度线程
|
||||||
|
|
||||||
|
### 三、线程处理单个身份证
|
||||||
|
|
||||||
|
每个身份证一个线程，使用现有 `fileUploadExecutor`。
|
||||||
|
|
||||||
|
单线程处理步骤：
|
||||||
|
|
||||||
|
1. 调用 `fetchInnerFlow`
|
||||||
|
- `groupId = lsfxProjectId`
|
||||||
|
- `customerNo = 身份证号`
|
||||||
|
- `dataChannelCode = ZJRCU`
|
||||||
|
- `requestDateId = 当天 yyyyMMdd`
|
||||||
|
- `dataStartDateId = 开始日期 yyyyMMdd`
|
||||||
|
- `dataEndDateId = 结束日期 yyyyMMdd`
|
||||||
|
- `uploadUserId = SecurityUtils.getUserId()`
|
||||||
|
|
||||||
|
2. 从响应中获取唯一 `logId`
|
||||||
|
|
||||||
|
3. 进入公共处理流水线
|
||||||
|
- 更新记录 `logId`
|
||||||
|
- 更新状态为 `parsing`
|
||||||
|
- 轮询解析状态
|
||||||
|
- 调用“获取单个文件上传状态”接口
|
||||||
|
- 读取文件名字段，优先使用 `uploadFileName`，取不到则回退 `downloadFileName`
|
||||||
|
- 将文件名回写到 `ccdi_file_upload_record.file_name`
|
||||||
|
- 提取主体名称、主体账号
|
||||||
|
- 调用“获取流水列表”接口分页拉取并入库
|
||||||
|
- 成功后更新状态为 `parsed_success`
|
||||||
|
- 失败时更新状态为 `parsed_failed`
|
||||||
|
|
||||||
|
## 公共流水线重构设计
|
||||||
|
|
||||||
|
当前 `CcdiFileUploadServiceImpl` 中，`processFileAsync` 同时承担“上传文件并拿到 `logId`”和“拿到 `logId` 后继续处理”两段职责。
|
||||||
|
|
||||||
|
本次建议拆成两段：
|
||||||
|
|
||||||
|
1. 文件来源阶段
|
||||||
|
- 上传文件拿到 `logId`
|
||||||
|
- 或者拉取本行信息拿到 `logId`
|
||||||
|
|
||||||
|
2. 公共处理阶段
|
||||||
|
- 接收 `projectId`、`lsfxProjectId`、`record`、`logId`
|
||||||
|
- 负责后续统一处理
|
||||||
|
|
||||||
|
拆分后：
|
||||||
|
|
||||||
|
- 现有 `processFileAsync` 仍然保留，但只负责文件上传到平台并获得 `logId`
|
||||||
|
- 新增 `processPullBankInfoAsync` 负责调用 `fetchInnerFlow` 并获得 `logId`
|
||||||
|
- 两者统一调用新的公共处理方法，例如：
|
||||||
|
- `processRecordAfterLogIdReady(...)`
|
||||||
|
|
||||||
|
## 文件上传记录表回写规则
|
||||||
|
|
||||||
|
### 记录初始化
|
||||||
|
|
||||||
|
- `fileName`：先写身份证号占位
|
||||||
|
- `accountNos`：写身份证号
|
||||||
|
- `enterpriseNames`：初始为空
|
||||||
|
|
||||||
|
### 状态接口返回后
|
||||||
|
|
||||||
|
- 若状态接口返回 `uploadFileName`，更新到 `fileName`
|
||||||
|
- 若 `uploadFileName` 为空但 `downloadFileName` 不为空，回写 `downloadFileName`
|
||||||
|
- `enterpriseNameList` 存在时更新 `enterpriseNames`
|
||||||
|
- `accountNoList` 存在时更新 `accountNos`
|
||||||
|
|
||||||
|
## 异常处理
|
||||||
|
|
||||||
|
### 提交阶段异常
|
||||||
|
|
||||||
|
以下场景直接拦截，不进入异步任务：
|
||||||
|
|
||||||
|
- 项目不存在
|
||||||
|
- 项目未绑定 `lsfxProjectId`
|
||||||
|
- 身份证集合为空
|
||||||
|
- 开始日期或结束日期为空
|
||||||
|
- 开始日期大于结束日期
|
||||||
|
|
||||||
|
### 文件解析异常
|
||||||
|
|
||||||
|
- 文件为空
|
||||||
|
- 文件格式不是 Excel
|
||||||
|
- 首个 sheet 第一列没有有效身份证
|
||||||
|
- 存在非法身份证号
|
||||||
|
|
||||||
|
解析异常直接返回错误，不覆盖前端已有输入值。
|
||||||
|
|
||||||
|
### 异步执行异常
|
||||||
|
|
||||||
|
每个身份证单独处理，单条失败不影响其他条目：
|
||||||
|
|
||||||
|
- `fetchInnerFlow` 失败：当前记录标记 `parsed_failed`
|
||||||
|
- 轮询超时：当前记录标记 `parsed_failed`
|
||||||
|
- 获取状态失败：当前记录标记 `parsed_failed`
|
||||||
|
- 获取流水失败：清理该 `logId` 已入库流水后标记 `parsed_failed`
|
||||||
|
|
||||||
|
错误信息统一落入 `error_message`，并延续现有超长错误截断规则。
|
||||||
|
|
||||||
|
## 测试设计
|
||||||
|
|
||||||
|
### 后端测试
|
||||||
|
|
||||||
|
重点新增以下测试：
|
||||||
|
|
||||||
|
1. 身份证文件解析测试
|
||||||
|
- 读取首个 sheet 第一列
|
||||||
|
- 忽略表头、空行、重复值
|
||||||
|
- 非法身份证时返回失败
|
||||||
|
|
||||||
|
2. 提交任务测试
|
||||||
|
- 为每个身份证插入一条上传记录
|
||||||
|
- 初始化 `accountNos` 为身份证号
|
||||||
|
- `uploadUser` 正确记录当前用户名
|
||||||
|
|
||||||
|
3. 公共流水线复用测试
|
||||||
|
- `fetchInnerFlow` 成功后能进入公共处理链路
|
||||||
|
- 状态接口返回文件名时能正确回写到记录表
|
||||||
|
- 流水入库失败时能清理已写入数据
|
||||||
|
|
||||||
|
4. Controller 测试
|
||||||
|
- 解析接口成功/失败
|
||||||
|
- 提交接口成功/失败
|
||||||
|
|
||||||
|
### 前端验证
|
||||||
|
|
||||||
|
- 选择身份证文件后自动解析并回填
|
||||||
|
- 手输身份证与文件解析结果正确合并去重
|
||||||
|
- 日期必填校验生效
|
||||||
|
- 提交成功后弹窗关闭并刷新列表
|
||||||
|
- 正在执行的记录可通过现有轮询刷新状态
|
||||||
|
|
||||||
|
## 验收标准
|
||||||
|
|
||||||
|
### 功能验收
|
||||||
|
|
||||||
|
- 上传数据页面可打开“拉取本行信息”弹窗
|
||||||
|
- 身份证 Excel 上传后能自动解析并回填输入框
|
||||||
|
- 提交后每个身份证都创建一条上传记录
|
||||||
|
- 每个身份证走一个线程处理
|
||||||
|
- 状态接口返回文件名后，记录列表能展示更新后的文件名
|
||||||
|
- 成功记录能拉取流水并入库
|
||||||
|
- 失败记录不会影响其他身份证继续执行
|
||||||
|
|
||||||
|
### 技术验收
|
||||||
|
|
||||||
|
- 复用现有 `fileUploadExecutor`
|
||||||
|
- 复用现有上传记录列表、统计和轮询机制
|
||||||
|
- Controller 使用 Swagger 注释
|
||||||
|
- Service 中公共处理逻辑不重复实现两套
|
||||||
|
- 后端测试覆盖解析、提交、公共流水线复用
|
||||||
|
|
||||||
|
## 风险与约束
|
||||||
|
|
||||||
|
1. 身份证文件模板不固定
|
||||||
|
- 首版只按“首个 sheet 第一列”解析
|
||||||
|
- 如后续存在多模板，再扩展模板识别
|
||||||
|
|
||||||
|
2. `fetchInnerFlow` 返回值只提供 `logId`
|
||||||
|
- 必须严格复用后续状态接口和流水接口，不能只看首个响应判断成功
|
||||||
|
|
||||||
|
3. 线程池容量与批量身份证数量存在上限
|
||||||
|
- 沿用现有线程池拒绝重试机制
|
||||||
|
- 超量场景下记录单条失败，不阻断整批任务
|
||||||
|
|
||||||
|
4. 文件名依赖状态接口返回
|
||||||
|
- 需要兼容 `uploadFileName` 为空的场景，并回退 `downloadFileName`
|
||||||
Reference in New Issue
Block a user