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