202 lines
12 KiB
Markdown
202 lines
12 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
FastBee 是一个基于若依框架构建的物联网平台（v3.8.5）。后端为多模块 Spring Boot 应用（Java 8，Spring Boot 2.5.14），前端包含三个独立应用。所有 Java 包名使用 `com.fastbee`。
|
||
|
||
## 构建命令
|
||
|
||
### 后端（Java/Maven）
|
||
```bash
|
||
# 构建所有模块
|
||
mvn clean package
|
||
|
||
# 跳过测试构建
|
||
mvn clean package -DskipTests
|
||
|
||
# 构建指定模块
|
||
mvn clean package -pl fastbee-admin -am -DskipTests
|
||
```
|
||
|
||
可运行的 JAR 文件生成在 `fastbee-admin/target/`。通过 `fastbee.sh start|stop|restart|status` 启动/停止服务。
|
||
|
||
### 前端 - yack-web（Vue 2，管理后台）
|
||
```bash
|
||
cd yack-web
|
||
npm install
|
||
npm run dev # 开发服务器（代理到 localhost:8080）
|
||
npm run build:prod # 生产环境构建
|
||
npm run lint # ESLint 代码检查
|
||
```
|
||
|
||
### 前端 - yack-view（Vue 3 + Vite，低代码可视化）
|
||
```bash
|
||
cd yack-view
|
||
pnpm install # 推荐使用 pnpm（npm 可能出现依赖下载失败）
|
||
pnpm dev # Vite 开发服务器
|
||
pnpm build # 生产环境构建
|
||
# 或使用 npm：
|
||
npm install
|
||
npm run dev
|
||
npm run build
|
||
# 或使用 Makefile：
|
||
make dev
|
||
make dist
|
||
```
|
||
部署：编译文件上传至 Nginx `/var/data/nginx/view/`，配置 `location ^~/view/` 挂载。访问地址：`https://[域名]/view/`。
|
||
|
||
### 前端 - yack-app（UniApp 移动端）
|
||
```bash
|
||
cd yack-app
|
||
npm install
|
||
# 通过 HBuilderX 或 uni-app CLI 构建
|
||
```
|
||
配置：修改 `env.config.js` 设置服务端接口地址和 MQTT 地址。支持微信小程序、Android、iOS、H5。UI 框架为 uView 2.0。
|
||
|
||
### Docker 部署
|
||
`docker/` 目录包含 `docker-compose.yml` 和 EMQX 配置。用于快速部署完整 IoT 平台环境。
|
||
|
||
## 架构说明
|
||
|
||
### 后端模块结构
|
||
|
||
```
|
||
fastbee-admin/ # Spring Boot 入口（端口 8080），Web 层
|
||
fastbee-framework/ # 安全配置、拦截器、核心框架装配
|
||
fastbee-common/ # 公共工具类、领域模型、注解、常量
|
||
fastbee-open-api/ # REST API 控制器（对外暴露的接口）
|
||
fastbee-service/
|
||
fastbee-iot-service/ # IoT 业务逻辑（设备、产品、规则）
|
||
fastbee-system-service/ # 系统管理（用户、角色、菜单）
|
||
fastbee-server/ # 基于 Netty 的协议服务器
|
||
base-server/ # 抽象服务器基类
|
||
iot-server-core/ # IoT 服务器核心逻辑，消息分发
|
||
mqtt-broker/ # 内嵌 MQTT Broker（EMQX 的替代方案）
|
||
http-server/ # HTTP 设备接入服务器（端口 8081）
|
||
tcp-server/ # TCP 服务器（端口 8888）
|
||
coap-server/ # CoAP 服务器（端口 5683）
|
||
sip-server/ # SIP 服务器（GB28181 视频监控，需配合 ZLMediaKit 流媒体服务器）
|
||
boot-strap/ # 服务器启动引导
|
||
fastbee-protocol/ # 协议编解码
|
||
base/ # 协议抽象层
|
||
collect/ # 数据采集协议实现
|
||
fastbee-iot-data/ # IoT 时序数据存储（支持 TDengine）
|
||
fastbee-mq/ # RocketMQ 消息队列集成
|
||
fastbee-notify/ # 多渠道通知系统
|
||
fastbee-record/ # 设备数据记录/持久化（视频录像需配合 ZLMediaKit）
|
||
fastbee-plugs/
|
||
generator/ # 代码生成器（Velocity 模板）
|
||
quartz/ # 定时任务管理
|
||
ruleEngine/ # LiteFlow 规则引擎（IoT 场景自动化）
|
||
oss/ # 对象存储（S3/阿里云 OSS）
|
||
mqtt-client/ # MQTT 客户端插件
|
||
oauth/ # OAuth 2.0（JustAuth）
|
||
pay/ # 支付集成
|
||
http/ # Forest HTTP 客户端配置
|
||
```
|
||
|
||
### 关键架构模式
|
||
|
||
**数据流（设备 → 平台）：** 设备 → 协议服务器（Netty，端口因协议而异）→ `iot-server-core` 消息分发器 → RocketMQ → `fastbee-record` 持久化 → MySQL/TDengine。实时推送通过 WebSocket 发送至前端。
|
||
|
||
**MQTT Broker 模式：** 通过 `server.broker.enabled` 配置 — `true` 使用内嵌 Netty Broker（端口 1883/8083）；`false` 使用外部 EMQX Broker。
|
||
|
||
**规则引擎：** LiteFlow 规则链存储在 `iot_scene` 表，脚本存储在 `iot_script` 表。规则在启动时从数据库加载，支持可选的轮询刷新机制。
|
||
|
||
**多数据源：** 动态数据源（主 MySQL + 可选 TDengine `taos` 数据源）。TDengine 默认禁用（`enabled: false`）。
|
||
|
||
**认证方式：** 通过 `Authorization` 请求头传递 JWT Token。Token 配置在 `application.yml` 的 `token:` 节点下。
|
||
|
||
**权限策略（重要）：** 后端接口权限基于若依 `@PreAuthorize("@ss.hasPermi(...)" )` / `@ss.hasAnyPermi(...)`。`sys_menu.menu_type = C` 通常代表页面权限，`menu_type = F` 代表按钮/功能权限。由于前端页面会跨模块复用选择器/列表/详情接口（例如设备计算公式页面复用产品物模型接口、数据中心复用设备/场景接口），读接口、列表接口、下拉选择器、详情接口应优先使用 `hasAnyPermi`，允许“接口原所属权限 + 实际使用页面的页面级权限”。示例：`@PreAuthorize("@ss.hasAnyPermi('iot:model:list,iot:device:list')")`。写接口（新增/修改/删除/导入/导出）不要默认用页面 `list` 权限放开；只有确认该写操作属于该页面功能时，才追加对应页面的 `add/edit/remove` 权限，例如设备页维护计算公式可考虑 `iot:model:edit,iot:device:edit`。
|
||
|
||
**API 文档：** 服务运行时可通过 `/swagger-ui/index.html` 访问 Swagger/OpenAPI 文档。
|
||
|
||
### 前端架构
|
||
|
||
- **yack-web**：Vue 2 + Element UI + Vuex + Vue Router。管理后台，消费后端 REST API。`vue.config.js` 中的代理配置指向 `localhost:8080`。
|
||
- **yack-view**：Vue 3 + TypeScript + Vite + Naive UI + Pinia。独立的低代码可视化设计器（基于 GoView）。单独部署，通常挂载在 Nginx 的 `/view/` 路径下。
|
||
- **yack-app**：UniApp（Vue 2 语法）iOS/Android 移动端，通过 MQTT.js 和 HTTP 与平台通信。
|
||
|
||
## 运行时配置
|
||
|
||
`application-dev.yml` 关键配置：
|
||
- MySQL：`localhost:3306/fastbee`，用户名 `root`，密码 `fastbee`
|
||
- Redis：在 `application-dev.yml` 中单独配置（Redisson 单节点模式）
|
||
- 激活的 Profile 在 `application.yml` 中设置：`spring.profiles.active: prod`（本地开发时改为 `dev`）
|
||
|
||
本地开发请切换至 dev profile —— prod profile 需要生产环境基础设施支持。
|
||
|
||
## 数据库
|
||
|
||
SQL 初始化脚本位于 `sql/` 目录。主数据库：`fastbee`。最新完整脚本：`sql/yack-init.sql`（共 117 张表）。
|
||
|
||
### 数据库通用约定
|
||
|
||
- **多租户**：大多数 IoT 表含 `tenant_id` / `tenant_name` 字段
|
||
- **审计字段**：`create_by`、`create_time`、`update_by`、`update_time`
|
||
- **软删除**：`del_flag`（0=正常，2=删除）
|
||
- **国际化**：单独的 `*_translate` 表存储多语言翻译
|
||
- **复杂数据**：物模型、配置等使用 JSON 列存储
|
||
|
||
### 主要表分类
|
||
|
||
**告警监控**：`iot_alert`（告警定义）、`iot_alert_log`（告警历史）、`iot_alert_notify_template`、`iot_alert_scene`、`iot_device_alert_user`
|
||
|
||
**设备管理**：`iot_device`（设备注册表）、`iot_device_group`、`iot_device_record`（导入/分配/回收历史）、`iot_device_share`（设备共享权限）、`iot_device_user`（设备归属）、`iot_keep_user`（运维人员）
|
||
|
||
**产品管理**：`iot_product`（产品定义）、`iot_category`（产品分类，层级结构）、`iot_things_model`（物模型，1380+ 条）、`iot_things_model_template`（物模型模板）、`iot_product_authorize`（授权码）
|
||
|
||
**网关与子设备**：`iot_sub_gateway`（网关-子设备关系）、`iot_product_sub_gateway`（产品级网关-子产品映射）
|
||
|
||
**Modbus 配置**：`iot_modbus_config`、`iot_modbus_job`（轮询任务）、`iot_modbus_params`（产品级参数模板）、`iot_product_modbus_job`、`iot_var_temp`（采集变量模板）、`iot_var_temp_salve`
|
||
|
||
**规则引擎**：`iot_scene`（场景自动化，LiteFlow 规则链）、`iot_script`（规则脚本）、`bridge`（数据桥接端点：HTTP/MQTT/数据库）、`iot_script_bridge`、`iot_device_job`（设备定时任务）
|
||
|
||
**场景编排**：`scene_model`（场景管理）、`scene_model_data`（数据源绑定）、`scene_model_device`、`scene_model_tag`（输入变量）、`scene_tag_points`（计算变量）、`iot_scene_device`、`iot_scene_script`
|
||
|
||
**数据日志**：`iot_device_log`（设备事件日志）、`iot_event_log`、`iot_function_log`（服务调用日志）、`iot_device_air_log`（Air780 上报）、`iot_simulate_log`（模拟设备日志）
|
||
|
||
**固件升级**：`iot_firmware`（固件版本）、`iot_firmware_task`（升级任务）、`iot_firmware_task_detail`（逐设备状态跟踪）
|
||
|
||
**SCADA 与可视化**：`iot_goview_project`（GoView 可视化项目）、`iot_goview_project_data`、`scada`（SCADA 页面）、`scada_component`（UI 组件）、`scada_device_bind`（组件-设备绑定）、`scada_echart`、`scada_gallery`（图标库，3896+ 条）、`scada_model`（3D 模型）
|
||
|
||
**SIP 与媒体**：`sip_device`（摄像头/录像机）、`sip_device_channel`、`sip_config`、`iot_sip_relation`、`media_server`（流媒体服务器）
|
||
|
||
**OAuth 与认证**：`oauth_client_details`（支持 DuerOS/AliGenie/小米）、`oauth_access_token`、`oauth_refresh_token`、`oauth_approvals`、`oauth_code`、`sys_auth_user`（第三方登录）
|
||
|
||
**通知系统**：`notify_channel`（邮件/短信等渠道）、`notify_template`（消息模板）、`notify_log`（发送历史）
|
||
|
||
**系统管理（若依 RBAC）**：`sys_user`、`sys_role`、`sys_menu`（3430+ 菜单项）、`sys_dept`（117+ 部门）、`sys_post`、`sys_user_role`、`sys_role_menu`、`sys_role_dept`、`sys_config`、`sys_dict_type`（166+ 类型）、`sys_dict_data`（738+ 条）、`sys_oper_log`、`sys_logininfor`、`sys_job`、`sys_job_log`、`sys_notice`、`sys_client`、`sys_user_relation`
|
||
|
||
**定时任务（Quartz）**：`qrtz_job_details`、`qrtz_triggers`、`qrtz_cron_triggers`、`qrtz_simple_triggers`、`qrtz_fired_triggers`、`qrtz_scheduler_state`、`qrtz_locks` 等共 11 张表
|
||
|
||
**对象存储**：`oss_config`（S3/阿里云 OSS 配置）、`oss_detail`（文件上传历史）
|
||
|
||
**代码生成**：`gen_table`、`gen_table_column`
|
||
|
||
**其他**：`iot_group`（设备分组）、`iot_protocol`（支持的通信协议）、`iot_social_platform`（第三方登录平台）、`app_language`（4 种语言）、`app_preferences`（用户偏好）、`command_preferences`（指令预设模板，120+）、`order_control`（指令权限控制）、`news`/`news_category`（新闻资讯）
|
||
|
||
## 代码生成
|
||
|
||
代码生成器模块（`fastbee-plugs/generator`）使用 Velocity 模板生成 Java + Vue 的 CRUD 脚手架代码。模板位于 `fastbee-plugs/generator/src/main/resources/vm/`。
|
||
|
||
## MQTT 协议端口
|
||
|
||
| 协议 | 端口 | 说明 |
|
||
|:---|:---|:---|
|
||
| mqtt | 1883 | 未加密 TCP，硬件/服务端使用 |
|
||
| mqtts | 8883 | 加密 TCP，硬件/服务端使用 |
|
||
| ws | 8083 | 未加密 WebSocket，前端/移动端使用 |
|
||
| wss | 8084 | 加密 WebSocket，通过代理访问 8083 |
|
||
| wxs | 8084 | 微信小程序专用 |
|
||
|
||
微信小程序和 App 端使用 `wxs://` 协议连接 MQTT。
|
||
|
||
## GB28181 视频监控
|
||
|
||
`fastbee-server/sip-server` 实现国标 GB28181 协议，支持摄像头/录像机接入、设备直播、录像拉取、PTZ 云台控制。需部署 ZLMediaKit 流媒体服务器，通过其 API（`/index/api/`）管理 RTP 接收端口和流信息。
|