svn-log-tool/CLAUDE.md

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

# Compile only (fastest validation)
mvn clean compile

# Package with tests
mvn clean package

# Package without tests
mvn clean package -DskipTests

Run

# 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

# 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