372 lines
9.3 KiB
Markdown
372 lines
9.3 KiB
Markdown
# 项目详情流水明细查询设计
|
||
|
||
## 概述
|
||
|
||
本次设计面向项目详情页中的“流水明细查询”菜单，按原型图实现“查询 + 筛选 + 导出”能力，不包含旧需求中的“加入分析”“二次分析”等扩展功能。
|
||
|
||
页面默认查询当前项目下全部已入库流水，数据源仅使用本地表 `ccdi_bank_statement`，不再依赖上传记录的“查看流水”跳转。上传数据页同步移除上传记录表的操作列，后续不再从上传记录进入流水明细页。
|
||
|
||
## 已确认范围
|
||
|
||
- 页面入口保留在项目详情页的 `detail` 菜单
|
||
- 默认查询范围为当前 `projectId` 下全部流水
|
||
- 上传页移除“查看流水”入口
|
||
- “导出流水”需要实现真实功能
|
||
- 导出范围为当前页面筛选后的全部结果
|
||
- 本次只做“查询 + 筛选 + 导出”
|
||
- 摘要筛选仅使用 `userMemo`
|
||
- 筛选栏中的多选项需要基于整个项目维度单独查询
|
||
- 进入页面时即并行加载列表数据和项目级多选项
|
||
|
||
## 方案对比
|
||
|
||
### 方案一：本地库专用查询模块
|
||
|
||
- 在 `ccdi-project` 模块新增银行流水查询 Controller、Service、Mapper 查询方法
|
||
- 页面直接查询本地 `ccdi_bank_statement`
|
||
- 导出使用本地查询条件复用
|
||
|
||
优点：
|
||
|
||
- 与现有“上传后落本地库”架构一致
|
||
- 查询与导出结果稳定，可复现
|
||
- 后续可继续扩展更多项目级分析能力
|
||
|
||
缺点：
|
||
|
||
- 需要补充 DTO、VO、Mapper SQL、导出模型
|
||
|
||
### 方案二：大而全聚合接口
|
||
|
||
- 用一个接口同时返回列表、多选项、统计信息
|
||
|
||
优点：
|
||
|
||
- 前端调用少
|
||
|
||
缺点：
|
||
|
||
- 接口职责混杂
|
||
- 后续增加筛选维度时维护成本高
|
||
- 导出仍需要单独处理
|
||
|
||
### 方案三：直接回源 LSFX 接口
|
||
|
||
- 页面查询与导出实时调用流水分析平台接口
|
||
|
||
优点：
|
||
|
||
- 本地查询层改动少
|
||
|
||
缺点：
|
||
|
||
- 与现有本地入库方案冲突
|
||
- 项目级全量查询稳定性差
|
||
- 页面与导出口径难统一
|
||
|
||
## 选型
|
||
|
||
采用方案一：本地库专用查询模块。
|
||
|
||
该方案与当前 `ccdi_bank_statement`、`CcdiFileUploadServiceImpl` 的入库逻辑一致，最符合“项目维度统一查询 + 当前筛选导出”的实现要求。
|
||
|
||
## 页面结构
|
||
|
||
页面仍由 `ruoyi-ui/src/views/ccdiProject/detail.vue` 动态加载 `DetailQuery.vue`。
|
||
|
||
`DetailQuery.vue` 从占位组件升级为正式页面，整体布局分为左右两栏：
|
||
|
||
- 左侧：固定筛选栏
|
||
- 右侧：结果区域
|
||
|
||
右侧结果区域包含：
|
||
|
||
- 标题“流水明细查询”
|
||
- 顶部页签：`全部` / `流入` / `流出`
|
||
- 导出按钮：`导出流水`
|
||
- 列表表格
|
||
- 分页器
|
||
|
||
列表中的操作位保留只读详情能力，用于打开详情抽屉或弹窗查看单条流水完整字段。
|
||
|
||
## 筛选项设计
|
||
|
||
左侧筛选栏按原型提供以下条件：
|
||
|
||
1. 交易时间
|
||
- 对应字段：`trxDate`
|
||
- 支持起止范围查询
|
||
- 后端兼容 `yyyy-MM-dd HH:mm:ss` 和 `yyyy-MM-dd`
|
||
|
||
2. 对方名称 + 空值
|
||
- 对应字段：`customerAccountName`
|
||
- 输入框为模糊匹配
|
||
- 勾选空值时匹配 `null`、空串、全空白字符串
|
||
|
||
3. 摘要 + 空值
|
||
- 对应字段：`userMemo`
|
||
- 输入框为模糊匹配
|
||
- 勾选空值时匹配 `null`、空串、全空白字符串
|
||
|
||
4. 本方主体
|
||
- 对应字段：`leAccountName`
|
||
- 多选
|
||
|
||
5. 本方银行
|
||
- 对应字段：`bank`
|
||
- 多选
|
||
|
||
6. 本方账户
|
||
- 对应字段：`leAccountNo`
|
||
- 多选
|
||
|
||
7. 交易金额
|
||
- 使用绝对值范围筛选
|
||
- 统一适配 `全部 / 流入 / 流出` 三个页签
|
||
|
||
8. 对方账户 + 空值
|
||
- 对应字段：`customerAccountNo`
|
||
- 输入框为模糊匹配
|
||
|
||
9. 交易类型 + 空值
|
||
- 对应字段：`cashType`
|
||
- 输入框为模糊匹配
|
||
|
||
## 多选项加载规则
|
||
|
||
本方主体、本方银行、本方账户三类多选项不从当前列表结果派生，而是通过单独接口按整个项目维度去重查询。
|
||
|
||
进入页面时前端并行加载：
|
||
|
||
- 列表接口：默认查询当前项目全部流水
|
||
- 多选项接口：返回整个项目维度的全部主体、银行、账户选项
|
||
|
||
多选项接口返回值：
|
||
|
||
- `ourSubjectOptions`
|
||
- `ourBankOptions`
|
||
- `ourAccountOptions`
|
||
|
||
前端多选框内部搜索仅在已加载的项目级选项上做本地过滤，不再触发额外远程请求。
|
||
|
||
## 列表列设计
|
||
|
||
表格列与原型语义对齐：
|
||
|
||
1. 交易时间
|
||
- 字段：`trxDate`
|
||
|
||
2. 本行账户/主体
|
||
- 主行：`leAccountNo`
|
||
- 副行：`leAccountName`
|
||
|
||
3. 对方名称/账户
|
||
- 主行：`customerAccountName`
|
||
- 副行：`customerAccountNo`
|
||
|
||
4. 摘要/交易类型
|
||
- 主行：`userMemo`
|
||
- 副行：`cashType`
|
||
|
||
5. 交易金额
|
||
- 流入显示 `+amountCr`
|
||
- 流出显示 `-amountDr`
|
||
- 页面展示统一输出计算后的 `displayAmount`
|
||
|
||
6. 操作
|
||
- 只读详情
|
||
|
||
## 页签与排序规则
|
||
|
||
### 页签规则
|
||
|
||
- `全部`：不过滤金额方向
|
||
- `流入`：仅查询 `amount_cr > 0`
|
||
- `流出`：仅查询 `amount_dr > 0`
|
||
|
||
### 排序规则
|
||
|
||
支持两个排序字段：
|
||
|
||
- 交易时间
|
||
- 交易金额
|
||
|
||
排序方向支持：
|
||
|
||
- 升序
|
||
- 降序
|
||
|
||
交易金额排序按绝对值排序，和金额范围筛选保持一致。
|
||
|
||
排序字段必须由后端白名单控制，禁止前端任意传值直接拼接 SQL。
|
||
|
||
## 后端接口设计
|
||
|
||
建议新增专用 Controller：`CcdiBankStatementController`
|
||
|
||
### 1. 列表分页查询
|
||
|
||
- 路径：`GET /ccdi/project/bank-statement/list`
|
||
- 入参：`CcdiBankStatementQueryDTO`
|
||
- 返回：`TableDataInfo`
|
||
|
||
入参字段包括：
|
||
|
||
- `projectId`
|
||
- `tabType`
|
||
- `transactionStartTime`
|
||
- `transactionEndTime`
|
||
- `counterpartyName`
|
||
- `counterpartyNameEmpty`
|
||
- `userMemo`
|
||
- `userMemoEmpty`
|
||
- `ourSubjects`
|
||
- `ourBanks`
|
||
- `ourAccounts`
|
||
- `amountMin`
|
||
- `amountMax`
|
||
- `counterpartyAccount`
|
||
- `counterpartyAccountEmpty`
|
||
- `transactionType`
|
||
- `transactionTypeEmpty`
|
||
- `orderBy`
|
||
- `orderDirection`
|
||
|
||
### 2. 多选项查询
|
||
|
||
- 路径：`GET /ccdi/project/bank-statement/options`
|
||
- 入参：`projectId`
|
||
- 返回：`CcdiBankStatementFilterOptionsVO`
|
||
|
||
### 3. 单条详情
|
||
|
||
- 路径：`GET /ccdi/project/bank-statement/detail/{bankStatementId}`
|
||
- 返回：`CcdiBankStatementDetailVO`
|
||
|
||
### 4. 导出
|
||
|
||
- 路径：`POST /ccdi/project/bank-statement/export`
|
||
- 入参：复用 `CcdiBankStatementQueryDTO`
|
||
- 返回：Excel 文件流
|
||
|
||
## 服务层设计
|
||
|
||
建议新增：
|
||
|
||
- `ICcdiBankStatementService`
|
||
- `CcdiBankStatementServiceImpl`
|
||
|
||
职责拆分：
|
||
|
||
- 列表查询参数校验与标准化
|
||
- 排序字段白名单处理
|
||
- 时间范围解析与兼容
|
||
- 多选项去重查询
|
||
- 单条详情查询
|
||
- 导出列表查询与导出模型组装
|
||
|
||
## Mapper 设计
|
||
|
||
保留现有 `CcdiBankStatementMapper`，在接口和 XML 中新增查询方法，不新增独立 Mapper。
|
||
|
||
建议补充的方法：
|
||
|
||
- `selectStatementPage`
|
||
- `selectStatementListForExport`
|
||
- `selectFilterOptions`
|
||
- `selectStatementDetailById`
|
||
|
||
SQL 规则：
|
||
|
||
- 基于 `project_id` 做主过滤
|
||
- 使用动态 SQL 处理输入框、空值、多选数组
|
||
- 用统一表达式计算排序时间字段
|
||
- 用统一表达式计算展示金额与金额排序值
|
||
|
||
## 前端设计
|
||
|
||
建议新增 API 文件：
|
||
|
||
- `ruoyi-ui/src/api/ccdiProjectBankStatement.js`
|
||
|
||
建议改造文件：
|
||
|
||
- `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
|
||
- `ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue`
|
||
|
||
页面初始化流程：
|
||
|
||
1. 读取 `projectId`
|
||
2. 并行调用：
|
||
- `list`
|
||
- `options`
|
||
3. 渲染左侧筛选和右侧列表
|
||
|
||
交互规则：
|
||
|
||
- 查询、页签切换、排序切换、分页切换时重置到第一页并刷新列表
|
||
- 重置时恢复默认筛选并回到 `全部`
|
||
- 导出时使用当前筛选条件导出全部结果
|
||
|
||
## 导出规则
|
||
|
||
- 导出范围：当前页面筛选后的全部结果
|
||
- 不受当前分页限制
|
||
- 导出文件名：`项目名称_流水明细_时间戳.xlsx`
|
||
- 导出列与页面列表保持一致：
|
||
- 交易时间
|
||
- 本方账户
|
||
- 本方主体
|
||
- 对方名称
|
||
- 对方账户
|
||
- 摘要
|
||
- 交易类型
|
||
- 交易金额
|
||
- 当前筛选结果为空时，不生成空文件，直接提示“当前条件下无可导出数据”
|
||
|
||
## 异常处理
|
||
|
||
- 多选项接口失败：列表仍可查询，筛选项置空并提示可刷新重试
|
||
- 列表接口失败：显示错误态并保留当前筛选值
|
||
- 详情接口失败：仅阻断详情展示，不影响主页面
|
||
- 导出失败：保留筛选条件并提示失败原因
|
||
- 项目下无流水数据：显示空态，导出按钮禁用
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收
|
||
|
||
- 进入页面时并行加载列表与项目级多选项
|
||
- 默认展示当前项目下全部流水
|
||
- 三个页签切换结果正确
|
||
- 所有筛选项单独与组合查询均正确
|
||
- 空值筛选逻辑正确
|
||
- 交易时间兼容两种时间格式
|
||
- 金额范围按绝对值筛选正确
|
||
- 排序仅支持交易时间与交易金额
|
||
- 导出结果与页面筛选口径一致
|
||
- 上传页操作列已移除，不再支持查看流水跳转
|
||
|
||
### 技术验收
|
||
|
||
- 后端遵循项目 DTO / VO 分层规范
|
||
- Controller 使用 Swagger 注释
|
||
- 简单查询由 MyBatis Plus + XML 动态 SQL 实现
|
||
- 前端 API 独立封装到 `src/api`
|
||
- 页面在桌面端和移动端均可正常展示
|
||
|
||
## 风险与约束
|
||
|
||
1. `TRX_DATE` 为字符串字段
|
||
- 需要在 SQL 或服务层统一解析，保证筛选与排序稳定
|
||
|
||
2. 历史数据可能存在空字符串与空白字符串混用
|
||
- 空值筛选必须统一兼容
|
||
|
||
3. 项目维度多选项可能数量较大
|
||
- 首版先按项目维度一次性加载
|
||
- 若实际数据量过大，再考虑远程搜索优化
|
||
|
||
4. 当前页面不引入旧需求中的二次分析能力
|
||
- 后续若扩展，需要新增业务表与关联逻辑
|