102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# Backend - AI Context
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: Spring Boot 3.4.2
|
|
- **Language**: Kotlin 1.9.25, Java 21
|
|
- **Database**: PostgreSQL
|
|
- **Migrations**: Liquibase (manual)
|
|
- **PDF Generation**: LaTeX (lualatex) via Thymeleaf templates
|
|
- **API**: Auto-generated server stubs from OpenAPI spec
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run backend (port 8080)
|
|
./gradlew bootRun
|
|
|
|
# Build
|
|
./gradlew build
|
|
|
|
# Generate server stubs (after OpenAPI spec changes)
|
|
./gradlew generate_legalconsenthub_server
|
|
|
|
# Database migrations
|
|
# Never create Liquibase changesets in src/main/resources/db/changelog/
|
|
```
|
|
|
|
---
|
|
|
|
## Seed Data Maintenance
|
|
|
|
The application automatically seeds initial data on first startup:
|
|
|
|
### 1. Template Seeding
|
|
**Seeder:** `InitialApplicationFormTemplateSeeder`
|
|
**File:** `src/main/resources/seed/initial_application_form_template.yaml`
|
|
**Condition:** Seeds if no templates exist (`isTemplate = true`)
|
|
**Purpose:** Comprehensive IT system approval workflow template
|
|
|
|
**IMPORTANT:** Keep this file updated when form structure or validation rules change.
|
|
|
|
### 2. Application Form Seeding
|
|
**Seeder:** `InitialApplicationFormSeeder`
|
|
**File:** `src/main/resources/seed/initial_application_form.yaml`
|
|
**Condition:** Seeds if no forms exist for empty organizationId (`isTemplate = false`)
|
|
**Purpose:** Realistic SAP S/4HANA application form for development and UI testing
|
|
**organizationId:** Empty string (global form visible to all organizations)
|
|
**Content:** Pre-filled IT system introduction form based on the template structure with realistic SAP S/4HANA values
|
|
|
|
**IMPORTANT:** Keep this file synchronized with template changes. When template structure changes, update the demo form accordingly.
|
|
|
|
**Note:**
|
|
- Forms with empty/null organizationId act as "global" forms and are visible to all organizations
|
|
- This allows the demo form to appear regardless of the current organization context
|
|
- The demo form is derived from the template structure with values filled for realistic testing
|
|
- Demonstrates visibility conditions, section spawning, clonable elements, and GDPR compliance features
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/main/resources/templates/application_form_latex_template.tex` | PDF template |
|
|
| `src/main/resources/seed/initial_application_form_template.yaml` | Initial form template (isTemplate=true) |
|
|
| `src/main/resources/seed/initial_application_form.yaml` | SAP S/4HANA demo application form (global, filled with realistic values) |
|
|
| `src/main/resources/db/changelog/` | Liquibase migrations |
|
|
| `src/main/kotlin/com/legalconsenthub/service/ApplicationFormFormatService.kt` | HTML/PDF export logic |
|
|
|
|
---
|
|
|
|
## Rules for AI
|
|
|
|
1. **Never add SQL migrations** - They will be handled by the user
|
|
2. **Use mapper classes** - All DTO ↔ Entity conversions must happen in dedicated mapper classes (never in services/controllers)
|
|
3. **PDF Export Validation** - After changes to form elements, visibility, or spawning:
|
|
- Test both HTML and PDF export for real form instances
|
|
- Verify all element types render correctly
|
|
- Ensure template sections excluded, spawned sections included
|
|
- Hotspots: `ApplicationFormFormatService.kt`, `application_form_latex_template.tex`
|
|
4. **Stateless** - Any implementation must support statelessness for horizontal scaling (multiple instances behind load balancer)
|
|
|
|
### Architecture Guidelines
|
|
- **Service layer** - Business logic lives here
|
|
- **Repository layer** - JPA repositories for data access
|
|
- **Controller layer** - Thin controllers that delegate to services
|
|
- **Mapper layer** - Separate mapper classes for DTO/Entity conversions
|
|
- **Entity layer** - JPA entities with relationships
|
|
|
|
### Code Quality Rules
|
|
- **Never use @Suppress annotations** - Fix the underlying issue instead of suppressing warnings
|
|
- **Controller methods must override generated interfaces** - All public endpoints must be in OpenAPI spec
|
|
|
|
### PDF Generation
|
|
- LaTeX templates in `src/main/resources/templates/`
|
|
- Thymeleaf for dynamic content
|
|
- Use `lualatex` for compilation
|
|
- Escape special LaTeX characters in user input
|
|
- Test PDF generation after form structure changes
|