Files
tsumugu/docs/product/TECHNICAL_SPEC_HANDOFF.md

91 lines
11 KiB
Markdown
Raw Permalink 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.
# Tsumugu – Auftrag zur technischen MVP-Spezifikation
**Stand:** 16.10.2026 · **Zielrepository:** `C:\Dev\tsumugu`
**Auftrag:** Technische Spezifikation erstellen, noch keine Implementierung.
## Ziel und Arbeitsweise
Überführe die vorhandene fachliche Tsumugu-Spezifikation in eine umsetzbare technische MVP-Spezifikation. Tsumugu ist ein universeller Vorgangs- und Informationsmanager und die erste reale Anwendung der Jinkendo-Blueprints. Erfinde das Produkt nicht neu und führe keine weitere allgemeine Architekturinventur durch.
Wir wollen bald einen praktisch nutzbaren MVP als Keimzelle für iterative Entwicklung umsetzen. Kläre deshalb nur Grundfragen, die Organisation, Nachverfolgung, Datenhoheit, Rechte oder die konkrete Umsetzung wesentlich beeinflussen. Spezifiziere die beiden Anwendungsfälle nicht vorab bis in alle Sonderfälle.
Arbeite eigenständig innerhalb der bestätigten fachlichen und technischen Vorgaben. Triff keine grundlegenden Produktentscheidungen stillschweigend. Technische Details und begründete Anpassungen technischer Defaults benötigen keine zusätzliche allgemeine Freigaberunde.
## 1. Fachliche Grundlage und vorhandenes Repository
Lies zunächst vollständig:
- `C:\Dev\tsumugu\docs\product\TSUMUGU_PRODUCT_SPEC.md` – führende fachliche Arbeitsdatei; beim Erstellen dieses Auftrags Arbeitsstand 0.24. Bestätigte Entscheidungen, Bestandsangaben, Vorschläge und offene Punkte sind ausdrücklich unterschieden.
- `C:\Dev\tsumugu\docs\product\Tsumugu_Product_Recovery_Baseline_v0.1.md` – unveränderter historischer Ausgangspunkt; neue Interviewentscheidungen stehen in der führenden Spezifikation.
- `C:\Dev\tsumugu\README.md`
- `C:\Dev\tsumugu\docs\architecture\ARCHITECTURE_DISCOVERY.md`
- `C:\Dev\tsumugu\docs\DEPLOYMENT.md`
Prüfe danach gezielt den aktuellen Code, vorhandene Konfigurationen und Git-Arbeitsstand im Zielrepository. Beachte tatsächlich vorhandene `AGENTS.md`-Anweisungen. Bestehende geeignete Komponenten bleiben erhalten. Nicht zum Auftrag gehörende lokale Änderungen bleiben unberührt.
Die letzte gezielte Sichtung zeigte einen FastAPI-Health-Endpunkt mit PostgreSQL, eine statische HTML-/Nginx-Platzhalteroberfläche und Compose-/Gitea-Deploymentdefinitionen. Eine React-/Vite-Fachanwendung ist damit nicht als bereits implementiert belegt. Prüfe diesen Stand selbst; weder einen kompletten Neuaufbau noch bereits fertige Fachkomponenten voraussetzen.
## 2. Architekturrichtlinien und Blueprints
Diese lokal vorhandenen Fassungen sind die konkreten technischen Quellen dieses Auftrags:
### Referenzarchitektur und Foundation – vollständig lesen
- `C:\Dev\jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16\A_Jinkendo_Technical_Reference_Architecture.md`
- `C:\Dev\jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16\B_Implementation_Blueprint_Application_Foundation.md`
- `C:\Dev\jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16\C_Technical_Decisions_Open_Issues.md`
### Für Tsumugu unmittelbar relevante Spezial-Blueprints – relevante Verträge und Abläufe lesen
- `C:\Dev\jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16\Jinkendo_Auth_Session_Scope_Blueprint.md`
- `C:\Dev\jinkendo-release-betrieb-recovery-blueprint-2026-10-16\Jinkendo_Release_Betrieb_Recovery_Blueprint.md`
- `C:\Dev\jinkendo-medien-dateien-rendering-blueprint-2026-10-16\Jinkendo_Media_Files_Safe_Rendering_Blueprint.md`
### Erweiterungskontext – nur soweit für tatsächlich benötigte Grenzen relevant
- `C:\Dev\jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16\Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md`
- `C:\Dev\jinkendo-prompt-placeholder-workflow-blueprint-2026-10-16\Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md`
- `C:\Dev\jinkendo-entitlements-usage-quotas-blueprint-2026-10-16\Jinkendo_Entitlements_Usage_Quotas_Blueprint.md`
Die Existenz dieser zusätzlichen Blueprints macht KI-Ausführung, Workflow-Engine, Billing oder kommerzielle Kontingente nicht zur Tsumugu-MVP-Pflicht. Benötigte Sicherheits- und Ressourcengrenzen sind davon zu unterscheiden. Folge Querverweisen nur gezielt, wenn sie für einen konkreten Vertrag oder Wiederverwendungskandidaten erforderlich sind.
Beachte den Status der Quellen: A/B/C v0.3 und die Spezial-Blueprints unterscheiden beschlossene Architekturverträge, anpassbare technische Defaults und noch nicht integriert/getestete Vorschläge. Vorhandene Testdateien sind kein bestandener Testnachweis. Keine ungeprüfte Übernahme von Beispielschemas, Dateistrukturen oder Paketversionsangaben als bereits freigegebene, validierte Implementierung. Kein pauschales Framework-Upgrade.
## 3. Verbindlichkeit und Umgang mit offenen Fragen
- Ausdrückliche Nutzerentscheidungen und bestätigte Fachanforderungen bestimmen das Produkt. Recovery-Rekonstruktionen sind entsprechend ihrem Nachweisstatus zu behandeln.
- Beschlossene Schutz-, Identitäts-, Transaktions- und Releaseverträge der Architektur bleiben wirksam. Anpassbare technische Defaults können für das bestehende Repository begründet ausgestaltet werden.
- Discovery-Vorschläge und als Vorschlag gekennzeichnete Passagen der Fachspec sind keine freigegebenen Produktentscheidungen.
- Die Fachspec ist keine vollständig abgenommene Gesamtspezifikation. Ein endgültiger MVP-Schnitt liegt noch nicht vor: Erstelle dafür einen konkreten Vorschlag, kennzeichne Rückstellungen und streiche bestätigte Anforderungen nicht stillschweigend.
- Bei einem echten Konflikt zwischen Fachanforderung und Architekturvertrag: konkrete Quellenstellen, Auswirkung und eine Empfehlung knapp dokumentieren. Weder Schutzregeln umgehen noch das Fachmodell an einen unpassenden Default anpassen.
- Arbeite an unabhängigen Teilen weiter. Führe am Ende höchstens drei aktuell blockierende Produktfragen mit Empfehlung auf. Weitere Detailfragen nur am betroffenen späteren Umsetzungsschritt festhalten.
Besonders zu prüfen ist die produktbezogene Autorisierung: Tsumugu erlaubt gezielte Freigaben desselben Elements über Datenraumgrenzen und unterschiedliche Kontextrechte. Die persönlichen Standardadapter des Auth-Blueprints und die Scope-/Assetprüfungen des Datei-Blueprints sind damit gezielt abzugleichen. Das ist zunächst ein Prüfpunkt, kein pauschal festgestellter Blueprint-Konflikt. Keine globale Rechtevereinigung über fremde Akten und keine reine Scope-ID-Gleichheitsregel, die bestätigte Freigaben unmöglich macht. Prüfe auch, wo die Fachspec die Auflösung mehrerer Rechtepfade noch offenlässt.
## 4. Erwartetes Ergebnis
Erstelle eine führende technische Datei:
`C:\Dev\tsumugu\docs\architecture\TSUMUGU_TECHNICAL_SPEC.md`
Verwende klare, kompakte Abschnitte. Die Spezifikation muss die ersten Implementierungsschritte ermöglichen, nicht sämtliche späteren Ausbaustufen vorwegnehmen.
1. **MVP-Vorschlag und Reifestand:** Erster nutzbarer Umfang, spätere Lieferungen und tatsächlich blockierende Entscheidungen. Beide ursprünglichen Anwendungsfälle bleiben Validierungsfälle: Mietangelegenheiten/Rechtsstreitigkeiten sowie Rechnungen/Krankenkassenerstattungen. Universellen Produktumfang erhalten.
2. **Gezielter Bestandsabgleich:** Was bleibt, was muss ergänzt werden und warum. Referenzen auf konkrete vorhandene Dateien statt neuer Gesamtinventur.
3. **Technischer Zuschnitt:** Benötigte Module, Verantwortlichkeiten und ihre Schnittstellen anhand der vorhandenen Architekturverträge; Wiederverwendung gezielt begründen. Keine allgemeine neue Plattform.
4. **Datenmodell und Invarianten:** Entitäten, relevante Felder, Beziehungen, Kardinalitäten, Ownership und Kontextbezüge; als Tabellen und bei Bedarf ER-Diagramm. Bestätigte Beziehungen von offenen Modellvorschlägen trennen. Gemeinsame Inhalte, deren Einbindungen und kontextbezogene Anmerkungen unterscheiden. Akte, Vorgang, Teilvorgang, Kapitel, Sicht und virtuelle Zusammenstellung fachlich konsistent abbilden. Schemaentwurf ist noch keine auszuführende Migration.
5. **Zugriff und Datenräume:** Ein einfaches vorgeschlagenes Rechte-/Rollenmodell für Lesen, Bearbeiten, Freigeben, Ownership und Löschen; Aktenvererbung, Elementausnahmen, gezielte Datenraumfreigaben und Entzug konkret prüfen. Entfernen einer Einbindung von globalem Löschen unterscheiden. Unfreigegebene Inhalte und fremde Herkunftskontexte auch über Suche, Counts, Chronologie, Downloads und Exporte schützen. Späteren gezielten Anwaltszugang berücksichtigen, ohne eine noch nicht entschiedene Zugangsform zur MVP-Pflicht zu machen.
6. **Arbeitsabläufe und Schnittstellen:** Die wenigen für den MVP erforderlichen API-/UI-Verträge, Statusübergänge und Transaktionsgrenzen. Insbesondere Vorgang anlegen, Ressourcen zuordnen, Chronologie nachvollziehen, Aufgaben und unabhängige Fristen verfolgen sowie private/gemeinsame Bearbeitung. Ein knappes API-Verzeichnis mit Ein-/Ausgaben genügt; keine zweite große OpenAPI-Handschrift.
7. **Dateien, Paperless und Finanzen:** Eigene geschützte Ablage gegenüber externen Referenzen; notwendige Datei-/Lifecycleverträge. Ausgewählte bidirektionale Metadaten, Feldzuständigkeit, bewusste Konfliktauflösung und Ausfallsichtbarkeit konkretisieren. Bisheriges `erstattet_am` ist Mitteilungsdatum und kein Zahlungseingang. Erstattungsbeträge stehen bisher an Rechnungen mit Belegreferenz. Rechnungszahlung, Erstattungsbearbeitung und tatsächliche Eingänge unterscheiden; Teilbeträge unterstützen, den Regelfall einfach halten. Noch offene Produktregeln nicht als entschieden ausgeben.
8. **Überprüfbare Umsetzungsschritte:** Wenige geordnete Arbeitspakete mit Ergebnis, Abhängigkeiten und passenden Abnahmekriterien. Sinnvolle Nachweise für Rechteisolation/gezielte Freigaben, gemeinsame Inhalte, Fristen, Finanzzuordnungen und Metadatenkonflikte benennen. Release-/Recovery-Anforderungen für den ersten echten Betrieb berücksichtigen. Tests als geplant kennzeichnen; hier keine Implementierungs- oder Laufzeitnachweise behaupten.
Halte ein kleines Mapping von den tatsächlich benötigten Blueprint-Verträgen zu ihrer Tsumugu-Ausprägung fest. Keine neue umfassende Compliance-/Governancematrix und keine Vervielfachung der Produktspezifikation. Offene Frage, technischer Vorschlag und bestätigte Vorgabe müssen auch im Ergebnis erkennbar bleiben.
## 5. Grenzen und Abschluss
Dieser Auftrag erlaubt ausschließlich das Erstellen/Aktualisieren der technischen Spezifikation im Zielrepository. Die fachliche Spezifikation und die historische Baseline bleiben inhaltlich unverändert. Dokumentiere neu benötigte Fachentscheidungen als Vorschläge oder Fragen in der technischen Datei; sie werden nach der Nutzerentscheidung in die führende Fachspec übernommen.
Keine Änderungen an Anwendungscode, Datenbanken, Migrationen, Abhängigkeiten, CI/CD, Deployments oder anderen Produkt-Repositories. Keine Paketinstallation, keine Netz-/Provider-/Paperless-Integrationstests und keine Eingriffe in laufende Systeme. Keine Implementierung starten, auch wenn Beispiele in Blueprints als Coding-Aufträge formuliert sind. Kein Push oder Deployment aus diesem Auftrag.
Liefere abschließend eine kurze Zusammenfassung mit Dateilink, empfohlenem MVP-Schnitt, erstem vorgeschlagenem Umsetzungspaket und höchstens drei wirklich blockierenden Fragen. Danach auf die ausdrückliche Freigabe für den konkreten Implementierungsauftrag warten.