WorkBuddy
60c591fc68
按文档 DoD/约束逐条复查后补齐的差距（承接 438b38d 主体纠偏）：
- CFG-001 字面化：FeatureFlagConfig.KEY_ALIASES（identity.liveness.enabled / 遗留
livenessVerification.enabled → 实现字段 livenessEnabled，读兼容）+ Controller PUT/DELETE
落库归一到 canonical 键 + V051 迁移（删遗留键、写入 identity.liveness.enabled=false）；
MigrationValidationTest 基线 50→51。
- PHOTO-004 真实并发突破：新增 PhotoLimitConcurrencyGuardTest（3 线程 H2 并发冲顶）——
实测咬住「锁照片行+读时计数」在 H2 MVCC 快照漏读、3/3 全成功突破上限的缺陷；
并发控制改为锁用户行（UserMapper.lockUserRow FOR UPDATE）+ 锁后新语句 COUNT，
0 张照片亦有锁可加（补首张并发缺口）；UserPhotoMapper 计数方法同步替换。
- FF-LIVENESS-003 + canonical 持久化：FeatureFlagPersistenceGuardTest +4
（canonical 加载 / 遗留别名读兼容 / PUT 落 canonical 键 / 切换即生效无旧缓存）、
FeatureFlagControllerTest +3（canonical/legacy/reset）。
- 文档同步：AGENTS.md 规则 27（配置治理纪律）；docs/governance/known-risks.md
（7 项含本机 WSL/Docker 故障 KR-07）；config-register / open-questions 更新 canonical 口径；
STATUS rc.21 行补 ⑥⑦⑧。
全量回归 741/0/0/3（基线 717 + 25 新增 − 1 删死测试，宿主机 JDK21+Maven 3.9.9 实测，
本机 WSL/Docker 引擎故障期间）；UI 契约门禁 18/18
6.5 KiB
6.5 KiB
配置登记表 — config-register.md
版本：V1.0.1 配置与规则纠偏基线 · 生效：2026-09-20 · owner：WorkBuddy 代码载体：
FeatureFlagConfig（feature flag，前缀features）/MatchRuleConfigProperties（前缀match）/ProfileProperties（前缀profile）/AccountConfig（前缀account） 一致性守卫：FeatureFlagPersistenceGuardTest、MatchRuleConfigPropertiesTest、EntityMigrationParityTest、MigrationValidationTest核心纪律（AGENTS.md #12 + V1.0.1 纠偏）：技术默认值 ≠ 产品正式确认规则。 未确认的数量/阈值/时间/比例/权重/开关，一律按
DEFAULT + CONFIG管理，禁止作为LOCKED业务规则写死； 所有配置必须有唯一 canonical key，禁止同一业务含义存在多套 key（seed / yml / 字段 / 前端各写一套）。
一、分类图例
| 分类 | 含义 | 是否可硬编码 |
|---|---|---|
LOCKED |
产品负责人已确认的业务/安全硬约束 | 原则上不可随意变更 |
DEFAULT |
当前技术实现默认值，可经配置/ADR 替换 | 不应散落硬编码 |
CONFIG |
需配置化管理的业务参数/开关 | 禁止写死 |
TBD |
产品尚未正式确认 | 禁止当成产品规则 |
FUTURE |
明确不属于当前 V1 范围 | 不实现主链路 |
LEGAL_VERIFY |
上线前需依最新官方/法律要求核验 | 不得自行假设 |
二、配置登记表
| canonical 配置键 | 实现键（yml / flag 字段） | 分类 | 当前默认值 | 产品正式确认 | 是否可配置 | 代码载体 / 说明 |
|---|---|---|---|---|---|---|
identity.liveness.enabled |
DB 键即 canonical 名（feature_flag_overrides.flag_key = 'identity.liveness.enabled'，V051 写入；Java 字段 livenessEnabled，yml features.liveness-enabled） |
CONFIG / TBD | false |
否 | 是 | FeatureFlagConfig.KEY_ALIASES 承担「canonical 键 ↔ 实现字段」映射（identity.liveness.enabled / 遗留 livenessVerification.enabled → livenessEnabled）；写库归一（Controller PUT/DELETE 落 canonical 键）；IdentityPolicy + GET /verification/liveness-status 真实判定点（FF-LIVENESS-002）。活体不是 V1 强制规则；默认关闭不阻断实名主流程；fail-safe：配置缺失默认 false。 |
identity.liveness.provider |
features.livenessProvider（yml features.liveness-provider） |
CONFIG / TBD | none |
否 | 是 | FeatureFlagConfig；none=尚未接入合规第三方，人脸 Provider 选型未定（OQ-IDENTITY-001）。 |
profile.photo.maxCount |
profile.photo.max-count |
CONFIG / TBD | 6 |
否 | 是 | ProfileProperties + ProfilePolicy；6 仅为技术默认；服务器端 PhotoService.ensureWithinPhotoLimit（FOR UPDATE 并发安全）强制校验；前端经 GET /app/config → businessLimits.maxProfilePhotos 动态读取，不再写死。 |
matching.recommendation.minScore |
match.default-score-threshold |
CONFIG / TBD | 60 |
否 | 是 | MatchRuleConfigProperties + MatchingPolicy；60 仅为技术默认，非产品确认（消解 PENDING :43 vs :75 矛盾）；引擎/资格判定读配置；推荐记录 V050 起写 threshold_snapshot 支持追溯。 |
matching.rule.version |
match.rule-version |
CONFIG | 1 |
否 | 是 | MatchRuleConfigProperties；写入 recommendation_records.rule_version，与阈值快照配合构成规则版本。 |
matching.daily.limit |
match.default-daily-limit |
CONFIG | 6 |
是（每日 6 人，见 decision-register） | 是 | MatchRuleConfigProperties。 |
matching.cooldown.days |
match.default-cooldown-days |
CONFIG | 180 |
是（Pass 冷却 180 天） | 是 | MatchRuleConfigProperties。 |
matching.weights.*（10 维） |
match.*-weight（age 15 / region 15 / marital 10 / children 10 / education 5 / height 5 / marriagePlan 15 / settlement 10 / lifestyle 10 / interest 5） |
CONFIG / TBD | 见左 | 否 | 是 | MatchRuleConfigProperties；yml 未覆盖，全用类内默认；打分公式仍为 V1 占位（见 audit 未来项）。 |
matching.local-eligibility.required |
match.local-eligibility-required |
CONFIG | false |
否 | 是（仅 docker yml） | 本地资格是否作为推荐硬性门禁；默认关。 |
account.data-retention.months |
account.data-retention-months |
LOCKED | 36 |
是（2026-09-19 产品确认下限 36 个月） | 是 | AccountConfig；注销后保留期下限，到期人工审核匿名化（V049）。 |
account.feature-flags.*（活动/红娘/图片聊天/申诉/转介/互选/专项 开关） |
features.* |
CONFIG | 见 FeatureFlagConfig |
部分 | 是 | FeatureFlagConfig；feature_flag_overrides（V048）持久化覆盖。 |
idempotency.ttl |
应用层 idempotency_records（TTL 默认 86400s） |
CONFIG / LEGAL_VERIFY | 86400s |
否 | 是 | 幂等去重窗口；开放第三方时需决定是否按调用方分级（OQ，见 open-questions）。 |
三、已消除的 key 漂移（本轮）
| 漂移 | 处置 |
|---|---|
seed livenessVerification.enabled vs 实现键 livenessEnabled vs 治理名 identity.liveness.enabled（三套 key 同义） |
已删 demo-seed-final.sql 的死 seed 行；V051 迁移把 feature_flag_overrides 收敛为只写 canonical 键 identity.liveness.enabled（删除遗留 livenessVerification.enabled/livenessEnabled 行 + 写入 canonical 行）；FeatureFlagConfig.KEY_ALIASES 承担「canonical/遗留键 → 实现字段 livenessEnabled」读兼容映射，Controller PUT/DELETE 落库归一到 canonical 键。Java 内部字段保持 livenessEnabled（文档允许内部变量如此命名）。 |
MatchConfig（shared/config）与 MatchRuleConfigProperties（match/config）同前缀 match 双 bean |
已删 死类 MatchConfig（0 业务引用），统一读 MatchRuleConfigProperties。 |
前端 mergeAppConfig 平铺合并 → 服务端嵌套 businessLimits.* 从不生效 |
已修 显式节-键映射，maxProfilePhotos 等真正下发到前端。 |
最后更新: 2026-09-21 — V1.0.1 配置与规则纠偏 + canonical key 字面化：登记 identity.liveness.enabled / profile.photo.maxCount / matching.recommendation.minScore 三项 canonical 键；V051 把活体键收敛为 feature_flag_overrides 唯一正式键（KEY_ALIASES 读兼容遗留键）；消除 MatchConfig 双 bean 与前后端照片上限失同步。