First commit

2026-01-12 13:12:46 +01:00
parent b2d9501f6d
commit a1fbd8acf5
4413 changed files with 1245183 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,122 @@
+# QR-Invoice Service
+
+Swiss QR-Bill PDF Generation Service für Schweizer Zahlscheine nach SIX-Spezifikation.
+
+## Projektübersicht
+
+Ein Node.js/TypeScript HTTP-Service, der JSON-Daten über einen Webhook empfängt und eine PDF mit Swiss QR-Zahlteil generiert.
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+
+- **Sprache**: TypeScript
+- **HTTP Framework**: Fastify 4
+- **PDF-Generierung**: swissqrbill + pdfkit
+- **Validierung**: Zod
+
+## Projektstruktur
+
+```
+src/
+├── index.ts              # Entry Point, startet Server
+├── app.ts                # Fastify App Konfiguration
+├── config/index.ts       # Umgebungsvariablen (PORT, HOST, LOG_LEVEL)
+├── types/                # TypeScript Interfaces
+├── schemas/              # Zod Validierungsschemas
+├── services/             # Business Logic (QR-Bill Generierung)
+├── routes/               # API Endpoints
+└── errors/               # Error Handler
+```
+
+## Wichtige Befehle
+
+```bash
+npm run dev       # Entwicklungsserver mit Hot-Reload (tsx watch)
+npm run build     # TypeScript kompilieren nach dist/
+npm run start     # Produktionsserver starten
+npm run typecheck # TypeScript Typprüfung
+```
+
+## API Endpoints
+
+| Method | Path | Beschreibung |
+|--------|------|--------------|
+| POST | `/api/v1/invoice/qr-bill` | Generiert QR-Bill PDF |
+| GET | `/health` | Health Check |
+| GET | `/health/ready` | Readiness Probe |
+
+## Request Format (POST /api/v1/invoice/qr-bill)
+
+```json
+{
+  "creditor": {
+    "iban": "CH4431999123000889012",
+    "address": {
+      "name": "Firma AG",
+      "street": "Strasse",
+      "buildingNumber": "123",
+      "postalCode": "8000",
+      "city": "Zürich",
+      "country": "CH"
+    }
+  },
+  "amount": 1949.75,
+  "currency": "CHF",
+  "reference": {
+    "type": "QRR",
+    "value": "210000000003139471430009017"
+  },
+  "debtor": {
+    "address": { ... }
+  },
+  "additionalInformation": {
+    "message": "Rechnung Nr. 123"
+  },
+  "options": {
+    "language": "de",
+    "separate": true
+  }
+}
+```
+
+## Validierungsregeln (SIX-Spezifikation)
+
+- **QRR** (QR-Referenz): 27 Ziffern, Modulo 10 rekursiv, erfordert QR-IBAN (IID 30000-31999)
+- **SCOR** (Creditor Reference): ISO 11649, erfordert normale IBAN
+- **NON** (Ohne Referenz): Erfordert normale IBAN
+- **Strukturierte Adressen**: Pflicht seit November 2025
+- **Betrag**: 0.01 - 999'999'999.99, max. 2 Dezimalstellen
+- **Währung**: CHF oder EUR
+
+## Umgebungsvariablen
+
+| Variable | Default | Beschreibung |
+|----------|---------|--------------|
+| PORT | 3000 | Server Port |
+| HOST | 0.0.0.0 | Server Host |
+| LOG_LEVEL | info | Pino Log Level |
+
+## Testen
+
+```bash
+# Server starten
+npm run dev
+
+# Test-Request senden
+curl -X POST http://localhost:3000/api/v1/invoice/qr-bill \
+  -H "Content-Type: application/json" \
+  -d @test-request.json \
+  -o output.pdf
+```
+
+## Wichtige Dateien
+
+- `src/schemas/qr-invoice.schema.ts` - Zod Schema mit Cross-Validation für IBAN/Referenz
+- `src/services/qr-bill.service.ts` - PDF-Generierung mit swissqrbill
+- `src/routes/invoice.routes.ts` - API Endpoint Implementation
+- `test-request.json` - Beispiel-Request für Tests
+
+## Externe Ressourcen
+
+- [SIX QR-Bill Spezifikation](https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.3-en.pdf)
+- [swissqrbill Dokumentation](https://github.com/schoero/swissqrbill)