83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development Commands
|
|
|
|
- **Start development server**: `./mvnw` (runs Spring Boot with Vaadin dev mode)
|
|
- **Build for production**: `./mvnw -Pproduction package`
|
|
- **Clean build**: `./mvnw clean compile`
|
|
|
|
## Architecture Overview
|
|
|
|
This is a **Vaadin Spring Boot** application for job/task management with real-time mobile app communication via MQTT. The system manages logistics jobs with tasks that mobile app users complete.
|
|
|
|
### Core Architecture Layers
|
|
|
|
**Frontend**: Vaadin Flow views (server-side rendered)
|
|
- `src/main/java/de/assecutor/votianlt/pages/view/` - Main UI views
|
|
- `src/main/java/de/assecutor/votianlt/pages/base/ui/` - Shared UI components
|
|
|
|
**Backend Services**:
|
|
- `src/main/java/de/assecutor/votianlt/service/` - Business logic
|
|
- `src/main/java/de/assecutor/votianlt/controller/` - MQTT message handling
|
|
- `src/main/java/de/assecutor/votianlt/repository/` - MongoDB data access
|
|
|
|
**Models**:
|
|
- `src/main/java/de/assecutor/votianlt/model/` - Domain entities
|
|
- Task hierarchy: `BaseTask` with subtypes (`PhotoTask`, `BarcodeTask`, `SignatureTask`, etc.)
|
|
|
|
### Key Architectural Patterns
|
|
|
|
**Job-Task Relationship**: Jobs contain multiple ordered tasks. Tasks have completion states and can store completion data (photos, barcodes, signatures).
|
|
|
|
**User Hierarchy**:
|
|
- `User` - Web interface users (job managers)
|
|
- `AppUser` - Mobile app users (task executors)
|
|
- `AppUser.owner` field links to `User` for notifications
|
|
|
|
**MQTT Communication**:
|
|
- `MqttV5ClientManager` handles bidirectional communication with mobile apps
|
|
- `MessageController` routes inbound MQTT messages and processes task completions
|
|
- Topics: `/server/{clientId}/task_completed`, `/server/login`, etc.
|
|
|
|
**History Tracking**: `JobHistoryService` logs all job/task changes with detailed audit trail displayed in `JobHistoryView`.
|
|
|
|
**Email Notifications**: `EmailService` sends notifications for job creation, task completion, and job completion using Spring Mail with SMTP.
|
|
|
|
## Data Storage
|
|
|
|
**MongoDB Collections**:
|
|
- `jobs` - Main job entities with status tracking
|
|
- `tasks` - Polymorphic task storage (discriminated by `taskType`)
|
|
- `job_history` - Audit trail for all job changes
|
|
- `photos`, `barcodes`, `signatures` - Task completion data
|
|
- `users` - Web interface users
|
|
- `app_user` - Mobile app users
|
|
- `cargo_item` - Job cargo/delivery items
|
|
|
|
## Configuration
|
|
|
|
**Database**: MongoDB at `192.168.180.25:27017/votianlt`
|
|
**MQTT**: HiveMQ client connects to `mqtt-2.assecutor.de` with credentials `app`/`apppwd`
|
|
**Email**: SMTP via `mailhub.assecutor.org:587` using Spring Boot mail auto-configuration
|
|
|
|
## Development Environment
|
|
|
|
**Java 21** with **Spring Boot 3.4.3** and **Vaadin 24.7.0**
|
|
**Security**: Spring Security with role-based access (`USER` role required)
|
|
**Profiles**: `production` profile available for optimized builds
|
|
|
|
## Key Integration Points
|
|
|
|
When adding new task types:
|
|
1. Extend `BaseTask` and add to `@JsonSubTypes`
|
|
2. Add completion logic in `MessageController.handleTaskCompleted()`
|
|
3. Update `JobHistoryView` for task-specific previews if needed
|
|
|
|
When modifying job status flow:
|
|
1. Update `JobStatus` enum
|
|
2. Modify `EmailService.updateJobStatusToCompleted()` logic
|
|
3. Consider email notification templates
|
|
|
|
MQTT message routing follows pattern: extract `taskType` from payload, route to appropriate processor method in `MessageController`. |