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

> 来源：[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 调用走服务端代理
```