# VizTyp Backend Server / VizTyp 后端服务

VizTyp 知识管理的 HTTP 后端服务。Web 端和 Tauri 桌面端共用同一套 HTTP API。
HTTP backend for VizTyp knowledge management. Shared by web and Tauri desktop via one HTTP API.

## 架构 / Architecture

- **Runtime**: tokio
- **HTTP**: hyper 1.x + hyper-util(官方配套)
- **序列化**: serde + serde_json
- **认证**: jsonwebtoken(JWT)+ sha2(SHA-256 密码哈希)
- **存储**: JSON 文件(元数据)+ .typ 文件(内容),无数据库

## API / 接口

### 认证 / Auth

| Method | Path | 功能 / Function | 认证 |
|---|---|---|---|
| POST | `/api/auth/register` | 注册(首用户自动 owner) | 公开 |
| POST | `/api/auth/login` | 登录(返回 JWT) | 公开 |
| GET | `/api/auth/me` | 当前用户信息 | JWT |
| GET | `/api/auth/status` | 是否有注册用户 | 公开 |
| GET | `/api/users` | 列出所有用户 | JWT |

### 知识库与文档 / KB & Docs

| Method | Path | 功能 / Function | 认证 |
|---|---|---|---|
| GET | `/api/workspace` | 获取工作空间(含所有 KB 元数据) | — |
| POST | `/api/kb` | 创建知识库 | — |
| GET | `/api/kb/:id/docs` | 列出 KB 下所有文档(递归) | KB 读权限 |
| GET | `/api/kb/:id/tags` | 列出 KB 标签 | KB 读权限 |
| GET/POST/DELETE | `/api/kb/:id/collaborators` | 协作者 CRUD | KB 写权限 |
| POST | `/api/kb/:id/access-code` | 设置 KB 访问码 | KB 写权限 |
| GET | `/api/doc/:id` | 读取文档(含 draft_content/status/tags) | KB 读权限 |
| PUT | `/api/doc/:id` | 保存文档(`{content, draft}`) | KB 写权限 |
| POST | `/api/doc` | 创建文档 | KB 写权限 |
| POST | `/api/doc/:id/publish` | 发布草稿(提升为发布版) | KB 写权限 |

### 版本历史 / Version History

| Method | Path | 功能 / Function |
|---|---|---|
| GET | `/api/doc/:id/versions` | 列出版本快照 |
| POST | `/api/doc/:id/versions` | 保存版本快照 |
| POST | `/api/doc/:id/versions/:vid/restore` | 恢复到指定版本 |

### 标签 / Tags

| Method | Path | 功能 / Function |
|---|---|---|
| GET | `/api/doc/:id/tags` | 读取文档标签 |
| PUT | `/api/doc/:id/tags` | 设置文档标签 |

### 搜索与分享 / Search & Share

| Method | Path | 功能 / Function |
|---|---|---|
| POST | `/api/search` | 权限感知全文搜索(body: `{q, kb_ids}`) |
| POST | `/api/share` | 创建分享令牌 |
| GET/POST | `/api/share/:token` | 通过令牌访问(GET 公开,POST 可带访问码) |
| DELETE | `/api/share/:token` | 删除分享 |
| GET | `/api/doc/:id/share` | 查询文档的分享令牌 |

### 工作区与状态 / Workspace & Presence

| Method | Path | 功能 / Function | 认证 |
|---|---|---|---|
| GET | `/api/workspace/export` | 导出整个工作区(含文档内容) | JWT |
| POST | `/api/workspace/import` | 导入工作区(body: `{data, overwrite}`) | JWT |
| GET | `/api/presence` | 在线状态(记录心跳 + 列出在线用户) | JWT |

所有响应统一格式:`{"ok": true, "data": ...}` 或 `{"ok": false, "error": "..."}`。

**权限层级 / Permission tiers**:
- **public**:任何人可读
- **private / specified**:需 JWT 身份且有协作者角色(owner 对所有 KB 有 admin)
- **access_code**:需有效访问码(`X-Access-Code` header)或有角色
- **写权限**:reader 禁止写,writer/admin 允许

## 运行 / Run

```bash
cd server
cargo run

# 自定义端口/数据目录 / Custom port / data dir
VIZTYP_PORT=8000 VIZTYP_DATA_DIR=/path/to/data cargo run

# JWT secret (缺省用临时值, 生产环境务必设置) / JWT secret
VIZTYP_JWT_SECRET=your-secret cargo run
```

默认地址 `http://127.0.0.1:7480`,数据目录 `~/.viztyp/data/`。

## 存储布局 / Storage layout

```
~/.viztyp/data/
├── workspace.json         # Workspace + KB[] 元数据
├── users.json             # 用户表 (id → User, 含密码哈希)
├── kb_collaborators.json  # KB 协作者 (kb_id → [(user_id, role)])
├── versions.json          # 版本快照 (doc_id → [DocVersion])
├── doc_tags.json          # 文档标签 (doc_id → [tag])
├── shares.json            # 分享令牌 (token → DocShare)
├── access_codes.json      # KB 访问码 (kb_id → code)
├── presence.json          # 在线状态 (user_id → Presence)
├── kbs/                   # KB 快照目录
└── <root_path>/           # KB 实际文件目录 (创建时指定)
    ├── *.typ              # 发布版文档
    └── *.typ.draft        # 草稿 sidecar (发布后清除)
```

## 与前端集成 / Frontend integration

- Web 端:前端 `VIZTYP_API_URL` 环境变量指向本服务(默认 `http://127.0.0.1:7480`)
- Tauri 桌面端:作为 sidecar 自动启动
  - `yarn dev`(debug):`src-tauri/src/lib.rs` 用 `std::process::Command` spawn(需先在 `server/` 运行 `cargo build`)
  - `yarn build`(release):先 `yarn server:build` 生成 `src-tauri/binaries/viztyp-server-<triple>`,再用 `tauri-plugin-shell` 的 `app.shell().sidecar()`(打包进安装包)
  - 应用退出时通过 `RunEvent::Exit` 自动 kill 子进程

## 打包流程 / Bundling

```bash
# 1. 构建 sidecar (带 target-triple 后缀) / Build sidecar with triple suffix
yarn server:build

# 2. 完整桌面打包 (含 sidecar) / Full desktop bundle
yarn build
```

`scripts/build-sidecar.sh` 自动读取 `TAURI_ENV_TARGET_TRIPLE`(Tauri 注入)或宿主 triple。

交叉编译示例 / Cross-compile:
```bash
TAURI_ENV_TARGET_TRIPLE=x86_64-pc-windows-msvc yarn server:build
```