添加注释

source/pq_app.h

@@ -157,7 +157,12 @@ struct PqMqEvent {
 
 using PqMqEventFn = std::function<void(const PqMqEvent&)>;
 
-// 默认配置。mq.cpp 会把运行期路径修正到 exe 所在目录旁的 runtime 目录。
+/**
+ * @brief 创建一份完整的默认运行配置。
+ * @details mq.cpp 会把相对路径修正到 exe 所在目录旁的 runtime 目录；GUI 随后再用
+ *          编辑框内容覆盖相应字段。返回值是独立副本，调用方可以安全修改。
+ * @return 包含 HTTP、RocketMQ、Topic/Tag/Key 和落盘路径默认值的 PqToolConfig。
+ */
 PqToolConfig pqDefaultConfig();
 
 /*
@@ -214,17 +219,37 @@ bool pqSendTraceRequest(const PqToolConfig& cfg,
                         PqLogFn log,
                         PqMqEventFn event = {});
 
-// 清空某个追踪目录下的 txt/json/jsonl/log 文本记录，保留目录本身。
+/**
+ * @brief 清空指定装置/测点本次追踪可消费的历史文本记录。
+ * @details 路径由 pqTraceDirectoryFor() 统一计算；只移除 txt、json、jsonl、log 等
+ *          追踪记录并保留目录，以保证点击“数据追踪”后只读取新到达的数据。
+ * @param cfg 包含 traceRootDir 的运行配置。
+ * @param device 当前台账装置，参与进程和装置目录名计算。
+ * @param monitor 当前测点，参与最终目录名计算。
+ */
 void pqClearTraceRecords(const PqToolConfig& cfg,
                          const PqLedgerDevice& device,
                          const PqLedgerMonitor& monitor);
 
-// 按 traceRootDir/process_x/device_x/monitor_x 生成稳定追踪目录。
+/**
+ * @brief 计算某个装置和测点的稳定追踪目录。
+ * @details 目录布局为 traceRootDir/process_x/device_x/monitor_x；实现会清理不适合
+ *          Windows 文件名的字符，所有发送、消费、自动解析流程都应调用本函数，避免
+ *          各模块自行拼路径后指向不同目录。
+ * @return UTF-8 编码的目录字符串；本函数只计算路径，不创建目录。
+ */
 std::string pqTraceDirectoryFor(const PqToolConfig& cfg,
                                 const PqLedgerDevice& device,
                                 const PqLedgerMonitor& monitor);
 
-// 为装置寻找 XML：优先 device.xmlPath，其次 icd_response.json 下载缓存，最后 cfg.xmlPath。
+/**
+ * @brief 为当前装置选择最合适的 ICD/XML 映射模板。
+ * @details 查找顺序为 device.xmlPath、icd_response.json 中的下载缓存、cfg.xmlPath；
+ *          只有实际存在的普通文件才会返回，防止解析阶段拿到失效路径。
+ * @param cfg 提供 XML 缓存目录和用户配置的兜底路径。
+ * @param device 提供装置自身的 xmlPath、devType 等识别信息。
+ * @return 找到时返回 UTF-8 路径，未找到时返回空字符串。
+ */
 std::string pqFindDeviceXmlPath(const PqToolConfig& cfg, const PqLedgerDevice& device);
 
 /*
@@ -266,5 +291,10 @@ bool pqApplyIcdDescriptionsToWorkbook(const std::string& icdPath,
                                       const std::string& workbookPath,
                                       std::string* message = nullptr);
 
-// GUI 入口。main.cpp 无命令行参数时调用，内部创建 Win32 主窗口和消息循环。
+/**
+ * @brief 启动 Win32 图形界面并运行消息循环。
+ * @details main.cpp 在无命令行参数时调用；函数注册窗口类、创建 AppState 和各页面，
+ *          然后通过 GetMessage/DispatchMessage 把用户操作交给 interface.cpp::wndProc。
+ * @return 正常退出时返回消息循环的退出码，初始化失败时返回非零值。
+ */
 int runPqGuiApp();