suyu_two/app/src/services/hmi_editor_service.h

/**
 * @file hmi_editor_service.h
 * @brief 定义 HMI 页面和控件的编辑用例服务
 * @author suyu
 * @date 2026-08-10
 */

#pragma once

#include "domain/hmi_model.h"

#include <string>

class ProjectService;
struct HmiControlDescriptor;

/**
 * @brief HMI 编辑操作的失败分类
 */
enum class HmiEditorError
{
    None,
    PageNotFound,
    ControlNotFound,
    DuplicateId,
    DuplicateName,
    InvalidPage,
    InvalidControl,
    LastPageRequired,
    InitialPageCannotBeRemoved,
    PageReferenced,
    InvalidOperation
};

/**
 * @brief HMI 编辑操作的统一结果
 *
 * 成功时 `id` 保存新建或更新后的控件或页面标识
 */
struct HmiEditorResult
{
    bool succeeded = false;
    HmiEditorError error = HmiEditorError::None;
    std::string message;
    std::string id;
};

/**
 * @brief 编排 HMI 页面和控件的编辑操作，不依赖 Qt 视图
 *
 * 服务通过 ProjectService 修改工程并负责标记工程为已修改
 */
class HmiEditorService
{
public:
    explicit HmiEditorService(ProjectService &project_service);

    /**
     * @brief 按页面标识查找只读页面
     * @param page_id 页面唯一标识
     * @return 找到时返回页面指针，未找到时返回空指针
     */
    const HmiPage *findPage(const std::string &page_id) const;
    /**
     * @brief 按页面和控件标识查找只读控件
     * @param page_id 所属页面唯一标识
     * @param control_id 控件唯一标识
     * @return 找到时返回控件指针，任一标识不存在时返回空指针
     */
    const HmiControl *findControl(
        const std::string &page_id, const std::string &control_id) const;
    /**
     * @brief 返回工程中第一个 HMI 页面标识
     * @return 工程没有 HMI 页面时返回空字符串
     */
    std::string firstPageId() const;

    /**
     * @brief 在工程没有 HMI 页面时创建默认操作页
     * @return 已有或新建页面的成功结果及其页面标识
     */
    HmiEditorResult ensureDefaultPage();
    HmiEditorResult addPage(const std::string &name);
    HmiEditorResult renamePage(
        const std::string &page_id, const std::string &name);
    HmiEditorResult removePage(const std::string &page_id);
    HmiEditorResult movePage(const std::string &page_id, int offset);
    HmiEditorResult setInitialPage(const std::string &page_id);
    /**
     * @brief 向指定页面添加待配置的基础控件
     * @param page_id 目标页面唯一标识
     * @param type 新控件类型
     * @return 成功时返回新控件标识，页面不存在时返回 PageNotFound
     *
     * 新控件可暂时没有寄存器绑定，完整绑定校验在工程保存前执行
     */
    HmiEditorResult addControl(
        const std::string &page_id, HmiControlType type);
    /**
     * @brief 删除指定页面中的控件
     * @param page_id 所属页面唯一标识
     * @param control_id 待删除控件唯一标识
     * @return 页面或控件不存在时返回对应错误
     */
    HmiEditorResult removeControl(
        const std::string &page_id, const std::string &control_id);
    /**
     * @brief 更新控件位置和尺寸
     * @param page_id 所属页面唯一标识
     * @param control_id 待移动控件唯一标识
     * @param bounds 新矩形，必须完整位于页面范围内
     * @return 页面、控件或矩形无效时返回失败结果
     */
    HmiEditorResult moveControl(
        const std::string &page_id,
        const std::string &control_id,
        const HmiRect &bounds);
    /**
     * @brief 更新控件可编辑属性
     * @param page_id 所属页面唯一标识
     * @param control_id 原控件唯一标识
     * @param control 更新后的控件配置，不允许改变控件类型
     * @return 控件标识重复、绑定区域错误或矩形越界时返回失败结果
     *
     * 允许控件暂时没有必需绑定，完整工程校验仍在保存前执行
     */
    HmiEditorResult updateControl(
        const std::string &page_id,
        const std::string &control_id,
        const HmiControl &control);

private:
    /**
     * @brief 校验控件编辑后仍满足页面内的基础约束
     * @param page 控件所属页面
     * @param control 待校验控件
     * @param error 校验失败时写入原因，可为 nullptr
     * @return 控件标识、尺寸、位置和寄存器绑定区域均有效时返回 true
     */
    bool validateEditableControl(
        const HmiPage &page,
        const HmiControl &control,
        std::string *error) const;
    /**
     * @brief 检查候选控件标识是否与页面内其他控件重复
     * @param page 待检查页面
     * @param excluded_id 更新场景中需要排除的原控件标识
     * @param candidate_id 待使用的控件标识
     * @return 存在同标识的其他控件时返回 true
     */
    static bool hasDuplicateControlId(
        const HmiPage &page,
        const std::string &excluded_id,
        const std::string &candidate_id);
    /**
     * @brief 按控件类型创建带默认属性的新控件
     * @param page 新控件所属页面，用于确定初始位置和唯一标识
     * @param type 新控件类型
     * @return 未绑定寄存器的默认控件配置
     */
    static HmiControl makeControl(
        const HmiPage &page, const HmiControlDescriptor &descriptor);
    /**
     * @brief 在页面内生成带指定前缀的唯一控件标识
     * @param page 待检查页面
     * @param prefix 控件类型对应的标识前缀
     * @return 从 1 开始递增且不与现有控件重复的标识
     */
    static std::string makeUniqueId(
        const HmiPage &page, const std::string &prefix);

    /**
     * @brief 非拥有的工程服务依赖，由应用入口保证生命周期
     */
    ProjectService &project_service_;
};