From c9c1676602eeabf410033fe5f473afb661d227f2 Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Wed, 18 Mar 2026 14:35:16 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE=E6=89=93?=
 =?UTF-8?q?=E6=A0=87=E7=8A=B6=E6=80=81=E8=81=94=E5=8A=A8=E8=AE=BE=E8=AE=A1?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...ject-bank-tag-status-lock-design-record.md |  22 ++
 ...-18-project-bank-tag-status-lock-design.md | 302 ++++++++++++++++++
 2 files changed, 324 insertions(+)
 create mode 100644 docs/reports/implementation/2026-03-18-project-bank-tag-status-lock-design-record.md
 create mode 100644 docs/superpowers/specs/2026-03-18-project-bank-tag-status-lock-design.md

diff --git a/docs/reports/implementation/2026-03-18-project-bank-tag-status-lock-design-record.md b/docs/reports/implementation/2026-03-18-project-bank-tag-status-lock-design-record.md
new file mode 100644
index 00000000..26d348f6
--- /dev/null
+++ b/docs/reports/implementation/2026-03-18-project-bank-tag-status-lock-design-record.md
@@ -0,0 +1,22 @@
+# 项目银行流水打标状态联动设计记录
+
+## 变更概述
+
+- 新增“项目银行流水打标状态联动”设计文档。
+- 明确项目状态扩展为 `0-进行中`、`1-已完成`、`2-已归档`、`3-打标中`。
+- 明确所有银行流水打标入口都要统一驱动项目状态切换。
+- 明确打标中期间，上传数据页与参数模型页都需要受限，同时后端接口必须做兜底拦截。
+
+## 新增文件
+
+- `docs/superpowers/specs/2026-03-18-project-bank-tag-status-lock-design.md`
+
+## 设计结论
+
+- 打标开始前后由后端统一切换项目状态，成功置为 `已完成`，失败回退为 `进行中`。
+- `打标中` 作为项目正式状态参与列表展示、详情展示与状态统计。
+- 前端禁用只作为体验控制，文件上传、拉取本行信息、参数保存仍要由后端按项目状态拒绝。
+
+## 后续动作
+
+- 待用户审阅 spec 后，进入前后端实施计划阶段。
diff --git a/docs/superpowers/specs/2026-03-18-project-bank-tag-status-lock-design.md b/docs/superpowers/specs/2026-03-18-project-bank-tag-status-lock-design.md
new file mode 100644
index 00000000..e65d030d
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-18-project-bank-tag-status-lock-design.md
@@ -0,0 +1,302 @@
+# 项目银行流水打标状态联动设计
+
+## 背景
+
+当前项目状态仅包含：
+
+- `0-进行中`
+- `1-已完成`
+- `2-已归档`
+
+银行流水打标已经具备手工触发和自动触发两条链路：
+
+- 手工触发：用户在项目中发起标签重算
+- 自动触发：上传流水文件或拉取本行信息成功后触发自动重算
+
+但现状里“项目状态”和“银行流水打标任务状态”是分离的：
+
+- 打标开始时，项目状态不会切到明确的“执行中”
+- 打标期间，上传数据页仍可继续拉取本行信息、上传流水
+- 打标期间，参数模型页仍可修改阈值
+- 项目列表、详情页、状态统计也无法反映项目是否处于打标执行中
+
+这会带来两个问题：
+
+1. 用户无法判断项目当前是否正在执行银行流水打标
+2. 打标运行过程中仍允许修改输入数据和参数，容易导致执行口径与结果不一致
+
+## 目标
+
+- 为项目增加“打标中”这一正式业务状态。
+- 所有银行流水打标入口统一驱动项目状态切换。
+- 打标成功后将项目状态变更为“已完成”。
+- 打标失败后将项目状态回退为“进行中”。
+- 当项目处于“打标中”时：
+  - 上传数据页禁止拉取本行信息、上传流水等会改变输入数据的操作
+  - 参数模型页禁止修改参数
+- 项目列表、项目详情、项目状态统计统一展示“打标中”。
+- 前端禁用与后端校验保持一致，避免仅靠页面控制被绕过。
+
+## 范围
+
+### In Scope
+
+- `ccdi_project.status` 业务状态扩展
+- 银行流水打标任务开始/结束时的项目状态切换
+- 手工触发与自动触发两类打标链路
+- 项目列表、详情页、状态统计的“打标中”展示
+- 上传数据页与参数模型页的前端禁用
+- 文件上传、拉取本行信息、参数保存的后端状态拦截
+- 对应 SQL、测试与实施记录
+
+### Out of Scope
+
+- 打标执行线程模型调整
+- 新增消息推送、WebSocket、实时进度条
+- 已归档项目的业务流程重构
+- 打标结果口径、规则 SQL、本次标签计算逻辑本身的调整
+
+## 设计原则
+
+- 项目状态是页面展示、统计、交互控制的唯一业务事实来源。
+- “打标中”不是临时页面标记，而是项目正式状态。
+- 所有打标触发入口必须复用同一套状态切换逻辑，不能分散在多个控制器中各自处理。
+- 前端负责体验层禁用，后端负责最终业务兜底。
+- 失败回退遵循用户确认规则：打标失败回退为 `0-进行中`。
+
+## 方案选择
+
+本次采用“把打标中做成项目正式状态”的方案，不采用“从任务表动态推导打标中”。
+
+原因：
+
+- 当前项目列表、详情、统计、按钮显隐都已直接依赖 `ccdi_project.status`
+- 将“打标中”纳入正式状态，能最小化前后端口径分叉
+- 相比运行时拼装任务态，字典、统计、筛选、禁用逻辑更容易统一维护
+
+## 状态模型设计
+
+项目状态扩展为：
+
+- `0-进行中`
+- `1-已完成`
+- `2-已归档`
+- `3-打标中`
+
+### 状态流转
+
+#### 1. 项目创建
+
+- 新建项目默认状态仍为 `0-进行中`
+
+#### 2. 打标开始
+
+当任一银行流水打标任务开始执行时，项目状态切换为 `3-打标中`。
+
+覆盖入口包括：
+
+- 手工重算
+- 批量上传流水完成后触发的自动打标
+- 拉取本行信息完成后触发的自动打标
+
+#### 3. 打标成功
+
+- 当前轮及补跑轮次全部执行完成后，项目状态切换为 `1-已完成`
+
+#### 4. 打标失败
+
+- 当前轮打标执行失败时，项目状态切换回 `0-进行中`
+
+#### 5. 补跑场景
+
+`ProjectBankTagRebuildCoordinator` 当前已经支持 `needRerun` 机制。
+
+设计要求：
+
+- 当项目已经处于打标流程中且出现补跑标记时，项目状态持续保持 `3-打标中`
+- 仅当最后一轮实际执行结束后，才根据最终结果落为 `1-已完成` 或 `0-进行中`
+
+## 后端设计
+
+## 1. 项目状态统一更新能力
+
+建议在项目模块中补充一个明确的项目状态更新能力，供打标服务、文件上传服务、参数服务复用。
+
+职责：
+
+- 根据 `projectId` 获取项目并校验存在性
+- 更新 `status`、`updateBy`、`updateTime`
+- 对已归档项目做保护，避免被意外改写状态
+
+不建议把状态切换逻辑散落在多个业务类里直接 `projectMapper.updateById(...)`。
+
+## 2. 打标状态切换落点
+
+状态切换收口在 `CcdiBankTagServiceImpl.rebuildProject(...)`。
+
+建议流程：
+
+1. 创建打标任务前或任务创建后、规则执行前，将项目状态更新为 `3-打标中`
+2. 规则执行全部完成后，将项目状态更新为 `1-已完成`
+3. 捕获异常时，将项目状态更新为 `0-进行中`
+4. 若存在补跑循环，则状态保持 `3`，由最后一轮执行负责写最终态
+
+这样可以保证手工和自动触发都复用同一套状态流转。
+
+## 3. 前置拦截能力
+
+后端需要对“打标中不可改输入”的规则做服务端校验，避免前端禁用被绕过。
+
+### 文件上传相关
+
+在 `CcdiFileUploadServiceImpl` 中，对以下入口增加项目状态校验：
+
+- 批量上传流水
+- 拉取本行信息
+
+当项目状态为 `3-打标中` 时，直接抛出业务异常，例如：
+
+- `当前项目正在进行银行流水打标，暂不允许上传或拉取数据`
+
+### 参数保存相关
+
+在 `CcdiModelParamServiceImpl` 中，对以下入口增加项目状态校验：
+
+- `saveParams`
+- `saveAllParams`
+
+当项目状态为 `3-打标中` 时，直接抛出业务异常，例如：
+
+- `当前项目正在进行银行流水打标，暂不允许修改参数`
+
+## 4. 已归档项目保护
+
+若已归档项目被误触发打标，不应继续推进状态切换。
+
+建议策略：
+
+- 已归档项目不允许进入新的打标流程
+- 若入口层未提前拦住，状态更新能力也应拒绝把 `2-已归档` 改写为 `3`
+
+这样能避免“已归档”与“打标中”之间出现非法流转。
+
+## 前端设计
+
+## 1. 项目详情页状态展示
+
+`ruoyi-ui/src/views/ccdiProject/detail.vue` 需要新增 `3-打标中` 的状态展示：
+
+- 状态文字：`打标中`
+- 状态样式：与现有“进行中/已完成/已归档”区分
+
+详情页向子组件透传的 `projectInfo.projectStatus` 保持为统一禁用依据。
+
+## 2. 上传数据页禁用
+
+`UploadData.vue` 在项目状态为 `3` 时进入受限态。
+
+### 禁用范围
+
+- `拉取本行信息`
+- `上传流水`
+- 所有会触发上传、拉取、重新提交输入数据的入口按钮
+
+### 交互要求
+
+- 按钮使用 `disabled`
+- 禁用状态有明确提示文案，而不是仅变灰
+- 已存在的文件列表、统计、查看类操作仍允许使用
+
+目标是“禁止改变输入”，而不是“整个页面不可看”。
+
+## 3. 参数模型页只读
+
+`ParamConfig.vue` 在项目状态为 `3` 时进入只读态。
+
+### 控制项
+
+- 参数输入框禁用
+- “保存所有修改”按钮禁用
+- 页面顶部或按钮区展示提示文案：
+  - `项目正在进行银行流水打标，参数暂不可修改`
+
+## 4. 项目列表与状态统计
+
+### 项目列表
+
+项目列表页需要新增 `3-打标中` 的显示与操作策略：
+
+- 状态列可正常显示“打标中”
+- “打标中”项目允许进入详情页查看
+- 不显示仅适用于完成态的“查看结果/归档”
+- 不把“打标中”误判为“进行中”或“已完成”
+
+### 状态统计
+
+项目首页状态统计扩展为：
+
+- 全部
+- 进行中
+- 已完成
+- 已归档
+- 打标中
+
+对应后端统计 VO 与前端 tabCounts 都要同步扩展。
+
+## SQL 与字典设计
+
+需要新增一条增量 SQL，补齐状态字典与注释口径：
+
+- `ccdi_project.status` 注释补充 `3-打标中`
+- `sys_dict_data` 为 `ccdi_project_status` 新增：
+  - `dict_label = 打标中`
+  - `dict_value = 3`
+
+不直接依赖历史初始化脚本作为唯一变更承载，避免新环境与增量环境口径不一致。
+
+## 错误处理
+
+- 打标失败时，项目状态必须回退为 `0-进行中`
+- 若状态更新失败，不应静默吞掉，需要保留日志，便于排查“任务完成但状态未切回”的问题
+- 服务端拦截返回的错误文案要能让用户理解是“项目正在打标，所以暂时不可操作”
+- 前端收到业务错误后直接展示后端文案，不再自行拼装另一套口径
+
+## 测试设计
+
+至少覆盖以下测试：
+
+### 1. 打标状态流转测试
+
+- 手工打标开始时置为 `3`
+- 手工打标成功后置为 `1`
+- 手工打标失败后回退为 `0`
+- 自动打标开始时也会置为 `3`
+- 存在补跑时，期间持续保持 `3`
+
+### 2. 服务端拦截测试
+
+- 项目状态为 `3` 时，批量上传流水被拒绝
+- 项目状态为 `3` 时，拉取本行信息被拒绝
+- 项目状态为 `3` 时，参数保存被拒绝
+
+### 3. 前端页面测试/联调验证
+
+- 项目详情页正确显示“打标中”
+- 上传数据页相关按钮禁用
+- 参数模型页输入框和保存按钮禁用
+- 项目列表与状态统计正确显示“打标中”
+
+## 风险与兼容性
+
+- 新增状态 `3` 后，所有基于项目状态写死 `0/1/2` 的前后端逻辑都要排查，避免出现未知状态回退到默认分支
+- 字典数据、状态统计 VO、前端颜色映射、按钮显隐条件需同步改造，否则会出现展示不一致
+- 若存在历史完成项目再次触发自动打标，按本设计会先进入 `3-打标中`，完成后重新回到 `1-已完成`，这是符合本次需求的
+
+## 实施拆分建议
+
+后续实施计划建议拆成两份：
+
+- 后端实施计划：状态枚举/SQL/服务端状态切换/拦截/测试
+- 前端实施计划：详情页禁用/列表与统计展示/交互提示/联调验证
+
+这样能符合仓库“前后端分别产出实施计划”的协作约定。