mindfulness/spec_kit/iOS Widget/tasks.md

iOS Widget（任务清单，V1 写死文案）

说明：本清单根据 plan.md 拆解，要求“可执行、可验收、可标记”。
标记规则：执行完成后将对应项从 - [ ] 改为 - [x]，并把“状态”改为 已完成；进行中改为 进行中；阻塞写明原因与解除条件。

0. 清单状态说明

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

1. 预构建 iOS 原生工程（必须）

• 执行 prebuild 生成 ios/ 目录
  • 状态：已完成（已执行 npx expo prebuild -p ios --no-install，已生成 client/ios/）
  • 命令：

cd client
npx expo prebuild -p ios

• 产出：client/ios/（包含 Xcode 工程）
• 验收：client/ios/ 目录存在，并能在 Xcode 打开

2. 创建 WidgetKit Extension（Xcode 操作）

• 在 Xcode 新建 Widget Extension（WidgetKit）
  • 状态：已完成（已创建 Target：情绪小组件；下一步把 Swift 文件加入该 Target 并跑模拟器验证）
  • 操作：
    • 打开 client/ios/*.xcworkspace（优先 workspace）
    • File -> New -> Target... -> Widget Extension
    • 名称建议：MindfulnessWidget（或你喜欢的命名）
  • 验收：工程里新增 Widget target，能编译通过
  • 下一步（必须做）：
    • 把 client/ios/MindfulnessWidget/MindfulnessWidget.swift 加入 Target Membership：情绪小组件
    • 如果 Xcode 自动生成了同类的 Widget 主文件（例如 情绪小组件.swift / *_Bundle.swift），请确保最终只有一个 @main struct ...: Widget 入口（避免重复入口导致编译失败）

3. 实现写死文案（3 个尺寸都要）

• 实现 Small/Medium/Large 三种尺寸布局
  • 状态：已完成（已提供 client/ios/MindfulnessWidget/MindfulnessWidget.swift 写死文案 + 三尺寸布局代码骨架）
  • 文案（写死）：可先用一条默认文案，例如：你已经很努力了，今天也值得被温柔对待。
  • 要求：
    • Small：一行标题 + 主文案（可截断）
    • Medium：主文案更完整（可多行）
    • Large：增加留白与排版层次（例如标题 + 文案 + 小注脚）
  • 验收：三种尺寸均显示美观，无溢出/遮挡

4. 点击跳转到 Home（Deep Link）

• 为 Widget 配置点击跳转 URL
  • 状态：已完成（代码骨架已使用 .widgetURL(URL(string: \"client:///(app)/home\")!)）
  • URL：client:///(app)/home
  • 实现：在 Widget 中设置 .widgetURL(URL(string: \"client:///(app)/home\")!)
  • 验收：点击小组件能打开 App 并进入 Home

5. 本地验证

• 在 iOS 模拟器运行并添加桌面小组件
  • 状态：阻塞（需要本机 Xcode Run 安装后在模拟器桌面添加 Widget 验证）
  • 步骤：
    • Xcode Scheme 选择主 App（一般是 client），选择模拟器，点击 Run 安装 App
    • 回到桌面长按 -> “+” -> 搜索小组件 -> 添加 Small/Medium/Large
  • 验收：小组件显示正确，点击跳转正确
  • 排查：
    • 桌面搜索不到：通常是没有 Run 安装过主 App，或 Widget target 未加入编译
    • 点击不跳转：确认 Widget 里 widgetURL 为 client:///(app)/home，且 app.json 的 scheme 为 client

6. 文档补充（可选但建议）

• 在 client/README.md 增加“小组件开发（V1 写死文案）”说明
  • 状态：已完成
  • 内容：
    • Expo Go 不支持
    • prebuild 命令
    • Xcode 创建 Widget Extension 的步骤
    • deep link：client:///(app)/home
  • 验收：新同学照 README 可复现