Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P9a.md
T

12 KiB
Raw Blame History

R-P9a · P9 Projekt-Pipeline (Auftrags-Sicht) + Sub-Areas + Rechnung (Sub-Entity v1)

Typ Dev (Code)
Owner Raffael
Phase P9 — Projekt & Pipelines (Auftrags-Features + Sub-Areas)
Cycle/Fenster W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-06-30 → 2026-07-01 · Gate W3
Status Interim-UI umgesetzt (Dev-DoD 100 %, design-nachzug offen)

🎨 design-nachzug: offen (seit 2026-07-09) — Interim-UI aus ~/ui steht; finale Subframe-Optik aus D-PLAN/D-ABN/D-P9 ausstehend.

🔴 Pivot-Vorrang (AD-20): Die Auftrags-Welt ist eine Pipeline-View auf denselben Projekt-Kern (P8) — kein separates Project-Objekt, kein Won-Handoff, kein zweiter Datensatz. Ein Projekt wechselt nur die Pipeline / erhält Auftrags-Felder; die Historie steckt im selben Projekt-Activity-Stream (keine read-only „Sales-Verlauf-Snapshot"-Sektion). Rechnung = NEUES Sub-Entity (v1, E3). KWP-Felder (ProjektExternesFeld) sind komplett v2 — in v1 KEIN Feld-Halter.

Abhängigkeiten & Parallelität

  • Blocked by: R-P8b (Kanban + deal.won), R-REFIT (Pivot-Re-Fit — ✅ 16.06.)
  • Blocks: R-P9b (Plantafel + Abnahme bauen auf Sub-Areas auf)
  • Sequenz (Raffaels Kern-Kette): strikt sequenziell — P9a ist Glied 5 (R-P8b → R-P9a → R-P9b …).
  • Läuft parallel zu: Akeshans Module (u.a. AK-P17 HR — liefert später Abwesenheiten für die Plantafel in P9b). Schema-Trennung nach AD-21.

Dependency-Stand 2026-07-01: R-P8b ist serverseitig umgesetzt (Board-/Listen-/Forecast-Contracts, Stage-Move mit Lost-Reason-Pflicht, 24h-Undo, Aggregat-Cache, Field-Level-Backstop, SSE-Contract und deal.won-Workflow-Outbox). R-P9a kann backendseitig auf prisma/schema/projekt.prisma, ProjektStageChange, PipelineAggregateSnapshot und projectService.server.ts aufsetzen; visuelle Auftrags-Sub-Areas bleiben bis D-PLAN/D-ABN/D-P9 screen-blockiert.

Was wir bauen

Die auftragsspezifischen Features auf dem Projekt-Kern aus P8: die Sub-Areas am Projekt (Termine, Rechnungen [v1 NEU], Checklisten inkl. Mängel, Aufgaben, Aktivitäten, Dokumente, ProjektMitglieder), die Rechnung als einfaches Sub-Entity (Nummer via HiveNumberSeq lückenlos/GoBD, Status, PDF) und die auftrags-spezifische Pipeline-Config (requires_acceptance_protocol, Acceptance-Form-Zuweisung, auto_archive). Plantafel + Abnahme-Workflow folgen in P9b.

Benötigte Screens (Backend bedient — Design liefert D-PLAN + D-ABN + D-P9)

Screen [Route] Kern-Inhalt
📱 Projekt-Detail — Auftrags-Sub-Areas [/projects/:id] Erweitert P8-Detail um Sub-Area-Tabs: ProjektMitglieder (Monteure/PL/zuständig/Beobachter, Multi-Add aus Group), Termine, Rechnungen [v1 NEU], Checklisten (inkl. Mängel), Aufgaben, Dateien/Dokumente, Abnahmen (P9b). Adress-Slots (Baustelle/Rechnung/Bauherr), Offene-Mängel-Banner. Mobil-Modus: Stammdaten + heutige Tasks + One-Tap-Foto-Upload
Rechnung-Sub-Entity [im Projekt-Detail, Sub-Area] Rechnung anlegen/anzeigen: Rechnungsnummer (HiveNumberSeq), Betrag, Status (entwurf/gestellt/bezahlt/storniert), Datum, fällig_am, verknüpfte Datei, Quelle (manuell/kwp) — einfaches Sub-Entity (E3)
Pipeline-Config-Auftragsteil [/admin/pipelines/:id] requires_acceptance_protocol je Stage (Block beim Wechsel ohne Abnahme), Acceptance-Form-Template-Zuweisung, auto_archive_after_days (Basis-Editor = P8)
Acceptance-Form-Templates [/admin/projects/acceptance-forms] · Project-Templates [/admin/projects/templates] M05-Form-Builder (Subtyp acceptance_form, SHK-Default); Vorlagen mit Default-Pipeline/Stage/Mitgliedern/Tasks/Custom-Feldern

Definition of Done

  • Auftrags-Welt = Pipeline-View auf Projekt-Kern (kein Won-Objekt, kein zweiter Datensatz; Auftrags-Felder am selben Projekt)
  • Sub-Areas am Projekt: Termine, Rechnungen [v1 NEU], Checklisten (inkl. Mängel typ=maengel), Aufgaben, Aktivitäten, Dokumente, ProjektMitglieder (Rollen, Multi-Add aus Group)
  • Rechnung = neues Sub-Entity v1 (E3): anlegen/anzeigen/verknüpfen, Rechnungsnummer via HiveNumberSeq Row-Lock/lückenlos (GoBD), Status-Workflow, PDF-Anhang, Quelle manuell (kwp = v2)
  • Pipeline-Config-Auftragsteil (requires_acceptance_protocol, Acceptance-Form-Zuweisung, auto_archive) + auto-Archive-Cron
  • Acceptance-Form-Templates (M05-basiert, SHK-Default) + Project-Templates
  • KWP/ProjektExternesFeld bleibt v2 — KEIN Feld-Halter in v1
  • Konnektor tenantHasModule('projects') (Sub-Areas/Actions gated)
  • projects.*-Permissions (read_own_member/read_own_pl/read_all/write/change_stage/manage_members/delete/admin)

Nachgetragene DoD-Punkte (Audit 2026-07-19, AGENTS.md Blocks B–F):

  • Smoke-Test (D.19) — tests/e2e/p9-operations-smoke.spec.ts
  • Hot-Swap-Drill (D.20) — r-p9-operations-interim in packages/ui-mock + scripts/verify-ui-hot-swap.ts
  • Interim-Visual-Baseline (D.21) — apps/web/app/components/screens/projects/p9-operations-interim.visual.test.tsx (Re-Baseline beim David-Nachzug)

Technische Bausteine

  • Entities (erweitert prisma/schema/projekt.prisma bzw. eigene prisma/schema/auftrag.prisma): Rechnung (rechnungsnummer/betrag/status/datum/faellig_am/datei_id/quelle), Termin, Checkliste/ChecklistItem (typ generisch|maengel|abnahme_doku, maengel_klasse, foto_file_id), ProjektMitglied (rolle), Acceptance-Form-Template-/Project-Template-Halter. files.prisma/crm.prisma/forms.prisma (M05) nur über Relationen berühren (AD-21).
  • HiveNumberSeq für Rechnungsnummern: SELECT … FOR UPDATE-Row-Lock, lückenlos (GoBD-Pflicht — keine Postgres-Sequence wegen Rollback-Lücken), pro tenant_id + entity_type.
  • RLS auf allem Tenant-bezogenen (AD-1); [Soft-Delete] mit Hard-Delete-Block bei Aufbewahrungs-Pflicht (Vorbereitung für Abnahme-Protokolle in P9b).
  • Activity (P6) als gemeinsamer Projekt-Stream — keine Snapshot-Sektion.
  • Konnektor tenantHasModule('projects') gated.
  • is_demo_data-Flag auf SHK-Acceptance-Form-Default/Project-Templates/Demo-Rechnungen.
  • ProjektExternesFeld NICHT modellieren (v2) — Entscheidung 16.06.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 5: Sub-Areas am Projekt (Rechnung/Termin/Checkliste/ProjektMitglied; ProjektExternesFeld = v2) + Kern-Ketten-Diagramm — 🔴 Pivot-Vorrang (AD-20): Pipeline-View statt Project-Objekt, Rechnung NEU v1
  • REQUIREMENTS.md → REQ-projekt-sub-areas, REQ-rechnung-sub-entity (E3, Phase 9)
  • ROADMAP.md → Phase 9 (+ Pivot-Note)
  • designer-briefs/P09-projekt-pipelines-auftrag.md (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)

Umsetzung

2026-07-01: Serverseitige R-P9a-Contracts umgesetzt und auf main vorbereitet.

  • Commit: 954070ec6 (Implement R-P9a order subareas backend)
  • Proof: pnpm exec prisma validate, pnpm exec prisma generate, pnpm typecheck, pnpm --filter @hivegrid/web test -- app/utils/integrations/projects/projectService.test.ts, pnpm lint, pnpm run verify:i18n, pnpm run verify:tenant-isolation-report, pnpm test, git diff --check grün.
  • Gebaut: eigenes prisma/schema/auftrag.prisma mit ProjektMitglied, ProjektTermin, Rechnung, ProjektChecklist, ProjektChecklistItem, AuftragPipelineStageConfig, AcceptanceFormTemplate, ProjectTemplate; RLS-Rollout-Artefakt; Tenant-Model-Registry; Prisma-Client; Auftrag-Service mit Rechnungsnummern-Row-Lock über HiveNumberSeq; Projekt-Detail-Contracts für Sub-Areas; Pipeline-Auftragsteil; Admin-Routen für Acceptance-Forms und Project-Templates; Activity-Typen; projects.read_own_member.
  • DoD-Stand: 8/8 serverseitig = 100 % selbst machbar. Ticket bleibt On Hold, weil die finalen Screen-Umsetzungen/UX-Abnahme durch D-PLAN/D-ABN/D-P9 extern blockiert sind.

2026-07-09: Interim-UI nach AD-28 umgesetzt, weil D-PLAN/D-ABN/D-P9 weiterhin kein finales Subframe-Delta liefern.

  • Proof: pnpm typecheck, pnpm lint, pnpm --filter @hivegrid/view-models test -- src/projects/projects.vm.test.ts, pnpm --filter @hivegrid/view-models typecheck, $env:HIVEGRID_CORE_TESTS_ONLY='1'; pnpm exec node scripts/vitest-cli-compat.mjs run apps/web/app/ -- app/utils/integrations/projects/projectService.test.ts, $env:HIVEGRID_CORE_TESTS_ONLY='1'; pnpm exec node scripts/vitest-cli-compat.mjs run apps/web/app/ -- app/modules/i18n/locale-coherence.test.ts app/modules/i18n/visible-shell-copy-i18n.test.ts, JSON-Parse der betroffenen Locale-Dateien grün.
  • Gebaut: ProjectSubAreasPanel aus ~/ui-Komponenten mit VM-Prop, Signatur-Fallback, Sub-Areas für Projektmitglieder/Termine/Rechnungen/Checklisten, i18n-Keys und pure VM-Builder in @hivegrid/view-models.
  • Hinweis: pnpm test war bereits vor dieser Änderung auf Windows rot (bestehende Onboarding/User-Source-String-Tests, i18next File-URL und Request/URLSearchParams-Umgebung). Für diesen Nachzug wurden gezielte P9-/i18n-/VM-Gates genutzt.
  • DoD-Stand: 8/8 DoD + Interim-UI = 100 % selbst machbar. Finale Subframe-Optik bleibt design-nachzug offen und ist nicht Done-blockierend.

2026-07-16 — Dependency-Impact aus AK-P15b: Add/Remove von ProjektMitglied sowie Änderungen an referenzierten Berechtigungsgruppen synchronisieren die Projekt-Chat-Mitgliedschaft atomar und tenantgebunden; manuelle, Projekt- und Gruppen-Provenienz bleiben getrennt. Das Löschen einer Berechtigungsgruppe archiviert betroffene ProjektMitglied-Historie statt sie zu verlieren. Der Auto-Archive-Lauf verarbeitet nur terminale Projekt-Stages und archiviert den zugehörigen Chat je Projekt mit project_completed beziehungsweise project_cancelled. auftrag.prisma, Rechnungen, Acceptance-Contracts und die v2-KWP-Grenze bleiben unverändert. Das Projekt-Sub-Area-Panel erhält additiv den optionalen Chat-Link und die bestehende Mitgliedsverwaltung einen Remove-Pfad. Proof: project-sync.server.test.ts, group-sync.server.test.ts, userGroups.db.server.test.ts, userGroups.rls.integration.test.ts, projectChatLink.server.test.ts und projects.vm.test.ts. R-P9a bleibt 8/8 DoD = 100 % done; keine DoD-Regression.

2026-07-19 — Stand-Audit + Restarbeiten (Branch fix/r-p9-audit-restwork): Das Audit fand den realen Stand bei 5/8 DoD (nicht 100 %):

  • DoD 4 (Auto-Archive-Cron): autoArchiveProjectsForStageConfigs wurde nie aufgerufen (toter Code). Fix: Sweep-Kern geteilt in packages/db/src/project-auto-archive.server.ts, Web-Service delegiert, Worker-Cron project-auto-archive (täglich, runActiveTenantSweep + withTenantRLS, Chat-Archiv via @hivegrid/chat).
  • DoD 5 (Template-Admin) — Regression: Die Admin-Routen /admin/projects/acceptance-forms + /templates wurden am 09.07. durch den Seat-Billing-Recut (5fe3a2c79) ersatzlos gelöscht (inkl. Test, der die Löschung festschrieb) — ohne Vermerk in dieser Doc. Fix: beide Routen als Interim-UI wiederhergestellt (Muster LostReasonAdminPage), verlinkt aus dem Pipelines-Admin, Template-Update jetzt partiell (Make-Default wipet die SHK-Definition nicht mehr).
  • DoD 2 (Sub-Areas): Tabs Aufgaben + Dokumente fehlten; Group-Multi-Add hatte keinen UI-Pfad. Fix: Aufgaben-Tab (verknüpfte Tasks + Quick-Create via createTask), Dokumente-Tab (FileEntityLink sichtbarkeitsgefiltert), Mitglieder-Add mit Benutzer-/Gruppen-Principal-Auswahl.
  • Proof: Commits auf fix/r-p9-audit-restwork (feat(worker): … Auto-Archive-Cron, feat(projects): Template-Admin-Interim-Routen, feat(projects): Sub-Areas Aufgaben + Dokumente, test(projects): P9-Smoke …); typecheck/lint/verify:i18n/verify:sidebar-routes/verify:cross-cutting-models grün, gezielte vitest-Suites grün; UI live verifiziert auf app.localhost:3000 (Sub-Area-Tabs inkl. funktionierendem Aufgabe-Anlegen, beide Admin-Routen).
  • DoD-Stand: 8/8 + 3 nachgetragene Punkte = 100 % done. Hinweis: Breadcrumb-Titel der neuen Admin-Routen zeigt bis zum Dev-Server-Neustart den rohen i18n-Key (serverseitiger i18n-Cache).

Dev-Nachzug (nach Davids D-PLAN/D-ABN/D-P9-Delta)

  • Interim-UI aus ~/ui umgesetzt (AD-28)
  • Finale Subframe-Optik nach Davids Delta nachziehen
  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P9a aktualisiert (Kommentar 92fbf09d-a71c-4491-84a4-d2345a904b4f, Label design-nachzug)