easyfk-web-prd Web 应用

dependencies {
    api project(':easyfk-web:web-simple')
    api project(':easyfk-web:web-common')
}

web-prd
├── web-simple
│   ├── spring-boot-starter-web（排除 Tomcat + Logging）
│   ├── spring-boot-starter-undertow
│   └── easyfk-core
└── web-common
    ├── web-base
    │   ├── easyfk-authority
    │   └── easyfk-core
    ├── easyfk-core
    └── spring-web

web-prd/
├── config/
│   ├── PrdWebConfig.java               # 核心自动配置
│   ├── WebInterceptorRegister.java      # 拦截器注册
│   └── ControllerAspectConfigure.java   # Controller AOP 配置
├── filter/
│   └── RequestBaseFilter.java           # 请求前置过滤器（含安全链）
├── interceptor/
│   └── LocalInterceptor.java            # 本地权限拦截器
├── exception/
│   └── PrdExceptionHandler.java         # 全局异常处理
├── aspect/
│   └── ControllerAspect.java            # Controller 方法拦截切面
├── converter/
│   ├── DateConverter.java               # String → Date
│   ├── LocalDateConverter.java          # String → LocalDate
│   ├── LocalDateTimeConverter.java      # String → LocalDateTime
│   └── LocalTimeConverter.java          # String → LocalTime
├── runner/
│   └── InitResourceRunner.java          # 权限资源自动初始化
├── properties/
│   ├── PrdWebProperties.java            # PRD Web 配置
│   ├── ResourceInitProperties.java      # 资源初始化配置
│   └── ControllerAspectProperties.java  # 切面配置
├── util/
│   ├── FailRequestUtil.java             # 失败响应工具
│   ├── RequestUtil.java                 # 请求工具（URL/Ajax/微信检测）
│   └── StaticUriUtil.java               # 静态资源判断
└── vo/
    ├── LoginRequestVO.java              # 登录请求 VO
    ├── SiteLoginSuccessVO.java          # 登录成功响应 VO
    └── RegistryRequestVO.java           # 注册请求 VO

easyfk:
  config:
    web:
      prd:
        open-interceptor: true
        open-filter: true
        pic-code-cache-name: PicCodes
        code-time-to-live: 5m
      security:
        open: true
        sign-key: "your-sign-key"
        sign-key-dynamic: false
        timeout: 150s
        ignore-uri:
          - /api/public
          - /health
      intercept:
        exclude-paths:
          - /api/login
          - /api/register
        auth-type: 1
        refresh-user-auth: true
      cors:
        open: true
        cors-domain: "https://yourdomain.com"
      jwt:
        secret: "your-jwt-secret"
    aspect:
      controller:
        open: true
        pointcut: "execution(public * com.example..*.controller..*.*(..))"
    resource:
      init:
        open: true
        group: default
        normal: false

HTTP 请求到达
    │
    ├─ TRACE 方法 → 返回 405（安全防护）
    │
    ├─ 静态资源（StaticUriUtil.isStaticUrl）
    │   └─ 直接 filterChain.doFilter()（跳过全部逻辑）
    │
    └─ 非静态请求
        │
        ├─ 1. createTraceId()（生成全链路追踪 ID）
        │
        ├─ 2. doLocalHeaderFilter()（提取 10 个请求头字段）
        │      ├─ accessToken（优先 URL 参数，其次 Header）
        │      ├─ language / resetSign / paramSign
        │      ├─ timestamp / requestToken / accessToken
        │      ├─ requestNonce / deviceNo / clientType
        │      └─ → RequestHeaderContext（ThreadLocal）
        │
        ├─ 3. doDataContext()（JWT 解析 + 用户数据加载）
        │
        ├─ 4. doSecurityFilterMethod()（安全签名校验）
        │      ├─ 忽略白名单 URI → 放行
        │      ├─ 检查请求头完整性（headers/nonce/sign/timestamp）
        │      ├─ 获取签名密钥（静态或动态）
        │      ├─ MD5 签名验证
        │      └─ Nonce 防重放校验（缓存检查 + 写入）
        │
        ├─ 5. filterChain.doFilter()
        │
        └─ finally: clearContext()

签名原文 = "Request-Nonce={nonce}&Timestamp={timestamp}&Key={signKey}"
签名结果 = MD5(签名原文)
验证条件 = 签名结果 == headers.getResetSign()

1. cacheService.existKey(nonce) → 已存在 → API_AGAIN 错误
2. 不存在 → cacheService.cacheObject(nonce, timeout) → 放行
3. timeout 后 nonce 自动过期

请求到达 Controller 方法
    │
    ├─ URI 在排除列表中 → 放行
    │
    ├─ handler 是 HandlerMethod？
    │   │
    │   ├─ 有 @LoginResource 或 @AuthResource？
    │   │   │
    │   │   ├─ UserData 为空 → 返回 UN_LOGIN
    │   │   │
    │   │   ├─ 有 @AuthResource？
    │   │   │   │
    │   │   │   ├─ 检查 authCachedKey → UserAuth 为空 → UN_LOGIN
    │   │   │   │
    │   │   │   └─ authType != 0？
    │   │   │       ├─ checkAuth(key, url) 成功 → 放行
    │   │   │       └─ 失败 → 返回 UN_AUTH + 自定义消息
    │   │   │
    │   │   └─ 只有 @LoginResource → 有 UserData 即放行
    │   │
    │   └─ 无权限注解 → 放行
    │
    └─ 非 HandlerMethod → 放行

execution(public * com.mcst..*.controller..*.*(..))

if (errMsg.contains("Failed to deserialize java.time.LocalDate")) {
    code = "DateFormatErrorMsg";
} else if (errMsg.contains("Failed to deserialize java.time.LocalDateTime")) {
    code = "DateTimeFormatErrorMsg";
} else if (errMsg.contains("Failed to deserialize java.time.LocalTime")) {
    code = "TimeFormatErrorMsg";
}

应用启动（CommandLineRunner，Order=0）
    │
    ├─ open=false → 跳过
    │
    ├─ 扫描 @ResourceController Bean
    │   ├─ group="default" → 全部
    │   └─ group="xxx" → 按组过滤
    │
    └─ 遍历每个 Controller
        │
        ├─ 创建菜单资源（@ResourceController 元数据）
        │
        └─ 遍历所有方法
            ├─ 解析 URL（@GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@RequestMapping）
            ├─ 跳过通配路径（*、{参数}）
            │
            ├─ 有 @AuthResource → 创建权限资源
            └─ 无 @AuthResource + normal=true
                ├─ 有 @LoginResource → level=1（需登录）
                └─ 无注解 → level=0（公开）

// 构建失败响应对象
ResponseResult<?> result = FailRequestUtil.failRequestInfo(ErrorRequest.SIGN_ERROR);

// 直接写入 HTTP 响应
FailRequestUtil.failRequest(httpServletResponse, ErrorRequest.UNLOGIN);
FailRequestUtil.failRequest(httpServletResponse, responseResult);

String url = RequestUtil.getRequestUrl(request);       // 获取去除 contextPath 后的 URI
boolean isAjax = RequestUtil.isAjax(request);           // 判断 Ajax 请求
boolean isWeChat = RequestUtil.isWeChatRequest(request); // 判断微信浏览器
boolean isQQ = RequestUtil.isQqRequest(request);         // 判断 QQ 浏览器

boolean isStatic = StaticUriUtil.isStaticUrl(url);

CorsConfiguration corsConfiguration = new CorsConfiguration();
corsConfiguration.addAllowedOriginPattern(corsProperties.getCorsDomain());
corsConfiguration.addAllowedHeader(corsProperties.getAllowedHeader());
corsConfiguration.addAllowedMethod(corsProperties.getAllowedMethod());
corsConfiguration.setAllowCredentials(true);
corsConfiguration.setMaxAge(3600L);