# AGENTS.md

本文档包含针对此 Vue 3 + TypeScript 本地告警管理应用的智能编码代理指南。

## 开发命令

| 命令 | 说明 |
|------|------|
| `npm install` | 安装依赖 |
| `npm run dev` | 启动热重载开发服务器（8000端口） |
| `npm run build` | 构建生产版本（包含类型检查） |
| `npm run type-check` | 仅运行 TypeScript 类型检查 |
| `npm run preview` | 本地预览生产构建 |

> 本项目目前未配置测试框架。

## 项目结构

```
src/
├── components/      # 可复用 Vue 组件
├── html/           # 页面级 Vue 组件
├── utils/          # 工具函数和 API
│   ├── boxApi.ts               # 主 API 接口
│   ├── useGlobalWebSocket.ts  # WebSocket 管理
│   ├── crossWindowChannel.ts   # 跨窗口通信
│   └── eventBus.ts             # 事件总线（mitt）
├── router/         # Vue Router 配置
└── stores/        # Pinia 状态管理
```

## 代码风格指南

### TypeScript
- 路径别名：`@/` 映射到 `src/`
- 始终为 props 和数据接口添加类型

### Vue 组件
- 使用 `<script setup>` 组合式 API
- 使用 `defineProps<T>()` 和 `defineEmits<T>()`

### 导入顺序
```typescript
// 1. Vue 导入
import { ref, computed, onMounted } from 'vue'

// 2. 第三方库
import axios from 'axios'
import { ElMessage } from 'element-plus'

// 3. 内部导入（@ 别名）
import { BoxApi } from '@/utils/boxApi'
```

### 命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 组件 | PascalCase | `CameraRules.vue` |
| 变量 | camelCase | `selectedAlerts` |
| 常量 | UPPER_SNAKE_CASE | `MAX_COUNT` |
| 函数 | fetch/handle/format 前缀 | `fetchEvents` |

### 错误处理
- 异步操作使用 try-catch
- 使用 `ElMessage.error()` 显示错误
- 在 axios 拦截器中处理 401 响应

## 常用模式

### 跨窗口通信
```typescript
import { broadcast, onCrossWindowMessage } from '@/utils/crossWindowChannel'

// 发送
broadcast.sendDialog(data)

// 接收
onCrossWindowMessage((msg) => { /* 处理 */ })
```

### 事件总线
```typescript
import eventBus from '@/utils/eventBus'

eventBus.emit('showDialog', data)
eventBus.on('showDialog', (data) => { /* 处理 */ })
```

### 告警列表导出（支持跨页勾选）
```typescript
// 选中导出：selectedAlerts.value 存储勾选的 ID
// 无勾选：导出当前筛选条件下的所有数据
```

## 注意事项

- 这是一个安防摄像头告警管理系统
- 中文 UI 文本是有意保留的
- 跨窗口通信使用 BroadcastChannel，需同源策略
- WebSocket 连接地址：`ws://192.168.28.32:8080/ws/event`
- API 基础地址：`http://192.168.28.32:8000/api/v1`



## 补充说明：
event接口
GET请求，/api/v1/event

响应体如下：

```
{
    "err": {
        "ec": 0,
        "dm": "ok"
    },
    "ret": {
        "count": 1617,
        "next": "http://127.0.0.1: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://127.0.0.1:8000/media/mediums/2026/04/02/camera1_1775035800_wander_OHtwpT0.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": [
                        {
                            "id": 1,
                            "unique_id": "1268f3f2-e0c5-47ea-aa1f-5b97b6dfb95d",
                            "camera": 1,
                            "name": "徘徊",
                            "mode": "on",
                            "algo": "wander",
                            "params": {},
                            "params_base": "",
                            "schedule": {},
                            "event_types": {
                                "wander": "人员徘徊"
                            }
                        },
                        {
                            "id": 32,
                            "unique_id": "9c5e2f2d-4d0e-4ca7-97ee-866462664f8e",
                            "camera": 1,
                            "name": "入侵",
                            "mode": "on",
                            "algo": "intrusion",
                            "params": {},
                            "params_base": "",
                            "schedule": {},
                            "event_types": {
                                "intrusion": "入侵"
                            }
                        },
                        {
                            "id": 35,
                            "unique_id": "fdd29eaa-c07a-43c4-ad6c-171d9dfadcf4",
                            "camera": 1,
                            "name": "未穿反光衣",
                            "mode": "on",
                            "algo": "no_reflective_clothing",
                            "params": {},
                            "params_base": "",
                            "schedule": {},
                            "event_types": {
                                "no_reflective_clothing": "未佩戴反光衣"
                            }
                        }
                    ],
                    "should_push": false,
                    "config_params": {},
                    "sampling": false,
                    "note": {},
                    "snapshot": "http://127.0.0.1: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": {}
            }]
```



## 本次修改记录（2026年4月）

### 问题描述

部署到服务器后，前端通过 HTTPS 访问 (`https://192.168.28.32`)，但后端返回的 JSON 数据中包含内部地址（如 `http://127.0.0.1:8000/media/...`），导致：

1. **图片无法显示** - 告警列表、详情、通道预览图等全部异常
2. **分页 next/previous URL 异常** - 指向 `http://127.0.0.1:8000/...`
3. **Channel/CenterTop 摄像头预览图异常** - `http://127.0.0.1:8000/media/camera/...`

### 问题原因

后端 Django 在内部请求自己的 API 时，返回的 JSON 数据中使用的是内部地址 `127.0.0.1:8000`，而不是前端实际访问的服务器地址。

### 解决方案

在 `boxApi.ts` 中添加 `normalizeBackendUrls` 方法，将后端返回的 URL 统一转换为正确地址。

### 修改原理

```typescript
private normalizeBackendUrls(data: any): any {
    // 强制使用 http + 8000 端口
    const baseUrl = `http://${window.location.hostname}:8000`;

    const replaceHost = (url: string | null | undefined): string | null => {
        if (!url) return null;
        return url
            .replace(/https?:\/\/127\.0\.0\.1(?::8000)?/gi, baseUrl)
            .replace(/https?:\/\/localhost(?::8000)?/gi, baseUrl);
    };

    // 处理多种数据格式...
}
```

**转换示例**：
- `http://127.0.0.1:8000/media/xxx.jpg` → `http://192.168.28.32:8000/media/xxx.jpg`
- `http://localhost:8000/media/xxx.jpg` → `http://192.168.28.32:8000/media/xxx.jpg`

### 修改的文件

| 文件 | 修改内容 |
|------|---------|
| `src/utils/boxApi.ts` | 添加 normalizeBackendUrls 方法，在多个 API 接口中调用 |
| `src/utils/superboxApi.ts` | 添加 URL 规范化支持（备用） |
| `src/components/Cameras.vue` | 修复硬编码 IP `192.168.28.33` |
| `vite.config.ts` | 添加 /media 和 /ws 代理配置 |

### 已修复的接口

| 接口方法 | 返回数据 | 处理的字段 |
|---------|---------|-----------|
| `getEvents` | 事件列表 | `results[].mediums[].file`, `results[].camera.snapshot` |
| `getEventsByParams` | 事件列表 | 同上 + `next`, `previous` 分页链接 |
| `getEventsByUrl` | 事件列表 | 同上 |
| `getEventById` | 单个事件 | `mediums[].file`, `camera.snapshot` |
| `getAllCameras` | 摄像头列表 | `[].snapshot` |
| `getCameraById` | 单个摄像头 | `.snapshot` |

### 视频点播（WebSocket）说明

- **接口**：`startCameraStream` 返回动态端口（如 8094）
- **连接方式**：前端直接连接 `ws://192.168.28.32:8094/`
- **限制**：需要服务器开放对应端口，或配置 Apache 动态代理
- **Vite 代理**：仅开发环境有效，部署后需服务器端配置

### Vite 开发代理配置

开发环境代理配置（`vite.config.ts`）：

```typescript
proxy: {
    '/api': {
        target: 'http://192.168.28.32:8000', 
        changeOrigin: true,  
    },
    '/media': {
        target: 'http://192.168.28.32:8000',
        changeOrigin: true,
    },
    '/ws': {
        target: 'ws://192.168.28.32:8080',
        ws: true,
    }
}
```

**注意**：此配置仅开发环境有效，部署后需配置服务器端代理（Apache/Nginx）。

### API 统一使用说明

- 项目统一使用 `BoxApi` 类进行 API 调用
- `SuperboxApi` 为遗留代码，未被页面使用
- 所有页面通过 `new BoxApi()` 创建实例调用接口


### 通道视频安全模式观看方式

> chrome://flags/#unsafely-treat-insecure-origin-as-secure（非安全模式在可开启通知权限）

- 权限开启允许不安全文件