# Daily Widget Reco（任务清单）

> 对应计划：`spec_kit/Daily Widget Reco/plan.md`
>
> 标记规则：
>
> - 执行完成后将对应项从 `- [ ]` 改为 `- [x]`，并把“状态”改为 **已完成**
> - 进行中改为 **进行中**
> - 阻塞写明原因与解除条件

---

## 0. 清单状态说明

- **状态**：未开始 / 进行中 / 已完成 / 阻塞
- **阻塞**：必须写明阻塞点与解除条件

---

## 1. 客户端：补齐 Widget 场景 API（RN）

- [ ] **新增 `fetchRecoWidget`（`POST /v1/reco/widget`）**  
  - **状态**：未开始  
  - **文件**：`client/src/services/recoApi.ts`  
  - **要求**：
    - Header `Accept-Language` 逻辑沿用 `fetchRecoFeed`
    - body 结构沿用 `RecoRequest`
    - timeout 建议 12s
  - **验收**：在 App 内调用可拿到 `items[0].text`（允许为空但不报错）

---

## 2. iOS 原生能力：App Group 共享读写（suiteName 已确认）

> suiteName：`group.com.damer.mindfulness`

- [ ] **新增 App Group 共享存储原生模块（RN Bridge）**  
  - **状态**：未开始  
  - **目标**：RN 可写/读共享 `UserDefaults(suiteName:)`  
  - **要求**：
    - 支持 `setString(key, value)` / `getString(key)`（最小闭环）
    - 以 JSON 字符串形式存储（上层 JS 自行 `JSON.stringify/parse`）
  - **验收**：
    - RN 写入后，Widget 侧能读到同一 key
    - 解析失败不 crash（返回 `null`/空字符串均可，按上层回退）

- [ ] **新增触发 Widget 刷新的原生方法（可选但建议）**  
  - **状态**：未开始  
  - **目标**：App 写入缓存后触发 `WidgetCenter.reloadAllTimelines()`  
  - **验收**：App 调用后，Widget 在合理时间内刷新显示新内容（允许系统延迟）

---

## 3. 客户端：写入共享配置/画像/每日缓存（App ↔ Widget 共通）

- [ ] **写入共享配置 `widget.config.v1`（包含 `apiBaseUrl`）**  
  - **状态**：未开始  
  - **要求**：
    - App 启动后（或 baseURL 计算完成后）写入
    - JSON 字段最少包含：`schema_version`、`apiBaseUrl`、`saved_at`
  - **验收**：Widget 侧可读到正确 baseURL（dev/pro 随 App 切换）

- [ ] **写入共享画像 `widget.userProfile.v1_2`（Onboarding 完成后）**  
  - **状态**：未开始  
  - **依赖**：客户端已能获取/持久化用户画像（本地存储已有 `user.profileScoring`）  
  - **要求**：
    - 结构以现有 `UserProfileV1_2` 输出为准
    - JSON 字段建议包含：`schema_version`、`saved_at`、`user_profile`
  - **验收**：Widget 侧可读到 `user_profile`，且可用于请求后端

- [ ] **实现 App 前台“可选主动拉取”并写入 `widget.dailyReco.v1`**  
  - **状态**：未开始  
  - **要求**：
    - 判断 `day_key`（用户时区 `YYYY-MM-DD`）不是今天时才拉取
    - 调用 `fetchRecoWidget(k=1)`，成功写入缓存
    - 失败不影响 UI，不阻塞主流程
  - **验收**：App 打开后能把今日推荐写入共享缓存，Widget reload 后展示一致

---

## 4. iOS Widget：读取共享缓存并展示（先不接网络也能跑通）

- [ ] **Widget 读取 `widget.dailyReco.v1` 并展示**  
  - **状态**：未开始  
  - **要求**：
    - JSON 解析失败容错：视为无缓存
    - 展示优先级：今日缓存 → 最近缓存 → 兜底文案
  - **验收**：手动写入共享缓存后，Widget 立即能展示对应文案（或在下一次 reload 展示）

---

## 5. iOS Widget：网络拉取每日推荐 + Timeline 每日刷新（核心）

- [ ] **Widget 在缓存过期时请求 `POST /v1/reco/widget` 并写回缓存**  
  - **状态**：未开始  
  - **依赖**：可读到 `widget.config.v1`（apiBaseUrl）与 `widget.userProfile.v1_2`（user_profile）  
  - **要求**：
    - 无鉴权
    - 超时建议 8～12s
    - `Accept-Language` 与 App 保持一致（`en/tc`）
    - `items=[]` 视为失败，走回退
  - **验收**：清空今日缓存后，Widget 能在一次 timeline 请求内拉取并展示今日推荐（允许先兜底再更新）

- [ ] **实现每日刷新调度（TimelinePolicy）**  
  - **状态**：未开始  
  - **要求**：
    - `nextRefreshDate` 设置为“下一天本地时间 00:10～01:00 随机”之一
    - 不追求严格准点，但确保每日范围内能更新
  - **验收**：通过修改系统日期/模拟 day_key 变化，可观察到会进入“过期→重新拉取”逻辑

---

## 6. 联调与验收验证（必须）

- [ ] **联调：添加小组件后，未打开 App 也能每日更新（尽力而为）**  
  - **状态**：未开始  
  - **步骤**：
    - 安装带 Widget 的开发包
    - 在桌面添加 Widget
    - 清空今日缓存并等待 Widget 刷新（或手动触发 reload）
  - **验收**：Widget 能从后端拉取并展示；隔天能更新到新内容（允许系统延迟）

- [ ] **回退验证：断网/后端不可用/返回异常**  
  - **状态**：未开始  
  - **验收**：
    - Widget 不崩溃
    - 展示最近缓存或兜底文案

- [ ] **一致性验证：App 与 Widget 当天展示一致**  
  - **状态**：未开始  
  - **验收**：App 主动拉取并写入缓存后，Widget reload 后展示同一条 `content_id/text`

---

## 7. 文档与总览更新

- [ ] **补充实现说明（可放入客户端 README 或本需求 overflow）**  
  - **状态**：未开始  
  - **要求**：记录 suiteName、共享 key、如何本地验证

- [ ] **更新 `spec_kit/overview.md`**  
  - **状态**：未开始  
  - **要求**：在“Spec Kit Overview”中新增本需求摘要（目标/产物/已完成编码变更）