155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# 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
|