O-6 md5 指纹组装单点化（S-P2-1） #277

New Issue

tanzk · 2026-10-09T04:54:33+08:00

tanzk commented

2026-10-09 04:54:33 +08:00

背景

排期规划 O-6（S-P2-1）：指纹组装逻辑分散多处，漂移风险（同 A-20260910-004 菜单漂移）。

处理动作

grep 全部指纹组装点（md5/hash 拼接）
单源化为一个函数，各采集通道调用
⚠️ 铁律#9：去重键语义不可变，仅做单源化重构，指纹值前后必须一致

验收标准

指纹组装全仓唯一入口
等价性验证：重构前后同样本指纹值 byte 一致（测试守护）

## 背景排期规划 O-6（S-P2-1）：指纹组装逻辑分散多处，漂移风险（同 A-20260910-004 菜单漂移）。 ## 处理动作 - [x] grep 全部指纹组装点（md5/hash 拼接） - [x] 单源化为一个函数，各采集通道调用 - [x] ⚠️ 铁律#9：去重键语义不可变，仅做单源化重构，指纹值前后必须一致 ## 验收标准 - [x] 指纹组装全仓唯一入口 - [x] 等价性验证：重构前后同样本指纹值 byte 一致（测试守护）

tanzk referenced this issue from a commit

2026-10-09 05:40:45 +08:00

#277 refactor: md5 指纹组装单源化（O-6 / S-P2-1）

tanzk commented

2026-10-09 05:41:10 +08:00

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

验收标准	核验方式（可复现）	结果
全仓业务 md5 指纹存在唯一组装入口	新增 `backend/app/services/fingerprint.py`：`md5_hex` / `complaint_dedup_hash` / `staff_unique_key` 三个函数	✅ commit `78e4e32`
既有调用方全部委托单源，无自行拼串	`complaint_sync._dedup_hash`、`upsert/_complaints._complaint_dedup_hash`、`scrm_staff_service.build_staff_unique_key` 三处均改为 `from app.services.fingerprint import ...` 委托；`grep -rn "hashlib" backend/app/services/` 仅剩安全用途(sha256/hmac)与 complaint_scope 明文 key（非 md5，不在范围）	✅ commit `78e4e32`
重构前后指纹值 byte 级一致（铁律#9 去重键语义不可变）	`backend/tests/test_fingerprint_single_source.py::test_complaint_dedup_hash_byte_identical` / `test_staff_unique_key_byte_identical`：旧实现原样内联做基准，覆盖空值/None/空白/中文/超长/含"\|"样本逐条比对	✅ 4 项测试通过
staff key 的 None→"0" 语义钉死	`test_staff_none_config_id_maps_to_zero_not_empty` 显式断言 None 映射为 `"0"` 而非空串	✅ 通过
不引入采集链路回归	回归测试：`tests/test_sn_backfill.py` + `test_dedup_dup_import.py` + `test_device_dim_filter.py` 共 52 项全部通过	✅ 实测命令 `backend/.venv/bin/python -m pytest tests/test_fingerprint_single_source.py tests/test_sn_backfill.py tests/test_dedup_dup_import.py tests/test_device_dim_filter.py -q`

备注：纯重构无语义变更，已推送 origin/main（4aff092）；随下一批改动合并部署。

## 关闭凭证核验 (2026-10-09) | 验收标准 | 核验方式（可复现） | 结果 | |---|---|---| | 全仓业务 md5 指纹存在唯一组装入口 | 新增 `backend/app/services/fingerprint.py`：`md5_hex` / `complaint_dedup_hash` / `staff_unique_key` 三个函数 | ✅ commit `78e4e32` | | 既有调用方全部委托单源，无自行拼串 | `complaint_sync._dedup_hash`、`upsert/_complaints._complaint_dedup_hash`、`scrm_staff_service.build_staff_unique_key` 三处均改为 `from app.services.fingerprint import ...` 委托；`grep -rn "hashlib" backend/app/services/` 仅剩安全用途(sha256/hmac)与 complaint_scope 明文 key（非 md5，不在范围） | ✅ commit `78e4e32` | | 重构前后指纹值 byte 级一致（铁律#9 去重键语义不可变） | `backend/tests/test_fingerprint_single_source.py::test_complaint_dedup_hash_byte_identical` / `test_staff_unique_key_byte_identical`：旧实现原样内联做基准，覆盖空值/None/空白/中文/超长/含"\|"样本逐条比对 | ✅ 4 项测试通过 | | staff key 的 None→"0" 语义钉死 | `test_staff_none_config_id_maps_to_zero_not_empty` 显式断言 None 映射为 `"0"` 而非空串 | ✅ 通过 | | 不引入采集链路回归 | 回归测试：`tests/test_sn_backfill.py` + `test_dedup_dup_import.py` + `test_device_dim_filter.py` 共 52 项全部通过 | ✅ 实测命令 `backend/.venv/bin/python -m pytest tests/test_fingerprint_single_source.py tests/test_sn_backfill.py tests/test_dedup_dup_import.py tests/test_device_dim_filter.py -q` | 备注：纯重构无语义变更，已推送 origin/main（`4aff092`）；随下一批改动合并部署。

tanzk closed this issue

2026-10-09 05:41:10 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tanzk/csctalon#277