人脸不能是唯一入口：一套刷脸系统的多通道验证改造实战

public interface IdentityVerifier {

    /** 通道标识，用于审计日志与灰度控制 */
    String channel();

    /** 通道是否可用：设备状态、授权状态、开关状态三者都要看 */
    boolean isAvailable();

    /** 执行一次验证，不允许抛业务异常，失败以结果对象返回 */
    VerifyResult verify(VerifyRequest request);
}

public final class VerifyRequest {
    public final String scene;      // 例如 "GATE_ENTRANCE" / "APP_LOGIN"
    public final String userIdHint; // 可选，扫码/刷卡场景可携带
    public final byte[] credential; // 各通道自定义：人脸帧、码值、卡号
}

public final class VerifyResult {
    public final boolean passed;
    public final String channel;    // 实际生效的通道
    public final String reasonCode; // 失败原因码，进日志
    public final String matchedUserId;
}

public final class FaceVerifier implements IdentityVerifier {

    private final FaceSdk sdk;
    private final FeatureStore store;
    private final FeatureSwitch featureSwitch;

    @Override
    public String channel() {
        return "FACE";
    }

    @Override
    public boolean isAvailable() {
        if (!featureSwitch.isFaceEnabled()) {
            return false;                 // 业务开关：整体停用
        }
        if (!sdk.isLicenseValid()) {
            return false;                 // 授权失效，常见的高发故障
        }
        return sdk.isEngineReady();       // 引擎初始化状态
    }

    @Override
    public VerifyResult verify(VerifyRequest request) {
        if (!isAvailable()) {
            return VerifyResult.fail("FACE", "FACE_CHANNEL_UNAVAILABLE");
        }
        FaceFeature f = sdk.extract(request.credential);
        if (f == null) {
            return VerifyResult.fail("FACE", "FACE_EXTRACT_FAILED");
        }
        Match m = store.searchTop1(f);
        if (m == null || m.score < threshold()) {
            return VerifyResult.fail("FACE", "FACE_NO_MATCH");
        }
        return VerifyResult.pass("FACE", m.userId);
    }
}

public final class VerifyRouter {

    private final List channels;

    public VerifyResult verify(VerifyRequest request, String preferred) {
        // 1) 用户显式选择的通道优先
        if (preferred != null) {
            IdentityVerifier v = find(preferred);
            if (v != null && v.isAvailable()) {
                return v.verify(request);
            }
            // 指定通道不可用：不阻断，继续走备选
            Audit.log("CHANNEL_FALLBACK", preferred);
        }
        // 2) 按注册顺序挑第一个可用通道
        for (IdentityVerifier v : channels) {
            if (v.isAvailable()) {
                return v.verify(request);
            }
        }
        // 3) 全部不可用：必须落到人工，而不是直接拒绝
        return ManualVerifier.enqueue(request);
    }
}

public final class ManualVerifier implements IdentityVerifier {

    private final TicketQueue queue;
    private final AuditLog audit;

    @Override
    public String channel() {
        return "MANUAL";
    }

    @Override
    public boolean isAvailable() {
        return queue.hasDutyStaff();     // 当前是否有人在岗
    }

    @Override
    public VerifyResult verify(VerifyRequest request) {
        String ticket = queue.enqueue(request.scene, System.currentTimeMillis());
        audit.write("MANUAL_TICKET", ticket, request.scene);
        // 人工核验是异步的，返回受理号而不是即时结果
        return VerifyResult.pending("MANUAL", ticket);
    }
}

public enum ConsentState { NONE, GRANTED, WITHDRAWN }

public final class ConsentService {

    private final ConsentRepo repo;
    private final FeatureStore store;
    private final AuditLog audit;

    /** 同意：必须独立记录来源与时间，不能挂在主协议上 */
    public void grant(String userId, String source, long ts) {
        repo.save(userId, ConsentState.GRANTED, source, ts);
        audit.write("CONSENT_GRANT", userId, source);
    }

    /** 撤回：状态变更 + 特征值删除 + 缓存清理 + 日志，四步缺一不可 */
    public void withdraw(String userId) {
        repo.save(userId, ConsentState.WITHDRAWN, "USER_SELF_SERVICE", System.currentTimeMillis());
        int deleted = store.deleteByUserId(userId);   // 本地人脸库特征值
        store.evictCache(userId);                     // 内存缓存
        audit.write("CONSENT_WITHDRAW", userId, "deleted=" + deleted);
    }
}

@Component
public class RetentionJob {

    // 30 是占位默认值，不是推荐值：需按业务回看周期确定，本文不给出通用取值
    @Value("${face.retention.days:30}")
    private int retentionDays;

    @Scheduled(cron = "0 30 3 * * ?")   // 每天凌晨 3:30
    public void purge() {
        long deadline = System.currentTimeMillis() - retentionDays * 86400000L;
        int rows = verifyLogDao.deleteBefore(deadline);
        int features = featureStore.deleteOrphan();   // 无对应同意记录的特征值
        audit.write("RETENTION_PURGE", "logs=" + rows, "features=" + features);
    }
}

-- 只留了人脸、没有任何替代凭证的用户数
SELECT COUNT(*) FROM user u
WHERE u.face_feature_id IS NOT NULL
  AND NOT EXISTS (SELECT 1 FROM credential c WHERE c.user_id = u.id);

@Component
public class ConsentBackfillJob {

    private final ConsentRepo repo;
    private final FeatureStore store;
    private final NotifyService notify;

    /** 每天扫描一次，推进补签状态机 */
    @Scheduled(cron = "0 0 10 * * ?")
    public void advance() {
        // 历史采集、尚未发起补签
        for (String uid : repo.findByState(ConsentState.LEGACY)) {
            notify.sendConsentRequest(uid);          // 站内 + 短信，文案独立成条
            repo.moveTo(uid, ConsentState.PENDING);
        }
        // 超过补签期限未响应：停用人脸通道并删除特征值
        for (String uid : repo.findTimeoutPending(backfillDeadlineDays)) {
            store.deleteByUserId(uid);
            repo.moveTo(uid, ConsentState.TIMEOUT);
            Audit.write("CONSENT_BACKFILL_TIMEOUT", uid);
        }
    }
}

public final class PiaRecord {
    public String scenario;            // 应用场景标识
    public String purpose;             // 处理目的
    public String method;              // 处理方式
    // (一) 合法性、正当性、必要性结论
    public String necessityConclusion;
    // (二) 对个人权益的影响与降低影响的措施
    public String impactAndMitigation;
    // (三) 泄露、篡改、丢失、毁损或被非法获取的风险与危害
    public String riskAndHarm;
    // (四) 保护措施是否与风险程度相适应
    public String measureAdequacy;
    public String assessor;
    public long   assessAt;
    public int    retainYears = 3;     // 第九条要求的下限
}

public final class DeviceSignageConfig {
    public String  deviceId;
    public boolean noticePosted;        // 是否已设置显著提示
    public String  noticePhotoId;       // 现场照片留档
    public String  captureZoneDesc;     // 采集区域说明
    public boolean privateSpace;        // 是否涉私密空间，恒为 false
    public long    checkedAt;
}