需求注释

src/app.cpp

@@ -9,6 +9,10 @@
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="核心引擎初始化", id="REQ-ENGINE-INIT-001")
+ * 构造函数需初始化系统状态上下文，设置默认运行模式为空闲模式，
+ * 并重置自增计数器，为后续业务操作提供初始状态。
+ *
  * @brief 构造函数，初始化系统状态上下文与自增计数器
  */
 CmsEngine::CmsEngine()
@@ -21,8 +25,11 @@ CmsEngine::CmsEngine()
 }
 
 /**
- * @brief 生成自增唯一标识
+ * @requirement(name="唯一标识生成", id="REQ-UTIL-IDGEN-001")
+ * 系统需支持生成格式为 "ID-xxxxx" 的自增唯一标识，
+ * 用于任务方案、事件等实体的 ID 分配。
  *
+ * @brief 生成自增唯一标识
  * @return std::string 格式如 "ID-00001"
  */
 std::string CmsEngine::generateNextId()
@@ -37,10 +44,11 @@ std::string CmsEngine::generateNextId()
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="战场事件接入", id="REQ-EVENT-INGEST-001")
+ * 系统需支持从外部事件总线接入原始战场事件，执行基本合法性校验
+ * （ID 不能为空、优先级范围检查），通过后存入事件库。
+ *
  * @brief 接入原始战场事件
- *
- * 执行基本合法性校验（ID 不能为空、优先级范围检查），通过后存入事件库。
- *
  * @param event 战场事件
  * @return true  接入成功
  * @return false 接入失败
@@ -58,11 +66,11 @@ bool CmsEngine::ingestEvent(const EventRecord& event)
 }
 
 /**
+ * @requirement(name="待处理事件处理", id="REQ-EVENT-PROC-001")
+ * 系统需遍历事件库中所有 Pending 状态的事件，自动将其状态标记为 Generated，
+ * 并据此生成一个对应的 TaskPlan 草案，实现事件到方案的自动转化。
+ *
  * @brief 处理待处理事件队列
- *
- * 遍历事件库中所有 Pending 状态的事件，自动将其状态标记为 Generated，
- * 并据此生成一个对应的 TaskPlan 草案。
- *
  * @return size_t 处理的事件数量
  */
 size_t CmsEngine::processPendingEvents()
@@ -90,8 +98,11 @@ size_t CmsEngine::processPendingEvents()
 }
 
 /**
- * @brief 根据事件 ID 查找事件
+ * @requirement(name="事件查询", id="REQ-EVENT-QUERY-001")
+ * 系统需支持根据事件 ID 在事件库中查找对应的事件记录，
+ * 找到则返回事件指针，未找到返回 nullptr。
  *
+ * @brief 根据事件 ID 查找事件
  * @param eventId 事件标识
  * @return const EventRecord* 事件指针，未找到返回 nullptr
  */
@@ -110,10 +121,11 @@ const EventRecord* CmsEngine::findEventById(const std::string& eventId) const
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="任务方案创建", id="REQ-PLAN-CREATE-001")
+ * 系统需校验方案名称非空后，为其分配系统 ID 并存入方案库，
+ * 确保方案数据的完整性和可追溯性。
+ *
  * @brief 创建任务方案
- *
- * 校验方案名称非空后，为其分配系统 ID 并存入方案库。
- *
  * @param plan 待创建方案（id 由系统填充）
  * @return true  创建成功
  * @return false 名称不合法
@@ -130,8 +142,10 @@ bool CmsEngine::createTaskPlan(TaskPlan& plan)
 }
 
 /**
- * @brief 获取所有任务方案列表
+ * @requirement(name="任务方案列表查询", id="REQ-PLAN-LIST-001")
+ * 系统需返回全部任务方案列表的引用，以支撑方案全局视图展示。
  *
+ * @brief 获取所有任务方案列表
  * @return const std::vector<TaskPlan>& 方案列表
  */
 const std::vector<TaskPlan>& CmsEngine::getAllPlans() const
@@ -140,8 +154,11 @@ const std::vector<TaskPlan>& CmsEngine::getAllPlans() const
 }
 
 /**
- * @brief 根据 ID 查找任务方案
+ * @requirement(name="任务方案查找", id="REQ-PLAN-FIND-001")
+ * 系统需支持根据任务 ID 在方案库中遍历查找对应方案，
+ * 找到返回方案指针，未找到返回 nullptr。
  *
+ * @brief 根据 ID 查找任务方案
  * @param planId 任务标识
  * @return const TaskPlan* 方案指针，未找到返回 nullptr
  */
@@ -156,8 +173,11 @@ const TaskPlan* CmsEngine::findPlanById(const std::string& planId) const
 }
 
 /**
- * @brief 更新任务方案状态
+ * @requirement(name="任务方案状态更新", id="REQ-PLAN-UPDATE-001")
+ * 系统需支持根据任务 ID 查找方案并更新其状态，返回是否更新成功，
+ * 以驱动方案从草稿到完成的生命周期流转。
  *
+ * @brief 更新任务方案状态
  * @param planId    任务标识
  * @param newStatus 新状态
  * @return true  更新成功
@@ -179,8 +199,10 @@ bool CmsEngine::updatePlanStatus(const std::string& planId, PlanStatus newStatus
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
- * @brief 注册模板实例
+ * @requirement(name="模板注册", id="REQ-TMPL-REG-001")
+ * 系统需支持将模板实例添加到模板库中，为后续场景匹配提供候选模板。
  *
+ * @brief 注册模板实例
  * @param tmpl 模板实例
  */
 void CmsEngine::registerTemplate(const TemplateInstance& tmpl)
@@ -189,10 +211,11 @@ void CmsEngine::registerTemplate(const TemplateInstance& tmpl)
 }
 
 /**
+ * @requirement(name="模板匹配", id="REQ-TMPL-MATCH-001")
+ * 系统需遍历模板库，返回置信度最高的模板（简单策略：置信度最大者），
+ * 空库时返回 nullptr。
+ *
  * @brief 根据场景匹配最佳模板
- *
- * 遍历模板库，返回置信度最高的模板（简单策略：置信度最大者）。
- *
  * @param scenario 场景描述（当前未用于精确匹配，仅做演示）
  * @return const TemplateInstance* 最佳模板，无匹配返回 nullptr
  */
@@ -216,10 +239,11 @@ const TemplateInstance* CmsEngine::matchTemplate(const std::string& scenario) co
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="执行状态上报", id="REQ-MON-REPORT-001")
+ * 系统需将节点遥测数据写入内部状态表，按 nodeId 覆盖更新，
+ * 以维护各节点最新的执行状态。
+ *
  * @brief 上报节点执行状态
- *
- * 将节点遥测数据写入内部状态表，按 nodeId 覆盖更新。
- *
  * @param status 执行状态
  */
 void CmsEngine::reportExecutionStatus(const ExecutionStatus& status)
@@ -228,10 +252,11 @@ void CmsEngine::reportExecutionStatus(const ExecutionStatus& status)
 }
 
 /**
+ * @requirement(name="节点健康检查", id="REQ-MON-HEALTH-001")
+ * 系统需遍历所有节点状态，依据健康指数 < 0.5、异常码 != 0 或
+ * 距最后上报超过 30 秒的判据筛选异常节点，返回异常节点状态列表。
+ *
  * @brief 检查所有节点健康状态
- *
- * 异常判据：健康指数 < 0.5 或异常码 != 0 或心跳超时（距最后上报 > 30秒）。
- *
  * @return std::vector<ExecutionStatus> 异常节点列表
  */
 std::vector<ExecutionStatus> CmsEngine::checkHealth() const
@@ -268,10 +293,10 @@ std::vector<ExecutionStatus> CmsEngine::checkHealth() const
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="用户会话创建", id="REQ-SESS-CREATE-001")
+ * 系统需校验 userId 非空且不重复后存入会话表，确保用户会话的唯一性。
+ *
  * @brief 创建用户会话
- *
- * 校验 userId 非空且不重复后存入会话表。
- *
  * @param session 用户会话
  * @return true  创建成功
  * @return false 用户已存在或 ID 为空
@@ -289,10 +314,11 @@ bool CmsEngine::createSession(const UserSession& session)
 }
 
 /**
+ * @requirement(name="权限校验", id="REQ-SESS-PERM-001")
+ * 系统需检查用户会话的权限位图是否包含所需的权限掩码，
+ * 通过按位与运算进行判定，以保障系统操作安全。
+ *
  * @brief 校验用户权限
- *
- * 检查用户会话的权限位图是否包含所需的权限掩码。
- *
  * @param userId         用户 ID
  * @param permissionMask 所需权限位掩码
  * @return true  有权限
@@ -313,8 +339,10 @@ bool CmsEngine::checkPermission(const std::string& userId,
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
- * @brief 推送通知消息
+ * @requirement(name="通知推送", id="REQ-NOTIF-PUSH-001")
+ * 系统需支持将通知消息添加到消息队列尾部，以支撑系统内实时信息传达。
  *
+ * @brief 推送通知消息
  * @param msg 通知消息
  */
 void CmsEngine::pushNotification(const NotificationMessage& msg)
@@ -323,8 +351,11 @@ void CmsEngine::pushNotification(const NotificationMessage& msg)
 }
 
 /**
- * @brief 获取所有未读通知
+ * @requirement(name="未读通知查询", id="REQ-NOTIF-UNREAD-001")
+ * 系统需遍历通知队列，筛选出所有未读通知并返回列表，
+ * 以支撑用户快速查看待处理信息。
  *
+ * @brief 获取所有未读通知
  * @return std::vector<NotificationMessage> 未读通知列表
  */
 std::vector<NotificationMessage> CmsEngine::getUnreadNotifications() const
@@ -343,10 +374,11 @@ std::vector<NotificationMessage> CmsEngine::getUnreadNotifications() const
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @requirement(name="运行模式切换", id="REQ-MODE-SWITCH-001")
+ * 系统需支持运行模式切换，降级模式下不允许切换到其他模式（模拟故障隔离策略），
+ * 切换成功后更新时间戳和一致性标记。
+ *
  * @brief 切换系统运行模式
- *
- * 降级模式下不允许切换到其他模式（模拟故障隔离策略），其余模式可自由切换。
- *
  * @param newMode 目标模式
  * @return true  切换成功
  * @return false 切换被拒绝
@@ -364,8 +396,11 @@ bool CmsEngine::switchMode(RunMode newMode)
 }
 
 /**
- * @brief 获取当前系统状态上下文
+ * @requirement(name="系统状态查询", id="REQ-MODE-QUERY-001")
+ * 系统需返回当前系统状态上下文的常量引用，包括运行模式、上下文快照、
+ * 一致性标记和切换时间，以支撑状态监控与审计。
  *
+ * @brief 获取当前系统状态上下文
  * @return const SystemStateContext& 状态上下文
  */
 const SystemStateContext& CmsEngine::getSystemContext() const
@@ -374,8 +409,11 @@ const SystemStateContext& CmsEngine::getSystemContext() const
 }
 
 /**
- * @brief 获取引擎摘要信息
+ * @requirement(name="引擎摘要生成", id="REQ-SUMM-GEN-001")
+ * 系统需汇总事件数、方案数、模板数、监控节点数、活跃会话数、
+ * 未读通知数和当前运行模式，生成格式化的引擎运行摘要字符串。
  *
+ * @brief 获取引擎摘要信息
  * @return std::string 包含事件数、方案数、节点数、未读通知数等
  */
 std::string CmsEngine::getSummary() const