架构与技术栈

深入理解 TodoHeap 的系统架构与技术选择。

系统架构

三层架构

┌─────────────────────────────────────┐
│         前端层 (Presentation)        │
│    Vue 3 + Vite + TailwindCSS       │
│  ├─ UI 组件                         │
│  ├─ 状态管理 (Pinia)               │
│  ├─ 路由 (Vue Router)              │
│  └─ 本地存储 (IndexedDB)           │
└─────────────────────────────────────┘
          ↕ HTTP / WebSocket
┌─────────────────────────────────────┐
│       后端计算层 (Compute)          │
│  Supabase Edge Functions (Deno)    │
│  ├─ AI 调用与处理                   │
│  ├─ 业务逻辑                        │
│  ├─ 数据验证与转换                  │
│  └─ 权限检查 (JWT)                  │
└─────────────────────────────────────┘
          ↕ PostgreSQL Wire
┌─────────────────────────────────────┐
│       数据存储层 (Data)             │
│  Supabase PostgreSQL                │
│  ├─ todos 表                        │
│  ├─ user_settings 表                │
│  ├─ 权限政策 (RLS)                  │
│  └─ 实时同步 (Realtime)            │
└─────────────────────────────────────┘

数据流

用户操作 (UI)
    ↓ 本地验证
    ↓ Pinia 状态更新
    ↓ 乐观更新 UI
    ↓ 异步请求后端
    ↓ Edge Function 处理
    ↓ 数据库更新
    ↓ Realtime 推送更新
    ↓ 前端 Store 同步
    ↓ UI 重新渲染

前端架构

技术栈

组件	技术	用途
框架	Vue 3	响应式 UI 框架
构建	Vite 7.2+	极速开发服务、优化打包
路由	Vue Router 4	SPA 路由管理
状态管理	Pinia 3.0+	全局状态 (Composition 风格)
样式	TailwindCSS 4.1+	原子 CSS 框架
UI 组件库	shadcn-vue	精美组件库
编辑器	Milkdown 7.17+	Markdown 编辑
可视化	simple-mind-map	思维导图
日期选择	vue-datepicker-next	日期时间选择
HTTP 客户端	Supabase JS SDK	API 调用
本地存储	IndexedDB	离线数据存储

项目结构

frontend/src/
├── components/
│   ├── AITaskInput.vue          # AI 输入组件
│   ├── BreakdownStatusCard.vue  # 分解状态卡片
│   ├── TodoListItem.vue         # 任务条目
│   ├── TodoDetailEditor.vue     # 详情编辑器
│   ├── MindMapWrapper.vue       # 思维导图包装器
│   ├── LeftSidebar.vue          # 左侧边栏
│   └── SyncStatusIndicator.vue  # 同步状态指示
│
├── pages/
│   ├── Home.vue                 # 首页
│   ├── Login.vue                # 登录页
│   ├── Todo.vue                 # 主任务页
│   ├── ResetPassword.vue        # 重置密码
│   ├── 404.vue                  # 404 页
│   └── todo/
│       ├── TodoList.vue         # 列表视图
│       ├── TodoTree.vue         # 树视图
│       ├── TodoHeap.vue         # 堆视图
│       ├── Trash.vue            # 垃圾箱
│       └── Settings.vue         # 设置页
│
├── stores/
│   ├── auth.ts                  # 认证状态
│   ├── todos.js                 # 任务主状态
│   ├── todos.optimistic.js      # 乐观更新逻辑
│   ├── todos.realtime.js        # Realtime 同步
│   ├── todos.rollback.js        # 回滚处理
│   ├── todos.breakdown.js       # 分解状态
│   ├── syncQueue.js             # 同步队列管理
│   └── *.test.js                # 单元测试
│
├── lib/
│   ├── supabase.ts              # Supabase 初始化
│   └── userSettings.js          # 用户设置 API
│
├── utils/
│   ├── detailPanelContext.js    # 详情面板上下文
│   ├── handleAuthCallback.ts    # 认证回调处理
│   └── priorityCalculator.js    # 优先级计算器
│
├── router/
│   └── index.ts                 # 路由配置
│
├── App.vue                       # 根组件
├── main.ts                       # 应用入口
├── style.css                     # 全局样式
└── shims-vue.d.ts               # Vue 类型声明

状态管理 (Pinia)

核心状态模块：

模块	职责
auth	用户认证状态、登录登出
todos	任务列表、垃圾箱、详情
todos.optimistic	乐观更新、本地修改
todos.realtime	Realtime 监听、实时同步
todos.rollback	失败回滚、状态恢复
todos.breakdown	AI 分解进度、子任务
syncQueue	同步队列、离线操作缓存

关键特性

乐观更新

操作立即反映在 UI 中，同时后台上传：

javascript

// 用户删除任务
deleteTodo(id)
  ├─ UI 立即移出任务
  ├─ 加入同步队列
  ├─ 异步发送删除请求
  └─ 成功 ✓ / 失败 → 回滚

离线支持

网络中断时操作暂存本地，网络恢复后自动同步：

javascript

网络中断 → 切换到离线模式
  ├─ 所有改动保存在 IndexedDB
  ├─ 同步队列持久化
  └─ UI 提示离线状态

网络恢复 → 自动同步
  ├─ 读取队列中的操作
  ├─ 按序上传
  └─ 冲突检测与合并

实时同步 (Realtime)

多个客户端间实时同步数据：

javascript

用户 A 修改任务 → Supabase Realtime
  ↓
用户 B 客户端立即收到更新
  ↓
自动更新本地状态与 UI

后端架构

Edge Functions

为什么用 Edge Functions？

无需管理服务器
自动扩展
接近用户地理位置（低延迟）
与数据库紧密集成
支持 Deno（现代化、安全、快速）

Edge Function 三大功能

1. breakdown_task - 任务分解

请求：
  ├─ todosTree: 完整任务树
  ├─ selectedNodeId: 要分解的任务 ID
  └─ query: 分解指令（可选）

处理流程：
  ├─ 构建 Prompt（任务上下文 + 用户指令）
  ├─ 调用 AI 大模型
  ├─ 流式解析响应
  └─ 即时返回子任务

响应：
  ├─ SSE 流式数据
  ├─ 每个子任务单独推送
  └─ done 事件表示完成

2. analyze_task_create - 任务分析与入库

请求：
  ├─ query: 任务描述
  └─ parentId: 父任务 ID（可选）

处理流程：
  ├─ 使用 Tool Calling 让 AI 直接生成任务
  ├─ AI 调用 create_todo 工具
  ├─ 直接在 Function 中执行数据库插入
  └─ 返回创建结果

响应：
  ├─ { success, createdCount, tasks }
  └─ 任务立即入库可用

3. optimize_tasks - 任务优化

请求：
  ├─ todos: 所有待优化任务
  └─ strategy: 优化策略（日期重排/优先级调整）

处理流程：
  ├─ AI 分析任务间依赖关系
  ├─ 根据难度、截止日期计算最优顺序
  ├─ 生成优化方案
  └─ 返回新的优先级分配

响应：
  ├─ { success, optimizedTodos }
  └─ 前端更新所有任务优先级

技术栈

组件	技术	用途
运行时	Deno 2.0+	安全、现代的 JavaScript 运行时
语言	TypeScript	类型安全的开发体验
框架	无（标准库）	极轻量化
AI	OpenAI API	调用大模型
认证	JWT	验证用户身份
日志	标准输出	Supabase 自动收集

Edge Function 项目结构

supabase/functions/
├── _shared/
│   └── cors.ts          # 跨域配置
│
├── breakdown_task/
│   ├── index.ts         # 任务分解主逻辑
│   └── deno.json        # Deno 配置（导入、权限）
│
├── analyze_task_create/
│   ├── index.ts         # 任务分析与创建
│   └── deno.json
│
└── optimize_tasks/
    ├── index.ts         # 任务优化
    └── deno.json

数据存储架构

数据库设计

todos 表

sql

CREATE TABLE todos (
  id BIGINT PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  title TEXT NOT NULL,
  status TEXT DEFAULT 'todo',      -- todo | doing | done | deleted
  priority INT DEFAULT 1,           -- 0:低 | 1:中 | 2:高
  difficulty INT,                  -- 简单|中等|困难
  deadline TIMESTAMP,
  parent_id BIGINT REFERENCES todos(id),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  deleted_at TIMESTAMP,
  description TEXT
);

user_settings 表

sql

CREATE TABLE user_settings (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  theme TEXT DEFAULT 'system',     -- light | dark | system
  language TEXT DEFAULT 'zh',
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

行级安全 (RLS)

所有表启用 RLS，确保用户只能访问自己的数据：

sql

-- todos 表 RLS 策略
ALTER TABLE todos ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can see own todos"
  ON todos
  FOR SELECT
  USING (auth.uid() = user_id);

CREATE POLICY "Users can create own todos"
  ON todos
  FOR INSERT
  WITH CHECK (auth.uid() = user_id);

Realtime 配置

启用 Realtime 以支持多设备实时同步：

sql

ALTER PUBLICATION supabase_realtime ADD TABLE todos;

前端监听：

javascript

// 监听任务表变更
const channel = supabase
  .channel('todos')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'todos' },
    (payload) => {
      // 处理变更
      updateLocalState(payload);
    }
  )
  .subscribe();

数据流示意

创建任务流程

用户输入 → 前端验证 → Pinia 更新 → UI 渲染
                      ↓ 异步
                  后端接收
                      ↓
                  数据库保存
                      ↓
                  Realtime 推送
                      ↓
                  其他客户端更新

AI 分解流程

用户选择任务 → 前端构建请求
    ↓
Edge Function 接收
    ↓
构建 AI Prompt
  ↓
调用 AI API
  ↓ SSE 流式返回
前端解析并渲染
  ↓
用户确认
  ↓
提交创建请求
  ↓
数据库保存

需求概览（已合并）

下面为原 02.需求文档.md 的核心要点，已并入本页面以便集中维护：

开发指导原则

实现顺序：功能优先 → 安全其次 → 性能最后

功能优先：先实现可以工作的最直接方案
安全其次：完成功能后补充错误处理与安全控制
性能最后：根据用户反馈再优化性能

功能需求要点

支持多级子任务（父子层级）
基础 CRUD：创建、编辑、删除任务
支持截止日期、优先级与难度字段
三大 AI 能力：
- AI 任务输入（自然语言）
- AI 任务分解（细化到子任务/日程）
- AI 任务优化（优先级与日期调整）

附加与体验功能

任务堆视图（优先级驱动）
任务进度管理与报告
思维导图式的任务管理视图

典型使用案例

日常任务管理：用户输入目标，系统分解为执行步骤
学习计划场景：按难度与天数拆分学习任务
全局优化场景：对用户全部任务进行优先级/日期重排

（原需求文档已合并，故 02.需求文档.md 将被移除）

关键设计决策

决策	选择	原因
前端框架	Vue 3	易学、高效、中文社区大
构建工具	Vite	极速开发体验、原生 ESM 支持
状态管理	Pinia	比 Vuex 简洁、Composition API 友好
样式方案	TailwindCSS	快速开发、一致设计、文件体积小
后端计算	Edge Functions	无服务器、自动扩展、低成本
运行时	Deno	类型安全、快速、安全隔离
数据库	PostgreSQL	功能完整、可靠性高、RLS 支持
认证	Supabase Auth	开箱即用、多策略支持
实时同步	WebSocket	低延迟、双向通信

性能考虑

前端优化

✅ 代码分割：按路由和功能分割
✅ 懒加载：组件、库按需加载
✅ 缓存：IndexedDB 离线缓存
✅ 虚拟滚动：大列表性能优化

后端优化

✅ 连接池：数据库连接复用
✅ 查询优化：合理使用索引
✅ 缓存层：边缘节点地理分布

数据库优化

✅ 索引：user_id、deadline 等关键字段
✅ 分区：考虑按用户或日期分区
✅ 查询分析：定期检查慢查询

下一步

理解了架构后：

阅读本页的 需求概览（已合并） 部分以了解功能需求
阅读开发流程与任务学习参与方式
深入特定功能的技术文档

架构与技术栈 ​

系统架构 ​

三层架构 ​

数据流 ​

前端架构 ​

技术栈 ​

项目结构 ​

状态管理 (Pinia) ​

关键特性 ​

乐观更新 ​

离线支持 ​

实时同步 (Realtime) ​

后端架构 ​

Edge Functions ​

Edge Function 三大功能 ​

1. breakdown_task - 任务分解 ​

2. analyze_task_create - 任务分析与入库 ​

3. optimize_tasks - 任务优化 ​

技术栈 ​

Edge Function 项目结构 ​

数据存储架构 ​

数据库设计 ​

todos 表 ​

user_settings 表 ​

行级安全 (RLS) ​

Realtime 配置 ​

数据流示意 ​

创建任务流程 ​

AI 分解流程 ​

需求概览（已合并） ​

开发指导原则 ​

功能需求要点 ​

附加与体验功能 ​

典型使用案例 ​

关键设计决策 ​

性能考虑 ​

前端优化 ​

后端优化 ​

数据库优化 ​

下一步 ​

架构与技术栈

系统架构

三层架构

数据流

前端架构

技术栈

项目结构

状态管理 (Pinia)

关键特性

乐观更新

离线支持

实时同步 (Realtime)

后端架构

Edge Functions

Edge Function 三大功能

1. breakdown_task - 任务分解

2. analyze_task_create - 任务分析与入库

3. optimize_tasks - 任务优化

技术栈

Edge Function 项目结构

数据存储架构

数据库设计

todos 表

user_settings 表

行级安全 (RLS)

Realtime 配置

数据流示意

创建任务流程

AI 分解流程

需求概览（已合并）

开发指导原则

功能需求要点

附加与体验功能

典型使用案例

关键设计决策

性能考虑

前端优化

后端优化

数据库优化

下一步