ccdi/docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md

# Project Bank Statement Tagging Frontend Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 在本期“仅做后端能力、不改页面展示”的范围下，明确前端暂不接入流水标签展示，同时补齐后续接入所需的接口契约文档与回归检查，确保后端发布不会误伤现有项目详情页。

**Architecture:** 本期前端不新增 UI、不改造 `UploadData.vue`、`DetailQuery.vue`、`PreliminaryCheck.vue`、`SpecialCheck.vue`。前端实施计划聚焦于两件事：一是确认现有页面对新增后端能力保持兼容，二是在 API 层和页面待办文档中记录未来接入点，避免后续二次梳理。

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

---

### Task 1: 明确本期前端范围为零代码接入

**Files:**
- Modify: `docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md`

**Step 1: Write the acceptance checklist**

先把本期前端边界写清楚：

- 不新增标签展示页面
- 不新增标签查询按钮
- 不修改上传数据页现有轮询行为
- 不修改流水明细查询页现有筛选交互
- 不修改结果总览和专项排查占位页面

**Step 2: Run a repository grep to verify no mandatory frontend dependency exists**

Run:

```bash
Get-ChildItem -Recurse -File ruoyi-ui/src | Select-String -Pattern "project/tags|bank-tag|标签重算" | Measure-Object
```

Expected:

- 当前为 `0`，说明前端尚未被后端新能力反向强依赖

**Step 3: Keep implementation minimal**

不修改任何前端业务文件，仅在计划文档中记录本期范围。

**Step 4: Commit**

```bash
git add docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md
git commit -m "docs: 明确流水标签前端一期范围"
```

### Task 2: 记录未来 API 契约占位

**Files:**
- Modify: `docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md`

**Step 1: Define the future API contract**

在计划中补充后续前端接入时将消费的后端接口：

- `POST /ccdi/project/tags/rebuild`
- 后续可能新增：
  - `GET /ccdi/project/tags/summary`
  - `GET /ccdi/project/tags/list`
  - `GET /ccdi/project/tags/task/latest`

并记录请求与响应最小示例。

**Step 2: Run a smoke review**

Run:

```bash
Get-Content docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md | Select-String "/ccdi/project/tags/rebuild"
```

Expected:

- 能检索到接口说明

**Step 3: Keep implementation minimal**

仅补充文档，不提前创建未使用的前端 API 文件，避免本期产生无效代码。

**Step 4: Commit**

```bash
git add docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md
git commit -m "docs: 补充流水标签前端后续接口契约"
```

### Task 3: 约束后续页面接入位置

**Files:**
- Modify: `docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md`

**Step 1: Write the page integration checklist**

在计划中明确二期前端接入位置：

- `ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue`
  - 适合展示项目级标签汇总、模型触发概览
- `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue`
  - 适合展示对象级异常标签列表
- `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
  - 适合展示流水级标签明细与异常原因
- `ruoyi-ui/src/api/`
  - 预留 `ccdiProjectTag.js`

**Step 2: Run a path existence smoke check**

Run:

```bash
@(Test-Path 'ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue'), @(Test-Path 'ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue'), @(Test-Path 'ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue')
```

Expected:

- 三个结果均为 `True`

**Step 3: Keep implementation minimal**

仅记录接入点和职责边界，不提前改页面。

**Step 4: Commit**

```bash
git add docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md
git commit -m "docs: 约束流水标签前端二期接入位置"
```

### Task 4: 完成本期前端回归检查

**Files:**
- Modify: `docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md`

**Step 1: Run frontend build smoke check**

Run:

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

Expected:

- 构建成功
- 说明后端新能力引入后没有要求前端同步改动

**Step 2: Run upload/detail page manual checklist**

手工验证：

- 上传数据页可正常进入
- 批量上传弹窗行为不变
- 拉取本行信息弹窗行为不变
- 流水明细查询页可正常打开
- 结果总览和专项排查仍保持占位状态

**Step 3: Update verification notes**

在计划末尾补充本期前端“不变更但已验证兼容”的结论和后续待接入项。

**Step 4: Commit**

```bash
git add docs/plans/2026-03-16-project-bank-statement-tagging-frontend-implementation.md
git commit -m "docs: 完成流水标签前端一期兼容性核对"
```

## Future API Contract

本期不接入，但二期前端可直接按以下契约接入：

- `POST /ccdi/project/tags/rebuild`
  - 请求体：

```json
{
  "projectId": 40,
  "modelCode": "LARGE_TRANSACTION"
}
```

  - 成功响应：

```json
{
  "code": 200,
  "msg": "标签重算任务已提交"
}
```

- 后续推荐新增：
  - `GET /ccdi/project/tags/task/latest?projectId=40`
  - `GET /ccdi/project/tags/summary?projectId=40`
  - `GET /ccdi/project/tags/list?projectId=40&resultType=STATEMENT`

## Verification Notes

本期前端计划的核心结论是：

- 按当前需求不做页面实现是合理的
- 需要保证后端独立发布不影响现有项目详情页
- 后续若要展示标签结果，建议优先接入 `PreliminaryCheck.vue`、`SpecialCheck.vue`、`DetailQuery.vue`