29e3d0ff74
SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
214 lines
11 KiB
Markdown
214 lines
11 KiB
Markdown
---
|
||
title: "Kanshō – Handover Laptop-Instanz → Heim-Entwicklung und Server"
|
||
status: "Aktiver Übergabestand"
|
||
date: "2026-09-07"
|
||
product_family: "Jinkendo"
|
||
document_role: "Session Handover / Environment Transfer / Implementation Bootstrap"
|
||
parent_document: "runtime_and_deploy.md"
|
||
canonical_concept_handover: "docs/architecture/functional/handover.md"
|
||
---
|
||
|
||
# Kanshō – Handover: Laptop-Urlaubsinstanz → normale Entwicklung und Server
|
||
|
||
Dieses Dokument ist der **technische Aufsatzpunkt** für den Umgebungswechsel. Es ersetzt weder `runtime_and_deploy.md` noch das fachliche Konzept-Handover `../functional/handover.md`.
|
||
|
||
**Stand:** 2026-09-07, erstellt auf dem Urlaubs-Laptop unter `C:\dev\Kansho`.
|
||
|
||
Ziel: Code, Dokumentation und persönliche Testdaten so übergeben, dass zu Hause weiterentwickelt und später auf Docker/PostgreSQL umgestellt werden kann, ohne die Urlaubsdaten zu verlieren.
|
||
|
||
---
|
||
|
||
## 1. Leitentscheidung für den Transfer
|
||
|
||
**Zwei Wellen, nicht eine.**
|
||
|
||
| Welle | Was | Warum |
|
||
|---|---|---|
|
||
| **1. Kontinuität** | Gitea-Stand klonen, lokale SQLite-Instanz wie bisher, Backup wiederherstellen, Dialog-/Journalqualität prüfen | Der gebaute Slice ist SQLite. Die persönlichen Daten liegen in `backend/data/`. Postgres ist Ziel, nicht Ist. |
|
||
| **2. Betriebsrahmen** | Docker Compose, eigenes Postgres, Deploy-Muster analog Mitai, Gitea-Runner | Entschiedenes Ziel in `product_frame_and_stack.md`. Nicht im selben Schritt wie der erste Daten-Restore. |
|
||
|
||
Ein SQLite-Restore auf dem Heimrechner **vor** der Postgres-Migration ist die Restore-Übung, die `runtime_and_deploy.md` §7 Punkt 3 verlangt. Erst wenn Welle 1 grün ist, wird der Slice auf Compose/Postgres gehoben.
|
||
|
||
Nicht tun: Urlaubs-SQLite in ein noch nicht existierendes Postgres-Schema laden, während uncommitteter Code nur auf dem Laptop liegt.
|
||
|
||
---
|
||
|
||
## 2. Ist-Stand der Laptop-Instanz (2026-09-07)
|
||
|
||
### 2.1 Laufzeit
|
||
|
||
| Element | Ist |
|
||
|---|---|
|
||
| Host | Windows-Laptop, Pfad `C:\dev\Kansho` |
|
||
| Start | ohne Docker: Uvicorn **8018**, Vite **5188** (`strictPort`) |
|
||
| Persistenz | SQLite `backend/data/kansho.sqlite` (~11,3 MB) |
|
||
| Medien | `backend/data/media/<profile_id>/` (70 Dateien, ~8,9 MB Nutzlast; zwei große JPEGs, viele Mini-WebM/PNG) |
|
||
| Secrets | `backend/.env` (nicht im Git, nicht im Backup-Archiv) |
|
||
| Python | 3.12, venv `backend/.venv` |
|
||
| Remote | `https://gitea.stommer.de/Lars/Kansho.git` |
|
||
|
||
### 2.2 Git
|
||
|
||
| Element | Ist |
|
||
|---|---|
|
||
| Branch | `main` |
|
||
| HEAD | `e42f751` Message `MVP 1.0` |
|
||
| Remote | `origin/main` ist **einen Commit hinter** HEAD (`ahead 1`) |
|
||
| `develop` | existiert **nicht** (Familienmuster Dev=`develop` / Prod=`main` ist entschieden, aber noch nicht angelegt) |
|
||
|
||
Uncommittet (muss vor dem Verlassen des Laptops nach Gitea):
|
||
|
||
- Opening-Fix: `backend/journal_opening.py`, `context_builder.py`, `retrieval.py`, `tests/test_journal_opening.py`
|
||
- Opening-Doku: `mvp.md` §6.1, `mvp_implementation.md` §17, `mvp_stand_und_abgleich.md` (Tabellen 5.4, §6.4, §7, Dateikarte), `memory_storage_and_offline.md` §6.2
|
||
- Invariante: Vorhaben nur aus dem **user-Dialog des vorigen Kalendertags**; gespeicherte Journal-Entries sind kein Opening-Mandat; Opening-Call ohne Space-Recency. Fehlerbild: Nachsatz mit Morgenuhrzeit + 400-Zeichen-Prefix. Tests 2026-09-03/07 lokal grün.
|
||
- Transfer-Doku und Work Orders (siehe unten)
|
||
|
||
Bewusst **nicht** in diesem Transfer schließen: Prefix-Recency im laufenden `dialogue_turn`.
|
||
|
||
Unversioniert (gehören in denselben oder einen Dokumentations-Commit):
|
||
|
||
- `docs/architecture/functional/Idea_seconmd_sclide.md` (Konzeptbrief Slice 2, Dateiname mit Tippfehler)
|
||
- `docs/work_orders/` (Debug-Diagnostik, Dialog/Memory-Slice, Laptop-Abschluss, Heim-Setup)
|
||
- dieses Handover und die Runtime-Ergänzungen
|
||
|
||
Nicht in Git und **nicht** ins Backup: `backend/.env`.
|
||
|
||
### 2.3 Persönlicher Datenbestand (Inventar, kein Inhalt)
|
||
|
||
Ein Admin-Profil seit 2026-08-19. Zwei Spaces: `Kroatien 2026` (Urlaubsjournal) und `Test für Prosagenerierung`. 17 Journal Days, 17 Current-Entries, 20 Conversations, 379 Messages, Writing Profile vorhanden, Identity-Mappings lokal, Debug-Runs opt-in persistiert.
|
||
|
||
Das ist **Klasse-A/B-Material**. Es darf nicht nach Gitea, nicht an Provider, nicht unverschlüsselt in die Cloud.
|
||
|
||
### 2.4 Backup dieser Session
|
||
|
||
Erzeugt: `local-backups/kansho-20260907-055703.zip` (gitignoriert).
|
||
|
||
Enthält SQLite (Backup-API) + 70 Mediendateien + Manifest/Checksummen. Enthält **keine** `.env` und keine Keys. Das Archiv ist **unverschlüsselt** und persönlich.
|
||
|
||
Vor dem Abschalten des Laptops: Archiv auf verschlüsselten USB-Stick, NAS-Share oder den Heimrechner kopieren. Zweite Kopie getrennt halten. Nicht committen.
|
||
|
||
---
|
||
|
||
## 3. Was auf dem Laptop noch zu tun ist
|
||
|
||
Siehe Arbeitsauftrag `../../work_orders/laptop_closeout.md`.
|
||
|
||
Kurz:
|
||
|
||
1. Opening-Fix und diese Dokumentation committen und nach Gitea pushen.
|
||
2. Backup-Archiv und `.env` **getrennt** physisch mitnehmen.
|
||
3. Backend beenden, keine weiteren Dialoge mehr als „führende Instanz“ führen, sobald Welle 1 zu Hause bestätigt ist.
|
||
4. Slice-2-Konzept, Debug-Export und Memory-Slice **nicht** auf dem Laptop zu Ende bauen.
|
||
|
||
---
|
||
|
||
## 4. Offene Cursor-Sessions (Laptop)
|
||
|
||
Diese Sessions sind Kontext, keine zweite Source of Truth. Kanonisch bleiben die Repository-Dateien.
|
||
|
||
| Session | Thema | Status für den Transfer |
|
||
|---|---|---|
|
||
| [Opening-Impuls](d5e159cf-4d3c-4069-95f9-123a5500b1da) | Erster Impuls zog abgeschlossene Vortage / 400-Zeichen-Entry-Prefix | **Code und kanonische Doku fertig (2026-09-07).** Invariante in `mvp.md` §6.1, Fit-Gap §6.4, `mvp_implementation.md` §17. Bewusst offen: Prefix-Recency im laufenden Dialogzug. Persönliche Dialoginhalte nicht in Doku. |
|
||
| Diese Session | Umgebungswechsel | **Laptop-pflichtig.** Handover und Work Orders angelegt; kanonische Opening-Doku nachgezogen. Commit/Push und physisches Backup bleiben die Abnahme. |
|
||
| `docs/work_orders/debug_diagnostics_perfection.md` | Zentraler Admin-Export | **Verschieben.** Kein Laptop-Zwang. |
|
||
| `docs/work_orders/dialogue_memory_next_slice_handover.md` | Dialog + Langzeitgedächtnis | **Verschieben.** Konzept/Fit-Gap, keine Implementierung auf dem Laptop. |
|
||
| `docs/architecture/functional/Idea_seconmd_sclide.md` | Fachlicher Slice-2-Brief | **Verschieben.** Keine Dateien ändern, bis eine Konzept-Session ihn abarbeitet. |
|
||
| Ältere MVP-Sessions (Freeze, Editorial, Policy, Debug-Persistenz, Writing Style) | Journal-MVP 1.0 | **Abgeschlossen** im Commit `e42f751`, sofern nach Gitea gepusht. |
|
||
|
||
Ältere Transcripts lokal unter Cursor; sie müssen nicht migriert werden, wenn Gitea den Code-Stand trägt.
|
||
|
||
---
|
||
|
||
## 5. Welle 1 – Heim-Entwicklung mit SQLite
|
||
|
||
Auftrag: `../../work_orders/home_environment_setup.md` Phase A.
|
||
|
||
1. Auf dem Heimrechner (erwarteter Pfad analog `C:\dev\Kansho` oder später Linux-Checkout) `git clone https://gitea.stommer.de/Lars/Kansho.git`.
|
||
2. `.\scripts\dev-setup.ps1` (Windows) bzw. venv + `npm install`.
|
||
3. `backend/.env` aus der **separaten** Secret-Kopie anlegen, nicht aus dem Backup.
|
||
4. Backend **nicht** mit Produktionsdaten starten, bevor das Restore-Ziel leer oder bewusst überschrieben wird.
|
||
5. Restore: `.\scripts\backup-local.ps1 restore -Archive <pfad>\kansho-20260907-055703.zip -Confirm -Replace`.
|
||
6. Start: Backend 8018, Frontend 5188. Login mit dem bestehenden Admin-Konto (Passwort-Hash steckt in der SQLite, nicht in `.env`).
|
||
7. Smoke: Space `Kroatien 2026` sichtbar, Journal Days vorhanden, ein Entry mit Medien, ein Dialogzug fail-closed ohne Key und mit Key über Gateway, Health `GET /api/health`.
|
||
8. `.\scripts\test-mvp.ps1` (isolierte Temp-DB, ändert die Restoredaten nicht).
|
||
|
||
Erst wenn das gilt, ist der Laptop nicht mehr führend.
|
||
|
||
---
|
||
|
||
## 6. Welle 2 – Docker, Postgres, Server
|
||
|
||
Auftrag: `../../work_orders/home_environment_setup.md` Phase B–C.
|
||
|
||
Mitai-Referenz auf dem Heimrechner: `C:\dev\mitai` (Compose, `.gitea/workflows/`, Hostpfade `/home/lars/docker/bodytrack` und `bodytrack-dev`).
|
||
|
||
**Noch nicht im Kanshō-Repo:** Dockerfiles, Compose, Gitea-Workflows, Postgres-Adapter. `backend/db.py` ist SQLite (`sqlite3`, `PRAGMA`, `datetime('now')`). Das ist eine eigene Implementierungsarbeit, kein Copy-Paste von Mitai-Fachlogik.
|
||
|
||
Entschieden (nicht neu verhandeln):
|
||
|
||
- Docker Compose: Frontend, Backend, PostgreSQL 16
|
||
- Branches: `develop` → Dev, `main` → Prod
|
||
- Secrets nur in Server-`.env`
|
||
- Persönlicher LLM-Egress nur über Privacy Gateway
|
||
- Kein Auto-Rollback der Datenbank
|
||
- Kanshō-Ports **nicht** Mitai `3002`/`8002`/`3099`/`8099` kopieren
|
||
|
||
Offen, vor Compose festlegen:
|
||
|
||
1. Läuft Kanshō auf demselben Pi wie Mitai, als **eigenes** Compose-Projekt?
|
||
2. Eigenes Postgres (bevorzugte Richtung: ja, eigene Instanz/DB `kansho`, kein Shared-Schema mit Mitai)?
|
||
3. Dev-Domain / Prod-Domain / Host-Pfade (Hypothese: `dev.kansho.jinkendo.de` / `kansho.jinkendo.de`)?
|
||
4. Dev-Ports auf dem Pi, lokal bleiben 5188/8018 für den Windows-Checkout ohne Docker.
|
||
5. Ob Welle 2 zuerst Compose **mit SQLite-Volume** als Zwischenstand nutzt oder direkt Postgres + Migrationsadapter.
|
||
|
||
Empfohlene Reihenfolge in Welle 2:
|
||
|
||
1. Offene Host-Fragen beantworten und in `runtime_and_deploy.md` §1/§6 eintragen.
|
||
2. `develop` anlegen, sobald Auto-Deploy gewünscht ist; bis dahin darf `main` der einzige Branch bleiben.
|
||
3. Compose-Gerüst analog Mitai, **eigene** Container-/Volumen-/Projektnamen (`kansho-*`, keine `bodytrack/`-Pfade).
|
||
4. Backend-Start: Postgres ready → nummerierte SQL-Migrationen → App. Fail-fast.
|
||
5. Datenübernahme SQLite → Postgres als **eigenes** Migrationsskript mit Probe-Restore, nicht still im Alltagspfad.
|
||
6. Gitea-Workflows erst, wenn Runner-Pfade existieren (`runtime_and_deploy.md` §4).
|
||
7. Watchtower später prüfen, nicht in diesem Transfer.
|
||
|
||
---
|
||
|
||
## 7. Datenschutz beim Transfer
|
||
|
||
- Backup und `.env` nie in Git, nie in Chat-Uploads, nie an OpenRouter.
|
||
- Identity-Mappings bleiben lokal (Klasse A).
|
||
- Das Zip ist Klartext-Journal. Transport verschlüsseln (BitLocker-Stick, verschlüsseltes NAS, `age`/`gpg` nach Wahl).
|
||
- Nach erfolgreichem Heim-Restore Laptop-Kopie als Archive behalten, nicht parallel weiterschreiben.
|
||
- Debug-Traces in der DB können Prompt-Ausschnitte enthalten; sie reisen im Backup mit. Auf dem Server den Schalter `debug.persist_traces` prüfen.
|
||
|
||
---
|
||
|
||
## 8. Bewusst nicht Teil dieses Transfers
|
||
|
||
- Slice 2 / Memory-Continuity implementieren
|
||
- Zentralen Debug-Export umbauen
|
||
- Voice, semantisches Retrieval, Self Model
|
||
- Mitai-Verzeichnisnamen, Mitai-Ports, Shared-Postgres-Schema
|
||
- Fachliche Produktentscheidungen aus dem Konzept-Handover
|
||
|
||
---
|
||
|
||
## 9. Nächster Arbeitsschritt
|
||
|
||
1. Auf dem Laptop: `laptop_closeout.md` abschließen (Commit/Push, Backup kopieren).
|
||
2. Zu Hause: neue Session mit diesem Dokument plus `runtime_and_deploy.md` und `home_environment_setup.md`.
|
||
3. Welle 1 bis Restore-Abnahme.
|
||
4. Erst dann Welle 2.
|
||
|
||
---
|
||
|
||
## 10. Querverweise
|
||
|
||
- Runtime: `runtime_and_deploy.md`
|
||
- Stack: `product_frame_and_stack.md`
|
||
- SQLite-Ist: `mvp_implementation.md` §1 und §4
|
||
- Fachliches Session-Handover: `../functional/handover.md`
|
||
- Laptop-Abschluss: `../../work_orders/laptop_closeout.md`
|
||
- Heim-Setup: `../../work_orders/home_environment_setup.md`
|
||
- Mitai: `C:\dev\mitai\docker-compose.yml`, `docker-compose.dev.yml`, `.gitea/workflows/`
|