mindfulness/spec_kit/overview.md

Spec Kit Overview

本文件用于简短记录当前项目每个 spec 的核心内容摘要，便于快速总览与追踪变更。

Client Bootstrap

• 目标：初始化正念 APP 客户端工程规范，确保可运行、可切环境、可多语言扩展、目录标准化、可 EAS 打包
• 核心范围：客户端工程骨架与文档（client/README.md）、环境变量约定、i18n（CN/EN/ES/PT/TC）、推送/小组件/卡片滑动的一期能力约束
• 主要约定：
  • 环境：.env.dev / .env.prod，推荐 EXPO_PUBLIC_ 前缀
  • 语言码：zh-CN/en/es/pt/zh-TW
  • 目录：app/（可选 expo-router）+ src/（features/services/store/utils 等）+ assets/
  • 打包：EAS Build，dev/prod bundle id 约定
• 阶段产物：
  • spec_kit/Client Bootstrap/spec.md
  • spec_kit/Client Bootstrap/plan.md
  • spec_kit/Client Bootstrap/tasks.md
• 已完成编码（阶段性）：
  • Expo 工程已在 client/ 初始化，并完成 pnpm install
  • i18n 基座已接入：5 份语言资源 + 设备语言优先/设置可切换/持久化 + 入口初始化

Project Bootstrap

• 目标：完成项目仓库初始化与工程约定落地，明确 client/server 结构、dev/pro 环境隔离、MySQL/Redis 资源命名与访问边界
• 核心范围：根目录结构与文档、dev/pro 配置策略、MySQL schema 命名（mindfulness_dev/mindfulness）、Redis ACL + key 前缀隔离（dev:*/pro:*）
• 主要约定：
  • MySQL：prod=mindfulness，dev=mindfulness_dev，统一 utf8mb4 与 snake_case
  • Redis：单实例，通过 ACL 限制不同用户只能访问对应前缀；应用侧强制 key 使用 dev:/pro: 前缀
  • 安全：真实 IP/账号/密码/Token 不写入仓库，仅提供 .env.example 结构
• 阶段产物：
  • spec_kit/Project Bootstrap/spec.md

Onboarding App Shell

• 目标：落地首次进入体验（Onboarding 3–5 页可跳过 + Push 设置可跳过）与主应用壳（点赞/讨厌、收藏夹入口、通用设置入口）
• 核心范围：Onboarding 多页流程、Push 引导页、主界面反应操作（Like/Dislike）、收藏夹、设置页（版本、iOS 小组件入口/说明）
• 阶段产物：
  • spec_kit/Onboarding App Shell/spec.md
  • spec_kit/Onboarding App Shell/plan.md
  • spec_kit/Onboarding App Shell/tasks.md

iOS Widget

• 目标：实现真正的 iOS 桌面小组件（WidgetKit Extension），展示美观文案并与 App 共享数据
• 核心范围：WidgetKit 扩展、App Group 数据共享、尺寸适配（Small/Medium/Large）、点击跳转回 App
• 阶段产物：
  • spec_kit/iOS Widget/spec.md
  • spec_kit/iOS Widget/plan.md
  • spec_kit/iOS Widget/tasks.md

Splash Consent

• 目标：实现开屏页（使用 client/assets/images/index/ 图片资源），首次加载展示渐变同意按钮并提供隐私/协议入口
• 核心范围：开屏 UI、首次同意状态持久化（consent.accepted）、点击同意后进入后续 Onboarding/App 流程
• 阶段产物：
  • spec_kit/Splash Consent/spec.md
  • spec_kit/Splash Consent/plan.md
  • spec_kit/Splash Consent/tasks.md

Card UI

• 目标：优化卡片页 UI 与交互，支持右上角主题切换与个人主页弹窗，并将喜欢/讨厌改为 icon + 动效
• 核心范围：
  • 系统导航栏右上角两个圆形 icon：主题（theme.svg）/ 我的（my.svg）
  • 底部上拉弹窗（Sheet）：统一内容区背景 #FAF3EC，点 X 关闭
  • 主题两种模式：scenery / color（本期最少影响 Home 页面背景），并持久化 ui.theme.mode
  • 喜欢/讨厌按钮：使用 like.svg / hate.svg，喜欢提供“心形填满”强反馈动效（like_filled.svg）
  • 每日提醒弹窗：次数 +/-、Push 提醒开关、渐变 Ok 按钮，并持久化设置
• 阶段产物：
  • spec_kit/Card UI/spec.md
  • spec_kit/Card UI/plan.md
  • spec_kit/Card UI/tasks.md
• 已完成编码（阶段性）：
  • 已接入 react-native-svg-transformer + client/metro.config.js
  • 新增 SheetModal、ThemeModal、ProfileModal 并在 Home 中接入
  • 新增 DailyReminderModal 并从个人主页弹窗打开
  • Home：右上角 icon 按钮、主题切换背景、喜欢/讨厌 icon + 动效

User Profile Scoring

• 目标：将 Onboarding 问卷答案映射为标准化“用户画像 U”，并输出硬规则与置信度元信息，供推荐/Push 等模块统一复用
• 核心范围：mom_stage（离散）、emotion_score（0–1 连续）、context（离散）、need（离散）四维度；以及 profile_version/source/generated_at/confidence（V1.1）
• 主要约定：
  • 输出结构稳定可版本化，便于规则演进
  • 置信度随时间衰减，用于推送场景降个性化/降风险
  • 硬规则优先于任何分数计算（例如 unknown 禁推育儿压力内容等）
• 阶段产物：
  • spec_kit/User Profile Scoring/spec.md