# 后端模块映射

## 页面导读

- **适用场景**: 适合二次开发人员从业务功能快速定位后端模块、接口分组和源码目录。
- **源码位置**: 后端源码位于 `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。

## 一、工程结构

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
flowchart TB
  A["springboot 聚合工程"] --> B["fastbee-admin"]
  A --> C["fastbee-open-api"]
  A --> D["fastbee-service"]
  A --> E["fastbee-iot-data"]
  A --> F["fastbee-protocol"]
  A --> G["fastbee-server"]
  A --> H["fastbee-record"]
  A --> I["fastbee-notify"]
  A --> J["fastbee-ai"]
  A --> K["fastbee-plugs"]
  A --> L["fastbee-common-extend"]
  A --> M["fastbee-common-media"]
  A --> N["fastbee-media-api"]
  A --> O["fastbee-mq"]
```

## 二、模块职责

| 模块 | 主要职责 | 二开关注点 |
| --- | --- | --- |
| `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` | 源码知识库 |

## 五、二开定位流程

以“设备运行状态新增字段”为例：

1. 前端先定位页面：`vue3/src/views/iot/device`。
2. 查找请求封装：`vue3/src/api/iot`。
3. 根据接口路径定位 Controller：`fastbee-open-api` 中 `/iot/device` 或 `/iot/runtime`。
4. 从 Controller 进入 Service，确认业务逻辑和权限。
5. 查 Mapper 和 Domain，确认数据库字段。
6. 修改 SQL 升级脚本。
7. 更新 OpenAPI 类型和前端页面。
8. 补充文档字段说明和验收点。

## 六、常见二开注意事项

* 不要绕过权限注解和数据权限处理。
* 多租户功能要确认 `create_by`、机构、用户和角色数据范围。
* 设备数据链路要区分实时数据、历史数据、事件日志和指令日志。
* 协议解析不要直接写死到 Controller，优先放到协议模块或服务层。
* 高频设备数据要关注缓存、批量写入和时序库性能。
* 前端接口变更后要更新 OpenAPI 类型和联调 Mock。
* 修改菜单或按钮权限后，需要同步角色授权。

## 七、关联文档

* [Vue3 前端开发与联调](https://www.fastbee.cn/doc/business/v2/dev/vue3-development.html)
* [数据模型与接口映射](https://www.fastbee.cn/doc/business/v2/dev/data-model-map.html)
* [数据库持久层架构](https://www.fastbee.cn/doc/business/v2/dev/database.html)
* [服务端模块](https://www.fastbee.cn/doc/business/v2/dev/server.html)
* [后端架构](https://www.fastbee.cn/doc/business/v2/architecture/backend.html)
