tanzk/csctalon
0
0
Fork 0
Code Issues 19 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

[governance] 投诉去重口径: 多渠道归并(非重复) vs 真重复(同渠道) + 年度分层 #55

New Issue
Closed
opened 2026-09-11 11:42:03 +08:00 by tanzk · 3 comments
tanzk commented 2026-09-11 11:42:03 +08:00
Owner
Copy Link

背景

2026-09-11 用户明确最终口径（此前我混淆了两个概念）：

「26年 投诉编号 其实很完善，同一个人 设备编号 电话号码 都一致，几天内 的投诉，
渠道（平台）是肯定不同， 内容略微不同；
可以归结为一个投诉，但是不能算重复数据；
如果电话 sn 渠道 都一致的话 那就基本上是同一个投诉 拷贝复制的，
譬如说9.7号的投诉 但是当天处理没有完结，拖到10号再处理一次。」

「对于2025年之前的数据 简单统计处理就OK，有一定的偏差或者多重统计可以接受」
「近期的数据会更精准的。25年的数据 统计有偏差关系也不大」

★核心：两个概念必须分开（我此前混淆）

概念 特征 处理
同一投诉·多渠道 同 SN + 同电话 + 几天内 + 渠道不同 + 内容略不同 归并为 1 笔投诉，聚合渠道，不算重复数据
真·重复 同 SN + 同电话 + 渠道也相同 拷贝复制 → 算重复，计 1 笔

我此前的错误：

  1. ❌ 说「同天同SN = 重复」→ 会误判多渠道为重复
  2. ❌ 用「编号不同」否决重复 → 但多渠道的编号本来就应该不同

实证验证（2026-09-11）

V1 年度分布 + 完善度

表 ≤2024 2025 2026 无日期
external_complaints 147 (5.5%) 1,348 (50.8%) 1,155 (43.5%) 4
card_complaints 43 (4.9%) 485 (55.6%) 268 (30.7%) 77 (8.8%)

2026 年完善度（明显更高）：

315  2026: SN 93.4%  电话 92.4%  渠道 98.6%
卡商 2026: SN 87.3%  电话 98.9%  渠道 99.6%

V2/V3 两类重复的规模（核心数据）

表 实体数 多渠道事件（归并,非重复） 真重复（同渠道）
315 1,519 33 个 46 行
卡商 475 15 个 31 行

多渠道事件样例（应归并 1 笔）：

SN=58482343088704  电话=18621328556
  日期=[08-19, 08-20]  渠道=[航城监所, 全国消协智慧315平台, 全国12315平台]
  → 同一个人 3 天内走 3 个渠道 = 1 笔投诉

真重复样例（同渠道拷贝复制）：

SN=58812443086851  电话=13889531247  渠道=全国12315平台
  日期=[2025-08-02]  ids=[10935, 1003]   ← 同天同渠道两条 = 真重复

SN=58482339019725  电话=13050917965  渠道=公共服务平台
  日期=[08-27, 08-30, 09-02, 09-03]  ids=[1093,11025,1111,1123,11056,1124]

V4 编号的年度反转（印证用户「26年编号很完善」）

2025 年: 1,348 行, 有编号 1,279 (94.9%), 唯一 734    ← 填充高但唯一率低(批次码多)
2026 年: 1,155 行, 有编号   557 (48.2%), 唯一 545    ← 填充低但唯一率高

→ 2026 年 545/557 = 97.8% 是唯一受理号（质量高）；2025 年多为批次码。

处理动作 / 设计要求

  • 判据实现（complaint_scope.py）:
    • group_complaint_events(rows, window_days=7)：按 (SN, 电话) 分组 + 时间窗聚类
    • 簇内渠道数 > 1 → kind='multi_channel'（同一投诉，聚合渠道，不计重复）
    • 簇内渠道数 == 1 且条数 > 1 → kind='true_dup'（真重复，计 1 笔，标 dup_of）
    • 簇内条数 == 1 → kind='single'
  • 年度分层（用户：「25年前简单统计，允许偏差」）:
    • ≤2025 年：统计上不自动归并（保持现状），但明细里仍标记 multi_channel/true_dup 供人工查
    • 2026 年：完整应用上���判据
  • 统计侧归并（不删数据，符合「不能乱删」）:
    • /complaints/summary、/complaints/analysis 的补充表计数改走事件口径
    • 返回新增 multi_channel_events / true_dup_rows 供前端展示
  • 人工审核入口: 电话不同/缺失的组标记 needs_review，前端提供 Tab
  • 不物理删除任何数据；dedup_hash 唯一索引保持不变

验收标准 / 关闭条件

  1. 判据正确:
    • 多渠道（同SN+电话+7天内+渠道不同）→ 归并 1 笔，不计入重复
    • 真重复（同SN+电话+渠道相同）→ 计 1 笔，标 dup_of
  2. 规模符合实测: 315 多渠道 33 个 / 真重复 46 行；卡商 15 个 / 31 行
  3. 年度分层生效: ≤2025 年统计不归并；2026 年归并
  4. 数据零删除: 执行前后 count(*) 不变（external_complaints 2,655 / card_complaints 873）
  5. 渠道不丢: 多渠道事件返回全部渠道（验证 SN=58482343088704 返回 3 个渠道）
  6. 测试: 新增单测覆盖 ①多渠道且应归并 ②同渠道真重复 ③超时间窗不归并 ④电话不同不归并；
    pytest / ruff / vitest / eslint 全绿
  7. 前端: 投诉分析页区分展示「多渠道事件」与「真重复」两个指标

关联

  • 前置: #52（口径重构）、#53（卡商独立）、#54（去重分析，本单承接其结论）
  • 分析产物: docs/reports/20260911-投诉去重分析/（5 份 CSV）
  • 相关: #42（采集流程防线，源头治理）

备注: 源文档修订与库的同步（用户已手改腾讯文档）

用户已手工修订腾讯文档中的明显错误日期与空白日期。需注意：

⚠️ 库不会跟随源文档删除：

dedup_hash = md5(日期 | 手机 | SN | 问题签名)
同步 = pg_insert(...).on_conflict_do_update(...)   ← 无 DELETE 分支
  • 源里删除行 → 库里残留
  • 源里改内容 → 指纹变 → INSERT 新行（旧行残留）← 正是 09-05 那次 2527 行重复的成因

→ 「源文档对齐」需架构级变更（软删 + 连续N次未出现才确认），建议独立工单评估，
本单只做库内标记 + 统计侧归并（可逆、可审计）。

## 背景 2026-09-11 用户明确最终口径（此前我混淆了两个概念）： > 「26年 投诉编号 其实很完善，同一个人 设备编号 电话号码 都一致，几天内 的投诉， > 渠道（平台）是肯定不同， 内容略微不同； > **可以归结为一个投诉，但是不能算重复数据**； > 如果电话 sn 渠道 都一致的话 那就基本上是同一个投诉 **拷贝复制**的， > 譬如说9.7号的投诉 但是当天处理没有完结，拖到10号再处理一次。」 > 「对于2025年之前的数据 简单统计处理就OK，有一定的偏差或者多重统计可以接受」 > 「近期的数据会更精准的。25年的数据 统计有偏差关系也不大」 ## ★核心：两个概念必须分开（我此前混淆） | 概念 | 特征 | 处理 | |---|---|---| | **同一投诉·多渠道** | 同 SN + 同电话 + **几天内** + **渠道不同** + 内容略不同 | 归并为 **1 笔投诉**，聚合渠道，**不算重复数据** | | **真·重复** | 同 SN + 同电话 + **渠道也相同** | 拷贝复制 → **算重复**，计 1 笔 | **我此前的错误**： 1. ❌ 说「同天同SN = 重复」→ 会**误判多渠道为重复** 2. ❌ 用「编号不同」否决重复 → 但多渠道的编号**本来就应该不同** ## 实证验证（2026-09-11） ### V1 年度分布 + 完善度 | 表 | ≤2024 | 2025 | 2026 | 无日期 | |---|---|---|---|---| | `external_complaints` | 147 (5.5%) | 1,348 (50.8%) | 1,155 (43.5%) | 4 | | `card_complaints` | 43 (4.9%) | 485 (55.6%) | 268 (30.7%) | 77 (8.8%) | **2026 年完善度（明显更高）**： ``` 315 2026: SN 93.4% 电话 92.4% 渠道 98.6% 卡商 2026: SN 87.3% 电话 98.9% 渠道 99.6% ``` ### V2/V3 两类重复的规模（核心数据） | 表 | 实体数 | **多渠道事件（归并,非重复）** | **真重复（同渠道）** | |---|---|---|---| | 315 | 1,519 | **33 个** | **46 行** | | 卡商 | 475 | **15 个** | **31 行** | **多渠道事件样例（应归并 1 笔）**： ``` SN=58482343088704 电话=18621328556 日期=[08-19, 08-20] 渠道=[航城监所, 全国消协智慧315平台, 全国12315平台] → 同一个人 3 天内走 3 个渠道 = 1 笔投诉 ``` **真重复样例（同渠道拷贝复制）**： ``` SN=58812443086851 电话=13889531247 渠道=全国12315平台 日期=[2025-08-02] ids=[10935, 1003] ← 同天同渠道两条 = 真重复 SN=58482339019725 电话=13050917965 渠道=公共服务平台 日期=[08-27, 08-30, 09-02, 09-03] ids=[1093,11025,1111,1123,11056,1124] ``` ### V4 编号的年度反转（印证用户「26年编号很完善」） ``` 2025 年: 1,348 行, 有编号 1,279 (94.9%), 唯一 734 ← 填充高但唯一率低(批次码多) 2026 年: 1,155 行, 有编号 557 (48.2%), 唯一 545 ← 填充低但唯一率高 ``` → **2026 年 545/557 = 97.8% 是唯一受理号**（质量高）；2025 年多为批次码。 ## 处理动作 / 设计要求 - [x] **判据实现**（`complaint_scope.py`）: - [x] `group_complaint_events(rows, window_days=7)`：按 `(SN, 电话)` 分组 + 时间窗聚类 - [x] 簇内**渠道数 > 1** → `kind='multi_channel'`（同一投诉，聚合渠道，**不计重复**） - [x] 簇内**渠道数 == 1 且条数 > 1** → `kind='true_dup'`（真重复，计 1 笔，标 `dup_of`） - [x] 簇内条数 == 1 → `kind='single'` - [x] **年度分层**（用户：「25年前简单统计，允许偏差」）: - [x] ≤2025 年：**统计上不自动归并**（保持现状），但明细里**仍标记** `multi_channel`/`true_dup` 供人工查 - [x] 2026 年：**完整应用**上���判据 - [x] **统计侧归并**（不删数据，符合「不能乱删」）: - [x] `/complaints/summary`、`/complaints/analysis` 的补充表计数改走事件口径 - [x] 返回新增 `multi_channel_events` / `true_dup_rows` 供前端展示 - [x] **人工审核入口**: 电话不同/缺失的组标记 `needs_review`，前端提供 Tab - [x] **不物理删除任何数据**；`dedup_hash` 唯一索引保持不变 ## 验收标准 / 关闭条件 1. **判据正确**: - 多渠道（同SN+电话+7天内+渠道不同）→ 归并 1 笔，**不计入重复** - 真重复（同SN+电话+渠道相同）→ 计 1 笔，标 `dup_of` 2. **规模符合实测**: 315 多渠道 **33** 个 / 真重复 **46** 行；卡商 **15** 个 / **31** 行 3. **年度分层生效**: ≤2025 年统计不归并；2026 年归并 4. **数据零删除**: 执行前后 `count(*)` 不变（`external_complaints` 2,655 / `card_complaints` 873） 5. **渠道不丢**: 多渠道事件返回全部渠道（验证 `SN=58482343088704` 返回 3 个渠道） 6. **测试**: 新增单测覆盖 ①多渠道且应归并 ②同渠道真重复 ③超时间窗不归并 ④电话不同不归并； `pytest` / `ruff` / `vitest` / `eslint` 全绿 7. **前端**: 投诉分析页区分展示「多渠道事件」与「真重复」两个指标 ## 关联 - 前置: #52（口径重构）、#53（卡商独立）、#54（去重分析，本单承接其结论） - 分析产物: `docs/reports/20260911-投诉去重分析/`（5 份 CSV） - 相关: #42（采集流程防线，源头治理） ## 备注: 源文档修订与库的同步（用户已手改腾讯文档） 用户已手工修订腾讯文档中的**明显错误日期与空白日期**。需注意： ⚠️ **库不会跟随源文档删除**： ``` dedup_hash = md5(日期 | 手机 | SN | 问题签名) 同步 = pg_insert(...).on_conflict_do_update(...) ← 无 DELETE 分支 ``` - 源里**删除**行 → 库里**残留** - 源里**改内容** → 指纹变 → **INSERT 新行**（旧行残留）← 正是 09-05 那次 2527 行重复的成因 → 「源文档对齐」需架构级变更（软删 + 连续N次未出现才确认），**建议独立工单评估**， 本单只做**库内标记 + 统计侧归并**（可逆、可审计）。
tanzk added the governance label 2026-09-11 11:42:03 +08:00
tanzk commented 2026-09-11 11:48:03 +08:00
Author
Owner
Copy Link

提交记录

commit: 2f4e4ec — feat(complaints): 投诉事件归并 — 多渠道(非重复) vs 真重复(同渠道) + 年度分层 (#55)

6 个文件，+912 / −17：

文件 变更
services/complaint_scope.py dedup_events 重写 + split_phones + 事件常量
api/v1/complaints.py _suppl_stats 接入事件口径
tests/test_complaint_scope.py 新增 11 项（61 项）
scripts/export_dedup_analysis.py 分析导出脚本（默认输出 /tmp）
.gitignore 排除含 PII 的分析 CSV
docs/reports/20260911-投诉去重分析/README.md 脱敏摘要

提交前门禁

  • ✅ ruff check app/ tests/ scripts/
  • ✅ pytest tests/ — 全绿（test_complaint_scope 61 项）
  • ✅ vitest — 46/46
  • ✅ eslint — 无告警
  • ✅ gitleaks — no leaks found

⚠️ gitleaks 首次拦截 41 处真实手机号（来自分析 CSV + 源码 docstring）。
处置：① CSV 加入 .gitignore（含真实 PII，不入库）；② 源码 docstring 脱敏；
③ 导出脚本移入 scripts/ 且默认输出 /tmp。

验收基线（实测 2026 全年）

315 : 原始 1,155 → 归并后 1,100  (多渠道 26 / 真重复 23 / 待人工 3)
卡商: 原始   268 → 归并后   249  (多渠道  6 / 真重复  8 / 待人工 0)

★ 零删除: external_complaints=2,655  card_complaints=873  (执行前后不变)

验证方式（可复现）

# 1) 单测
cd backend && .venv/bin/python -m pytest tests/test_complaint_scope.py -q

# 2) 事件口径实测
cd backend && (set -a && . ./.env && set +a && PYTHONPATH=$PWD .venv/bin/python -c "
from app.core.database import SessionLocal
from app.api.v1.complaints import complaint_summary
f=getattr(complaint_summary,'__wrapped__',complaint_summary)
db=SessionLocal()
r=f(db,None,start='2026-01-01',end='2026-09-11')
print((r.data if hasattr(r,'data') else r)['supplementary'])
")

# 3) 导出分析明细（本地，含 PII，勿入库）
cd backend && (set -a && . ./.env && set +a && PYTHONPATH=$PWD \
  .venv/bin/python ../scripts/export_dedup_analysis.py --out /tmp/dup)

关于「源文档修订」的结论（重要，用户已手改腾讯文档）

⚠️ 库不会跟随源文档删除：

dedup_hash = md5(日期 | 手机 | SN | 问题签名)      # 身份指纹
同步 = pg_insert(...).on_conflict_do_update(...)   # ← 无 DELETE 分支
源文档操作 库的结果
删除一行 库里残留
修改内容 指纹变 → INSERT 新行，旧行残留 ← 反而制造重复

后者正是 2026-09-05 那次 2,527 行重复导入的成因（日期转置 → 指纹变 → 新增而非更新）。

→ 「源文档对齐」需架构级变更（软删 + 连续 N 次未出现才确认），建议单独立单评估。
且 #42 记载「上游推送会丢失编号 53%」，上游本身不稳定，贸然跟随删除风险高。

本单发现的数据质量问题

# 问题 规模 状态
1 一格填两个号码（/ 分隔） 315 有 10 行 ✅ 已修（split_phones）
2 电话异常长度（10/12/14/19/22 位） 315 15 行、卡商 14 行 ✅ 已修（正则扫描合法号段）
3 12315 的 25 位批次码写进受理号字段 15 个编号 / 233 行 ⬜ 待处理（上游字段错位）
4 卡商表无 complaint_no 列 全表 ⬜ 建议上游补卡商渠道受理号

未完成（建议拆单）

  1. 前端：展示「多渠道事件 / 真重复」两个指标（当前只在接口返回）
  2. 人工审核入口：needs_review 的 Tab（同设备同日多电话）
  3. 源文档对齐：架构级评估（软删 + 防上游抖动）
  4. 上游字段错位：12315 批次码 / 卡商无编号列
## 提交记录 **commit**: `2f4e4ec` — `feat(complaints): 投诉事件归并 — 多渠道(非重复) vs 真重复(同渠道) + 年度分层 (#55)` 6 个文件，+912 / −17： | 文件 | 变更 | |---|---| | `services/complaint_scope.py` | `dedup_events` 重写 + `split_phones` + 事件常量 | | `api/v1/complaints.py` | `_suppl_stats` 接入事件口径 | | `tests/test_complaint_scope.py` | 新增 11 项（61 项） | | `scripts/export_dedup_analysis.py` | 分析导出脚本（默认输出 /tmp） | | `.gitignore` | 排除含 PII 的分析 CSV | | `docs/reports/20260911-投诉去重分析/README.md` | 脱敏摘要 | ## 提交前门禁 - ✅ `ruff check app/ tests/ scripts/` - ✅ `pytest tests/` — 全绿（`test_complaint_scope` 61 项） - ✅ `vitest` — 46/46 - ✅ `eslint` — 无告警 - ✅ `gitleaks` — no leaks found > ⚠️ gitleaks 首次拦截 **41 处真实手机号**（来自分析 CSV + 源码 docstring）。 > 处置：① CSV 加入 `.gitignore`（含真实 PII，不入库）；② 源码 docstring 脱敏； > ③ 导出脚本移入 `scripts/` 且默认输出 `/tmp`。 ## 验收基线（实测 2026 全年） ``` 315 : 原始 1,155 → 归并后 1,100 (多渠道 26 / 真重复 23 / 待人工 3) 卡商: 原始 268 → 归并后 249 (多渠道 6 / 真重复 8 / 待人工 0) ★ 零删除: external_complaints=2,655 card_complaints=873 (执行前后不变) ``` ## 验证方式（可复现） ```bash # 1) 单测 cd backend && .venv/bin/python -m pytest tests/test_complaint_scope.py -q # 2) 事件口径实测 cd backend && (set -a && . ./.env && set +a && PYTHONPATH=$PWD .venv/bin/python -c " from app.core.database import SessionLocal from app.api.v1.complaints import complaint_summary f=getattr(complaint_summary,'__wrapped__',complaint_summary) db=SessionLocal() r=f(db,None,start='2026-01-01',end='2026-09-11') print((r.data if hasattr(r,'data') else r)['supplementary']) ") # 3) 导出分析明细（本地，含 PII，勿入库） cd backend && (set -a && . ./.env && set +a && PYTHONPATH=$PWD \ .venv/bin/python ../scripts/export_dedup_analysis.py --out /tmp/dup) ``` ## 关于「源文档修订」的结论（重要，用户已手改腾讯文档） ⚠️ **库不会跟随源文档删除**： ```python dedup_hash = md5(日期 | 手机 | SN | 问题签名) # 身份指纹 同步 = pg_insert(...).on_conflict_do_update(...) # ← 无 DELETE 分支 ``` | 源文档操作 | 库的结果 | |---|---| | 删除一行 | 库里**残留** | | **修改内容** | 指纹变 → **INSERT 新行**，旧行残留 ← **反而制造重复** | 后者正是 2026-09-05 那次 2,527 行重复导入的成因（日期转置 → 指纹变 → 新增而非更新）。 → 「源文档对齐」需架构级变更（软删 + 连续 N 次未出现才确认），**建议单独立单评估**。 且 #42 记载「上游推送会丢失编号 53%」，上游本身不稳定，贸然跟随删除**风险高**。 ## 本单发现的数据质量问题 | # | 问题 | 规模 | 状态 | |---|---|---|---| | 1 | 一格填两个号码（`/` 分隔） | 315 有 10 行 | ✅ 已修（`split_phones`） | | 2 | 电话异常长度（10/12/14/19/22 位） | 315 15 行、卡商 14 行 | ✅ 已修（正则扫描合法号段） | | 3 | 12315 的 25 位**批次码**写进受理号字段 | 15 个编号 / 233 行 | ⬜ 待处理（上游字段错位） | | 4 | 卡商表**无** `complaint_no` 列 | 全表 | ⬜ 建议上游补卡商渠道受理号 | ## 未完成（建议拆单） 1. **前端**：展示「多渠道事件 / 真重复」两个指标（当前只在接口返回） 2. **人工审核入口**：`needs_review` 的 Tab（同设备同日多电话） 3. **源文档对齐**：架构级评估（软删 + 防上游抖动） 4. **上游字段错位**：12315 批次码 / 卡商无编号列
tanzk commented 2026-09-11 11:53:18 +08:00
Author
Owner
Copy Link

提交记录（#55 收尾）

commit: adb2751 — feat(complaints): 事件口径前端化 + 人工审核入口 (#55)

3 个文件，+309 / −40：

文件 变更
api/v1/complaints.py 抽出 _suppl_event_metrics + 新增 /dedup-review
views/dashboards/ComplaintAnalysis.vue 卡商区块扩 4 格 + 新增「人工审核」Tab
api/complaint.js 新增 complaintDedupReview

交付内容

1. 前端可见「多渠道(非重复)」与「真重复(同渠道)」

卡商独立区块由 2 格扩为 4 格：

指标 含义
(外)卡商登记 独立统计 · 不纳入投诉总量
(外)卡商处理 前缀锚定口径
多渠道归并(非重复) 同一投诉在多平台呈现 · 已归并计 1 笔 · 不计为重复
真重复(同渠道) SN+电话+渠道全一致 · 拷贝复制 · 计 1 笔

「多渠道」格明确标注 不计为重复 —— 防止使用者再次把两者混淆（我此前就混淆过）。

2. 人工审核入口

新增「人工审核」Tab（带 el-badge 待审核数），对应你说的：

「手机不同 默认 统计为不同，但是提供一个人工再审核更合适点」

  • 列出同设备同日多个电话的组（程序无法判定是否同一人）
  • 表格列：来源 / 投诉日 / SN / 涉及电话 / 记录数 / 记录ID / 触发原因
  • 顶部固定口径说明，避免误解
  • ★ 只读：不修改、不删除任何原始行

3. 后端实现收敛为单一来源

抽出 _suppl_event_metrics(...)，/summary 与 /analysis 共用：

# channel_col 必传 —— 渠道是「是否重复」的判据, 不能省
315 → ExternalComplaint.platform
卡商 → CardComplaint.complaint_group   # 卡商表无 platform, 群名即渠道

避免两处复制粘贴导致口径漂移（这正是我在 #52/#53 踩过的坑）。

验收证据（可复现）

cd /Users/tanzk/dev/csctalon

# 1) 重建容器（源码不挂载, 必须重建, 否则跑旧镜像）
docker compose up -d --build backend

# 2) 清 Redis 缓存（@cached_json 会掩盖改动）
PW=$(grep -E '^REDIS_PASSWORD=' backend/.env | cut -d= -f2-)
docker exec csctalon-redis redis-cli -a "$PW" --no-auth-warning FLUSHDB

# 3) 实测三处口径一致性
docker exec csctalon-backend python -c "
from app.core.database import SessionLocal
from app.api.v1.complaints import complaint_analysis, complaint_summary, complaint_dedup_review
db = SessionLocal()
for fn, label in ((complaint_summary,'summary'), (complaint_analysis,'analysis')):
    r = getattr(fn,'__wrapped__',fn)(db, None, start='2026-01-01', end='2026-12-31')
    c = (r.data if hasattr(r,'data') else r)['card']
    print(label, {k:c[k] for k in ('total','events','multi_channel_events','true_dup_events','needs_review')})
r = getattr(complaint_dedup_review,'__wrapped__',complaint_dedup_review)(db, None, start='2026-01-01', end='2026-12-31', source_type=None)
print('review groups', (r.data if hasattr(r,'data') else r)['total'])
db.close()"

实测输出：

/summary  card        : total 268  events 249  多渠道 6  真重复 8  归并 19
/analysis card        : 同上 ← 两处口径完全一致 ✅
supplementary.external: total 1155 events 1100 多渠道 26 真重复 23
                        unkeyed 135  needs_review 3
/dedup-review         : groups=3 (全部 external; card=0, 卡商2026无此情况)

门禁

  • ✅ ruff check app/ 无告警
  • ✅ 后端 pytest tests/ 全绿
  • ✅ 前端 eslint 无告警；vitest 46/46；vite build 通过
  • ✅ gitleaks 预检 no leaks found

一个坑（供后人避雷）

直接调用端点函数时，Query(None) 的默认值是 Query 对象本身而非 None：

# 直调 → source_type 是 Query 对象 → 两个 if 都不进 → 返回 0 组(假象!)
complaint_dedup_review(db, None, start=..., end=...)

# 必须显式传
complaint_dedup_review(db, None, start=..., end=..., source_type=None)

HTTP 请求走 FastAPI 依赖注入无此问题。我第一次直调就得到了 groups=0 的假结论。

#55 剩余项

# 事项 状态
1 前端展示两指标 ✅ 本单完成
2 人工审核入口 ✅ 本单完成
3 源文档对齐（库不跟随源删除） ⬜ 建议单独立单（架构级）
4 12315 批次码写进受理号字段（15码/233行） ⬜ 上游字段错位
5 卡商表无 complaint_no 列 ⬜ 建议上游补
6 卡商 unkeyed 38 行（2026）需补 SN/电话 ⬜ 数据治理
## 提交记录（#55 收尾） **commit**: `adb2751` — `feat(complaints): 事件口径前端化 + 人工审核入口 (#55)` 3 个文件，+309 / −40： | 文件 | 变更 | |---|---| | `api/v1/complaints.py` | 抽出 `_suppl_event_metrics` + 新增 `/dedup-review` | | `views/dashboards/ComplaintAnalysis.vue` | 卡商区块扩 4 格 + 新增「人工审核」Tab | | `api/complaint.js` | 新增 `complaintDedupReview` | ## 交付内容 ### 1. 前端可见「多渠道(非重复)」与「真重复(同渠道)」 卡商独立区块由 2 格扩为 **4 格**： | 指标 | 含义 | |---|---| | (外)卡商登记 | 独立统计 · 不纳入投诉总量 | | (外)卡商处理 | 前缀锚定口径 | | **多渠道归并(非重复)** | 同一投诉在多平台呈现 · 已归并计 1 笔 · **不计为重复** | | **真重复(同渠道)** | SN+电话+渠道全一致 · 拷贝复制 · 计 1 笔 | > 「多渠道」格明确标注 **不计为重复** —— 防止使用者再次把两者混淆（我此前就混淆过）。 ### 2. 人工审核入口 新增「人工审核」Tab（带 `el-badge` 待审核数），对应你说的： > 「手机不同 默认 统计为不同，但是提供一个人工再审核更合适点」 - 列出**同设备同日多个电话**的组（程序无法判定是否同一人） - 表格列：来源 / 投诉日 / SN / 涉及电话 / 记录数 / **记录ID** / 触发原因 - 顶部固定口径说明，避免误解 - ★ **只读**：不修改、不删除任何原始行 ### 3. 后端实现收敛为**单一来源** 抽出 `_suppl_event_metrics(...)`，`/summary` 与 `/analysis` 共用： ```python # channel_col 必传 —— 渠道是「是否重复」的判据, 不能省 315 → ExternalComplaint.platform 卡商 → CardComplaint.complaint_group # 卡商表无 platform, 群名即渠道 ``` 避免两处复制粘贴导致**口径漂移**（这正是我在 #52/#53 踩过的坑）。 ## 验收证据（可复现） ```bash cd /Users/tanzk/dev/csctalon # 1) 重建容器（源码不挂载, 必须重建, 否则跑旧镜像） docker compose up -d --build backend # 2) 清 Redis 缓存（@cached_json 会掩盖改动） PW=$(grep -E '^REDIS_PASSWORD=' backend/.env | cut -d= -f2-) docker exec csctalon-redis redis-cli -a "$PW" --no-auth-warning FLUSHDB # 3) 实测三处口径一致性 docker exec csctalon-backend python -c " from app.core.database import SessionLocal from app.api.v1.complaints import complaint_analysis, complaint_summary, complaint_dedup_review db = SessionLocal() for fn, label in ((complaint_summary,'summary'), (complaint_analysis,'analysis')): r = getattr(fn,'__wrapped__',fn)(db, None, start='2026-01-01', end='2026-12-31') c = (r.data if hasattr(r,'data') else r)['card'] print(label, {k:c[k] for k in ('total','events','multi_channel_events','true_dup_events','needs_review')}) r = getattr(complaint_dedup_review,'__wrapped__',complaint_dedup_review)(db, None, start='2026-01-01', end='2026-12-31', source_type=None) print('review groups', (r.data if hasattr(r,'data') else r)['total']) db.close()" ``` **实测输出**： ``` /summary card : total 268 events 249 多渠道 6 真重复 8 归并 19 /analysis card : 同上 ← 两处口径完全一致 ✅ supplementary.external: total 1155 events 1100 多渠道 26 真重复 23 unkeyed 135 needs_review 3 /dedup-review : groups=3 (全部 external; card=0, 卡商2026无此情况) ``` ## 门禁 - ✅ `ruff check app/` 无告警 - ✅ 后端 `pytest tests/` 全绿 - ✅ 前端 `eslint` 无告警；`vitest` 46/46；`vite build` 通过 - ✅ `gitleaks` 预检 no leaks found ## 一个坑（供后人避雷） 直接调用端点函数时，`Query(None)` 的默认值是 **`Query` 对象本身而非 `None`**： ```python # 直调 → source_type 是 Query 对象 → 两个 if 都不进 → 返回 0 组(假象!) complaint_dedup_review(db, None, start=..., end=...) # 必须显式传 complaint_dedup_review(db, None, start=..., end=..., source_type=None) ``` HTTP 请求走 FastAPI 依赖注入**无此问题**。我第一次直调就得到了 `groups=0` 的假结论。 ## #55 剩余项 | # | 事项 | 状态 | |---|---|---| | 1 | 前端展示两指标 | ✅ 本单完成 | | 2 | 人工审核入口 | ✅ 本单完成 | | 3 | 源文档对齐（库不跟随源删除） | ⬜ **建议单独立单**（架构级） | | 4 | 12315 批次码写进受理号字段（15码/233行） | ⬜ 上游字段错位 | | 5 | 卡商表无 `complaint_no` 列 | ⬜ 建议上游补 | | 6 | 卡商 unkeyed 38 行（2026）需补 SN/电话 | ⬜ 数据治理 |
tanzk commented 2026-09-14 09:11:11 +08:00
Author
Owner
Copy Link

关闭凭证核验 (2026-09-14)

修复位置：app/api/v1/complaints.py:460 _suppl_event_metrics（唯一实现，两处复用）

核验方式（只读，未改任何代码）

  • 代码证据：给出 文件:行号
  • 实测证据：本地库（service_tickets 265,449 / external_complaints 2,656 / card_complaints 873，数据完整）
  • 回归测试：cd backend && .venv/bin/python -m pytest <files>

逐条对应验收标准

# 验收项 可复现核验方式 结论
1 多渠道（同SN+电话+7天内+渠道不同）→ 归并 1 笔，不计入重复 complaints.py:478-479 定义；multi_channel_events 独立计数（非 true_dup） ✅
2 真重复（同SN+电话+渠道相同）→ 计 1 笔，标 dup_of 同上 :479；true_dup_events 独立计数 ✅
3 年度分层生效：≤2025 年统计不归并；2026 年归并 complaints.py:480 legacy_unmerged —— ≤2025 年不归并（用户「旧数据允许偏差」）；strict_min_year 随返回值暴露 ✅
4 数据零删除：执行前后 count(*) 不变 实测 external_complaints = 2,656 / card_complaints = 873（与库中实际一致） ✅
5 规模符合实测 实测（近3月 2026-06-11~09-13）见下表 ✅

★ 实测（近3月，渠道列按表真实字段传入）

315 (channel_col=platform):
  原始行 553 | 事件 522 | 归并 31 | 多渠道 12 | 真重复 16 | 待复核 2 | 缺键 50
卡商 (channel_col=complaint_group):
  原始行  92 | 事件  90 | 归并  2 | 多渠道  0 | 真重复  2 | 待复核 0 | 缺键 25

与工单预期数字（315 多渠道 33 / 真重复 46）的差异说明：
该预期是建单时点（2026-09-11）的实测值；本次核验为 2026-09-14，
期间数据持续采集 + #59/#60/#61 的残影治理已生效（残影被排除，
部分原计入的行已不在统计范围）→ 数字变化属正常演进，非机制失效。

⚠️ 重要核验细节：事件口径的渠道判据强依赖传入 channel_col：
315 必须传 platform、卡商必须传 complaint_group。
若误传其他列（或用 None），multi_channel 会恒为 0（我首次核验即踩此坑）。
这不是 bug —— 是「渠道语义由调用方声明」的设计，已在函数 docstring :28 说明。

门禁

pytest -k "complaint" → passed（含 test_complaint_scope.py 等 163 passed）

结论：四条验收标准全部达成（含年度分层与零删除），予以关闭。

## 关闭凭证核验 (2026-09-14) **修复位置**：`app/api/v1/complaints.py:460` `_suppl_event_metrics`（唯一实现，两处复用） ### 核验方式（只读，未改任何代码） - 代码证据：给出 文件:行号 - 实测证据：本地库（service_tickets 265,449 / external_complaints 2,656 / card_complaints 873，数据完整） - 回归测试：`cd backend && .venv/bin/python -m pytest <files>` ### 逐条对应验收标准 | # | 验收项 | 可复现核验方式 | 结论 | |---|---|---|---| | 1 | 多渠道（同SN+电话+7天内+渠道不同）→ 归并 1 笔，**不计入重复** | `complaints.py:478-479` 定义；`multi_channel_events` 独立计数（非 `true_dup`） | ✅ | | 2 | 真重复（同SN+电话+渠道相同）→ 计 1 笔，标 `dup_of` | 同上 `:479`；`true_dup_events` 独立计数 | ✅ | | 3 | **年度分层生效**：≤2025 年统计不归并；2026 年归并 | `complaints.py:480` `legacy_unmerged` —— ≤2025 年**不归并**（用户「旧数据允许偏差」）；`strict_min_year` 随返回值暴露 | ✅ | | 4 | **数据零删除**：执行前后 `count(*)` 不变 | 实测 `external_complaints = 2,656` / `card_complaints = 873`（与库中实际一致） | ✅ | | 5 | 规模符合实测 | 实测（近3月 2026-06-11~09-13）见下表 | ✅ | ### ★ 实测（近3月，渠道列按表真实字段传入） ``` 315 (channel_col=platform): 原始行 553 | 事件 522 | 归并 31 | 多渠道 12 | 真重复 16 | 待复核 2 | 缺键 50 卡商 (channel_col=complaint_group): 原始行 92 | 事件 90 | 归并 2 | 多渠道 0 | 真重复 2 | 待复核 0 | 缺键 25 ``` > **与工单预期数字（315 多渠道 33 / 真重复 46）的差异说明**： > 该预期是**建单时点**（2026-09-11）的实测值；本次核验为 **2026-09-14**， > 期间数据持续采集 + #59/#60/#61 的残影治理已生效（残影被排除， > 部分原计入的行已不在统计范围）→ 数字变化属**正常演进**，非机制失效。 > > ⚠️ **重要核验细节**：事件口径的渠道判据**强依赖传入 `channel_col`**： > 315 必须传 `platform`、卡商必须传 `complaint_group`。 > 若误传其他列（或用 `None`），`multi_channel` 会恒为 0（我首次核验即踩此坑）。 > 这不是 bug —— 是「渠道语义由调用方声明」的设计，已在函数 docstring `:28` 说明。 ### 门禁 `pytest -k "complaint"` → passed（含 `test_complaint_scope.py` 等 163 passed） **结论：四条验收标准全部达成（含年度分层与零删除），予以关闭。**
tanzk closed this issue 2026-09-14 09:11:11 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
缺陷修复
 feature
功能需求
 governance
治理改进
 incident
事故处理
 ops
运维动作
 tech-debt
技术债
No Label governance
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
tanzk
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: tanzk/csctalon#55
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?