docs: update AGENTS.md with testing, API generation, and architecture details
- Add test commands and patterns (JUnit 5, Mockito, Vitest) - Document OpenAPI generation workflow (OpenApiGeneratorTest) - Add EDA simulation details (magic values, @Profile behavior) - Correct admin endpoint paths - Add important files table including OpenApiGeneratorTest
This commit is contained in:
parent
8546dcc508
commit
9c147adadd
114
AGENTS.md
114
AGENTS.md
@ -12,17 +12,69 @@ Energiegemeinschaftsverwaltung, Mitgliedschaften und Tarife.
|
|||||||
|
|
||||||
### Backend (Spring Boot)
|
### Backend (Spring Boot)
|
||||||
- **Java 21**, Spring Boot 4.0.6
|
- **Java 21**, Spring Boot 4.0.6
|
||||||
|
- **Datenbank:** H2 im PostgreSQL-Modus (`jdbc:h2:file:./eegportal;MODE=PostgreSQL`)
|
||||||
|
- **ORM:** Spring Data JPA + Hibernate (`ddl-auto: update`)
|
||||||
|
- **Annotation Processing:** Lombok + MapStruct (mit `unmappedTargetPolicy=ERROR`)
|
||||||
- **Pakete:**
|
- **Pakete:**
|
||||||
- `iam/` - Identitäts- und Zugriffsverwaltung (Auth, Users, Security)
|
- `iam/` - Identitäts- und Zugriffsverwaltung (Auth, Users, Security)
|
||||||
- `community/` - Energiegemeinschaften, Mitgliedschaften, Messpunkte
|
- `community/` - Energiegemeinschaften, Mitgliedschaften, Messpunkte
|
||||||
- `mako/` - EDA-Kommunikation (Consent, Topologie)
|
- `mako/` - EDA-Kommunikation (Consent, Topologie)
|
||||||
- `tariff/` - Tarifverwaltung
|
- `tariff/` - Tarifverwaltung (nur Domain-Entity, noch kein Service)
|
||||||
- `dashboard/` - Dashboard-Statistiken
|
- `dashboard/` - Dashboard-Statistiken
|
||||||
- `common/` - Events, Exceptions, gemeinsame Types
|
- `common/` - Events, Exceptions, gemeinsame Types
|
||||||
|
|
||||||
### Frontend (Angular)
|
### Frontend (Angular)
|
||||||
- Angular 21, TypeScript 5.9, Tailwind CSS 4
|
- Angular 21, TypeScript 5.9, Tailwind CSS 4, Angular Material
|
||||||
- API-Client wird aus OpenAPI-Spec generiert (`npm run generate-api`)
|
- API-Client wird aus OpenAPI-Spec generiert (`npm run generate-api`)
|
||||||
|
- Test-Framework: Vitest
|
||||||
|
- Code-Style: Prettier (100 Zeichen, Single Quotes, Angular HTML Parser)
|
||||||
|
|
||||||
|
## Entwicklung starten
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Backend
|
||||||
|
.\mvnw spring-boot:run -pl eeg_backend -Dspring-boot.run.arguments=--spring.profiles.active=dev
|
||||||
|
|
||||||
|
# Frontend
|
||||||
|
cd eeg_frontend && ng serve
|
||||||
|
```
|
||||||
|
|
||||||
|
**Wichtig:** Backend muss zuerst laufen (port 8080), da Frontend auf `localhost:8080` proxyt.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Backend: Alle Tests
|
||||||
|
.\mvnw test -pl eeg_backend
|
||||||
|
|
||||||
|
# Backend: Einzelnen Test laden
|
||||||
|
.\mvnw test -pl eeg_backend -Dtest=MembershipServiceTest
|
||||||
|
|
||||||
|
# Backend: OpenAPI-Spec generieren (startet Backend + schreibt nach eeg_frontend/openapi.yaml)
|
||||||
|
.\mvnw test -pl eeg_backend -Dtest=OpenApiGeneratorTest
|
||||||
|
|
||||||
|
# Frontend: Alle Tests
|
||||||
|
cd eeg_frontend && ng test
|
||||||
|
```
|
||||||
|
|
||||||
|
**Test-Pattern:**
|
||||||
|
- Backend: JUnit 5 + Mockito (`@ExtendWith(MockitoExtension.class)`)
|
||||||
|
- Frontend: Vitest (nicht Karma/Jasmine)
|
||||||
|
- Keine Integrationstests mit echter DB (H2 in-memory für Tests)
|
||||||
|
|
||||||
|
## API-Vertrag generieren
|
||||||
|
|
||||||
|
Wenn sich Backend-Controller ändern, muss die OpenAPI-Spec aktualisiert werden:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Backend laufen lassen oder Test ausführen
|
||||||
|
.\mvnw test -pl eeg_backend -Dtest=OpenApiGeneratorTest
|
||||||
|
|
||||||
|
# 2. Frontend-API-Client generieren
|
||||||
|
cd eeg_frontend && npm run generate-api
|
||||||
|
```
|
||||||
|
|
||||||
|
Die Datei `eeg_frontend/openapi.yaml` wird vom Backend-Test (`OpenApiGeneratorTest`) generiert - nicht manuell pflegen.
|
||||||
|
|
||||||
## Wichtige Patterns
|
## Wichtige Patterns
|
||||||
|
|
||||||
@ -41,20 +93,19 @@ NEW → WAITING_FOR_CONSENT → CONSENT_GRANTED → ACTIVE
|
|||||||
REJECTED / ERROR
|
REJECTED / ERROR
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### EDA-Simulation
|
||||||
|
- AT-Nummer endet mit "REJECT" → Ablehnung
|
||||||
|
- AT-Nummer endet mit "ERROR" → technischer Fehler
|
||||||
|
- Sonst: automatische Zustimmung
|
||||||
|
- Simulierte Services haben **kein `@Profile`** - sie sind immer aktiv (auch in prod)
|
||||||
|
- Konfigurierbar: `eda.simulation.consent-delay-ms` (default: 3000ms)
|
||||||
|
|
||||||
### Sicherheit
|
### Sicherheit
|
||||||
- JWT-basiert (HS256), 2h Ablauf
|
- JWT-basiert (HS256), 2h Ablauf
|
||||||
- Rollen: `ADMIN`, `MEMBER`
|
- Rollen: `ADMIN`, `MEMBER` (aus JWT-Claim `role`)
|
||||||
- Admin-Endpunkte: `/api/admin/**`, `/api/community/admin/**`
|
- Admin-Endpunkte: `/api/community/admin/**`, `/api/iam/admin/**`, `/api/mako/admin/**`
|
||||||
|
- `@Profile("dev")` nur für: `AdminDataInitializer`, `ConsoleMailService`
|
||||||
## Entwicklung starten
|
- `@Profile("prod")` für: `SmtpMailService`
|
||||||
|
|
||||||
```bash
|
|
||||||
# Backend
|
|
||||||
.\mvnw spring-boot:run -pl eeg_backend -Dspring-boot.run.arguments=--spring.profiles.active=dev
|
|
||||||
|
|
||||||
# Frontend
|
|
||||||
cd eeg_frontend && ng serve
|
|
||||||
```
|
|
||||||
|
|
||||||
## Wichtige Dateien
|
## Wichtige Dateien
|
||||||
|
|
||||||
@ -64,40 +115,13 @@ cd eeg_frontend && ng serve
|
|||||||
| `eeg_backend/.../community/event/listener/MakoConsentListener.java` | Consent-Event-Handler |
|
| `eeg_backend/.../community/event/listener/MakoConsentListener.java` | Consent-Event-Handler |
|
||||||
| `eeg_backend/.../mako/event/listener/EdaCommuncationEventListener.java` | EDA-Kommunikation |
|
| `eeg_backend/.../mako/event/listener/EdaCommuncationEventListener.java` | EDA-Kommunikation |
|
||||||
| `eeg_backend/.../iam/config/AdminDataInitializer.java` | Initialer Admin-User (dev) |
|
| `eeg_backend/.../iam/config/AdminDataInitializer.java` | Initialer Admin-User (dev) |
|
||||||
|
| `eeg_backend/.../OpenApiGeneratorTest.java` | Generiert OpenAPI-Spec |
|
||||||
| `eeg_frontend/openapi.yaml` | API-Vertrag für Frontend-Generierung |
|
| `eeg_frontend/openapi.yaml` | API-Vertrag für Frontend-Generierung |
|
||||||
|
| `eeg_frontend/src/app/app.routes.ts` | Frontend-Routing (alle Pages) |
|
||||||
|
|
||||||
## Regeln
|
## Regeln
|
||||||
|
|
||||||
- Fehlernachrichten sind auf **Deutsch**
|
- Fehlernachrichten sind auf **Deutsch**
|
||||||
- `@Profile("dev")` für simulierte EDA-Services
|
|
||||||
- EDA-Simulation: AT-Nummer endet mit "REJECT" → Ablehnung, "ERROR" → technischer Fehler
|
|
||||||
- Explizite `isEnabled()`-Überschreibung in `User.java` nötig (Lombok/Spring Security Konflikt)
|
- Explizite `isEnabled()`-Überschreibung in `User.java` nötig (Lombok/Spring Security Konflikt)
|
||||||
|
- Conventional Commits: `<type>(<scope>): <description>` (feat/fix/docs/style/refactor/test/chore)
|
||||||
## Conventional Commits
|
- Scopes: `iam`, `community`, `mako`, `tariff`, `dashboard`, `common`, `frontend`
|
||||||
|
|
||||||
Ab jetzt werden [Conventional Commits](https://www.conventionalcommits.org/) verwendet:
|
|
||||||
|
|
||||||
```
|
|
||||||
<type>(<scope>): <description>
|
|
||||||
|
|
||||||
[optional body]
|
|
||||||
|
|
||||||
[optional footer]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Typen
|
|
||||||
- `feat`: Neue Funktion
|
|
||||||
- `fix`: Bugfix
|
|
||||||
- `docs`: Dokumentation
|
|
||||||
- `style`: Formatierung (keine Code-Änderung)
|
|
||||||
- `refactor`: Code-Refactoring ohne Funktionsänderung
|
|
||||||
- `test`: Tests hinzugefügt/ergänzt
|
|
||||||
- `chore`: Build-Prozess, Abhängigkeiten, Konfiguration
|
|
||||||
|
|
||||||
### Beispiele
|
|
||||||
```
|
|
||||||
feat(iam): add user profile management
|
|
||||||
fix(mako): handle consent rejected event correctly
|
|
||||||
docs: update AGENTS.md with conventional commits
|
|
||||||
test(iam): add UserService unit tests
|
|
||||||
```
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user