fastbee/CLAUDE.md

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）

# 构建所有模块
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，管理后台）

cd yack-web
npm install
npm run dev          # 开发服务器（代理到 localhost:8080）
npm run build:prod   # 生产环境构建
npm run lint         # ESLint 代码检查

前端 - yack-view（Vue 3 + Vite，低代码可视化）

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 移动端）

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: 节点下。

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-20260316.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 接收端口和流信息。