# 桌面 Widget 接入步骤（约 3 分钟，Xcode 操作）

代码已全部写好。主 App 侧（快照写入 + RootView hook）已自动编译生效；
Widget extension 需要你在 Xcode 里建一次 target，再放入两个源文件。

## 1. 创建 Widget Extension target

1. Xcode 打开 `康康.xcodeproj` → 菜单 **File → New → Target…**
2. 选 **iOS → Widget Extension**，点 Next
3. Product Name 填 **`KangkangWidget`**
   - ❌ 不勾 "Include Live Activity"（W5 做 Live Activity 时再往这个 target 里加，Bundle 入口已留好注释）
   - ❌ 不勾 "Include Configuration App Intent"（我们用 StaticConfiguration）
4. 点 Finish；弹出 "Activate scheme?" 选 **Activate**

## 2. 替换模板代码

Xcode 会在工程根目录生成 `KangkangWidget/` 文件夹（含模板 swift 文件）。

1. 删除模板生成的所有 `.swift` 文件（`KangkangWidget.swift`、`KangkangWidgetBundle.swift`、`AppIntent.swift` 等，**保留 `Info.plist` 和 Assets**），选 "Move to Trash"
2. 把 `KangkangWidget-src/` 里的两个文件拖进 Xcode 的 `KangkangWidget` 文件夹（勾选 target：KangkangWidget）：
   - `KangkangWidgetBundle.swift`
   - `PinnedIndicatorsWidget.swift`
3. 拖完后可删掉暂存目录 `KangkangWidget-src/`

## 3. 配置 App Group（两个 target 都要）

数据通过 App Group UserDefaults 传递，ID 固定为 **`group.com.xuhuayong.kangkang`**。

1. 选中工程 → target **康康** → Signing & Capabilities → **+ Capability → App Groups** → ＋ 添加 `group.com.xuhuayong.kangkang`
2. target **KangkangWidget** → 同样添加 App Groups → 勾选同一个 `group.com.xuhuayong.kangkang`
3. KangkangWidget 的 **iOS Deployment Target 改成 17.0**（模板默认可能更高）

> 个人开发者账号下 App Group 会自动注册；如签名报错，在两个 target 的 Signing 里确认 Team 一致。

## 4. 验证

1. scheme 切回 **康康**，跑真机/模拟器
2. 进 App（首页出现即写入快照），回到桌面 → 长按 → 添加小组件 → 找 **康康 · 长期监测**
3. 小/中两个尺寸都支持。没有任何 pinned 指标时显示引导文案；
   在趋势页关注指标（或 C2「关联到趋势」）后，回桌面即可看到最新值

## 故障排查

- **小组件空白/不出现**：先确认两个 target 的 App Group 勾的是同一个 ID；再确认主 App 至少前台打开过一次（快照由主 App 写）
- **数据不更新**：快照在 App 进后台时刷新；强杀 App 不触发 `scenePhase == .background`，正常 Home 手势退出即可
- **编译报 `containerBackground` 不存在**：KangkangWidget 的 Deployment Target 没改成 17.0

## 架构备忘（给后续会话）

- 主 App 写快照：`康康/Persistence/WidgetSnapshot.swift`（数据契约）+ `WidgetSnapshotRefresher.swift`（pinned 指标 → App Group，RootView 在启动和进后台时调用）
- Widget 读快照：`KangkangWidget/PinnedIndicatorsWidget.swift` 内有 `WidgetSnapshot` 的**独立拷贝**（extension 不引主 App 代码）。⚠️ 改字段两边同步
- Widget 不读 SwiftData：store 有文件保护且在主 App 沙盒，extension 锁屏时读不到；快照 = 最后一次看到的值，锁屏也能显示