# 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 "补充流水异常标签后端验证记录"
```
