fix(realname): 增加身份证唯一性校验，防止同一证件重复实名

2026-10-29 12:06:53 +08:00
parent 86fbc05e9b
commit 2029c1f4fb
16 changed files with 538 additions and 53 deletions
@@ -134,3 +134,13 @@ AppCode 与阿里云市场的订购关系绑定，**换商品必须换 AppCode**

 该接口不返回服务商流水号，因此 `user_realname.provider_order_no` 对 cloudmarket 渠道为空。
 姓名与身份证号由本项目自行脱敏入库，并用 `pkg/crypto` 加密保存完整值。
+
+## 身份证唯一性
+
+同一身份证号最多绑定一个已实名账号：
+
+- `user_realname.id_no_hash` 保存身份证号的 HMAC-SHA256 盲索引，`uk_user_realname_id_no_hash` 唯一索引兜底并发请求。
+- 指纹密钥优先使用 `REALNAME_ID_HASH_KEY`，未配置时回退到 `FIELD_ENCRYPTION_KEY`。更换密钥不会丢失唯一性：旧指纹查不到时会退回解密候选比对，并在命中时补写新指纹。
+- 已实名用户再次调用实名校验会返回 `realname_already_verified`。
+- 同一身份证绑定第二个账号会返回 `realname_id_no_used`；后台人工实名同样执行该校验。
+- 存量记录没有指纹或指纹使用旧密钥时，按 `masked_id_no` 取出候选并解密做精确比对，命中后自动补写当前指纹，兼容历史上已加密保存的实名数据。