mindfulness/spec_kit/Policy Links/plan.md

Policy Links（技术计划）

1. 目标与原则

目标：让客户端所有「隐私协议 / 使用协议」入口（至少包含：首次同意页 + 个人主页弹窗）统一通过后端接口获取链接，并支持按设备语言分发，缺省回退 EN。

原则：

• 客户端不写死协议 URL（避免发版更新）
• 请求失败不阻塞主流程（尤其是首次同意页）
• 语言选择策略一致、可解释、可排查（返回 resolvedLang）

2. 接口与契约

2.1 HTTP 接口

• 方法与路径：GET /v1/legal/links
• 请求头：
  • Accept-Language: en / tc（当前仅支持 EN / TC；客户端可按 i18n/设备语言映射为其中之一）
• 响应（JSON）：
  • privacyPolicyUrl: string
  • termsOfUseUrl: string
  • resolvedLang: "en" | "tc"

2.2 语言回退（服务端决策）

• 若 Accept-Language 缺失/无法解析：回退 en
• 若目标语言的链接未配置：回退 en
• resolvedLang 表示服务端最终命中的语言（用于排查）

3. 后端实现方案（FastAPI）

3.1 配置来源

采用环境变量（Pydantic Settings）承载各语言链接配置：

• 推荐配置（EN）：
  • LEGAL_PRIVACY_URL_EN
  • LEGAL_TERMS_URL_EN
• 可选：
  • LEGAL_PRIVACY_URL_TC / LEGAL_TERMS_URL_TC

补充：若未配置 LEGAL_*，后端将使用内置协议内容页作为兜底，保证客户端点击后“必有内容”。

3.2 路由与业务逻辑

• 新增 v1/legal 路由模块
• 读取 Accept-Language 做轻量解析（只关心 en/tc，其他回退 en）
• 根据解析结果选择 URL；如缺失则回退到 EN URL

3.3 内置协议内容页（兜底，保证有内容）

• 页面接口：
  • GET /v1/legal/privacy：隐私协议（HTML）
  • GET /v1/legal/terms：使用协议（HTML）
• 内容来源：
  • 直接使用仓库文档：设计说明文档/隐私协议.md、设计说明文档/用户使用协议.md
• 语言策略：
  • 仍按 Accept-Language 解析 en/tc；若文档缺少 tc 段落则回退 en
• 链接下发回退：
  • 当 LEGAL_* 未配置（或显式走内置）时，GET /v1/legal/links 返回当前服务域名下的上述内置页面绝对 URL

3.4 兼容性与安全

• 要求链接为 HTTPS（推荐）；返回前做基本 URL 校验（通过响应模型约束）
• 不引入数据库变更

3.5 后端测试（建议）

• 单测覆盖：
  • Accept-Language 缺失 → resolvedLang=en
  • tc 命中/缺失回退
  • zh-hant/zh-hk/zh-tw 等输入能解析为 tc

4. 客户端实现方案（React Native + Expo）

4.1 统一 service

• 新增 src/services/legalApi.ts：
  • 统一拼接 API_BASE_URL + /v1/legal/links
  • 统一设置 Accept-Language
  • 统一超时与错误处理（抛错由调用方兜底）

4.2 接入点

• 首次同意页（app/(splash)/splash.tsx）：
  • 页面展示时拉取链接
  • 拉取失败：不崩溃、不阻塞「同意并继续」
  • 点击协议入口：使用 expo-web-browser 打开下发链接
• 个人主页弹窗（components/home/ProfileModal.tsx）：
  • 弹窗打开时拉取链接
  • 点击「隐私协议/使用协议」时打开下发链接（不再 toastTodo）

4.3 语言映射策略（客户端）

• 将客户端当前语言映射到 en / tc 二选一：
  • 任意 zh* → tc
  • 其他语言 → en

5. 可观测与排障

• 开发环境打印：
  • 请求地址、请求头（含 Accept-Language）
  • 拉取失败原因（仅 dev）
• 线上环境：
  • 不打印用户相关敏感信息（本接口仅链接配置，风险较低，但仍应克制日志）

6. 发布与回滚策略

• 灰度：dev 环境可先不配 LEGAL_*，直接验证内置页面能打开；再逐步切到外部托管链接
• 补齐多语言：逐步补齐 zh-CN / zh-TW 链接配置
• 回滚：
  • 后端：回滚到仅 EN 配置仍可运行（客户端自动回退）
  • 客户端：即使接口失败也不阻塞主流程（保持可用）

7. 验收映射（对应 spec）

• 首次同意页 + 个人主页弹窗均从 API 获取链接
• 设备语言为 EN/TC 时分别打开对应链接
• 不支持语言回退 EN
• 后端不可达时 App 不崩溃，且同意流程可继续