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

105 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
- [x] **Auftrags-Welt = Pipeline-View auf Projekt-Kern** (kein Won-Objekt, kein zweiter Datensatz; Auftrags-Felder am selben Projekt)
- [x] **Sub-Areas am Projekt:** Termine, **Rechnungen [v1 NEU]**, Checklisten (inkl. Mängel `typ=maengel`), Aufgaben, Aktivitäten, Dokumente, **ProjektMitglieder** (Rollen, Multi-Add aus Group)
- [x] **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)
- [x] Pipeline-Config-Auftragsteil (`requires_acceptance_protocol`, Acceptance-Form-Zuweisung, auto_archive) + auto-Archive-Cron
- [x] Acceptance-Form-Templates (M05-basiert, SHK-Default) + Project-Templates
- [x] **KWP/ProjektExternesFeld bleibt v2** — KEIN Feld-Halter in v1
- [x] Konnektor `tenantHasModule('projects')` (Sub-Areas/Actions gated)
- [x] `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):**
- [x] Smoke-Test (D.19) — `tests/e2e/p9-operations-smoke.spec.ts`
- [x] Hot-Swap-Drill (D.20) — `r-p9-operations-interim` in `packages/ui-mock` + `scripts/verify-ui-hot-swap.ts`
- [x] 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)
- [x] 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
- [x] Plane-Ticket `R-P9a` aktualisiert (Kommentar `92fbf09d-a71c-4491-84a4-d2345a904b4f`, Label `design-nachzug`)