he/process/doc/cloud_interact_class_reference.md

# cloud_interact 类调用关系速查

> 配合 [cloud_interact_analysis.md](./cloud_interact_analysis.md) 使用

---

## 1. 按命名空间 pr 的完整类列表

### 1.1 cloud_interact 模块（15 个公开类 + 内部私有类）

| # | 类名 | 基类/模式 | 创建方式 | 主要被谁调用 |
|---|------|----------|---------|-------------|
| 1 | `CCommuInteraction` | `CBaseThread` | `CreateInstance()` | main |
| 2 | `CCommuInterData` | 内部类 | CommuInteraction 构造 | CCommuInteraction |
| 3 | `CCommunicatorHelper` | 独立 | `CreateInstance()` | CCommuInteraction, CDownstreamCommand, CForwardHelper |
| 4 | `CCommunicatorHelperPrivate` | 内部类 | — | CCommunicatorHelper |
| 5 | `CForwardHelper` | 独立 | `CreateInstance()` | CCommuInteraction, CDownstreamCommand |
| 6 | `CForwardHelperPrivate` | 内部类 | — | CForwardHelper |
| 7 | `CDownstreamCommand` | 独立 | `CreateInstance()` | CCommuInteraction |
| 8 | `CDownstreamCommandPrivate` | 内部类 | — | CDownstreamCommand |
| 9 | `CDataCache` | 单例 | `Instance()` | main, CCommuInteraction, Offline/Fault Task |
| 10 | `CCachePrivate` | 内部类 | — | CDataCache |
| 11 | `CStateManager` | 单例 | `Instance()` | main, CCommuInteraction, CAuthManager |
| 12 | `CStateCache` | 内部类 | — | CStateManager |
| 13 | `CAuthManager` | 独立 | `CreateInstance()` | main |
| 14 | `CAuthManagerPrivate` | 内部类 | — | CAuthManager |
| 15 | `CCloudConnectivityDetector` | 独立 | `CreateInstance()` | CAuthManager |
| 16 | `CConnectivityData` | 内部类 | — | CCloudConnectivityDetector |
| 17 | `CAuthQueryHandler` | 独立 | `CreateInstance()` | CAuthManager |
| 18 | `CAuthQueryData` | 内部类 | — | CAuthQueryHandler |
| 19 | `CAuthDistributeTask` | `CBaseThread` | `CreateInstance()` | CAuthManager (EMS) |
| 20 | `CAuthDistributeData` | 内部类 | — | CAuthDistributeTask |
| 21 | `CAuthReceiveHandler` | 独立 | `CreateInstance()` | CAuthManager (非EMS) |
| 22 | `CAuthReceiveData` | 内部类 | — | CAuthReceiveHandler |
| 23 | `COfflineDataTask` | `CBaseThread` | `CreateInstance()` | main |
| 24 | `COfflineTaskPrivate` | 内部类 | — | COfflineDataTask |
| 25 | `CFaultRecordTask` | `CBaseThread` | `CreateInstance()` | main |
| 26 | `CFaultRecordPrivate` | 内部类 | — | CFaultRecordTask |
| 27 | `CRemoteSshHelper` | 单例 | `Instance()` | main, CDownstreamCommand |
| 28 | `CRemoteSshData` | 内部类 | — | CRemoteSshHelper |

### 1.2 reuse_utils 模块

| 类名 | 模式 | 主要被谁调用 |
|------|------|-------------|
| `CConfigManager` | 单例 | main, CCommuInteraction, CDownstreamCommand |
| `CFrameManager` | 独立 | CCommuInteraction |
| `CFrameHelper` | 静态工具 | CFrameManager, CCommuInteraction, Auth 模块 |
| `CProtocolSinglton` | 单例 | main, CCommuInteraction, CFrameManager |
| `CSSLLibSinglton` | 单例 | CDataProcesser (加解密) |
| `CDowloadTask` | 独立 | CCommuInteraction (升级下载) |
| `CFtpDownloadTask` | 独立 | CDowloadTask |
| `CSftpDowloadTask` | 独立 | CDowloadTask |
| `CFtpUploadTask` | 独立 | 上传场景 |
| `CUdpSender` / `CUdpReceiver` | 独立 | Auth 广播 |
| `CSSHHelper` | 工具 | CRemoteSshHelper |

### 1.3 processers 模块 — 数据处理器继承树

```
CDataProcesser (抽象基类)
├── CLoginProcesser                          # 登录
├── CHeartBeatProcesser                      # 心跳
├── CGeneralDataProcesser (通用中间层)
│   ├── [DeviceManage] CVersionInfoProcesser, CDeviceInfoProcesser, CDeviceStateProcesser
│   ├── [Overview] COverallOverviewProcesser, CTerminalOverviewProcesser, CESSProcesser,
│   │              CGatewayPowerMeterOverviewProcesser, CLoadPowerMeterOverviewProcesser,
│   │              CSolarGenerationOverviewProcesser, CWindGenerationOverviewProcesser,
│   │              CDieselGenerationOverviewProcesser, CVirtualPowerPlantOverviewProcesser,
│   │              CEssBranchOverviewProcesser
│   ├── [DeviceData] CPCSProcesser, CPowerMeterProcesser, CSolarInverterProcesser,
│   │                CWindInverterProcesser, CChargePileProcesser, CDieselGeneratorProcesser,
│   │                CPowerEnvironProcesser, CSolarDcProcesser
│   ├── [BMS] CBMSSummaryProcesser, CBMSExtremeProcesser, CBMSChangedCellsProcesser,
│   │         CBMSCellDetailsProcesser
│   ├── [Alarm] CTeleSignalingProcesser, CRealtimeAlarmProcesser,
│   │           CHistoryAlarmProcesser, CHistoryEventProcesser
│   ├── [Statistics] COverviewTOUProcesser, CDeviceTOUProcesser, CRevenueStatisticsProcesser
│   ├── [EMS Strategy Read] CDownstreamSchedulingTaskReadProcesser,
│   │                       CDownstreamPeakShavingReadProcesser, CDownstreamLoadResponseReadProcesser,
│   │                       CDownstreamDemandResponseReadProcesser, CDownstreamCapacityExpansionReadProcesser,
│   │                       CDownstreamGridRestrictionReadProcesser, CDownstreamTOUParamsReadProcesser,
│   │                       CDownstreamPVWorkingReadProcesser, CDownstreamPva*ReadProcesser (6个)
│   ├── [EMS Strategy Write] CDownstreamSchedulingTaskWriteProcesser, ... (对应 Write 系列)
│   ├── [Tariff] CDownstreamTariffTypeRead/WriteProcesser, CDownstreamTariffTemplateRead/WriteProcesser,
│   │            CDownstreamTimeTemplateRead/WriteProcesser, CDownstreamTariffSettingRead/WriteProcesser,
│   │            CUpstreamTariffTypeNofityProcesser
│   ├── [Battery] CDownstreamSafeProtectionRead/WriteProcesser, CDownstreamSOCCalibrationRead/WriteProcesser,
│   │             CDownstreamCapacityCalibrationRead/WriteProcesser, CDownstreamInsulationDetectionRead/WriteProcesser
│   ├── [Control] CDownstreamEMSControlProcesser, CDownstreamDeviceControlProcesser
│   ├── [Upgrade] CUpstreamUpgradeTaskQueryProcesser, CUpstreamUpgradeTaskResultProcesser,
│   │               CUpstreamUpgradeTerminalResultProcesser, CDownstreamnUpgradeTaskNotificationProcesser
│   ├── [Offline] CUpstreamOfflineRequestProcesser
│   ├── [FaultRecord] CUpstreamFaultRecRequestProcesser
│   ├── [RemoteManage] CDownstreamSshStartProcesser, CDownstreamSshStopProcesser
│   └── [Setup] CDownstreamTermUpdateProcesser
├── CProcesserDataHelper (单例, 非继承)         # 数据Id与上报状态管理
└── CTerminalCache (单例, 非继承)              # 终端列表缓存
```

---

## 2. 核心调用链

### 2.1 启动阶段

```
main()
  ├─ LibCreateMutexLog()
  ├─ CDataCache::UpdateRunningDurationPeriodically()
  ├─ RegisterHandleSigs() → CStateManager::NotifyQuit()
  ├─ CAuthManager::CreateInstance()
  │    ├─ CCloudConnectivityDetector::CreateInstance()
  │    ├─ CAuthQueryHandler::CreateInstance()
  │    ├─ [EMS] CAuthDistributeTask::CreateInstance()
  │    └─ [非EMS] CAuthReceiveHandler::CreateInstance()
  ├─ CAuthManager::Execute()  ← 阻塞直到授权完成
  ├─ CStateManager::Notify*() 重置状态
  ├─ CConfigManager::Initialize()
  ├─ CProtocolSinglton::Create()
  ├─ CCommuInteraction::CreateInstance() → Initialize(STATION_CONFIG)
  │    └─ CCommuInterData::Initialize()
  │         ├─ CFrameManager::CreateInstance() → CreateDataProcessers()
  │         ├─ CCommunicatorHelper::CreateInstance()
  │         ├─ CForwardHelper::CreateInstance()
  │         └─ CDownstreamCommand::CreateInstance()
  ├─ [可选] COfflineDataTask / CFaultRecordTask
  └─ CThreadWatchDog::Initialize() → Start()
```

### 2.2 通信线程单次 Handle 调用链

```
CCommuInteraction::Handle()
  ├─ CDataCache::Initialize()                    [首次]
  ├─ ConnectCloud()
  │    └─ CCommunicatorHelper::Connect()
  │         └─ ICloudCommunicator::Connect()
  ├─ LoginCloud()
  │    ├─ CFrameManager::GetDataProcesserByFrameType(LOGIN)
  │    ├─ CLoginProcesser::EncodeUpstreamRequest()
  │    ├─ CFrameHelper::EncodeUpstreamFrame()
  │    ├─ CCommunicatorHelper::Send()
  │    ├─ ReceiveDownstreamFrame*()
  │    ├─ CFrameManager::DecodeDownstreamFrame()
  │    └─ CConfigManager::UpdateLoginResponse()
  ├─ HandleLastUncompletedUpgradeTask()
  ├─ CDownstreamCommand::CheckDownstreamCommandResults()
  ├─ HandleDownstreamData()
  │    ├─ CCommunicatorHelper::Receive()
  │    ├─ CFrameManager::DecodeDownstreamFrame()
  │    ├─ [命令] CDownstreamCommand::HandleDownstreamRequest()
  │    │    ├─ HandleTerminalUpdateRequest()
  │    │    ├─ HandleDownstreamCommandRequest()
  │    │    ├─ HandleDownstreamParams*Request()
  │    │    ├─ HandleDownstreamSsh*Request() → CRemoteSshHelper
  │    │    └─ HandleDownstreamUpgradeNotificationRequest()
  │    └─ [转发] CForwardHelper::ForwardDownstreamData()
  ├─ HandleUpstreamData()
  │    └─ for (priority → processer)
  │         ├─ TimeToEncodeUpstreamRequest()
  │         ├─ FillUpstreamRequestData()
  │         ├─ EncodeUpstreamRequest()
  │         ├─ SendUpstreamFrame()
  │         └─ Receive + DecodeDownstreamResponse()
  ├─ CForwardHelper::ForwardUpstreamData()     [EMS]
  ├─ CForwardHelper::ForwardFaultRecord()      [EMS]
  ├─ CForwardHelper::ForwardOfflineData()      [EMS]
  └─ CDataCache::CalculateTotalOnlineDuration()  [每5分钟]
```

### 2.3 下行命令处理链（CDownstreamCommand）

```
CDownstreamCommand::HandleDownstreamRequest()
  ├─ IsDownstreamRequest(frameType) ?
  ├─ pDataProcesser->DecodeDownstreamRequest()
  ├─ 按帧类型分发：
  │    ├─ TERM_UPDATE        → HandleTerminalUpdateRequest/Response
  │    ├─ UPGRADE_NOTIFY     → HandleDownstreamUpgradeNotificationRequest
  │    ├─ READ_*_PARAMS      → HandleDownstreamParamsReadingRequest
  │    ├─ WRITE_*_PARAMS     → HandleDownstreamParamsWritingRequest
  │    ├─ CONTROL_COMMAND    → HandleDownstreamCommandRequest
  │    └─ START/STOP_SSH     → HandleDownstreamSshStart/StopRequest
  ├─ pDataProcesser->EncodeUpstreamResponse()
  └─ CCommunicatorHelper::Send() 回复云平台

CDownstreamCommand::CheckDownstreamCommandResults()
  └─ 轮询 librunning_data / libcloud_command 获取异步执行结果并上报
```

---

## 3. 单例与生命周期

| 单例类 | 创建时机 | 销毁时机 |
|--------|---------|---------|
| `CStateManager` | 首次 Instance() | 进程结束 |
| `CDataCache` | 首次 Instance() | 进程结束 |
| `CConfigManager` | main 中 Initialize | 进程结束 |
| `CProtocolSinglton` | main 中 Create | main 退出前 Free()，重授权时也会 Free/Create |
| `CRemoteSshHelper` | 首次 Instance() | 进程结束 |
| `CThreadWatchDog` | main 中 Initialize | main 退出前 Stop() |
| `CProcesserDataHelper` | 首次 Instance() | 进程结束 |
| `CTerminalCache` | 首次 Instance() | 进程结束 |

**线程对象生命周期：**

| 对象 | 所有者 | 启停 |
|------|--------|------|
| `CCommuInteraction` | main 局部 shared_ptr | main 循环 Start/Stop，重授权时 Deinitialize |
| `COfflineDataTask` | main 局部 shared_ptr | main 循环按需 Start |
| `CFaultRecordTask` | main 局部 shared_ptr | main 循环按需 Start |
| `CAuthDistributeTask` | CAuthManager 内部 | EMS 授权成功后 Start(detached) |
| `CAuthManager` | main 局部 shared_ptr | 全程存活，退出前 Deinitialize |

---

## 4. 共享库接口（跨模块数据通道）

| 库 | cloud_interact 中的用途 |
|----|------------------------|
| `librunning_data` | 云连接/登录状态、终端信息、授权状态、进程喂狗 |
| `libcloud_data` | 数据上报状态、离线数据、数据Id生成 |
| `libcloud_command` | 下行控制指令队列与执行结果 |
| `libcloud_repeater` | EMS 中继转发缓冲 |
| `libruntime_environ` | 运行环境、站点配置加载、终端透传有效性 |
| `libcloud_protocol` | 协议编解码（通过 ICloudProtocol 接口） |
| `libcloud_communicator` | TCP 通信（通过 ICloudCommunicator 接口） |

---

## 5. 帧类型 → Processor 映射表（节选）

完整映射见 `reuse_utils/src/FrameManager.cpp` 中 `mapType2ProcesserCreator`。

| 帧类型常量 | Processor 类 | 方向 | 优先级 |
|-----------|---------------|------|--------|
| `UPSTREAM_LOGIN` | CLoginProcesser | 上行请求 | 1 |
| `UPSTREAM_VERSION_INFOS` | CVersionInfoProcesser | 上行请求 | 2 |
| `UPSTREAM_DEVICE_INFOS` | CDeviceInfoProcesser | 上行请求 | 3 |
| `UPSTREAM_DEVICE_STATES` | CDeviceStateProcesser | 上行请求 | 4 |
| `UPSTREAM_HEART_BEAT` | CHeartBeatProcesser | 上行请求 | 2001 |
| `UPSTREAM_REALTIME_ALARM_DATA` | CRealtimeAlarmProcesser | 上行请求 | 302 |
| `UPSTREAM_OVERALL_OVERVIEW` | COverallOverviewProcesser | 上行请求 | 401 |
| `UPSTREAM_OFFLINE_DATA_REQUEST` | CUpstreamOfflineRequestProcesser | 上行请求 | 501 |
| `UPSTREAM_FAULT_RECORD` | CUpstreamFaultRecRequestProcesser | 上行请求 | 303 |
| `UPSTREAM_UPGRADE_TASK_QUERY` | CUpstreamUpgradeTaskQueryProcesser | 上行请求 | 200 |
| `DOWNSTREAM_EMS_CONTROL_COMMAND` | CDownstreamEMSControlProcesser | 下行请求 | 801 |
| `DOWNSTREAM_DEVICE_CONTROL_COMMAND` | CDownstreamDeviceControlProcesser | 下行请求 | 802 |
| `DOWNSTREAM_READ_SCHEDULING_TASK_PARAMS` | CDownstreamSchedulingTaskReadProcesser | 下行请求 | 901 |
| `DOWNSTREAM_WRITE_SCHEDULING_TASK_PARAMS` | CDownstreamSchedulingTaskWriteProcesser | 下行请求 | 902 |
| `DOWNSTREAM_START_SSH` | CDownstreamSshStartProcesser | 下行请求 | 1201 |
| `DOWNSTREAM_STOP_SSH` | CDownstreamSshStopProcesser | 下行请求 | 1202 |
| `DOWNSTREAM_UPGRADE_TASK_NOTIFICATION` | CDownstreamnUpgradeTaskNotificationProcesser | 下行请求 | 203 |

> 注：优先级数值越小越先上报；下行命令类帧不参与自动上行优先级排序，由云平台主动下发触发。