package com.flowable.devops.workflow.plugin;

import com.flowable.devops.entity.NodeType;
import org.springframework.stereotype.Component;

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

/**
 * 节点插件注解
 * 
 * 用于标记一个类为工作流节点插件，系统会自动扫描并注册
 * 
 * 使用示例：
 * <pre>
 * {@code
 * @NodePlugin(
 *     id = "http_request",
 *     name = "httpRequest", 
 *     displayName = "HTTP Request",
 *     category = NodeCategory.API,
 *     version = "1.0.0",
 *     author = "Flowable Team",
 *     description = "发送HTTP请求到指定URL"
 * )
 * public class HttpRequestNode implements WorkflowNode {
 *     // 实现...
 * }
 * }
 * </pre>
 * 
 * @author Flowable Team
 * @since 1.0.0
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Component  // 继承Spring的@Component，自动注册为Bean
public @interface NodePlugin {
    
    /**
     * 节点唯一ID
     * <p>
     * 必须全局唯一，建议使用下划线命名法
     * 例如：http_request, send_email, database_query
     * 
     * @return 节点ID
     */
    String id();
    
    /**
     * 节点名称（用于代码引用）
     * <p>
     * 建议使用驼峰命名法
     * 例如：httpRequest, sendEmail, databaseQuery
     * 
     * @return 节点名称
     */
    String name();
    
    /**
     * 节点显示名称（用于UI展示）
     * <p>
     * 用户在界面上看到的名称
     * 例如：HTTP Request, Send Email, Database Query
     * 
     * @return 显示名称
     */
    String displayName();
    
    /**
     * 节点分类
     * <p>
     * 用于在前端进行分类展示
     * 
     * @return 节点分类
     */
    NodeType.NodeCategory category();
    
    /**
     * 插件版本
     * <p>
     * 建议遵循语义化版本规范：MAJOR.MINOR.PATCH
     * 例如：1.0.0, 1.2.3, 2.0.0
     * 
     * @return 版本号
     */
    String version() default "1.0.0";
    
    /**
     * 插件作者
     * <p>
     * 可以是个人或团队名称
     * 
     * @return 作者信息
     */
    String author() default "";
    
    /**
     * 插件描述
     * <p>
     * 简要说明插件的功能和用途
     * 
     * @return 插件描述
     */
    String description() default "";
    
    /**
     * 节点图标
     * <p>
     * 支持：
     * - Ant Design 图标名称，例如：api, database, mail
     * - 自定义图标URL
     * - 内置图标关键词
     * 
     * @return 图标标识
     */
    String icon() default "";
    
    /**
     * 是否默认启用
     * <p>
     * true: 插件加载后自动启用
     * false: 插件加载后处于禁用状态，需要手动启用
     * 
     * @return 是否启用
     */
    boolean enabled() default true;
    
    /**
     * 依赖的其他插件
     * <p>
     * 格式：pluginId:version
     * 例如：["base_plugin:1.0.0", "util_plugin:2.1.0"]
     * 
     * @return 依赖列表
     */
    String[] dependencies() default {};
    
    /**
     * 所需的最低平台版本
     * <p>
     * 用于确保插件与平台版本兼容
     * 
     * @return 最低平台版本
     */
    String minPlatformVersion() default "1.0.0";
    
    /**
     * 插件主页URL
     * <p>
     * 可选，提供插件的文档或主页链接
     * 
     * @return 主页URL
     */
    String homepage() default "";
    
    /**
     * 许可证
     * <p>
     * 例如：Apache-2.0, MIT, GPL-3.0
     * 
     * @return 许可证标识
     */
    String license() default "Apache-2.0";
}
