Lars
07479f6a9f
Use host ports 3006/8005 and 3096/8096 so Kansho does not collide with Bookstack on 3005 or the sister products. Co-authored-by: Cursor <cursoragent@cursor.com>
121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# Kanshō
|
||
|
||
Persönlicher KI-Reflexionsbegleiter innerhalb der Jinkendo-Produktfamilie.
|
||
|
||
> Wahrnehmen → Reflektieren → Verstehen → Einordnen
|
||
|
||
Kanshō ist **kein** Tagebuch mit KI, keine Meditations-App und kein generischer Chatbot. Die Produktidentität ist ein langfristiger, dialogischer Reflexionsbegleiter. Journaling, Achtsamkeit und Meditation sind Werkzeuge, nicht der Kern.
|
||
|
||
## Aktueller Stand
|
||
|
||
Fachliche Konzeption, technische Rahmenarchitektur und der erste **vertikale MVP-Slice** (dialoggeführtes Journal) auf dem lokalen Produktrahmen (`frontend/`, `backend/`). Identity bleibt lokal; persönlicher LLM-Egress nur über das Privacy Gateway.
|
||
|
||
| Bereich | Stand |
|
||
|---|---|
|
||
| Produktidentität | entschieden: Personal Reflection Companion |
|
||
| Technische Form | entschieden: PWA, Mobile First, Offline, Transkription |
|
||
| Fachliche Doku | Baseline in `docs/architecture/functional/` |
|
||
| Technische Doku | vorläufiger Rahmen in `docs/architecture/technical/` |
|
||
| App | MVP-Journal-Slice auf dem Produktrahmen; Dialog-IA und Target-Modell nicht eingefroren |
|
||
|
||
Remote: [gitea.stommer.de/Lars/Kansho](https://gitea.stommer.de/Lars/Kansho.git)
|
||
|
||
Die Urlaubs-Laptop-Instanz lief ohne Docker auf SQLite. Heimtransfer, Backup und späterer Server-/Postgres-Pfad: `docs/architecture/technical/environment_handover.md`.
|
||
|
||
## Dokumentation zuerst laden
|
||
|
||
Nicht alle Kapitel gleichzeitig in den Kontext ziehen. Der Index beschreibt sinnvolle Bundles:
|
||
|
||
- `docs/architecture/functional/documentation_index.md`
|
||
- `docs/architecture/technical/documentation_index.md`
|
||
|
||
Führende Root-Dokumente:
|
||
|
||
1. `docs/architecture/functional/fachliche_zielarchitektur.md`
|
||
2. `docs/architecture/functional/produktvision_und_produktidentitaet.md`
|
||
3. `docs/architecture/functional/interview_plan.md`
|
||
4. `docs/architecture/technical/technische_zielarchitektur.md`
|
||
|
||
Nächster Konzeptblock: Abschluss und Outputs der **Tagesreflexion** (siehe Interviewplan).
|
||
|
||
## Lokal starten
|
||
|
||
Ohne Docker. SQLite lokal, PostgreSQL bleibt das spätere Ziel. Python 3.12 unter `%LOCALAPPDATA%\Programs\Python\Python312\python.exe`, falls der Store-Alias `python` stört.
|
||
|
||
```powershell
|
||
# einmalig
|
||
.\scripts\dev-setup.ps1
|
||
|
||
# Terminal 1
|
||
cd backend
|
||
.\.venv\Scripts\python -m uvicorn main:app --reload --port 8018
|
||
|
||
# Terminal 2
|
||
cd frontend
|
||
npm run dev
|
||
```
|
||
|
||
Kanshō nutzt eigene lokale Ports, nicht die Vite-/FastAPI-Defaults: Frontend **5188**, Backend **8018** (`strictPort`, kein Ausweichen auf 5173/5174). Dann http://localhost:5188 – erster Start legt das Admin-Profil an.
|
||
|
||
Frame-Test und lokaler Abnahmelauf:
|
||
|
||
```powershell
|
||
.\scripts\test-mvp.ps1
|
||
```
|
||
|
||
Der Lauf setzt UTF-8, leere Provider-Keys und isolierte Temp-Daten. Er ändert nicht `backend/data/kansho.sqlite` und nicht die echten Medien. Fail-closed bleibt prüfbar; Suites, die einen Fake-Provider brauchen, setzen ihn selbst. Einzelne Suites bleiben möglich:
|
||
|
||
```powershell
|
||
cd backend
|
||
$env:PYTHONUTF8 = "1"
|
||
.\.venv\Scripts\python tests\test_frame.py
|
||
.\.venv\Scripts\python tests\test_mvp_journal.py
|
||
```
|
||
|
||
Zwei Provider. URL, Modell und ZDR/No-Train unter **Admin → Schnittstellen**. Der Secret-Key nur in `backend/.env` (Vorlage: `backend/.env.example`, wird nicht committet) oder ebenfalls dort eintragen, nie in der Datenbank.
|
||
|
||
Das Sprachmodell (Dialogzug und Journalentwurf) bleibt fail-closed ohne Key plus ZDR und Trainingsverbot. Maskierung ist lokal per Muster; ein Detect-LLM ist optional und sieht Klartext, deshalb klein oder später Ollama.
|
||
|
||
Tests: `KANSHO_FAKE_PROVIDER=1`, optional `KANSHO_FAKE_DETECT=1`. Zusätzlich `tests/test_privacy_detect.py`.
|
||
|
||
Lokales Backup der Urlaubs-Testdaten (persönlich, unverschlüsselt, ohne `.env` oder Keys):
|
||
|
||
```powershell
|
||
.\scripts\backup-local.ps1 create
|
||
.\scripts\backup-local.ps1 restore -Archive .\local-backups\<datei>.zip -Confirm
|
||
# bestehenden Stand ersetzen, nach automatischem Sicherheitsbackup:
|
||
.\scripts\backup-local.ps1 restore -Archive .\local-backups\<datei>.zip -Confirm -Replace
|
||
```
|
||
|
||
Restore bestätigt ausdrücklich, legt vorher ein Sicherheitsbackup an und überschreibt nie still. Backend währenddessen beenden.
|
||
|
||
## Transfer auf die Heim-Umgebung
|
||
|
||
Persönliche Daten liegen **nicht** beim Provider. Der einmalige Laptop-Transport lief über das selbst gehostete Gitea. Nach dem Restore auf dem Heimrechner `transfer/` aus dem Arbeitsbaum entfernen (Historie behält das Zip).
|
||
|
||
Docker/Postgres, Gitea-Deploy und Cutover: `docs/DEPLOYMENT.md` und `docs/architecture/technical/runtime_and_deploy.md`.
|
||
|
||
## Lokal weiterarbeiten
|
||
|
||
```powershell
|
||
git pull
|
||
```
|
||
|
||
Änderungen nach Gitea:
|
||
|
||
```powershell
|
||
git add .
|
||
git commit -m "Kurze Begründung, warum die Änderung nötig ist"
|
||
git push
|
||
```
|
||
|
||
## Cursor / Vibe Coding
|
||
|
||
Projektregeln liegen in `.cursor/rules/` und in `AGENTS.md`. Sie halten Produktgrenzen, Dokumentationsprinzipien und Privacy-Guardrails im Agenten-Kontext.
|
||
|
||
Der Produktrahmen (React/Vite-PWA, FastAPI, PostgreSQL, Mitai-Auth- und Shell-Muster) ist in der technischen Zielarchitektur festgehalten und darf weitgehend von Mitai kopiert werden. Der fachliche Konzeptionsstand ist nicht final. Weiterhin nicht stillschweigend festlegen:
|
||
|
||
- Kanshō-Start-IA, Dialog- und Memory-Schemas
|
||
- Offline-Sync und konkrete Ports/Domains
|
||
- AI-Agentenzerlegung, Integrationsverträge, MVP-Schnitt
|