后端模块映射
页面导读
适用场景适合二次开发人员从业务功能快速定位后端模块、接口分组和源码目录。
源码位置后端源码位于 `D:\project\gitlab\wumei-smart\springboot`。
技术栈Java 21、Spring Boot 3.5、MyBatis Plus、Sa-Token、Spring AI、TDengine、IoTDB、RocketMQ、Redisson。
使用方式先按业务模块定位 Controller，再追踪 Service、Mapper、Domain、SQL 和前端 API。
一、工程结构
二、模块职责
| 模块 | 主要职责 | 二开关注点 |
|---|---|---|
fastbee-admin | 系统管理、监控、登录、Swagger、后台基础能力 | 用户、角色、菜单、日志、系统配置 |
fastbee-open-api | 物联网平台主要业务接口 | 产品、设备、物模型、规则、场景、视频、组态、报表、卡管理 |
fastbee-service | 通用业务服务和基础服务 | 公共业务逻辑、系统服务复用 |
fastbee-iot-data | 设备运行数据、时序数据、历史数据处理 | TDengine、IoTDB、实时数据、历史数据 |
fastbee-protocol | 设备协议编解码和适配 | MQTT、TCP、HTTP、Modbus、JT808 等协议扩展 |
fastbee-server | MQTT/TCP/SIP/ISUP 等服务端能力 | 网络服务启动、会话、信令、设备连接 |
fastbee-record | 录像服务、ZLM Hook、回放相关能力 | 云端录像、录像查询、媒体 Hook |
fastbee-notify | 通知渠道、模板、日志、发送服务 | 邮箱、短信、微信、钉钉、HTTP 推送 |
fastbee-ai | AI 对话、模型、知识库、协议适配、NL2SQL | 大模型接入、RAG、知识库、AI 二开 |
fastbee-plugs | Quartz、代码生成、OSS、OAuth 等插件 | 定时任务、文件存储、代码生成、SSO |
fastbee-common-extend | 公共扩展能力 | 通用工具、公共 Controller |
fastbee-common-media | 媒体公共能力 | 视频播放、媒体服务公共对象 |
fastbee-media-api | 外部媒体平台集成 | 大华 ICC 等第三方媒体平台 |
fastbee-mq | 消息队列相关能力 | RocketMQ 或其他 MQ 扩展 |
三、Controller 分组
fastbee-open-api 是业务接口最集中的模块，Controller 按业务目录划分：
| 分组 | 典型接口 | 对应业务 |
|---|---|---|
device | /iot/device、/iot/deviceUser、/iot/share | 设备、设备用户、分享、分配 |
deviceConfig | /iot/template、/iot/deviceExtValue | 设备模板、扩展参数 |
deviceLog | /iot/record、/iot/message | 设备日志、消息记录 |
protocol | /iot/protocol | 协议管理 |
runtime | /iot/runtime | 运行态数据 |
modbus | /api/modbus、/modbus/config、/modbus/job | Modbus 配置、采集任务 |
gateway | /sub/gateway | 网关与子设备 |
ruleEngine | /iot/ruletrigger、/iot/bridge、/iot/alert | 规则、桥接、告警 |
ruleview | /rule/chain、/rule/node、/ruleview/parser | 可视化规则编辑器 |
sceneModel | /scene/model、/scene/modelData | 场景模型、变量、设备 |
sip、media | /sip/*、/common/player、/iot/channel | 视频、SIP、播放、PTZ、通道 |
datacenter | 报表、历史数据相关接口 | 数据中心、报表 |
goview | /goview/project、/goview/projectData | 可视化大屏 |
firmware | /iot/firmware、/iot/business/firmware/task | OTA 固件和升级任务 |
card | 物联网卡相关接口 | 卡平台、SIM 卡、流量 |
operations | 维保、工单等接口 | 运维闭环 |
translate | /app/language、/app/preferences | 多语言、偏好配置 |
wechat、socialUser | 微信、社交用户 | 小程序、公众号、绑定 |
四、AI 模块接口
| Controller | 接口前缀 | 用途 |
|---|---|---|
AiChatController | /ai/chat | AI 对话 |
AiChatRecordController | /ai/chatRecord | 对话记录 |
AiProviderController | /ai/provider | 模型供应商 |
AiModelController | /ai/model | 模型配置 |
AiKnowledgeController | /ai/knowledge | 知识库 |
AiKnowledgeDocumentController | /ai/knowledge/document | 知识文档 |
AiKnowledgeVersionController | /ai/knowledge/version | 知识库版本 |
AiProtocolAdaptationController | /ai/protocol/adaptation | 协议适配 |
AiProtocolKnowledgeController | /ai/protocol/knowledge | 协议知识 |
AiNl2SqlController | /ai/nl2sql | 自然语言查询 |
AiCodebaseGuideKnowledgeController | /ai/knowledge/codebase | 源码知识库 |
五、二开定位流程
以“设备运行状态新增字段”为例：
- 前端先定位页面：
vue3/src/views/iot/device。 - 查找请求封装：
vue3/src/api/iot。 - 根据接口路径定位 Controller：
fastbee-open-api中/iot/device或/iot/runtime。 - 从 Controller 进入 Service，确认业务逻辑和权限。
- 查 Mapper 和 Domain，确认数据库字段。
- 修改 SQL 升级脚本。
- 更新 OpenAPI 类型和前端页面。
- 补充文档字段说明和验收点。
六、常见二开注意事项
- 不要绕过权限注解和数据权限处理。
- 多租户功能要确认
create_by、机构、用户和角色数据范围。 - 设备数据链路要区分实时数据、历史数据、事件日志和指令日志。
- 协议解析不要直接写死到 Controller，优先放到协议模块或服务层。
- 高频设备数据要关注缓存、批量写入和时序库性能。
- 前端接口变更后要更新 OpenAPI 类型和联调 Mock。
- 修改菜单或按钮权限后，需要同步角色授权。