mirror of
https://github.com/dromara/tianai-captcha.git
synced 2026-05-24 03:02:43 +08:00
fix: 修复点选验证码图片文字缩放的bug
This commit is contained in:
tianai
@@ -0,0 +1,233 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
必须用中文回复我
|
||||
## Project Overview
|
||||
|
||||
tianai-captcha (天爱验证码/TAC) is a Java-based behavioral CAPTCHA library supporting multiple verification types:
|
||||
- **SLIDER**: Slide-to-fit puzzle captcha
|
||||
- **ROTATE**: Rotation verification captcha
|
||||
- **CONCAT**: Slide-to-restore captcha
|
||||
- **WORD_IMAGE_CLICK**: Text-click verification captcha
|
||||
|
||||
The project is a multi-module Maven project with Java 8 compatibility.
|
||||
|
||||
## Build Commands
|
||||
|
||||
```bash
|
||||
# Build the entire project (skips tests by default)
|
||||
mvn clean install
|
||||
|
||||
# Build without skipping tests
|
||||
mvn clean install -DskipTests=false
|
||||
|
||||
# Build specific module
|
||||
cd tianai-captcha
|
||||
mvn clean install
|
||||
|
||||
# Package for deployment
|
||||
mvn clean package
|
||||
|
||||
# Generate javadoc
|
||||
mvn javadoc:javadoc
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
mvn test
|
||||
|
||||
# Run tests for specific module
|
||||
cd tianai-captcha
|
||||
mvn test
|
||||
|
||||
# Run a specific test class
|
||||
mvn test -Dtest=TACBuilderTest
|
||||
|
||||
# Run a specific test method
|
||||
mvn test -Dtest=TACBuilderTest#testMethod
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Modules
|
||||
|
||||
1. **tianai-captcha** (core module)
|
||||
- Core captcha generation and validation logic
|
||||
- Generator implementations for each captcha type
|
||||
- Resource management system
|
||||
- Cache and storage abstractions
|
||||
|
||||
2. **tianai-captcha-springboot-starter**
|
||||
- Spring Boot auto-configuration
|
||||
- Redis integration support
|
||||
- Configuration properties binding
|
||||
|
||||
3. **tianai-captcha-solon-plugin**
|
||||
- Solon framework integration
|
||||
|
||||
4. **tianai-captcha-web-sdk**
|
||||
- Frontend JavaScript SDK
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Key Components
|
||||
|
||||
**ImageCaptchaApplication** (cloud.tianai.captcha.application.ImageCaptchaApplication)
|
||||
- Main entry point for captcha operations
|
||||
- Handles captcha generation via `generateCaptcha(type)`
|
||||
- Handles validation via `matching(id, matchParam)`
|
||||
- Manages lifecycle of generators, validators, and cache
|
||||
|
||||
**TACBuilder** (cloud.tianai.captcha.application.TACBuilder)
|
||||
- Builder pattern for constructing ImageCaptchaApplication
|
||||
- Fluent API for configuration
|
||||
- Key methods:
|
||||
- `addDefaultTemplate()`: Load built-in templates
|
||||
- `addResource(type, resource)`: Add background images
|
||||
- `addTemplate(type, resourceMap)`: Add custom templates
|
||||
- `addFont(resource)`: Add fonts for WORD_IMAGE_CLICK
|
||||
- `cached(size, waitTime, period, expireTime)`: Enable pre-generation cache
|
||||
- `setCacheStore(store)`: Set cache implementation (local or distributed)
|
||||
- `setResourceStore(store)`: Set resource storage
|
||||
- `setTransform(transform)`: Set image transformation (default: Base64)
|
||||
|
||||
### Generator Layer
|
||||
|
||||
**MultiImageCaptchaGenerator** (cloud.tianai.captcha.generator.impl.MultiImageCaptchaGenerator)
|
||||
- Delegates to specific generators based on captcha type
|
||||
- Manages resource loading and image transformation
|
||||
|
||||
**Specific Generators**:
|
||||
- `StandardSliderImageCaptchaGenerator`: Generates slider puzzles
|
||||
- `StandardRotateImageCaptchaGenerator`: Generates rotation captchas
|
||||
- `StandardConcatImageCaptchaGenerator`: Generates slide-to-restore captchas
|
||||
- `StandardWordClickImageCaptchaGenerator`: Generates text-click captchas
|
||||
|
||||
**CacheImageCaptchaGenerator** (cloud.tianai.captcha.generator.impl.CacheImageCaptchaGenerator)
|
||||
- Wrapper that pre-generates captchas for improved performance
|
||||
- Configurable cache size and refresh intervals
|
||||
|
||||
### Validator Layer
|
||||
|
||||
**ImageCaptchaValidator** (cloud.tianai.captcha.validator.ImageCaptchaValidator)
|
||||
- Interface for captcha validation logic
|
||||
- Default implementation: `SimpleImageCaptchaValidator`
|
||||
|
||||
**BasicCaptchaTrackValidator** (cloud.tianai.captcha.validator.impl.BasicCaptchaTrackValidator)
|
||||
- Validates mouse/touch track data
|
||||
- Checks for suspicious behavior patterns
|
||||
|
||||
### Resource Management
|
||||
|
||||
**ResourceStore** (cloud.tianai.captcha.resource.ResourceStore)
|
||||
- Abstraction for storing captcha resources (images, templates)
|
||||
- Implementations:
|
||||
- `LocalMemoryResourceStore`: In-memory storage
|
||||
- Custom implementations for distributed scenarios
|
||||
|
||||
**ImageCaptchaResourceManager** (cloud.tianai.captcha.resource.ImageCaptchaResourceManager)
|
||||
- Manages resource loading and retrieval
|
||||
- Default implementation: `DefaultImageCaptchaResourceManager`
|
||||
|
||||
**Resource** (cloud.tianai.captcha.resource.common.model.dto.Resource)
|
||||
- Represents a resource with type and location
|
||||
- Types: "classpath", "file", "url"
|
||||
|
||||
### Cache Layer
|
||||
|
||||
**CacheStore** (cloud.tianai.captcha.cache.CacheStore)
|
||||
- Abstraction for caching captcha data
|
||||
- Implementations:
|
||||
- `LocalCacheStore`: Local in-memory cache
|
||||
- Redis-based implementation in Spring Boot starter
|
||||
|
||||
### Image Transformation
|
||||
|
||||
**ImageTransform** (cloud.tianai.captcha.generator.ImageTransform)
|
||||
- Converts generated images to desired format
|
||||
- Default: `Base64ImageTransform` (JPG for background, PNG for template)
|
||||
|
||||
## Configuration
|
||||
|
||||
### Non-Spring Projects
|
||||
|
||||
Use TACBuilder to configure:
|
||||
|
||||
```java
|
||||
ImageCaptchaApplication app = TACBuilder.builder()
|
||||
.addDefaultTemplate()
|
||||
.addResource("SLIDER", new Resource("classpath", "path/to/image.jpg"))
|
||||
.cached(20, 5000, 2000, 120000L)
|
||||
.build();
|
||||
```
|
||||
|
||||
### Spring Boot Projects
|
||||
|
||||
Configure via application.yml:
|
||||
|
||||
```yaml
|
||||
captcha:
|
||||
prefix: captcha # Cache key prefix
|
||||
expire:
|
||||
default: 120000 # Default expiration (ms)
|
||||
WORD_IMAGE_CLICK: 180000 # Type-specific expiration
|
||||
init-default-resource: false # Load built-in resources
|
||||
local-cache-enabled: true # Enable pre-generation cache
|
||||
local-cache-size: 20 # Cache size
|
||||
local-cache-wait-time: 5000 # Wait time on cache miss (ms)
|
||||
local-cache-period: 2000 # Cache refresh interval (ms)
|
||||
font-path: # Font files for WORD_IMAGE_CLICK
|
||||
- classpath:font/simhei.ttf
|
||||
```
|
||||
|
||||
## Important Constants
|
||||
|
||||
**CaptchaTypeConstant** (cloud.tianai.captcha.common.constant.CaptchaTypeConstant)
|
||||
- `SLIDER`: Slide-to-fit captcha
|
||||
- `ROTATE`: Rotation captcha
|
||||
- `CONCAT`: Slide-to-restore captcha
|
||||
- `WORD_IMAGE_CLICK`: Text-click captcha
|
||||
|
||||
**ParamKeyEnum** (cloud.tianai.captcha.generator.common.model.dto.ParamKeyEnum)
|
||||
- `TOLERANT`: Configurable tolerance value for validation (added in recent commit)
|
||||
|
||||
## Key Data Flow
|
||||
|
||||
### Generation Flow
|
||||
1. Client calls `ImageCaptchaApplication.generateCaptcha(type)`
|
||||
2. `MultiImageCaptchaGenerator` selects appropriate generator
|
||||
3. Generator loads resources via `ImageCaptchaResourceManager`
|
||||
4. Generator creates captcha with random parameters
|
||||
5. `ImageTransform` converts images to Base64 (or custom format)
|
||||
6. Captcha data cached in `CacheStore` with unique ID
|
||||
7. Returns `ImageCaptchaVO` with ID and image data
|
||||
|
||||
### Validation Flow
|
||||
1. Client submits ID and track data via `matching(id, matchParam)`
|
||||
2. Application retrieves cached captcha data by ID
|
||||
3. `ImageCaptchaValidator` validates track against expected answer
|
||||
4. `BasicCaptchaTrackValidator` checks track behavior patterns
|
||||
5. Returns `ApiResponse` with success/failure status
|
||||
|
||||
## Extension Points
|
||||
|
||||
- **Custom Generators**: Implement `ImageCaptchaGenerator` interface
|
||||
- **Custom Validators**: Implement `ImageCaptchaValidator` interface
|
||||
- **Custom Cache**: Implement `CacheStore` (e.g., Redis, Memcached)
|
||||
- **Custom Resources**: Implement `ResourceStore` for centralized resource management
|
||||
- **Custom Transform**: Implement `ImageTransform` for different image formats
|
||||
- **Interceptors**: Implement `CaptchaInterceptor` for pre/post processing
|
||||
|
||||
## Recent Changes
|
||||
|
||||
- Added support for Spring Boot 4 (commit: db0603a, 7c8730f)
|
||||
- Fixed resource leak issues (commits: 16e517c, 29279e8)
|
||||
- Added configurable tolerance value via `ParamKeyEnum.TOLERANT` (commit: a4f8a99)
|
||||
|
||||
## Documentation
|
||||
|
||||
- Online Demo: http://captcha.tianai.cloud
|
||||
- Online Documentation: http://doc.captcha.tianai.cloud
|
||||
- License: MulanPSL-2.0
|
||||
Reference in New Issue
Block a user