Placeholder Allowlist

公开端派生篇可用 placeholder 的唯一白名单. 议题: MEETING-2026-05-12-07 D-13 主笔: PM 治理: 修改走七角色 (/meeting skill), 不走 PM+Tech Lead 双签 (placeholder 涉及对用户承诺的事实)

设计原则

派生篇 (docs/public/**) 写作中, 如果需要引用用户能感知的具体数字/事实, 必须使用 placeholder, 不允许硬编码. Sync 脚本会:

1. 校验 placeholder 100% 存在于本 allowlist (fail-safe 检查 3)
2. Transform 阶段从主仓真实源自动注入值 (例如 :stages-count: → 6)
3. 若主仓源删除 / 改名了 placeholder 对应字段 → hard-fail 拦 sync (派生失效)

允许使用的 placeholder

placeholder	当前值	注入源 (主仓真实位置)	用户感知场景
:overtime-threshold:	105%	ReminderStage.OVERTIME.thresholdRatio	对家长的承诺数字
:min-android-version:	Android 7.0	app/build.gradle.kts minSdk	安装前家长查兼容性
:stages-count:	6	ReminderStage.values().size	”6 阶段渐进式提醒”宣传语
:weekend-mystery-window:	周六和周日 (en: Saturday and Sunday)	AvailabilityWindow.WEEKEND (仅周六/周日可派遣)	孩子能感知的功能边界

永久排除 (绝不入 placeholder)

以下事实不允许走 placeholder 暴露给公开端, 即使主仓改了公开端也不跟进:

工程内部参数 (用户感知不到)

• ❌ Heartbeat 60s — 心跳间隔
• ❌ Service 轮询 1s (INTERVAL_MS = 1000)
• ❌ 防抖 2s (DEBOUNCE_MS = 2000)
• ❌ SLEEP_THRESHOLD_MS = 5000
• ❌ MAX_ELAPSED_MS = 1500
• ❌ RevivalCoordinator 3s 窗口

阶段阈值具体数字 (UX 决议: 用户感知是 4 档语义)

• ❌ 60% (GENTLE)
• ❌ 75% (FRIENDLY)
• ❌ 90% (SERIOUS)
• ❌ 100% (TIMES_UP)

用户公开端应该用语义表达 (“温柔提醒” / “友好提醒” / “严肃警告” / “时间到”), 不暴露百分比.

内部技术细节

• ❌ XP 公式 (SaveTimeToCoinFormula 分段公式)
• ❌ Migration schema 版本号 (schema 5 → 6 → 7)
• ❌ Room DB 表名
• ❌ Koin module 名 / DI 配置
• ❌ API level 数字 (Android 24 / 36 等)

性能 / SLA 内部承诺

• ❌ RevivalCoordinator P50 ≤5s / P95 ≤60s / P99 ≤5min
• ❌ 测试用例数 (308 / 339)
• ❌ Firebase Test Lab 配额

添加新 placeholder 流程

1. PM 提议新 placeholder + 主仓真实源位置 + 用户感知场景
2. 召集七角色会议 (/meeting) — placeholder 涉及”对用户承诺”, 必须七角色齐审
3. 七角色一致接受后, 主笔 PM 改本文件 + 添加注入逻辑到 scripts/docs-pipeline/transform.py
4. 落 commit 带 MEETING-XX ref + 全七角色 Audience-approved-by

删除 placeholder 流程

同”添加新” — 删除也走七角色, 因为派生篇可能引用了它.

当前状态

✅ 4 个 placeholder 当前有效 (原 5 个). 🗑️ :pin-grace-minutes: 已移除 (2026-06-12): 5min PIN 宽限期功能已删, 注入源 GRACE_WINDOW_MS 不存在, 留着会 hard-fail 拦 sync. 现行: 父母改限额走 App→设置→PIN. 🚧 注入逻辑由 transform.py 实现.