198 lines
8.4 KiB
Markdown
198 lines
8.4 KiB
Markdown
# Daily Widget Reco（高层规范）
|
||
|
||
> 阶段：高层规范（spec）
|
||
>
|
||
> 背景引用：
|
||
>
|
||
> - `spec_kit/Personalized Reco/overview.md`：后端已实现可复用推荐流程（Feed / Push / Widget）
|
||
> - `spec_kit/iOS Widget/spec.md`：已完成 WidgetKit Extension V1（写死文案）
|
||
>
|
||
> 本需求聚焦：**iOS 小组件“每日推荐”与 App 数据共通**，以及**客户端与后端推荐接口的串联**。
|
||
|
||
---
|
||
|
||
## 1. 背景与动机
|
||
|
||
后端已实现推荐接口（含 `widget` 场景），但客户端目前只接入了 Feed 推荐（`POST /v1/reco/feed`），iOS 小组件仍是 V1 写死文案。
|
||
|
||
现在需要实现：
|
||
|
||
- iOS 小组件展示“每日推荐”（每天一条），从后端获取。
|
||
- App 与 Widget 的推荐内容数据共通（同一天展示同一条），并支持在用户添加小组件后开始每日更新。
|
||
- 推荐链路具备可回退能力：网络失败、画像缺失、接口异常时不崩溃、仍有可展示内容。
|
||
|
||
---
|
||
|
||
## 2. 目标（Goals）
|
||
|
||
- **后端串联**：客户端与 iOS WidgetKit 能稳定调用后端 `widget` 场景推荐接口获取每日文案。
|
||
- **数据共通**：App 与 Widget 通过 **App Group 共享存储**读写同一份“每日推荐缓存”，保证展示一致。
|
||
- **每日更新（尽力而为）**：
|
||
- 小组件添加到桌面后，系统开始调度 Widget Timeline；Widget 能在**每天**刷新一次内容（受系统限制，允许延迟）。
|
||
- App 在合适时机触发更新与 `WidgetCenter.reload`，提高准时性（但不承诺“严格准点”）。
|
||
- **安全与回退**：出现失败时按回退梯度展示（今日缓存 → 最近一次缓存 → 兜底安全文案），且不阻塞 App 主流程。
|
||
|
||
---
|
||
|
||
## 3. 非目标（Non-goals）
|
||
|
||
- 不做 Android Widget。
|
||
- 不在本需求内改动后端推荐算法逻辑与 DB（后端已实现接口）。
|
||
- 不承诺高频刷新（例如分钟级），遵循 iOS WidgetKit 刷新限制。
|
||
- 不在本需求内实现复杂的“用户自定义小组件配置”（例如选择主题/类型）；仅做“每日一句”。
|
||
|
||
---
|
||
|
||
## 4. 范围与交付物
|
||
|
||
### 4.1 范围
|
||
|
||
- 客户端（React Native / Expo）：
|
||
- 增加 `POST /v1/reco/widget` 的请求封装（与 Feed 形态一致）。
|
||
- 负责把“用户画像快照/必要上下文”写入 App Group（供 Widget 拉取/请求）。
|
||
- 在合适时机触发“写缓存 + 通知 Widget 刷新”。
|
||
- iOS Widget（Swift / WidgetKit Extension）：
|
||
- 从 App Group 读取“每日推荐缓存”并展示。
|
||
- 在需要时（缓存过期/缺失）发起网络请求从后端拉取，并写回缓存（或由 App 拉取并写回，见第 8 节决策）。
|
||
- 共享数据契约：
|
||
- 定义 App 与 Widget 共用的数据结构（版本化、可演进）。
|
||
|
||
### 4.2 交付物
|
||
|
||
- 客户端：推荐接口封装 + 共享存储写入 + 刷新触发。
|
||
- iOS：Widget Timeline Provider 支持每日推荐（读取共享缓存/必要时拉取）。
|
||
- 文档：本 `spec.md`。
|
||
|
||
---
|
||
|
||
## 5. 术语与关键约束
|
||
|
||
- **Daily Reco（每日推荐）**：Widget 场景 Top1 文案（每天一条）。
|
||
- **App Group**：iOS 用于 App 与 Extension 共享数据的机制（建议使用共享 `UserDefaults(suiteName:)`）。
|
||
- **Widget 刷新限制**：刷新由系统调度，**不可保证准点**；需要设计缓存与兜底展示。
|
||
|
||
---
|
||
|
||
## 6. 后端接口契约（Client ↔ Server）
|
||
|
||
### 6.1 接口
|
||
|
||
- `POST /v1/reco/widget`
|
||
|
||
### 6.2 Header
|
||
|
||
- `Accept-Language`：
|
||
- 客户端沿用既有策略：当前仅区分 `en/tc`
|
||
- 规则：`i18n.language` 以 `zh` 开头 → `tc`，否则 `en`
|
||
|
||
### 6.3 Request Body（与 Feed 一致）
|
||
|
||
- `k?: number`（Widget 默认 1；建议不传或显式传 `1`）
|
||
- `user_profile: UserProfileV1_2`（必填）
|
||
- `already_recommended_ids?: (string|number)[]`（可选，默认 `[]`）
|
||
- `touched_or_viewed_ids?: (string|number)[]`（可选，默认 `[]`）
|
||
- `now?: string`（ISO8601，可选，用于测试/确定性）
|
||
|
||
### 6.4 Response Body
|
||
|
||
- `items: RecommendedItem[]`（Widget 预期取 `items[0]`；允许为空）
|
||
- `meta: Record<string, unknown>`（用于可观测/调参；客户端可选择性落地）
|
||
|
||
---
|
||
|
||
## 7. 共享数据契约（App ↔ Widget）
|
||
|
||
> 原则：结构**版本化**、字段可缺省、读取端容错；避免把整个业务状态塞进共享区。
|
||
|
||
### 7.1 共享 Key（建议）
|
||
|
||
- `widget.dailyReco.v1`：每日推荐缓存（Widget 展示的主数据）
|
||
- `widget.userProfile.v1_2`：用户画像快照（供 Widget 发起请求使用）
|
||
- `widget.recoHistory.v1`：去重/频控所需的最小历史（可选，控制大小）
|
||
- `widget.config.v1`：Widget 端需要的配置（例如 `apiBaseUrl`、灰度开关等）
|
||
|
||
### 7.2 `widget.dailyReco.v1` 数据结构（JSON）
|
||
|
||
- `schema_version: 1`
|
||
- `saved_at: string`（ISO8601）
|
||
- `day_key: string`（本地日维度 key，例如 `2026-02-03`；用于“今天是否已刷新”的判断）
|
||
- `lang: "en" | "tc"`
|
||
- `item`（可为空）：
|
||
- `content_id: number`
|
||
- `text: string`
|
||
- `final_score?: number`
|
||
- `fallback_level_final?: number`
|
||
- `meta?: Record<string, unknown>`（可选，用于排查；注意体积）
|
||
- `source: "app" | "widget"`（可选：谁写入的）
|
||
|
||
### 7.3 读写规则
|
||
|
||
- Widget 展示优先级：
|
||
1. `day_key` 为今天且 `item.text` 非空 → 直接展示
|
||
2. 否则展示最近一次缓存（若存在）
|
||
3. 否则展示兜底安全文案（写死）
|
||
- 写入要求：
|
||
- 写入必须原子化（一次性写完整 JSON），避免部分字段缺失导致解析失败
|
||
- 解析失败时当作“无缓存”，走兜底策略
|
||
|
||
---
|
||
|
||
## 8. 每日更新策略（刷新触发与责任划分）
|
||
|
||
### 8.1 关键结论
|
||
|
||
为满足“用户添加小组件后可每日更新”，需要依赖 WidgetKit 自身的 Timeline 调度。仅靠 App 在前台触发更新，无法保证用户不打开 App 时也能更新。
|
||
|
||
### 8.2 推荐实现（V1.5：Widget 主动拉取）
|
||
|
||
- **Widget Timeline Provider**：
|
||
- 每次 `getTimeline`：
|
||
- 先读 `widget.dailyReco.v1`
|
||
- 若 `day_key` 不是今天 → 尝试从后端请求 `POST /v1/reco/widget` 获取今日内容
|
||
- 成功后写入 `widget.dailyReco.v1` 并返回 timeline
|
||
- 失败则返回“最近一次缓存/兜底文案”的 timeline
|
||
- Timeline 刷新策略：
|
||
- `policy = .after(nextRefreshDate)`，`nextRefreshDate` 设为“下一天的本地 00:10～01:00 之间随机一个时间”（减少集中刷新）
|
||
|
||
- **App（RN）**：
|
||
- 在 Onboarding 完成或画像更新时，把 `widget.userProfile.v1_2` 写入共享区
|
||
- 当 App 成功拉取到推荐（可选）时，也可写入 `widget.dailyReco.v1` 并触发 `WidgetCenter.reloadAllTimelines()`，提升即时性
|
||
|
||
### 8.3 备选实现（App 主动拉取 + Widget 仅展示）
|
||
|
||
若团队希望 Widget 端完全不发网络请求，则：
|
||
|
||
- App 负责在“启动/前台/每天首次打开”等时机拉取 `POST /v1/reco/widget` 并写入共享缓存
|
||
- Widget 仅读取缓存展示
|
||
|
||
缺点：用户不打开 App 时，小组件可能长期不更新（不满足“每日更新”的强诉求）
|
||
|
||
---
|
||
|
||
## 9. 失败回退与稳定性
|
||
|
||
- **网络失败**：使用最近一次缓存；若无缓存，展示兜底安全文案。
|
||
- **接口返回 items 为空**：视为失败，走同样回退。
|
||
- **画像缺失**：
|
||
- App 侧应尽量在首次进入完成问卷后写入 `widget.userProfile.v1_2`
|
||
- 若仍缺失，Widget 端不崩溃，直接展示缓存/兜底文案；并在下一次 timeline 继续尝试
|
||
- **数据损坏/解析失败**：清空本次读取结果，走兜底策略（不可 crash）。
|
||
|
||
---
|
||
|
||
## 10. 验收标准（Acceptance Criteria）
|
||
|
||
- **接口串联**：客户端/Widget 能成功请求 `POST /v1/reco/widget` 并解析返回。
|
||
- **数据共通**：同一天内，App 与 Widget 展示的“每日推荐”一致（以共享缓存为准）。
|
||
- **每日更新**：用户把小组件添加到桌面后，小组件在后续每天能更新到新的推荐（允许系统延迟，但应在一天内更新）。
|
||
- **可用性**：断网/后端不可用/返回异常时，Widget 仍能展示最近缓存或兜底文案，App 不崩溃。
|
||
|
||
---
|
||
|
||
## 11. 风险与注意事项
|
||
|
||
- iOS Widget 刷新由系统调度，无法承诺“严格 00:00 更新”；需接受“尽力而为 + 缓存兜底”。
|
||
- App Group 的 suiteName / entitlements 配置错误会导致 Widget 读不到共享数据；必须在实现阶段统一校验。
|
||
- Widget 端直连后端需要维护 baseURL 与环境切换策略（dev/pro）；建议通过 `widget.config.v1` 注入，避免写死。
|
||
|