204 lines
18 KiB
Markdown
204 lines
18 KiB
Markdown
<!-- status: plan -->
|
||
<!-- started: 2026-06-04 -->
|
||
<!-- component: gateway | ui-nyla | platform -->
|
||
<!-- replaces: 2026-06-STEP2-umsystem-integration-connectors-und-datenquellen-seiten.md, 2026-06-STEP2-pm-consolidated-customer-requirements.md (Solution-Teile) -->
|
||
|
||
# Plan: Solutions — kundeneigene Workflows als Konfiguration (kein Code)
|
||
|
||
> **Baut auf:** `2026-06-CustomerCases-step1-architecture.md` (Schichten L1–L4, Feature-vs-Solution-Grenze).
|
||
> **Schwester-Plan:** `2026-06-CustomerCases-step3-features-plan.md` (der Code dahinter: Solution-Schicht, generische Bausteine, Connectors, vertikale Features).
|
||
> **Konsolidiert/ersetzt:** Umsystem-Integration-Plan + die Solution-tauglichen Use Cases aus dem konsolidierten Kundenwünsche-Plan.
|
||
|
||
## Beschreibung und Kontext
|
||
|
||
Eine **Solution** ist ein **konfigurierter Workflow** (Daten = Graph + Settings + Trigger + Output-Bindung), der ein wiederkehrendes Kundenbedürfnis erfüllt — **ohne kundenspezifischen Code**. Sie konsumiert die vorhandenen Plattform-Bausteine (L1 Toolbox, L2 Graph) und wird über die neue Solution-Schicht (L3/L4) angelegt, eingestellt, getestet, ausgeführt und angesehen.
|
||
|
||
Dieser Plan listet die **konkreten Kunden-Use-Cases, die als Solutions** umgesetzt werden. Der Code, den diese Solutions voraussetzen (Solution-Schicht selbst, generische Workflow-Bausteine, Connectors), steht im **features-plan** — eine Solution schreibt nie eigenen Code.
|
||
|
||
Business-Treiber: jeder Use Case wird zu Konfiguration statt Engineering → Time-to-value in Tagen, Onboarding ohne Entwicklungs-Backlog, Grenzkosten pro Use Case nahe null.
|
||
|
||
## Fokus und kritische Details
|
||
|
||
- **Solution = Daten, nie Code.** Konten-Mappings, Empfänger, Perioden, Ordnerpfade, Cron-Zeiten, Instanz-Auswahl = **Settings**. Tauchen Kundennamen oder `if kunde == X` im Code auf, ist die Solution falsch geschnitten. Settings werden zur Laufzeit injiziert (features-plan A0.3), nie in den Graph geschrieben.
|
||
- **Owner-Achse = Mandant + Run-as-Principal** (features-plan A0.1): eine Solution gehört dem **Mandanten** und läuft **im Namen eines Principals** (interaktiv: User; geplant: definierte Automations-Identität). «Im Trustee angezeigt» ist nur UI-Platzierung. Datenzugriff richtet sich nach der **RBAC des Principals**, über Feature-Grenzen hinweg.
|
||
- **Multi-Feature/Multi-Instanz ist nativ** (features-plan A0.2): per-Node `FeatureInstanceRef`; eine Solution kann mandatsintern über **mehrere Feature-Instanzen** (Pling: 5 Trustee-Instanzen einer Holding) und sogar **mehrere Features** laufen. Echte Schranke = der **Mandant** (kein Cross-Mandate). Kosten werden **per-Node** der berührten Instanz zugeordnet.
|
||
- **Voraussetzung sind generische Bausteine, keine kundenspezifischen.** Wo ein Baustein fehlt (z. B. `rbac.queryUsersByRole`, `email.sendEmail`, `data.writeToTable`, ein SelectLine-Connector), wird er **generisch** im features-plan gebaut und hier nur referenziert.
|
||
- **Neutralisierung** für jeden LLM-Pfad (Belege/Berichte mit Personendaten) — selektiv über `FeatureDataSource`-Flags (`neutralizeFields`), **feature-admin-gated** konfiguriert (Namen/Beschreibungen pseudonymisiert, Zahlen/Konten lesbar).
|
||
- **Testlauf real, ohne Versand:** Solutions laufen im Test echt, nur Seiteneffekt-Nodes (`email.sendEmail`/`sharepoint.upload`/`integration.pushToTarget`) unterdrücken via run-level `testMode`.
|
||
|
||
## Ziel und Nicht-Ziele
|
||
|
||
- **Ziel:** Die häufigsten Kundenbedürfnisse als **kuratierte Solution-Templates** + pro Mandant/Instanz konfigurierte Solutions abbilden.
|
||
- **Ziel:** SelectLine→RMA und Pling-Reporting als erste produktive Solutions (Leit-Cases).
|
||
- **Ziel:** Nachweis, dass dasselbe Muster Beleg-Import, Dokumentenverarbeitung und Finanz-Analysen trägt.
|
||
- **Explizit NICHT:** kundenspezifischer Code pro Solution (→ features-plan baut nur Generisches).
|
||
- **Explizit NICHT:** den Graphical Editor ersetzen — Solutions kapseln ihn; «Im Editor öffnen» bleibt Escape-Hatch.
|
||
- **Explizit NICHT:** Use Cases, die ein eigenes Datenmodell / tiefe opinionated UI brauchen (→ das sind **Features**, siehe features-plan; z. B. `lawyer`).
|
||
|
||
## Klassifikation: was wird Solution, was Feature
|
||
|
||
| Use-Case-Quelle | Umsetzung | Begründung |
|
||
|---|---|---|
|
||
| SelectLine → RMA (Umsystem) | **Solution** «Systeme synchronisieren» | Komponierbar aus Connectors + Integration-Nodes; Kundenspezifika = Mapping/Settings |
|
||
| Pling Kaffee-Klatsch (Monatsreporting) | **Solution** «Periodisches Reporting» | Fan-out + Konsolidierung + AI-Report + rollenbasierte Verteilung, alles Bausteine |
|
||
| PWG Jahresmietzinsbestätigungen (1.9c) | **Solution** «Dokumente verarbeiten» | SharePoint→Extract→AI→Tabelle→Mail, 1 AI-Schritt |
|
||
| Beleg-/Spesen-Import periodisch (1.1, 1.10.5) | **Solution** «Beleg-Import» | SharePoint/Drive→Trustee-Pipeline, Zeitplan |
|
||
| Budget/Soll-Ist, KPI, Cashflow, Prognose, Jahresabschluss-Check, Liquidität (1.2–1.7, 4.x) | **Solution** «Finanz-Analyse & Reporting» | `queryData`→`ai.generate`→Output (Tabelle/Report); heute Prompt-Templates |
|
||
| KPI-/Notification-Verteilung (1.9.12, 4.5.8) | **Solution** «Benachrichtigung/Report» | Trigger→Daten→Report→rollenbasierte Verteilung |
|
||
| Lawyer (Mandatsvorbereitung + Dashboards) | **Feature** | Eigene Modelle (`LawyerMatter`…) + opinionated UI |
|
||
| CommCoach, Neutralisierung, Trustee-Core | **Feature** (bestehend) | Domänenlogik/eigene UI/Engine |
|
||
| Connectors (SelectLine, Xero, FileMaker, Lohn, Kassensystem) | **Feature/Plattform-Baustein** | Generischer Code (L1), kein Kunden-Code → features-plan |
|
||
| Solution-Schicht, generische Nodes, `testMode` | **Feature/Plattform-Enabler** | Code, der Solutions erst möglich macht → features-plan |
|
||
|
||
## Solution-Katalog
|
||
|
||
Jede Solution = Template (kuratiert) → pro Instanz konfiguriert. Bausteine sind **vorhanden**, sofern nicht als «(neu → features-plan)» markiert.
|
||
|
||
### S1 — «Systeme synchronisieren» (Pilot: SelectLine → RMA)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Rechnungen aus externem System (SelectLine) periodisch ins RMA buchen |
|
||
| **Trigger** | `trigger.schedule` (z. B. täglich 06:00) oder `trigger.manual` |
|
||
| **Bausteine (Graph)** | `integration.fetchFromSource` (SelectLine) → `integration.mapAccounts` → `integration.pushToTarget` (RMA, inkl. Beleg-Upload) *(Nodes + SelectLine-Connector neu → features-plan)* |
|
||
| **Settings (L3)** | Quell-Connector + Credentials, Ziel-Connector, Konten-/Steuer-Mapping, Filter (nur Ausgangsrechnungen, «seit letztem Sync»), Zeitplan |
|
||
| **Output (L4)** | `summary` — Sync-Log/Status (gebucht/übersprungen/Duplikate) |
|
||
| **Dedup** | über bestehende AccountingBridge-Dedup-Logik |
|
||
| **Kunden** | konkreter SelectLine-Kunde; Muster für jedes weitere Umsystem |
|
||
| **Voraussetzungen (features-plan)** | SelectLine-Connector, `source`/`target`-Rolle auf Config, Integration-Nodes, ggf. kanonisches `Invoice`-Modell |
|
||
|
||
Zwei Kunden mit unterschiedlichem Kontenplan-Mapping = **zwei Solutions/Configs, ein Code**.
|
||
|
||
### S2 — «Periodisches Reporting» (Leit-Case: Pling Kaffee-Klatsch)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Am 15./Monat aus 5 RMA-Buchhaltungen konsolidieren, 6 PDFs erzeugen, rollenbasiert mailen |
|
||
| **Trigger** | `trigger.schedule` `0 6 15 * *` (Europe/Zurich) + `trigger.manual` (rollen-beschränkt) |
|
||
| **Bausteine (Graph)** | `flow.loop`(Instanz-Auswahl, mandatsintern) → `trustee.refreshAccountingData` → `trustee.queryData` (Salden akt.+Vorjahr) → `data.consolidate` (sumByKey) → `ai.generateDocument`×6 (1 Holding + 5 Store) → `rbac.queryUsersByRole` (pro Instanz) → `email.sendEmail` → `file.create` (Archiv) |
|
||
| **Settings (L3)** | **Instanz-Auswahl** (5 Trustee-Instanzen *derselben Holding/Mandant* — bestätigt), Konten-Ranges (Umsatz 3000–3999, Warenkosten 6000–6299, Personal 5000–5099), Cron, Empfänger-**Rollen** (Holding→`trustee-accountant`/`trustee-viewer`, Store→`trustee-client`, Protokoll→`trustee-admin` — alle verifiziert vorhanden), `stopOnIncomplete` |
|
||
| **Owner/Billing** | Owner = Mandant; Run-as-Principal = definierte Automations-Identität (geplanter Lauf). **Per-Node-Billing**: jede Store-`refresh/query` bucht die berührte Store-Instanz, Konsolidierung/Report/Versand die Holding-Instanz (A0.1/A0.2) |
|
||
| **Output (L4)** | `file` — 6 PDFs, archiviert als `TrusteeDocument`; + `summary` Lauf-Protokoll |
|
||
| **Sonderfall** | Buchhaltung am 15. nicht abgeschlossen → durchlaufen mit Markierung (`flow.ifElse` nach refresh), steuerbar via `stopOnIncomplete` |
|
||
| **Neutralisierung** | selektiv via `FeatureDataSource`-Flags (Namen/Beschreibungen ja; Zahlen/Konten nein) |
|
||
| **Voraussetzungen (features-plan)** | `rbac.queryUsersByRole`, **`email.sendEmail`-Node (neu, Blocker)**, Trigger-`accessControl.requiredRoles`, `testMode`; `data.consolidate` vorhanden ✓ |
|
||
|
||
Vollständig spezifiziert (High-Level + Anhang); ~2 Wochen Build → bester End-to-End-Beleg der Solution-Schicht.
|
||
|
||
### S3 — «Dokumente verarbeiten + Antwort» (PWG Jahresmietzinsbestätigungen, 1.9c)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Gescannte Rücklauf-Bestätigungen (≈3'200/Jahr) prüfen, Status klassifizieren, Antwortvorschläge |
|
||
| **Trigger** | `trigger.schedule` (täglich) oder `trigger.manual` |
|
||
| **Bausteine (Graph)** | `sharepoint.listFiles` → `flow.loop` → `sharepoint.readFile` + `trustee.extractFromFiles` (OCR) → `ai.prompt` (Scan vs. Abacus-Originaldaten, Status, Antwortvorschlag) → **`input.humanTask`** (Review der Antwortvorschläge vor Versand, optional) → `data.writeToTable` → `email.sendEmail` |
|
||
| **Settings (L3)** | Scan-Ordner (SharePoint), Abacus-Mandant + Mietzins-Stammdaten-Abfrage, Empfänger (Sachbearbeiter), Prompt-Variante, Review-Pflicht ja/nein |
|
||
| **Output (L4)** | `table` — Übersicht verarbeiteter Bestätigungen (bestätigt / Abweichung / fehlende Unterschrift / unleserlich) + Mail-Zusammenfassung |
|
||
| **Kunden** | PWG (Pilot, Versand Sommer 2026, Deadline-gebunden) |
|
||
| **Voraussetzungen (features-plan)** | Prompt-Template «Mietzinsbestätigung prüfen», Abacus-Stammdaten-Abfrage konfigurieren, **`data.writeToTable`-Node (neu)**, **`email.sendEmail`-Node (neu)**; `sharepoint.readFile`/`input.humanTask` vorhanden ✓ |
|
||
|
||
### S4 — «Beleg-Import» (periodische Spesen-/Belegverarbeitung; 1.1, 1.10.5)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Belege/Spesen aus SharePoint/Drive periodisch klassifizieren, kontieren, verbuchen |
|
||
| **Trigger** | `trigger.schedule` (z. B. täglich 22:00) |
|
||
| **Bausteine (Graph)** | `sharepoint.listFiles` → `flow.loop` → `trustee.extractFromFiles` → `trustee.processDocuments` (Klassifikation + Kontierung) → `trustee.syncToAccounting` |
|
||
| **Settings (L3)** | Quelle (Ordner), Ziel-Buchhaltung (RMA/Bexio/Abacus), Klassifikations-/Kontierungsoptionen, Zeitplan |
|
||
| **Output (L4)** | `table` verarbeitete Belege + `summary` |
|
||
| **Kunden** | Bling, PWG, Quid |
|
||
| **Voraussetzungen** | bestehende Pipeline + System-Template existiert bereits; als Solution kapseln |
|
||
|
||
### S5 — «Finanz-Analyse & Reporting» (1.2–1.7, 4.x — heute Prompt-Templates)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Budget/Soll-Ist, KPI-Dashboard, Cashflow, Prognose, Jahresabschluss-Checks, Liquidität |
|
||
| **Trigger** | `trigger.manual` / `trigger.form` oder `trigger.schedule` (periodischer Report) |
|
||
| **Bausteine (Graph)** | `trustee.refreshAccountingData` → `trustee.queryData`/`aggregateTable` → `ai.generateDocument`/`ai.prompt` → Output |
|
||
| **Settings (L3)** | Periode(n), Vergleichsbasis (Vorjahr/Budget), optionaler Budget-Upload, KPI-Auswahl, Empfänger |
|
||
| **Output (L4)** | `table` (KPIs), `file` (Report-PDF) oder `summary` |
|
||
| **Kunden** | Bling, Quid, allgemein Treuhand |
|
||
| **Voraussetzungen** | **bereits vorhandene** System-Templates (`trustee-budget-comparison`/`-kpi-dashboard`/`-cashflow`/`-forecast`/`-year-end-check`) nur als `customerFacing` Solutions exponieren (kein Neubau) — features-plan B3 |
|
||
|
||
### S6 — «Benachrichtigung / Report-Verteilung» (1.9.12, 4.5.8)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Bedürfnis** | Bei Ereignis/Zeitplan Bericht erzeugen und rollenbasiert verteilen; KPI-Alerts |
|
||
| **Trigger** | `trigger.schedule` / `trigger.event` (DB-Change → features-plan) |
|
||
| **Bausteine (Graph)** | Daten lesen → `ai.generateDocument` (optional) → `rbac.queryUsersByRole` → `email.sendEmail` |
|
||
| **Settings (L3)** | Auslöser/Schwellwerte, Empfänger-Rollen, Vorlage |
|
||
| **Output (L4)** | `summary` + Mail |
|
||
| **Voraussetzungen (features-plan)** | `rbac.queryUsersByRole`, **`email.sendEmail`-Node (neu)**, optional `trigger.event`/DB-Change-Detection |
|
||
|
||
## Gemeinsames Settings-Muster (alle Solutions)
|
||
|
||
- **`settingsSchema`** automatisch aus `trigger.form` + exposed Node-Params abgeleitet; kundensichtbare Labels als `TextMultilingual` (i18n, features-plan A5).
|
||
- **`settingsValues`** (Daten, Secrets verschlüsselt) inkl. **Instanz-Auswahl** (mandatsintern, mehrere Feature-Instanzen/Features möglich, A0.2); zur Laufzeit als `runEnvelope` injiziert (A0.3) — **kein** Graph-Schreiben.
|
||
- **`triggerPolicy`** manuell/Zeitplan/Event/Form + `accessControl.requiredRoles` (bestehende Feature-Rollen).
|
||
- **`outputBinding.kind`** = `file | table | summary` (Dashboard später).
|
||
- **Lebenszyklus** in der «Lösungen»-Seite (UX-Muster wie `TrusteeDataTablesView`: Tabs + `?tab=`/`?solutionId=`-Deep-Links, FormGenerator, `useConfirm`/`usePrompt`, alle Texte `t()`): Liste · Katalog/Neu (Vorlage oder AI) · Detail mit Tabs (Einstellungen · Testlauf · Läufe · Ausgabe).
|
||
|
||
## Betroffene Module
|
||
|
||
- **Daten/Config (kein Code pro Solution):** Solution-Definition + Settings-Record pro Feature-Instanz (Modell → features-plan), Workflow-Graph als Template/Version.
|
||
- **Kuratierte System-Templates:** `interfaces/interfaceBootstrap.py` — «Systeme synchronisieren», «Periodisches Reporting», «Dokumente verarbeiten», «Beleg-Import», «Finanz-Analyse».
|
||
- **Voraussetzungen (Code):** vollständig im **features-plan** (Solution-Schicht, generische Nodes, Connectors, `testMode`, `rbac.queryUsersByRole`).
|
||
- **Demo:** je Solution ein Demo-Setup (Pling-/PWG-/Bling-Mandant) — verweist auf Demo-Items aus dem alten Kundenplan.
|
||
|
||
## Entscheidungen
|
||
|
||
| Datum | Entscheidung | Begründung |
|
||
|-------|-------------|------------|
|
||
| 2026-06-04 | Kunden-Use-Cases primär als **Solutions** (Config) statt Code | step1-architecture Solution-first; skaliert ohne Engineering pro Kunde |
|
||
| 2026-06-04 | SelectLine→RMA und Pling als **erste produktive Solutions** | konkrete Geld-Cases, decken Sync- und Reporting-Muster ab |
|
||
| 2026-06-04 | Analyse-Prompt-Templates (Budget/KPI/Cashflow/…) werden **Solution-Templates** | bisher Trustee-interne Quick Actions → kundentauglich als Solutions |
|
||
| 2026-06-04 | Fehlende Bausteine werden **generisch** im features-plan gebaut, nie kundenspezifisch | «keine Kundenlogik im Code» |
|
||
|
||
## Umsetzungs-Checkliste
|
||
|
||
- [ ] Solution-Schicht + generische Bausteine verfügbar (→ features-plan: A1–A3)
|
||
- [ ] System-Template «Systeme synchronisieren» + Demo SelectLine→RMA (S1)
|
||
- [ ] System-Template «Periodisches Reporting» + Pling-Solution konfiguriert (S2)
|
||
- [ ] System-Template «Dokumente verarbeiten» + PWG-Mietzins-Solution (S3) — Deadline Sommer 2026
|
||
- [ ] «Beleg-Import» als Solution kapseln (S4)
|
||
- [ ] Analyse-Templates → Solution-Templates migrieren (S5)
|
||
- [ ] «Benachrichtigung/Report» (S6) inkl. rollenbasierte Verteilung
|
||
- [ ] Pro Solution: Testlauf (`testMode`) grün, dann Aktivierung
|
||
|
||
## Akzeptanzkriterien
|
||
|
||
| # | Kriterium (Given-When-Then) | Prio |
|
||
|---|---|---|
|
||
| 1 | Given konfigurierte S1, When der Sync läuft, Then erscheinen SelectLine-Rechnungen als Buchungen in RMA (kein Kunden-Code; zweiter Kunde = nur andere Settings) | must |
|
||
| 2 | Given konfigurierte S2 (Pling), When der Monatslauf läuft, Then 6 PDFs erzeugt + rollenbasiert versendet + archiviert; manueller Start nur für `trustee-admin` | must |
|
||
| 3 | Given S2 im Testlauf, When ausgeführt, Then Reports werden erzeugt aber **keine** Mails versendet (`testMode`) | must |
|
||
| 4 | Given konfigurierte S3, When Scans eintreffen, Then Übersichtstabelle mit Status + Antwortvorschlägen + Mail | must |
|
||
| 5 | Given eine Solution, When der Kunde Settings ändert, Then ohne Re-Publish/Code-Deploy beim nächsten Run wirksam (Injektion, A0.3) | must |
|
||
| 6 | Given ein neuer ähnlicher Use Case, When aus Template instanziiert, Then nur Settings nötig, kein Code | should |
|
||
| 7 | Given S2 über 5 Trustee-Instanzen **einer** Holding, When der Lauf läuft, Then keine Cross-Mandate-Daten; per-Node-Billing bucht Store-Kosten je Store, Holding-Kosten auf Holding (A0.1/A0.2) | must |
|
||
| 8 | Given die «Lösungen»-Seite, When sie gerendert wird, Then alle UI-Texte via `t()`, Solution-Name/-Beschreibung lokalisiert (`TextMultilingual`) | must |
|
||
|
||
## Offene Fragen
|
||
|
||
1. **S1 Erreichbarkeit:** SelectLine on-prem → Zugriffsweg (VPN/Tunnel/Agent)? Zielart RMA (AR-Rechnung vs. GL-Buchung)?
|
||
2. **S2 Pling-Topologie:** ✅ bestätigt — 5 Trustee-Instanzen *eines* Mandanten (Holding); native Multi-Instanz-Verarbeitung (A0.2).
|
||
3. **S5 Umfang:** Welche der vorhandenen Analyse-Templates werden 1:1 als Solution exponiert vs. konsolidiert?
|
||
4. **S2/S3 Output:** `outputBinding`-Detail (Artefakt-Referenz, `table`-Spalten aus Node-Output ableiten) — siehe step1-architecture «Output-Bindung».
|
||
5. **Demo-Daten:** welche Mandanten/Testdaten zuerst (Pling, PWG, Bling)?
|
||
|
||
## Links
|
||
|
||
- Architektur: `c-work/0-ideas/2026-06-CustomerCases-step1-architecture.md`
|
||
- Product Summary: `c-work/0-ideas/2026-06-CustomerCases-step2-communication-product-summary.md` (+ `.pdf`)
|
||
- Mockup: `c-work/0-ideas/2026-06-CustomerCases-step2-communication-mockup.html`
|
||
- Features/Code: `c-work/0-ideas/2026-06-CustomerCases-step3-features-plan.md`
|
||
- Pling-Spec: `pamocreate/projects/poweron/customer-pling/20-spezifikation/20260522-workflow-spec-kaffee-klatsch.md` (+ `-anhang.md`)
|
||
- Bausteine: `b-reference/platform-core/workflow.md`, `b-reference/platform-core/automation.md`, `b-reference/platform-core/features/trustee.md`
|
||
|
||
## Abschluss
|
||
|
||
- [ ] Bei Annahme → Solution-Templates + erste Konfigurationen in `c-work/2-build/`
|
||
- [ ] `b-reference/` Kanon-Seite «Solutions» nach Umsetzung
|
||
- [ ] `_CHANGELOG.md`-Eintrag pro Solution
|