Files

T

adminandClaude Sonnet 4.6 a1561c7d43 chore: 初始化仓库结构

- 建立 monorepo 结构：app/ + server/ + docs/
- 纳入全部需求/架构/开发计划文档
- 新增 docs/PROGRESS.md 功能状态总览
- 新增 docs/decisions/ ADR 决策记录（001-004）
- 新增根目录 README.md 含 AI 阅读指引
- 新增 .gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-24 16:39:16 +08:00

6.2 KiB

Raw Permalink Blame History

🏗️ 架构设计 — 技术选型与数据结构

来源：Notion 原始文档

技术选型

维度	选择	理由
框架	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`

{
  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`

{
  "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 调用走服务端代理

6.2 KiB Raw Permalink Blame History Unescape Escape