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.

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 · Inhaber-Aufgaben: Sammelliste

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).
• In Arbeit: Beute in 3D (L2–L5). Geplant: T5 Optik, T7 Spracherfassung.

Die abhakbare Aufgabenliste je Modul steht in 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 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), ERPNext über GET /api/v1/export/inventar/* (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.

# 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 Abschnitt 8).

Prüfen

Je Projekt einzeln:

# 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).

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, 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 Abschnitte 7 und 8.

Doku

Datei	Inhalt
docs/lastenheft.md	Fachliches Lastenheft (verbindlich)
ARCHITECTURE.md	Modulschnitt, Auth, Rückverfolgbarkeit, Annahmen, Kubernetes, Backup, API-Sicherheit, Rückgrat, T4, T6, Beute
TASKS.md	Aufgabenliste je Modul und Teilprojekt
docs/pruefung-2026-09.md	Prüfmatrix, Bestandsbuch, Überwinterung, Sicherheitsaudit, AuDHD-Anpassung
docs/erp-inventar-export.md	Vertrag der Schnittstelle zu ERPNext
docs/superpowers/specs/	Designs: Bestandsabgleich, Rückgrat und Fahrplan, T4, T5, T6, T7, Beute
docs/superpowers/plans/	Umsetzungspläne mit Tasks und Rollout-Runbook