Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/AK-P4b.md
T

239 lines
18 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.
# AK-P4b · P4 Tasks + polymorphe EntityLink-Tabelle
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P4 — Files & Tasks |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · **Gate W1 (EntityLink)** |
| **Status** | geplant |
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P4a` (Files + FileEntityLink-Muster)
- **Blocks:** `R-P6` (Tasks-Tab + Verknüpfung am CRM), **Gate W1 (EntityLink)** — die polymorphe `EntityLink`-Tabelle ist die Andock-Voraussetzung für alle Folge-Entitäten
- **Läuft parallel zu:** Raffaels `R-P2a`/`R-P2b` (P2‖P4-Paar). Disjunkte Domänen, eigene `prisma/schema/tasks.prisma` → kein Schema-Konflikt (AD-21).
- **Konflikt-Risiko:** keines auf Schema-Ebene; Task-Entity-Links zu CRM-Entitäten werden erst in **P6 nachverdrahtet** (Task-Kern hier, Links dort).
## Was wir bauen
Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorität/Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Deal/Project), Person- **oder** Gruppen-Zuweisung (genau eines, Default = Ersteller), Watcher, **Reminder via `notify()`** (24h vor / bei / 24h nach Deadline, Eskalation Email) und **Auto-Archivierung** erledigter Tasks nach 30 Tagen per Cron. Tasks entstehen manuell, aus Chat, aus Form-Submission und aus Automation-Actions. Dazu die **polymorphe `EntityLink`-Tabelle** (`entity_type + entity_id`), gegen die jedes Modul andockt. Die **Task-Liste ist als wiederverwendbare Komponente** zu bauen (P12/P14/P16 betten sie ein; erscheint als Tasks-Tab in jeder Entity-Detail-View).
## Benötigte Screens (Backend bedient — Design liefert `D-P4` aus `D-D0a`/`D-D0b`)
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|---|---|---|
| Task-Liste [`/tasks`] | Titel/Prio/Fälligkeit/verknüpfte Entität/Assignee/Status/Quelle · Presets Meine/Erstellt/Alle · Filter · Bulk · Inline-Quick-Actions — **wiederverwendbare Komponente** | `D-P4` (A2) |
| Task-Detail + Anlage [`/tasks/:id`, `/tasks/new`] | Markdown-Beschreibung, Status/Prio/Fälligkeit inline, Assignee-Picker (Person↔Gruppe), Verknüpfungs-Picker (Auto-Complete), Watcher, Quelle-Link, Activity-Stream, Aktionen | `D-P4` (A3+A5) |
*Eingebettet: Tasks-Tab + „Aufgabe anlegen" (Pre-Fill) in jeder Entity-Detail-View (R-P6 ff.).*
## Definition of Done
- [x] **Task-CRUD:** Status/Priorität/Fälligkeit/Entity-Link/Watcher/Reminder
- [x] Person- **oder** Gruppen-Zuweisung (Constraint: genau eines, Default = Ersteller)
- [x] Task-Quellen: manuell / Chat / Form / Automation (je Quelle-Marker + Link)
- [x] **Reminder via `notify()`** (24h vor / bei / 24h nach Deadline, Eskalation Email)
- [x] **30-Tage-Auto-Archiv-Cron** für erledigte Tasks
- [x] **Polymorphe `EntityLink`-Tabelle** (`entity_type + entity_id`)
- [x] `tasks.*`-Permission-Bundle (read_own mit Owner-Check / read_all / write / admin) — fremde Tasks **404 statt 403**, Action-Buttons permission-aware
- [x] Task-Liste als **wiederverwendbare Komponente** (embeddable)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/tasks.prisma`): `Task` (title, description, assigned_to_user **oder** _group, deadline, priority, status, source, linked_entity_type/id — polymorph; `is_demo_data`; Soft-Delete), `TaskWatcher` (M:N), **`EntityLink`** (polymorph `entity_type + entity_id`, Gate-W1-Lieferung). `core.prisma` nur für User/Group-Relationen berühren (AD-21).
- **RLS** auf `Task`/`TaskWatcher`/`EntityLink`; `tasks.read_own` mit serverseitigem Owner-Filter (fremde → 404).
- **Konnektor** `tenantHasModule('tasks')`.
- Reminder über `notify()`-Kanal-Abstraktion (R-P1b); Auto-Archiv-Cron (BullMQ).
- `is_demo_data` auf Demo-Tasks (Onboarding-Provisioning).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 3: Files & Tasks** (Task polymorph link, TaskWatcher) + Cross-Cutting (Task-Link, EntityLink-Prinzip)
- `REQUIREMENTS.md` → `REQ-tasks-datenmodell`, `REQ-tasks-reminder-archivierung`
- `ROADMAP.md` → Phase 4 · `PHASE-SOURCES.md` → Phase 4 (M071/M072/M073; M074-ERP-Sync → P10; Entity-Links → P6 nachverdrahtet)
- `designer-briefs/P04-files-tasks.md` (Task-Liste = wiederverwendbare Komponente)
- `_bmad-output/specs/M26-tasks.md`
## Dev-Nachzug (nach Davids `D-P4`-Delta)
- [ ] Task-Liste/-Detail an Davids UI angepasst (wiederverwendbare Komponente)
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P4b` aktualisiert
---
## Umsetzungs-Notiz
### 2026-06-22 — Tasks-Modul + generische EntityLink-Tabelle gebaut + verifiziert (Akeshan, Branch `feat/AK-P4b`)
Gebaut strikt nach `~/.claude/plans/du-bist-senior-software-squishy-kazoo.md` (Umsetzungsplan),
1:1 auf dem Files-Fundament (AK-P4a) als Template. Branch-Strategie: `origin/main` in
`feat/AK-P4a` gemergt (Merge-Commit `cd1322ce4`, 1 trivialer Konflikt in
`view-models/src/index.ts`), dann `feat/AK-P4b` davon abgezweigt. Plattform Windows 11.
**Fertig + verifiziert (typecheck/test grün pro Paket):**
- **DoD 6 — Polymorphe `EntityLink`-Tabelle (Gate W1):** `prisma/schema/entityLinks.prisma`
(voll generisch: `sourceType/Id` + `targetType/Id` + `linkRole`, beide Seiten polymorph,
`LinkableEntityType`-Enum). Generischer `entityLinkService.server.ts` (link/unlink/listLinksFor,
idempotenter Upsert). Andocken an konkrete CRM-Entitäten = P6 (laut Ticket).
- **DoD 1 — Task-CRUD:** `prisma/schema/tasks.prisma` (`Task`, `TaskWatcher` + Enums, AD-21 bare
Scalars). `taskService.server.ts`: create/update/complete/archive/reactivate/hardDelete,
Watcher add/remove, Status↔completedAt-Sync.
- **DoD 2 — Person- ODER Gruppen-Zuweisung:** `resolveAssignment` (genau eins; beide → Fehler;
keins → Ersteller). DB-CHECK `num_nonnulls(...)=1` in der Merge-Migration. 4 Unit-Tests grün.
- **DoD 7 — `tasks.*`-Bundle + 404-statt-403:** `tasks.read_own/read_all/write/delete/admin`
(permissions-seed mit expliziten Grants + DefaultPermissions). `taskAccess.server.ts`
(Foundation-404-Pfad). Sichtbarkeit read_own = Ersteller/Assignee/Watcher/Gruppen-Mitglied;
fremde Task → 404. Action-Buttons permission-aware (VM `canWrite`/`canDelete`).
- **DoD 8 — Wiederverwendbare Task-Liste:** `task-list.vm.ts` (+ `task-detail.vm.ts`), Komponente
in `ui-app` (`taskListAdapter`) + Renderer `ui-subframe`/`ui-mock` + Hot-Swap-Drill (M017) grün.
- **DoD 3 — Task-Quellen:** `source` + `sourceRef` (manuell via UI; chat/form/automation als
Marker vorbereitet, produzierende Module verdrahten in Folge-Tickets).
- **DoD 4 — Reminder via `notify()`:** `task-reminder-cron.ts` (stündlicher Sweep, 3 Fenster
24h-vor/fällig/24h-nach, after → EMAIL-Eskalation). Idempotenz über `notify()`-`sourceKey`-Upsert
(kein Doppelversand). Reine Window-Logik 7 Unit-Tests grün. Handler in `worker/handlers.ts`.
- **DoD 5 — 30-Tage-Auto-Archiv-Cron:** `task-archive-retention-cron.ts` + Handler (setzt
`archivedAt` auf `done`-Tasks mit `completedAt < now-30d`). Registrierung im `general`-Group-Block.
- **Routen:** `tasks._index` (Browser, Presets Meine/Erstellt/Alle, server-side-Filter,
Cursor-Pagination), `tasks.$id` (Detail + alle Actions, Audit + Activity), `tasks.new` (Anlage +
Entity-Pre-Fill). Loader baut VM, Component pur, ErrorBoundary + Empty/Locked-States.
- **Querschnitt:** Sidebar-Eintrag (permission-gated, Modul `tasks`), Such-Index `tasks` + Registry,
Audit (`auditTaskEvent`) + Activity (`logTaskActivity`, gegen verknüpfte Entität bzw. Task-Subject),
Entitlements (`featureKeys.tasks` + Registry/Plans/Blueprint), i18n `tasks.*` de/en (Parität 69/69).
**Verifikation:** typecheck grün für web/worker/queue + alle Pakete; Tests grün: view-models (32,
inkl. 5 Tasks-VM), ui-app (20, inkl. Hot-Swap), search (47), entitlements (75), queue (101),
worker reminder-cron (7), web assignment (4). `prisma validate` + `generate` grün.
**Bewusst offen (deferred, wie bei AK-P4a):**
- **Merge-Migration + RLS** (`local/AK-P4b-merge-migration.sql`): Branch nur `db push`; die eine
forward-only P4-Tasks-Migration (Tabellen + `pg_trgm`-Index auf `Task.title` + RLS-Policies +
Single-Assignee-CHECK, DO-guarded, Inverse-SQL) beim main-Merge erzeugen, mit R-P2b
(`SET LOCAL app.tenant_id`) abstimmen.
- **Live-Verifikation Reminder/Archiv auf Staging** (braucht Redis + notify-Delivery): EICAR-Analog
zu AK-P4a — lokal kein Redis/DB.
- **Mobile-Tab-Bar (DoD 11 der AGENTS-Liste)** + **Visual-Regression (M016)**: deferred wie bei P4a
(PWA-only AD-17 / keine Snapshot-Harness), Reviewer-Freigabe.
- **Davids `D-P4`-Delta**: Baseline-UI funktional (data-ui-id-Marker); visuelle Politur = Dev-Nachzug.
**%-Done-Stand:** Alle **8 DoD-Code-Punkte grün** (8/8 = 100 % Code). Gesamt ~95 % — offen sind nur
die extern/infrastrukturell blockierten Punkte (Merge-Migration-Erzeugung beim Merge, Live-Staging-
Verifikation, deferred-DoD-Freigabe, Davids Optik). Selbst-machbarer Rest auf dem Branch: 0.
> 💡 Vorschlag (außerhalb Ticket-Scope): Beim P4-Merge die P4a- und P4b-Merge-Migrationen zu **einer**
> forward-only Migration zusammenführen (gemeinsamer `pg_trgm`-Index + RLS-Block), um die
> Migrations-Historie schlank zu halten. Erst nach OK.
---
## HANDOFF für den nächsten Coding-Agenten (hier weitermachen)
**Status:** Tasks-Modul + generische `EntityLink`-Tabelle stehen vollständig und sind grün
(Full-Monorepo-`pnpm typecheck` exit 0; alle berührten Paket-Tests grün). Branch `feat/AK-P4b`
(zweigt von `feat/AK-P4a` ab, das wiederum `origin/main` enthält). **3 Commits:** `4e3d12607`
(Schema/Domain/VMs/Routes/Wiring), `31659d4dc` (Worker-Crons/Tests/Doku), `316e35c6c` (Cleanup).
### Was steht (nicht erneut bauen)
- **Schema:** `prisma/schema/tasks.prisma` (Task, TaskWatcher), `prisma/schema/entityLinks.prisma`
(generisch: sourceType/Id + targetType/Id + linkRole). Auf dem Branch nur `db push`.
- **Domain:** `apps/web/app/utils/integrations/{taskService,taskAccess,entityLinkService,taskAudit,
taskRoutePaths}.server.ts`.
- **VMs:** `packages/view-models/src/tasks/{task-list,task-detail}.vm.ts` (+ Tests).
- **UI:** Routes `apps/web/app/routes/app.$tenant/tasks.{_index,$id,new}.tsx`; wiederverwendbare
Liste `packages/ui-app/src/adapters/taskList.ts` + Renderer in ui-subframe/ui-mock + Hot-Swap-Test.
- **Worker:** `apps/worker/src/jobs/task-{reminder,archive-retention}-cron.ts` + Handler-Branches in
`apps/worker/src/handlers.ts` + Registrierung im `general`-Group-Block von `apps/worker/src/index.ts`.
- **Wiring:** Sidebar (`AppSidebar.tsx`), Search (`packages/search` schema+registry), Entitlements
(`packages/entitlements`), Permissions (`packages/db permissions-seed` + `DefaultPermissions.ts`),
i18n `tasks.*` in `apps/web/public/locales/{de,en}/translations.json`.
### Nächste Schritte bis „Done" (Checkliste)
1. **Merge-Migration + RLS erzeugen** (Blocker für main-Merge): beim Merge **eine** forward-only
P4-Tasks-Migration aus `local/AK-P4b-merge-migration.sql` (Tabellen + `pg_trgm`-Index auf
`Task.title` + RLS-Policies + Single-Assignee-CHECK, DO-guarded, Inverse-SQL als Kommentar).
Mit R-P2b (`SET LOCAL app.tenant_id`, `prisma/rls/tenant-isolation.sql`) abstimmen.
`prisma validate` + `prisma migrate status` grün. **Vorschlag:** mit der P4a-Merge-Migration
zu einer Migration zusammenführen (nach User-OK).
2. **Live-Verifikation auf Staging** (braucht Redis + DB): (a) Reminder-Sweep → `notify()`-Einträge
in den 3 Fenstern, after-Fenster als EMAIL-PENDING; (b) Archiv-Cron → `done`-Task mit
`completedAt < now-30d` bekommt `archivedAt`. Cron-Registrierung läuft nur im `general`-Worker
mit gesetztem `BULLMQ_REDIS_URL`/`REDIS_URL`.
3. **Reminder-Empfänger-i18n prüfen:** `tasks.reminder.{before,due,after}` sind als Notification-
messageKeys gesetzt; ob der Notification-Renderer diese Keys auflöst, auf Staging gegenchecken.
4. **Deferred-DoD vom Reviewer freigeben lassen:** Mobile-Tab-Bar (PWA-only AD-17) und
Visual-Regression/M016 (keine Snapshot-Harness) — gleicher Stand wie AK-P4a.
5. **Davids `D-P4`-Delta** abwarten → visuelle Politur als Dev-Nachzug über die Adapter-/
ui-subframe-Schicht (Baseline-UI mit `data-ui-id`-Markern steht).
6. **DSGVO-Hinweis (R-P2b-Koordination):** Der Merge hat `UserSession`/`TrustedDevice` aus
`auth.prisma` ohne Eintrag in `packages/db/src/dsgvo/user-fk-map.ts` mitgebracht — ich habe sie
als `hard-delete` (passend zum `onDelete: Cascade`) eingetragen, damit der DSGVO-Test grün ist.
Mit Raffael bestätigen, dass das die gewünschte Lösch-Strategie ist.
### Konventionen (sonst PR-Block)
- Code-Kommentare Englisch (`apps/**`/`packages/**`/`prisma/**`); Deutsch nur in `.planning/`/`local/`.
- Drei Anti-Patterns: kein `~/db`/`@prisma/client` in `ui-app`; kein `ui-subframe`-Direktimport in
`routes/**`; kein `useLoaderData` in `ui-app`.
- Audit über `createAuditEvent` (ohne Client-Arg); 4xx via `notFoundResponse()`/`badRequestResponse()`.
- **UI-Paket-Tests (ui-app/-subframe/-mock):** keine hartkodierten Strings in `title:`/`label:`-Feldern
(no-restricted-syntax) → Fixture-Werte über Variablen referenzieren (siehe `taskList.hot-swap.test.ts`).
- **`GroupUser` hat kein `tenantId`** → Gruppen-Mitgliedschaft über die `group`-Relation scopen.
Erst wenn 1+2 erledigt und 3–5 abgenommen sind → DoD 100 %, Ticket auf **Done**.
---
### 2026-06-24 — Merge-Migration + RLS „Teil A" + Gate-Test gebaut + lokal gegen echte Postgres verifiziert (Akeshan)
Blocker AK-P4a ist abgeschlossen (Plane „In Review"), also die Merge-Vorbereitung von AK-P4b
nachgezogen — exakt das, was AK-P4a am 24.06. erledigt hat, nur auf Tasks angewandt. Reihenfolge:
Baseline-grün → RLS-Wrapping (Web) → Worker-Crons → RLS-Artefakt → Migration → Gate-Test → Verifikation.
**Fertig + verifiziert:**
- **Forward-only P4b-Migration** `prisma/migrations/20260624120000_p4b_tasks_entitylinks/`: Tabellen
`Task`/`TaskWatcher`/`EntityLink` + 5 Enums + alle Indizes + FK `TaskWatcher.taskId→Task`
(Cascade), Anhang `Task_single_assignee_chk` (`num_nonnulls=1`, DoD 2) + `pg_trgm`-Index
`Task_title_trgm_idx`, beide DO-guarded; Inverse-SQL als Kommentar (DoD 28). **RLS bewusst NICHT
hier** (siehe unten). DDL via `prisma migrate diff --from-empty --to-schema` erzeugt und auf
P4b-Objekte getrimmt. **Verifiziert gegen frische Leer-DB** (pgvector pg16, Docker): `prisma migrate
deploy` spielt **alle** Migrationen inkl. P4b durch (P3018-sicher); Drift-Check
(`migrate diff --from-config-datasource --to-schema`) meldet für P4b nur den `pg_trgm`-Index
(erwarteter Raw-SQL-False-Positive wie bei p4a `File_displayName_trgm_idx`); CHECK + Trigram per
`psql` als vorhanden bestätigt.
- **RLS „Teil A" (non-breaking, Code RLS-ready)** — analog AK-P4a:
- **Web:** alle tenant-scoped DB-Zugriffe in `taskService.server.ts` + `entityLinkService.server.ts`
laufen durch `withTenantRLS()` (interne `*WithTx`-Helfer, kein Nesting; langsame I/O n/a). Einziger
nicht-gewrappter Zugriff: der **globale** User-Lookup `resolveUserLabels` (User ist nicht
tenant-scoped) — bleibt am db-Singleton. `taskAccess.server.ts` unverändert (kein direkter
`db.task`-Zugriff).
- **Worker:** die zwei Maintenance-Crons (`runTaskArchiveRetentionHandler` +
`runTaskReminderSweepHandler` in `handlers.ts`) von cross-tenant-Sweep auf **per-Tenant** umgebaut:
aktive Tenants aus der globalen `Tenant`-Registry (nicht RLS-scoped) enumerieren, dann je Tenant die
Task/TaskWatcher-Reads/Writes in `withTenantRLS()` (Worker-Helfer `db/tenantRls.ts`); `notify()`
bleibt außerhalb der Tx. `take` begrenzt jetzt pro Tenant statt global.
- **Aktivierungs-Artefakt** `prisma/rls/task-isolation.sql` (getrackt, parallel zu
`file-isolation.sql`): ENABLE/FORCE + `*_tenant_isolation`-Policy + `GRANT … TO hivegrid_app` für
`Task`/`TaskWatcher`/`EntityLink`, Inverse-SQL als Kommentar. **Nicht** im Auto-Migrations-Pfad.
Enthält den Teil-B-Hinweis, dass die Maintenance-Crons beim Cutover SELECT auf `Tenant` (oder eine
privilegierte Connection) brauchen.
- **Gate-Test** `apps/web/app/utils/db/.server/rls-task-isolation.integration.test.ts` (gespiegelt an
`rls-file-isolation`, gated auf `RLS_TEST_DATABASE_URL`): **8/8 grün** gegen echte Postgres mit
angewandtem Task-RLS-Block (Kontext A sieht nur A; cross-tenant = 0; ohne Kontext = 0; `WITH CHECK`
blockt Fremd-Insert; eigener Insert+Read ok; `TaskWatcher` + `EntityLink` analog isoliert). Ohne die
Env-Var skippt der Block sauber (normale Suite bleibt grün).
**Damit ist Tasks/EntityLink RLS-ready:** der P5-Cutover wird ein reiner Schalter (Migration aus
`prisma/rls/task-isolation.sql` aktivieren + Runtime-Rolle `hivegrid_app` + Maintenance-Worker-Grant),
ohne weitere Tasks-Code-Änderung — bewiesen durch den Gate-Test.
**Lokale Verifikation (grün):** Full-Typecheck Baseline (exit 0) · web-typecheck · worker-typecheck ·
`handlers.test.ts` 76/76 + `task-reminder-cron.test.ts` 7/7 · RLS-Gate 8/8 (echte PG) · `verify:i18n`
exit 0. **Nicht von mir berührte Vorbefunde (separat, kein P4b-Code):** worker `workflow-trigger-store.test.ts`
~22 Reds (AD-26 KI-Removal-Fallout, gpt/workflow-Blöcke) · Drift `TenantPluginCapabilityGrant`
(FK/Index-Rename, main-seitig) — beide bewusst unangetastet (p4a-Stance „fremden Drift nicht mitziehen").
**Weiterhin offen (extern/deferred, unverändert):** RLS „Teil B" (Policy aktivieren + Rollenwechsel +
Cutover, org-weit Raffael/R-P2b) · Live-Staging-Verifikation Reminder/Archiv (Redis + notify, wie p4a
entitlement-gated) · Reminder-Empfänger-i18n auf Staging · DoD 11 Mobile-Tab-Bar (PWA-only AD-17) +
DoD 21 Visual-Regression (keine Snapshot-Harness) · Davids `D-P4`-Optik · Push/PR/Merge auf main
(wartet auf User-Go).
**%-Done-Stand:** 8/8 DoD-Code-Punkte grün; Merge-Migration + RLS-Teil-A + Gate-Test gebaut und lokal
gegen echte Postgres verifiziert. Selbst-machbarer Rest auf dem Branch: **0** (alles Weitere ist
extern/infra blockiert oder Reviewer-Freigabe). Gesamt **~95 %** — Ticket bleibt in **„Ready for
Review"** bis Staging-Verifikation + Reviewer-Freigabe der deferrten Punkte.