# 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 `admin@apicore.local`), 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 |