package org.dromara.app.mqtt;

import java.util.regex.Pattern;

/**
 * MQTT 消息 Topic 处理器策略接口。
 * <p>
 * 所有上行消息处理器实现此接口，由 {@link MqttMessageDispatcher} 自动发现并路由。
 * 新增 Topic 只需新增实现类并注册为 Spring Bean，无需修改 Dispatcher。
 *
 * @author water team
 */
public interface MqttTopicHandler {

    /**
     * 返回该处理器匹配的 Topic 正则。
     * 必须包含一个捕获组用于提取设备标识（设备编号或 MAC 地址）。
     */
    Pattern topicPattern();

    /**
     * 处理匹配到的消息。
     *
     * @param deviceIdentity 从 Topic 正则中提取的设备标识（设备编号或 MAC 地址）
     * @param payload        消息体（JSON）
     */
    void handle(String deviceIdentity, String payload);

    /**
     * 处理匹配到的消息，并携带 MQTT 消息属性。
     */
    default void handle(String deviceIdentity, String payload, boolean retained) {
        handle(deviceIdentity, payload);
    }
}
