fix:小组件- PUSH

spec_kit/Policy Links/plan.md

@@ -0,0 +1,122 @@
+# 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 不崩溃，且同意流程可继续
+