需求注释

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,240 +0,0 @@
-#include <gtest/gtest.h>
-#include "app.hpp"
-#include <chrono>
-#include <string>
-
-class CmsEngineTest : public ::testing::Test {
-protected:
-    CmsEngine engine;
-
-    EventRecord makeEvent(const std::string& id, int priority, EventStatus status) {
-        EventRecord evt;
-        evt.id = id;
-        evt.priority = priority;
-        evt.status = status;
-        return evt;
-    }
-
-    TaskPlan makePlan(const std::string& name, PlanType type, PlanStatus status) {
-        TaskPlan plan;
-        plan.name = name;
-        plan.type = type;
-        plan.status = status;
-        return plan;
-    }
-
-    TemplateInstance makeTemplate(const std::string& id, double confidence) {
-        TemplateInstance tmpl;
-        tmpl.id = id;
-        tmpl.confidence = confidence;
-        return tmpl;
-    }
-
-    ExecutionStatus makeExecStatus(const std::string& nodeId, double health, int errorCode, std::chrono::system_clock::time_point lastReport) {
-        ExecutionStatus s;
-        s.nodeId = nodeId;
-        s.healthIndex = health;
-        s.errorCode = errorCode;
-        s.lastReport = lastReport;
-        return s;
-    }
-
-    UserSession makeSession(const std::string& userId, uint64_t perm) {
-        UserSession s;
-        s.userId = userId;
-        s.permissionBitmap = perm;
-        return s;
-    }
-
-    NotificationMessage makeNotification(const std::string& id, bool isRead) {
-        NotificationMessage msg;
-        msg.id = id;
-        msg.isRead = isRead;
-        return msg;
-    }
-};
-
-// 1. CmsEngine 构造函数测试
-TEST_F(CmsEngineTest, testConstructorInitializesCorrectly) {
-    EXPECT_EQ(engine.getSystemContext().currentMode, RunMode::Idle);
-    EXPECT_EQ(engine.getSystemContext().consistencyMark, 0);
-}
-
-// 2. generateNextId (私有函数，通过公开接口间接测试)
-TEST_F(CmsEngineTest, testGenerateNextIdIndirect) {
-    TaskPlan plan = makePlan("TestPlan", PlanType::Centralized, PlanStatus::Drafting);
-    EXPECT_TRUE(engine.createTaskPlan(plan));
-    EXPECT_FALSE(plan.id.empty());
-    EXPECT_EQ(plan.id.substr(0, 3), "ID-");
-}
-
-// 3. ingestEvent 正常输入
-TEST_F(CmsEngineTest, testIngestEventValidInput) {
-    EventRecord evt = makeEvent("EVT1", 100, EventStatus::Pending);
-    EXPECT_TRUE(engine.ingestEvent(evt));
-    EXPECT_NE(engine.findEventById("EVT1"), nullptr);
-}
-
-// 3. ingestEvent 边界值：空ID
-TEST_F(CmsEngineTest, testIngestEventEmptyId) {
-    EventRecord evt = makeEvent("", 50, EventStatus::Pending);
-    EXPECT_FALSE(engine.ingestEvent(evt));
-}
-
-// 3. ingestEvent 异常输入：优先级越界
-TEST_F(CmsEngineTest, testIngestEventHighPriority) {
-    EventRecord evt = makeEvent("EVT2", 256, EventStatus::Pending);
-    EXPECT_FALSE(engine.ingestEvent(evt));
-}
-
-// 4. processPendingEvents 正常处理
-TEST_F(CmsEngineTest, testProcessPendingEventsMultiple) {
-    engine.ingestEvent(makeEvent("EVT1", 10, EventStatus::Pending));
-    engine.ingestEvent(makeEvent("EVT2", 20, EventStatus::Pending));
-    EXPECT_EQ(engine.processPendingEvents(), 2);
-    EXPECT_EQ(engine.findEventById("EVT1")->status, EventStatus::Generated);
-    EXPECT_EQ(engine.getAllPlans().size(), 2);
-}
-
-// 5. findEventById 未找到场景
-TEST_F(CmsEngineTest, testFindEventByIdNotFound) {
-    EXPECT_EQ(engine.findEventById("NONEXIST"), nullptr);
-}
-
-// 6. createTaskPlan 正常输入
-TEST_F(CmsEngineTest, testCreateTaskPlanValid) {
-    TaskPlan plan = makePlan("ValidPlan", PlanType::Centralized, PlanStatus::Drafting);
-    EXPECT_TRUE(engine.createTaskPlan(plan));
-    EXPECT_FALSE(plan.id.empty());
-}
-
-// 6. createTaskPlan 边界值：空名称
-TEST_F(CmsEngineTest, testCreateTaskPlanEmptyName) {
-    TaskPlan plan = makePlan("", PlanType::Centralized, PlanStatus::Drafting);
-    EXPECT_FALSE(engine.createTaskPlan(plan));
-}
-
-// 7. getAllPlans 正常获取
-TEST_F(CmsEngineTest, testGetAllPlans) {
-    engine.createTaskPlan(makePlan("P1", PlanType::Centralized, PlanStatus::Drafting));
-    const auto& plans = engine.getAllPlans();
-    EXPECT_EQ(plans.size(), 1);
-    EXPECT_EQ(plans[0].name, "P1");
-}
-
-// 8. findPlanById 正常查找
-TEST_F(CmsEngineTest, testFindPlanById) {
-    TaskPlan plan = makePlan("P1", PlanType::Centralized, PlanStatus::Drafting);
-    engine.createTaskPlan(plan);
-    const auto* found = engine.findPlanById(plan.id);
-    ASSERT_NE(found, nullptr);
-    EXPECT_EQ(found->name, "P1");
-}
-
-// 9. updatePlanStatus 正常更新
-TEST_F(CmsEngineTest, testUpdatePlanStatusSuccess) {
-    TaskPlan plan = makePlan("P1", PlanType::Centralized, PlanStatus::Drafting);
-    engine.createTaskPlan(plan);
-    auto planId = engine.getAllPlans()[0].id;
-    EXPECT_TRUE(engine.updatePlanStatus(planId, static_cast<PlanStatus>(1)));
-    EXPECT_EQ(engine.findPlanById(planId)->status, static_cast<PlanStatus>(1));
-}
-
-// 10. registerTemplate 正常注册
-TEST_F(CmsEngineTest, testRegisterTemplate) {
-    TemplateInstance tmpl = makeTemplate("T1", 0.8);
-    engine.registerTemplate(tmpl);
-    EXPECT_EQ(engine.matchTemplate("any")->id, "T1");
-}
-
-// 11. matchTemplate 空列表边界
-TEST_F(CmsEngineTest, testMatchTemplateEmptyList) {
-    EXPECT_EQ(engine.matchTemplate("scenario"), nullptr);
-}
-
-// 11. matchTemplate 最高置信度匹配
-TEST_F(CmsEngineTest, testMatchTemplateHighestConfidence) {
-    engine.registerTemplate(makeTemplate("T1", 0.7));
-    engine.registerTemplate(makeTemplate("T2", 0.9));
-    const auto* best = engine.matchTemplate("any");
-    ASSERT_NE(best, nullptr);
-    EXPECT_EQ(best->id, "T2");
-}
-
-// 12. reportExecutionStatus 正常上报
-TEST_F(CmsEngineTest, testReportExecutionStatus) {
-    auto now = std::chrono::system_clock::now();
-    ExecutionStatus s = makeExecStatus("N1", 0.9, 0, now);
-    engine.reportExecutionStatus(s);
-    EXPECT_EQ(engine.checkHealth().size(), 0);
-}
-
-// 13. checkHealth 异常节点检测
-TEST_F(CmsEngineTest, testCheckHealthUnhealthyNode) {
-    auto now = std::chrono::system_clock::now();
-    engine.reportExecutionStatus(makeExecStatus("N1", 0.4, 0, now));
-    auto unhealthy = engine.checkHealth();
-    EXPECT_EQ(unhealthy.size(), 1);
-    EXPECT_EQ(unhealthy[0].nodeId, "N1");
-}
-
-// 14. createSession 正常创建与重复拦截
-TEST_F(CmsEngineTest, testCreateSessionValidAndDuplicate) {
-    UserSession s1 = makeSession("U1", 0xFF);
-    UserSession s2 = makeSession("U1", 0xAA);
-    EXPECT_TRUE(engine.createSession(s1));
-    EXPECT_FALSE(engine.createSession(s2));
-}
-
-// 15. checkPermission 权限校验
-TEST_F(CmsEngineTest, testCheckPermission) {
-    engine.createSession(makeSession("U1", 0x0F));
-    EXPECT_TRUE(engine.checkPermission("U1", 0x03));
-    EXPECT_FALSE(engine.checkPermission("U1", 0x10));
-    EXPECT_FALSE(engine.checkPermission("UNKNOWN", 0x01));
-}
-
-// 16. pushNotification 正常推送
-TEST_F(CmsEngineTest, testPushNotification) {
-    engine.pushNotification(makeNotification("MSG1", false));
-    EXPECT_EQ(engine.getUnreadNotifications().size(), 1);
-}
-
-// 17. getUnreadNotifications 过滤已读
-TEST_F(CmsEngineTest, testGetUnreadNotificationsFilter) {
-    engine.pushNotification(makeNotification("MSG1", false));
-    engine.pushNotification(makeNotification("MSG2", true));
-    auto unread = engine.getUnreadNotifications();
-    EXPECT_EQ(unread.size(), 1);
-    EXPECT_EQ(unread[0].id, "MSG1");
-}
-
-// 18. switchMode 正常切换
-TEST_F(CmsEngineTest, testSwitchModeNormal) {
-    EXPECT_TRUE(engine.switchMode(RunMode::HumanLoop));
-    EXPECT_EQ(engine.getSystemContext().currentMode, RunMode::HumanLoop);
-}
-
-// 18. switchMode 降级模式限制
-TEST_F(CmsEngineTest, testSwitchModeDegradedRestriction) {
-    engine.switchMode(RunMode::Degraded);
-    EXPECT_FALSE(engine.switchMode(RunMode::AutoExec));
-    EXPECT_TRUE(engine.switchMode(RunMode::Degraded));
-}
-
-// 19. getSystemContext 状态获取
-TEST_F(CmsEngineTest, testGetSystemContext) {
-    const auto& ctx = engine.getSystemContext();
-    EXPECT_EQ(ctx.currentMode, RunMode::Idle);
-    EXPECT_FALSE(ctx.contextSnapshot.empty());
-}
-
-// 20. getSummary 摘要生成
-TEST_F(CmsEngineTest, testGetSummaryContent) {
-    engine.ingestEvent(makeEvent("E1", 10, EventStatus::Pending));
-    engine.createTaskPlan(makePlan("P1", PlanType::Centralized, PlanStatus::Drafting));
-    auto summary = engine.getSummary();
-    EXPECT_NE(summary.find("Events          : 1"), std::string::npos);
-    EXPECT_NE(summary.find("Plans           : 1"), std::string::npos);
-    EXPECT_NE(summary.find("Mode            : Idle"), std::string::npos);
-}