18 KiB
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 polymorpheEntityLink-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, eigeneprisma/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
- Task-CRUD: Status/Priorität/Fälligkeit/Entity-Link/Watcher/Reminder
- Person- oder Gruppen-Zuweisung (Constraint: genau eines, Default = Ersteller)
- Task-Quellen: manuell / Chat / Form / Automation (je Quelle-Marker + Link)
- Reminder via
notify()(24h vor / bei / 24h nach Deadline, Eskalation Email) - 30-Tage-Auto-Archiv-Cron für erledigte Tasks
- Polymorphe
EntityLink-Tabelle (entity_type + entity_id) tasks.*-Permission-Bundle (read_own mit Owner-Check / read_all / write / admin) — fremde Tasks 404 statt 403, Action-Buttons permission-aware- 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(polymorphentity_type + entity_id, Gate-W1-Lieferung).core.prismanur für User/Group-Relationen berühren (AD-21). - RLS auf
Task/TaskWatcher/EntityLink;tasks.read_ownmit serverseitigem Owner-Filter (fremde → 404). - Konnektor
tenantHasModule('tasks'). - Reminder über
notify()-Kanal-Abstraktion (R-P1b); Auto-Archiv-Cron (BullMQ). is_demo_dataauf 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-archivierungROADMAP.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-P4baktualisiert
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). GenerischerentityLinkService.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-CHECKnum_nonnulls(...)=1in 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 (VMcanWrite/canDelete). - DoD 8 — Wiederverwendbare Task-Liste:
task-list.vm.ts(+task-detail.vm.ts), Komponente inui-app(taskListAdapter) + Rendererui-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 übernotify()-sourceKey-Upsert (kein Doppelversand). Reine Window-Logik 7 Unit-Tests grün. Handler inworker/handlers.ts. - DoD 5 — 30-Tage-Auto-Archiv-Cron:
task-archive-retention-cron.ts+ Handler (setztarchivedAtaufdone-Tasks mitcompletedAt < now-30d). Registrierung imgeneral-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-Indextasks+ Registry, Audit (auditTaskEvent) + Activity (logTaskActivity, gegen verknüpfte Entität bzw. Task-Subject), Entitlements (featureKeys.tasks+ Registry/Plans/Blueprint), i18ntasks.*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 nurdb push; die eine forward-only P4-Tasks-Migration (Tabellen +pg_trgm-Index aufTask.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 nurdb 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 Listepackages/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 inapps/worker/src/handlers.ts+ Registrierung imgeneral-Group-Block vonapps/worker/src/index.ts. - Wiring: Sidebar (
AppSidebar.tsx), Search (packages/searchschema+registry), Entitlements (packages/entitlements), Permissions (packages/db permissions-seed+DefaultPermissions.ts), i18ntasks.*inapps/web/public/locales/{de,en}/translations.json.
Nächste Schritte bis „Done" (Checkliste)
- 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 aufTask.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 statusgrün. Vorschlag: mit der P4a-Merge-Migration zu einer Migration zusammenführen (nach User-OK). - 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 mitcompletedAt < now-30dbekommtarchivedAt. Cron-Registrierung läuft nur imgeneral-Worker mit gesetztemBULLMQ_REDIS_URL/REDIS_URL. - 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. - 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.
- Davids
D-P4-Delta abwarten → visuelle Politur als Dev-Nachzug über die Adapter-/ ui-subframe-Schicht (Baseline-UI mitdata-ui-id-Markern steht). - DSGVO-Hinweis (R-P2b-Koordination): Der Merge hat
UserSession/TrustedDeviceausauth.prismaohne Eintrag inpackages/db/src/dsgvo/user-fk-map.tsmitgebracht — ich habe sie alshard-delete(passend zumonDelete: 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/clientinui-app; keinui-subframe-Direktimport inroutes/**; keinuseLoaderDatainui-app. - Audit über
createAuditEvent(ohne Client-Arg); 4xx vianotFoundResponse()/badRequestResponse(). - UI-Paket-Tests (ui-app/-subframe/-mock): keine hartkodierten Strings in
title:/label:-Feldern (no-restricted-syntax) → Fixture-Werte über Variablen referenzieren (siehetaskList.hot-swap.test.ts). GroupUserhat keintenantId→ Gruppen-Mitgliedschaft über diegroup-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/: TabellenTask/TaskWatcher/EntityLink+ 5 Enums + alle Indizes + FKTaskWatcher.taskId→Task(Cascade), AnhangTask_single_assignee_chk(num_nonnulls=1, DoD 2) +pg_trgm-IndexTask_title_trgm_idx, beide DO-guarded; Inverse-SQL als Kommentar (DoD 28). RLS bewusst NICHT hier (siehe unten). DDL viaprisma migrate diff --from-empty --to-schemaerzeugt und auf P4b-Objekte getrimmt. Verifiziert gegen frische Leer-DB (pgvector pg16, Docker):prisma migrate deployspielt alle Migrationen inkl. P4b durch (P3018-sicher); Drift-Check (migrate diff --from-config-datasource --to-schema) meldet für P4b nur denpg_trgm-Index (erwarteter Raw-SQL-False-Positive wie bei p4aFile_displayName_trgm_idx); CHECK + Trigram perpsqlals 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.tslaufen durchwithTenantRLS()(interne*WithTx-Helfer, kein Nesting; langsame I/O n/a). Einziger nicht-gewrappter Zugriff: der globale User-LookupresolveUserLabels(User ist nicht tenant-scoped) — bleibt am db-Singleton.taskAccess.server.tsunverändert (kein direkterdb.task-Zugriff). - Worker: die zwei Maintenance-Crons (
runTaskArchiveRetentionHandler+runTaskReminderSweepHandlerinhandlers.ts) von cross-tenant-Sweep auf per-Tenant umgebaut: aktive Tenants aus der globalenTenant-Registry (nicht RLS-scoped) enumerieren, dann je Tenant die Task/TaskWatcher-Reads/Writes inwithTenantRLS()(Worker-Helferdb/tenantRls.ts);notify()bleibt außerhalb der Tx.takebegrenzt jetzt pro Tenant statt global. - Aktivierungs-Artefakt
prisma/rls/task-isolation.sql(getrackt, parallel zufile-isolation.sql): ENABLE/FORCE +*_tenant_isolation-Policy +GRANT … TO hivegrid_appfürTask/TaskWatcher/EntityLink, Inverse-SQL als Kommentar. Nicht im Auto-Migrations-Pfad. Enthält den Teil-B-Hinweis, dass die Maintenance-Crons beim Cutover SELECT aufTenant(oder eine privilegierte Connection) brauchen.
- Web: alle tenant-scoped DB-Zugriffe in
- Gate-Test
apps/web/app/utils/db/.server/rls-task-isolation.integration.test.ts(gespiegelt anrls-file-isolation, gated aufRLS_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 CHECKblockt Fremd-Insert; eigener Insert+Read ok;TaskWatcher+EntityLinkanalog 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.