# 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.