设计涉疑交易筛选一致性优化

docs/plans/fullstack/2026-07-16-suspicious-transaction-filter-consistency-design.md

@@ -0,0 +1,50 @@
+# 涉疑交易明细筛选一致性设计
+
+## 背景
+
+生产环境“涉疑交易明细”在员工模型与外部人员模型之间切换时，存在旧结果重新出现、列表标签与筛选模型不一致、刷新后仍可能恢复旧数据等问题。
+
+## 根因
+
+1. `RiskDetailSection` 对父组件 `sectionData` 使用深度监听。父页面静默刷新任意风险数据时，子组件会重置筛选条件并重新灌入首屏数据。
+2. 涉疑交易查询和当前页流水详情补全并行执行，但没有请求序号控制，较早发出的请求可以在较晚完成后覆盖最新筛选结果。
+3. 列表接口按 `modelCode` 筛选流水，前端随后逐条调用无模型参数的流水详情接口补标签，导致标签口径脱离列表筛选条件。
+4. 后端 `MODEL_RULE` 查询仍启用外部人员分支，模型命中 SQL 也没有排除 `EXTERNAL_*` 模型，“员工规则命中”与“外部人员预警”边界不完整。
+5. 涉疑交易导出的标签聚合没有按当前模型过滤，页面与导出可能不一致。
+
+## 筛选口径
+
+- 选择具体模型时，以 `modelCode` 精确筛选流水和标签。
+- `ALL + 员工模型` 仅返回该员工模型。
+- `ALL + 外部人员模型` 仅返回该外部人员模型。
+- `MODEL_RULE + 全部模型` 仅返回非 `EXTERNAL_*` 员工模型。
+- `EXTERNAL_PERSON + 全部模型` 仅返回 `EXTERNAL_*` 外部人员模型。
+- `ALL + 全部模型` 返回全部模型。
+- 列表、详情和风险明细导出的涉疑交易工作表使用同一口径。
+
+## 数据流
+
+1. 筛选条件变化时，前端清空旧列表、关闭详情并使正在执行的旧请求失效，不自动查询。
+2. 用户点击“查询”时，前端固定本次 `projectId`、`suspiciousType`、`modelCode`、页码和每页数量，并生成请求序号。
+3. 后端先完成涉疑流水分页查询，并直接返回列表展示所需的流水字段。
+4. 后端仅对当前页流水 ID 批量查询符合当前筛选口径的标签并装配到行数据。
+5. 前端仅允许最新请求序号更新列表、总数和加载状态。
+6. 用户打开详情时，详情请求携带当前筛选条件；详情标签与当前列表行标签保持一致。
+
+## 性能约束
+
+- 浏览器加载列表由“1 次列表请求 + 当前页 N 次详情请求”降为 1 次列表请求。
+- 后端列表处理固定为分页主查询和当前页标签批量查询，不按行查询数据库。
+- `ALL + 员工具体模型` 不检查、也不拼接外部人员分支。
+- 下拉框变化不自动请求，避免生产环境重复查询。
+- 当前页标签查询先按项目和流水 ID 范围收敛，再应用模型范围过滤。
+
+## 验收标准
+
+1. 员工疑似赌博筛选只展示员工疑似赌博流水和标签。
+2. 员工大额交易与外部人员大额交易严格区分。
+3. 人为延迟旧请求后，旧响应不能覆盖最新筛选结果。
+4. 父页面静默刷新后，当前筛选条件和列表不被首屏数据覆盖。
+5. 列表、详情和风险明细导出的涉疑交易标签一致。
+6. 每次列表查询不再产生当前页逐条详情请求。
+