# 用户认证 + 云端同步 + 评论系统设计文档

**日期：** 2026-05-05  
**作者：** MikiVL  
**状态：** 已批准

---

## 背景与目标

当前笔记应用（www.mikivl.online/app）的所有数据存储在浏览器 IndexedDB 中，清除浏览器数据或换设备即丢失。本次扩展目标：

1. 添加用户账号系统（用户名+密码注册/登录）
2. 登录用户的笔记双存——本地 IndexedDB 继续作为缓存，服务端 SQLite 持久化
3. 云存储功能需邀请码激活（预生成 10 个）
4. 主页（www.mikivl.online）新增评论区，登录用户可发评论

---

## 架构总览

```
前端（React）          服务端（Hono + Node.js）   数据库（SQLite + Drizzle）
────────────────       ──────────────────────     ───────────────────────────
IndexedDB（本地）  ←→  /api/auth/*                users
                       /api/notes/*        ←────  notes
                       /api/folders/*      ←────  folders
                       /api/comments/*     ←────  comments
                       /api/ai/*（已有）           invite_codes
```

---

## 数据库 Schema

### users
```sql
id          TEXT PRIMARY KEY  -- nanoid
username    TEXT UNIQUE NOT NULL
passwordHash TEXT NOT NULL    -- bcrypt hash
cloudEnabled INTEGER DEFAULT 0  -- 0=未激活，1=已激活（填写邀请码后）
createdAt   INTEGER NOT NULL
```

### notes
```sql
id          TEXT PRIMARY KEY
userId      TEXT NOT NULL REFERENCES users(id)
title       TEXT NOT NULL DEFAULT ''
content     TEXT NOT NULL DEFAULT ''
folderId    TEXT              -- null = 根目录
tags        TEXT NOT NULL DEFAULT '[]'  -- JSON 数组
starred     INTEGER DEFAULT 0
wordCount   INTEGER DEFAULT 0
deletedAt   INTEGER           -- null = 未删除，软删除时间戳
createdAt   INTEGER NOT NULL
updatedAt   INTEGER NOT NULL
```

### folders
```sql
id          TEXT PRIMARY KEY
userId      TEXT NOT NULL REFERENCES users(id)
name        TEXT NOT NULL
parentId    TEXT              -- null = 根目录
order       INTEGER DEFAULT 0
createdAt   INTEGER NOT NULL
```

### comments
```sql
id          TEXT PRIMARY KEY
userId      TEXT NOT NULL REFERENCES users(id)
content     TEXT NOT NULL
createdAt   INTEGER NOT NULL
```

### invite_codes
```sql
code        TEXT PRIMARY KEY
usedByUserId TEXT             -- null = 未使用
usedAt      INTEGER           -- null = 未使用
```

---

## 认证方案

- **JWT**，签发时有效期 30 天，存储在 `localStorage`（key: `mikivl_token`）
- 无 refresh token（30 天足够，过期重新登录）
- 密码使用 bcrypt hash（cost factor 10）
- 所有 `/api/notes/*`、`/api/folders/*` 接口需携带 `Authorization: Bearer <token>`

---

## 同步策略

**本地优先，登录后同步：**

1. **未登录**：完全使用 IndexedDB，功能不受影响
2. **登录时**：执行全量同步——拉取云端数据与本地合并，以 `updatedAt` 较新的为准
3. **本地写操作**（create/update/delete）：操作完成后立即异步推送到云端（fire-and-forget，失败静默）
4. **冲突处理**：同一条笔记本地和云端都有修改，取 `updatedAt` 较大的版本

**同步接口：**

- `GET /api/notes/sync` — 返回该用户全量笔记和文件夹
- `POST /api/notes/sync` — 批量 upsert 笔记和文件夹（幂等）

---

## API 接口定义

### 认证

```
POST /api/auth/register
Body: { username: string, password: string }
Response: { token: string, user: { id, username, cloudEnabled } }

POST /api/auth/login
Body: { username: string, password: string }
Response: { token: string, user: { id, username, cloudEnabled } }

POST /api/auth/activate
Header: Authorization: Bearer <token>
Body: { code: string }
Response: { success: true }
```

### 同步

```
GET /api/notes/sync
Header: Authorization: Bearer <token>
Response: { notes: Note[], folders: Folder[] }

POST /api/notes/sync
Header: Authorization: Bearer <token>
Body: { notes: Note[], folders: Folder[] }
Response: { synced: number }
```

### 笔记 CRUD（单条操作，供实时同步用）

```
PUT /api/notes/:id          -- upsert 单条笔记
DELETE /api/notes/:id       -- 软删除（设置 deletedAt）
PUT /api/folders/:id        -- upsert 单条文件夹
DELETE /api/folders/:id     -- 删除文件夹
```

### 评论

```
GET /api/comments           -- 获取所有评论（公开）
POST /api/comments          -- 发布评论（需登录）
Header: Authorization: Bearer <token>
Body: { content: string }
Response: { id, username, content, createdAt }
```

---

## 前端改动

### 新增文件
- `src/lib/auth.ts` — JWT 存取、login/register/activate API 封装
- `src/lib/sync.ts` — 全量同步、单条推送、冲突合并逻辑
- `src/components/auth/LoginModal.tsx` — 登录/注册弹窗（Tab 切换），含邀请码激活入口
- `src/components/auth/UserMenu.tsx` — 侧边栏底部用户区域（头像、用户名、云同步状态、登出）

### 修改文件
- `src/stores/appStore.ts` — 添加 `currentUser`、`syncStatus` state；写操作（createNote/updateNote/deleteNote/restoreNote/createFolder/updateFolder/deleteFolder）完成后触发 `sync.pushOne()`
- `src/components/sidebar/Sidebar.tsx` — 底部添加 `<UserMenu />`
- `homepage/index.html` — 底部新增评论区（读取 `/api/comments`，登录用户可发评论）

### appStore 新增 state
```typescript
currentUser: { id: string; username: string; cloudEnabled: boolean } | null
syncStatus: 'idle' | 'syncing' | 'error'
```

---

## 服务端文件结构

```
server/
├── index.ts          （已有，注册新路由）
├── db.ts             （Drizzle 初始化，schema 定义，DB 文件路径：/opt/mikivl/data/app.db）
├── middleware/
│   └── auth.ts       （JWT 验证，注入 c.set('userId', ...)）
└── routes/
    ├── auth.ts       （register/login/activate）
    ├── notes.ts      （sync GET/POST + 单条 CRUD）
    ├── folders.ts    （单条 CRUD）
    └── comments.ts   （list/create）
```

---

## 邀请码

预生成 10 个，数据库初始化时写入：

```
MIKI-A7X2-KP9Q
MIKI-B3N8-WR4L
MIKI-C6M1-ZT7Y
MIKI-D9F5-HJ2V
MIKI-E4K3-QN6U
MIKI-F8R7-XG1S
MIKI-G2W4-LB5E
MIKI-H5T9-MC8D
MIKI-J1P6-VF3O
MIKI-K7Q2-YH4N
```

---

## 部署变更

- 服务端新增依赖：`drizzle-orm`、`better-sqlite3`、`bcryptjs`、`jsonwebtoken`
- SQLite 数据库文件：`/opt/mikivl/data/app.db`（首次启动自动创建）
- 服务器需创建目录：`mkdir -p /opt/mikivl/data`
- PM2 重启 hono-server 后生效

---

## 分拆子项目顺序

由于子系统间有依赖关系，按以下顺序实现：

1. **服务端基础层**（db.ts + schema + auth 路由）
2. **前端认证**（LoginModal + UserMenu + auth.ts + appStore 扩展）
3. **云同步**（sync.ts + notes/folders 路由 + appStore 写操作触发同步）
4. **首页评论**（comments 路由 + homepage/index.html 评论区）