98 lines
No EOL
3.7 KiB
Markdown
98 lines
No EOL
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
LCC (Logistic Cost Calculator) is a Spring Boot 3.5.9 backend API for calculating complex logistics costs across supply chain networks. It handles materials, packaging, transportation rates, route planning, and multi-component cost calculations including customs duties, handling, inventory, and risk assessment.
|
|
|
|
## Build & Run Commands
|
|
|
|
```bash
|
|
# Build the project
|
|
mvn clean install
|
|
|
|
# Run the application
|
|
mvn spring-boot:run
|
|
|
|
# Run all tests
|
|
mvn test
|
|
|
|
# Run a specific test class
|
|
mvn test -Dtest=NodeControllerIntegrationTest
|
|
|
|
# Run a specific test method
|
|
mvn test -Dtest=NodeControllerIntegrationTest#shouldReturnListOfNodesWithDefaultPagination
|
|
|
|
# Skip tests during build
|
|
mvn clean install -DskipTests
|
|
|
|
# Generate JAXB classes from WSDL (EU taxation service)
|
|
mvn jaxb:generate
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Layered Architecture
|
|
```
|
|
Controllers → DTOs → Services → Transformers → Repositories → MySQL
|
|
```
|
|
|
|
### Package Structure (`de.avatic.lcc`)
|
|
- **controller/** - REST endpoints organized by domain (calculation, configuration, bulk, users, report)
|
|
- **service/access/** - Business logic for domain entities (PremisesService, MaterialService, NodeService, etc.)
|
|
- **service/calculation/** - Logistics cost calculation orchestration and step services
|
|
- **service/calculation/execution/steps/** - Individual calculation components (airfreight, handling, inventory, customs, etc.)
|
|
- **service/bulk/** - Excel-based bulk import/export operations
|
|
- **service/api/** - External API integrations (Azure Maps geocoding, EU taxation)
|
|
- **service/transformer/** - Entity-to-DTO mapping
|
|
- **repositories/** - JDBC-based data access (not JPA) with custom RowMappers
|
|
- **model/db/** - Database entity classes
|
|
- **dto/** - Data transfer objects for API contracts
|
|
|
|
### Key Design Decisions
|
|
- **JDBC over JPA**: Uses `JdbcTemplate` and `NamedParameterJdbcTemplate` for complex queries
|
|
- **Transformer layer**: Explicit DTO mapping keeps entities separate from API contracts
|
|
- **Calculation chain**: Cost calculations broken into fine-grained services in `execution/steps/`
|
|
|
|
### Core Calculation Flow
|
|
```
|
|
CalculationExecutionService.launchJobCalculation()
|
|
→ ContainerCalculationService (container type selection: FEU/TEU/HC/TRUCK)
|
|
→ RouteSectionCostCalculationService (per-section costs)
|
|
→ AirfreightCalculationService
|
|
→ HandlingCostCalculationService
|
|
→ InventoryCostCalculationService
|
|
→ CustomCostCalculationService (tariff/duties)
|
|
```
|
|
|
|
### Authorization Model
|
|
Role-based access control via `@PreAuthorize` annotations:
|
|
- SUPER, CALCULATION, MATERIAL, FREIGHT, PACKAGING, BASIC
|
|
|
|
## Testing
|
|
|
|
Integration tests use:
|
|
- `@SpringBootTest` + `@AutoConfigureMockMvc`
|
|
- `@Transactional` for test isolation
|
|
- `@Sql` annotations for test data setup/cleanup from `src/test/resources/master_data/`
|
|
- MySQL database (requires env.properties with DB_DATABASE, DB_USER, DB_PASSWORD)
|
|
|
|
## Database
|
|
|
|
- **MySQL** with Flyway migrations in `src/main/resources/db/migration/`
|
|
- Migration naming: `V{N}__{Description}.sql`
|
|
- Key tables: `premiss`, `premiss_sink`, `premiss_route`, `calculation_job`, `node`, `material`, `packaging`, `container_rate`, `country_matrix_rate`
|
|
|
|
## External Integrations
|
|
|
|
- **Azure AD**: OAuth2/OIDC authentication
|
|
- **Azure Maps**: Geocoding and route distance calculations (GeoApiService, DistanceApiService)
|
|
- **EU Taxation API**: TARIC nomenclature lookup for customs duties (EUTaxationApiService)
|
|
|
|
## Configuration
|
|
|
|
Key properties in `application.properties`:
|
|
- `lcc.auth.identify.by` - User identification method (workday)
|
|
- `calculation.job.processor.*` - Async calculation job settings
|
|
- Flyway enabled by default; migrations run on startup |