package com.lingniu.ingest.api.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 方法级路由注解：声明此方法处理哪些协议消息。
 *
 * <p>{@link #command} 和 {@link #infoType} 的含义由各协议自行解释，Dispatcher 只负责匹配：
 * <ul>
 *   <li>GB/T 32960：{@code command} = 0x01 车辆登入 / 0x02 实时上报 / ...；{@code infoType} = 信息体 ID
 *   <li>JT/T 808：{@code command} = 消息 ID（0x0100 / 0x0200 / ...）；{@code infoType} 留空
 *   <li>MQTT：{@code command} 可为 topic hash 或忽略
 * </ul>
 *
 * <p>同一个方法可以声明多个 command/infoType。Dispatcher 会按协议、command、infoType 精确路由；
 * 32960 实时上报解析后通常由 0x02/0x03 主命令加信息体 ID 决定落到哪个 Handler。
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MessageMapping {

    /** 协议主命令或消息 ID，空数组表示该维度不限制。 */
    int[] command() default {};

    /** 协议子类型，GB32960 中对应信息体 ID；空数组表示该维度不限制。 */
    int[] infoType() default {};

    /** 仅用于日志/Swagger/排障展示，不参与路由。 */
    String desc() default "";
}
