TommasoGaspe22/laravel-crm-ai-skill

CRM-Build-Framework (Laravel, Enterprise-Verkaufsablauf)

Überblick

Dieses Skill ist der Implementierungsleitfaden, um deine Laravel-App in ein operatives CRM zu verwandeln, das einen Referenz-Verkaufsablauf auf Enterprise-Niveau abbildet – umgebrandet für deine eigene App. Umfang (schreibgeschützt aus der Live-Referenz-Organisation erfasst): Lead → (Konvertieren) → Account + Contact + Opportunity → Products/Price Books → Activities/Calendar. Es erfasst das echte Referenz-UX, das Daten-Mapping, die Wiederverwendungspunkte im vorhandenen Code und einen inkrementellen Plan.

Kernprinzip: Klone NICHT die Referenzplattform selbst (keine Flows, Report-Builder, Admin, KI). Repliziere die Verkaufsobjekte und ihre Beziehungen. Beginne mit den bestehenden commercial_pipeline_entries + der Next-Action-Engine für die Lead-Ebene, füge dann die nachgelagerten relationalen Objekte als neue, additive Tabellen hinzu. Verwende wieder, bevor du hinzufügst. Jede Änderung ist additiv und reversibel; bestehende Pipeline-Seiten, Importe, Exporte und Tests müssen funktionsfähig bleiben.

Stack (festgelegt – verwende ihn, führe keine neuen Frameworks ein): Laravel 13, PHP 8.3, Blade, Alpine.js 3, Tailwind 4 (Vite), SQLite, Session-Auth mit admin/sales-Rollen. Kein Livewire, kein Inertia, kein React, keine neuen JS-Bibliotheken.

Wann verwenden

• Beim Erstellen beliebiger /crm-Listenansichten, gespeicherter Ansichten, Filter-Drawer, Bulk-/Row-Aktionen.
• Beim Erstellen beliebiger Detailseiten, Timeline oder Quick-Actions.
• Beim Erstellen von Account / Contact / Opportunity (mit Stages) / Activities oder dem Lead-Convert-Flow.
• Beim Hinzufügen von CRM-Feldern, Status-/Stage-/Priority-Badges oder der Opportunity-Stage-Path/Kanban.
• Bei jeder Aufgabe, die beschrieben wird als „lass es sich wie ein poliertes Enterprise-CRM anfühlen" für dein Verkaufsteam.

Wann NICHT verwenden: Inbound-Funnel/Assessment-Lead-Arbeit lebt in App\Models\Lead + /dashboard/leads (andere Tabelle, getrennt halten). Nur auf Enterprise-Plattform verfügbare Funktionen (Flows, Reports, Berechtigungen, KI-Assistent) – außerhalb des Rahmens. Rechnungen – außerhalb des Rahmens für V1.

Diese der Reihe nach lesen (das Framework)

Vollständige Dateizuordnung + Methoden- + Evidence-Legende: references/README.md. Fortschritt & ehrlicher Prozent: references/definition-of-done.md. Tiefgehende Reverse-Engineering-Dokumente (pro System) befinden sich in references/*-system.md und pro Objekt-Record-Seiten. Die folgende Liste ist der Kernlesepfad; das README indexiert alles.

1. references/source-crm-reference.md – die echte „Alle offenen Leads"-Listenansicht-Anatomie + Referenz→App-Konzept/Field-Mapping + Record-Seiten-Anatomie. Zuerst lesen für das UX-Ziel.
2. references/objects-catalog.md – der vollständige Verkaufsablauf, erfasst aus der Organisation: jedes Objekt (Account, Contact, Opportunity + echte Stages, Products/Pricebooks, Activities), seine echten Spalten/Felder/Aktionen, Beziehungen und wie sie mit der bestehenden Pipeline koexistieren. Lesen für das Was.
3. references/data-model.md – Lead-Ebene: pipeline-additive Spalten, status-Enum + Ableitung, owner_id-Backfill, Policy.
4. references/data-model-full.md – das nachgelagerte relationale Schema (crm_accounts/contacts/opportunities/activities…), Stage-Enum, der Convert-Flow, Pro-Objekt-Policies und die gesamte Build-Reihenfolge. Lesen für das Wie (Daten).
5. references/screen-anatomy.md – Pixel-genaue Anatomie jedes Bildschirm-Archetyps (Listenansicht, Record-Seite, Create/Edit-Modal, Convert-Modal, Kanban), erfasst aus der Organisation, Region für Region, mit den echten Abschnitts-/Related-List-/Control-Namen. Lesen für exakte Genauigkeit.
6. references/component-catalog.md – die Referenz-äquivalente Komponentenbibliothek zum Bauen in Blade/Alpine/Tailwind (Page-Header, Path, Data-Table, Detail-Section, Activity-Panel, Related-List, Modals, Form-Fields, Badges, Kanban, Toasts) + Design-Tokens. Das ist es, was es aussehen lässt wie ein poliertes Enterprise-CRM.
7. references/modules.md – das Lead-Modul-Build-Spez (Routes, Controller, gespeicherte Ansichten, Quick-Actions, Validierung). Jedes andere Objekt spiegelt dieses Muster.
8. references/ux-design-system.md – die UI-Regeln des CRM: Layout, Tabellendichte, Status-/Stage-/Priority-Badges, Empty-/Loading-/Error-Zustände, Barrierefreiheit, Responsive, Alpine-Muster.
9. references/testing.md – Test-Checkliste, Befehle, Done-Kriterien. Vor dem Beanspruchen der Fertigstellung ausführen.

Voraussetzungen (Tag 0)

Dieses Skill ist ein Build-Framework, kein Scaffolder: Die untenstehende Reuse-Map setzt voraus, dass deine App bereits eine operative Lead-/Pipeline-Tabelle mit Owner, Priorität und Follow-up-Tracking, eine Dashboard-Shell mit Auth und admin/sales-Rollen hat – die Namen in der Tabelle sind illustrative Beispiele dieser Form, keine harte Anforderung, exakt zu passen. Wenn deine App noch kein Äquivalent hat, baue (oder stube) diese Ebene zuerst – Phase A Schritt 1 setzt voraus, dass sie existiert, und wird sonst auf undefinierte Klassen verweisen. Überprüfe auch vor dem Schreiben des ersten Controllers: Bei Laravel 11+ enthält die Basis app/Http/Controllers/Controller.php standardmäßig kein AuthorizesRequests mehr, welches das $this->authorize()-Muster dieses Skills überall benötigt.

Wiederverwendungskarte (bestehender Code – nicht duplizieren)

Bedarf	Wiederverwendung	Ort
Lead-Daten (reichhaltig: Owner, Priorität, Score, Follow-ups, Ergebnisse)	CommercialPipelineEntry	app/Models/CommercialPipelineEntry.php
Next-Action / Bucket / Dringlichkeitslogik	actionForEntry() + Helfer	app/Http/Controllers/Dashboard/CommercialPipelineTodayController.php – extrahiere nach App\Support\CommercialPipelineActionService, dann konsumieren sowohl /dashboard/oggi als auch /crm es
Gefilterte Abfrage, Spalten, Zusammenfassung, CSV	filteredQuery(), columns(), export()	app/Http/Controllers/Dashboard/CommercialPipelineController.php
CSV-Ausgabe	App\Support\CsvExporter	app/Support/CsvExporter.php
Follow-up-Ergebnisvokabular + Slug-Badges	FOLLOW_UP_OUTCOMES, *OutcomeSlug-Accessoren	Model
Dashboard-Shell, Sidebar, Auth	layouts/dashboard.blade.php, auth + role:admin Middleware	Routen-Gruppe prefix('dashboard')->as('dashboard.')
Konfigurationsvokabular	config('crm.lead_statuses'), user_roles, dashboard.page_sizes	config/crm.php

Nicht verhandelbare Leitplanken

• Nur additive Migrationen. Neue Spalten sind nullable + haben ein down(). Niemals bestehende Pipeline-Spalten umbenennen/löschen.
• Bestehende Pipeline-Seiten/Tests nicht beschädigen. /dashboard/pipeline-commerciale, Import/Export, Bulk-Update bleiben grün.
• Single Source of Truth für Next-Action: der extrahierte Service. Bucket-Logik nicht in CRM-Controllern/Views neu implementieren.
• Keine echten Quell-Organisationsdaten in Code, Seeds, Docs oder Commits – keine echten Namen/E-Mails/Telefone. Demo-Seeder verwenden nur Fake-Daten.
• Server-seitig zuerst: Filtern, Sortieren, Paginierung in SQL (gegen N+1 absichern). Alpine nur für In-Page-Interaktionen (Drawer, Spalten-Toggle, Bulk-Select, Quick-Action-Menüs).
• Auth + Policy auf jeder Route und Aktion. sales und admin nutzen beide das CRM; „Mir zugewiesen" und Ownership-Scoping erfolgen über die Policy.
• Die eigene lokalisierte UI und das Design-System der App, keine externen Assets/CDNs über das hinaus, was das Projekt bereits lädt.

Build-Reihenfolge (inkrementell – Implementierung ist TDD)

Phase A – Lead-Ebene (Details in modules.md + data-model.md)

1. Extrahiere CommercialPipelineActionService (reines Refactoring; /dashboard/oggi-Tests bleiben grün).
2. Additive Pipeline-Migration (E-Mail, Telefon, Status, owner_id, optional lead_source/website/linkedin) + Casts/Accessoren + Backfill.
3. Lead-Listenansicht /crm/leads (Tabelle, gespeicherte Ansichten, Suche, Sortierung, Paginierung, Empty/Loading/Error).
4. Filter-Drawer + Spalten-Toggle + Bulk-Aktionen + Zeilen-Aktionen + Quick-Action-Endpoints.
5. Lead-Detail /crm/leads/{entry} (Highlights, Next-Action, Karten, Timeline, Notizen, Quick-Links).

Phase B – Relationaler Verkaufsablauf (Details in objects-catalog.md + data-model-full.md) 6. crm_accounts + crm_contacts (Liste + Detail + Beziehungen), neue Tabellen. 7. crm_opportunities mit der echten Stage-Path (Qualify→Present→Propose→Negotiate→Won/Lost) + „nach Stage"-Ansicht. 8. Lead-Convert-Aktion → erstellt Account + Contact + Opportunity (transaktional). 9. crm_activities + echte Timeline auf jeder Detailseite (ersetzt die abgeleitete Timeline). 10. Katalog (Produkte/Preisbücher/Positionsartikel) – nur wenn eine echte SKU-Liste benötigt wird.

Jede Phase: Policy pro Objekt + Tests (testing.md), dann pint, composer test, npm run build. Jedes Objekt spiegelt das Lead-Modul-Muster.

ERFORDERLICHES SUB-SKILL: Verwende superpowers:test-driven-development für jede Controller-/Service-/Policy-Änderung. ERFORDERLICH: Verwende superpowers:verification-before-completion, bevor du eine Phase als abgeschlossen beanspruchst.