# Superbox Go API Reference

> 后端 API 端点详尽文档。源自动词检索表 + 路由注册表 (`internal/router/router.go`) + handler/model 实现。

## 目录

- [基础信息](#基础信息)
- [统一响应信封](#统一响应信封)
- [认证机制](#认证机制)
- [访问控制矩阵](#访问控制矩阵)
- [错误码与 HTTP 状态码](#错误码与-http-状态码)
- [公共端点](#公共端点)
  - [健康检查](#健康检查)
  - [系统初始化](#系统初始化)
  - [认证](#认证)
  - [事件流 (SSE / WebSocket)](#事件流-sse--websocket)
- [API 端点](#api-端点)
  - [Detectors 检测器管理](#detectors-检测器管理)
  - [Cameras 摄像头管理](#cameras-摄像头管理)
  - [Events 事件管理](#events-事件管理)
  - [Rules 规则管理](#rules-规则管理)
  - [Mediums 媒体文件](#mediums-媒体文件)
  - [Webhooks 回调配置](#webhooks-回调配置)
  - [Algorithms 算法管理](#algorithms-算法管理)
  - [Samples 样本管理](#samples-样本管理)
  - [Users 用户管理](#users-用户管理)
  - [Settings 系统设置](#settings-系统设置)
  - [Stream 视频流](#stream-视频流)
- [静态资源](#静态资源)
- [数据模型](#数据模型)
- [附录：约束与默认值](#附录约束与默认值)
  - [JWT 与登录](#jwt-与登录)
  - [Refresh token 行为](#refresh-token-行为)
  - [客户端 silent refresh 协议](#客户端-silent-refresh-协议)
  - [多 tab 已知限制](#多-tab-已知限制)

---

## 基础信息

- 基础路径: `/api/v1` （`/health` 例外，直接挂在根路径）
- 默认监听地址: `0.0.0.0:8000`（可在 `config.json → server.addr` 修改或 `serve --addr` 覆盖）
- 内容类型: `application/json; charset=utf-8`（除文件上传、媒体文件、HLS 之外）
- 字符编码: UTF-8
- 跨域: `Access-Control-Allow-Origin: *`，`Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS`
- 限流: 暂未实现

> 全部错误均带 JSON 状态码/详情字段（见下）。所有受保护接口需先 `/api/v1/auth/login` 拿到 JWT。

---

## 统一响应信封

所有非文件流的成功响应均使用 `response/response.go` 中定义的信封：

```json
{
  "err": {
    "ec": 0,
    "dm": "ok",
    "em": ""
  },
  "ret": <data>
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `err.ec` | int | 自定义错误码，`0` = 成功；与 HTTP 状态码同步 |
| `err.dm` | string | 错误描述宏（`ok` / `Bad Request` / `Not Found` / `Internal Server Error` 等） |
| `err.em` | string | 错误详情原文（成功时省略） |
| `ret` | any | 业务负载，结构视端点而异 |

### 列表型分页负载（`response.RetList`）

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "count": 42,
    "next": null,
    "previous": null,
    "results": [ ... ]
  }
}
```

`count` 为符合条件的总行数；`results` 为当前页的对象数组。`next` / `previous` 始终为 `null`（Django 兼容字段），分页通过 `limit` / `offset` query 参数控制。

### 数组型负载（`response.RetArray`）

`/api/v1/algorithms` 的 GET 接口直接返回数组，不带分页包装：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": [ {...}, {...} ] }
```

### 空响应

`response.NoContent` 直接返回 `204 No Content`，无 body（用于 DELETE、PATCH 等无业务数据的接口）。

---

## 认证机制

### Token 体系（access + refresh）

后端使用 **stateful 双 token 模型**：

| Token | 格式 | 存储 | TTL | 用途 |
|-------|------|------|-----|------|
| `access_token` | HS256 JWT（含 `user_id` / `username` / `is_admin` / `exp` / `iat` claims） | 仅客户端 | `jwt.access_token_ttl`（默认 `15m`） | 访问受保护 API |
| `refresh_token` | 32 字节随机 → 43 字符 base64-url | 客户端明文 + 服务端存 **sha256 哈希** | `jwt.refresh_token_ttl`（默认 `7d`，**sliding**） | 换新 access + refresh 对 |

**关键属性**：

- **严格轮换**（strict rotation）：每次 `POST /api/v1/auth/refresh` 成功都会签发新 pair，旧的 refresh 立即失效（在 DB 行上标记 `rotated_at = now()`，不删除）。
- **Reuse detection**：被轮换过的 refresh token 若被再次使用，**整个 family（同一登录会话的 token 链）全部吊销**，原持有者被迫重新登录。视为凭据泄露的应对策略。
- **Sliding window**：每次成功 refresh 都会把 `expires_at` 重新设为 `now + 7d`，活跃用户不需要重新输入密码。**真正决定"多久要重新登录"的是 refresh token 的不活跃时长**。
- **7 天不活跃就要重新登录**；7 天内活跃用户**永不重新登录**（直到主动 logout 或 reuse detection 触发）。

### 登录获取 token pair

调用 `POST /api/v1/auth/login`，返回：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a",
    "expires_at": "2026-06-03T12:34:56Z",
    "refresh_expires_at": "2026-06-10T12:34:56Z",
    "user": { "id": 1, "username": "admin", "is_admin": true, "is_active": true }
  }
}
```

JWT 负载 (`Claims`)：

```json
{
  "user_id": 1,
  "username": "admin",
  "is_admin": true,
  "exp": 1748944496,
  "iat": 1748943596
}
```

签名算法：HS256，密钥取自 `config.json → jwt.secret_key`，TTL 由 `jwt.access_token_ttl` 控制（默认 `15m`）。

### 续期 token（silent refresh）

access 过期前无需主动操作；前端 axios 拦截器会在 401 时自动：

1. 用 `localStorage.refresh_token` 调 `POST /api/v1/auth/refresh`
2. 成功后更新 localStorage + 重发原请求
3. 失败（refresh 也过期 / 被吊销 / reuse detected）则清状态并跳 `/admin/login`

5 个并发 401 共用一个 in-flight refresh 请求（模块级 Promise 缓存），避免 strict rotation 误触发 reuse detection 把整个 family 杀光。

### 携带 access token

任选其一：

```http
# Header 方式（推荐）
Authorization: Bearer <access_token>

# Query 方式（用于浏览器 HLS / SSE / WebSocket）
GET /api/v1/events/stream?token=<access_token>
GET /api/v1/cameras/1/stream?token=<access_token>
GET /hls/camera_1.m3u8?token=<access_token>
```

> 中间件优先读 `Authorization` 头，缺失时回退到 `?token=` query。

### 携带 refresh token

refresh token **不通过 header 传递**（永远不进 URL / Authorization 头），仅用于以下两种途径：

```http
# 1. 主动调 /auth/refresh 时放在 body
POST /api/v1/auth/refresh
Content-Type: application/json
{ "refresh_token": "<raw>" }

# 2. 主动 logout 时放在 body（让服务端能删 DB 行）
POST /api/v1/auth/logout
Authorization: Bearer <access>
{ "refresh_token": "<raw>" }
```

### 鉴权模式

| 模式 | 描述 | 失败返回 |
|------|------|----------|
| `Auth` | 必须携带有效 access JWT | `401 Unauthorized` |
| `AuthOrDetector` | access JWT 有效 *或* 调用方 IP 在 `detectors` 表中注册过 | `401 Unauthorized` |
| `AdminOnly` | 紧接 `Auth` 使用，要求 `is_admin == true` | `403 Forbidden` |
| 公开 | 无任何校验 | — |

### Detector 接入

当 `AuthOrDetector` 中间件检测到 `Authorization` 无效时，会读取 `c.ClientIP()`，查询 `detectors` 表的 `ip` 字段；命中即放行（在 gin context 写入 `detector_ip`），否则 401。Detector 自身用 `/auth/login` 登录后也走同一 refresh 机制。

---

## 访问控制矩阵

下表汇总每个端点的访问控制（C = 受 CORS 公开；A = JWT 必填；AD = 仅管理员；AO = JWT 或 Detector IP；AOO = JWT 或 Detector IP）。

| 路径 | 方法 | 鉴权 | 备注 |
|------|------|------|------|
| `/health` | GET | C | — |
| `/api/v1/health` | GET | C | — |
| `/api/v1/setup/config` | POST | C | 初始化写入 |
| `/api/v1/init` | GET, POST | C | 系统初始化 |
| `/api/v1/auth/login` | POST | C | 登录，颁发 access + refresh pair |
| `/api/v1/auth/refresh` | POST | C | 用 refresh token 换新 access + refresh pair |
| `/api/v1/auth/logout` | POST | A | 注销当前会话（access + refresh 双 token） |
| `/api/v1/events/stream` | GET (SSE) | A | 需 query token |
| `/api/v1/events/ws` | GET (WS) | A | 需 query token |
| `/api/v1/detectors` | GET, POST, DELETE | AD | 按角色限制 |
| `/api/v1/detectors/register` | POST | A | 检测器自助注册 |
| `/api/v1/detectors/:ip` | GET, PUT, PATCH, DELETE | AD | — |
| `/api/v1/cameras` | GET | A | — |
| `/api/v1/cameras` | POST | AD | — |
| `/api/v1/cameras/:id` | GET, PATCH | AO | — |
| `/api/v1/cameras/:id` | PUT | AD | — |
| `/api/v1/cameras/:id` | DELETE | AD | — |
| `/api/v1/cameras/:id/enable_sampling` | POST | AD | — |
| `/api/v1/cameras/:id/disable_sampling` | POST | AD | — |
| `/api/v1/cameras/:id/stream` | GET | A | 拉取 / 启动信息 |
| `/api/v1/cameras/:id/stream/start` | POST | AD | 启动转码 |
| `/api/v1/cameras/:id/stream/stop` | POST | AD | 停止转码 |
| `/api/v1/cameras/:id/snapshot` | GET | A | 拉取 JPEG 快照 |
| `/api/v1/events` | GET | A | 分页过滤 |
| `/api/v1/events` | POST | AO | 创建事件 |
| `/api/v1/events/:id` | GET | A | — |
| `/api/v1/events/:id` | PUT, PATCH, DELETE | AD | — |
| `/api/v1/events/:id/close_event` | POST | AD | — |
| `/api/v1/events/:id/push_event` | POST | AO | — |
| `/api/v1/events/queue_analysis` | POST | AO | — |
| `/api/v1/events/people_count` | POST | AO | — |
| `/api/v1/events/unmarked` | GET | A | — |
| `/api/v1/events/retrieve_ids` | GET | A | 拉取 ID 列表 |
| `/api/v1/events/retrieves` | GET | A | 拉取对象列表 |
| `/api/v1/events/delete_all` | POST | AD | 批量删除 |
| `/api/v1/rules` | GET | A | — |
| `/api/v1/rules` | POST | AD | — |
| `/api/v1/rules/:id` | GET | A | — |
| `/api/v1/rules/:id` | PUT, PATCH, DELETE | AD | — |
| `/api/v1/rules/camera/:camera_id` | GET | A | — |
| `/api/v1/rules/camera/:camera_id` | POST | AD | — |
| `/api/v1/mediums` | GET | A | — |
| `/api/v1/mediums` | POST | AO | multipart/form-data |
| `/api/v1/mediums/:id` | GET | A | — |
| `/api/v1/mediums/:id` | PUT, PATCH, DELETE | AD | — |
| `/api/v1/mediums/:id/file` | GET | A | 文件下载 |
| `/api/v1/webhooks` | GET, POST | AD | — |
| `/api/v1/webhooks/:id` | GET, PUT, PATCH, DELETE | AD | — |
| `/api/v1/webhooks/echo` | POST | AD | 回声测试 |
| `/api/v1/algorithms` | GET | AO | 数组返回 |
| `/api/v1/algorithms` | POST | AD | — |
| `/api/v1/algorithms/:code_name` | GET | AO | — |
| `/api/v1/algorithms/:code_name` | DELETE | AD | — |
| `/api/v1/samples` | GET, POST | AO | — |
| `/api/v1/samples/:id` | GET, PUT, PATCH, DELETE | AO | — |
| `/api/v1/samples/:id/upload_file` | POST | AO | 创建 SampleFile |
| `/api/v1/samples/files/:id/mark_uploaded` | POST | AO | 标记完成 |
| `/api/v1/users` | GET, POST | AD | — |
| `/api/v1/users/:id` | GET, PUT, PATCH, DELETE | AD | — |
| `/api/v1/users/:id/change_password` | POST | AD | — |
| `/api/v1/settings` | GET, POST | AD | — |
| `/api/v1/settings/:id` | GET, PUT, PATCH, DELETE | AD | — |
| `/api/v1/settings/name/:name` | GET | AD | — |
| `/api/v1/settings/by-name/:name` | PUT | AD | Upsert |
| `/api/v1/stream/webrtc/proxy` | GET | A | WebRTC → go2rtc 代理 |
| `/hls/*filepath` | GET | A | HLS 切片（query token） |
| `/storage/*filepath` | GET | C | 静态文件 |
| `/`, `/admin`, `/admin/*`, `/assets/*` | GET | C | 前端 SPA |

> 警告：`Auth` 中间件对未带 token 的请求直接 401，不进入 handler；`AuthOrDetector` 失败也回 401。

---

## 错误码与 HTTP 状态码

| HTTP | 场景 |
|------|------|
| `200 OK` | 默认成功 |
| `201 Created` | POST 创建成功（`response.RetCreated`） |
| `204 No Content` | DELETE / 无业务数据 PATCH |
| `400 Bad Request` | 参数缺失、JSON 解析失败、字段校验未通过 |
| `401 Unauthorized` | Token 缺失或无效 |
| `403 Forbidden` | 非管理员访问受控端点 |
| `404 Not Found` | 资源不存在 |
| `500 Internal Server Error` | 未捕获异常 / 服务层错误 / panic（被 Recovery 中间件捕获） |

SSE/WS/HLS 在 token 缺失或无效时返回 `401 Unauthorized`（`{"error": "..."}`，信封外）。

---

## 公共端点

### 健康检查

#### `GET /health`

无鉴权。仅返回 `{"status":"ok"}`。

```http
GET /health HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "ok" }
```

#### `GET /api/v1/health`

同上的别名挂载（`/api/v1/health`）。

---

### 系统初始化

> 仅用于系统首次部署；正常情况下使用 `superbox config init` CLI。

#### `GET /api/v1/init`

读取数据库中管理员用户数量。

```json
// Response 200
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": { "initialized": true, "needs_setup": false }
}
```

> 数据库不可达时也返回 `{"initialized": false, "needs_setup": true}`（兜底）。

#### `POST /api/v1/init`

创建初始管理员（仅当尚无管理员用户时成功）。

请求体：

```json
{ "username": "ops", "password": "Str0ng-Pass!" }
```

校验规则：
- username 非空
- password 长度 ≥ 8，且不等于 username
- 命中弱密码黑名单（`password`、`12345678`、`qwerty`、`admin`、`letmein`、`welcome`，不区分大小写）会被拒

成功：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": { "success": true } }
```

失败：
- 管理员已存在 → `400 admin user already exists`
- 密码过弱 → `400 password too weak`

#### `POST /api/v1/setup/config`

无数据库时仍可调用：写 `config.json` + 连接数据库 + AutoMigrate + 创建管理员，一次性走完。

请求体（`SetupConfigRequest`）：

```json
{
  "database": {
    "type": "sqlite | postgres | mysql",
    "host": "127.0.0.1",
    "port": 5432,
    "name": "superbox.db",
    "user": "superbox",
    "password": "secret"
  },
  "cloud": { "box_file": "...", "http_server": "...", "ws_server": "..." },
  "storage": {
    "type": "local",
    "local": { "path": "./data" }
  },
  "admin": { "username": "ops", "password": "Str0ng-Pass!" }
}
```

成功：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": { "success": true, "config_path": "/etc/superbox/config.json" } }
```

副作用：
- 写入文件权限 `0600` 的 `config.json`
- 自动生成 32 字节随机 `jwt.secret_key`（hex）
- 默认 `access_token_ttl=15m`、`refresh_token_ttl=7d`、`storage.type=local`、go2rtc 默认参数

---

### 认证

> 全部 3 个端点走 `application/json` 信封（`{"err":{...},"ret":...}`），见前文「统一响应信封」。

#### `POST /api/v1/auth/login`

- **鉴权**：公开（无 token）
- **Content-Type**: `application/json`
- **副作用**：
  - 在 `refresh_tokens` 表 INSERT 一行（`family_id` 为新 UUIDv4，`expires_at = now + 7d`）
  - 更新 `users.last_login = now`（失败时记 WARN，不影响登录结果）

请求：

```json
{ "username": "ops", "password": "Str0ng-Pass!" }
```

字段约束：
- `username`、`password` 均为 `binding:"required"`，缺失 → `400 Bad Request`
- 用户名 / 密码错误 或 用户 `is_active=false` → `401 invalid credentials`（不区分两种情况，避免账号枚举）

成功响应（`LoginResult`）：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a",
    "expires_at": "2026-06-03T12:34:56Z",
    "refresh_expires_at": "2026-06-10T12:34:56Z",
    "user": {
      "id": 1,
      "username": "ops",
      "is_admin": true,
      "is_active": true
    }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `access_token` | string | HS256 JWT；客户端用于 `Authorization: Bearer ...` |
| `refresh_token` | string | 43 字符 base64-url 随机串；客户端**必须**持久化（localStorage）；服务端只存 sha256 哈希 |
| `expires_at` | RFC 3339 string | access token 过期时间（默认 = now + 15m） |
| `refresh_expires_at` | RFC 3339 string | refresh token 过期时间（默认 = now + 7d） |
| `user` | object | 登录用户对象（同 `UserResponse`） |

失败：
- 缺字段 / JSON 解析失败 → `400 Bad Request`
- 用户名 / 密码错 / 用户禁用 → `401 invalid credentials`
- 内部错误（DB 写失败等）→ `500 Internal server error`

---

#### `POST /api/v1/auth/refresh`

- **鉴权**：公开（无 access token）；用 **body 里的 refresh_token** 验真
- **作用**：用 refresh token 换新 access + refresh pair（**strict rotation**）
- **副作用**：
  - 在事务中：把旧行的 `rotated_at` 设为 `now()`，并 INSERT 新行（同 `family_id`，新 `token_hash`，新 `expires_at = now + 7d`）
  - **不**更新 `users.last_login`（refresh 不算"登录"）
- **行为**（按结果分类）：

| 条件 | 行为 | HTTP |
|------|------|------|
| body 缺 `refresh_token` | 400 | `400 Bad Request` |
| DB 找不到该 `sha256(refresh_token)` | 401（= invalid） | `401 refresh failed` |
| 旧行 `rotated_at` 非空（reuse） | **杀整个 family**（DELETE WHERE family_id = ?），401 | `401 refresh failed` |
| `expires_at` 已过 | 401 | `401 refresh failed` |
| 用户不存在 / `is_active=false` | **杀 family**，401 | `401 refresh failed` |
| 其它 DB 错误 | 500 | `500 Internal server error` |
| 成功 | 200 + 新 pair | `200 OK` |

> **故意统一 401 响应**（无论 invalid / expired / reused），前端不区分具体原因，UX 一致即可。

请求：

```json
{ "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a" }
```

成功响应（同 `LoginResult` 形状）：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "<NEW access JWT>",
    "refresh_token": "<NEW refresh token>",
    "expires_at": "2026-06-03T12:50:00Z",
    "refresh_expires_at": "2026-06-10T12:50:00Z",
    "user": { "id": 1, "username": "ops", "is_admin": true, "is_active": true }
  }
}
```

> 旧 refresh token 在响应后立即失效；继续用旧 token 调本端点会触发 reuse detection，杀 family。

---

#### `POST /api/v1/auth/logout`

- **鉴权**：必填 access token（`Authorization: Bearer <access>`）—— 中间件从中解析 `user_id`
- **作用**：删 `refresh_tokens` 表中**当前会话**对应的那一行；不删其它会话（多端点登录互不影响）
- **Idempotent**：找不到行或 `refresh_token` 为空都返 `200`

请求：

```http
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json

{ "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a" }
```

> `refresh_token` 在 body 里是**可选**的（缺省 / 解析失败都容忍），便于前端在 access 已过期的情况下也能 logout。

成功响应：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": {} }
```

失败：
- 缺 `Authorization` 头 / access token 无效 → `401 Unauthorized`（由中间件返）
- service 层 DB 错误 → `500 Internal server error`

> 当前只退出"当前会话"。**没有**"退出所有会话"端点，也不主动吊销其它 family 的 token。要彻底吊销需要 `DELETE FROM refresh_tokens WHERE user_id = ?` 手工执行（DB 层）。


---

### 事件流 (SSE / WebSocket)

#### `GET /api/v1/events/stream` (Server-Sent Events)

- 鉴权：通过 `?token=` query 传递 JWT
- Content-Type: `text/event-stream`
- 帧格式：`event: <type>\ndata: <json>\n\n`

事件类型（`sse.EventType`）：

| `type` | 触发时机 | `data` 字段 |
|--------|----------|-------------|
| `event_create` | 新事件入库（POST /events、`POST /events/:id/push_event`、detector 上报成功） | `{ id, camera_id, camera_name, types, status, started_at, thumbnail_url }` |
| `event_update` | 事件字段更新（保留） | 与 `event_create` 同结构 |

控制开关：
- 读取 `settings.frontend.event_popup_enabled`（值 `"false"` 时停止推送，默认/缺失 → 启用）
- 设置后由 `SettingHandler.UpsertByName` 同步失效 SSE 内部缓存（30s TTL）

> 详情：见 `internal/sse/events.go` 与 `internal/handler/event_handler.go` 的 `publishEventCreate`。

#### `GET /api/v1/events/ws` (WebSocket)

- 鉴权：`?token=` query JWT
- 同源策略已禁用（`CheckOrigin: return true`）
- 心跳：服务端每 54s 发 Ping；客户端需在 60s 内响应 Pong
- 接收消息格式与 SSE 一致（`type` + `data`），由 `ws.Manager.BroadcastJSON` 转发

握手失败（无 token / 无效 token）返回 `401 {"error": "..."}`。

---

## API 端点

### Detectors 检测器管理

> 边缘 AI 检测器注册表。`AuthOrDetector` 中间件用这里的 IP 实现"凭 IP 信任"。

#### `GET /api/v1/detectors`

**鉴权**: Admin
**响应**: `{ ret: { count, results: DetectorResponse[] } }`

```json
// DetectorResponse
{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }
```

#### `POST /api/v1/detectors`

**鉴权**: Admin

请求体：

```json
{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }
```

> `ip` 必填（数据库唯一索引）。

成功返回 `201 Created` + 新建对象。

#### `GET /api/v1/detectors/:ip`

**鉴权**: Admin
**路径参数**: `ip` — 字符串 IP 地址

成功返回单个 `DetectorResponse`，未找到 → `404 detector not found`。

#### `PUT /api/v1/detectors/:ip` / `PATCH /api/v1/detectors/:ip`

**鉴权**: Admin
**Body**: 局部更新（`type`、`version`），`ip` 不可改。

返回更新后的对象。

#### `DELETE /api/v1/detectors/:ip`

**鉴权**: Admin
返回 `204 No Content`。

#### `POST /api/v1/detectors/register`

**鉴权**: 任意已登录用户
**用途**: 检测器自服务注册/心跳。

请求体：

```json
{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }
```

> 不存在则创建、存在则更新 `type` + `version`（凭 IP）。返回 `DetectorResponse`。

#### `DELETE /api/v1/detectors?id=<id>`

**鉴权**: Admin
**Query**: `id` (uint, 必填)
返回 `204 No Content`。未找到 → `404 detector not found`。

---

### Cameras 摄像头管理

#### `GET /api/v1/cameras`

**鉴权**: Auth
**响应**: `CameraResponse[]` 的分页包装。

```json
// CameraResponse
{
  "id": 1,
  "name": "Front Door",
  "uri": "rtsp://user:pass@192.168.1.10/stream1",
  "streaming_uri": "rtsp://192.168.1.10/stream1",
  "mode": "detect",
  "schedule": { /* JSON, 见 model.Camera.Schedule */ },
  "status": "online",
  "detect_params": { /* JSON */ },
  "default_params": { /* JSON */ },
  "rules": [ /* RuleResponse[] */ ],
  "should_push": false,
  "config_params": { /* JSON */ },
  "sampling": "5m",
  "note": null,
  "snapshot": "snapshots/cam1.jpg",
  "remote_id": "",
  "raw_address": "192.168.1.10",
  "ip": "192.168.1.10",
  "port": 554
}
```

#### `POST /api/v1/cameras`

**鉴权**: Admin
**Body**: `Camera` JSON（除 `id`/`created_at`/`updated_at` 外）。
成功 `201`，返回带数据库写入后字段的对象。

#### `GET /api/v1/cameras/:id`

**鉴权**: Auth **或** Detector IP
**路径参数**: `id` uint

未找到 → `404 camera not found`。

#### `PUT /api/v1/cameras/:id`

**鉴权**: Admin
全量替换（`id` 来自 URL）。

#### `PATCH /api/v1/cameras/:id`

**鉴权**: Auth **或** Detector IP
局部更新（仅出现在 body 里的字段被覆盖，handler 未做 diff，传整个对象即可）。

#### `DELETE /api/v1/cameras/:id`

**鉴权**: Admin
返回 `204`。

#### `POST /api/v1/cameras/:id/enable_sampling`

**鉴权**: Admin
将 `Camera.Sampling` 设为启用（`enableSampling` 在 service 层实现具体策略）。返回 `200 { ret: {} }`。

#### `POST /api/v1/cameras/:id/disable_sampling`

**鉴权**: Admin
对应关闭采样。

#### `GET /api/v1/cameras/:id/stream`

**鉴权**: Auth

返回当前拉流状态：

```json
// 已有 HLS 转码
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "running",
    "playlist": "<internal playlist path>",
    "hls_url": "/hls/camera_1.m3u8",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}
```

```json
// 未启动
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "stopped",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}
```

> 优先使用 `camera.streaming_uri`，未设置时退回 `camera.uri`。

#### `POST /api/v1/cameras/:id/stream/start`

**鉴权**: Admin
启动 ffmpeg → go2rtc → HLS。

返回：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "started",
    "playlist": "<internal playlist path>",
    "hls_url": "/hls/camera_1.m3u8",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}
```

> HLS 切片存放：`{storage.local.path}/hls/camera_<id>.{ts,m3u8}`，经 `/hls/*` 路由鉴权后由 `ServeHLS` 读取。

#### `POST /api/v1/cameras/:id/stream/stop`

**鉴权**: Admin

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": { "status": "stopped" } }
```

#### `GET /api/v1/cameras/:id/snapshot`

**鉴权**: Auth
**响应**: `image/jpeg` 二进制（`c.Data(200, "image/jpeg", snapshot)`），由 `stream.Manager.TakeSnapshot` 通过 ffmpeg 单帧抓取。

未配置 URI → `400 camera has no stream URI configured`。

---

### Events 事件管理

#### `GET /api/v1/events`

**鉴权**: Auth
**支持的 Query 参数**：

| 参数 | 类型 | 说明 |
|------|------|------|
| `camera_id` | uint / 逗号分隔 uint | 单值精确匹配；多值转 `camera_id__in` 语义 |
| `status` | string | 精确匹配 `events.status` |
| `types` | 逗号分隔 string | 不区分大小写；空段会被丢弃 |
| `time_after` | RFC3339 | `started_at >= value` |
| `time_before` | RFC3339 | `started_at <= value` |
| `limit` | int | 默认 20，上限 1000 |
| `offset` | int | 默认 0 |
| `ordering` | string | `"field"`（ASC） / `"-field"`（DESC），字段白名单见 repo；非法 → `id DESC` |

**响应**: 标准分页。`results: EventResponse[]`：

```json
{
  "id": 123,
  "camera_id": 1,
  "started_at": "2026-06-03T08:30:00Z",
  "ended_at": null,
  "mediums": [
    { "id": 456, "name": "frame.jpg", "file": "mediums/event_1/.../frame.jpg", "event_id": 1 }
  ],
  "camera": { /* CameraResponse */ },
  "types": "person,vehicle",
  "types_bits": 6,
  "obj_types": null,
  "uuid": "0c1b...",
  "status": "open",
  "remark": "",
  "should_push": false,
  "metadata": null
}
```

> 任意 query 参数解析失败会**静默忽略**（不返回 400），与 Python 版本行为一致。

#### `GET /api/v1/events/:id`

**鉴权**: Auth
返回单个 `EventResponse`。未找到 → `404 event not found`。

#### `POST /api/v1/events`

**鉴权**: Auth **或** Detector IP
**Body**: `Event` JSON

必填字段：
- `camera_id` (uint)
- `types` (string，去空白后非空)

可选：
- `mediums: [{id, name, file, ...}]` — 仅 `id` 会被采纳，自动设置 `event.medium_id = mediums[0].id`，然后 `event.mediums` 在 handler 中清空（重新加载时由 service 预加载）。

成功 `201`，返回 `EventResponse`，并**广播** SSE/WS `event_create`（受 `frontend.event_popup_enabled` 开关控制）。

#### `PUT /api/v1/events/:id` / `PATCH /api/v1/events/:id`

**鉴权**: Admin
**Body**: 完整 `Event`（`id` 来自 URL）。

> 当前实现：把 `id` 之外的字段**全量覆盖**到数据库行（service 层 `Save` / `Updates`），不是真正的 PATCH 语义。

#### `DELETE /api/v1/events/:id`

**鉴权**: Admin
返回 `204`。

#### `POST /api/v1/events/:id/close_event`

**鉴权**: Admin
关闭事件（设置 `ended_at` 等，具体见 `EventService.CloseEvent`）。

#### `POST /api/v1/events/delete_all`

**鉴权**: Admin
**Body**: `[1, 2, 3]` — uint ID 数组
返回 `204`。

#### `POST /api/v1/events/:id/push_event`

**鉴权**: Auth **或** Detector IP

同 `POST /events`，但在 service 层走 `PushEvent`（语义：可能触发"事件升级 / 推送规则"链路）。成功同样广播 SSE `event_create`。

#### `POST /api/v1/events/queue_analysis`

**鉴权**: Auth **或** Detector IP
**Body**:

```json
{ "camera_name": "Front Door", "type": "motion" }
```

成功 `201`，返回 `EventResponse`。`camera_name` 与 `type` 均必填。

#### `POST /api/v1/events/people_count`

**鉴权**: Auth **或** Detector IP
**Body**:

```json
{
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "eventType": "PeopleCounting",
  "enter": 3,
  "exit": 1,
  "startTime": "2026-06-03T08:00:00Z",
  "endTime": "2026-06-03T08:30:00Z"
}
```

校验：
- `macAddress` 必填
- `eventType` 必须严格等于 `"PeopleCounting"`（其他值 → `400 event_type must be 'PeopleCounting'`）

成功 `201`，返回 `EventResponse`。

#### `GET /api/v1/events/unmarked`

**鉴权**: Auth
返回每个摄像头未标记（`remark == ''`）的事件数：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": [
    { "camera_id": 1, "count": 5 },
    { "camera_id": 2, "count": 0 }
  ]
}
```

> 数据结构由 `EventService.CountUnmarkedByCamera` 返回。

#### `GET /api/v1/events/retrieve_ids`

**鉴权**: Auth
**用途**: Python 兼容 cursor 风格拉取 ID 列表（`id >= start_id`，升序，最多 10000）。

Query 参数：
- `start_id` (uint, 默认 `1`)
- `id` (uint) — 限定单条
- 其它同 `GET /events`（`camera_id` / `status` / `types` / 时间范围 / `limit` / `offset` / `ordering`）

响应：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": { "ids": [101, 102, 103], "total": 3 }
}
```

#### `GET /api/v1/events/retrieves`

**鉴权**: Auth
**用途**: Python 兼容"倒序 + has_next"分页。

Query 参数：
- `start_id` (uint, 默认 `0xffffffff`) — 拉取 `id < start_id`
- `id` (uint) — 限定单条
- `limit` (int, 默认 20, 上限 1000, 负数 → 0)
- 其它同 `GET /events`

响应：

```json
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "objects": [ /* EventResponse[] */ ],
    "total": 7,
    "has_next": true
  }
}
```

> 当传 `?id=<n>` 时走快速路径，直接返回单条 + `has_next: false`。

---

### Rules 规则管理

#### `GET /api/v1/rules`

**鉴权**: Auth
**响应**: `RuleResponse[]` 分页包装。

```json
// RuleResponse
{
  "id": 7,
  "camera": 1,
  "unique_id": "uuid-v4",
  "name": "person-rule",
  "mode": "detect",
  "algo": "yolov8n",
  "params": { /* JSON */ },
  "params_base": { /* JSON */ },
  "schedule": { /* JSON */ },
  "event_types": { "person": "Person" }
}
```

> `event_types` 是从数据库 `JSON` 列中只保留 string→string 键值对后的精简版（`model.RuleResponse` 注释）。

#### `POST /api/v1/rules`

**鉴权**: Admin
**Body**: 完整 `Rule`（`camera_id` 必填）。返回 `201` + `RuleResponse`。

#### `GET /api/v1/rules/:id`

**鉴权**: Auth
未找到 → `404 rule not found`。

#### `PUT /api/v1/rules/:id` / `PATCH /api/v1/rules/:id`

**鉴权**: Admin
**Body**: 局部覆盖（`name` / `mode` / `algo` / `schedule` 出现即覆盖）。

> 注意：`camera_id` 一旦设置后通过此接口**不能修改**。

#### `DELETE /api/v1/rules/:id`

**鉴权**: Admin
返回 `204`。

#### `GET /api/v1/rules/camera/:camera_id`

**鉴权**: Auth
返回该摄像头下的所有规则（标准分页包装）。

#### `POST /api/v1/rules/camera/:camera_id`

**鉴权**: Admin
**Body**: `Rule` JSON（无需包含 `camera_id`，URL 提供）。
返回 `201`。

---

### Mediums 媒体文件

> 文件存于 `{storage.local.path}/mediums/{event_<id>|unassigned}/<timestamp>_<name>.<ext>`，最大 **100MB**。

#### `GET /api/v1/mediums`

**鉴权**: Auth
**响应**: `MediumResponse[]` 分页包装：

```json
{
  "id": 100,
  "name": "frame.jpg",
  "file": "mediums/event_1/1717400000_frame.jpg",
  "event_id": 1
}
```

#### `POST /api/v1/mediums`

**鉴权**: Auth **或** Detector IP
**Content-Type**: `multipart/form-data`
**字段**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | file | 是 | 最大 100MB |
| `name` | string | 否 | 默认取 `file.Filename` |
| `event_id` | uint (form 字段) | 否 | 关联事件 ID |

成功 `201`，返回 `MediumResponse`。

#### `GET /api/v1/mediums/:id`

**鉴权**: Auth
未找到 → `404 medium not found`。

#### `PUT /api/v1/mediums/:id` / `PATCH /api/v1/mediums/:id`

**鉴权**: Admin
**Body**: 局部更新（`name` / `file`）。

> ⚠️ 当前实现直接以 `file` 字符串覆盖原相对路径，**不会**把文件复制/移动到新位置。

#### `DELETE /api/v1/mediums/:id`

**鉴权**: Admin
**副作用**: 同时删除磁盘文件（若 `medium.file` 非空）。返回 `204`。

#### `GET /api/v1/mediums/:id/file`

**鉴权**: Auth
**响应**: 二进制流，附带 `Content-Disposition: inline; filename*=UTF-8''<encoded-name>` 头。

文件缺失 → `404 file not found`。

---

### Webhooks 回调配置

#### `GET /api/v1/webhooks`

**鉴权**: Admin
**响应**: `WebhookResponse[]` 分页：

```json
{
  "id": 1,
  "types": "person,vehicle",
  "url": "https://example.com/hook",
  "serializer": "default"
}
```

#### `POST /api/v1/webhooks`

**鉴权**: Admin
**Body**: 完整 `Webhook` JSON。返回 `201`。

#### `GET /api/v1/webhooks/:id`

**鉴权**: Admin

#### `PUT /api/v1/webhooks/:id` / `PATCH /api/v1/webhooks/:id`

**鉴权**: Admin
**Body**: 局部覆盖（`url` / `types` / `serializer`）。

#### `DELETE /api/v1/webhooks/:id`

**鉴权**: Admin
返回 `204`。

#### `POST /api/v1/webhooks/echo`

**鉴权**: Admin
**Body**: 任意 JSON / 文本（最多读取 1MB）。
**响应**: 把请求体原样以字符串形式回显：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": "{\"foo\":\"bar\"}" }
```

> 用于配置/连通性测试。

---

### Algorithms 算法管理

> 与 `Rule.algo` 字段关联的算法字典表（`code_name` 为主键）。

#### `GET /api/v1/algorithms`

**鉴权**: Auth **或** Detector IP
**响应**: 直接数组（**无**分页包装，`RetArray`）：

```json
{ "err": { "ec": 0, "dm": "ok" }, "ret": [ { "code_name": "yolov8n", "name": "YOLOv8 Nano" } ] }
```

#### `POST /api/v1/algorithms`

**鉴权**: Admin
**Body**:

```json
{ "code_name": "yolov8n", "name": "YOLOv8 Nano" }
```

#### `GET /api/v1/algorithms/:code_name`

**鉴权**: Auth **或** Detector IP
**路径参数**: `code_name` (string, 主键)
未找到 → `404 algorithm not found`。

#### `DELETE /api/v1/algorithms/:code_name`

**鉴权**: Admin
返回 `204`。

---

### Samples 样本管理

> 视频样本聚合（含若干 `SampleFile`），用于后续分析、上传到云端。

#### `GET /api/v1/samples`

**鉴权**: Auth **或** Detector IP
**响应**: `Sample[]` 分页包装。

```json
// Sample
{
  "id": "uuid-string",
  "camera_id": 1,
  "started_at": "2026-06-03T08:00:00Z",
  "ended_at": "2026-06-03T08:05:00Z",
  "notified_cloud": false,
  "notified_cloud_at": null,
  "expired": 0,
  "file_count": 3,
  "types": "person,vehicle",
  "types_at": null,
  "metadata": null,
  "notified_guardian": false,
  "notified_guardian_at": null,
  "event_at": null,
  "created_at": "2026-06-03T08:00:00Z",
  "updated_at": "2026-06-03T08:00:00Z",
  "sample_files": []
}
```

> `id` 是 `char(36)` 字符串（UUID），区别于其它资源的 uint 主键。

#### `POST /api/v1/samples`

**鉴权**: Auth **或** Detector IP
**Body**: 完整 `Sample`（`id` 必填，需为合法 UUID）。

#### `GET /api/v1/samples/:id`

**鉴权**: Auth **或** Detector IP
未找到 → `404 sample not found`。

#### `PUT /api/v1/samples/:id` / `PATCH /api/v1/samples/:id`

**鉴权**: Auth **或** Detector IP
**Body**: 完整 `Sample`（`id` 来自 URL）。

#### `DELETE /api/v1/samples/:id`

**鉴权**: Auth **或** Detector IP
返回 `204`。

#### `POST /api/v1/samples/:id/upload_file`

**鉴权**: Auth **或** Detector IP
**Body**: 完整 `SampleFile` JSON（`id` 字段填入 URL 中的数字 ID）：

```json
{
  "path": "samples/<uuid>/file1.mp4",
  "content_type": "mp4",
  "s3_data": { /* optional JSON */ }
}
```

成功 `201`，返回 `SampleFile`：

```json
{
  "id": 12,
  "sample_id": "<uuid>",
  "path": "samples/<uuid>/file1.mp4",
  "content_type": "mp4",
  "s3_data": null,
  "uploaded_at": null,
  "file_deleted": false,
  "created_at": "2026-06-03T08:00:00Z",
  "updated_at": "2026-06-03T08:00:00Z"
}
```

> 常量 `ContentTypeJPEG = "jpeg"` / `ContentTypePNG = "png"` / `ContentTypeMP4 = "mp4"`（`model.Sample`）。

#### `POST /api/v1/samples/files/:id/mark_uploaded`

**鉴权**: Auth **或** Detector IP
**路径参数**: `id` (uint, `SampleFile.ID`)

将 `SampleFile.UploadedAt` 设为当前时间。返回 `200 { ret: {} }`。

---

### Users 用户管理

#### `GET /api/v1/users`

**鉴权**: Admin
**响应**: `UserResponse[]` 分页：

```json
{ "id": 1, "username": "ops", "is_admin": true, "is_active": true }
```

> `password` 不会出现在响应中（`json:"-"`）。

#### `POST /api/v1/users`

**鉴权**: Admin
**Body**: 完整 `User` JSON。返回 `201`。

> 创建时密码通过 `AuthService.CreateUser` 加 bcrypt（默认 cost）后存储。重复用户名 → 服务层 `ErrUserExists` → `500`（当前实现未专门捕获 409 语义）。

#### `GET /api/v1/users/:id`

**鉴权**: Admin

#### `PUT /api/v1/users/:id` / `PATCH /api/v1/users/:id`

**鉴权**: Admin
**Body**: 局部覆盖（`username` / `is_active` / `is_admin`）。

> 通过此接口**不能**修改密码 — 使用 `POST /api/v1/users/:id/change_password`。

#### `DELETE /api/v1/users/:id`

**鉴权**: Admin
返回 `204`。

#### `POST /api/v1/users/:id/change_password`

**鉴权**: Admin
**Body**:

```json
{ "old_password": "old", "new_password": "new-Str0ng!" }
```

> `AuthService.UpdatePassword`（`user_service.go`）的实际语义是仅验证 `old_password` 与新密码均非空后覆盖哈希。返回 `200 { ret: {} }`。

---

### Settings 系统设置

> KV 表（`name` 唯一索引）。SSE 推送开关即存于此。

#### `GET /api/v1/settings`

**鉴权**: Admin
**响应**: `SettingResponse[]` 分页：

```json
{ "id": 1, "name": "frontend.event_popup_enabled", "value": "true" }
```

#### `POST /api/v1/settings`

**鉴权**: Admin
**Body**: 完整 `Setting` JSON。返回 `201`。

#### `GET /api/v1/settings/:id`

**鉴权**: Admin

#### `GET /api/v1/settings/name/:name`

**鉴权**: Admin
**路径参数**: `name` (string)
未找到 → `404 setting not found`。

#### `PUT /api/v1/settings/:id` / `PATCH /api/v1/settings/:id`

**鉴权**: Admin
**Body**: 局部覆盖（`name` / `value`）。

#### `PUT /api/v1/settings/by-name/:name`

**鉴权**: Admin
**Body**:

```json
{ "value": "true" }
```

**Upsert 语义**：若 `name` 存在则更新 `value`，否则创建新行。

> **副作用**：调用成功后立即失效 SSE 内部的 `frontend.event_popup_enabled` 缓存（30s TTL），使管理界面开关立即生效。

#### `DELETE /api/v1/settings/:id`

**鉴权**: Admin
返回 `204`。

> 预置默认设置（启动时由 `cmd/superbox` 自动创建）：
> - `frontend.event_popup_enabled` = `"true"`

---

### Stream 视频流

#### `GET /api/v1/stream/webrtc/proxy?src=<uri>`

**鉴权**: Auth
**Query**: `src` (string, 必填) — 原始媒体 URI

内部把 `src` 包装为 `ffmpeg:<src>#video=h264`，转发到 go2rtc 的 `http://127.0.0.1:<port>/api/stream.mp4?src=<encoded>`，并将响应体流式复制回客户端，保留 `Content-Type` / `Content-Length` 头。

错误：
- `src` 缺失 → `400 missing src parameter`
- go2rtc 返回非 200 → `500 go2rtc returned status <n>`
- 网络错误 → `500 failed to fetch stream: ...`

#### `GET /hls/*filepath`

**鉴权**: 通过 `?token=` query JWT
**用途**: 暴露 `{storage.local.path}/hls/` 下的转码产物。
**限制**: 文件后缀必须为 `.m3u8` 或 `.ts`，否则 `400 invalid file type`。

> 浏览器 `<video>` 元素播放 HLS 时，URL 模板：
> ```
> /hls/camera_<id>.m3u8?token=<JWT>
> ```

---

## 静态资源

| 路径 | 说明 |
|------|------|
| `/storage/*` | `{storage.local.path}` 下的所有文件（公开） |
| `/assets/*` | 嵌入的前端静态资源（公开） |
| `/admin`, `/admin/*` | 前端 SPA 入口（公开；带路径时回落到 `index.html`） |
| `/` | 前端根入口（公开） |

> 静态资源未走认证，直接 200。

---

## 数据模型

> 完整字段以 GORM tag 为准；以下 JSON 字段是 API 响应里出现的精简版。

### CameraResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `name` | string | 名称 |
| `uri` | string | 主码流 RTSP / HTTP URI |
| `streaming_uri` | string | 备用流地址（缺省时回退到 `uri`） |
| `mode` | string | `detect` / `sample` 等 |
| `schedule` | JSON | 排期（具体 schema 见 `Rule.Schedule`） |
| `status` | string | `online` / `offline` 等（由 `CameraMonitor` 周期刷新） |
| `detect_params` | JSON | 检测相关参数 |
| `default_params` | JSON | 默认参数 |
| `rules` | `RuleResponse[]` | 该摄像头的规则（外键） |
| `should_push` | bool | 是否推送至云 |
| `config_params` | JSON | 其它自定义配置 |
| `sampling` | string | 采样频率字符串（如 `5m`） |
| `note` | JSON | 备注 |
| `snapshot` | string | 静态预览图相对路径（`/storage/<snapshot>` 访问） |
| `remote_id` | string | 云端 ID（边缘同步） |
| `raw_address` | string | 裸 IP / 域名 |
| `ip` | string | 等同于 `raw_address`（保持 Django 字段兼容） |
| `port` | int | RTSP 端口 |

### EventResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `camera_id` | uint | 外键 |
| `started_at` | string (RFC3339Z) | 事件开始 |
| `ended_at` | string? (RFC3339Z) | 事件结束（可空） |
| `mediums` | `MediumResponse[]` | 关联媒体（外键 `EventID`） |
| `camera` | `CameraResponse?` | 嵌套摄像头（service 预加载） |
| `types` | string | 逗号分隔事件类型 |
| `types_bits` | uint64 | 类型位掩码 |
| `obj_types` | JSON | 目标类别详情 |
| `uuid` | string | 唯一 UUID |
| `status` | string | `open` / `closed` / `marked` 等 |
| `remark` | string | 备注（用于"标记"语义） |
| `should_push` | bool | 是否推送至云 |
| `metadata` | JSON | 任意附加元数据 |

### RuleResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `camera` | uint | `camera_id`（字段名 `camera` 保持 Django 兼容） |
| `unique_id` | string | UUID |
| `name` | string | — |
| `mode` | string | `detect` / `sample` |
| `algo` | string | 对应 `algorithms.code_name` |
| `params` | JSON | 当前参数 |
| `params_base` | JSON | 基础参数 |
| `schedule` | JSON | 排期 |
| `event_types` | map[string]string | 仅保留字符串键值对 |

### MediumResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `name` | string | 文件名 |
| `file` | string | 相对 `storage.local.path` 的路径 |
| `event_id` | uint* | 关联事件（可空） |

### DetectorResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `ip` | string | 唯一索引 |
| `type` | string | 设备类型 |
| `version` | string | 固件 / 软件版本 |

> 与 Django 一致：**不**返回 `id`、`created_at`、`updated_at`。

### WebhookResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `types` | string | 触发事件类型，逗号分隔 |
| `url` | string | 目标 URL |
| `serializer` | string | 序列化器名（默认 `default`） |

### UserResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `username` | string | 唯一索引 |
| `is_admin` | bool | 是否管理员 |
| `is_active` | bool | 是否启用 |

### SettingResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | uint | 主键 |
| `name` | string | 唯一索引 |
| `value` | string | 字符串值（无类型） |

### AlgorithmResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| `code_name` | string | 主键 |
| `name` | string | 显示名 |

### Sample / SampleFile

见 `Samples` 章节中的字段说明。

---

## 附录：约束与默认值

### JWT 与登录

- **access token 签名**：HS256
- **密钥**：`config.json → jwt.secret_key`（32 字节 hex，CLI 命令 `superbox jwt key generate -s` 可生成并写回）
- **access token TTL**：`access_token_ttl`（默认 `15m`）；由 JWT `exp` 声明携带，过期即失效
- **refresh token TTL**：`refresh_token_ttl`（默认 `7d`）；由 `refresh_tokens.expires_at` 列存 DB，每次成功 refresh 都重置为 `now + 7d`（**sliding window**）
- **refresh token 格式**：`crypto/rand` 32 字节 → `base64.RawURLEncoding` → 43 字符 `[A-Za-z0-9_-]`
- **refresh token 存储**：服务端**只存 sha256 哈希**（`refresh_tokens.token_hash`），DB 泄露也不暴露明文
- **密码**：bcrypt `DefaultCost`（10）
- **弱密码黑名单**：`password`、`12345678`、`qwerty`、`admin`、`letmein`、`welcome`（不区分大小写）
- **用户名不可等于密码，不可为 `admin`**

### Refresh token 行为

- **Login** 颁发新 pair，INSERT 一行 `refresh_tokens`（`family_id` = 新 UUIDv4）
- **Refresh**（成功）：事务里把旧行 `rotated_at = now()`，INSERT 新行（同 `family_id`、新 hash、`expires_at = now + 7d`）
- **Reuse detection**：被轮换过的旧 token 再次被提交 → `DELETE FROM refresh_tokens WHERE family_id = ?`（杀整个 family），返 401
- **User deactivation / deletion** 在 refresh 时被检测 → 杀 family，401
- **Logout**：删 `user_id + token_hash` 匹配的 1 行；找不到也返 `200`（idempotent）
- **无后台清理任务**（YAGNI）：过期行自然累积，可手工 `DELETE FROM refresh_tokens WHERE expires_at < now()` 或跑 `RefreshTokenRepository.DeleteExpired()`

### 客户端 silent refresh 协议

- 前端 axios 响应拦截器在收到 `401` 时：
  1. 若 `localStorage.refresh_token` 存在且请求**不是** `/auth/refresh` 本身且**未**重试过：调 `/auth/refresh`，成功后用新 token 重发原请求
  2. 否则：清 localStorage、`window.location.href = '/admin/login'`
- **in-flight 去重**：5 个并发 401 共享一个 `/auth/refresh` 请求（模块级 Promise 缓存），避免 strict rotation 误触发 reuse detection

### 多 tab 已知限制

in-flight 去重是**单 page-load** 级别。两个 tab 同时触发 401 时：

- Tab 1 调 `/auth/refresh` 成功，family 已轮换
- Tab 2 调 `/auth/refresh` 命中 reuse detection，family 杀光
- 结果：两个 tab 都被强制重新登录

v1 不修。NVR admin 多 tab 不常见。下次重登即可。后续可加 `BroadcastChannel` 或 `Web Locks API`。

### 事件查询

- `limit` 默认 20，上限 **1000**
- `retrieve_ids` 返回最多 **10000** 条
- `retrieves` 的 `start_id` 默认 `0xffffffff`
- 任何 query 参数解析失败 → 静默忽略（不返回 400）

### 上传与存储

- `mediums` 文件大小上限 **100MB**（`storage.maxUploadSize`）
- 路径规则：`{storage.local.path}/mediums/{event_<id>|unassigned}/<ts_ms>_<safe-name>.<ext>`
- 文件名清洗：保留 `[a-zA-Z0-9_-]`，其它字符 → `_`，最长 50 字符
- `Medium.ServeFile` 时使用 `http.ServeContent`（支持 Range 与 `Last-Modified`）

### HLS 切片

- 文件后缀必须为 `.m3u8` 或 `.ts`，否则 400
- 路径限制在 `{storage.local.path}/hls/` 下

### WebRTC 代理

- 始终以 `ffmpeg:<src>#video=h264` 形式包装原始流，确保浏览器 H264 兼容
- go2rtc 默认端口 `1984`（由 `config.json → stream.go2rtc_port` 修改）

### SSE 推送

- 事件类型：`event_create`（新增）、`event_update`（保留）
- 触发点：`POST /api/v1/events`、`POST /api/v1/events/:id/push_event`（detector 上报 / 业务方创建）
- 受 `settings.frontend.event_popup_enabled` 开关控制（默认启用）
- 缓存 TTL：30 秒；`PUT /settings/by-name/<name>` 会主动失效

### Detector IP 信任

- 仅 `AuthOrDetector` 模式生效
- `detector.ip` 是 `size:64` 字符串（兼容 IPv4/IPv6）
- 触发时 `gin.Context` 写入 `detector_ip`，业务层可读取

### 中间件链顺序（全局）

1. `middleware.Recovery(logger)` — panic 兜底
2. `middleware.Logger(logger)` — 请求日志
3. `middleware.CORS()` — 跨域

### 启动行为（`cmd/superbox`）

- 配置文件查找顺序：`--config` → `viper.AddConfigPath(".", "./config", "/etc/superbox/")` → 默认数据目录
- 缺失时自动生成默认 `config.json`（含随机 JWT key）
- 启动时执行 `AutoMigrate` + `ensureDefaultSettings`（注入 `frontend.event_popup_enabled=true`）
- `CameraMonitor` 默认 `enabled=true`，`interval_sec=30`

### 数据库支持

- `sqlite` / `sqlite3`（默认）
- `postgres` / `postgresql`
- `mysql`（默认）