# 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` 第四节，本文件不重复列举。