suro/aza
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c24f18b01e6eca8ca9817f1859d3dd90789b5ed
aza/AzA march 2026/project_handover.md
suro faf4ca10c9 update
2026-03-25 22:03:39 +01:00

13 KiB
Raw Blame History

AZA - Master Handover / Operational Runbook

Working Mode Rules

  • User does not tinker or manually edit files.
  • Always provide 1:1 Composer patches (usually Opus).
  • One step at a time.

CURRENT PROJECT PHASE (2026-03-25)

Phase: B1 Backend Sprint – Server-Side OpenAI Architecture (Variant B mandatory)

ARCHITECTURE DECISION VARIANT B (mandatory, 2026-03-25):

  • NO OpenAI key in the desktop app
  • NO per-customer OpenAI key requirement
  • NO shared OpenAI key client-side
  • Instead: AZA Office talks ONLY to own AZA backend
  • Only the AZA backend talks to OpenAI
  • The OpenAI key resides EXCLUSIVELY server-side
  • NO half-measures, NO shared-key hacks

Honest Assessment:

  • Desktop app is far advanced and fundamentally usable
  • Architecture decision Variant B is made
  • Hetzner backend is now being seriously built as server path
  • WordPress/Shop (Hostpoint) continues in parallel

B1 BACKEND SPRINT (4 Weeks)

Week Approx. Dates Focus
1 Mar 25 – Apr 01 Backend Chat Proxy Endpoint (POST /v1/chat) + Auth + Rate Limiting
2 Apr 02 – Apr 08 Desktop app: all OpenAI calls via backend instead of direct
3 Apr 09 – Apr 15 Hetzner Deploy: Docker/Caddy/HTTPS + Production Env + Smoke Tests
4 Apr 16 – Apr 22 E2E Test Desktop→Backend→OpenAI + Customer journey without OpenAI key + Go-Live

CURRENT PRIORITY ORDER (B1 Backend Sprint)

  1. Backend Chat Proxy POST /v1/chat (Week 1) – Foundation of architecture
  2. Desktop app migration to backend (Week 2) – Migrate all OpenAI calls
  3. Hetzner Deploy (Week 3) – Set up production server
  4. E2E Test + Go-Live backend path (Week 4) – Customer journey without OpenAI key
  5. WooCommerce/Stripe purchase path runs IN PARALLEL (Hostpoint)

EXPLICITLY DEFERRED / NOT NOW:

  • Update comfort / separate auto-updater
  • Browser-AZA web app (after backend architecture)
  • Large refactors not serving Variant B

HOSTPOINT vs. HETZNER:

  • Hostpoint remains for website/marketing/WooCommerce/Stripe
  • Hetzner is NOW the backend path for OpenAI proxy/API
  • Both run in parallel, not against each other

NEXT MAIN BLOCK (B1-W1)

Backend Chat Proxy Endpoint (POST /v1/chat)

Why this block first:

  • Without /v1/chat, desktop app cannot migrate away from direct OpenAI calls
  • Pattern already exists: /v1/transcribe does exactly this for audio transcription
  • Everything else (Hetzner deploy, key removal from app) depends on this

What already exists:

  • POST /v1/transcribe: Backend→OpenAI for transcription (WORKS)
  • Auth contract: X-API-Token + X-Device-Id headers
  • Docker/Caddy/Compose: Deployment stack in deploy/
  • License system: /license/status endpoint
  • OpenAI client: imported and configured in backend_main.py

What is missing (B1-W1 scope):

  1. POST /v1/chat endpoint in backend_main.py
  2. Request model: model, messages, temperature, max_tokens etc.
  3. Server-side OpenAI chat.completions.create
  4. Rate limiting per token/device
  5. Local Docker test

Target customer workflow (after B1 complete):

  1. Customer buys via WooCommerce/Stripe
  2. Customer installs → app starts → NO OpenAI key needed
  3. All AI features run through AZA backend on Hetzner
  4. OpenAI key resides ONLY on the server

Blocker Rule: One clear block at a time. No 10 construction sites simultaneously.

CUSTOMER JOURNEY ANALYSIS (2026-03-25)

Step Status Detail
Purchase (WooCommerce) IN PROGRESS (parallel) Docs ready, 7 admin steps on Hostpoint
Download PARTIAL Mechanism exists, WooCommerce upload missing
Installer FUNCTIONALLY COMPLETE No code signing (SmartScreen warning)
Activation BRIDGE IMPLEMENTED AZA key sets full mode, trial dialog shows status
First Start BEING REBUILT (VARIANT B) OpenAI key being replaced by backend proxy. B1 sprint running.

OPEN FOCUS BLOCKS

Priority Block Description
HIGHEST B1-W1: Backend /v1/chat Chat Proxy Endpoint – foundation of Variant B
HIGHEST B1-W2: Desktop migration All OpenAI calls via backend
HIGHEST B1-W3: Hetzner Deploy Docker/Caddy/HTTPS on Hetzner VPS
HIGHEST B1-W4: E2E + Go-Live Desktop→Backend→OpenAI end-to-end
HIGH (parallel) FB-A: WooCommerce Stripe purchase path on Hostpoint
MEDIUM FB-C: Signing Signing readiness prepared
DEFERRED FB-D: Update Comfort Only after stable customer journey

PRODUCT NAME – CURRENT DIRECTION

Current favorite: AZA Office

Preferred long form:

  • AZA Office – Ihr medizinischer KI-Arbeitsplatz fuer die Praxis

Second good variant:

  • AZA Office – Die KI-Assistenz fuer medizinische Dokumentation

Status: Current preferred naming direction. Not yet legally/brand-strategically finalized. Use for WooCommerce/website/download/Go-Live/product presentation.

Earlier shortlist (AZA Desktop): Documented in project_roadmap.json and project_plan.json. Superseded by AZA Office.

WORKING PRINCIPLES FOR NEXT CHATS

  • Root-cause-first instead of blind patching
  • One clear block at a time
  • No 10 construction sites simultaneously
  • Weight real installed builds higher than code assertions
  • Don't declare "done" too early
  • Distinguish Desktop into:
    1. Dev code
    2. Newly built installer
    3. Real behavior in installed build

Key Commands

Local start:

cd "C:\Users\surov\Documents\AZA\backup 24.2.26"
powershell -ExecutionPolicy Bypass -File .\deploy\local_reset_and_start.ps1

Tests:

powershell -ExecutionPolicy Bypass -File .\deploy\authorized_status.ps1
powershell -ExecutionPolicy Bypass -File .\deploy\smoke_suite.ps1
powershell -ExecutionPolicy Bypass -File .\deploy\docker_smoke.ps1

Desktop UX Block (2026-03-18)

  • Benutzerdaten bei Deinstallation erhalten (Inno Setup, Standard: Nein)
  • Signatur-UI: Haekchen "Profilname verwenden" + abweichender Signaturname in Einstellungen
  • Rechtsklick-Haekchen im Minifenster (synchronisiert)
  • Kommentare-Fenster (TEILWEISE: Grundstruktur, Detailmodus + Live-Update offen)
  • Briefstil-Lernen (DOCX-Upload, Stilprofil-Analyse, Profilauswahl, Integration)
  • Briefstil-Profile Fix: KISIM/Klinisch als feste Systemprofile, vereinheitlichtes Stilprofil-UI im Brief-Bereich
  • Autotext Root-Cause-Fix (_is_admin NameError, Listener-Revert)
  • Persistenz-Patch: Erststart-Consent, Profil+Code, Kommentare-Toggle, Einstellungs-Gruppierung
  • Uebersetzer-Stabilitaetsfix: Toplevel-Embedded statt Tkinter-in-Thread
  • Briefprofile: KISIM Bericht + Klinischer Bericht als vordefinierte Profile

AZA Clean Uninstall / Reset Tool

Per Doppelklick: AZA_Deinstallieren.bat

Per PowerShell:

powershell -ExecutionPolicy Bypass -File .\tools\aza_clean_uninstall.ps1
  • Modus 1: Nur App entfernen, Benutzerdaten behalten
  • Modus 2: Vollstaendig zuruecksetzen (App + Benutzerdaten)
  • Kein Neustart noetig (Standardfall)
  • Danach direkt Neuinstallation moeglich

Do-Not-Break Rules

  1. Do not change existing API response formats (especially /license/status).
  2. Do not modify auth/security mechanisms.
  3. Do not log or print secrets/tokens/keys.
  4. Signature fallback: profile name used when no explicit signature set.
  5. User data in %APPDATA%\AZA Desktop NOT deleted on uninstall by default.
  6. Style learning from old letters: only style/structure, NEVER copy patient data or old content.

Correction Patch (FIX-01) – 2026-03-19

  1. Translator label: "Fachuebersetzer" renamed to "Uebersetzer" everywhere
  2. Comments window: auto-open checkbox (persistent), live-update on KG change, clickable diagnosis headings with detail popups
  3. Correction window: scrollbar for saved corrections list
  4. Style profile live application: brief regenerated immediately on profile change/toggle
  5. "Profil anwenden" button in style profile management dialog
  6. KG creation writes directly to main window (no popup)
  7. Persistence: dokumente_collapsed now properly saved/loaded
  8. Main window centering: robust delayed centering after widget build via self.after()

FIX-02 Nachschaerfungs-Patch (2026-03-19)

  1. Style profile dialog: now management-only (status display, learn, delete). Active selection exclusively in brief window.
  2. Comments window: auto-opens after KG creation when checkbox is active (not just refreshes existing window).
  3. Logo separation: Wassertropfen (logo.ico) for EXE/desktop/installer/title bar icon. Original logo (logo.png) for internal branding (bottom-left).

Files: basis14.py, aza_text_windows_mixin.py, aza_desktop.spec, logo.png, logo.ico

FIX-09/10/11 Quellenstrenge Kommentarlogik – Inhaltsquelle / Originallink Trennung (2026-03-22)

Root Cause (FIX-09): LLM generated medication info purely from model knowledge. Root Cause (FIX-10): PharmaWiki regex wrong (used h2/h3 instead of span#subtitle). Compendium.ch is SPA (not scrapable). Root Cause (FIX-11): Content source and external link were mixed in one dropdown/dict.

Fix (FIX-11): Clean separation of content source and external link:

CONTENT SOURCE (what is shown in detail window):

  • _fetch_doccheck_info(med_name): DocCheck Flexikon (default) – server-rendered, h2/h3 headings
  • _fetch_pharmawiki_info(med_name): PharmaWiki (fallback) – span#subtitle headings
  • User-selectable via "Inhaltsquelle:" dropdown, persistent in med_content_quelle
  • New dict _MED_CONTENT_QUELLEN (DocCheck, PharmaWiki)
  • Curated _MEDICATION_FACTS as offline fallback

EXTERNAL LINK ("Originalquelle oeffnen" button):

  • CH = Compendium, AT = BASG, DE = BfArM – UNCHANGED
  • Still via _MED_QUELLEN / medikament_quelle – NOT modified

Therapies/procedures: separate handling via DocCheck/PharmaWiki (unchanged). Candidate logic (Dermowarte→Dermovate etc.): untouched.

Files: basis14.py

ARCH-MED: Medication Source Architecture (2026-03-22)

Architecture (implemented):

  1. Detect medication in KG text (existing tagging + validation)
  2. Fetch content from DocCheck Flexikon (default) or PharmaWiki (user choice/fallback)
  3. Inject source text into LLM prompt (strict: only use provided data)
  4. Curated facts list as offline fallback
  5. External link always country-based (CH/AT/DE)
  6. Omit anything not from the source

Coverage: All medications available on DocCheck Flexikon + PharmaWiki.

Next steps:

  1. Caching strategy (cache fetched content locally)
  2. Robustness against HTML structure changes
  3. Long-term: Compendium API / HCI Solutions data license evaluation

Later market profiles (DE: BfArM, AT: BASG) separately.

Zukunftsblock – Internationalisierung / Laender- und Quellenprofile (GEPARKT)

Status: Zukunftsthema – NICHT fuer jetzt. Erst nach DACH-Stabilitaet und Produkterfolg.

Voraussetzung: DACH (CH/DE/AT) stabil, Go-Live gesichert, Produkt erfolgreich.

Zielbild:

  • UI/Sprache, Medikamenten-/Diagnose-/Therapiequellen pro Markt anpassbar
  • Profil-Felder: app_language, market_region, med_source_profile, dx_source_profile, therapy_source_profile
  • Manueller Override durch Benutzer/Praxis
  • Nicht hart nach Herkunftsland schalten – saubere Profil-Logik
  • Handelsnamen/Zulassungen/Fachinfos sind laenderspezifisch → Quellenprofile pro Markt

Kein aktueller Implementierungsblock. Erst nach Go-Live und DACH-Erfolg relevant.

Windows Code-Signing / Smart App Control Readiness (2026-03-23)

Problem: Windows Smart App Control blockiert unsignierte Apps bei Kunden.

Status: Signing-Readiness vorbereitet, noch NICHT produktiv aktiviert.

Vorbereitet:

  • sign_release.ps1 – signiert EXE + DLLs/PYDs + Installer (DryRun-Modus verfuegbar)
  • build_and_test_release.ps1 – Signing-Schritt integriert (optional, graceful skip)
  • build_release_artifacts.ps1 – Artefakt-Report mit Signatur-Status
  • SIGNING_READINESS.md – Vollstaendige Dokumentation

Signing-Reihenfolge: DLLs/PYDs → EXE → Installer-Build → Installer signieren → Artefakt-Report

Vor Kundenauslieferung noch offen:

  1. EV Code-Signing-Zertifikat beschaffen
  2. signtool.exe installieren (Windows SDK)
  3. Publisher-Name abstimmen (Zertifikat ↔ AppPublisher ↔ Handelsregister)
  4. Produktiver Signierlauf + Test auf Windows-PC mit Smart App Control

Publisher-/Namenskonsistenz (Analyse 2026-03-23):

3 Namensformen im Projekt – beabsichtigt, keine Inkonsistenz:

  • AZA MedWork = Firma/Publisher → SIGNING-KRITISCH (Installer, Legal, Consent, E-Mail-Absender)
  • AZA Desktop = Produktname → konsistent, kein Handlungsbedarf
  • AZA Medical AI Assistant = interner Projektname → nicht signing-relevant

Vor Zertifikatskauf: HR-Name pruefen, AppPublisher auf Zertifikats-Subject abstimmen. Falls HR-Name abweicht: alle signing-relevanten Stellen gemeinsam anpassen (Liste in handover.md). Nach Festlegung: Publisher-Name NICHT mehr wechseln (SmartScreen-Reputation).

Reference in New Issue View Git Blame Copy Permalink