新增项目详情流水明细查询设计文档

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

@@ -0,0 +1,371 @@
+# 项目详情流水明细查询设计
+
+## 概述
+
+本次设计面向项目详情页中的“流水明细查询”菜单，按原型图实现“查询 + 筛选 + 导出”能力，不包含旧需求中的“加入分析”“二次分析”等扩展功能。
+
+页面默认查询当前项目下全部已入库流水，数据源仅使用本地表 `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. 当前页面不引入旧需求中的二次分析能力
+- 后续若扩展，需要新增业务表与关联逻辑