11 · 技术设计文档

文档库编号 11 · 地图 README.md
目标：数据模型、沉淀与调度排程、API、多端同步。
产品：01-overview.md / 08-prd.md
前端边界：09-frontend-architecture.md
原则：MVP 优先；调度级排程，非日历套件；Eisenhower 仅内部字段。

1. 技术选型

1.1 前端

平台	技术	说明
桌面	Tauri + React	Tauri 比 Electron 包体更小，启动更快，适合轻量悬浮胶囊
移动端	微信小程序 + 微信小程序后台服务（如腾讯云）	微信生态是核心入口，小程序最轻
浏览器	Web Extension (Manifest V3)	Chrome/Edge/Firefox 扩展，支持页面捕获
后台管理	React + Web	轻量 Web 管理台

1.2 后端

组件	技术	说明
API 服务	Go/Gin 或 Node.js/Fastify	高性能、少依赖
数据库	PostgreSQL（主库）+ Redis（缓存）	ACID + 事务保障状态一致性
搜索	PostgreSQL Full-text Search	碎片和线程全文检索
任务队列	Redis Streams 或 Sidekiq	异步处理沉淀引擎
通知	Firebase Cloud Messaging (FCM) + 微信服务号模板消息	移动端和微信通知
文件存储	七牛云 / 阿里云 OSS	图片、语音等原始碎片
LLM	OpenAI API / 讯飞星火 / 智谱 GLM	沉淀引擎的语义理解层

1.3 基础设施

组件	技术	说明
容器化	Docker + Kubernetes（生产）	容器化部署，便于扩展
CI/CD	GitHub Actions	自动构建、测试、部署
监控	Prometheus + Grafana	服务端性能和业务指标监控
日志	ELK (Elasticsearch + Logstash + Kibana)	集中式日志收集和分析
反向代理	Nginx	负载均衡、SSL 终止

2. 数据模型

2.1 ER 图（概念）

1
User (用户)
2
  ├── Thread (线程) [1:N]
3
  ├── Fragment (碎片) [1:N]
4
  ├── Preference (偏好) [1:N]
5
  └── Notification (通知) [1:N]
6

7
Thread (线程)
8
  ├── Fragment (碎片) [1:N]
9
  └── TodoItem (任务项) [1:N]
10

11
Fragment (碎片)
12
  ├── Attachment (附件) [1:N]
13
  └── StateHistory (状态历史) [1:N]
14

15
TodoItem (任务项)
16
  ├── StateHistory (状态历史) [1:N]
17
  └── Notification (通知) [1:N]

2.2 核心表结构

2.2.1 用户表 (users)

字段	类型	说明	约束
id	UUID	用户唯一标识	PK
wechat_openid	VARCHAR(64)	微信 OpenID	UNIQUE
email	VARCHAR(255)	邮箱	UNIQUE, NULLABLE
nickname	VARCHAR(100)	昵称
avatar_url	VARCHAR(500)	头像 URL
plan_type	ENUM	免费/个人/创作者/学生	默认’免费’
daily_fragment_limit	INT	每日碎片上限	默认50
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间
deleted_at	TIMESTAMP	软删除	NULLABLE

2.2.2 线程表 (threads)

字段	类型	说明	约束
id	UUID	线程唯一标识	PK
user_id	UUID	所属用户	FK -> users.id
title	VARCHAR(200)	线程标题（自动生成或用户命名）
summary	TEXT	线程摘要（AI 生成）
status	ENUM	active/archived	默认’active’
priority	INT	优先程度 1-5	默认3
thread_preferences	JSONB	线程级偏好（客户语气、项目风格等）
last_fragment_at	TIMESTAMP	最新碎片时间
created_at	TIMESTAMP	创建时间
archived_at	TIMESTAMP	归档时间	NULLABLE

2.2.3 碎片表 (fragments)

字段	类型	说明	约束
id	UUID	碎片唯一标识	PK
user_id	UUID	所属用户	FK -> users.id
thread_id	UUID	所属线程	FK -> threads.id, NULLABLE
source	ENUM	desktop/mobile/browser/wechat/siri
source_detail	VARCHAR(500)	来源详情（如微信聊天对象、浏览器URL）
content_type	ENUM	text/voice/image/link/screenshot
content_raw	TEXT	原始内容
content_processed	TEXT	处理后内容（如语音转文字、OCR结果）
content_embedding	VECTOR(384)	语义向量
state	ENUM	raw/next_step/waiting/merged/snoozed/frozen/pending/archived/done
confidence	FLOAT	智能体判断置信度 0-1	不对用户展示分数 UI
intent	VARCHAR(32)	意图：task/material/idea/waiting/noise
urgency	SMALLINT	内部 0–3 紧急启发	不暴露四象限 UI
importance	SMALLINT	内部 0–3 重要启发	不暴露四象限 UI
heuristic_quadrant	VARCHAR(16)	可选：do/schedule/delegate/eliminate	仅日志/调试
ai_analysis	JSONB	意图、情绪、reason 文案等
urgency_flags	JSONB	硬截止、承诺、敏感标记
reason	TEXT	用户可见一句解释
reviewed_at	TIMESTAMP	用户审阅时间	NULLABLE
expires_at	TIMESTAMP	稍后/冷冻的到期时间	NULLABLE
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间

2.2.4 任务项表 (todo_items)

字段	类型	说明	约束
id	UUID	任务唯一标识	PK
user_id	UUID	所属用户	FK -> users.id
thread_id	UUID	所属线程	FK -> threads.id
fragment_id	UUID	来源碎片	FK -> fragments.id
title	VARCHAR(200)	任务标题（AI生成）
action	VARCHAR(500)	端点化下一步动作描述
estimated_duration	INT	预估耗时（分钟）	默认15
due_at	TIMESTAMP	截止/再出现时间	NULLABLE
status	ENUM	pending/active/completed/snoozed
endpoint	ENUM	desktop/mobile/browser/wechat
attempt_count	INT	递回次数	默认0
last_notified_at	TIMESTAMP	最新通知时间	NULLABLE
completed_at	TIMESTAMP	完成时间	NULLABLE
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间

2.2.4b 递交调度表 (delivery_jobs)

调度级智能排程实体：不是日历事件表。

字段	类型	说明	约束
id	UUID	调度任务 ID	PK
user_id	UUID	用户	FK
todo_item_id	UUID	关联下一步	FK
scheduled_at	TIMESTAMP	计划递交时间
endpoint	ENUM	desktop/mobile/notification
priority_score	FLOAT	内部排序分（含 urgency×importance、偏好）	不对用户展示
wip_slot	BOOLEAN	是否占用当前唯一 WIP 位	同时 true ≤1 / 用户
suppress_until	TIMESTAMP	今天别推等抑制截止	NULLABLE
status	ENUM	queued/delivered/cancelled/suppressed
cancel_reason	TEXT	用户纠偏/过期等	NULLABLE
created_at	TIMESTAMP
updated_at	TIMESTAMP

约束：同一 user_id 在 status=delivered 且未完成的主动下一步，业务层强制 WIP=1（硬截止可例外并写 reason）。

2.2.5 通知表 (notifications)

字段	类型	说明	约束
id	UUID	通知唯一标识	PK
user_id	UUID	所属用户	FK -> users.id
todo_item_id	UUID	关联任务	FK -> todo_items.id, NULLABLE
type	ENUM	next_step/reminder/daily_digest/confirm
title	VARCHAR(200)	通知标题
body	TEXT	通知内容
action_payload	JSONB	可执行动作（点击通知后的行为）
send_at	TIMESTAMP	计划发送时间
sent_at	TIMESTAMP	实际发送时间	NULLABLE
read_at	TIMESTAMP	用户阅读时间	NULLABLE
action_taken	ENUM	dismissed/completed/snoozed/ignored	NULLABLE
created_at	TIMESTAMP	创建时间

2.2.6 偏好表 (preferences)

字段	类型	说明	约束
id	UUID	偏好唯一标识	PK
user_id	UUID	所属用户	FK -> users.id
scope	ENUM	global/user/thread
thread_id	UUID	线程级偏好时	FK -> threads.id, NULLABLE
key	VARCHAR(100)	偏好键
value	JSONB	偏好值（对象）
effective_from	TIMESTAMP	生效时间
effective_to	TIMESTAMP	失效时间	NULLABLE
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间

2.2.7 状态历史表 (state_histories)

字段	类型	说明	约束
id	UUID	历史记录唯一标识	PK
fragment_id	UUID	关联碎片	FK -> fragments.id
todo_item_id	UUID	关联任务	FK -> todo_items.id, NULLABLE
from_state	ENUM	原状态
to_state	ENUM	新状态
trigger	ENUM	auto/user/system
reason	TEXT	状态变更原因（AI生成）
metadata	JSONB	额外信息（如参与的 AI 模型、规则命中情况）
created_at	TIMESTAMP	创建时间

3. API 设计

3.1 认证

端点	方法	说明
`POST /auth/wechat`	微信登录	小程序/服务号获取 OpenID，返回 JWT
`POST /auth/refresh`	刷新 Token	延长 JWT 有效期
`DELETE /auth/logout`	退出登录	清除 Token

3.2 碎片捕获

端点	方法	说明	请求体	响应
`POST /fragments`	POST	创建碎片	`{content, source, source_detail, type}`	碎片对象 + 智能体判断结果
`GET /fragments`	GET	查询碎片列表	`?status=&thread_id=`	碎片列表
`GET /fragments/{id}`	GET	碎片详情	-	碎片对象 + 状态历史
`PUT /fragments/{id}`	PUT	用户纠偏	`{action, new_state, feedback}`	更新后碎片
`DELETE /fragments/{id}`	DELETE	删除碎片	-	软删除

3.3 线程管理

端点	方法	说明	请求体	响应
`GET /threads`	GET	线程列表	`?status=active&page=`	线程列表
`GET /threads/{id}`	GET	线程详情	-	线程 + 碎片 + 任务
`PUT /threads/{id}`	PUT	更新线程	`{title, summary, status}`	更新后线程
`GET /threads/{id}/fragments`	GET	线程下碎片	`?status=`	碎片列表

3.4 任务递回

端点	方法	说明	请求体	响应
`GET /todos/active`	GET	当前激活任务	-	最多1个下一步任务
`GET /todos`	GET	任务列表	`?status=&thread_id=`	任务列表
`PUT /todos/{id}/complete`	PUT	完成任务	-	更新后任务
`PUT /todos/{id}/snooze`	PUT	稍后提醒	`{duration: '1d'}`	更新后任务
`PUT /todos/{id}/breakdown`	PUT	拆小任务	-	新任务（更小粒度）
`GET /todos/daily`	GET	今日候选摘要（非日历）	-	统计 + 当前一步；非 time-block 网格

3.4b 调度

端点	方法	说明	请求体	响应
`GET /delivery/active`	GET	当前 WIP 递交	-	0–1 条
`POST /delivery/recompute`	POST	纠偏后重算调度	`{todo_id, action}`	新 job
`PUT /delivery/suppress`	PUT	今天别推等	`{scope, until}`	ok

禁止 MVP API：完整日历 CRUD、拖拽 time-block、四象限列表接口作为用户主路径。

3.5 复盘

端点	方法	说明	响应
`GET /daily/digest`	GET	晚间复盘数据	今日统计：接住/归并/冷冻/明天第一步
`GET /weekly/report`	GET	周报	本周趋势、减负效果

3.6 偏好

端点	方法	说明	请求体
`GET /preferences`	GET	当前用户偏好	-
`PUT /preferences`	PUT	更新偏好	`{scope, key, value}`
`DELETE /preferences/{key}`	DEL	恢复默认	-

3.7 通知

端点	方法	说明	请求体	响应
`GET /notifications`	GET	通知列表	`?unread_only=true`	通知列表
`PUT /notifications/{id}/read`	PUT	标记已读	-	-
`PUT /notifications/{id}/action`	PUT	执行通知动作	`{action: 'complete'}`	-

4. 系统架构

4.1 整体架构

1
+-------------------+     +-------------------+     +-------------------+
2
|   前端 (多端)      |  -> |   API Gateway     |  -> |   服务层           |
3
| 桌面/移动/浏览器   |     |  Nginx + Rate Limit |    |  Go/Gin           |
4
+-------------------+     +-------------------+     +-------------------+
5
                                                           |
6
                              +---------------------------+---------------------------+
7
                              |                                                       |
8
                              v                                                       v
9
                       +-------------------+                                 +-------------------+
10
                       |  业务服务          |                                 |  沉淀引擎         |
11
                       | - Fragment        |                                 | - 规则引擎        |
12
                       | - Thread          |                                 | - LLM 管道        |
13
                       | - TodoItem        |                                 | - 状态机          |
14
                       | - Notification    |                                 +-------------------+
15
                       | - Preference      |                                          |
16
                       +-------------------+                                          |
17
                              |                                                       |
18
                              v                                                       v
19
                       +-------------------+                                 +-------------------+
20
                       |  数据层            |                                 |  外部服务         |
21
                       | PostgreSQL        |                                 | - OpenAI/讯飞星火 |
22
                       | Redis             |                                 | - 微信 API        |
23
                       | 七牛云/OSS        |                                 | - FCM             |
24
                       +-------------------+                                 +-------------------+

4.2 沉淀引擎设计

核心流程：

1
闪念输入
2
  -> 预处理（文本、OCR、语音转写）
3
  -> 规则引擎（关键词、重复、明显截止）
4
  -> LLM 兜底（意图、线程、拆小）
5
  -> 内部 urgency × importance 启发（映射状态，非 UI）
6
  -> 状态机落点 + reason
7
  -> 若需行动：创建 todo_item 动作草案
8
  -> 写入 delivery_jobs（交给调度器）
9
  -> 异步持久化与日志

规则 vs LLM：

场景	规则引擎	LLM	触发
链接去重	URL 哈希	-	已存在
噪音归档	黑名单	-	命中
硬截止	日期/「截止」正则	语义确认	规则或低置信
情绪倾倒	情绪词	抽一个现实动作	长语音/倾倒
任务拆小	-	端点化下一步	描述过粗
线程关联	向量相似度	确认	相似度阈值
象限启发	截止→urgency↑ 等	综合 importance	内部字段

4.2b 调度器（智能排程）

1
delivery_jobs 到期 或 用户纠偏
2
  -> 检查 suppress_until / 勿扰 / 端点偏好
3
  -> 强制 WIP=1（硬截止例外 + reason）
4
  -> 生成 notifications
5
  -> 推送 FCM / 微信模板 / 桌面
6
  -> 埋点：delivered / ignored / snoozed / suppress（错误时机指标）

不是：扫描日历空闲并自动 time-block。

4.3 通知系统

通知调度：由 delivery_jobs 驱动，而非「一天塞满 N 条任务」。

去重与防骚扰：

同一 todo 主动提醒有上限。
同时主动下一步 ≤1（WIP）。
连续 3 次忽略同类 → 降权。
「今天别推」写 suppress_until。

5. 多端同步方案

5.1 同步策略

场景	同步方式	延迟	说明
碎片捕获	实时同步	< 1s	捕获后立即写入主库，其他端通过 WebSocket 接收
状态变更	实时同步	< 1s	状态机执行后，广播变更事件
通知推送	实时推送	< 3s	通过 FCM/微信模板消息推送到目标端点
偏好更新	实时同步	< 1s	偏好写回后，立即同步存栏
大批量数据	增量同步	< 5s	首次登录/长时间离线，增量拉取变更

5.2 WebSocket 设计

连接管理：

用户登录后建立 WebSocket 连接。
心跳检测：每 30 秒 ping/pong。
断线重连：指数退避策略（1s, 2s, 4s, 8s… 最大 60s）。

消息类型：

类型	说明
`fragment.new`	新碎片
`fragment.state_change`	碎片状态变更
`todo.activate`	激活下一步任务
`todo.complete`	任务完成
`notification.push`	通知推送
`preference.update`	偏好更新

6. 安全与隐私

6.1 数据安全

措施	说明
传输加密	HTTPS/TLS 1.3
存储加密	PostgreSQL 启用 SSL，OSS 服务端加密
敏感数据	用户内容 AES-256 加密存储
备份	每日全量备份 + 实时增量备份
访问控制	JWT Token + RBAC（基于角色的访问控制）

6.2 隐私保护

措施	说明
数据最小化	只收集必要数据（内容、来源、时间）
数据可删除	用户可完整删除账户和所有数据
数据可导出	提供 JSON/CSV/PDF 导出功能
第三方共享	不向第三方共享用户数据
AI 训练	用户使用数据不用于模型训练

7. 性能与扩展性

7.1 性能目标

指标	目标	说明
API 响应时间	P99 < 200ms	标准 API 请求
沉淀引擎延迟	规则引擎 < 100ms, LLM < 3s	碎片到状态判断
通知延迟	< 5s	任务到期到通知送达
并发用户	10K DAU	MVP 阶段目标
可用性	99.5%	月度可用性

7.2 扩展性设计

场景	方案
读多写少	读写分离，缓存热点数据
碎片增长	按用户 ID 分表/sharding
LLM 调用	异步队列 + 限流 + 降级（规则引擎兜底）
通知峰值	通知队列削峰填谷，错峰发送

8. 部署方案

8.1 开发环境

1
Docker Compose
2
  - PostgreSQL 14
3
  - Redis 7
4
  - API 服务（热重载）
5
  - 前端（HMR）

8.2 生产环境

1
Kubernetes (EKS/ACK/GKE)
2
  - API 服务 (3 replicas)
3
  - 沉淀引擎 Worker (2 replicas)
4
  - 通知 Worker (2 replicas)
5
  - PostgreSQL (RDS/云数据库)
6
  - Redis (ElastiCache/云 Redis)
7
  - 七牛云/OSS

8.3 CI/CD 流程

1
Git Push
2
  -> GitHub Actions
3
    -> Lint / Test / Build
4
    -> Docker Build and Push
5
    -> Deploy to Staging
6
    -> Smoke Test
7
    -> Deploy to Production (Canary)

9. 监控与告警

9.1 监控指标

指标	类型	告警阈值
API 请求延迟	P99 > 200ms	连续 5 分钟
API 错误率	> 1%	连续 3 分钟
沉淀引擎延迟	> 5s	单次
通知失败率	> 5%	连续 10 分钟
数据库连接数	> 80%	容量阈值
磁盘使用率	> 80%	容量

9.2 日志规范

1
时间戳 | 级别 | 服务 | 用户ID | 追踪ID | 操作 | 状态 | 耗时 | 附加信息

示例：

1
2024-07-06T15:30:00Z INFO api user_123 trace_a1 POST /fragments 200 45ms {"content_length": 50}