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。*