package com.annotation;

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

/**
 * 登录用户信息注入注解
 *
 * <p>该注解用于Spring MVC控制器方法参数，实现当前登录用户对象的自动注入，
 * 简化在Controller中获取认证用户信息的操作流程。</p>
 *
 * <p><b>核心功能：</b>
 * <ul>
 *   <li>自动从安全上下文中提取已认证用户信息</li>
 *   <li>避免在每个Controller方法中重复编写用户解析代码</li>
 *   <li>与Spring Security无缝集成</li>
 * </ul>
 *
 * <p><b>典型使用场景：</b>
 * <pre>{@code
 * @GetMapping("/orders")
 * public ResponseEntity<List<Order>> getUserOrders(
 *     @LoginUser User user  // 自动注入当前登录用户
 * ) {
 *     return orderService.findByUser(user);
 * }
 * }</pre>
 *
 * @author YourName
 * @version 1.0
 * @since 2023-10-01
 */
@Target(ElementType.PARAMETER)  // 限定注解仅能标注在方法参数上
@Retention(RetentionPolicy.RUNTIME)  // 注解在运行时保留，可通过反射机制读取
public @interface LoginUser {
    /**
     * 是否强制要求用户登录（默认true）
     *
     * <p>当设置为true时，如果未检测到登录用户，将抛出未授权异常(401)；
     * 设置为false时，未登录则注入null值。</p>
     *
     * @return 是否强制要求登录状态
     */
    boolean required() default true;

    /**
     * 用户角色类型限制（可选）
     *
     * <p>用于指定允许访问的用户角色类型，如：
     * <ul>
     *   <li>UserType.REGULAR - 普通用户</li>
     *   <li>UserType.ADMIN - 管理员</li>
     * </ul>
     * 不匹配时抛出403禁止访问异常。</p>
     *
     * @return 允许访问的用户角色类型
     */
    String[] allowedRoles() default {};
}