16337
f68b4e8b23
新增内容： - 项目概述和生产部署信息（aiot-web-antd 容器） - 常用命令（安装、开发、构建、测试、Docker 部署） - 项目结构说明（Turborepo monorepo 架构） - 关键页面路由（告警管理、设备管理、ROI 配置） - 环境配置说明（开发和生产环境） - API 集成指南（芋道网关、WebSocket） - 开发工作流（添加页面、共享组件、API 接口） - 常见问题排查 - Git 提交规范 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
298 lines
7.0 KiB
Markdown
298 lines
7.0 KiB
Markdown
# 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**，等待用户指示再推送到远程。
|