# 设备接入服务 (Device Access Service)

## 项目简介

设备接入服务(DAS) 是一个基于 Java Spring Boot 技术栈构建的雷达设备接入平台，采用领域驱动设计(DDD)思想，旨在为不同类型的雷达设备提供统一的、可扩展的接入方案。服务通过 MQTT 协议与设备进行通信，实现设备信息上报、状态监控、跌倒检测、点云数据处理等功能。

## 项目架构

本项目遵循领域驱动设计(DDD)的分层架构，具体划分为：

-   **应用层** (device-service-application): 负责协调领域服务，处理应用级别的业务逻辑，如设备命令处理、事件协调和数据转换。
-   **领域层** (device-service-domain): 项目的核心，包含了所有业务核心逻辑，如设备实体、点云处理、姿态识别、领域服务和仓储接口。
-   **基础设施层** (device-service-infrastructure): 提供技术实现，如数据库访问、MQTT消息处理、第三方服务接口的实现。
-   **通用层** (device-service-common): 包含跨模块的通用类，如常量定义、DTO对象、工具类和配置。
-   **客户端启动器** (device-service-client-starter): 为其他服务提供与本服务交互的Feign客户端。
-   **服务启动** (device-service-server): Spring Boot应用的入口，负责组装和启动整个服务。
-   **Python参考服务** (das): 用于对比和验证的Python版本实现，提供与Java服务等价的功能逻辑。

### 架构依赖图

```mermaid
graph TD;
    subgraph "应用层 Application"
        A["device-service-application"]
        A1["controller<br/>Web/WAP控制器"]
        A2["service<br/>应用服务层"]
        A21["DeviceCommandService"]
        A22["DeviceEventService"]
        A3["convert<br/>数据转换器"]
        A4["dto<br/>数据传输对象"]
        A5["task<br/>定时任务"]
        
        A -- 包含 --> A1 & A2 & A3 & A4 & A5
        A2 -- 包含 --> A21 & A22
    end

    subgraph "领域层 Domain"
        B["device-service-domain"]
        B1["entity<br/>领域实体"]
        B11["Device<br/>设备实体"]
        B12["AlarmPlan<br/>告警计划"]
        B13["BehaviorPattern<br/>行为模式"]
        B2["service<br/>领域服务"]
        B21["PointCloudProcessService<br/>点云处理服务"]
        B22["AlarmService<br/>告警服务"]
        B23["DeviceService<br/>设备服务"]
        B3["port/gateway<br/>端口接口"]
        B31["DeviceEventPort<br/>设备事件端口"]
        B32["DeviceGateway<br/>设备网关"]
        B33["MqttGateway<br/>MQTT网关"]
        B4["event<br/>领域事件"]
        B41["DeviceEvent<br/>设备事件"]
        B42["FallEvent<br/>跌倒事件"]
        B5["vo<br/>值对象"]
        B51["PoseAnalysisResult<br/>姿态分析结果"]
        B52["TargetPoint<br/>目标点"]

        B -- 包含 --> B1 & B2 & B3 & B4 & B5
        B1 -- 包含 --> B11 & B12 & B13
        B2 -- 包含 --> B21 & B22 & B23
        B3 -- 包含 --> B31 & B32 & B33
        B4 -- 包含 --> B41 & B42
        B5 -- 包含 --> B51 & B52
    end

    subgraph "基础设施层 Infrastructure"
        C["device-service-infrastructure"]
        C1["gateway/impl<br/>网关实现"]
        C11["DeviceGatewayImpl"]
        C12["MqttGatewayImpl"]
        C2["mqtt<br/>MQTT消息处理"]
        C21["DeviceMessageHandler<br/>设备消息处理器"]
        C22["AppMessageHandler<br/>应用消息处理器"]
        C23["MpsMessageHandler<br/>小程序消息处理器"]
        C24["OpcMessageHandler<br/>运维消息处理器"]
        C25["MqttHandlerImpl<br/>统一消息路由"]
        C3["config<br/>配置管理"]
        C31["MqttConfig<br/>MQTT配置"]
        C32["RedisConfig<br/>Redis配置"]
        C4["mapper<br/>数据映射"]
        C5["service<br/>基础服务"]

        C -- 包含 --> C1 & C2 & C3 & C4 & C5
        C1 -- 包含 --> C11 & C12
        C2 -- 包含 --> C21 & C22 & C23 & C24 & C25
        C3 -- 包含 --> C31 & C32
    end

    subgraph "通用层 Common"
        D["device-service-common"]
        D1["constant<br/>常量定义"]
        D11["MqttTopics<br/>MQTT主题"]
        D12["DeviceErrorCode<br/>设备错误码"]
        D2["dto<br/>数据传输对象"]
        D21["DeviceDTO<br/>设备DTO"]
        D22["EventDTO<br/>事件DTO"]
        D3["util<br/>工具类"]
        D31["PointCloudUtil<br/>点云工具"]
        D32["JsonUtil<br/>JSON工具"]
        D4["enums<br/>枚举"]
        D41["ModelType<br/>模型类型"]
        D42["PoseType<br/>姿态类型"]
        D5["annotation<br/>注解"]
        D51["MqttSubscriber<br/>MQTT订阅注解"]

        D -- 包含 --> D1 & D2 & D3 & D4 & D5
        D1 -- 包含 --> D11 & D12
        D2 -- 包含 --> D21 & D22
        D3 -- 包含 --> D31 & D32
        D4 -- 包含 --> D41 & D42
        D5 -- 包含 --> D51
    end

    subgraph "客户端启动器 Client"
        E["device-service-client-starter"]
        E1["feign<br/>Feign客户端"]
        E11["TokenFacadeFeign<br/>令牌服务客户端"]
        E12["LogLoginFacadeFeign<br/>登录日志客户端"]
    end

    subgraph "Python参考服务"
        P["das"]
        P1["mqtt_recv.py<br/>消息接收处理"]
        P2["mqtt_send.py<br/>消息发送处理"]
        P3["dev_mng.py<br/>设备管理"]
        P4["mydef.py<br/>核心定义和工具"]

        P -- 包含 --> P1 & P2 & P3 & P4
    end

    %% 模块间依赖关系
    A --> B & D
    C --> B & D
    B --> D
    E --> D

    %% 接口与实现关系
    C11 --. 实现 .-> B32
    C12 --. 实现 .-> B33
    A21 --. 实现 .-> B31

    %% 业务调用流
    C2 --. 调用 .-> A2
    A2 --. 调用 .-> B2
    A2 --. 调用 .-> B3

    %% Python与Java功能映射
    P1 --. 功能映射 .-> C2
    P2 --. 功能映射 .-> C12
    P3 --. 功能映射 .-> C11
    P4 --. 功能映射 .-> D3
```

### 核心组件详解

#### 1. 领域层核心组件

-   **设备实体 (Device)**: 领域层的核心实体，封装了设备的所有属性和行为，包括设备状态、位置信息、参数配置等。
-   **点云处理服务 (PointCloudProcessService)**: 负责处理雷达设备上报的点云数据，实现目标检测、姿态识别等核心算法。
-   **领域服务/端口**: `DeviceEventPort` 定义了设备事件处理的核心业务逻辑接口，确保业务逻辑的纯粹性。
-   **网关接口**: `DeviceGateway` 与 `MqttGateway` 定义了与外部系统（如数据库、MQTT Broker）交互的抽象接口。

#### 2. MQTT消息处理架构

-   **消息路由 (MqttHandlerImpl)**: 统一的MQTT消息入口，根据主题将消息分发给对应的处理器。
-   **专用消息处理器**: 
    - `DeviceMessageHandler`: 处理设备上行消息（设备信息上报、心跳、状态等）
    - `AppMessageHandler`: 处理应用下行消息（设备绑定、参数设置等）
    - `MpsMessageHandler`: 处理小程序服务消息
    - `OpcMessageHandler`: 处理运维客户端消息
-   **Spring Integration集成**: 通过`MqttConfig`配置实现与MQTT Broker的连接和消息订阅。

#### 3. 点云数据处理流程

1. **数据接收**: 设备通过MQTT上报点云数据到`/dev/{deviceId}/cloudpoint`主题
2. **数据解析**: `DeviceMessageHandler`解析消息并提取点云坐标信息
3. **目标检测**: `PointCloudProcessService.getTrackerTargets()`计算目标位置
4. **姿态识别**: 基于点云高度分布和空间特征识别人员姿态
5. **事件处理**: 检测跌倒等异常事件并触发告警

### 模块依赖关系

遵循DDD的依赖原则，模块间的依赖关系清晰明确：

-   **应用层**依赖领域层和通用层，负责协调业务流程
-   **基础设施层**依赖领域层和通用层，提供技术实现
-   **领域层**仅依赖通用层，保持业务逻辑的纯粹性
-   **客户端启动器**依赖通用层，提供对外服务接口

这种单向依赖关系保证了领域模型的独立性，使其不受技术实现细节的污染。

### MQTT消息处理流程

1.  **消息接收**: 基础设施层的 `MqttConfig` 配置了Spring Integration的 `MqttPahoMessageDrivenChannelAdapter`，负责订阅MQTT主题并将消息推送到指定的 `MessageChannel`。
2.  **消息路由**: `MqttHandlerImpl` 作为统一的入口，根据消息主题模式匹配将其分发给对应的 `MessageHandler`。
3.  **业务处理**: 各个 `MessageHandler` 调用应用层的服务（如 `DeviceEventService`）来执行具体的业务逻辑。
4.  **领域执行**: 应用层服务委托领域对象和领域服务完成核心业务，并通过网关接口与外部系统交互。

这个流程实现了技术关注点（MQTT通信）与业务关注点（设备事件处理）的完全分离。

## 项目结构说明

```
hfln-device-service/
├── device-service-application/         # 应用层
│   ├── controller/                     # Web控制器
│   │   ├── web/                       # Web端控制器
│   │   └── wap/                       # 移动端控制器
│   ├── service/                       # 应用服务
│   │   └── impl/                      # 服务实现
│   ├── convert/                       # 数据转换器
│   ├── dto/                          # 数据传输对象
│   └── task/                         # 定时任务
├── device-service-domain/              # 领域层
│   ├── entity/                       # 领域实体
│   ├── service/                      # 领域服务
│   │   └── impl/                     # 服务实现
│   ├── port/                         # 端口接口
│   ├── gateway/                      # 网关接口
│   ├── event/                        # 领域事件
│   ├── vo/                          # 值对象
│   ├── constant/                     # 领域常量
│   └── exception/                    # 领域异常
├── device-service-infrastructure/      # 基础设施层
│   ├── gateway/impl/                 # 网关实现
│   ├── mqtt/                         # MQTT消息处理
│   │   ├── handler/                  # 消息处理器
│   │   └── MqttHandlerImpl.java      # 消息路由实现
│   ├── config/                       # 配置管理
│   ├── mapper/                       # 数据映射
│   ├── po/                          # 持久化对象
│   └── service/                      # 基础服务
├── device-service-common/              # 通用模块
│   ├── constant/                     # 常量定义
│   ├── dto/                         # 通用DTO
│   ├── util/                        # 工具类
│   ├── enums/                       # 枚举类型
│   ├── annotation/                   # 自定义注解
│   ├── request/                      # 请求对象
│   └── vo/                          # 值对象
├── device-service-client-starter/      # 客户端启动器
│   └── api/feign/                   # Feign客户端
├── device-service-server/              # 服务启动模块
│   ├── config/                       # 启动配置
│   ├── controller/                   # 监控控制器
│   └── DeviceApplication.java        # 主启动类
├── das/                                # Python参考服务
│   ├── mqtt_recv.py                  # 消息接收处理
│   ├── mqtt_send.py                  # 消息发送处理
│   ├── dev_mng.py                    # 设备管理
│   └── mydef.py                      # 核心定义
├── .gitignore                          # Git忽略配置
├── Dockerfile                          # Docker构建文件
├── Jenkinsfile                         # Jenkins CI/CD 流水线
├── pom.xml                             # Maven项目根配置
└── README.md                           # 项目说明文档
```

## 核心功能特性

### 1. 设备接入管理
- 支持多种类型雷达设备的统一接入
- 设备注册、认证和状态管理
- 设备参数配置和远程控制

### 2. 点云数据处理
- 实时点云数据接收和解析
- 目标检测和跟踪算法
- 基于numpy算法等价的Java实现

### 3. 姿态识别
- 基于点云数据的人员姿态识别
- 支持站立、坐下、躺下、跌倒等多种姿态
- 实时姿态状态监控和历史记录

### 4. 跌倒检测告警
- 实时跌倒事件检测
- 告警计划配置和管理
- 多渠道告警通知（MQTT、短信等）

### 5. 多端接口支持
- Web端管理界面接口
- 移动端WAP接口
- 小程序服务接口
- 运维客户端接口

## MQTT通信协议

### MQTT配置

MQTT服务的连接配置信息位于 `device-service-server` 模块的 `application.yml` 文件中：

```yaml
mqtt:
  server:
    uri: tcp://8.130.28.21:1883
  client:
    id: device-service-
  username: admin
  password: public
  connect:
    timeout: 30
  keep:
    alive:
      interval: 60
  clean:
    session: true
```

### MQTT主题规范

项目采用层次化的MQTT主题设计：

#### 设备上行主题 (Device → Server)
- **设备信息上报**: `/dev/{deviceId}/report_device_info`
- **设备心跳**: `/dev/{deviceId}/keepalive`
- **设备状态上报**: `/dev/{deviceId}/report_status`
- **设备参数上报**: `/dev/{deviceId}/report_param`
- **点云数据上报**: `/dev/{deviceId}/cloudpoint`
- **跌倒事件上报**: `/dev/{deviceId}/report_fall`
- **实时数据上报**: `/dev/{deviceId}/dsp_data`

#### 应用下行主题 (Server → Device)
- **DAS服务消息**: `/das/{messageType}`
- **小程序服务消息**: `/mps/{messageType}`
- **运维客户端消息**: `/opc/{messageType}`

#### 具体消息主题
- **设备状态变更**: `/das/dev_status`
- **实时位置姿态**: `/das/realtime_pos`
- **跌倒事件通知**: `/das/event`
- **告警事件**: `/das/alarm_event`
- **设备绑定**: `/mps/bind_device`
- **设备解绑**: `/mps/unbind_device`
- **参数设置**: `/mps/set_device_param`

### 消息格式规范

#### 点云数据消息格式
```json
{
  "device_id": "设备ID",
  "timestamp": 1234567890000,
  "cloud_points": [
    [x1, y1, z1],
    [x2, y2, z2],
    ...
  ],
  "tracker_targets": [
    [x, y, z]
  ]
}
```

#### 跌倒事件消息格式
```json
{
  "device_id": "设备ID",
  "timestamp": 1234567890000,
  "event_type": "fall_detected",
  "target_position": [x, y, z],
  "confidence": 0.95
}
```

## 开发和测试

### 开发环境要求
- Java 8+
- Maven 3.6+
- Spring Boot 2.x
- Redis (用于缓存)
- MySQL (用于数据持久化)
- MQTT Broker (Eclipse Mosquitto 推荐)

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行指定的测试类
mvn test -Dtest="com.hfln.device.infrastructure.config.MqttConfigTest"

# 运行MQTT集成测试
mvn test -Dtest="com.hfln.device.infrastructure.mqtt.*Test"
```

### 代码质量检查

```bash
# 编译检查
mvn clean compile

# 依赖分析
mvn dependency:analyze

# 代码覆盖率
mvn jacoco:report
```

## 部署指南

### 本地开发部署

```bash
# 编译打包
mvn clean package

# 运行服务
java -jar device-service-server/target/device-service-server-1.0.0-SNAPSHOT.jar
```

### Docker部署

```bash
# 构建镜像
docker build -t device-service:latest .

# 运行容器
docker run -d -p 8080:8080 --name device-service device-service:latest
```

### 生产环境部署

1. **环境配置**: 修改 `application-prod.yml` 配置文件
2. **数据库初始化**: 执行 `src/main/resources/db/migration/` 下的SQL脚本
3. **服务启动**: 使用 `systemd` 或 `supervisor` 管理服务进程
4. **监控配置**: 配置 Prometheus + Grafana 监控告警

## 性能优化

### 点云数据处理优化
- 采用流式处理减少内存占用
- 使用对象池技术复用临时对象
- 异步处理非关键路径逻辑

### MQTT消息处理优化
- 消息处理器并行化处理
- 基于主题的消息路由优化
- 连接池和会话管理

### 数据库访问优化
- 使用MyBatis Plus提升开发效率
- 合理使用缓存策略
- 数据库连接池调优

## 监控和运维

### 应用监控
- Spring Boot Actuator健康检查
- 自定义业务指标收集
- JVM性能监控

### 日志管理
- 结构化日志输出
- 分级别日志配置
- 日志轮转和归档策略

### 告警配置
- 服务可用性告警
- 业务异常告警
- 性能指标告警

---

## 贡献指南

### 代码规范
- 遵循阿里巴巴Java开发手册
- 使用统一的代码格式化配置
- 编写完整的单元测试

### 提交规范
- 使用语义化提交信息
- 分支命名规范：`feature/功能名称`、`bugfix/问题描述`
- Pull Request必须通过代码审查

### 文档维护
- 及时更新API文档
- 维护架构设计文档
- 记录重要变更日志

如有问题或建议，请提交Issue或联系开发团队。