fix:小组件- PUSH

spec_kit/Policy Links/spec.md

@@ -0,0 +1,127 @@
+# 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 需保证稳定与可访问性（避免过期链接导致合规风险）
+- **缓存与更新**：若客户端做本地缓存，需要确保更新后能及时刷新（本期不强制，后续可扩展）
+