From f68b4e8b2394b75bd68cae93bc6d6d726eacc425 Mon Sep 17 00:00:00 2001 From: 16337 <1633794139@qq.com> Date: Thu, 5 Mar 2026 16:29:17 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E5=88=9B=E5=BB=BA?= =?UTF-8?q?=20CLAUDE.md=20=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容： - 项目概述和生产部署信息（aiot-web-antd 容器） - 常用命令（安装、开发、构建、测试、Docker 部署） - 项目结构说明（Turborepo monorepo 架构） - 关键页面路由（告警管理、设备管理、ROI 配置） - 环境配置说明（开发和生产环境） - API 集成指南（芋道网关、WebSocket） - 开发工作流（添加页面、共享组件、API 接口） - 常见问题排查 - Git 提交规范 Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 297 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 297 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..faacd14b6 --- /dev/null +++ b/CLAUDE.md @@ -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 " +``` + +**不要立即 push**，等待用户指示再推送到远程。