基本功能

spec_kit/iOS Widget/spec.md

@@ -0,0 +1,84 @@
+# iOS Widget（高层规范）
+
+## 1. 背景与目标
+
+当前客户端仅在设置页展示了“小组件说明文案”，并未实现真正的 iOS 桌面小组件。
+
+本需求用于实现**真正的 iOS 小组件**（WidgetKit Extension），使用户可以在 iOS 桌面添加小组件并看到“情绪文字/正念短句”等内容。
+
+### 目标
+
+- **可添加到桌面**：支持在 iOS 桌面添加小组件（WidgetKit）
+- **V1（本期）写死内容**：小组件展示一段美观文案（先写死，不做数据同步/更新）
+- **可点击跳转**：点击小组件可跳转回 App 指定页面（默认 Home）
+
+### 非目标（本阶段不做）
+
+- 不承诺严格准点刷新（受 iOS 系统调度限制）
+- 不做复杂的小组件交互配置（如需可后续拆分）
+- 不要求 Android Widget（仅 iOS）
+- **V1 不做数据更新**：不做 App -> Widget 数据共享与更新触发（App Group 留到后续版本）
+
+## 2. 关键结论与约束（必须接受）
+
+- **Expo Go 不支持 WidgetKit**：必须使用 **Development Build / 预构建后的原生工程 / EAS Build** 才能安装带小组件扩展的 App
+- **需要原生扩展**：iOS 小组件必须创建 **WidgetKit Extension（SwiftUI）**
+- **V1 不需要 App Group**：因为内容写死在 Widget 内部；后续做数据共享时再引入 App Group
+
+## 3. 小组件功能需求（高层）
+
+### 3.1 展示内容
+
+- 展示一段“情绪文字/正念短句”
+- 背景支持：
+  - 纯色或渐变（优先）
+  - 图片（可选，后续）
+- 文案需“美观可读”，适配暗色模式（可选）
+
+### 3.2 尺寸支持
+
+- 支持 iOS 常见尺寸：
+  - Small
+  - Medium
+  - Large
+
+### 3.3 更新策略
+
+V1：不做更新策略（内容写死）。后续版本可扩展：
+
+- 固定间隔更新（例如每天/每小时）
+- App 驱动更新：App 写入新内容，Widget 触发 reload（系统仍可能延迟）
+
+### 3.4 点击跳转
+
+- 点击小组件可打开 App 并跳转到指定页面：
+  - 默认：Home
+  - 可选：Favorites
+
+## 4. 数据共享与持久化（高层）
+
+V1：不做数据共享与持久化（写死文案）。
+
+后续版本（V2）再引入 App Group（共享 UserDefaults）与数据来源策略：
+
+- `widget.text`、`widget.updatedAt`、`widget.lang`、`widget.theme` 等
+- 数据来源可选：Home 当前/最近 Like/随机 mock
+
+## 5. 多语言（与 App 一致）
+
+- 语言码沿用客户端：`zh-CN/en/es/pt/zh-TW`
+- V1：Widget 内可先写死单语（例如中文）或做最小的本地化（可选）
+- V2：建议由 App 端选择语言并写入共享数据，降低 Widget 端 i18n 复杂度
+
+## 6. 验收标准
+
+- 可以在 iOS 桌面搜索并添加小组件
+- 小组件能显示一段美观文案（至少支持 Small）
+- 点击小组件能打开 App 并进入预期页面
+
+## 7. 风险与注意事项
+
+- iOS 刷新频率限制：不可承诺“每分钟刷新”等高频
+- App Group / Bundle ID 配置错误会导致 Widget 读不到数据
+- Dev Build / EAS 证书配置成本较高，需要在计划阶段明确落地路径
+