# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

IoT 设备管理前端，基于 Vue 3 + Vben Admin 框架构建的 Turborepo monorepo。包含 4 个 UI 框架变体（Ant Design、Element Plus、Naive UI、TDesign），共享核心代码库。

**生产部署信息：**
- **容器名称：** `aiot-web-antd`（生产使用 Ant Design 版本）
- **端口映射：** 9090:80
- **部署位置：** 腾讯云服务器 `/opt/vsp-platform`
- **后端 API：** http://服务器IP:48080（芋道微服务网关）
- **访问地址：** http://服务器IP:9090
- **默认账号：** admin / admin123

## 常用命令

### 安装依赖

```bash
# 需要 pnpm 10.0.0+ 和 Node.js 20.19.0+
pnpm install
```

### 本地开发

```bash
# 运行 Ant Design 版本（生产使用）
pnpm dev:antd

# 运行其他版本
pnpm dev:ele        # Element Plus
pnpm dev:naive      # Naive UI
pnpm dev:tdesign    # TDesign

# 开发服务器默认端口：5666
# 访问：http://localhost:5666
```

### 构建

```bash
# 构建 Ant Design 版本
pnpm build:antd

# 构建所有版本
pnpm build

# 构建其他版本
pnpm build:ele
pnpm build:naive
pnpm build:tdesign
```

### 代码质量

```bash
# 代码检查
pnpm lint

# 代码格式化
pnpm format

# TypeScript 类型检查
pnpm check:type

# 检查循环依赖
pnpm check:circular
```

### 测试

```bash
# 单元测试（Vitest）
pnpm test:unit

# E2E 测试（Playwright）
pnpm test:e2e
```

### 清理

```bash
# 清理构建产物
pnpm clean

# 清理并重新安装依赖
pnpm reinstall
```

### Docker 部署（生产环境）

```bash
# 构建 Ant Design 版本镜像
cd apps/web-antd
docker build -t aiot-web-antd:latest .

# 运行容器
docker run -d \
  --name aiot-web-antd \
  -p 9090:80 \
  -e VITE_BASE_URL=http://服务器IP:48080 \
  aiot-web-antd:latest

# 查看日志
docker logs -f aiot-web-antd

# 重启容器
docker restart aiot-web-antd
```

## 项目结构

### 目录组织

```
iot-device-management-frontend/
├── apps/                    # 应用层（4 个 UI 框架变体）
│   ├── web-antd/           # Ant Design 版本（生产使用）
│   ├── web-ele/            # Element Plus 版本
│   ├── web-naive/          # Naive UI 版本
│   └── web-tdesign/        # TDesign 版本
├── packages/               # 共享包
│   ├── @core/             # 核心库（框架无关）
│   │   ├── base/          # 基础库（design tokens, icons, shared）
│   │   ├── composables/   # Vue composables
│   │   ├── preferences/   # 设置管理
│   │   └── ui-kit/        # UI 组件（form, layout, menu, popup, tabs）
│   ├── effects/           # 功能包
│   │   ├── access/        # 访问控制
│   │   ├── hooks/         # React-like hooks
│   │   ├── layouts/       # 布局组件
│   │   └── plugins/       # 插件（echarts, vxe-table等）
│   └── constants/         # 共享常量
├── internal/              # 内部工具
│   ├── lint-configs/      # ESLint、Prettier、Stylelint 配置
│   ├── tsconfig/          # TypeScript 配置
│   ├── vite-config/       # Vite 配置
│   └── tailwind-config/   # Tailwind CSS 配置
└── docs/                  # 文档站点
```

### 核心概念

**Workspace 架构：**
- 使用 pnpm workspaces 管理 monorepo
- 使用 Turborepo 进行构建优化
- 所有 apps 共享 `@core` 和 `effects` 包
- 修改 `@core` 包自动反映到所有 apps（Vite HMR）

**包命名规范：**
- `@vben/` — Vben Admin 框架包
- `@core/` — 项目核心包
- `workspace:*` — workspace 内部依赖

## 关键页面路由

### AIoT 告警管理
- `/aiot/alarm/event` — 告警事件列表
  - 分页、筛选、统计
  - 实时 WebSocket 推送
  - 告警处理（确认、忽略、派单）

### 边缘设备管理
- `/aiot/edge/device` — 边缘设备列表
  - 设备状态监控
  - 告警数统计

### 摄像头与 ROI 管理
- `/aiot/camera` — 摄像头管理
  - 摄像头列表、添加、编辑
  - 与 WVP 平台同步
- `/aiot/roi` — ROI 区域配置
  - ROI 绘制（polygon）
  - 算法绑定配置

## 环境配置

### 开发环境（apps/web-antd/.env.development）

```bash
VITE_PORT=5666                          # 开发服务器端口
VITE_BASE_URL=http://127.0.0.1:48080   # 后端 API 地址
VITE_GLOB_API_URL=/admin-api            # API 路径前缀
VITE_DEVTOOLS=false                     # Vue DevTools
VITE_APP_DEFAULT_USERNAME=admin         # 默认用户名
VITE_APP_DEFAULT_PASSWORD=admin123      # 默认密码
```

### 生产环境（apps/web-antd/.env.production）

```bash
VITE_BASE_URL=http://服务器IP:48080
VITE_GLOB_API_URL=/admin-api
```

## API 集成

### 后端接口（通过 aiot-gateway 48080）

**告警事件：**
- `GET /admin-api/aiot/alarm/event/page` — 分页查询
- `GET /admin-api/aiot/alarm/event/get` — 获取详情
- `PUT /admin-api/aiot/alarm/event/handle` — 处理告警
- `GET /admin-api/aiot/alarm/event/statistics` — 统计

**边缘设备：**
- `GET /admin-api/aiot/edge/device/page` — 分页查询
- `GET /admin-api/aiot/edge/device/statistics` — 统计

**WebSocket（直连 vsp-service 8000）：**
- `ws://服务器IP:8000/ws/alerts` — 实时告警推送

### API 调用示例

```typescript
// 使用 @vben/request 统一请求工具
import { requestClient } from '@vben/request';

// 查询告警列表
const response = await requestClient.get('/admin-api/aiot/alarm/event/page', {
  params: { pageNo: 1, pageSize: 20 }
});

// 处理告警
await requestClient.put('/admin-api/aiot/alarm/event/handle', {
  id: alarmId,
  handleStatus: 'CONFIRMED',
  handleRemark: '已确认'
});
```

## 开发工作流

### 添加新页面
1. 在 `apps/web-antd/src/views/` 下创建页面组件
2. 在 `apps/web-antd/src/router/routes/modules/` 添加路由配置
3. 如果是共享组件，放到 `packages/@core/ui-kit/` 或 `packages/effects/common-ui/`

### 修改共享组件
1. 修改 `packages/@core/ui-kit/` 下的组件
2. Vite HMR 自动刷新所有使用该组件的 apps
3. 无需重新构建

### 添加 API 接口
1. 在 `apps/web-antd/src/api/` 创建 API 文件
2. 使用 `requestClient` 发起请求
3. 定义 TypeScript 类型

### 国际化（i18n）
- 语言文件：`apps/web-antd/src/locales/langs/`
- 中文：`zh-CN/`
- 英文：`en-US/`

## 常见问题

### pnpm install 失败
```bash
# 清理并重装
pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### 构建失败：循环依赖
```bash
# 检查循环依赖
pnpm check:circular
```

### 类型错误
```bash
# 运行类型检查
pnpm check:type
```

### WebSocket 连接失败
检查 vsp-service 是否运行：
```bash
docker logs vsp-service
```

## Git 提交规范

在修改代码后，使用中文提交信息：

```bash
git add .
git commit -m "功能：添加XXX功能

详细说明...

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
```

**不要立即 push**，等待用户指示再推送到远程。