需求注释

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_cms_engine.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_cms_engine.cpp

@@ -1,331 +0,0 @@
-#include <gtest/gtest.h>
-#include <gmock/gmock.h>
-#include "app.hpp"
-#include <string>
-#include <vector>
-#include <chrono>
-
-using namespace testing;
-
-// ============================================================================
-// Test Fixture for CmsEngine
-// ============================================================================
-class CmsEngineTest : public ::testing::Test {
-protected:
-    void SetUp() override {
-        engine = new CmsEngine();
-    }
-
-    void TearDown() override {
-        delete engine;
-    }
-
-    CmsEngine* engine;
-};
-
-// ============================================================================
-// Tests for CmsEngine constructor
-// ============================================================================
-
-/**
- * @brief Test: Constructor initializes system context correctly
- *
- * Verifies that after construction:
- * - currentMode is RunMode::Idle
- * - consistencyMark is 0
- * - switchTime is set (not default)
- * - contextSnapshot contains expected JSON
- */
-TEST_F(CmsEngineTest, testConstructorInitializesSystemContext) {
-    const auto& ctx = engine->getSystemContext();
-    EXPECT_EQ(ctx.currentMode, RunMode::Idle);
-    EXPECT_EQ(ctx.consistencyMark, 0);
-    EXPECT_NE(ctx.switchTime, std::chrono::system_clock::time_point());
-    EXPECT_THAT(ctx.contextSnapshot, HasSubstr("Idle"));
-    EXPECT_THAT(ctx.contextSnapshot, HasSubstr("1.0.0"));
-}
-
-/**
- * @brief Test: Constructor initializes empty containers
- *
- * Verifies that all internal containers are empty after construction.
- */
-TEST_F(CmsEngineTest, testConstructorInitializesEmptyContainers) {
-    EXPECT_EQ(engine->getAllPlans().size(), 0);
-    EXPECT_EQ(engine->getUnreadNotifications().size(), 0);
-    EXPECT_EQ(engine->getSummary().find("Events          : 0"), std::string::npos);
-}
-
-// ============================================================================
-// Tests for ingestEvent
-// ============================================================================
-
-/**
- * @brief Test: Ingest event with valid data succeeds
- *
- * Creates a valid EventRecord with non-empty ID and priority <= 255.
- * Expects ingestEvent to return true.
- */
-TEST_F(CmsEngineTest, testIngestEventValidData) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 100;
-    event.status = EventStatus::Pending;
-    EXPECT_TRUE(engine->ingestEvent(event));
-}
-
-/**
- * @brief Test: Ingest event with empty ID fails
- *
- * Verifies that an event with an empty ID is rejected.
- */
-TEST_F(CmsEngineTest, testIngestEventEmptyId) {
-    EventRecord event;
-    event.id = "";
-    event.priority = 100;
-    EXPECT_FALSE(engine->ingestEvent(event));
-}
-
-/**
- * @brief Test: Ingest event with priority > 255 fails
- *
- * Verifies that an event with priority exceeding 255 is rejected.
- */
-TEST_F(CmsEngineTest, testIngestEventPriorityExceedsMax) {
-    EventRecord event;
-    event.id = "EVT-002";
-    event.priority = 256;
-    EXPECT_FALSE(engine->ingestEvent(event));
-}
-
-/**
- * @brief Test: Ingest event with priority = 0 succeeds (boundary)
- *
- * Verifies that an event with minimum priority (0) is accepted.
- */
-TEST_F(CmsEngineTest, testIngestEventPriorityZero) {
-    EventRecord event;
-    event.id = "EVT-003";
-    event.priority = 0;
-    EXPECT_TRUE(engine->ingestEvent(event));
-}
-
-/**
- * @brief Test: Ingest event with priority = 255 succeeds (boundary)
- *
- * Verifies that an event with maximum valid priority (255) is accepted.
- */
-TEST_F(CmsEngineTest, testIngestEventPriorityMax) {
-    EventRecord event;
-    event.id = "EVT-004";
-    event.priority = 255;
-    EXPECT_TRUE(engine->ingestEvent(event));
-}
-
-/**
- * @brief Test: Ingest multiple events and verify storage
- *
- * Ingests multiple events and checks that they are stored correctly.
- */
-TEST_F(CmsEngineTest, testIngestMultipleEvents) {
-    EventRecord event1;
-    event1.id = "EVT-001";
-    event1.priority = 10;
-    EXPECT_TRUE(engine->ingestEvent(event1));
-
-    EventRecord event2;
-    event2.id = "EVT-002";
-    event2.priority = 20;
-    EXPECT_TRUE(engine->ingestEvent(event2));
-
-    // Verify events are stored by checking processPendingEvents count
-    EXPECT_EQ(engine->processPendingEvents(), 2);
-}
-
-// ============================================================================
-// Tests for processPendingEvents
-// ============================================================================
-
-/**
- * @brief Test: Process pending events with no events
- *
- * When there are no events in the system, processPendingEvents should return 0.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsNoEvents) {
-    EXPECT_EQ(engine->processPendingEvents(), 0);
-}
-
-/**
- * @brief Test: Process pending events with one pending event
- *
- * Ingests one pending event and verifies that processPendingEvents processes it.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsOnePending) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 50;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event);
-
-    EXPECT_EQ(engine->processPendingEvents(), 1);
-}
-
-/**
- * @brief Test: Process pending events with non-pending events only
- *
- * Events with status other than Pending should not be processed.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsNonPendingOnly) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 50;
-    event.status = EventStatus::Generated;
-    engine->ingestEvent(event);
-
-    EXPECT_EQ(engine->processPendingEvents(), 0);
-}
-
-/**
- * @brief Test: Process pending events changes status to Generated
- *
- * After processing, the event status should be changed to Generated.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsChangesStatus) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 50;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event);
-
-    engine->processPendingEvents();
-
-    const EventRecord* processedEvent = engine->findEventById("EVT-001");
-    ASSERT_NE(processedEvent, nullptr);
-    EXPECT_EQ(processedEvent->status, EventStatus::Generated);
-}
-
-/**
- * @brief Test: Process pending events creates TaskPlan
- *
- * Verifies that a TaskPlan is created for each processed event.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsCreatesPlan) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 50;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event);
-
-    engine->processPendingEvents();
-
-    const auto& plans = engine->getAllPlans();
-    ASSERT_EQ(plans.size(), 1);
-    EXPECT_EQ(plans[0].relatedEventId, "EVT-001");
-    EXPECT_EQ(plans[0].status, PlanStatus::Drafting);
-    EXPECT_EQ(plans[0].type, PlanType::Centralized);
-    EXPECT_EQ(plans[0].resourceQuota, 0.5);
-    EXPECT_EQ(plans[0].constraints, "自动生成约束");
-}
-
-/**
- * @brief Test: Process pending events with multiple pending events
- *
- * Verifies that all pending events are processed correctly.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsMultiple) {
-    EventRecord event1;
-    event1.id = "EVT-001";
-    event1.priority = 10;
-    event1.status = EventStatus::Pending;
-    engine->ingestEvent(event1);
-
-    EventRecord event2;
-    event2.id = "EVT-002";
-    event2.priority = 20;
-    event2.status = EventStatus::Pending;
-    engine->ingestEvent(event2);
-
-    EventRecord event3;
-    event3.id = "EVT-003";
-    event3.priority = 30;
-    event3.status = EventStatus::Generated; // Not pending
-    engine->ingestEvent(event3);
-
-    EXPECT_EQ(engine->processPendingEvents(), 2);
-
-    const auto& plans = engine->getAllPlans();
-    EXPECT_EQ(plans.size(), 2);
-}
-
-/**
- * @brief Test: Process pending events generates unique IDs
- *
- * Verifies that each generated TaskPlan has a unique ID.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsUniqueIds) {
-    EventRecord event1;
-    event1.id = "EVT-001";
-    event1.priority = 10;
-    event1.status = EventStatus::Pending;
-    engine->ingestEvent(event1);
-
-    EventRecord event2;
-    event2.id = "EVT-002";
-    event2.priority = 20;
-    event2.status = EventStatus::Pending;
-    engine->ingestEvent(event2);
-
-    engine->processPendingEvents();
-
-    const auto& plans = engine->getAllPlans();
-    EXPECT_NE(plans[0].id, plans[1].id);
-}
-
-/**
- * @brief Test: Process pending events twice does not reprocess
- *
- * After processing, events should not be processed again.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsIdempotent) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 50;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event);
-
-    EXPECT_EQ(engine->processPendingEvents(), 1);
-    EXPECT_EQ(engine->processPendingEvents(), 0);
-}
-
-/**
- * @brief Test: Process pending events with empty event ID (should not be ingested)
- *
- * Events with empty IDs are rejected by ingestEvent, so they won't be processed.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsEmptyIdNotIngested) {
-    EventRecord event;
-    event.id = "";
-    event.priority = 50;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event); // Should return false
-
-    EXPECT_EQ(engine->processPendingEvents(), 0);
-}
-
-/**
- * @brief Test: Process pending events with high priority event
- *
- * Verifies that events with high priority (up to 255) are processed correctly.
- */
-TEST_F(CmsEngineTest, testProcessPendingEventsHighPriority) {
-    EventRecord event;
-    event.id = "EVT-001";
-    event.priority = 255;
-    event.status = EventStatus::Pending;
-    engine->ingestEvent(event);
-
-    EXPECT_EQ(engine->processPendingEvents(), 1);
-
-    const auto& plans = engine->getAllPlans();
-    EXPECT_EQ(plans[0].relatedEventId, "EVT-001");
-}