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;

/**
 * 批量异步处理：框架把多次同类调用聚合成 {@code List} 交给方法。
 *
 * <p>处理方法签名需接收 {@code List<T>}，返回 {@code List<VehicleEvent>} 或单个
 * {@code VehicleEvent}。Dispatcher 不直接调用目标方法，而是交给
 * {@code AsyncBatchExecutor} 按 size/waitMs 聚合后调用。
 *
 * <p>注意：当调用方需要给每条事件补不同的 rawArchiveUri 等逐条元数据时，执行器会按单条 flush，
 * 以保证事件与原始帧一一对应。
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface AsyncBatch {

    /** 达到该批量大小后立即 flush。 */
    int size() default 1000;

    /** 第一条消息入队后最多等待毫秒数，避免低流量车辆长期不出批。 */
    long waitMs() default 500;

    /** 每个 Handler 方法对应的批处理 worker 数。 */
    int poolSize() default 2;
}
