Web_BLS_RCUAction_Server/docs/readme.md

# BLS RCU Action Server 开发文档

## 1. 项目概述
本项目旨在构建一个后端服务，负责从 Kafka 接收 RCU（客房控制单元）的通讯日志，解析数据结构，并将其持久化存储到 PostgreSQL 数据库中。

核心目标是将不同类型的通讯协议数据（0x36 上报、0x0F 下发、ACK）统一存储，并针对不定长数据结构采用 JSON 格式进行灵活保存。

## 2. 系统架构
**数据流向**: `MCU/Server` (产生数据) -> `Kafka` (消息队列) -> `Action Server` (消费 & 解析) -> `PostgreSQL` (存储)

- **Kafka Topic**: `blwlog4Nodejs-rcu-action-topic` (分区数: 6)
- **数据库**: PostgreSQL

## 3. 数据库设计

数据库名：`bls_rcu_action`
模式名: `rcu_action`

### 3.1 表结构设计
表名: `rcu_action_events`

| 字段名 | 类型 | 说明 | 备注 |
| :--- | :--- | :--- | :--- |
| **guid** | VARCHAR(32) | 主键 (Key2) | 32位无符号UUID |
| **ts_ms** | BIGINT | 日志产生时间 (Key1) | **必填** (L49) |
| **write_ts_ms** | BIGINT | 入库时间 | **必填** (L50) |
| **hotel_id** | INTEGER | 酒店ID | **必填** (L51) Index |
| **room_id** | VARCHAR(32) | 房间ID | **必填** (L52) Index |
| **device_id** | VARCHAR(32) | 设备ID | **必填** (新增) Index |
| **direction** | VARCHAR(10) | 数据方向 | **必填** (L53) "上报"/"下发" Index |
| **cmd_word** | VARCHAR(10) | 命令字 | **必填** (L54) 如 "0x36", "0x0F" Index |
| **frame_id** | INTEGER | 通讯帧号 | **必填** (L55) 用于串联命令与状态 |
| **udp_raw** | TEXT | UDP消息原文 | **必填** (L56) base64字符串；当前若上游仍发送十六进制字符串，则后端会在入库前临时转换为base64，后续会取消该自动转换机制 |
| **action_type** | VARCHAR(20) | 记录行为类型 | **必填** (L57) Index |
| **sys_lock_status** | SMALLINT | 系统锁状态 | (L59) 可空 |
| **report_count** | SMALLINT | 本次上报数量 | (L60) 可空 |
| **dev_type** | SMALLINT | 设备类型 | (L61) 可空 (统一字段) |
| **dev_addr** | SMALLINT | 设备地址 | (L62) 可空 (统一字段) |
| **dev_loop** | INTEGER | 设备回路 | (L63) 可空 (统一字段) |
| **dev_data** | INTEGER | 设备状态 | (L64) 可空 (0x36状态) |
| **fault_count** | SMALLINT | 本次故障数量 | (L65) 可空 |
| **error_type** | SMALLINT | 故障类型 | (L69) 可空 (0x36故障) |
| **error_data** | SMALLINT | 故障内容 | (L70) 可空 (0x36故障) |
| **type_l** | SMALLINT | 执行方式 | 可空 (0x0F下发) |
| **type_h** | SMALLINT | 执行内容 | 可空 (0x0F下发) |
| **details** | JSONB | 业务详情数据 | 存储不定长设备列表、故障信息等 |
| **extra** | JSONB | 扩展信息 | 存储上游传入的extra扩展字段；如未提供则为空对象 |

**主键定义**: `(ts_ms, guid)`
**索引定义**: 备注带index的字段为需要索引的字段，用于提高查询效率。

### 3.2 字典定义
**Action Type (记录行为类型)**:
- 枚举值：（ACK和下发控制是0x0F的特殊情况，用户操作和设备回路状态是0x36的枚举值）
    - ACK：ACK是0x0F的上报独有的，所以如果0F且Direction为上报，就标记为ACK
    - 下发控制：0x0F的Direction为下发指令，记录为下发控制
    - 用户操作：0x36上报 的开关、温控器等客户操作设备产生的，属于用户操作
    - 设备回路状态：0x36上报 的灯光、继电器回路等变化等受控设备，属于设备回路状态
        - 用户操作和设备回路状态的具体区分表（根据本行数据的dev_type来区分），注意，这张表是根据dev_type来区分的，所以dev_type不能改变，否则会导致数据错误，另外这个表要写入env配置文件，以数组形式保存，随时可以更改：
            |dev_type|名称|描述|Action Type|
            |---|---|---|---|
            |0|Dev_Host_Invalid|无效设备（也可以被认为是场景）|无效|
            |1|Dev_Host_HVout|强电继电器（输出状态）|设备回路状态|
            |2|Dev_Host_LVinput|弱电输入（输入状态）|用户操作|
            |3|Dev_Host_LVoutput|弱电输出（输出状态）|设备回路状态|
            |4|Dev_Host_Service|服务信息|设备回路状态|
            |5|Dev_NodeCurtain|干节点窗帘|设备回路状态|
            |6|DEV_RS485_SWT|开关|用户操作|
            |7|DEV_RS485_TEMP|空调|用户操作|
            |8|DEV_RS485_INFRARED|红外感应|用户操作|
            |9|DEV_RS485_AirDetect|空气质量检测设备|设备回路状态|
            |10|DEV_RS485_CARD|插卡取电|用户操作|
            |11|DEV_RS485_HEATER|地暖|用户操作|
            |12|Dev_RCU_NET|RCU 设备网络 - 没使用||
            |13|DEV_RS485_CURTAIN|窗帘|设备回路状态|
            |14|DEV_RS485_RELAY|继电器|设备回路状态|
            |15|DEV_RS485_IR_SEND|红外发送|设备回路状态|
            |16|DEV_RS485_DIMMING|调光驱动|设备回路状态|
            |17|DEV_RS485_TRAIC|可控硅调光（可控硅状态）|设备回路状态|
            |18|DEV_RS485_STRIP|灯带（灯带状态） --2025-11-24 取消|无效|
            |19|DEV_RS485_CoreCtrl|中控|无效|
            |20|DEV_RS485_WxLock|微信锁 （福 瑞狗的蓝牙锁 默认 0 地址）|无效|
            |21|DEV_RS485_MUSIC|背景音乐（背景音乐状态）|设备回路状态|
            |22|DEV_NET_ROOMSTATE|房态下发|无效|
            |23|Dev_Host_PWMLight|主机本地 调光|无效|
            |24|DEV_RS485_PWM|485PWM 调光（ PWM 调光状态）|无效|
            |25|DEV_PB_LED|总线调光（ PBLED 调光状态） - 没使用 -|无效|
            |26|DEV_RCU_POWER|RCU 电源|无效|
            |27|DEV_RS485_A9_IO_SWT|A9IO 开关|用户操作|
            |28|DEV_RS485_A9_IO_EXP|A9IO 扩展|设备回路状态|
            |29|DEV_RS485_A9_IO_POWER|A9IO 电源|设备回路状态|
            |30|DEV_RS485_RFGatewayCycle|无线网关轮询（用于轮询控制轮询设备；给无线网关下发配置和询问网关状态）|无效|
            |31|DEV_RS485_RFGatewayHost|无线网关主动（用于主动控制主动设备）|无效|
            |32|DEV_RS485_RFGatewayDoor|无线门磁|用户操作|
            |33|DEV_RS485_AirReveal|空气参数显示设备|设备回路状态|
            |34|DEV_RS485_RFGatewayRelayPir|无线继电器红外|设备回路状态|
            |35|Dev_Host_TimeCtrl|时间同步|设备回路状态|
            |36|Dev_Rs458_MonitorCtrl|监控控制|无效|
            |37|Dev_Rs458_RotaryCtrl|旋钮开关控制|用户操作|
            |38|Dev_BUS_C5IO|CSIO - 类型|设备回路状态|
            |39|Dev_RS485_CardState|插卡状态虚拟设备|设备回路状态|
            |40|DEV_RS485_FreshAir|485 新风设备|用户操作|
            |41|DEV_RS485_FaceMach|485 人脸机|用户操作|
            |42|DEV_Center_Control|中控|无效|
            |43|DEV_Domain_Control|域控|无效|
            |44|DEV_RS485_LCD|LCD|设备回路状态|
            |45|DEV_Virtual_NoCard|无卡断电 --2025-11-24 取消|无效|
            |46|DEV_Virtual_Card|无卡取电 2|用户操作|
            |47|DEV_Virtual_Time|虚拟时间设备|设备回路状态|
            |48|Dev_Rs485_PB20|PLC 总控|设备回路状态|
            |49|Dev_Rs485_PB20_LD|PLC 设备 - 恒流调光设备|设备回路状态|
            |50|Dev_Rs485_PB20_LS|PLC 设备 - 恒压调光设备|设备回路状态|
            |51|Dev_Rs485_PB20_Relay|PLC 设备 - 继电器设备|设备回路状态|
            |52|DEV_Virtual_ColorTemp|色温调节功能|设备回路状态|
            |53|Dev_485_BLE_Music|蓝牙音频|设备回路状态|
            |54|DEV_Carbon_Saved|碳达人|用户操作|
            |55|Dev_Scene_Restore|场景还原|用户操作|
            |56|Dev_Virtual_GlobalSet|全局设置|设备回路状态|
            |57|Dev_Energy_Monitor|能耗检测|设备回路状态|
            |241|Dev_BUS_C5IO|CSIO - 类型|设备回路状态|

**Direction (方向)**:
- `"上报"`: Upload
- `"下发"`: Download

## 4. 数据解析与存储映射

### 4.1 0x36 上报数据 (设备状态/故障)
*   **命令字**: "0x36"
*   **拆分逻辑**: 根据 `project.md` 说明，一条 UDP 可能包含多个设备状态，需拆分为多条记录入库，每条记录填充 `dev_type` 等字段。同时将完整的不定长列表存入 `details` 以便追溯。
*   **Action Type**: 4 (设备回路状态)

**Mapping**:
- `sys_lock_status` -> P0
- `report_count` -> P7
- `dev_type`, `dev_addr`... -> 从 P8~P13 循环解析，每组生成一条 DB 记录
- `details`: `{ "all_devices": [...], "all_faults": [...] }`
- `extra`: `{ "raw_hex": "..." }`

### 4.2 0x0F 下发数据 (控制指令)
*   **命令字**: "0x0F"
*   **Action Type**: 2 (下发控制)
*   **存储逻辑**: 主要是控制指令，通常作为单条记录存储。若包含多个设备控制，可选择存第一条到字段，或仅存入 JSON。根据 "0x0F不定长存为JSON" 的需求，主要依赖 `details` 字段。

**Mapping**:
- `details`: `{ "control_params": [ ... ] }`
- `extra`: `{ "raw_hex": "..." }`

### 4.3 0x0F 上报数据 (ACK)
*   **命令字**: "0x0F"
*   **Action Type**: "0FACK" (ACK)

**Mapping**:
- `details`: `{ "ack_code": "0x00" }`
- `extra`: `{ "raw_hex": "..." }`