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