# AGENTS.md - tianai-captcha-enhanced

## 项目概述

基于 tianai-captcha 1.5.5 开源版的增强版行为验证码，目标是复现增强版全部功能并自建验证码服务平台。

## 技术栈

| 组件 | 版本 |
|------|------|
| JDK | 21 (Microsoft OpenJDK 21.0.11 LTS) |
| Maven | 3.9.16 |
| Spring Boot | 3.4.5 |
| Lombok | 1.18.42 (后续逐步移除) |
| SLF4J | 2.0.17 |
| ONNX Runtime | 1.22.0 (ML推理，待引入) |

## 环境路径

```powershell
$env:JAVA_HOME = "C:\Users\USER879511\.jdks\ms-21.0.11"
$env:PATH = "$env:JAVA_HOME\bin;$env:PATH"
$Maven = "D:\Middleware\environment\apache-maven-3.9.16\bin\mvn.cmd"
```

## 构建 & 验证

```powershell
$env:JAVA_HOME = "C:\Users\USER879511\.jdks\ms-21.0.11"
& "D:\Middleware\environment\apache-maven-3.9.16\bin\mvn.cmd" -f "D:\tianai-captcha-enhanced\pom.xml" compile
& "D:\Middleware\environment\apache-maven-3.9.16\bin\mvn.cmd" -f "D:\tianai-captcha-enhanced\pom.xml" package -DskipTests
```

## 项目版本

从 `1.5.5` 升级到 `2.0.0-SNAPSHOT`，表示这是增强版的开发版本。

## 模块结构

```
tianai-captcha-enhanced/
├── tianai-captcha/                    # 核心模块 (JDK 21, Spring Boot 3.4)
├── tianai-captcha-springboot-starter/ # Spring Boot Starter (3.4.5)
├── tianai-captcha-web-sdk/            # 前端SDK (待增强)
├── tianai-captcha-platform/           # 管理平台后端 (待创建)
└── tianai-captcha-platform-ui/        # 管理平台前端 (待创建)
```

## 增强版功能计划

### 验证码类型 (对标官网16种)

| 类型 | 常量 | 开源版 | 增强版 | 优先级 |
|------|------|:------:|:------:|:------:|
| 滑块验证 | SLIDER | ✅ | ✅ | P0 |
| 滑块验证V2 | SLIDER_V2 | ❌ | 🔜 | P1 |
| 曲线滑块 | CURVE_SLIDER | ❌ | 🔜 | P1 |
| 曲线滑块V2 | CURVE_SLIDER_V2 | ❌ | 🔜 | P2 |
| 曲线滑块V3 | CURVE_SLIDER_V3 | ❌ | 🔜 | P2 |
| 旋转验证 | ROTATE | ✅ | ✅ | P0 |
| 滑动还原 | CONCAT | ✅ | ✅ | P0 |
| 角度验证 | ANGLE | ❌ | 🔜 | P1 |
| 刮刮乐 | SCRATCH | ❌ | 🔜 | P1 |
| 文字点选 | WORD_IMAGE_CLICK | ✅ | ✅ | P0 |
| 图标点选 | ICON_CLICK | ❌ | 🔜 | P1 |
| 语序点选 | WORD_ORDER_CLICK | ❌ | 🔜 | P1 |
| 乱序拼图 | JIGSAW | ❌ | 🔜 | P1 |
| 曲线绘制 | CURVE_DRAW | ❌ | 🔜 | P2 |
| 工作量证明 | PROOF_OF_WORK | ❌ | 🔜 | P2 |
| 随机 | RANDOM | ✅ | ✅ | P0 |

### 增强功能 (对标付费版10项)

| 功能 | 优先级 | 状态 |
|------|:------:|:----:|
| 全新加密算法 (AES-256 + RSA-4096 + SHA256) | P0 | 🔜 |
| ML轨迹校验器 (规则引擎 + ONNX) | P0 | 🔜 |
| 位置校验 (动态容错) | P0 | ✅ 已有基础 |
| 验证码背景乱序 | P1 | 🔜 |
| 差异校验 (防重放) | P1 | 🔜 |
| 请求次数校验 (滑动窗口限流) | P1 | 🔜 |
| 点选类图片背景扭曲 | P1 | 🔜 |
| IP禁用 | P1 | 🔜 |
| 轨迹相似性校验 (DTW) | P2 | 🔜 |
| 轨迹段落区分 | P2 | 🔜 |

### 平台化功能

| 功能 | 状态 |
|------|:----:|
| 站点管理 (SiteKey/SecretKey) | 🔜 |
| verifyToken 一次性消费 | 🔜 |
| 前端SDK (兼容TPCaptcha API) | 🔜 |
| 管理后台 | 🔜 |
| 统计监控 | 🔜 |

## 编码规范

- 包结构遵循开源版: application/generator/validator/resource/interceptor/cache/common
- 新增包: crypto/obfuscator/risk/site/ml
- API 响应统一使用 ApiResponse<T>
- 暂时保留 Lombok，后续逐步替换为手写 getter/setter