新增流水异常标签前后端实施计划
This commit is contained in:
@@ -0,0 +1,426 @@
|
||||
# Bank Statement Hit Tags Backend Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 在现有流水明细查询后端链路中补齐“异常标签”读取与组装能力，让列表、详情、导出统一展示当前流水直接命中的流水级标签。
|
||||
|
||||
**Architecture:** 继续复用现有 `CcdiBankStatementController -> CcdiBankStatementServiceImpl -> CcdiBankStatementMapper` 主链路，不改分页查询入口和筛选协议；新增 `CcdiBankTagResultMapper` 的只读标签查询方法，由 Service 在列表分页、详情查询和导出映射阶段批量补齐 `hitTags` 与导出字符串。所有标签口径统一限定为 `ccdi_bank_statement_tag_result.result_type = 'STATEMENT'` 且 `bank_statement_id` 命中当前流水。
|
||||
|
||||
**Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, JUnit 5, Mockito, Maven
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 补齐流水标签只读查询模型与 Mapper SQL
|
||||
|
||||
**Files:**
|
||||
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementHitTagVO.java`
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankTagResultMapper.java`
|
||||
- Modify: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankTagResultMapper.xml`
|
||||
- Create: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiBankTagResultMapperXmlTest.java`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
先新增 `CcdiBankTagResultMapperXmlTest`，锁定新 SQL 必须只查流水级标签，并按稳定顺序输出：
|
||||
|
||||
```java
|
||||
class CcdiBankTagResultMapperXmlTest {
|
||||
|
||||
@Test
|
||||
void selectStatementHitTagsByIds_shouldFilterStatementResultType() throws Exception {
|
||||
String xml = Files.readString(Path.of(
|
||||
"ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankTagResultMapper.xml"
|
||||
));
|
||||
|
||||
assertTrue(xml.contains("selectStatementHitTagsByBankStatementIds"));
|
||||
assertTrue(xml.contains("result_type = 'STATEMENT'"));
|
||||
assertTrue(xml.contains("bank_statement_id IN"));
|
||||
}
|
||||
|
||||
@Test
|
||||
void selectStatementHitTagsByIds_shouldKeepStableOrder() throws Exception {
|
||||
String xml = Files.readString(Path.of(
|
||||
"ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankTagResultMapper.xml"
|
||||
));
|
||||
|
||||
assertTrue(xml.contains("ORDER BY"));
|
||||
assertTrue(xml.contains("rule_code"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankTagResultMapperXmlTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `FAIL`
|
||||
- 原因是标签明细 VO、Mapper 方法和 XML 查询都还不存在
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
最小实现包含 4 个点：
|
||||
|
||||
1. 新增标签明细 VO：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class CcdiBankStatementHitTagVO {
|
||||
private Long bankStatementId;
|
||||
private String ruleName;
|
||||
private String riskLevel;
|
||||
private String reasonDetail;
|
||||
private String ruleCode;
|
||||
}
|
||||
```
|
||||
|
||||
2. 在 `CcdiBankTagResultMapper` 中新增：
|
||||
|
||||
```java
|
||||
List<CcdiBankStatementHitTagVO> selectStatementHitTagsByBankStatementIds(@Param("bankStatementIds") List<Long> bankStatementIds);
|
||||
|
||||
List<CcdiBankStatementHitTagVO> selectStatementHitTagsByBankStatementId(@Param("bankStatementId") Long bankStatementId);
|
||||
```
|
||||
|
||||
3. 在 `CcdiBankTagResultMapper.xml` 中新增对应 `resultMap` 与查询：
|
||||
|
||||
```xml
|
||||
<select id="selectStatementHitTagsByBankStatementIds" resultMap="CcdiBankStatementHitTagVOResultMap">
|
||||
SELECT bank_statement_id, rule_name, risk_level, reason_detail, rule_code
|
||||
FROM ccdi_bank_statement_tag_result
|
||||
WHERE result_type = 'STATEMENT'
|
||||
AND bank_statement_id IN
|
||||
<foreach collection="bankStatementIds" item="item" open="(" separator="," close=")">
|
||||
#{item}
|
||||
</foreach>
|
||||
ORDER BY bank_statement_id ASC, rule_code ASC
|
||||
</select>
|
||||
```
|
||||
|
||||
4. 单条查询直接复用相同过滤条件：
|
||||
|
||||
```xml
|
||||
<select id="selectStatementHitTagsByBankStatementId" resultMap="CcdiBankStatementHitTagVOResultMap">
|
||||
SELECT bank_statement_id, rule_name, risk_level, reason_detail, rule_code
|
||||
FROM ccdi_bank_statement_tag_result
|
||||
WHERE result_type = 'STATEMENT'
|
||||
AND bank_statement_id = #{bankStatementId}
|
||||
ORDER BY rule_code ASC
|
||||
</select>
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankTagResultMapperXmlTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `PASS`
|
||||
- 说明标签 Mapper 已具备只读查询能力，且不会混入对象级结果
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementHitTagVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankTagResultMapper.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankTagResultMapper.xml ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiBankTagResultMapperXmlTest.java
|
||||
git commit -m "补充流水异常标签结果查询"
|
||||
```
|
||||
|
||||
### Task 2: 在列表与详情查询中组装结构化命中标签
|
||||
|
||||
**Files:**
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementListVO.java`
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementDetailVO.java`
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java`
|
||||
- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
先在 `CcdiBankStatementServiceImplTest` 中补 2 个失败用例，锁定列表分页和详情查询都要回填 `hitTags`：
|
||||
|
||||
```java
|
||||
@Mock
|
||||
private CcdiBankTagResultMapper bankTagResultMapper;
|
||||
|
||||
@Test
|
||||
void selectStatementPage_shouldAssembleStatementHitTags() {
|
||||
Page<CcdiBankStatementListVO> page = new Page<>(1, 10);
|
||||
CcdiBankStatementListVO row = new CcdiBankStatementListVO();
|
||||
row.setBankStatementId(8L);
|
||||
page.setRecords(List.of(row));
|
||||
|
||||
CcdiBankStatementHitTagVO hitTag = new CcdiBankStatementHitTagVO();
|
||||
hitTag.setBankStatementId(8L);
|
||||
hitTag.setRuleName("大额转账交易");
|
||||
|
||||
when(bankStatementMapper.selectStatementPage(any(), any())).thenReturn(page);
|
||||
when(bankTagResultMapper.selectStatementHitTagsByBankStatementIds(List.of(8L)))
|
||||
.thenReturn(List.of(hitTag));
|
||||
|
||||
Page<CcdiBankStatementListVO> result = service.selectStatementPage(new Page<>(1, 10), new CcdiBankStatementQueryDTO());
|
||||
|
||||
assertEquals(1, result.getRecords().get(0).getHitTags().size());
|
||||
assertEquals("大额转账交易", result.getRecords().get(0).getHitTags().get(0).getRuleName());
|
||||
}
|
||||
|
||||
@Test
|
||||
void getStatementDetail_shouldAttachStatementHitTags() {
|
||||
CcdiBankStatementDetailVO detailVO = new CcdiBankStatementDetailVO();
|
||||
detailVO.setBankStatementId(9L);
|
||||
|
||||
CcdiBankStatementHitTagVO hitTag = new CcdiBankStatementHitTagVO();
|
||||
hitTag.setBankStatementId(9L);
|
||||
hitTag.setRuleName("房车消费支出交易");
|
||||
hitTag.setRiskLevel("HIGH");
|
||||
hitTag.setReasonDetail("摘要命中购买房产首付款");
|
||||
|
||||
when(bankStatementMapper.selectStatementDetailById(9L)).thenReturn(detailVO);
|
||||
when(bankTagResultMapper.selectStatementHitTagsByBankStatementId(9L)).thenReturn(List.of(hitTag));
|
||||
|
||||
CcdiBankStatementDetailVO result = service.getStatementDetail(9L);
|
||||
|
||||
assertEquals(1, result.getHitTags().size());
|
||||
assertEquals("HIGH", result.getHitTags().get(0).getRiskLevel());
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `FAIL`
|
||||
- 原因是 `hitTags` 字段和 Service 组装逻辑尚未实现
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
按最小范围补齐结构化标签：
|
||||
|
||||
1. `CcdiBankStatementListVO` 新增：
|
||||
|
||||
```java
|
||||
private List<CcdiBankStatementHitTagVO> hitTags;
|
||||
```
|
||||
|
||||
2. `CcdiBankStatementDetailVO` 新增：
|
||||
|
||||
```java
|
||||
private List<CcdiBankStatementHitTagVO> hitTags;
|
||||
```
|
||||
|
||||
3. `CcdiBankStatementServiceImpl` 注入 `CcdiBankTagResultMapper`
|
||||
4. 在 `selectStatementPage()` 中新增批量组装：
|
||||
|
||||
```java
|
||||
private void fillStatementHitTags(List<CcdiBankStatementListVO> records) {
|
||||
List<Long> ids = records.stream()
|
||||
.map(CcdiBankStatementListVO::getBankStatementId)
|
||||
.filter(Objects::nonNull)
|
||||
.distinct()
|
||||
.toList();
|
||||
Map<Long, List<CcdiBankStatementHitTagVO>> hitTagMap = bankTagResultMapper
|
||||
.selectStatementHitTagsByBankStatementIds(ids)
|
||||
.stream()
|
||||
.collect(Collectors.groupingBy(CcdiBankStatementHitTagVO::getBankStatementId));
|
||||
records.forEach(item -> item.setHitTags(hitTagMap.getOrDefault(item.getBankStatementId(), Collections.emptyList())));
|
||||
}
|
||||
```
|
||||
|
||||
5. 在 `getStatementDetail()` 中按单条流水补齐：
|
||||
|
||||
```java
|
||||
detail.setHitTags(bankTagResultMapper.selectStatementHitTagsByBankStatementId(bankStatementId));
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `PASS`
|
||||
- 说明列表和详情都能拿到结构化标签数据
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementListVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementDetailVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java
|
||||
git commit -m "补充流水明细标签组装逻辑"
|
||||
```
|
||||
|
||||
### Task 3: 扩展导出列并补齐后端交付记录
|
||||
|
||||
**Files:**
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/excel/CcdiBankStatementExcel.java`
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java`
|
||||
- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
|
||||
- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementControllerTest.java`
|
||||
- Create: `docs/reports/implementation/2026-03-19-bank-statement-hit-tags-backend-implementation.md`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
先在 `CcdiBankStatementServiceImplTest` 里锁定导出内容必须包含标签名与原因摘要：
|
||||
|
||||
```java
|
||||
@Test
|
||||
void selectStatementListForExport_shouldMapHitTagsAndReasons() {
|
||||
CcdiBankStatementListVO row = new CcdiBankStatementListVO();
|
||||
row.setBankStatementId(10L);
|
||||
row.setLeAccountNo("6222");
|
||||
|
||||
CcdiBankStatementHitTagVO first = new CcdiBankStatementHitTagVO();
|
||||
first.setBankStatementId(10L);
|
||||
first.setRuleName("房车消费支出交易");
|
||||
first.setReasonDetail("摘要命中购买房产首付款");
|
||||
|
||||
CcdiBankStatementHitTagVO second = new CcdiBankStatementHitTagVO();
|
||||
second.setBankStatementId(10L);
|
||||
second.setRuleName("大额转账交易");
|
||||
second.setReasonDetail("转账金额 200000.00 元超过阈值");
|
||||
|
||||
when(bankStatementMapper.selectStatementListForExport(any())).thenReturn(List.of(row));
|
||||
when(bankTagResultMapper.selectStatementHitTagsByBankStatementIds(List.of(10L)))
|
||||
.thenReturn(List.of(first, second));
|
||||
|
||||
List<CcdiBankStatementExcel> result = service.selectStatementListForExport(new CcdiBankStatementQueryDTO());
|
||||
|
||||
assertEquals("房车消费支出交易；大额转账交易", result.get(0).getHitTagNames());
|
||||
assertEquals("摘要命中购买房产首付款；转账金额 200000.00 元超过阈值", result.get(0).getHitTagReasons());
|
||||
}
|
||||
```
|
||||
|
||||
同时在交付记录里先写骨架：
|
||||
|
||||
```markdown
|
||||
# 流水明细异常标签展示后端实施记录
|
||||
|
||||
## 修改内容
|
||||
- 标签结果只读查询
|
||||
- 列表/详情组装
|
||||
- 导出列扩展
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest,CcdiBankStatementControllerTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `FAIL`
|
||||
- 原因是导出对象还没有标签列，Service 也没有做字符串拼装
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
1. `CcdiBankStatementExcel` 新增两列：
|
||||
|
||||
```java
|
||||
@Excel(name = "异常标签")
|
||||
private String hitTagNames;
|
||||
|
||||
@Excel(name = "命中原因摘要")
|
||||
private String hitTagReasons;
|
||||
```
|
||||
|
||||
2. `CcdiBankStatementServiceImpl.toExcel()` 改为接收当前流水标签集合并拼装：
|
||||
|
||||
```java
|
||||
excel.setHitTagNames(tags.stream().map(CcdiBankStatementHitTagVO::getRuleName).collect(Collectors.joining("；")));
|
||||
excel.setHitTagReasons(tags.stream().map(CcdiBankStatementHitTagVO::getReasonDetail).filter(StringUtils::isNotBlank).collect(Collectors.joining("；")));
|
||||
```
|
||||
|
||||
3. 导出查询阶段复用 Task 2 的批量标签查询逻辑，不新增第二套口径
|
||||
4. 完成 `docs/reports/implementation/2026-03-19-bank-statement-hit-tags-backend-implementation.md`，记录改动文件、测试命令和结果
|
||||
|
||||
- [ ] **Step 4: Run tests to verify they pass**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project -Dtest=CcdiBankTagResultMapperXmlTest,CcdiBankStatementServiceImplTest,CcdiBankStatementControllerTest test
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `PASS`
|
||||
- 说明标签查询、列表详情组装、导出扩展都已通过回归
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/excel/CcdiBankStatementExcel.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementControllerTest.java docs/reports/implementation/2026-03-19-bank-statement-hit-tags-backend-implementation.md
|
||||
git commit -m "补充流水异常标签后端导出能力"
|
||||
```
|
||||
|
||||
### Task 4: 进行接口级人工回归并确认无对象级标签串入
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/reports/implementation/2026-03-19-bank-statement-hit-tags-backend-implementation.md`
|
||||
|
||||
- [ ] **Step 1: Prepare the manual verification checklist**
|
||||
|
||||
在实施记录中补充 4 个后端联调点：
|
||||
|
||||
```markdown
|
||||
## 联调检查
|
||||
- [ ] 列表接口返回 `hitTags`
|
||||
- [ ] 详情接口返回 `hitTags`
|
||||
- [ ] 导出新增两列
|
||||
- [ ] 未混入 `OBJECT` 标签结果
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run targeted backend verification**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
mvn -pl ccdi-project test -Dtest=CcdiBankTagResultMapperXmlTest,CcdiBankStatementServiceImplTest,CcdiBankStatementControllerTest
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `PASS`
|
||||
|
||||
- [ ] **Step 3: Verify response shape manually**
|
||||
|
||||
联调时至少检查：
|
||||
|
||||
1. `GET /ccdi/project/bank-statement/list` 返回的每条流水出现 `hitTags`
|
||||
2. `GET /ccdi/project/bank-statement/detail/{bankStatementId}` 返回 `hitTags[*].ruleName/riskLevel/reasonDetail`
|
||||
3. 导出文件末尾新增两列且顺序固定
|
||||
4. 通过构造仅有对象级结果的样本，确认不会出现在列表和详情里
|
||||
|
||||
- [ ] **Step 4: Update the implementation record with results**
|
||||
|
||||
把实际命令、结果、异常点补回实施记录，至少包含：
|
||||
|
||||
- 运行日期
|
||||
- 测试命令
|
||||
- 是否通过
|
||||
- 若失败，失败原因和修正方式
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/reports/implementation/2026-03-19-bank-statement-hit-tags-backend-implementation.md
|
||||
git commit -m "补充流水异常标签后端验证记录"
|
||||
```
|
||||
Reference in New Issue
Block a user