a

2026-07-03 16:05:30 +08:00
commit df489d5640
1101 changed files with 779140 additions and 0 deletions
@@ -0,0 +1,393 @@
+# 设备管理
+
+<cite>
+**本文引用的文件**
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp)
+- [DevManager.h](file://h/DevManager.h)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp)
+- [Device.h](file://h/Device.h)
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp)
+- [HandleProcessor.h](file://h/HandleProcessor.h)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h)
+- [Constant.h](file://h/Constant.h)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [组件详解](#组件详解)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件系统性文档化设备管理模块的实现细节，重点覆盖：
+- CDevManager 类如何管理设备生命周期（连接、状态监控、固件升级、删除）
+- 设备链表 m_devLinkList 的数据结构设计与句柄处理器 HandleProcessor 的集成机制
+- CDevice 类的数据模型与其与数据库的交互方式
+- 设备注册、状态变更与异常处理的实际调用路径
+- 与项目管理器、脚本管理器等模块的协作关系
+- 在线/离线模式下的行为差异
+- 设备通信协议、错误码处理与性能优化建议
+
+## 项目结构
+设备管理相关代码主要分布在以下目录与文件：
+- 管理层：DevManager（设备管理器）、ProManager（项目管理器）、SptManager（脚本管理器）
+- 业务层：Device（设备实体）
+- 工具层：HandleProcessor（句柄处理器）、CtrlProtocolDef（通信协议与错误码定义）
+- 视图层：devmngframe（设备管理界面框架），用于触发升级、参数修改等操作
+- 工具：checkupdate（固件升级工具）
+
+```mermaid
+graph TB
+subgraph "管理层"
+DM["CDevManager<br/>设备管理器"]
+PM["CProManager<br/>项目管理器"]
+SM["CSptManager<br/>脚本管理器"]
+end
+subgraph "业务层"
+DEV["CDevice<br/>设备实体"]
+end
+subgraph "工具层"
+HP["CHandleProcessor<br/>句柄处理器"]
+CPD["CtrlProtocolDef<br/>通信协议/错误码"]
+CT["Constant<br/>常量/状态/句柄位宽"]
+end
+subgraph "视图层"
+DVF["CDevMngFrame<br/>设备管理界面"]
+CU["Ccheckupdate<br/>固件升级工具"]
+end
+DM --> DEV
+DM --> HP
+DM --> CPD
+DM --> CT
+PM --> DM
+SM --> DM
+DVF --> DM
+DVF --> DEV
+DVF --> CU
+```
+
+图表来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L1-L200)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L1-L120)
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L1-L96)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
+- [Constant.h](file://h/Constant.h#L60-L120)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1-L120)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L1780-L1840)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)
+
+章节来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L1-L200)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L1-L120)
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L1-L96)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
+- [Constant.h](file://h/Constant.h#L60-L120)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1-L120)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L1780-L1840)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)
+
+## 核心组件
+- CDevManager：负责设备生命周期管理、设备链表维护、句柄分配、数据库交互、在线/离线设备列表构建、远程设备集合维护、设备信息更新等。
+- CDevice：封装设备数据模型（ID、状态、类型、序列号、硬件/软件版本、电池电压、参数等），并提供与数据库交互的方法（展示详情、读取/写入参数、文件收发、GR/AC信息等）。
+- CHandleProcessor：负责句柄生成与解析，将ID与类型打包进统一的DWORD句柄，支持从句柄中提取ID与类型。
+- CtrlProtocolDef：定义控制协议头、设备参数结构、命令字、错误码、远程设备信息等。
+- Constant：定义句柄位宽、状态枚举、消息常量、缓冲区大小、轮询超时等通用常量。
+
+章节来源
+- [DevManager.h](file://h/DevManager.h#L1-L69)
+- [Device.h](file://h/Device.h#L1-L128)
+- [HandleProcessor.h](file://h/HandleProcessor.h#L1-L29)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
+- [Constant.h](file://h/Constant.h#L60-L120)
+
+## 架构总览
+设备管理模块围绕“设备管理器-设备实体-句柄处理器-通信协议-视图/工具”的分层组织，形成清晰的职责边界与调用链路。
+
+```mermaid
+sequenceDiagram
+participant UI as "视图/界面"
+participant DM as "CDevManager"
+participant DEV as "CDevice"
+participant HP as "CHandleProcessor"
+participant DB as "数据库"
+participant NET as "网络/远程设备"
+UI->>DM : 请求初始化设备链表
+DM->>DB : 查询设备表(device)
+DB-->>DM : 返回设备记录集
+loop 遍历记录
+DM->>DEV : 构造CDevice实例
+DM->>HP : 生成句柄(设备ID, 类型)
+DM->>DM : m_devLinkList.Add(句柄, 设备)
+end
+UI->>DM : 获取在线/离线设备列表
+DM->>DM : 遍历m_devLinkList
+DM-->>UI : 返回在线/离线设备数组
+UI->>DM : 更新设备参数/信息
+DM->>DB : 写入设备参数/信息
+DB-->>DM : 提交成功
+UI->>DM : 删除设备
+DM->>DB : 删除设备及关联表记录
+DB-->>DM : 提交成功
+UI->>DM : 远程设备上下线通知
+DM->>NET : 维护远程设备集合(set)
+DM-->>UI : 同步状态
+```
+
+图表来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L160-L201)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L486-L508)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L510-L591)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L592-L642)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L383-L433)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L435-L483)
+- [DevManager.h](file://h/DevManager.h#L20-L66)
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L29-L57)
+
+## 组件详解
+
+### CDevManager：设备生命周期与链表管理
+- 初始化设备链表：从数据库读取设备记录，构造 CDevice 对象，生成句柄并加入 m_devLinkList。
+- 设备查询：按ID、句柄、序列号查询设备，并进行MAC白名单匹配。
+- 设备增删改：新增设备（含默认desetting/acds表初始化）、删除设备（级联清理）、设置句柄。
+- 在线/离线列表：遍历链表筛选在线/离线设备。
+- 远程设备集合：维护远程GD10/PLC设备集合，支持增删。
+- 设备信息更新：接收远程设备参数，写入数据库。
+
+```mermaid
+flowchart TD
+Start(["初始化设备链表"]) --> QueryDB["查询设备表(device)"]
+QueryDB --> Loop{"遍历记录"}
+Loop --> |是| NewDev["构造CDevice实例"]
+NewDev --> GenHandle["生成句柄(设备ID, 类型)"]
+GenHandle --> AddList["m_devLinkList.Add(句柄, 设备)"]
+AddList --> Loop
+Loop --> |否| End(["完成"])
+subgraph "查询与筛选"
+Q1["按ID查询"] --> Q2["按句柄查询"]
+Q3["按序列号查询"] --> Q4["在线/离线列表"]
+end
+```
+
+图表来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L160-L201)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L48-L80)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L82-L90)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L127-L158)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L486-L508)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L510-L591)
+
+章节来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L48-L158)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L160-L201)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L203-L281)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L283-L294)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L296-L323)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L325-L381)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L383-L483)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L486-L591)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L592-L642)
+- [DevManager.h](file://h/DevManager.h#L16-L66)
+
+### CDevice：设备数据模型与数据库交互
+- 数据模型：包含设备ID、状态、类型、序列号、名称、型号、硬件/软件版本、生产日期、批次、MAC地址、数据库连接指针等。
+- 数据库交互：展示离线/在线详情、读取/写入desetting/acds参数、读取devgr/devac信息、执行脚本同步等。
+- 文件传输：支持接收/发送文件（Zmodem流程），带重试逻辑。
+- 参数与状态：提供参数修改、时间窗修改、锁机、重置等能力。
+
+```mermaid
+classDiagram
+class CDevice {
+DWORD m_dwID
+UINT m_uState
+UINT m_uType
+BYTE m_ucDevType
+CString m_szDevSN
+CString m_szDevName
+CString m_szModelNO
+CString m_szHWV
+CString m_szSWV
+CString m_szMacAddress
+_ConnectionPtr m_pConnection
+PrintLog(strLog)
+ShowFLDetailInfo(list)
+ShowOLDetailInfo(list)
+ShowGRInfo(list)
+ShowACInfo(list)
+ReceiveFile(local, host, retry)
+SendFile(host, local, name)
+}
+```
+
+图表来源
+- [Device.h](file://h/Device.h#L33-L128)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L115-L192)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L193-L280)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L511-L547)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L549-L649)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L682-L727)
+
+章节来源
+- [Device.h](file://h/Device.h#L33-L128)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L115-L280)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L511-L649)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L682-L727)
+
+### 句柄处理器 CHandleProcessor：ID与类型编码
+- 生成句柄：将设备ID与类型按固定位宽打包，类型高位存放，ID低位存放。
+- 解析句柄：从句柄中提取ID与类型。
+- 位宽定义：来自 Constant 中 HANDLE_OFFSET 常量，确保ID与类型的位域合理分配。
+
+```mermaid
+flowchart TD
+A["输入: 设备ID, 类型"] --> B["类型左移HANDLE_OFFSET位"]
+B --> C["ID按位或运算"]
+C --> D["输出: 句柄DWORD"]
+D --> E["解析: 取低27位ID, 取高5位类型"]
+```
+
+图表来源
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L29-L57)
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L59-L95)
+- [Constant.h](file://h/Constant.h#L60-L70)
+
+章节来源
+- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L29-L95)
+- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L29)
+- [Constant.h](file://h/Constant.h#L60-L70)
+
+### 设备通信协议与错误码
+- 协议头与参数结构：STCtrlProtoHeader、STSynDevParam、STModifyDevParam 等，定义了控制命令、数据类型、状态码、设备参数等。
+- 命令字与状态：EN_CTRL_CMD_INFO 定义了登录、参数同步、参数设置、任务参数设置、测量数据、心跳等命令字；EN_RCV_MSG_RES/EN_ERROR_MSG 定义了接收结果与错误码。
+- 远程设备信息：STSigRemoteDev 定义远程GD10/PLC设备标识与比较规则。
+
+章节来源
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L46-L120)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L126-L237)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L441-L548)
+
+### 设备注册、状态变更与异常处理
+- 注册查询：GetRegisterDevice 会检查设备是否已在链表中存在，并与当前MAC白名单比对，避免跨网卡误判。
+- 状态变更：CDevice::SetState 设置设备状态；CDevManager::UpdateDevInfo 将远程设备参数写入数据库。
+- 异常处理：数据库事务 Begin/Commit/Rollback 包裹关键操作；捕获_com_error 并弹窗提示；全局钩子用于统一错误提示。
+
+章节来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L92-L125)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L127-L158)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L592-L642)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L75-L84)
+
+### 与项目管理器、脚本管理器的协作
+- 项目管理器：通过句柄处理器解析工程/测试区句柄，构建数据管理结构（CProject/CTestingZone），并与设备建立关联（dptt表）。
+- 脚本管理器：在离线模式下创建脚本文件，与设备ID关联；在线模式下通过设备与脚本同步（脚本下发/接收）。
+
+章节来源
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L155-L182)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L184-L215)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L1782-L1834)
+
+### 在线/离线模式行为差异
+- 在线模式：设备状态可能为 EN_DEV_ONLINE 或 NEW；设备参数通过协议同步至数据库；支持实时数据接收与状态通知。
+- 离线模式：设备状态为 OFFLINE；通过数据库直接展示设备参数与历史数据；部分操作（如参数同步）受限。
+
+章节来源
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L42-L44)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L486-L508)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L1710-L1753)
+
+### 固件升级与参数修改
+- 固件升级：通过 CDevMngFrame 触发升级流程，使用 Ccheckupdate 下载/校验/执行升级，涉及文件发送、命令下发与结果校验。
+- 参数修改：通过 CDevice 接口修改参数，结合 CtrlProtocolDef 中的命令字与参数结构进行下发与确认。
+
+章节来源
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L508-L548)
+
+## 依赖关系分析
+- CDevManager 依赖 CDevice、CHandleProcessor、CtrlProtocolDef、Constant、数据库连接。
+- CDevice 依赖数据库连接、文件传输工具、对话框组件。
+- 视图层（CDevMngFrame）依赖设备管理器与升级工具。
+- 项目/脚本管理器通过句柄与设备管理器解耦协作。
+
+```mermaid
+graph LR
+DM["CDevManager"] --> DEV["CDevice"]
+DM --> HP["CHandleProcessor"]
+DM --> CPD["CtrlProtocolDef"]
+DM --> CT["Constant"]
+DEV --> DB["数据库"]
+DVF["CDevMngFrame"] --> DM
+DVF --> CU["Ccheckupdate"]
+PM["CProManager"] --> DM
+SM["CSptManager"] --> DM
+```
+
+图表来源
+- [DevManager.h](file://h/DevManager.h#L16-L66)
+- [Device.h](file://h/Device.h#L33-L128)
+- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L29)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
+- [Constant.h](file://h/Constant.h#L60-L120)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L155-L182)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L1782-L1834)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)
+
+章节来源
+- [DevManager.h](file://h/DevManager.h#L16-L66)
+- [Device.h](file://h/Device.h#L33-L128)
+- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L29)
+- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
+- [Constant.h](file://h/Constant.h#L60-L120)
+- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L155-L182)
+- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L1782-L1834)
+- [devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)
+
+## 性能考量
+- 句柄位宽与哈希/索引：HANDLE_OFFSET 与类型位域设计保证了O(1)的句柄解析与查找效率，适合大规模设备场景。
+- 数据库事务：关键操作（新增/删除设备、参数更新）使用事务包裹，减少中间态风险，但需注意事务开销与锁竞争。
+- 文件传输重试：接收文件具备重试机制，提升稳定性，但应限制最大重试次数与退避策略，避免阻塞UI。
+- 轮询与超时：通信轮询次数与超时常量（MAX_POLLING_TIME、COMM_TIMEOUT）影响响应速度与资源占用，应根据实际通信环境调整。
+- 在线/离线列表构建：遍历链表筛选在线/离线设备为O(N)，建议在频繁刷新场景引入增量更新与缓存。
+
+## 故障排查指南
+- 设备注册失败：检查 GetRegisterDevice 中 MAC 白名单匹配逻辑，确认当前网卡MAC与设备记录一致。
+- 数据库异常：AddDevice/DeleteDevice/UpdateDevInfo 使用事务，捕获_com_error后回滚并弹窗提示，优先检查SQL语句与权限。
+- 文件传输失败：查看 ReceiveFile 的重试逻辑与 EndTransfer 终止流程，确认Zmodem握手与缓冲区大小。
+- 远程设备状态不同步：核对远程设备集合维护逻辑（AddRemoteDevice/DeleteRemoteDevice），确保上下线通知正确到达。
+
+章节来源
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L92-L125)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L203-L281)
+- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L383-L483)
+- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L682-L727)
+- [DevManager.h](file://h/DevManager.h#L41-L66)
+
+## 结论
+设备管理模块通过“设备管理器-设备实体-句柄处理器-通信协议-视图/工具”的分层设计，实现了设备生命周期的完整闭环管理。其数据结构与句柄编码保证了高效稳定的设备索引；数据库事务与错误处理提升了可靠性；与项目/脚本管理器的协作使设备与数据、脚本的联动更加顺畅。在线/离线模式的差异化行为满足多场景需求，配合通信协议与错误码体系，为后续扩展（如云端托管、远程诊断）提供了坚实基础。
+
+## 附录
+- 关键调用路径参考
+  - 初始化设备链表：[DevManager.cpp](file://cpp/Managers/DevManager.cpp#L160-L201)
+  - 查询设备：[DevManager.cpp](file://cpp/Managers/DevManager.cpp#L48-L158)
+  - 在线/离线列表：[DevManager.cpp](file://cpp/Managers/DevManager.cpp#L486-L591)
+  - 更新设备参数：[DevManager.cpp](file://cpp/Managers/DevManager.cpp#L592-L642)
+  - 删除设备：[DevManager.cpp](file://cpp/Managers/DevManager.cpp#L383-L483)
+  - 设备详情展示：[Device.cpp](file://cpp/ProblemZone/Device.cpp#L115-L280)
+  - GR/AC信息展示：[Device.cpp](file://cpp/ProblemZone/Device.cpp#L511-L649)
+  - 文件接收/发送：[Device.cpp](file://cpp/ProblemZone/Device.cpp#L682-L727)
+  - 固件升级触发：[devmngframe.cpp](file://cpp/Views/devmngframe.cpp#L47-L96)
+  - 升级执行与校验：[checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1292-L1336)