package com.dne.ems.service;

import org.springframework.security.core.userdetails.UserDetails;

import io.jsonwebtoken.Claims;

/**
 * JWT服务接口，处理JWT令牌的生成、解析和验证
 *
 * <p>安全特性：
 * <ul>
 *   <li>使用HS256算法签名</li>
 *   <li>令牌有效期24小时</li>
 *   <li>包含用户角色和权限声明</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024-03
 */
public interface JwtService {
    /**
     * 从JWT令牌中提取用户名
     *
     * @param token JWT令牌字符串
     * @return 令牌中包含的用户名
     * @throws IllegalArgumentException 如果令牌无效或过期
     */
    String extractUserName(String token);

    /**
     * 提取JWT令牌的所有声明
     *
     * @param token JWT令牌字符串
     * @return 包含所有声明的Claims对象
     */
    Claims extractAllClaims(String token);

    /**
     * 为用户生成JWT令牌
     *
     * @param userDetails 用户详情，包含用户名和权限
     * @return 生成的JWT令牌(有效期24小时)
     */
    String generateToken(UserDetails userDetails);

    /**
     * 验证JWT令牌有效性
     *
     * @param token 待验证的JWT令牌
     * @param userDetails 用户详情用于验证
     * @return true如果令牌有效且匹配用户，false否则
     */
    boolean isTokenValid(String token, UserDetails userDetails);
}