docs: README im Root, Backend/Frontend-READMEs, Statuszeilen (2026-10-16)

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]>
2026-10-16 08:12:49 +02:00
1 parent b48fb157c8
commit ec8c95056d
@@ -0,0 +1,95 @@
+# 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 |