# Bank Statement Hit Tags Frontend 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:** 继续沿用 `DetailQuery.vue` 作为唯一页面组件，不新增页面和接口；前端直接消费后端返回的 `hitTags` 结构，列表只渲染标签名称，详情弹窗渲染标签名称、风险等级和命中原因摘要。由于仓库当前前端单测基建是静态 Node 脚本，本计划以“先补 source 断言 + 再跑 build 验证”为主，不额外引入测试框架。

**Tech Stack:** Vue 2, Element UI, Axios request wrapper, Node.js, npm

---

### Task 1: 在列表表格中新增异常标签列

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
- Create: `ruoyi-ui/tests/unit/detail-query-hit-tags-list.test.js`

- [ ] **Step 1: Write the failing test**

先新增静态断言脚本，锁定列表必须新增“异常标签”列并读取 `scope.row.hitTags`：

```js
const assert = require("assert");
const fs = require("fs");
const path = require("path");

const componentPath = path.resolve(
  __dirname,
  "../../src/views/ccdiProject/components/detail/DetailQuery.vue"
);
const source = fs.readFileSync(componentPath, "utf8");

assert(source.includes('label="异常标签"'), "列表应新增异常标签列");
assert(source.includes("scope.row.hitTags"), "异常标签列应读取当前行的 hitTags");
assert(source.includes('v-for="(tag, index) in scope.row.hitTags"'), "异常标签列应逐个渲染命中标签");
assert(source.includes("tag.ruleName"), "异常标签列应展示标签名称");
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd ruoyi-ui
node tests/unit/detail-query-hit-tags-list.test.js
```

Expected:

- `FAIL`
- 原因是当前列表还没有异常标签列和对应格式化方法

- [ ] **Step 3: Write minimal implementation**

在 `DetailQuery.vue` 中做最小范围改动：

1. 在“摘要 / 交易类型”和“交易金额”之间新增：

```html
<el-table-column label="异常标签" min-width="220">
  <template slot-scope="scope">
    <div v-if="scope.row.hitTags && scope.row.hitTags.length" class="hit-tag-list">
      <el-tag
        v-for="(tag, index) in scope.row.hitTags"
        :key="`${scope.row.bankStatementId}-tag-${index}`"
        size="mini"
        :type="mapRiskLevelToTagType(tag.riskLevel)"
        effect="plain"
      >
        {{ tag.ruleName }}
      </el-tag>
    </div>
    <span v-else class="empty-text">-</span>
  </template>
</el-table-column>
```

2. 给 `createEmptyDetailData()` 补 `hitTags: []`，并在列表取数后统一兜底：

```js
this.list = (res.rows || []).map((item) => ({
  hitTags: [],
  ...item,
}));
```

3. 新增方法：

```js
mapRiskLevelToTagType(riskLevel) {
  const level = String(riskLevel || "").toUpperCase();
  if (level === "HIGH") return "danger";
  if (level === "MEDIUM") return "warning";
  return "info";
}
```

4. 增加轻量样式：

```scss
.hit-tag-list {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
}

.empty-text {
  color: #909399;
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run:

```bash
cd ruoyi-ui
node tests/unit/detail-query-hit-tags-list.test.js
node tests/unit/detail-query-filter-layout.test.js
node tests/unit/detail-query-detail-dialog.test.js
```

Expected:

- 3 个脚本都 `PASS`
- 说明列表新增列没有破坏现有静态结构

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue ruoyi-ui/tests/unit/detail-query-hit-tags-list.test.js ruoyi-ui/tests/unit/detail-query-filter-layout.test.js ruoyi-ui/tests/unit/detail-query-detail-dialog.test.js
git commit -m "补充流水明细异常标签列表展示"
```

### Task 2: 在详情弹窗中新增命中异常标签模块

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
- Modify: `ruoyi-ui/tests/unit/detail-query-detail-dialog.test.js`

- [ ] **Step 1: Write the failing test**

在 `detail-query-detail-dialog.test.js` 中追加断言，锁定详情弹窗必须出现“命中异常标签”模块：

```js
[
  "命中异常标签",
  "detail-hit-tag-section",
  "detailData.hitTags",
  "当前流水未命中异常标签",
  "mapRiskLevelToTagType(tag.riskLevel)",
].forEach((token) => {
  assert(source.includes(token), `详情弹窗缺少异常标签结构: ${token}`);
});
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd ruoyi-ui
node tests/unit/detail-query-detail-dialog.test.js
```

Expected:

- `FAIL`
- 原因是详情弹窗尚未渲染命中异常标签模块

- [ ] **Step 3: Write minimal implementation**

在详情弹窗文件区下方新增独立模块：

```html
<div class="detail-hit-tag-section">
  <div class="detail-section-title">命中异常标签</div>
  <div v-if="detailData.hitTags && detailData.hitTags.length" class="detail-hit-tag-items">
    <div
      v-for="(tag, index) in detailData.hitTags"
      :key="`detail-tag-${index}`"
      class="detail-hit-tag-item"
    >
      <div class="detail-hit-tag-header">
        <span class="detail-hit-tag-name">{{ formatField(tag.ruleName) }}</span>
        <el-tag size="mini" :type="mapRiskLevelToTagType(tag.riskLevel)" effect="plain">
          {{ formatRiskLevel(tag.riskLevel) }}
        </el-tag>
      </div>
      <div class="detail-hit-tag-reason">{{ formatField(tag.reasonDetail) }}</div>
    </div>
  </div>
  <div v-else class="detail-hit-tag-empty">当前流水未命中异常标签</div>
</div>
```

并新增方法：

```js
formatRiskLevel(value) {
  const level = String(value || "").toUpperCase();
  if (level === "HIGH") return "高风险";
  if (level === "MEDIUM") return "中风险";
  if (level === "LOW") return "低风险";
  return "未标注";
}
```

同时补充对应样式类，保证详情里纵向展示原因摘要，不把多条命中压成一行。

- [ ] **Step 4: Run tests to verify they pass**

Run:

```bash
cd ruoyi-ui
node tests/unit/detail-query-detail-dialog.test.js
node tests/unit/detail-query-hit-tags-list.test.js
```

Expected:

- `PASS`
- 说明详情模块和列表模块结构都已具备

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue ruoyi-ui/tests/unit/detail-query-detail-dialog.test.js ruoyi-ui/tests/unit/detail-query-hit-tags-list.test.js
git commit -m "补充流水详情异常标签展示"
```

### Task 3: 补齐前端回归验证记录并完成构建验证

**Files:**
- Create: `docs/tests/records/2026-03-19-bank-statement-hit-tags-frontend-verification.md`
- Create: `docs/reports/implementation/2026-03-19-bank-statement-hit-tags-frontend-implementation.md`
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`

- [ ] **Step 1: Write the verification record skeleton**

先建立前端验证记录，锁定联调检查项：

```markdown
# 流水明细异常标签前端验证记录

## 验证范围
- 列表异常标签列
- 详情异常标签模块
- 空态展示
- 导出入口回归

## 验证结果
- [ ] 列表显示命中标签名称
- [ ] 详情显示名称、风险等级、命中原因摘要
- [ ] 无标签时显示空态
- [ ] 导出入口仍可触发下载
```

同时创建前端实施记录骨架：

```markdown
# 流水明细异常标签前端实施记录

## 修改内容
- 列表异常标签列
- 详情异常标签模块
- 静态测试与构建验证
```

- [ ] **Step 2: Run baseline build check before final polish**

Run:

```bash
cd ruoyi-ui
npm run build:prod
```

Expected:

- 当前改动后的前端代码可以正常构建

- [ ] **Step 3: Write minimal final polish**

补齐最后的回归点：

1. 确认 `handleViewDetail()` 在详情返回无 `hitTags` 时仍回填空数组
2. 确认列表、详情空态文案和样式一致
3. 若需要，给异常标签模块补最小响应式样式，确保移动端不溢出
4. 在实施记录中写明本次不改 `ruoyi-ui/src/api/ccdiProjectBankStatement.js` 的原因：
   - 复用现有接口
   - 仅扩展响应数据结构

- [ ] **Step 4: Run full frontend verification**

Run:

```bash
cd ruoyi-ui
node tests/unit/detail-query-filter-layout.test.js
node tests/unit/detail-query-detail-dialog.test.js
node tests/unit/detail-query-hit-tags-list.test.js
npm run build:prod
```

Expected:

- 静态脚本全部 `PASS`
- 构建 `PASS`

联调时额外检查：

1. 列表页一条命中多标签的流水是否正确折行
2. 无标签流水是否显示 `-`
3. 详情页命中原因摘要是否完整可见
4. 点击“导出流水”按钮仍能正常触发下载

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue docs/tests/records/2026-03-19-bank-statement-hit-tags-frontend-verification.md docs/reports/implementation/2026-03-19-bank-statement-hit-tags-frontend-implementation.md
git commit -m "补充流水异常标签前端验证记录"
```
