下面是 `README.md` 初稿。根目录文件，定位是**索引 + 工作流入口**，不重复任何文档的内容。

---

# Haven

自托管的个人综合知识中台。PostgreSQL 为唯一真值源，Go + Gin 后端，Vue 3 前端，公开域与私有域分离部署。本期只做 Web 端，TUI 与 Neovim 插件在第二版。

## 文档即事实来源

本项目所有代码由 opencode + DeepSeek 依据 `docs/` 生成，**文档是唯一事实来源**：

- 代码与文档冲突时，以文档为准；
- 改需求先改文档，再重新生成代码；
- `docs/` 只能由人类修改，AI 只读不写。

完整规则见 `docs/conventions.md`。

## 文档索引

### 项目级（`docs/`）

| 文件 | 回答什么问题 |
|---|---|
| `overview.md` | Haven 是什么、面向什么场景、由哪几部分组成 |
| `architecture.md` | 技术栈、目录结构、组件关系、配置项、部署形态 |
| `conventions.md` | 文档与代码的组织规则、主从关系、硬性禁令清单 |
| `api.md` | 每个 HTTP 接口的路径、请求、响应、鉴权、错误码 |

### 后端（`docs/backend/`）

| 文件 | 回答什么问题 |
|---|---|
| `data-model.md` | 数据库有哪些表、字段、约束、索引、业务规则 |
| `auth.md` | 鉴权分层、会话、授信设备、API Token、授权中间件 |
| `audit.md` | 审计记录哪些事件、表结构、写入时机 |
| `llm-extension.md` | LLM 抽象层接口定义（本期只定义不实现） |

### 前端（`docs/frontend/`）

| 文件 | 回答什么问题 |
|---|---|
| `frontend.md` | 公开域与私有域的页面清单、路由、登录流程 |
| `clients.md` | TUI 与 Neovim 插件（第二版，本期占位） |

## 仓库结构

```
Haven/
├── docs/           # 唯一事实来源
├── backend/        # Go 后端（Gin + database/sql + pgx）
├── frontend/       # Vue 3 + Vite 前端
├── deploy/         # 部署脚本（如需要）
└── README.md
```

后端代码只写 `backend/`，前端代码只写 `frontend/`，不得交叉。

## 工作流

生成代码时，按任务类型喂上下文：

- **生成后端代码**：`docs/` 根下项目级文件 + `docs/backend/` + `docs/api.md`；
- **生成前端代码**：`docs/` 根下项目级文件 + `docs/frontend/` + `docs/api.md`。

生成结果与文档不符时，是代码错，修代码或重新生成，不改文档去迁就代码。

## 快速开始

（占位，部署方式待 Gogs 备案通过后确定，届时补入。已知约束：不使用 Docker / K8s，宿主机直接运行。）

## 技术栈

Go ≥ 1.22 / Gin / PostgreSQL ≥ 15（`pg_trgm`）/ Vue 3 / Vite / TypeScript。详见 `docs/architecture.md`。