Haven/docs/overview.md

overview — 项目定位与边界

本文件回答：Haven 是什么、面向什么场景、由哪几部分组成、主页承担什么职责。 依赖：无

一、一句话定位

Haven 是一套自托管的个人综合知识中台：以 PostgreSQL 为唯一真值源，Go 后端 + Vue 前端，Web 浏览器为一等主入口，TUI 与 Neovim 插件为次级客户端，服务于个人在多环境下的写作与查阅。

二、核心场景

使用者在三类环境之间切换，对鉴权和访问方式的要求不同：

• 家里终端：可信环境，可授信长期免二次验证；
• 公司电脑：半可信环境，需要登录但可授信；
• 网吧等公共环境：不可信环境，需要完整鉴权且离开后凭证应可撤销。

核心矛盾是：同一套数据，要在可信与不可信环境之间安全地读写。Haven 的鉴权模型围绕这个矛盾设计。

三、组成部分

部分	角色	说明
Web 前端	一等主入口	登录、写作、公开浏览、作品集、设置
Go 后端	唯一 API 出口	所有客户端经由它读写 PostgreSQL
PostgreSQL	唯一真值源	不引入其他存储作为真值源
TUI 客户端	次级客户端	只覆盖读写笔记 + 检索主路径
Neovim 插件	次级客户端	同上，走 API Token 鉴权

三类客户端的分工原则：Web 是功能全集，TUI 与 Neovim 只覆盖主路径，不做功能对等。

四、权限模型概览

• 笔记分两级：private（默认）/ public；
• 新建笔记一律 private，公开是显式动作；
• 未登录只能访问 public 内容；
• 鉴权分层：账号密码 → TOTP → 可授信浏览器设备；
• 长期 API Token 供 TUI / Neovim / 脚本使用，可单独撤销，与登录会话解耦。

细节见 docs/backend/auth.md 与 docs/backend/data-model.md。

五、主页职责

主页同时承担三件事，按登录态区分渲染：

• 私有工作台：登录后可见的笔记管理与写作入口；
• 公开内容浏览：未登录也可访问的 public 笔记列表；
• 作品集展示：仓库托管在自建 Gogs 或 GitHub，条目声明平台后跳转。

六、扩展预留

• LLM 抽象层：为后续 RAG 检索、笔记静态翻译预留接口，本期只定义不实现；
• 审计日志：表结构预留，前期只记安全与状态事件。

七、边界

本项目的硬性禁令（不做什么）集中在 docs/conventions.md 第四节，本文件不重复列举。