mindfulness/spec_kit/Policy Links/spec.md

Policy Links（高层规范）

1. 背景与目标

当前客户端首次进入的同意页（Splash Consent）需要在底部提供「隐私协议」「用户使用协议」的查看入口。为避免协议链接写死在客户端、并支持多语言分发，本需求将协议链接放到后端统一管理与下发，客户端按设备语言展示对应链接。

目标

• 首进页补充协议链接：在客户端首次进入的同意页底部展示「隐私协议」「用户使用协议」链接入口
• 后端托管与可配置：协议链接由后端配置与下发，支持后续更新而无需发版
• 按设备语言下发：后端根据客户端设备语言返回对应语言的链接
• 默认 EN：当语言缺失/不支持/无法识别时，回退为英文（EN）链接

非目标（本阶段不做）

• 不做复杂的协议版本强制重同意机制（例如协议更新后要求重新同意）
• 不规定协议内容必须以何种格式（Markdown/HTML/PDF）存储；本需求仅要求“链接由后端提供并可访问”

2. 需求范围与交付物

范围

• 客户端：
  • 首次进入同意页底部展示 2 个协议链接入口，并在点击时打开对应链接
  • **个人主页弹窗（ProfileModal）**中「隐私协议」「用户使用协议」入口也必须使用同一套后端下发链接（不再写死/不再 TODO）
• 后端：提供可被客户端请求的协议链接下发能力，并支持按语言返回不同链接

交付物

• 后端：新增/扩展一个“协议链接配置与下发”的接口（或纳入现有配置接口），并可按语言返回
• 客户端：同意页 UI 补充协议链接入口，且链接来源改为后端下发（含兜底策略）
• 文档：本 spec

3. 用户体验与交互（高层）

3.1 展示位置

• 位置：客户端首次进入同意页底部，「同意并继续」按钮下方（或同等位置）展示：
  • 隐私协议
  • 用户使用协议

3.2 点击行为

• 点击后打开对应链接内容：
  • 推荐使用 App 内 WebView（不离开 App），也允许外部浏览器打开（实现阶段在客户端方案中确定）
• 若链接无法获取或打开失败：
  • 仍允许用户继续使用“同意并继续”（不阻塞主流程）
  • 入口可隐藏或展示为不可点击状态（实现阶段确定，但需保持体验一致且不崩溃）

4. 语言策略

4.1 语言来源

• 客户端以设备语言/应用当前语言作为请求依据（优先级由客户端既有 i18n 策略决定）
• 客户端请求应携带语言信息（例如 Accept-Language 头或显式参数）

4.2 默认与回退

• 默认语言：EN
• 回退策略（必须满足）：
  • 语言缺失/空值 → EN
  • 语言不支持 → EN
  • 后端配置缺失对应语言 → EN

4.3 支持语言（建议）

当前多语言仅支持 EN / TC，建议最少覆盖：

• en
• tc

说明：当前协议文档可能包含英文与繁体版本；当 tc 版本缺失时，系统会回退到 EN。

5. 后端职责（高层）

5.1 配置管理

• 后端存储并维护协议链接配置，至少包含：
  • privacy_policy_url
  • terms_of_use_url
• 配置需支持按语言维度区分（例如每个语言各一套 URL）
• 兜底要求：当外部托管链接未配置或不可用时，后端应提供可访问的内置协议页面（保证客户端点击“必有内容”）

5.2 下发接口（建议形态）

• 提供一个可被客户端调用的接口，用于获取协议链接（示例，仅表达形态，不强制路径）：
  • GET /v1/legal/links
• 输入（建议）：
  • 语言：通过 Accept-Language 或 lang 参数（例如 en/tc）
  • 可选：平台、App 版本（用于灰度/差异化配置）
• 输出（建议）：
  • privacyPolicyUrl: string
  • termsOfUseUrl: string
  • resolvedLang: string（后端最终命中的语言，便于排查）

5.3 可用性与安全

• 链接必须可被公网访问（或在 App 可访问的网络环境可达）
• 推荐使用 HTTPS
• 若后端短时不可用，不应导致客户端首进流程崩溃

6. 客户端职责（高层）

• 在首次进入同意页渲染时，向后端请求协议链接
• 根据返回结果渲染「隐私协议」「用户使用协议」入口
• 若请求失败或返回缺失：
  • 按本 spec 的默认回退策略处理（最终保证 EN）
  • 不阻塞“同意并继续”主流程
• （建议）对获取到的链接做轻量校验（非空字符串、看起来是 URL），避免渲染异常

7. 验收标准

• 首进展示：首次进入同意页时，底部出现「隐私协议」「用户使用协议」入口
• 语言分发：
  • 设备语言为 EN 时，打开英文链接
  • 设备语言为已支持的其他语言（如 zh-CN/zh-TW）时，打开对应语言链接
  • 设备语言为不支持语言时，默认回退打开 EN 链接
• 稳定性：后端不可达/返回异常时：
  • App 不崩溃
  • “同意并继续”仍可正常进入后续流程

8. 风险与注意事项

• 法务一致性：各语言协议内容差异需要法务确认；若部分语言缺失，需明确 zh-CN 的回退策略（到 EN 还是 zh-TW）
• 链接长期可用：后端配置的 URL 需保证稳定与可访问性（避免过期链接导致合规风险）
• 缓存与更新：若客户端做本地缓存，需要确保更新后能及时刷新（本期不强制，后续可扩展）