docs(10): capture phase context

2026-07-17 13:49:35 +02:00
parent eb3ed949a9
commit b482c4aaa7
2 changed files with 126 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Phase 10: Ausschreibungs-Radar Foundation & DÖE Ingestion - Context
+
+**Gathered:** 2026-07-17
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Fundament des Ausschreibungs-Radar-Moduls: ein neues, im Marketplace registrierbares Tessera-Modul (wie DKV-Fleet/Cert-Manager), das deutsche Ausschreibungen über die DÖE OpenData-API abruft, in ein einheitliches, **plattform-globales** (nicht mandantengebundenes) OCDS-orientiertes Schema normalisiert, Änderungen an bestehenden Einträgen erkennt und alles über einen mandantensicheren **poll-once-fan-out-many**-Scheduler betreibt.
+
+Requirements: CONFIG-01, INGEST-01, INGEST-06, SCHEMA-01, SCHEMA-02.
+
+Nicht in dieser Phase: Filter/UI/Suchprofile (Phase 11), Benachrichtigungen (Phase 12), Scraping-Adapter + Dedup (Phase 13), RSS/E-Mail/i18n-Rollout (Phase 14).
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### DÖE-Ingest-Umfang
+- **D-01:** Initialer Backfill = **nur ab jetzt**. Beim ersten plattformweiten DÖE-Poll werden nur ab diesem Zeitpunkt veröffentlichte Ausschreibungen aufgenommen — kein historischer Import. Da die Tender-Daten global sind, sieht ein später aktivierender Mandant den seit Plattformstart aufgelaufenen Bestand. Passt zur späteren Backfill-Unterdrückung bei Benachrichtigungen (Phase 12).
+- **D-02:** Nur **offene Ausschreibungen** (aktive Vergaben, auf die man bieten kann — tender/contract notices). Vergabeergebnisse, Zuschläge und Aufhebungen (award/result notices) werden in dieser Phase NICHT aufgenommen.
+- **D-03:** Ingest lädt **ganz Deutschland global** (plattformweit einmal), **keine** Vor-Eingrenzung nach Region/CPV beim Ingest — Eingrenzung passiert erst pro Suchprofil (Phase 11). Bewusst wegen Multi-Tenant-Wiederverkauf.
+- **D-04:** Standard-Poll-Intervall = **stündlich**, admin-konfigurierbar (INGEST-06).
+
+### Datenaufbewahrung
+- **D-05:** Ausschreibungen nach Ablauf der Abgabefrist werden **90 Tage** aufbewahrt, dann gelöscht. Vor Fristablauf: aktiv. Nach Fristablauf: als „abgelaufen" markiert, standardmäßig aus der aktiven Liste ausgeblendet, aber bis zur Löschung recherchierbar.
+
+### Claude's Discretion
+- Exakte Prisma-Schema-Felder (OCDS-orientiert, Form gemäß ARCHITECTURE.md), Adapter-Interface (`TenderSourceAdapter`), Normalizer-Interna, Dedup-Key-Berechnung (OCID → Quelle:NoticeId → …) und contentHash-Änderungserkennung.
+- DÖE-API-Client (native `fetch` + `fast-xml-parser`, CSV-Fallback), Pagination/Rate-Limit-Handling (Detail per Phase-Research live zu klären).
+- Scheduler-Implementierung: **poll-once-fan-out-many, mehrmandantensicher — NICHT** das DKV-`findFirst()`-Single-Tenant-Muster.
+- Modul-Registrierung im Marketplace nach DKV/Cert-Manager-Vorbild.
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Milestone-Research (verbindlich)
+- `.planning/research/SUMMARY.md` — Gesamtbild, Build-Order, Architektur-Kernentscheidungen
+- `.planning/research/ARCHITECTURE.md` — normalisiertes Schema, `TenderSourceAdapter`-Abstraktion, global-vs-tenant-Split, Scheduler, Dedup-Strategie, new-vs-modified-Inventar
+- `.planning/research/STACK.md` — neue Libraries (fast-xml-parser, csv-parse) + „reuse, nicht neu bauen"-Liste
+- `.planning/research/PITFALLS.md` — Multi-Tenant-Scheduler (Pitfall: DKV-findFirst), Tenant-Isolation in Background-Jobs, OCDS/eForms-Parsing-Fallen
+- `.planning/research/ausschreibungs-portale-feasibility.md` — DÖE OpenData-API, OCDS-Prefix `ocds-mnwr74`, Swagger-Endpunkt
+
+### Phasen-Vorgaben
+- `.planning/ROADMAP.md` § Phase 10 — Ziel + 5 Erfolgskriterien (u.a. Zwei-Mandanten-Scheduler-Test)
+- `.planning/REQUIREMENTS.md` — CONFIG-01, INGEST-01, INGEST-06, SCHEMA-01, SCHEMA-02
+
+### Offener Research-Punkt (Phase-Research klären)
+- DÖE OpenData Pagination/Rate-Limit-Parameter — Swagger `oeffentlichevergabe.de/documentation/swagger-ui/opendata/` ist JS-gerendert; **live gegen die API verifizieren** bevor der Poll-Zyklus finalisiert wird.
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `apps/api/src/dkv/` — Modul-Struktur, Scheduler-Pattern (`@nestjs/schedule` + `SchedulerRegistry`) als Vorlage; Mail-/Config-Muster (erst ab Phase 12 relevant).
+- `apps/api/src/module-registry/` — Modul-Selbstregistrierung + Marketplace-Aktivierung pro Mandant (CONFIG-01).
+- `apps/api/src/prisma/prisma-tenant.extension.ts` (`forTenant`) — Mandanten-Scoping; hier bewusst NUR für tenant-bezogene Tabellen, NICHT für die globale `Tender`-Tabelle.
+- `apps/api/prisma/schema.prisma` — Modell-Konventionen (uuid, Timestamps, Migrations-Format).
+- Cert-Manager- und DKV-Modul als Gesamt-Template (Controller/Service/Module/Web-UI-Registrierung).
+
+### Established Patterns
+- Native `fetch` als HTTP-Client (kein axios) — siehe `icon-discovery.service.ts`, `ics.provider.ts`.
+- Migrationen als handgeschriebene timestamped Ordner unter `apps/api/prisma/migrations/`.
+
+### Integration Points
+- Neues `TendersModule` self-registriert im Module-Registry.
+- Globale `Tender`-Tabelle (kein `tenantId`); tenant-/user-bezogene Tabellen (Suchprofile, Matches, Triage) kommen in Phase 11.
+- Scheduler läuft plattformweit einmal pro Quelle, unabhängig von der Anzahl aktiver Mandanten.
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- „Nur ab jetzt" + „nur offene" + „90-Tage-Retention" zusammen halten die DB schlank und die Trefferliste relevant (nur bietbare, aktuelle Vergaben).
+- Erfolgskriterium aus ROADMAP.md ernst nehmen: Aktivierung für einen zweiten Mandanten darf keinen zweiten DÖE-Poll auslösen (poll-once-fan-out-many).
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Vergabeergebnisse/Zuschläge/Aufhebungen (award notices) aufnehmen — spätere Erweiterung, außerhalb v1.1-Scope.
+- Historischer Backfill (letzte 30 Tage / alles) — bei Bedarf später als Konfig-Option.
+- Vor-Eingrenzung des Ingest nach Region/CPV — bewusst verworfen (widerspricht Multi-Tenant-Wiederverkauf); Eingrenzung bleibt Sache der Suchprofile.
+- Aufbewahrungsdauer (90 Tage) später ggf. admin-konfigurierbar machen.
+
+None weiter — Diskussion blieb im Phasen-Scope.
+</deferred>
+
+---
+
+*Phase: 10-ausschreibungs-radar-foundation-d-e-ingestion*
+*Context gathered: 2026-07-17*
@@ -0,0 +1,30 @@
+# Phase 10 — Discussion Log
+
+**Date:** 2026-07-17
+**Mode:** discuss (default)
+
+Human-reference only. Not consumed by downstream agents.
+
+## Areas discussed (user selected all 4)
+
+### 1. Initialer Backfill-Umfang
+- Optionen: Nur ab jetzt / Letzte 30 Tage / Alles Verfügbare
+- **Gewählt:** Nur ab jetzt → **D-01**
+
+### 2. Status/Typen der Meldungen
+- Optionen: Nur offene Ausschreibungen / Auch Ergebnisse & Zuschläge
+- **Gewählt:** Nur offene Ausschreibungen → **D-02**
+
+### 3. Ingest-Umfang & Poll-Intervall
+- Optionen: Ganz DE stündlich / Ganz DE täglich / Vor-eingegrenzt
+- **Gewählt:** Ganz DE, stündlich → **D-03, D-04**
+
+### 4. Aufbewahrung abgelaufener Ausschreibungen
+- Optionen: Behalten & markieren / Nach 90 Tagen löschen / Sofort löschen
+- **Gewählt:** Nach 90 Tagen löschen (vorher als abgelaufen markiert/ausgeblendet) → **D-05**
+
+## Deferred
+- Award/Ergebnis-Meldungen, historischer Backfill, Region/CPV-Ingest-Vorfilter (verworfen), konfigurierbare Retention.
+
+## Claude's Discretion
+- Prisma-Schema-Form, Adapter-Interface, Normalizer, Scheduler-Impl (poll-once-fan-out-many), DÖE-Client + Pagination (Research), Modul-Registrierung.