danyang-match/docs/governance/config-register.md

配置登记表 — config-register.md

版本：V1.0.1 配置与规则纠偏基线 · 生效：2026-09-20 · owner：WorkBuddy 代码载体：FeatureFlagConfig（feature flag，前缀 features）/ MatchRuleConfigProperties（前缀 match）/ ProfileProperties（前缀 profile）/ AccountConfig（前缀 account）/ ContactAuthorizationConfig（前缀 matchmaker.contact） 一致性守卫：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）。
matchmaker.contact.enabled	matchmaker.contact.enabled（Java 字段 enabled）	CONFIG / TBD	代码缺省 false（fail-safe：配置缺失=机制关闭）；生产 yml 显式 true	否	是	ContactAuthorizationConfig；受控联系（DEC-MATCHMAKER-003 B1 例外通道）功能总开关，紧急停用入口；判定点 ContactAuthorizationService 全部写路径与 disclose 前置。
matchmaker.contact.approver-authorities	matchmaker.contact.approver-authorities（逗号分隔权限码）	CONFIG / 已裁决（2026-10-11）	"matchmaker.team.assign,matchmaker.assign"	是（分层语义）	是	ContactAuthorizationConfig；分层审批（OQ-MATCHMAKER-009 RESOLVED）：列表首段（默认 matchmaker.team.assign）=主审岗（组织范围校验，NULL=NULL 平台直属可审），兜底岗键固定 matchmaker.assign（全量审批不受组织限制、不受本配置调整影响）；两者皆无 403。读点 approve/reject Service 层动态判定。
matchmaker.contact.consent-deadline-hours	matchmaker.contact.consent-deadline-hours	CONFIG / TBD	72	否	是	ContactAuthorizationConfig；批准后用户单独同意窗口，超时 pending_consent 惰性收敛为 expired。
matchmaker.contact.default-validity-days	matchmaker.contact.default-validity-days	CONFIG / TBD	7	否	是	ContactAuthorizationConfig；授权生效期（LEGAL_VERIFY③ 默认值，待终审），expires_at = user_consented_at + N 天。
matchmaker.contact.retention-days	matchmaker.contact.retention-days	CONFIG / TBD	365	否	是	ContactAuthorizationConfig；授权记录保留期（LEGAL_VERIFY④ 默认值，对齐 OQ-LOCAL-ELIG-001 现行 365）；读点 GET .../my 响应 retentionDays 下发前端。

---

三、已消除的 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-10-11（二次）— 受控联系产品裁决落账：approver-authorities 转「已裁决/分层语义」（组长主审+管理员兜底，OQ-009 RESOLVED）；enabled/consent-deadline-hours/default-validity-days/retention-days 裁决维持默认值（OQ-003 RESOLVED）；request 读点补 enabled fail-safe（OQ-010 落地顺带修复真实缺口）。此前：2026-10-11 受控联系立项登记五 key。