ccdi/docs/plans/2026-03-10-project-detail-transaction-query-design.md

项目详情流水明细查询设计

概述

本次设计面向项目详情页中的“流水明细查询”菜单，按原型图实现“查询 + 筛选 + 导出”能力，不包含旧需求中的“加入分析”“二次分析”等扩展功能。

页面默认查询当前项目下全部已入库流水，数据源仅使用本地表 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. 当前页面不引入旧需求中的二次分析能力

• 后续若扩展，需要新增业务表与关联逻辑