需求注释

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

tests/CMakeLists.txt

@@ -1,25 +0,0 @@
-cmake_minimum_required(VERSION 3.10.0)
-project(test_plan_execute_t1)
-include(FetchContent)
-if (MSVC)
-    add_compile_options(/utf-8)
-endif()
-FetchContent_Declare(
-  googletest
-  URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
-)
-# For Windows: Prevent overriding the parent project's compiler/linker settings
-set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-FetchContent_MakeAvailable(googletest)
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../include)
-
-include(CTest)
-enable_testing()
-
-add_executable(test_plan_execute_t1 test_app.cpp ../src/app.cpp)
-
-target_link_libraries(test_plan_execute_t1 gtest gmock gtest_main)
-include(GoogleTest)
-gtest_discover_tests(test_plan_execute_t1)

tests/test_app.cpp

@@ -1,192 +0,0 @@
-#include <gtest/gtest.h>
-#include <string>
-#include <vector>
-#include <chrono>
-#include "app.hpp"
-
-// ============================================================================
-// 测试夹具：CmsEngineTest
-// ============================================================================
-class CmsEngineTest : public ::testing::Test {
-protected:
-    CmsEngine engine;
-
-    void SetUp() override {
-        // 每个测试用例开始前重置引擎状态
-    }
-
-    void TearDown() override {
-        // 每个测试用例结束后清理
-    }
-
-    // 辅助函数：创建一个有效的事件记录
-    EventRecord createValidEvent(const std::string& id = "EVT-001",
-                                  uint32_t priority = 100,
-                                  EventStatus status = EventStatus::Pending) {
-        EventRecord event;
-        event.id = id;
-        event.priority = priority;
-        event.status = status;
-        event.timestamp = std::chrono::system_clock::now();
-        event.source = "TestSource";
-        event.description = "Test event description";
-        return event;
-    }
-};
-
-// ============================================================================
-// ingestEvent 函数测试
-// ============================================================================
-
-// 测试用例 1：正常输入测试 - 有效事件接入成功
-TEST_F(CmsEngineTest, testIngestEventValidEvent) {
-    EventRecord event = createValidEvent();
-    bool result = engine.ingestEvent(event);
-    EXPECT_TRUE(result);
-}
-
-// 测试用例 2：边界值测试 - 事件 ID 为空字符串
-TEST_F(CmsEngineTest, testIngestEventEmptyId) {
-    EventRecord event = createValidEvent("", 100);
-    bool result = engine.ingestEvent(event);
-    EXPECT_FALSE(result);
-}
-
-// 测试用例 3：边界值测试 - 事件优先级为 0（最小值）
-TEST_F(CmsEngineTest, testIngestEventPriorityZero) {
-    EventRecord event = createValidEvent("EVT-002", 0);
-    bool result = engine.ingestEvent(event);
-    EXPECT_TRUE(result);
-}
-
-// 测试用例 4：边界值测试 - 事件优先级为 255（最大值）
-TEST_F(CmsEngineTest, testIngestEventPriorityMax) {
-    EventRecord event = createValidEvent("EVT-003", 255);
-    bool result = engine.ingestEvent(event);
-    EXPECT_TRUE(result);
-}
-
-// 测试用例 5：异常输入测试 - 事件优先级超过 255
-TEST_F(CmsEngineTest, testIngestEventPriorityExceedsMax) {
-    EventRecord event = createValidEvent("EVT-004", 256);
-    bool result = engine.ingestEvent(event);
-    EXPECT_FALSE(result);
-}
-
-// 测试用例 6：异常输入测试 - 事件优先级为极大值
-TEST_F(CmsEngineTest, testIngestEventPriorityVeryHigh) {
-    EventRecord event = createValidEvent("EVT-005", 1000);
-    bool result = engine.ingestEvent(event);
-    EXPECT_FALSE(result);
-}
-
-// 测试用例 7：特殊场景测试 - 多次接入相同 ID 的事件
-TEST_F(CmsEngineTest, testIngestEventDuplicateId) {
-    EventRecord event1 = createValidEvent("EVT-006", 50);
-    EventRecord event2 = createValidEvent("EVT-006", 100);
-    EXPECT_TRUE(engine.ingestEvent(event1));
-    EXPECT_TRUE(engine.ingestEvent(event2));
-}
-
-// 测试用例 8：特殊场景测试 - 接入大量事件
-TEST_F(CmsEngineTest, testIngestEventMultipleEvents) {
-    const size_t eventCount = 100;
-    for (size_t i = 0; i < eventCount; ++i) {
-        EventRecord event = createValidEvent("EVT-" + std::to_string(i), i % 256);
-        EXPECT_TRUE(engine.ingestEvent(event));
-    }
-}
-
-// ============================================================================
-// processPendingEvents 函数测试
-// ============================================================================
-
-// 测试用例 9：正常输入测试 - 处理单个待处理事件
-TEST_F(CmsEngineTest, testProcessPendingEventsSingleEvent) {
-    EventRecord event = createValidEvent("EVT-010", 100, EventStatus::Pending);
-    engine.ingestEvent(event);
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, 1);
-}
-
-// 测试用例 10：正常输入测试 - 处理多个待处理事件
-TEST_F(CmsEngineTest, testProcessPendingEventsMultipleEvents) {
-    for (int i = 0; i < 5; ++i) {
-        EventRecord event = createValidEvent("EVT-" + std::to_string(i + 100), 50, EventStatus::Pending);
-        engine.ingestEvent(event);
-    }
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, 5);
-}
-
-// 测试用例 11：边界值测试 - 没有待处理事件（事件状态为 Generated）
-TEST_F(CmsEngineTest, testProcessPendingEventsNoPendingEvents) {
-    EventRecord event = createValidEvent("EVT-200", 100, EventStatus::Generated);
-    engine.ingestEvent(event);
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, 0);
-}
-
-// 测试用例 12：边界值测试 - 事件队列为空
-TEST_F(CmsEngineTest, testProcessPendingEventsEmptyQueue) {
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, 0);
-}
-
-// 测试用例 13：边界值测试 - 混合状态的事件
-TEST_F(CmsEngineTest, testProcessPendingEventsMixedStatus) {
-    EventRecord pendingEvent1 = createValidEvent("EVT-300", 100, EventStatus::Pending);
-    EventRecord pendingEvent2 = createValidEvent("EVT-301", 200, EventStatus::Pending);
-    EventRecord generatedEvent = createValidEvent("EVT-302", 150, EventStatus::Generated);
-    engine.ingestEvent(pendingEvent1);
-    engine.ingestEvent(pendingEvent2);
-    engine.ingestEvent(generatedEvent);
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, 2);
-}
-
-// 测试用例 14：特殊场景测试 - 处理事件后状态变为 Generated
-TEST_F(CmsEngineTest, testProcessPendingEventsStatusChange) {
-    EventRecord event = createValidEvent("EVT-400", 100, EventStatus::Pending);
-    engine.ingestEvent(event);
-    engine.processPendingEvents();
-    const EventRecord* foundEvent = engine.findEventById("EVT-400");
-    ASSERT_NE(foundEvent, nullptr);
-    EXPECT_EQ(foundEvent->status, EventStatus::Generated);
-}
-
-// 测试用例 15：特殊场景测试 - 处理事件后生成对应的 TaskPlan
-TEST_F(CmsEngineTest, testProcessPendingEventsGeneratesPlan) {
-    EventRecord event = createValidEvent("EVT-500", 100, EventStatus::Pending);
-    engine.ingestEvent(event);
-    engine.processPendingEvents();
-    const auto& plans = engine.getAllPlans();
-    ASSERT_EQ(plans.size(), 1);
-    EXPECT_EQ(plans[0].relatedEventId, "EVT-500");
-    EXPECT_EQ(plans[0].name, "AutoPlan-EVT-500");
-    EXPECT_EQ(plans[0].type, PlanType::Centralized);
-    EXPECT_EQ(plans[0].status, PlanStatus::Drafting);
-    EXPECT_EQ(plans[0].resourceQuota, 0.5);
-    EXPECT_EQ(plans[0].constraints, "自动生成约束");
-}
-
-// 测试用例 16：特殊场景测试 - 多次调用 processPendingEvents
-TEST_F(CmsEngineTest, testProcessPendingEventsMultipleCalls) {
-    EventRecord event1 = createValidEvent("EVT-600", 100, EventStatus::Pending);
-    engine.ingestEvent(event1);
-    size_t firstCall = engine.processPendingEvents();
-    EXPECT_EQ(firstCall, 1);
-    size_t secondCall = engine.processPendingEvents();
-    EXPECT_EQ(secondCall, 0);
-}
-
-// 测试用例 17：特殊场景测试 - 大量待处理事件
-TEST_F(CmsEngineTest, testProcessPendingEventsLargeBatch) {
-    const size_t eventCount = 1000;
-    for (size_t i = 0; i < eventCount; ++i) {
-        EventRecord event = createValidEvent("EVT-" + std::to_string(i + 1000), i % 256, EventStatus::Pending);
-        engine.ingestEvent(event);
-    }
-    size_t processed = engine.processPendingEvents();
-    EXPECT_EQ(processed, eventCount);
-}