adminandClaude Sonnet 4.6
a1561c7d43
- 建立 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>
208 lines
6.2 KiB
Markdown
208 lines
6.2 KiB
Markdown
# 🏗️ 架构设计 — 技术选型与数据结构
|
||
|
||
> 来源：[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 调用走服务端代理
|
||
```
|