commit a1561c7d43f93c7ac44b1e704ba6c5b204bcade3 Author: ila Date: Sun May 24 16:39:16 2026 +0800 chore: 初始化仓库结构 - 建立 monorepo 结构：app/ + server/ + docs/ - 纳入全部需求/架构/开发计划文档 - 新增 docs/PROGRESS.md 功能状态总览 - 新增 docs/decisions/ ADR 决策记录（001-004） - 新增根目录 README.md 含 AI 阅读指引 - 新增 .gitignore Co-Authored-By: Claude Sonnet 4.6 diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..097d93f --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,8 @@ +{ + "permissions": { + "allow": [ + "Bash(git config *)", + "Bash(git add *)" + ] + } +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f8a259d --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# 依赖 +node_modules/ +.pnp +.pnp.js + +# 构建产物 +dist/ +build/ +.next/ +out/ + +# 环境变量（含 API Key，绝不提交） +.env +.env.local +.env.*.local + +# 系统文件 +.DS_Store +Thumbs.db +desktop.ini + +# 编辑器 +.vscode/ +.idea/ +*.suo +*.ntvs* +*.njsproj +*.sln + +# 日志 +*.log +npm-debug.log* + +# Capacitor +android/ +ios/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..5dac7b2 --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# 🌱 人生目标 App + +> 帮助用户管理人生目标树、每日/每周复盘并通过 AI 教练保持方向感的个人成长应用。 + +## 目录结构 + +``` +life_goals/ +├── app/ — React 前端（PWA → Capacitor） +├── server/ — 后端 API（Phase 4 账号体系阶段启动） +└── docs/ — 项目文档 +``` + +## 快速了解项目 + +| 我想了解… | 去哪里看 | +|-----------|---------| +| 当前开发进度 | [docs/PROGRESS.md](./docs/PROGRESS.md) | +| 重要决策的来龙去脉 | [docs/decisions/](./docs/decisions/) | +| 需求和功能边界 | [docs/02-需求分析/](./docs/02-需求分析/) | +| 技术选型和架构 | [docs/03-架构设计/](./docs/03-架构设计/) | +| 迭代路线图 | [docs/05-开发计划/](./docs/05-开发计划/) | +| 完整文档目录 | [docs/README.md](./docs/README.md) | + +## 给 AI 的阅读指引 + +1. 先读 `docs/PROGRESS.md` — 了解当前阶段和各功能状态 +2. 读 `docs/decisions/` — 了解重要决策的背景和原因 +3. 按需读对应的需求 / 架构文档 + +## 当前阶段 + +**Phase 0 已完成** — MVP 包含目标树 + 每日复盘 + AI 教练 +**Phase 1 待开发** — 每周复盘 + 体验提升 + +技术栈：React · Claude AI API · localStorage +创建日期：2026-05-24 diff --git a/app/README.md b/app/README.md new file mode 100644 index 0000000..e09f5ca --- /dev/null +++ b/app/README.md @@ -0,0 +1,42 @@ +# app — React 前端 + +> 人生目标 App 的前端代码，目标是 PWA（Phase 2）后续打包为 Capacitor 原生 App（Phase 3）。 + +## 当前状态 + +📋 **待初始化** — 代码目前以 Claude Artifact 形式存在（`life-goals.jsx`），Phase 2 时迁移至此目录并引入 Vite 构建工具。 + +## 技术栈（规划） + +| 项目 | 技术 | +|------|------| +| 框架 | React + Vite | +| 样式 | Inline CSS + CSS Variables | +| 存储 | localStorage（PWA）/ SQLite（Capacitor） | +| AI 接口 | Anthropic API（Phase 4 前直连，之后走 server 代理） | +| 打包 | Capacitor（Phase 3） | + +## 启动方式（初始化后） + +```bash +cd app +npm install +npm run dev +``` + +## 目录结构（初始化后规划） + +``` +app/ +├── public/ +│ ├── manifest.json — PWA 配置 +│ └── icons/ +├── src/ +│ ├── components/ — GoalNode / ScoreRing / CheckIn 等 +│ ├── pages/ +│ ├── services/ — callAI() / storage 封装 +│ └── main.jsx +└── package.json +``` + +> 详见 [架构设计文档](../docs/03-架构设计/技术选型与数据结构.md) diff --git a/docs/01-需求收集/用户访谈与原始需求.md b/docs/01-需求收集/用户访谈与原始需求.md new file mode 100644 index 0000000..3254cba --- /dev/null +++ b/docs/01-需求收集/用户访谈与原始需求.md @@ -0,0 +1,75 @@ +# 📋 需求收集 — 用户访谈与原始需求 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a6818eaaafcab80e853ad2) + +## 需求背景 + +**前期用户：产品作者本人（自用工具）。** 后续验证有市场价值后再面向外部用户推广。 + +核心动机是**防止迷失方向**——在日常忙碌中不忘初心，能随时看到自己的目标并检查是否偏离。通过每日和每周的复盘节奏，持续记录感受与总结，并在偏离时及时纠正。 + +--- + +## 访谈记录 + +### 基本信息收集（2026-05-24） + +| 问题 | 用户回答 | +|------|---------| +| 主要使用者？ | 产品作者本人，前期纯自用 | +| 复盘节奏？ | **每日**复盘为主 + **每周**检查和复盘；偶尔会漏记 1-2 天，属正常情况 | +| 每天检查目标的场景？ | 晚上睡前，用于复盘当天 | +| 复盘内容？ | 今日对齐度评分（1-10 分）+ 记录感受和总结 + AI 点评 | +| 每周复盘内容？ | 回顾本周目标完成情况，总结规律，纠正偏离方向 | +| AI 的角色？ | 全部都要：分析冲突、主动追问、梳理模糊目标、点评反思 | +| 数据存储要求？ | 跨设备同步（需要账号/持久化） | +| 偏离感知方式？ | 每天打分 + 每周汇总，低分或连续低分触发 AI 提醒 | +| 目标树的清晰程度？ | 人生主目标很清晰，子目标需要拆解 | +| 界面语言？ | 中文 | +| 视觉风格？ | 可视化优先（图表、树形图、进度环） | +| 开发推进方式？ | 先做目标树 + 每日打分两个核心模块（MVP） | + +--- + +## 原始需求描述（用户原话） + +> 我现在需要编写个 app 用来检查自己人生目标，包含了主目标、年目标、月目标、周目标和天目标。人生目标是一棵树，最上面的是人生主要目标，枝干是 1 年期到 3 年期的重要目标，枝干下面的叶子是周目标或月目标，叶子上的脉络是每天的目标。 +> +> 为了不会突然忘记或迷失自己的目标，需要记录下来，然后每天检查自己是否偏离，如果偏离了，就要纠正偏离的方向。 +> +> 其中可以加入 AI 来整理和预测。 + +--- + +## 核心痛点 + +1. **迷失感** — 日常繁忙容易忘记长期目标 +2. **断层感** — 每天的行动和人生目标之间缺乏连接 +3. **模糊感** — 知道大方向，但子目标不够具体 +4. **无反馈** — 没有机制判断自己是否在正确轨道上 +5. **沉淀缺失** — 感受和总结散落在脑子里，没有系统记录，难以回顾规律 + +--- + +## 用户使用场景（User Story） + +### 每日场景 +- 作为用户，我想在**每晚睡前**打开 App，回顾今天的行动是否推进了我的目标 +- 作为用户，我想给今天打一个 **1-10 分的对齐度评分**，写下今天的**感受和总结** +- 作为用户，我想让 **AI 教练点评**我的复盘，指出偏离并给出纠正建议 +- 作为用户，如果某天**忘记打卡**（偶尔 1-2 天），App 不应报错或惩罚，历史记录有空白即可 + +### 每周场景 +- 作为用户，我想每周做一次**周复盘**，回顾本周目标完成情况和主要感受 +- 作为用户，我想在周复盘中看到**本周每日评分趋势**，发现规律 +- 作为用户，我想让 AI 基于本周数据，帮我**识别偏离模式**并给出下周调整建议 + +### 初始化场景（面向外部用户） +- 作为新用户，我想在第一次打开时**选择一个模版**快速搭建目标树，而不是面对空白页不知所措 +- 作为新用户，我想根据自己的人生阶段（职业发展 / 创业 / 学习 / 健康 / 家庭）**选择对应的模版**，预填适合我的目标结构 +- 作为新用户，我也可以选择**空白开始**，自己从零搭建目标树 + +### 通用场景 +- 作为用户，我想随时看到**完整目标树**，从人生目标到周目标一目了然 +- 作为用户，我想随时向 AI 提问，**梳理和拆解**模糊的目标 +- 作为用户，我希望数据**跨设备同步**，手机和电脑都能访问 diff --git a/docs/02-需求分析/功能优先级与边界.md b/docs/02-需求分析/功能优先级与边界.md new file mode 100644 index 0000000..20cc85c --- /dev/null +++ b/docs/02-需求分析/功能优先级与边界.md @@ -0,0 +1,137 @@ +# 🔍 需求分析 — 功能优先级与边界 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a681d08067c046a637acdd) + +## 目标用户 + +| 阶段 | 用户 | 说明 | +|------|------|------| +| 前期（当前） | 产品作者本人 | 自用，快速验证功能价值 | +| 中期 | 早期外部用户 | PWA 上线后逐步开放 | +| 后期 | 付费会员 | 账号体系稳定后商业化 | + +--- + +## 功能优先级矩阵 + +| 功能 | 用户价值 | 实现难度 | 优先级 | +|------|---------|---------|-------| +| 目标树管理（增删改查） | 极高 | 中 | P0 - MVP | +| 每日评分 + 感受记录 | 极高 | 低 | P0 - MVP | +| AI 教练点评 | 高 | 中 | P0 - MVP | +| AI 对话教练 | 高 | 中 | P0 - MVP | +| 历史复盘与趋势图 | 高 | 中 | P0 - MVP | +| 漏打卡容错（历史空白不报错） | 高 | 低 | P0 - MVP | +| **每周复盘** | 高 | 中 | P1 | +| 跨设备数据同步 | 高 | 高 | P4（账号体系阶段） | +| 目标完成进度 checkbox | 中 | 低 | P1 | +| 目标提醒通知 | 中 | 高 | P2 | +| 目标树导出分享 | 中 | 中 | P2 | +| **初始化模版**（通用模版 + 人生方向模版） | 高 | 低 | P2（PWA 上线时） | +| 精品付费模版库 | 中 | 低 | P5（会员阶段） | +| 拖拽排序 | 低 | 高 | P6 | + +--- + +## MVP 范围确认（P0） + +### 模块一：目标树管理 + +**目标：** 用户能够建立和维护自己的人生目标树 + +**功能明细：** +- 支持 5 个层级：人生 / 年度 / 月度 / 周 / 日 +- 点击文字内联编辑 +- 点击 ＋ 按钮添加子目标（自动分配下一层级） +- 点击 ✕ 删除节点（包括子树） +- 展开 / 折叠子树 +- 层级配色区分：金色→橙色→蓝色→绿色→紫色 + +**验收标准：** +- 用户能在 3 分钟内建立一棵包含 5+ 节点的目标树 +- 数据刷新后仍然保持 + +### 模块二：每日复盘 + +**目标：** 用户每晚进行目标对齐度复盘，记录感受与总结 + +**功能明细：** +- 1-10 分评分环（可视化进度环） +- 自由文字输入框：记录当天感受、总结、偏离情况 +- 提交后 AI 自动读取目标树 + 近期复盘记录 → 生成点评和纠偏建议 +- 每天只能提交一次（已提交状态展示） +- 历史复盘列表（近 14 天） +- **漏打卡容错：** 某天无记录显示为空白，不报错、不惩罚，不影响其他日期 + +**验收标准：** +- 提交后 3 秒内返回 AI 点评 +- 评分 ≤4 显示红色，5-7 黄色，≥8 绿色 +- 连续漏记 2 天后，下次打开时 AI 主动提示 + +### 模块三：每周复盘（Phase 1） + +**目标：** 用户每周做一次整体回顾，发现规律、纠正偏离 + +**功能明细：** +- 显示本周每日评分趋势柱状图 +- 汇总本周感受和总结关键词 +- 提交本周总体反思文字 +- AI 基于本周数据生成：偏离模式分析 + 下周调整建议 + +**验收标准：** +- 每周日（或用户手动触发）可进行周复盘 +- AI 周报建议与每日点评在语气和内容上有明显区别（宏观 vs 微观） + +### 模块五：初始化模版（Phase 2） + +**目标：** 外部用户首次使用时快速搭建目标树，降低启动门槛 + +**触发时机：** 首次打开 App 且目标树为空时，进入模版选择页 + +**模版类型：** + +| 模版 | 预填重点 | 适合人群 | +|------|---------|---------| +| 🗂️ 通用模版 | 纯结构 + 占位符，用户自填内容 | 所有人，默认推荐 | +| 🚀 职业发展 | 职位目标、技能成长、收入提升 | 上班族、想晋升/转型者 | +| 💼 创业/副业 | 产品目标、用户规模、收入里程碑 | 创业者、斜杠青年 | +| 📚 学习提升 | 技能掌握、证书考取、输出成果 | 学生、自学者 | +| 💪 健康生活 | 运动习惯、饮食、睡眠、心理状态 | 关注身心健康者 | +| 👨‍👩‍👧 家庭生活 | 家庭关系、子女教育、家庭财务 | 已婚有子女者 | +| 🌱 自由探索 | 最轻结构，留白最多 | 目标还不清晰者 | + +**初始化流程：** +``` +首次打开（目标树为空） + ↓ +欢迎页：选择启动方式 + ├── 从模版开始 → 选择模版 → 预览内容 → 一键载入 → 进入编辑 + └── 空白开始 → 直接进入空目标树 +``` + +**验收标准：** +- 用户从选择模版到完成初始化不超过 1 分钟 +- 载入模版后可自由编辑所有内容，模版只是起点 + +> 💡 **付费扩展：** Phase 5 会员阶段提供精品行业模版库（更细分、更专业的模版），作为付费内容之一。 + +### 模块四：AI 对话教练 + +**目标：** 用户能随时与 AI 就目标进行对话 + +**功能明细：** +- AI 上下文包含：完整目标树 + 近 7 天复盘记录 + 最近一次周复盘 +- 支持任务：拆解目标、分析冲突、预测偏离风险 +- 对话历史在单次会话内保持 + +--- + +## 不在范围内（MVP） + +- 多用户 / 团队功能 +- 账号体系（MVP 阶段免登录，Phase 4+ 引入） +- 外部日历同步 +- 目标分享 / 导出 +- 移动端原生 App（Phase 3 Capacitor 阶段） +- 每周复盘模块（Phase 1 引入，MVP 仅做每日） +- 初始化模版（Phase 2 PWA 上线时引入，自用阶段无需） diff --git a/docs/03-架构设计/技术选型与数据结构.md b/docs/03-架构设计/技术选型与数据结构.md new file mode 100644 index 0000000..9367f9e --- /dev/null +++ b/docs/03-架构设计/技术选型与数据结构.md @@ -0,0 +1,207 @@ +# 🏗️ 架构设计 — 技术选型与数据结构 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a6813c88b1f89d0df5b12b) + +## 技术选型 + +| 维度 | 选择 | 理由 | +|------|------|------| +| 框架 | React (JSX) | 组件化、状态管理成熟，适合复杂交互 | +| 样式 | Inline CSS + CSS Variables | 无需构建工具，展开即用 | +| 存储 | Artifact Storage API | 跨设备持久化，免登录 | +| 备用存储 | localStorage | 离线备用，与 Storage API 双写 | +| AI 接口 | Anthropic API /v1/messages | 直接调用，无需后端 | +| AI 模型 | claude-sonnet-4-20250514 | 性价最优，响应快 | +| 字体 | Noto Serif SC | 中文手写书感，与"人生"主题匹配 | + +--- + +## 数据结构设计 + +### 目标树 — `GoalTree` + +```javascript +{ + root: { + id: "root", + text: "我的人生主目标", + level: "life", // life | year | month | week | day + children: ["id1", "id2"], + expanded: true + }, + nodes: { + "id1": { + id: "id1", + text: "年度目标 A", + level: "year", + children: ["id3"], + expanded: true + } + // ... + } +} +``` + +**设计决策：** +- 使用 flat 结构（nodes 字典）而非嵌套对象，方便增删改 +- children 存 id 数组，保持顺序 +- level 自动推断：父节点 level 的下一级 + +### 每日复盘 — `Checkins` + +```javascript +{ + "2026-05-24": { + score: 8, + note: "今天完成了...", + aiReply: "AI 点评内容..." + } + // 以日期为 key +} +``` + +**设计决策：** +- 以日期字符串为 key，天然去重 +- AI 点评随复盘存储，无需单独请求 + +--- + +## 模块划分 + +``` +App +├── GoalNode — 目标树节点（递归组件） +├── ScoreRing — SVG 圆形评分环 +├── CheckIn — 每日复盘输入表单 +├── History — 历史复盘列表 + 柱状图 +├── Advisor — AI 对话界面 +└── callAI() — Anthropic API 封装函数 +``` + +## 数据流 + +``` +用户输入 + ↓ +React State (useState) + ↓ +localStorage (备用) + ↓↑ +Artifact Storage API (主存储，跨设备) +``` + +## AI 调用流 + +``` +用户提交复盘 + ↓ +收集目标树全文 + 近期复盘记录 + ↓ +构建 System Prompt (教练角色 + 目标上下文) + ↓ +Anthropic /v1/messages + ↓ +返回点评文字 → 显示 + 存储 +``` + +--- + +## 性能考虑 + +- AI 请求只在用户主动提交时触发，不自动定时 +- 目标树数据小，本地状态即可实时更新，无需节流 +- Storage API 异步写入，不阻塞 UI + +--- + +## 移动端打包策略 + +采用**两阶段**路线，先低成本验证市场，再投入打包成本。 + +### 阶段一：PWA（需求验证） + +> 目标：以最小改动让用户在手机上"安装"并使用，验证产品市场价值。 + +| 项目 | 说明 | +|------|------| +| 方式 | 浏览器打开后「添加到主屏幕」 | +| 改动 | 加 `manifest.json` + Service Worker 即可 | +| 存储 | 沿用 localStorage（Artifact Storage API 不适用独立部署） | +| 限制 | iOS Safari 对 PWA 支持有限；无法上架应用商店 | +| 验证指标 | 用户留存、复盘频率、AI 功能使用率 | + +### 阶段二：Capacitor 原生打包（正式发布） + +> 触发条件：PWA 阶段验证产品有市场价值后启动。 + +| 项目 | 说明 | +|------|------| +| 工具 | Capacitor（@capacitor/android + @capacitor/ios） | +| 构建工具 | 需引入 Vite（当前无构建工具） | +| 存储替换 | Artifact Storage API → `@capacitor-community/sqlite` 或 localStorage | +| Android | Android Studio 打包 APK/AAB，可上架 Google Play | +| iOS | Xcode（需 Mac）打包 IPA，需 Apple 开发者账号（$99/年） | + +**存储迁移注意：** 当前 Artifact Storage API 是 Claude 平台专属，独立打包后必须替换，localStorage 备用数据可作为迁移来源。 + +--- + +## 账号体系与云同步策略 + +### 核心决策 + +产品分三个阶段演进： + +| 阶段 | 登录 | 存储 | 目标 | +|------|------|------|------| +| **① 开发调试期** | 免登录 | 本地 | 稳定核心功能，快速迭代 | +| **② 用户增长期** | 可选注册登录 | 本地（默认）/ 服务端（登录后） | 沉淀用户数据，建立留存 | +| **③ 商业化期** | 登录必要 | 服务端 | 开展会员收费功能 | + +> 设计原则：先让用户体验到价值，再引导注册沉淀数据，最后以数据和高级功能驱动付费。 + +### 存储模式对比 + +| 模式 | 触发条件 | 存储位置 | 跨设备同步 | +|------|---------|---------|-----------| +| 游客模式（默认） | 打开即用 | 本地 SQLite / localStorage | ❌ | +| 登录模式（可选） | 用户主动注册 / 登录 | 服务端 DB + 本地缓存 | ✅ | + +### 数据迁移策略（游客 → 登录） + +用户注册时，需处理本地已有数据的合并： + +``` +用户首次登录 + ├── 服务端无数据 → 直接上传本地数据 ✅ 无冲突 + ├── 服务端有数据 → 提示用户选择合并策略 ⚠️ 需 UI 设计 + │ ├── 以服务端为主（覆盖本地） + │ ├── 以本地为主（覆盖服务端） + │ └── 按节点时间戳合并（推荐） + └── 已登录换设备 → 拉取服务端数据，正常同步 ✅ 无冲突 +``` + +### AI 调用迁移（引入后端时） + +当前 AI 调用在**前端直接请求 Anthropic API**，API Key 暴露在客户端。引入后端后需同步迁移： + +``` +当前（无后端）： + 客户端 ──→ Anthropic API ⚠️ API Key 暴露 + +引入后端后： + 客户端 ──→ 自有服务端 ──→ Anthropic API ✅ Key 安全，可做用量控制 +``` + +**后端引入时机：** 与账号体系同步实现，无需提前单独做。 + +### 架构演进路线 + +``` +Phase 2 PWA Phase 3 Capacitor Phase 4+ 账号体系 +──────────── ───────────────── ───────────────── +localStorage → 本地 SQLite → 本地 SQLite（游客默认） + ↕ 可选登录同步 + 服务端 DB + 账号 API + AI 调用走服务端代理 +``` diff --git a/docs/04-UI设计/视觉规范与交互流程.md b/docs/04-UI设计/视觉规范与交互流程.md new file mode 100644 index 0000000..67a87a9 --- /dev/null +++ b/docs/04-UI设计/视觉规范与交互流程.md @@ -0,0 +1,111 @@ +# 🎨 UI 设计 — 视觉规范与交互流程 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a681e2955befd8a352ff48) + +## 设计理念 + +**主题：** 深夜导航仪 — 让用户每晚打开就有"回到指挥中心"的仪式感 + +**设计关键词：** +- 深色底 (`#0a0e1a`)，星空感 +- 温暖金色 (`#f5c542`) 为主强调色 +- 可视化优先：SVG 圆形进度环、层级树形图、柱状趋势图 +- 中文宋体（Noto Serif SC）增强人文感 + +--- + +## 颜色规范 + +| 用途 | 颜色 | Hex | +|------|------|-----| +| 主强调色 / 人生目标层 | 金色 | `#f5c542` | +| 年度目标层 | 橙色 | `#f0884a` | +| 月度目标层 | 蓝色 | `#4aabf0` | +| 周目标层 | 绿色 | `#7dd87a` | +| 日目标层 | 紫色 | `#c47af5` | +| 高分指示 | 绿色 | `#7dd87a` | +| 中分指示 | 黄色 | `#f5c542` | +| 低分指示 | 红色 | `#f04a4a` | +| 页面背景 | 深山蓝黑 | `#0a0e1a` | +| 卡片背景 | 半透明白 | `rgba(255,255,255,0.04)` | +| 边框 | 深蓝灯光 | `#1e2535` | + +--- + +## 页面布局 + +### Header +- 左：项目标题"人生罗盘"+ 当日日期 +- 右：今日评分小圆环（未复盘时显示虚线圈） + +### 底部 Tab 导航（固定 4 项） + +``` +🌳 目标树 | ✦ 每日复盘 | 📊 历史 | ◈ AI 教练 +``` + +### 内容区域各 Tab 布局 + +#### 🌳 目标树 + +``` +[提示文字] 点击文字编辑 · 点击 + 添加子目标 +[根节点] 人生—金色左边框 + └ [年度] 橙色左边框 + └ [月度] 蓝色左边框 + └ [周] 绿色左边框 + └ [日] 紫色左边框 +[层级说明色色块] +``` + +#### ✦ 每日复盘 + +``` +[ScoreRing 大圈 90px] [评分按钮 1-10] + +[文字反思输入框 4行] + +[提交复盘 · AI 点评] 按钮 + +[金色边框卡片] AI 教练点评内容 +``` + +#### 📊 历史 + +``` +[近期评分趋势柱状图] + +[复盘卡片列表] + [ScoreRing 52px] [日期 + 反思文字 + AI 摘要] +``` + +#### ◈ AI 教练 + +``` +[对话气泡流] + 右对齐：用户消息（金色渐变） + 左对齐：AI 回复（半透明卡片） + +[输入框] + [→ 发送] 按钮 +``` + +--- + +## 交互状态设计 + +| 状态 | 表现 | +|------|------| +| 空默认 | 虚线圈 + 灰色"今日" | +| 已评分未提交 | 圆环点亮 + 评分按钮选中状态 | +| 提交中 | 按钮显示"AI 分析中…" | +| 已完成 | AI 点评卡片展示 + "已保存"标识 | +| 编辑目标 | 节点文字变为 input，回车或失焦保存 | +| 删除确认 | 直接删除（MVP 简化，后续添加 confirm） | + +--- + +## 响应式设计 + +- 最大内容宽度：600px（在手机和桌面均可用） +- 评分按钮在小屏时自动换行（flex-wrap） +- 导航 Tab 固定底部（Header） diff --git a/docs/05-开发计划/MVP范围与迭代路线图.md b/docs/05-开发计划/MVP范围与迭代路线图.md new file mode 100644 index 0000000..bb58364 --- /dev/null +++ b/docs/05-开发计划/MVP范围与迭代路线图.md @@ -0,0 +1,128 @@ +# 🚀 开发计划 — MVP 范围与迭代路线图 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a681c78158fa7cb91f2840) + +## MVP 范围（当前阶段） + +### 包含功能 + +- 目标树管理（增删改、层级展示、内联编辑） +- 每日 1-10 分复盘 + 文字反思 +- AI 教练自动点评（基于目标树 + 历史复盘） +- AI 对话教练（随时提问） +- 历史复盘列表 + 评分趋势图 +- Artifact Storage 持久化 + +### 不包含 + +- 账号体系（MVP 阶段免登录；Phase 4+ 作为可选功能引入） +- 目标提醒通知 +- 导出分享 + +--- + +## 迭代路线图 + +### Phase 0 — MVP（已完成 ✅） + +| 功能 | 状态 | +|------|------| +| 目标树增删改查 | ✅ 已完成 | +| 5 层级树形结构 | ✅ 已完成 | +| 每日 1-10 分评分环 | ✅ 已完成 | +| AI 复盘点评 | ✅ 已完成 | +| AI 对话教练 | ✅ 已完成 | +| 历史复盘 + 柱状图 | ✅ 已完成 | +| Artifact Storage 持久化 | ✅ 已完成 | +| 金色深色视觉风格 | ✅ 已完成 | + +### Phase 1 — 提升体验 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| **每周复盘模块**（本周趋势 + 总结 + AI 周报建议） | 待开发 | P1 | +| 目标完成度 checkbox | 待开发 | P1 | +| 目标提要展示（hover） | 待开发 | P1 | +| 每周目标自动归档 | 待开发 | P1 | +| AI 主动提示（连续漏记 2 天 / 连续低分） | 待开发 | P1 | + +### Phase 2 — PWA 验证（跨平台第一步） + +> 策略：先以 PWA 形式让用户在手机上使用，验证产品市场价值，再决定是否投入原生打包。 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| 手机端响应式布局优化 | 待开发 | P2 | +| PWA manifest（可添加到主屏幕） | 待开发 | P2 | +| Service Worker 离线缓存 | 待开发 | P2 | +| **初始化模版**（通用模版 + 6 类人生方向模版） | 待开发 | P2 | +| 目标树导出图片 | 待开发 | P2 | +| 目标完成年度总结 | 待开发 | P2 | + +**验证指标：** 用户留存率、复盘频率、AI 功能使用率 — 达标后进入 Phase 3。 + +### Phase 3 — Capacitor 原生打包（市场验证通过后） + +> 触发条件：Phase 2 验证产品有市场价值。替换 Artifact Storage API → SQLite，引入 Vite 构建工具。 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| 引入 Vite 构建工具 | 待开发 | P3 | +| 存储迁移（localStorage → SQLite） | 待开发 | P3 | +| Capacitor 接入 + Android APK 打包 | 待开发 | P3 | +| iOS IPA 打包（需 Mac + 开发者账号） | 待开发 | P3 | +| 上架 Google Play / App Store | 待开发 | P3 | + +### Phase 4 — 账号体系 + 云同步（功能稳定后） + +> 触发条件：核心功能稳定、有稳定用户基础后引入。账号是后续会员收费的前置条件。 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| 用户注册 / 登录（邮箱 或 Google/Apple 一键登录） | 待开发 | P4 | +| 服务端数据存储与云同步 | 待开发 | P4 | +| 游客数据迁移到账号（首次登录合并） | 待开发 | P4 | +| AI 调用迁移至服务端（保护 API Key） | 待开发 | P4 | +| 多设备数据同步 | 待开发 | P4 | + +### Phase 5 — 会员收费 + +> 触发条件：有登录用户基础，账号体系稳定后启动。 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| 免费 / 付费功能分层设计 | 待开发 | P5 | +| 会员订阅（月付 / 年付） | 待开发 | P5 | +| 付费功能（更多 AI 对话次数、高级分析报告、**精品行业模版库**） | 待开发 | P5 | +| 支付接入（支付宝 / 微信支付 / Stripe） | 待开发 | P5 | + +### Phase 6 — 社交 / 高级 + +| 功能 | 状态 | 优先级 | +|------|------|-------| +| 目标拖拽排序 | 待开发 | P6 | +| 目标分享卡片 | 待开发 | P6 | +| 多用户 / 好友查看 | 待开发 | P6 | + +--- + +## 里程碑 + +| 时间 | 里程碑 | +|------|-------| +| 2026-05-24 | MVP 完成，包含目标树 + 复盘 + AI 教练 | +| Phase 1 | 完善体验：checkbox、主动提示、目标孵化 | +| Phase 2 | PWA 上线，验证市场需求与用户留存 | +| Phase 3 | 市场验证通过，Capacitor 打包 APK，上架应用商店 | +| Phase 4 | 引入账号体系 + 云同步，沉淀用户数据，为收费做准备 | +| Phase 5 | 开启会员订阅，功能分层，接入支付 | +| Phase 6 | 社交分享功能 | + +--- + +## 当前已交付 Artifact + +- 文件：`life-goals.jsx` +- 框架：React JSX +- 存储：Artifact Storage API + localStorage 双备份 +- AI：Anthropic claude-sonnet-4-20250514 diff --git a/docs/06-测试计划/验收标准与测试用例.md b/docs/06-测试计划/验收标准与测试用例.md new file mode 100644 index 0000000..a3d90dd --- /dev/null +++ b/docs/06-测试计划/验收标准与测试用例.md @@ -0,0 +1,47 @@ +# ✅ 测试计划 — 验收标准与测试用例 + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a68195a725d1a9eb00ebe4) + +## 验收标准 + +### 目标树模块 + +| # | 测试用例 | 预期结果 | +|---|---------|---------| +| 1 | 创建根节点并编辑文字 | 文字即时保存 | +| 2 | 点击"＋"添加子目标 | 层级自动推断为下一级 | +| 3 | 删除带子节点的年度目标 | 子树一并删除 | +| 4 | 折叠年度目标子树 | 子节点隐藏 | +| 5 | 层级颜色是否匹配规范 | 金色=人生，橙=年，蓝=月，绿=周，紫=日 | +| 6 | 刷新页面后树结构依然存在 | Storage 持久化有效 | +| 7 | 3 分钟内建立 5+ 节点的树 | 流畅度测试 | + +### 每日复盘模块 + +| # | 测试用例 | 预期结果 | +|---|---------|---------| +| 1 | 点击评分 8，输入反思，提交 | 3 秒内返回 AI 点评 | +| 2 | 评分 3 分的颜色 | 圆环显示红色 | +| 3 | 评分 6 分的颜色 | 圆环显示黄色 | +| 4 | 评分 9 分的颜色 | 圆环显示绿色 | +| 5 | 已提交时再次进入复盘 Tab | 显示已保存内容，无法重复提交 | +| 6 | 历史 Tab 显示连续 7 天记录 | 柱状图正确渲染 | + +### AI 教练模块 + +| # | 测试用例 | 预期结果 | +|---|---------|---------| +| 1 | 问"我的目标之间有没有冲突？" | AI 应引用目标树内容作答 | +| 2 | 问"帮我把月目标拆解成具体行动" | AI 返回可执行行动清单 | +| 3 | 多轮对话后 AI 能否记住上文 | 同一会话内上下文连贯 | + +--- + +## AI 点评质量标准 + +AI 点评需要同时达到： + +- ✅ 指出今天行动与哪个目标最对齐 / 最偏离 +- ✅ 给出明天可立即执行的建议（1 个具体行动） +- ✅ 不超过 150 字 +- ✅ 语气真诚干练，不泛泛鼓励 diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md new file mode 100644 index 0000000..c39b267 --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,67 @@ +# 📊 项目进度总览 + +> 最后更新：2026-05-24 +> 当前阶段：**Phase 1 待开发** + +--- + +## 功能状态一览 + +| 功能 | 阶段 | 状态 | 备注 | +|------|------|------|------| +| 目标树增删改查 | Phase 0 | ✅ 完成 | | +| 5 层级树形结构 | Phase 0 | ✅ 完成 | | +| 每日评分环（1-10 分） | Phase 0 | ✅ 完成 | | +| 每日感受 + 文字记录 | Phase 0 | ✅ 完成 | | +| AI 复盘点评 | Phase 0 | ✅ 完成 | | +| AI 对话教练 | Phase 0 | ✅ 完成 | | +| 历史复盘 + 柱状图 | Phase 0 | ✅ 完成 | | +| 漏打卡容错 | Phase 0 | ✅ 完成 | 空白显示，不报错 | +| 金色深色视觉风格 | Phase 0 | ✅ 完成 | | +| **每周复盘模块** | Phase 1 | 📋 待开发 | 本周趋势 + AI 周报 | +| 目标完成度 checkbox | Phase 1 | 📋 待开发 | | +| 目标提要展示（hover） | Phase 1 | 📋 待开发 | | +| AI 主动提示（连续漏记/低分） | Phase 1 | 📋 待开发 | | +| 手机端响应式优化 | Phase 2 | 📋 待开发 | | +| PWA（可添加到主屏幕） | Phase 2 | 📋 待开发 | | +| Service Worker 离线缓存 | Phase 2 | 📋 待开发 | | +| 初始化模版（通用 + 6 类方向） | Phase 2 | 📋 待开发 | 外部用户上线时 | +| 目标树导出图片 | Phase 2 | 📋 待开发 | | +| Vite 构建工具引入 | Phase 3 | 📋 待开发 | | +| 存储迁移（localStorage → SQLite） | Phase 3 | 📋 待开发 | | +| Capacitor Android APK | Phase 3 | 📋 待开发 | | +| Capacitor iOS IPA | Phase 3 | 📋 待开发 | 需 Mac + 开发者账号 | +| 账号注册 / 登录 | Phase 4 | 📋 待开发 | 功能稳定后启动 | +| 云同步 + 多设备 | Phase 4 | 📋 待开发 | | +| AI 调用迁移至服务端 | Phase 4 | 📋 待开发 | 保护 API Key | +| 会员订阅（月付 / 年付） | Phase 5 | 📋 待开发 | 有用户基础后 | +| 支付接入 | Phase 5 | 📋 待开发 | | +| 精品行业模版库（付费） | Phase 5 | 📋 待开发 | | +| 目标分享卡片 | Phase 6 | 📋 待开发 | | +| 多用户 / 好友查看 | Phase 6 | 📋 待开发 | | + +--- + +## 状态标签说明 + +| 标签 | 含义 | +|------|------| +| ✅ 完成 | 已开发并验证 | +| 🚧 开发中 | 当前正在开发 | +| 📋 待开发 | 已规划，未启动 | +| ⏸️ 暂缓 | 暂时搁置 | +| ❌ 取消 | 已决定不做 | + +--- + +## 里程碑 + +| 里程碑 | 目标 | 状态 | +|--------|------|------| +| Phase 0 MVP | 目标树 + 每日复盘 + AI 教练 | ✅ 2026-05-24 完成 | +| Phase 1 | 每周复盘 + 体验提升 | 📋 待开发 | +| Phase 2 | PWA 上线，验证市场需求 | 📋 待开发 | +| Phase 3 | Capacitor 打包 APK，上架应用商店 | 📋 待开发 | +| Phase 4 | 账号体系 + 云同步 | 📋 待开发 | +| Phase 5 | 会员订阅，接入支付 | 📋 待开发 | +| Phase 6 | 社交分享功能 | 📋 待开发 | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4df6515 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# 🧭 人生目标 App — 项目文档 + +> 一款帮助用户管理人生目标树、每日复盘并通过 AI 教练保持方向感的个人成长应用。 + +## 文档目录 + +### 快速入口 +| 文档 | 用途 | +|------|------| +| [PROGRESS.md](./PROGRESS.md) | 📊 所有功能当前状态，**最常看** | +| [decisions/](./decisions/) | 📒 重要决策的背景和原因（ADR） | + +### 完整文档 +| # | 阶段 | 文档 | +|---|------|------| +| 01 | 需求收集 | [用户访谈与原始需求](./01-需求收集/用户访谈与原始需求.md) | +| 02 | 需求分析 | [功能优先级与边界](./02-需求分析/功能优先级与边界.md) | +| 03 | 架构设计 | [技术选型与数据结构](./03-架构设计/技术选型与数据结构.md) | +| 04 | UI 设计 | [视觉规范与交互流程](./04-UI设计/视觉规范与交互流程.md) | +| 05 | 开发计划 | [MVP 范围与迭代路线图](./05-开发计划/MVP范围与迭代路线图.md) | +| 06 | 测试计划 | [验收标准与测试用例](./06-测试计划/验收标准与测试用例.md) | + +### 决策记录（ADR） +| 编号 | 决策 | +|------|------| +| [ADR-001](./decisions/001-monorepo单仓库结构.md) | Monorepo 单仓库管理 app / server / docs | +| [ADR-002](./decisions/002-PWA优先验证市场.md) | PWA 优先验证市场，再做 Capacitor 原生打包 | +| [ADR-003](./decisions/003-本地优先免登录.md) | 本地优先存储，账号为可选功能 | +| [ADR-004](./decisions/004-初始化模版系统.md) | 提供初始化模版降低新用户门槛 | + +--- + +**创建日期：** 2026-05-24 +**当前阶段：** MVP 开发完成 +**技术栈：** React · Claude AI API · Artifact Storage + +> 来源：[Notion 原始文档](https://www.notion.so/36a401dc38a681f3975ccebf80a49d27) diff --git a/docs/decisions/001-monorepo单仓库结构.md b/docs/decisions/001-monorepo单仓库结构.md new file mode 100644 index 0000000..b3f7125 --- /dev/null +++ b/docs/decisions/001-monorepo单仓库结构.md @@ -0,0 +1,33 @@ +# ADR-001 采用 Monorepo 单仓库管理 app / server / docs + +**状态：** 已采纳 ✅ +**日期：** 2026-05-24 + +--- + +## 背景 + +项目包含前端（app）、后端（server，Phase 4 启动）、文档（docs）三部分，需要决定是用一个 git 仓库还是多个仓库管理。 + +## 决策 + +所有代码和文档放在同一个 git 仓库，采用 monorepo 结构： + +``` +life_goals/ +├── app/ +├── server/ +└── docs/ +``` + +## 原因 + +- **小团队 / 个人项目**：管理一个仓库比同步多个仓库负担小得多 +- **前后端强耦合**：同一个功能（如账号体系）需要同时改 app 和 server，monorepo 可以一个 commit 完成 +- **AI 协作友好**：AI 在同一仓库内能同时看到代码和文档，理解更准确 +- **文档即代码**：需求变更和代码变更在同一条时间线，不会出现文档滞后 + +## 影响 + +- `server/` 目前为占位目录，Phase 4 再填充内容 +- 如未来 server 需要被多个产品复用，再考虑拆出独立仓库 diff --git a/docs/decisions/002-PWA优先验证市场.md b/docs/decisions/002-PWA优先验证市场.md new file mode 100644 index 0000000..4cebd53 --- /dev/null +++ b/docs/decisions/002-PWA优先验证市场.md @@ -0,0 +1,27 @@ +# ADR-002 PWA 优先验证市场，再做 Capacitor 原生打包 + +**状态：** 已采纳 ✅ +**日期：** 2026-05-24 + +--- + +## 背景 + +App 需要在手机上使用，面临两个选择：直接打包成原生 App，或先做 PWA 验证需求。 + +## 决策 + +**Phase 2 先做 PWA**，让用户在手机浏览器「添加到主屏幕」使用。确认产品有市场价值后，**Phase 3 再用 Capacitor 打包** Android APK / iOS IPA。 + +## 原因 + +- PWA 只需加 `manifest.json` + Service Worker，改动极小 +- Capacitor 打包需要引入 Vite、替换存储方案、配置 Android Studio / Xcode，成本高 +- 先用 PWA 以最低成本验证：用户留存率、复盘频率、AI 功能使用率 +- 验证有价值后再投入打包成本，避免过早优化 + +## 影响 + +- Artifact Storage API 是 Claude 平台专属，PWA 独立部署后需替换为 localStorage +- iOS Safari 对 PWA 支持有限，是已知限制，PWA 阶段接受 +- Capacitor 打包触发条件：Phase 2 验证指标达标 diff --git a/docs/decisions/003-本地优先免登录.md b/docs/decisions/003-本地优先免登录.md new file mode 100644 index 0000000..8b6e132 --- /dev/null +++ b/docs/decisions/003-本地优先免登录.md @@ -0,0 +1,33 @@ +# ADR-003 本地优先存储，账号为可选功能 + +**状态：** 已采纳 ✅ +**日期：** 2026-05-24 + +--- + +## 背景 + +App 需要数据持久化，需要决定是否强制登录，以及何时引入账号体系。 + +## 决策 + +采用三阶段演进： + +| 阶段 | 登录 | 存储 | +|------|------|------| +| 开发调试期（当前） | 免登录 | 本地 | +| 用户增长期（Phase 2-3） | 可选注册 | 本地（默认）/ 服务端（登录后） | +| 商业化期（Phase 4+） | 登录必要 | 服务端 | + +## 原因 + +- **降低启动门槛**：打开即用，无需注册，用户转化率更高 +- **先验证价值**：让用户先体验到产品价值，再引导注册，信任成本低 +- **账号是收费前置**：Phase 5 会员收费需要账号体系，Phase 4 作为前置建设 +- **参考案例**：Obsidian、Bear 等 Local-First 应用均采用此模式 + +## 影响 + +- 游客首次登录时需处理本地数据迁移（按时间戳合并为推荐策略） +- 引入后端时，Anthropic API 调用需同步迁移至服务端（保护 API Key） +- 换设备 / 清缓存会丢失游客数据，这是已知限制，通过引导注册解决 diff --git a/docs/decisions/004-初始化模版系统.md b/docs/decisions/004-初始化模版系统.md new file mode 100644 index 0000000..aed7da3 --- /dev/null +++ b/docs/decisions/004-初始化模版系统.md @@ -0,0 +1,33 @@ +# ADR-004 提供初始化模版降低新用户门槛 + +**状态：** 已采纳 ✅ +**日期：** 2026-05-24 + +--- + +## 背景 + +外部用户首次打开 App 时，面对空白目标树不知道如何填写，容易流失。 + +## 决策 + +**Phase 2 PWA 上线时**引入初始化模版系统： + +- **通用模版**：纯结构 + 占位符，适合所有人 +- **6 类人生方向模版**：职业发展 / 创业副业 / 学习提升 / 健康生活 / 家庭生活 / 自由探索 +- 用户也可选择「空白开始」 + +**Phase 5 会员阶段**提供精品行业模版库作为付费内容。 + +## 原因 + +- 新用户看到结构示例后能快速理解产品价值 +- 模版是起点，用户可自由编辑，不构成约束 +- 自用阶段（当前）无需此功能，Phase 2 面向外部用户时引入 +- 免费模版 vs 付费精品模版形成分层，支撑商业化 + +## 影响 + +- Phase 2 开发时需新增「欢迎页 + 模版选择」流程 +- 模版内容需要打磨文案，覆盖主流人群 +- 精品模版定价和内容在 Phase 5 决策 diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..869eca6 --- /dev/null +++ b/server/README.md @@ -0,0 +1,35 @@ +# server — 后端 API + +> 人生目标 App 的后端服务，**Phase 4（账号体系）阶段启动开发**，当前目录为占位。 + +## 当前状态 + +📋 **待启动** — Phase 4 触发条件：核心功能稳定 + 有稳定用户基础。 + +## 负责的功能（Phase 4+） + +- 用户注册 / 登录（邮箱 + Google / Apple 一键登录） +- 数据云端存储与多设备同步 +- **Anthropic API 代理**（保护 API Key，替代前端直连） +- 游客本地数据迁移至账号 +- Phase 5：会员订阅 + 支付接入 + +## 技术栈（待定，Phase 4 决策） + +| 项目 | 候选 | +|------|------| +| 运行时 | Node.js | +| 框架 | Express / Fastify / Hono | +| 数据库 | PostgreSQL / Supabase | +| 认证 | JWT + OAuth2 | +| 部署 | 待定 | + +## 启动方式（开发后） + +```bash +cd server +npm install +npm run dev +``` + +> 详见 [架构设计文档](../docs/03-架构设计/技术选型与数据结构.md)