# 告警管理系统 API 接口文档（Django 版）

> 基础路径：`/api/v1`
> 服务器地址：`http://192.168.28.32:8000`
> 认证方式：Bearer Token（24h 有效期）
> 统一响应信封：`{ "err": { "ec": 0, "dm": "ok" }, "ret": <data> }`

---

## 目录

1. [认证接口](#1-认证接口)
2. [事件（告警）接口](#2-事件告警接口)
3. [摄像头接口](#3-摄像头接口)
4. [规则接口](#4-规则接口)
5. [算法接口](#5-算法接口)
6. [WebSocket 接口](#6-websocket-接口)
7. [通用响应格式](#7-通用响应格式)
8. [认证与 Token 管理](#8-认证与-token-管理)
9. [前端数据转换说明](#9-前端数据转换说明)
10. [完整调用示例](#10-完整调用示例)
11. [附录：前端 API 方法速查表](#11-附录前端-api-方法速查表)

---

## 1. 认证接口

---

### 1.1 登录

- **方法**：`POST`
- **路径**：`/auth/login`
- **描述**：用户登录，获取 Token
- **鉴权**：无（公开）

**请求头**：
```http
Content-Type: application/json
Accept: application/json
```

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `username` | `string` | 是 | 用户名 |
| `password` | `string` | 是 | 密码 |
| `cookieless` | `string` | 是 | `"True"` 或 `"False"` |

```json
{
    "username": "admin",
    "password": "123456",
    "cookieless": "False"
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "token": "eyJhbGciOiJIUzI1NiIs..."
    }
}
```

| 返回字段 | 类型 | 说明 |
|---------|------|------|
| `ret.token` | `string` | JWT Token，有效期 24h |

**失败响应**：
```json
{
    "err": { "ec": 1001, "dm": "用户名或密码错误" }
}
```

---

### 1.2 登出

- **方法**：`POST`
- **路径**：`/auth/logout`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**请求体**：无

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```

---

### 1.3 添加用户

- **方法**：`POST`
- **路径**：`/auth/adduser`
- **鉴权**：Bearer Token（需管理员权限）

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `username` | `string` | 是 | 用户名 |
| `password` | `string` | 是 | 密码 |
| `email` | `string` | 否 | 邮箱，默认为空 |

```json
{
    "username": "operator1",
    "password": "pass123456",
    "email": ""
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```

---

### 1.4 删除用户

- **方法**：`POST`
- **路径**：`/auth/rmuser`
- **鉴权**：Bearer Token（需管理员权限）

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `username` | `string` | 是 | 要删除的用户名 |

```json
{
    "username": "operator1"
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```

---

### 1.5 获取所有用户

- **方法**：`GET`
- **路径**：`/auth/allusers`
- **鉴权**：Bearer Token（需管理员权限）

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**请求参数**：无

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "users": [
            {
                "username": "admin",
                "email": ""
            },
            {
                "username": "operator1",
                "email": "op1@example.com"
            }
        ]
    }
}
```

| 返回字段 | 类型 | 说明 |
|---------|------|------|
| `ret.users` | `array` | 用户列表 |
| `ret.users[].username` | `string` | 用户名 |
| `ret.users[].email` | `string` | 邮箱 |

---

### 1.6 重置用户信息

- **方法**：`POST`
- **路径**：`/auth/resetuser`
- **鉴权**：Bearer Token（需管理员权限）

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `username` | `string` | 是 | 用户名 |
| `password` | `string` | 是 | 新密码 |
| `email` | `string` | 是 | 邮箱 |

```json
{
    "username": "operator1",
    "password": "newpass123",
    "email": "op1@example.com"
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```


---

## 2. 事件（告警）接口

---

### 2.1 获取事件列表（分页）

- **方法**：`GET`
- **路径**：`/events`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**查询参数（Query）**：

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `limit` | `number` | 否 | `20` | 每页条数 |
| `offset` | `number` | 否 | `0` | 偏移量 |

**请求示例**：
```
GET /api/v1/events?limit=20&offset=0
Authorization: Bearer <token>
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "count": 1617,
        "next": "http://192.168.28.32:8000/api/v1/events?limit=20&offset=20",
        "previous": null,
        "results": [
            {
                "id": 90908,
                "camera_id": 1,
                "started_at": "2026-04-01T09:30:00Z",
                "ended_at": "2026-04-01T09:30:10Z",
                "mediums": [
                    {
                        "id": 109656,
                        "name": "snapshot",
                        "file": "http://192.168.28.32:8000/media/mediums/2026/04/02/camera1_xxx.jpg",
                        "event_id": 90908
                    }
                ],
                "camera": {
                    "id": 1,
                    "name": "421枪机",
                    "uri": "rtsp://admin:1234qwer@192.168.28.102:554/Streaming/Channels/202",
                    "mode": "on",
                    "status": "online",
                    "detect_params": { "threshold": 0.5 },
                    "default_params": {},
                    "rules": [ /* RuleItem[] 见规则结构 */ ],
                    "should_push": false,
                    "config_params": {},
                    "sampling": false,
                    "note": {},
                    "snapshot": "http://192.168.28.32:8000/media/camera/camera1_snapshot.jpg",
                    "remote_id": -1,
                    "raw_address": "0b8342ec52e62d01dd3273f583d326ec",
                    "ip": "admin:1234qwer@192.168.28.102:554",
                    "port": 8082
                },
                "types": "wander",
                "types_bits": 0,
                "obj_types": {},
                "uuid": "461aeb6e-10f3-4173-9b33-d540ce59511e",
                "status": "pending",
                "remark": null,
                "should_push": false,
                "metadata": {}
            }
        ]
    }
}
```

**前端返回**：
```typescript
{
    tableData: EventItem[],   // ret.results
    totalItems: number        // ret.count
}
```

---

### 2.2 按参数筛选事件列表

- **方法**：`GET`
- **路径**：`/events`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**查询参数（Query）**：

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `limit` | `number` | 否 | `20` | 每页条数 |
| `offset` | `number` | 否 | `0` | 偏移量 |
| `time_before` | `string` | 否 | — | 结束时间（ISO 8601） |
| `time_after` | `string` | 否 | — | 开始时间（ISO 8601） |
| `types` | `string` | 否 | — | 告警类型编码（如 `wander`） |
| `camera_id` | `number` | 否 | — | 摄像头 ID |
| `status` | `string` | 否 | — | 状态：`pending` / `closed` |

**请求示例**：
```
GET /api/v1/events?limit=20&offset=0&time_after=2026-04-01T00%3A00%3A00Z&time_before=2026-04-02T00%3A00%3A00Z&types=wander&camera_id=1&status=pending
Authorization: Bearer <token>
```

**成功响应（200 OK）**：同 2.1 响应结构。

---



---

### 2.3 获取单个事件详情

- **方法**：`GET`
- **路径**：`/event/events/retrieves`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**查询参数（Query）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `id` | `number` | 是 | 事件 ID |

**请求示例**：
```
GET /api/v1/event/events/retrieves?id=90908
Authorization: Bearer <token>
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "objects": [
            {
                "id": 90908,
                "camera_id": 1,
                "started_at": "2026-04-01T09:30:00Z",
                "ended_at": "2026-04-01T09:30:10Z",
                "mediums": [
                    {
                        "id": 109656,
                        "name": "snapshot",
                        "file": "http://192.168.28.32:8000/media/mediums/2026/04/02/camera1_xxx.jpg",
                        "event_id": 90908
                    }
                ],
                "camera": { /* CameraItem 见摄像头结构 */ },
                "types": "wander",
                "types_bits": 0,
                "obj_types": {},
                "uuid": "461aeb6e-10f3-4173-9b33-d540ce59511e",
                "status": "pending",
                "remark": null,
                "should_push": false,
                "metadata": {}
            }
        ]
    }
}
```

**前端取值**：`res.data.ret.objects[0]`

---

### 2.4 获取最新一条事件

- **方法**：内部调用 `getEvents(token, 1, 1)`
- **路径**：`/events?limit=1&offset=0`
- **鉴权**：Bearer Token

**成功响应**：同 2.1，但 `results` 只有一条，`count` 为总条数。

---

### 2.5 修改事件状态

- **方法**：`PATCH`
- **路径**：`/events/{eventId}`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `eventId` | `number` | 事件 ID |

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `status` | `string` | 是 | 状态值：`pending` / `closed` |
| `remark` | `string` | 否 | 备注信息 |

```json
{
    "status": "closed",
    "remark": "已处理完毕"
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```

---

### 2.6 删除事件

- **方法**：`DELETE`
- **路径**：`/event/events/{eventId}`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `eventId` | `number` | 事件 ID |

**请求体**：无

**成功响应**：`204 No Content`（无 body）

**失败响应**（如事件不存在）：
```json
{
    "err": {
        "ec": 404,
        "dm": "Not Found",
        "em": "Not found."
    }
}
```



---

### 2.7 事件对象完整结构（EventItem）

```typescript
interface EventItem {
    id: number;                    // 告警 ID
    camera_id: number;             // 摄像头 ID
    started_at: string;            // 开始时间（ISO 8601）
    ended_at: string;              // 结束时间（ISO 8601）
    types: string;                 // 告警类型编码（如 "wander"）
    types_bits: number;            // 类型位标记
    obj_types: Record<string, any>; // 目标类型
    uuid: string;                  // 唯一标识
    status: 'pending' | 'closed';  // 处理状态
    remark: string | null;         // 备注
    should_push: boolean;          // 是否推送
    metadata: Record<string, any>; // 元数据

    // 多媒体
    mediums: Array<{
        id: number;
        name: string;              // 如 "snapshot"
        file: string;              // 图片 URL（已规范化）
        event_id: number;
    }>;

    // 关联摄像头
    camera: CameraItem;
}
```

---

## 3. 摄像头接口

---

### 3.1 获取摄像头列表

- **方法**：`GET`
- **路径**：`/camera/cameras/get_all`
- **鉴权**：Bearer Token

**请求头**：

```http
Authorization: Bearer <access_token>
Accept: application/json
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "count": 10,
        "results": [ 
            		{
                        "id": 1,
                        "name": "421枪机",
                        "uri": "rtsp://{camerastream}",
                        "mode": "on",
                        "status": "online",
                        "detect_params": {
                            "threshold": 0.5
                        },
                        "default_params": {},
                        "rules": [
                            {
                                "id": 1,
                                "unique_id": "1268f3f2-e0c5-47ea-aa1f-5b97b6dfb95d",
                                "camera": 1,
                                "name": "规则名称",
                                "mode": "on",
                                "algo": "rule-name",
                                "params": {},
                                "params_base": "",
                                "schedule": {},
                                "event_types": {
                                    "规则英文": "别名，中文映射"
                                }
                            }
                        ],
                        "should_push": false,
                        "config_params": {},
                        "sampling": false,
                        "note": {},
                        "snapshot": "URL***.jpg",
                        "remote_id": -1,
                        "raw_address": "0b8342ec52e62d01dd3273f583d326ec",
                        "ip": "camera-url",
                        "port": 8082
                    }
             	]
    }
}
```

---



---

### 3.2 获取单个摄像头详情

- **方法**：`GET`
- **路径**：`/camera/cameras/{cameraId}`
- **鉴权**：Bearer Token

**请求头**：

```http
Authorization: Bearer <access_token>
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `cameraId` | `number` | 摄像头 ID |

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": { /* CameraItem */ }
}
```

---

### 3.3 更新摄像头信息

- **方法**：`PATCH`
- **路径**：`/camera/cameras/{cameraId}`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `cameraId` | `number` | 摄像头 ID |

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | `string` | 否 | 摄像头名称 |
| `mode` | `"on"` / `"off"` | 是 | 检测模式 |

```json
{
    "name": "421枪机",
    "mode": "on"
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": { /* CameraItem */ }
}
```

---

### 3.4 启动摄像头视频流

- **方法**：`POST`
- **路径**：`/camera/cameras/{cameraId}/start_stream`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `cameraId` | `number` | 摄像头 ID |

**请求体**：无

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {
        "port": 8094
    }
}
```

| 返回字段 | 类型 | 说明 |
|---------|------|------|
| `ret.port` | `number` | 动态分配的 WebSocket 端口，用于 JSMpeg 视频播放 |

---

### 3.5 停止摄像头视频流

- **方法**：`POST`
- **路径**：`/camera/cameras/{cameraId}/stop_stream`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `cameraId` | `number` | 摄像头 ID |

**请求体**：无

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": {}
}
```

---

### 3.8 摄像头对象完整结构（CameraItem）

```typescript
interface CameraItem {
    id: number;
    name: string;                 // 点位名称（如 "421枪机"）
    uri: string;                  // RTSP 地址
    mode: 'on' | 'off';          // 检测全局开关
    status: 'online' | 'offline'; // 在线状态
    detect_params: {
        threshold: number;        // 检测阈值（如 0.5）
    };
    default_params: Record<string, any>;
    rules: RuleItem[];            // 关联规则列表
    should_push: boolean;
    config_params: Record<string, any>;
    sampling: boolean;
    note: Record<string, any>;
    snapshot: string;             // 快照图片 URL（已规范化）
    remote_id: number;
    raw_address: string;
    ip: string;
    port: number;
}
```

**前端发送的 CameraData 类型**（用于 updateCamera）：
```typescript
interface CameraData {
    id?: number;
    name?: string;
    mode?: "on" | "off";
    rules?: RuleData[] | {};
}
```

---

## 4. 规则接口

---

### 4.1 更新规则

- **方法**：`PATCH`
- **路径**：`/rules/{ruleId}`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

**路径参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `ruleId` | `number` | 规则 ID |

**请求体（Body JSON）**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `id` | `number` | 是 | 规则 ID |
| `name` | `string` | 否 | 规则名称 |
| `mode` | `"on"` / `"off"` / `"schedule"` | 否 | 规则模式 |
| `schedule` | `object` | 否 | 时间段配置 |

```json
{
    "id": 1,
    "name": "徘徊",
    "mode": "on",
    "schedule": {}
}
```

**带时间段的请求**：
```json
{
    "id": 1,
    "name": "未穿反光衣",
    "mode": "schedule",
    "schedule": {
        "type": "daily",
        "time_slots": [
            [
                960,
                1020
            ]
        ]
    }
}
```

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": { /* RuleItem */ }
}
```



---

### 4.2 规则对象完整结构（RuleItem）

```typescript
interface RuleItem {
    id: number;
    unique_id: string;             // UUID
    camera: number;                // 关联摄像头 ID
    name: string;                  // 规则名称（如 "徘徊"）
    mode: 'on' | 'off' | 'schedule';
    algo: string;                  // 算法编码（如 "wander"）
    params: Record<string, any>;
    params_base: string;
    schedule: {
        type: string;              // 如 "daily"
        time_slots?: Array<[number, number]>;
    } | {};
    event_types: Record<string, string>; // 如 { "wander": "人员徘徊" }
}
```

---

## 5. 算法接口

---

### 5.1 获取算法列表

- **方法**：`GET`
- **路径**：`/algorithms`
- **鉴权**：Bearer Token

**请求头**：
```http
Authorization: Bearer <access_token>
Accept: application/json
```

**请求参数**：无

**成功响应（200 OK）**：
```json
{
    "err": { "ec": 0, "dm": "ok" },
    "ret": [
        { "code_name": "wander", "name": "人员徘徊" },
        { "code_name": "intrusion", "name": "入侵" },
        { "code_name": "no_reflective_clothing", "name": "未佩戴反光衣" }
    ]
}
```

| 返回字段 | 类型 | 说明 |
|---------|------|------|
| `ret[]` | `array` | 算法列表（无分页包装） |
| `ret[].code_name` | `string` | 算法编码（如 `wander`） |
| `ret[].name` | `string` | 算法中文名称（如 `人员徘徊`） |

### 5.2 算法映射表

```typescript
interface AlgorithmItem {
    code_name: string;   // 算法编码（如 "wander"）
    name: string;        // 算法中文名称（如 "人员徘徊"）
}
```

登录时自动拉取并构建 `Map<code_name, name>` 映射，供全局以编码查中文名。

---

## 6. WebSocket 接口

### 6.1 事件监听通道 WebSocket

- **地址**：`ws://192.168.28.32:8080/ws/event`
- **代理地址（Vite 开发环境）**：`/ws/event`

### 6.2 推送消息格式

```json
{
    "id": 90908,
    "camera_id": 1,
    "started_at": "2026-04-01T09:30:00Z",
    "ended_at": "2026-04-01T09:30:10Z",
    "types": "wander",
    "status": "pending",
    "camera": { "id": 1, "name": "421枪机" },
    "mediums": [ { "id": 109656, "name": "snapshot", "file": "http://192.168.28.32:8000/media/mediums/xxx.jpg" } ]
}
```

### 6.3 视频流 WebSocket

- **地址**：`ws://{host}:{dynamicPort}/`
- **说明**：由 `startCameraStream` 返回动态端口，JSMpeg 直接连接播放

---

## 7. 通用响应格式

### 7.1 成功响应

```json
{
    "err": {
        "ec": 0,
        "dm": "ok"
    },
    "ret": { /* 响应数据 */ }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `err.ec` | `number` | 错误码，`0` 表示成功 |
| `err.dm` | `string` | 状态描述，成功时为 `"ok"` |
| `ret` | `object` / `array` | 返回的数据主体 |

### 7.2 错误响应

```json
{
    "err": {
        "ec": 1001,
        "dm": "错误描述信息"
    }
}
```

### 7.3 常见错误码

| 错误码 | 说明 |
|--------|------|
| `0` | 成功 |
| `1001` | 参数错误 |
| `1002` | 认证失败 |
| `1003` | 权限不足 |
| `1004` | 资源不存在 |
| `1005` | 操作失败 |

### 7.4 HTTP 状态码

| 状态码 | 说明 | 前端处理 |
|--------|------|----------|
| `200 OK` | 请求成功 | 正常处理 |
| `201 Created` | POST 创建成功 | 正常处理 |
| `204 No Content` | DELETE / 无业务数据 PATCH | 视作成功 |
| `400 Bad Request` | 参数错误 | 提示错误信息 |
| `401 Unauthorized` | 未授权 / Token 过期 | 清除 Token，跳转登录页 |
| `403 Forbidden` | 权限不足 | 提示无权限 |
| `404 Not Found` | 资源不存在 | 提示未找到 |
| `500 Internal Server Error` | 服务器内部错误 | 提示服务器错误 |

---

## 8. 认证与 Token 管理

### 8.1 Token 有效期

- Token 有效期：**24 小时**
- 前端每 **30 分钟** 检查一次 Token 是否过期
- 过期后自动清除 Token 并跳转到登录页

### 8.2 请求头格式

```http
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
```

### 8.3 拦截器行为

- **请求拦截**：每次请求前检查 Token 是否过期（`checkTokenExpiry`）
- **响应拦截**：收到 `401` 状态码时自动清除 Token 并跳转登录

---

## 9. 前端数据转换说明

### 9.1 URL 规范化

后端返回的 JSON 中包含内部地址（如 `http://127.0.0.1:8000/media/...`），前端自动转换为：
- `http://127.0.0.1:8000/xxx` → `http://<实际服务器IP>:8000/xxx`
- `http://localhost:8000/xxx` → `http://<实际服务器IP>:8000/xxx`

适用字段：
- `mediums[].file`（事件图片）
- `camera.snapshot`（摄像头快照）
- 顶层 `snapshot` / `file`
- `next` / `previous` 分页链接

### 9.2 分页结构

所有列表接口统一分页格式：
```typescript
{
    count: number,      // 总条数
    next: string|null,  // 下一页 URL
    previous: string|null, // 上一页 URL
    results: T[]        // 当前页数据
}
```

---

## 10. 完整调用示例

### 10.1 登录并获取事件列表

```typescript
import { BoxApi } from '@/utils/boxApi';

const api = new BoxApi();

// 登录
const token = await api.login('admin', 'password');

// 获取事件（第1页，每页20条）
const { tableData, totalItems } = await api.getEvents(token, 20, 1);

// 按条件筛选
const { results, count } = await api.getEventsByParams(
    token, 20, 1,
    '2026-04-01T00:00:00Z', '2026-04-02T00:00:00Z',
    'wander', null, 'pending'
);

// 获取所有摄像头
const cameras = await api.getAllCameras(token);

// 更新事件状态
await api.setEventStatus(90908, 'closed', '已处理', token);

// 删除事件
await api.delEvents(token, [90908, 90909]);
```

### 10.2 摄像头管理

```typescript
// 获取单个摄像头详情（含规则）
const camera = await api.getCameraById(token, 1);

// 更新摄像头基本设置
await api.updateCamera(token, 1, { name: '421枪机', mode: 'on' });

// 批量更新规则
await api.updateRule(token, [
    { id: 1, camera: 1, name: '徘徊', mode: 'on' },
    { id: 32, camera: 1, name: '入侵', mode: 'schedule', schedule: { type: 'daily', time_slots: [[480, 720]] } }
]);

// 启动视频流
const { port } = await api.startCameraStream(token, 1);

// 停止视频流
await api.stopCameraStream(token, 1);
```

---

## 11. 附录：前端 API 方法速查表

| 方法 | HTTP 方法 | 路径 | 请求体/参数 | 响应体 |
|------|-----------|------|------------|--------|
| `login()` | POST | `/auth/login` | `{username, password, cookieless}` | `{token}` |
| `logout()` | POST | `/auth/logout` | 无 | `{}` |
| `addUser()` | POST | `/auth/adduser` | `{username, password, email?}` | `{}` |
| `rmUser()` | POST | `/auth/rmuser` | `{username}` | `{}` |
| `getAllUsers()` | GET | `/auth/allusers` | — | `{users: [...]}` |
| `resetUser()` | POST | `/auth/resetuser` | `{username, password, email}` | `{}` |
| `getEvents()` | GET | `/events?limit=&offset=` | — | `{count, next, prev, results}` |
| `getEventsByParams()` | GET | `/events?limit=&offset=&...` | — | `{count, next, prev, results}` |
| `getEventsByUrl()` | GET | 自定义 URL | — | `{count, next, prev, results}` |
| `getEventById()` | GET | `/event/events/retrieves?id=` | — | `{objects: [EventItem]}` |
| `getOneEvent()` | GET | `/events?limit=1&offset=0` | — | `{count, next, prev, results}` |
| `setEventStatus()` | PATCH | `/events/{id}` | `{status, remark?}` | `{}` |
| `delEvents()` | DELETE | `/event/events/{id}` | 无 | `[{id, success, message?}]` |
| `getCameras()` | GET | `/cameras?limit=&offset=` | — | `{count, results: [...]}` |
| `getCamerasByUrl()` | GET | 自定义 URL | — | `{count, results: [...]}` |
| `getAllCameras()` | GET | `/camera/cameras/get_all` | — | `CameraItem[]` |
| `getCameraById()` | GET | `/camera/cameras/{id}` | — | `CameraItem` |
| `updateCamera()` | PATCH | `/camera/cameras/{id}` | `{name, mode}` | `CameraItem` |
| `startCameraStream()` | POST | `/camera/cameras/{id}/start_stream` | 无 | `{port}` |
| `stopCameraStream()` | POST | `/camera/cameras/{id}/stop_stream` | 无 | `{}` |
| `updateRule()` | PATCH | `/rules/{id}` | `{id, camera, name?, mode?, schedule?}` | `RuleItem` |
| `getAlgorithms()` | GET | `/algorithms` | — | `AlgorithmItem[]` |
| `getAlgorithmName()` | — | 本地映射 | `code_name: string` | `string`（中文名） |