iot-device-management-frontend/CLAUDE.md

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

常用命令

安装依赖

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

本地开发

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

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

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

构建

# 构建 Ant Design 版本
pnpm build:antd

# 构建所有版本
pnpm build

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

代码质量

# 代码检查
pnpm lint

# 代码格式化
pnpm format

# TypeScript 类型检查
pnpm check:type

# 检查循环依赖
pnpm check:circular

测试

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

# E2E 测试（Playwright）
pnpm test:e2e

清理

# 清理构建产物
pnpm clean

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

Docker 部署（生产环境）

# 构建 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）

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）

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 调用示例

// 使用 @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 失败

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

构建失败：循环依赖

# 检查循环依赖
pnpm check:circular

类型错误

# 运行类型检查
pnpm check:type

WebSocket 连接失败

检查 vsp-service 是否运行：

docker logs vsp-service

Git 提交规范

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

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

详细说明...

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

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