Nick SzaunigandClaude Opus 5.5
ec8c95056d
Neues README im Root mit Zweck, Aufbau, Start, Prüfbefehlen, Betrieb und Projektstand (Issues #44, #43). Backend- und Frontend-README ersetzen die Framework-Vorlagen. CLAUDE.md: Ordnerstruktur und echte Arbeitsweise (main, gebündelt pushen, Rollout nur mit Freigabe). ARCHITECTURE §7/§8: Live-ConfigMap, ensure-secrets.sh, korrektes Admin-Seed-Verhalten. .env.example um BACKUP_MAX_IMPORT_BYTES und SEED_ADMIN_* ergänzt. Statuszeilen in Plänen Rückgrat, T3–T6 und Specs Fahrplan, T7. Refs #42 Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
96 lines
6.1 KiB
Markdown
96 lines
6.1 KiB
Markdown
# ApiCore
|
||
|
||
Digitale Imkereiverwaltung der Imkerei Wabenhain. ApiCore führt Bienenstände, Völker, Königinnen, Durchsichten, Varroa, Behandlungen und Fütterungen, die Kette Ernte → Schleuderung → Honigcharge → Lager → Abfüllung, Etiketten, Bestand und Herstellung. Dazu kommen Compliance (Bestandsbuch für Tierarzneimittel, Etikett-Pflichtangaben, Behördenpaket, Prüfbereitschaft), ein Saison-Autopilot mit Vorschlägen und ein Offline-Modus für die Arbeit am Stand.
|
||
|
||
Fachliche Quelle der Wahrheit ist das Lastenheft [`docs/lastenheft.md`](docs/lastenheft.md).
|
||
|
||
## Projektstand
|
||
|
||
Was gebaut, geprüft, gemergt und ausgerollt ist, was offen ist und was der Inhaber tun muss, steht im Übersichts-Issue:
|
||
**[Projektstand und Übersicht](https://git.encry.de/Nick.Rosenloecher/ApiCore/issues/44)** · Inhaber-Aufgaben: [Sammelliste](https://git.encry.de/Nick.Rosenloecher/ApiCore/issues/43)
|
||
|
||
Kurzfassung (Stand 2026-10-16):
|
||
|
||
- Im Cluster läuft seit 2026-10-12 das Backend-Image `sha-f5b1964` mit dem Frontend vom selben Tag.
|
||
- Auf `main` fertig, aber noch nicht ausgerollt: Paket 0, Plattform-Rückgrat (Laufrollen `api`/`worker`/`job`, Ereignis-Outbox), T3 Erfassung am Stand, T4 Logik-Ketten und Saison-Autopilot, T6 Compliance, ERP-Inventar-Export und Beute L1. Der Rollout läuft nur Schritt für Schritt mit Freigabe des Inhabers ([Issue #28](https://git.encry.de/Nick.Rosenloecher/ApiCore/issues/28)).
|
||
- In Arbeit: Beute in 3D (L2–L5). Geplant: T5 Optik, T7 Spracherfassung.
|
||
|
||
Die abhakbare Aufgabenliste je Modul steht in [`TASKS.md`](TASKS.md).
|
||
|
||
## Aufbau
|
||
|
||
```
|
||
ApiCore/
|
||
├── ApiCore-Backend/ NestJS-API (TypeScript, Prisma, PostgreSQL), /api/v1
|
||
├── ApiCore-Frontend/ Next.js App Router (TypeScript, Tailwind, shadcn/ui), PWA
|
||
├── deploy/k8s/ Kustomize: base, components, overlays/encry, tests, scripts
|
||
├── docs/ Lastenheft, Prüfberichte, Schnittstellen, Specs und Pläne
|
||
├── .gitea/workflows/ CI: Backend-Image, Frontend-Image, Manifest-Prüfung
|
||
├── ARCHITECTURE.md Module, Datenfluss, Annahmen, Kubernetes, Backup, Sicherheit
|
||
├── CLAUDE.md Arbeitsregeln für Claude Code
|
||
└── TASKS.md Aufgabenliste
|
||
```
|
||
|
||
- **Backend:** NestJS 11, Prisma 7 gegen PostgreSQL 18, class-validator, JWT mit Refresh-Rotation, MFA (TOTP), Entra-ID-SSO, Rechte über `@RequirePermission` (fail-closed). Ein Image läuft in drei Rollen: `api` (HTTP), `worker` (Zustellung der Outbox, Webhooks, Kalender-Sync, Wetter, Telegram) und `job` (Kubernetes-CronJobs). Fachliche Folgen hängen an der Transactional Outbox `DomainEvent` in Postgres. Details: [`ARCHITECTURE.md`](ARCHITECTURE.md) Abschnitt 10.
|
||
- **Frontend:** Next.js 16 (App Router), TanStack Query, Vitest und React Testing Library. Offline-Warteschlange in IndexedDB, Service Worker mit App-Hülle für den Kaltstart ohne Netz.
|
||
- **Schnittstellen nach außen:** Wabenhain-Shop über `GET /api/v1/shop-sync` mit API-Schlüssel ([`docs/pruefung-2026-09.md`](docs/pruefung-2026-09.md)), ERPNext über `GET /api/v1/export/inventar/*` ([`docs/erp-inventar-export.md`](docs/erp-inventar-export.md)), Webhooks mit HMAC-Signatur, Microsoft-365-Kalender, Telegram-Erinnerungen, Wetter von Open-Meteo.
|
||
|
||
## Lokal starten
|
||
|
||
Voraussetzungen: Node.js 22, eine laufende PostgreSQL-Instanz.
|
||
|
||
```bash
|
||
# Backend
|
||
cd ApiCore-Backend
|
||
cp .env.example .env # DATABASE_URL und Secrets eintragen
|
||
npm install
|
||
npx prisma migrate dev # Schema anwenden
|
||
npm run start:dev # http://localhost:3001, Rolle "all" (API + Worker in einem Prozess)
|
||
|
||
# Frontend
|
||
cd ApiCore-Frontend
|
||
cp .env.example .env.local # API_URL zeigt auf das Backend
|
||
npm install
|
||
npm run dev # http://localhost:3000
|
||
```
|
||
|
||
Gibt es noch keinen Benutzer mit `SEED_ADMIN_EMAIL` (Standard `[email protected]`), legt der Seed (`npx prisma db seed` lokal, im Cluster der initContainer `seed`) einen Administrator an und gibt das Passwort einmalig im Log aus (siehe [`ARCHITECTURE.md`](ARCHITECTURE.md) Abschnitt 8).
|
||
|
||
## Prüfen
|
||
|
||
Je Projekt einzeln:
|
||
|
||
```bash
|
||
# ApiCore-Backend/
|
||
npm run lint && npm run typecheck && npm test && npm run build
|
||
npm run test:e2e # braucht eine Test-Datenbank; bei Problemen mit -- --runInBand
|
||
|
||
# ApiCore-Frontend/
|
||
npm run lint && npm run typecheck && npm test && npm run build
|
||
|
||
# Manifeste (Repo-Root)
|
||
kubectl kustomize deploy/k8s/overlays/encry | kubeconform -strict -summary -
|
||
node --test deploy/k8s/tests/manifest-policy.test.mjs
|
||
```
|
||
|
||
Die CI baut bei jedem Push auf `main` die Images (Lint, Typecheck und Unit-Tests laufen im Image-Build) und prüft die Manifeste. Die Backend-e2e-Tests laufen bisher nur lokal ([Issue #32](https://git.encry.de/Nick.Rosenloecher/ApiCore/issues/32)).
|
||
|
||
## Betrieb
|
||
|
||
- RKE2-Cluster, Namespace `apicore`, Ingress über Traefik hinter Cloudflare.
|
||
- `deploy/k8s` ist die Quelle der Wahrheit (Kustomize). Rollout nur nach dem Runbook im Plan [`docs/superpowers/plans/2026-10-13-plattform-rueckgrat.md`](docs/superpowers/plans/2026-10-13-plattform-rueckgrat.md), jeder Schritt mit Freigabe des Inhabers. Vorher immer `kubectl diff -k deploy/k8s/overlays/encry`.
|
||
- Fehlende Secrets ergänzt `deploy/k8s/scripts/ensure-secrets.sh`; Werte stehen nie im Repo.
|
||
- Backups: In-App-Backup (verschlüsselt, CronJob `app-backup`) und täglicher `pg_dump` (CronJob `apicore-db-backup`), siehe [`ARCHITECTURE.md`](ARCHITECTURE.md) Abschnitte 7 und 8.
|
||
|
||
## Doku
|
||
|
||
| Datei | Inhalt |
|
||
|---|---|
|
||
| [`docs/lastenheft.md`](docs/lastenheft.md) | Fachliches Lastenheft (verbindlich) |
|
||
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Modulschnitt, Auth, Rückverfolgbarkeit, Annahmen, Kubernetes, Backup, API-Sicherheit, Rückgrat, T4, T6, Beute |
|
||
| [`TASKS.md`](TASKS.md) | Aufgabenliste je Modul und Teilprojekt |
|
||
| [`docs/pruefung-2026-09.md`](docs/pruefung-2026-09.md) | Prüfmatrix, Bestandsbuch, Überwinterung, Sicherheitsaudit, AuDHD-Anpassung |
|
||
| [`docs/erp-inventar-export.md`](docs/erp-inventar-export.md) | Vertrag der Schnittstelle zu ERPNext |
|
||
| [`docs/superpowers/specs/`](docs/superpowers/specs/) | Designs: Bestandsabgleich, Rückgrat und Fahrplan, T4, T5, T6, T7, Beute |
|
||
| [`docs/superpowers/plans/`](docs/superpowers/plans/) | Umsetzungspläne mit Tasks und Rollout-Runbook |
|