# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SVN Log Tool is a Java-based application that fetches SVN logs, exports them to Markdown, and uses DeepSeek AI to analyze logs and generate Excel workload reports.

**Tech Stack**: Java 8, Maven, Spring Boot 2.7.18, SVNKit, Apache POI, OkHttp

**Entry Points**:
- CLI: `com.svnlog.Main` - Interactive SVN log fetcher
- Web: `com.svnlog.WebApplication` - Web workbench with REST API (port 8080)
- AI Processor: `com.svnlog.DeepSeekLogProcessor` - Standalone AI analysis tool

## Build & Run Commands

### Build
```bash
# Compile only (fastest validation)
mvn clean compile

# Package with tests
mvn clean package

# Package without tests
mvn clean package -DskipTests
```

### Run
```bash
# Web workbench (recommended)
mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.WebApplication
# Access at http://localhost:8080

# CLI tool
java -jar target/svn-log-tool-1.0.0-jar-with-dependencies.jar

# AI processor
java -cp target/svn-log-tool-1.0.0-jar-with-dependencies.jar com.svnlog.DeepSeekLogProcessor
```

### Test
```bash
# Run all tests
mvn test

# Run single test class
mvn -Dtest=ClassName test

# Run single test method
mvn -Dtest=ClassName#methodName test
```

## Architecture

### Core Components

**SVN Layer** (`com.svnlog`):
- `SVNLogFetcher` - SVN connection, log fetching, user filtering
- `LogEntry` - Log data model
- `Main` - CLI interaction and Markdown generation

**AI Layer** (`com.svnlog`):
- `DeepSeekLogProcessor` - Calls DeepSeek API, generates Excel workload reports

**Web Layer** (`com.svnlog.web`):
- `controller/AppController` - REST API endpoints
- `controller/GlobalExceptionHandler` - Centralized error handling
- `service/TaskService` - Async task orchestration
- `service/SvnWorkflowService` - SVN fetch workflow
- `service/AiWorkflowService` - AI analysis workflow
- `service/TaskPersistenceService` - Task history persistence
- `service/HealthService` - System health checks
- `service/SettingsService` - API key and output directory management
- `service/SvnPresetService` - Preset SVN projects
- `service/OutputFileService` - File listing and downloads
- `service/AiInputValidator` - Input validation (max 20 files, 2MB each)
- `service/RetrySupport` - Retry logic for external calls

**Frontend** (`src/main/resources/static`):
- `index.html` - Main web interface
- `app.js` - Frontend logic
- `styles.css` - Styling

### Data Flow

1. **SVN Fetch**: User input → `SVNLogFetcher` → Markdown file (`outputs/md/*.md`)
2. **AI Analysis**: Markdown → `DeepSeekLogProcessor` → Excel file (`outputs/excel/*.xlsx`)
3. **Web Mode**: REST API → Async tasks → Task history (`outputs/task-history.json`)

### Output Directory Structure
```
outputs/
├── md/              # SVN log Markdown files
├── excel/           # AI-generated Excel reports
└── task-history.json # Task persistence (survives restarts)
```

## Key REST API Endpoints

- `POST /api/svn/test-connection` - Test SVN connection
- `POST /api/svn/fetch` - Async SVN log fetch
- `GET /api/svn/presets` - List preset SVN projects
- `POST /api/ai/analyze` - Async AI analysis
- `GET /api/tasks` - List all tasks
- `GET /api/tasks/query?status=&type=&keyword=&page=1&size=10` - Query tasks
- `POST /api/tasks/{taskId}/cancel` - Cancel running task
- `GET /api/health` - System health status
- `GET /api/files` - List output files
- `GET /api/files/download?path=...` - Download file
- `GET /api/settings` - Get settings
- `PUT /api/settings` - Update settings

## DeepSeek API Configuration

**API Key Priority** (highest to lowest):
1. Request-level `apiKey` parameter
2. Runtime settings (via `/api/settings`)
3. Environment variable `DEEPSEEK_API_KEY`

**Security**: Never commit real API keys. Use environment variables in production.

## Code Style Requirements

- **Java 8 compatibility**: No Java 9+ APIs
- **Imports**: No wildcards, explicit imports only, grouped by: `java.*` / third-party / `com.svnlog.*`
- **Formatting**: 4 spaces, max 120 chars/line, always use braces for `if/for/while`
- **Naming**: `UpperCamelCase` for classes, `lowerCamelCase` for methods/variables, `UPPER_SNAKE_CASE` for constants
- **Resources**: Use try-with-resources for I/O, explicit UTF-8 encoding
- **Error handling**: Never swallow exceptions, provide actionable error messages

## Testing Strategy

- Test directory: `src/test/java/com/svnlog/`
- Naming: `<ClassName>Test`, methods: `should<Behavior>When<Condition>`
- Minimal validation: `mvn clean compile` must pass

## Important Notes

- **Preset SVN projects** are hardcoded in `Main.java` (lines 14-18)
- **Task persistence** enables history recovery after restart
- **AI input limits**: Max 20 files, 2MB each, `.md` only
- **Async tasks** run in background, tracked via `TaskService`
- **Web frontend** is a single-page app with vanilla JS

## When Modifying Code

- SVN logic → `SVNLogFetcher`
- CLI interaction → `Main`
- AI/Excel logic → `DeepSeekLogProcessor`
- Web API → `AppController` + services
- Always update `docs/` if behavior changes
- Run `mvn clean compile` before committing