# 服务端 API

## 概述

服务端为 Python Flask 应用，位于 `server/` 目录。提供用户统计、数据同步和管理后台功能。

## 模块结构

| 文件 | 职责 |
|------|------|
| `app.py` | 入口，注册所有路由模块 |
| `config.py` | 配置（JWT 密钥、数据库路径、备份目录）|
| `database.py` | 数据库初始化与管理（SQLite）|
| `auth.py` | 认证路由（激活码验证）|
| `admin_api.py` | 管理后台 API |
| `sync_api.py` | 同步 API（文件上传/下载、心跳）|
| `data_api.py` | 数据 CRUD API（影视/书籍/笔记/标签/图片）|
| `web_ui.py` | Web 管理界面 |
| `static/` | 静态资源 |
| `requirements.txt` | Python 依赖 |

## API 端点

### 认证

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/activate` | 校验激活码 |

请求体：`{"code": "激活码", "device_id": "设备标识"}`

响应：`{"valid": true, "expires_at": "...", "is_permanent": false}`

### 数据 CRUD

所有请求需在 body 中附带 `code` 字段。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/data/movies` | 获取影视列表（支持 status/limit/offset）|
| POST | `/api/data/movie/save` | 保存影视（新建/更新）|
| POST | `/api/data/movie/delete` | 删除影视 |
| POST | `/api/data/books` | 获取书籍列表 |
| POST | `/api/data/book/save` | 保存书籍 |
| POST | `/api/data/book/delete` | 删除书籍 |
| POST | `/api/data/notes` | 获取笔记列表 |
| POST | `/api/data/note/save` | 保存笔记 |
| POST | `/api/data/note/delete` | 删除笔记 |
| POST | `/api/data/movie_reviews` | 获取影评 |
| POST | `/api/data/movie_review/save` | 保存影评 |
| POST | `/api/data/movie_review/delete` | 删除影评 |
| POST | `/api/data/movie_posters` | 获取海报 |
| POST | `/api/data/movie_poster/save` | 保存海报 |
| POST | `/api/data/movie_poster/delete` | 删除海报 |
| POST | `/api/data/book_reviews` | 获取书评 |
| POST | `/api/data/book_review/save` | 保存书评 |
| POST | `/api/data/book_review/delete` | 删除书评 |
| POST | `/api/data/book_excerpts` | 获取摘抄 |
| POST | `/api/data/book_excerpt/save` | 保存摘抄 |
| POST | `/api/data/book_excerpt/delete` | 删除摘抄 |
| POST | `/api/data/tags` | 获取标签 |
| POST | `/api/data/tag/save` | 保存标签 |
| POST | `/api/data/tag/delete` | 删除标签 |

### 同步

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/heartbeat` | 设备心跳上报 |
| POST | `/api/sync/upload` | 上传数据库/图片文件 |
| POST | `/api/sync/download` | 下载数据库/图片文件 |

### 图片

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/data/image/upload` | 上传图片 |
| GET | `/api/data/image/{code}/{path}` | 获取图片 |

## 激活码机制

每个激活码对应一个独立的 SQLite 数据库：

```
server/backups/{CODE}/
├── database/
│   └── mooknote.db     ← 该激活码的数据
├── images/              ← 图片文件
└── avatars/             ← 头像文件
```

激活码校验通过 `admin_api.py` 中的 `_verify_code()` 函数完成，支持有效期和永久有效两种模式。

## 服务端数据库

服务端自身使用 `stats.db` 存储设备信息和心跳日志：

| 表 | 说明 |
|----|------|
| `devices` | 设备注册（device_hash, first_seen, last_seen）|
| `heartbeat_logs` | 心跳日志（device_hash, ip, device_type, device_name）|
| `changelog` | 更新日志 |

每个激活码的数据存储在独立的 `backups/{code}/database/mooknote.db` 中，表结构与客户端一致。

## 启动

```bash
cd server
python app.py          # 开发环境（waitress）
# 或
gunicorn -w 2 -b 0.0.0.0:27047 app:app  # 生产环境
```

默认端口：27047（可通过环境变量 `PORT` 修改）。

[返回首页](Home.md)