From aae6724c9114cc102e96cbb9edd7d7959106bb68 Mon Sep 17 00:00:00 2001 From: lukisch <55554266+lukisch@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:39:48 +0100 Subject: [PATCH] docs(marketing): sequence diagram architecture, UI tour gallery & test badge parity --- CHANGELOG.md | 8 ++++++ README-DE.md | 58 +++++++++++++++++++++++++++++++++++++++--- README.md | 58 +++++++++++++++++++++++++++++++++++++++--- llms.txt | 6 ++--- tests/test_metadata.py | 14 +++++----- 5 files changed, 126 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e097c2b..c9606c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,14 @@ Alle wichtigen Änderungen an diesem Projekt werden in dieser Datei dokumentiert ## [Unreleased] +### Pfad B: Sequenzdiagramme, visuelle Benutzeroberflächen-Tour & Test-Badge-Parität (2026-11-03) [GITHUBBOT_ONE_REPO_MARKETING_AND_DESIGN] +- **Sequenzdiagramm-Architektur (`README.md`, `README-DE.md`)**: + - Neues zweisprachiges Mermaid-`sequenceDiagram` in Abschnitt 3 für den vollständigen End-to-End-Lebenszyklus: E-Mail-Abruf (IMAP SSL / Gmail OAuth2), PDF-Konvertierung, OCR-Extraktion, SHA-256 Hashdeduplikation, optionales Offline-Prüfbündel mit Web Companion PWA und normierte DATEV EXTF CSV Buchungsstapel-Erzeugung. +- **Visuelle Benutzeroberflächen-Tour & Screenshot-Galerie (`README.md`, `README-DE.md`)**: + - Strukturierte 2x2-Galerie in Abschnitt 1 mit hochauflösenden Store-Screenshots: Rechnungsübersicht & Betragserfassung, Postfach-Konfiguration, DATEV-Export und Offline Web Companion PWA. +- **Verifikation & Test-Parität (`README.md`, `README-DE.md`, `llms.txt`, `tests/test_metadata.py`)**: + - Test-Badges und Verifikationsangaben auf 302/302 Pytest-Tests + 10/10 Node-Tests (100% grün) und Stempel `2026-11-03` synchronisiert. + ### WCAG 2.1 AA / BITV 2.0 Barrierefreiheit, Tastatur-Ergonomie, Menüleiste, Statusbar & Dialog-Härtung (2026-11-02) [SOFTWARE_UX_AND_ACCESSIBILITY_REVIEW] - **Barrierefreie Menüleiste & Alt-Mnemonics (`UniversalInvoiceMail.py`)**: - `MainWindow.menuBar()` mit barrierefreiem Namen ("Hauptmenü") und 4 Hauptmenüs strukturiert: `&Datei` (Alt+D), `&Bearbeiten` (Alt+B), `&Ansicht` (Alt+A) und `&Hilfe` (Alt+H). diff --git a/README-DE.md b/README-DE.md index 26e52b4..d4f5ac1 100644 --- a/README-DE.md +++ b/README-DE.md @@ -4,7 +4,7 @@ [![doc-bricks Organisation](https://img.shields.io/badge/Organisation-doc--bricks-blue.svg)](https://github.com/doc-bricks) [![open-bricks Ökosystem](https://img.shields.io/badge/%C3%96kosystem-open--bricks-4A154B.svg)](https://github.com/open-bricks) -[![Pytest](https://img.shields.io/badge/Tests-282%20passed%20%7C%20100%25%20green-brightgreen.svg)](https://github.com/doc-bricks/UniversalInvoiceMail) +[![Pytest](https://img.shields.io/badge/Tests-302%20passed%20%7C%20100%25%20green-brightgreen.svg)](https://github.com/doc-bricks/UniversalInvoiceMail) [![Web Companion](https://img.shields.io/badge/Web%20Companion-10%20passed-brightgreen.svg)](web_companion/) [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/) [![Datenschutz: Local-First](https://img.shields.io/badge/Datenschutz-100%25%20Local--First-brightgreen.svg)](#15-datenschutz--datensicherheit) @@ -15,7 +15,7 @@ [![Level 1 SBOM](https://img.shields.io/badge/SBOM-Level%201-brightgreen.svg)](THIRD_PARTY_LICENSES.md) [![Notice: Lukas Geiger](https://img.shields.io/badge/Notice-Lukas%20Geiger-blue.svg)](NOTICE) [![LLMs.txt Discovery](https://img.shields.io/badge/LLMs.txt-Discovery-blue.svg)](llms.txt) -[![Geprüft](https://img.shields.io/badge/Gepr%C3%BCft-2026--10--03-informational.svg)](MARKETING-LOG.txt) +[![Geprüft](https://img.shields.io/badge/Gepr%C3%BCft-2026--11--03-informational.svg)](MARKETING-LOG.txt) [![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-yellow.svg)](LICENSE) @@ -66,6 +66,18 @@ Kommerzielle Cloud-Dienste verlangen dafür permanente Zugriffsrechte auf privat ![UniversalInvoiceMail Vorschau](README/screenshots/main.png) +### 📸 Visueller Rundgang & Benutzeroberfläche + +| 1. Rechnungsübersicht & Betragserfassung | 2. Sichere Postfach-Konfiguration | +|---|---| +| ![Rechnungsübersicht](README/screenshots/store/01_rechnungsuebersicht.png) | ![Postfach-Konfiguration](README/screenshots/store/02_postfach_konfiguration.png) | +| *Sortierbare Tabelle mit Status, erfassten Beträgen, Vorschau & Tastatur-Ergonomie.* | *Direkter SSL-IMAP-Zugriff (Port 993) & Google Gmail OAuth2 mit minimalen Berechtigungen.* | + +| 3. Vorab validierter DATEV-Export | 4. Offline Web Companion PWA | +|---|---| +| ![DATEV-Export Dialog](README/screenshots/store/03_datev_export.png) | ![Web Companion PWA](README/screenshots/store/04_bundle_companion.png) | +| *Normierte cp1252-EXTF-CSV-Buchungsstapel mit Vorab-Kontenvalidierung (SKR03/SKR04).* | *Datenschutzkonforme Belegprüfung und Änderungsabgleich im lokalen Webbrowser.* | + --- @@ -87,6 +99,8 @@ Kommerzielle Cloud-Dienste verlangen dafür permanente Zugriffsrechte auf privat ## 3. Visuelle Systemarchitektur & Ablaufdiagramm +### 🧩 Komponenten-Pipeline Ablaufdiagramm + ```mermaid flowchart TD subgraph Sources ["Mail-Quellen (Local-First)"] @@ -125,6 +139,42 @@ flowchart TD BundleImp --> Config ``` +### 🔄 End-to-End Verarbeitungs- & Prüfsequenz + +```mermaid +sequenceDiagram + autonumber + actor User as Anwender / Buchhaltung + participant App as UniversalInvoiceMail (Desktop) + participant Mail as Mail-Server (IMAP / Gmail API) + participant Engine as Verarbeitungs-Engine (PDF & OCR) + participant Storage as Lokale Speicherung (%USERPROFILE%) + participant PWA as Web Companion (Offline PWA) + participant DATEV as Steuerberater / DATEV EXTF + + User->>App: Abruf starten (Suchprofil & Zeitraum) + App->>Mail: Nachrichten abfragen (IMAP SSL 993 oder Gmail API OAuth2) + Mail-->>App: E-Mails & Rechnungsanhänge übertragen + App->>Engine: Anhänge zur Standardisierung übergeben + Engine->>Engine: Bilder, DOCX, XLSX in Archiv-PDF konvertieren + opt Reine Bildscans & Faxbelege + Engine->>Engine: OCR-Textebene via Tesseract & pypdfium2 extrahieren + end + Engine->>Storage: Normierte PDFs ablegen & SHA-256 Hash berechnen + App->>Storage: Lokale Rechnungsmetadaten & Beträge zwischenspeichern + opt Optionale Offline-Prüfung via Web Companion + App->>Storage: Redigiertes Prüfbündel exportieren (JSON ohne Mailbody) + User->>PWA: Prüfbündel im lokalen Browser öffnen + User->>PWA: Beträge, Freigabestatus & Notizen bearbeiten + PWA-->>User: Minimales Änderungsbündel exportieren + User->>App: Änderungsbündel in Desktop-App importieren + App->>Storage: Freigabestatus & Betragsabgleich synchronisieren + end + User->>App: DATEV-Export anfordern (Berater- & Mandanten-Nr) + App->>App: Vorab-Validierung ausführen (Kontenlänge 4-8 Ziffern, Eindeutigkeit) + App->>DATEV: Normierten cp1252-EXTF-CSV-Buchungsstapel erzeugen (SKR03/SKR04) +``` + --- @@ -168,7 +218,7 @@ UniversalInvoiceMail richtet sich an vier zentrale Anwendergruppen: | **7. Offline-Fähigkeit** | **100% Offline-Archiv** | NEIN (Nur Online) | JA | JA | JA | | **8. PWA Companion** | **JA (Lokal redigiert)** | Cloud Mobile App | NEIN | NEIN | NEIN | | **9. Open Source / MIT** | **JA (Freie MIT-Lizenz)**| NEIN (Proprietär) | Entfällt | Variiert | Variiert | -| **10. Automatisierte Tests** | **282 Pytest + 10 Node**| Unbekannt / SaaS | 0 | Minimal | 0 – 5 | +| **10. Automatisierte Tests** | **302 Pytest + 10 Node**| Unbekannt / SaaS | 0 | Minimal | 0 – 5 | --- @@ -398,7 +448,7 @@ ruff check . python -m compileall -q . ``` -Das Repository enthält gemockte Python-Tests für Hilfsfunktionen, IMAP-/Gmail-Workflows, DATEV-Abläufe, Bündel-Export/-Import, Barrierefreiheit, Headless-CLI-Automation, Metadaten-Parität sowie Node-Vertragstests für den Web Companion (282 Pytest + 10 Node-Tests 100% grün). +Das Repository enthält gemockte Python-Tests für Hilfsfunktionen, IMAP-/Gmail-Workflows, DATEV-Abläufe, Bündel-Export/-Import, Barrierefreiheit, Headless-CLI-Automation, Metadaten-Parität sowie Node-Vertragstests für den Web Companion (302 Pytest + 10 Node-Tests 100% grün). --- diff --git a/README.md b/README.md index acc2d76..58753ef 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![doc-bricks Organization](https://img.shields.io/badge/Organization-doc--bricks-blue.svg)](https://github.com/doc-bricks) [![open-bricks Ecosystem](https://img.shields.io/badge/Ecosystem-open--bricks-4A154B.svg)](https://github.com/open-bricks) -[![Pytest](https://img.shields.io/badge/Tests-282%20passed%20%7C%20100%25%20green-brightgreen.svg)](https://github.com/doc-bricks/UniversalInvoiceMail) +[![Pytest](https://img.shields.io/badge/Tests-302%20passed%20%7C%20100%25%20green-brightgreen.svg)](https://github.com/doc-bricks/UniversalInvoiceMail) [![Web Companion](https://img.shields.io/badge/Web%20Companion-10%20passed-brightgreen.svg)](web_companion/) [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/) [![Privacy: Local-First](https://img.shields.io/badge/Privacy-100%25%20Local--First-brightgreen.svg)](#15-privacy--data-protection-policy) @@ -15,7 +15,7 @@ [![Level 1 SBOM](https://img.shields.io/badge/SBOM-Level%201-brightgreen.svg)](THIRD_PARTY_LICENSES.md) [![Notice: Lukas Geiger](https://img.shields.io/badge/Notice-Lukas%20Geiger-blue.svg)](NOTICE) [![LLMs.txt Discovery](https://img.shields.io/badge/LLMs.txt-Discovery-blue.svg)](llms.txt) -[![Verified](https://img.shields.io/badge/Verified-2026--10--03-informational.svg)](MARKETING-LOG.txt) +[![Verified](https://img.shields.io/badge/Verified-2026--11--03-informational.svg)](MARKETING-LOG.txt) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -66,6 +66,18 @@ Commercial cloud aggregators require granting third parties ongoing access to pe ![UniversalInvoiceMail Preview](README/screenshots/main.png) +### 📸 Visual Interface Tour + +| 1. Invoice Overview & Inline Editing | 2. Secure Mailbox Configuration | +|---|---| +| ![Invoice Overview Table](README/screenshots/store/01_rechnungsuebersicht.png) | ![Mailbox Configuration](README/screenshots/store/02_postfach_konfiguration.png) | +| *Sortable table with review status, parsed amounts, PDF preview & keyboard navigation.* | *Direct SSL IMAP (Port 993) & Google Gmail OAuth2 configuration with least privilege.* | + +| 3. Pre-Validated DATEV Export | 4. Offline Web Companion PWA | +|---|---| +| ![DATEV Export Dialog](README/screenshots/store/03_datev_export.png) | ![Web Companion PWA](README/screenshots/store/04_bundle_companion.png) | +| *Standardized cp1252 EXTF CSV booking batch generation with pre-save account syntax checks.* | *Privacy-first redacted invoice review and delta synchronization in any local browser.* | + --- @@ -87,6 +99,8 @@ Commercial cloud aggregators require granting third parties ongoing access to pe ## 3. Visual Architecture & Flowchart +### 🧩 Component Pipeline Flowchart + ```mermaid flowchart TD subgraph Sources ["Mail Sources (Local-First)"] @@ -125,6 +139,42 @@ flowchart TD BundleImp --> Config ``` +### 🔄 End-to-End Processing & Review Sequence + +```mermaid +sequenceDiagram + autonumber + actor User as User / Finance Staff + participant App as UniversalInvoiceMail (Desktop) + participant Mail as Mail Server (IMAP / Gmail API) + participant Engine as Processing Pipeline (PDF & OCR) + participant Storage as Local Storage (%USERPROFILE%) + participant PWA as Web Companion (Offline PWA) + participant DATEV as Accounting / DATEV EXTF + + User->>App: Launch fetch with profile & date range + App->>Mail: Query messages (IMAP SSL 993 or Gmail API OAuth2) + Mail-->>App: Return emails & raw invoice attachments + App->>Engine: Stream attachments for normalization + Engine->>Engine: Convert Images, DOCX, XLSX to archival PDF + opt Scanned image-only receipts + Engine->>Engine: Extract OCR text layer via Tesseract & pypdfium2 + end + Engine->>Storage: Save standard PDFs & compute SHA-256 hash + App->>Storage: Cache local invoice metadata and amounts + opt Optional offline review via Web Companion + App->>Storage: Export redacted bundle (universalinvoicemail-invoicebundle-v1.json) + User->>PWA: Load redacted JSON bundle in offline browser + User->>PWA: Verify amounts, status & bookkeeping notes + PWA-->>User: Export minimal companion delta bundle + User->>App: Import delta bundle into desktop app + App->>Storage: Synchronize amounts & verification status + end + User->>App: Request DATEV export (Advisor & Client ID) + App->>App: Pre-validate account mappings (4-8 digits, unique keys) + App->>DATEV: Generate compliant cp1252 EXTF CSV booking batch (SKR03/SKR04) +``` + --- @@ -168,7 +218,7 @@ UniversalInvoiceMail is tailored for four specific personas: | **7. Offline Capability** | **100% Offline Archival**| NO (Zero Offline) | YES | YES | YES | | **8. PWA Companion** | **YES (Local Redacted)** | Cloud Mobile App | NO | NO | NO | | **9. Open Source / MIT** | **YES (Permissive MIT)** | NO (Proprietary) | N/A | Varies | Varies | -| **10. Automated Tests** | **282 Pytest + 10 Node** | Unknown / SaaS | 0 | Minimal | 0 - 5 | +| **10. Automated Tests** | **302 Pytest + 10 Node** | Unknown / SaaS | 0 | Minimal | 0 - 5 | --- @@ -398,7 +448,7 @@ ruff check . python -m compileall -q . ``` -The repository includes mocked Python tests for helper functions, IMAP/Gmail workflows, DATEV-adjacent behavior, bundle export/import, compact UI control accessibility, headless CLI automation, metadata parity, plus Node contract tests for the Web Companion (282 Pytest + 10 Node tests passing 100% green). +The repository includes mocked Python tests for helper functions, IMAP/Gmail workflows, DATEV-adjacent behavior, bundle export/import, compact UI control accessibility, headless CLI automation, metadata parity, plus Node contract tests for the Web Companion (302 Pytest + 10 Node tests passing 100% green). --- diff --git a/llms.txt b/llms.txt index 5dd3206..6e8c393 100644 --- a/llms.txt +++ b/llms.txt @@ -25,7 +25,7 @@ UniversalInvoiceMail is a local-first Windows desktop app for collecting invoice - `DATEV Buchungsstapel aus E-Mail` - `Rechnungen aus Gmail archivieren` -## Last-checked: 2026-10-03 +## Last-checked: 2026-11-03 Important files: @@ -47,7 +47,7 @@ Important files: - `ROADMAP.txt`: Public roadmap and follow-up strands for the desktop and companion workflows. - `web_companion/`: local-only PWA review surface with committed install manifest and icons. - `.github/workflows/`: hardened CI lifecycle workflows (auto-assign, label-sync, stale, welcome, tests, source-platform-smoke). -- `tests/`: mocked unit, integration, validation, i18n, metadata parity, accessibility, and security/license contract tests (282 passing). +- `tests/`: mocked unit, integration, validation, i18n, metadata parity, accessibility, and security/license contract tests (302 passing). - `DATEVSettingsDialog`: editable sender/keyword mapping table with add/remove/reset, pre-save validation against SKR03/SKR04 rules, and `DATEVConfig` persistence. - Statutory liability limitation: German Civil Code § 521 BGB (Gefälligkeitsrecht) and 48h Security Response SLA. @@ -60,7 +60,7 @@ Safety boundary: Verification: -- Run `PYTHONIOENCODING=utf-8 pytest -ra -v` (282 Pytest tests passing 100% green). +- Run `PYTHONIOENCODING=utf-8 pytest -ra -v` (302 Pytest tests passing 100% green). - Run `node --test web_companion/tests/library.test.mjs web_companion/tests/mobile_pwa_smoke.test.mjs` (10 passed). - Run `ruff check .` (0 errors). - Run `python -m compileall -q .` (0 bytecode errors). diff --git a/tests/test_metadata.py b/tests/test_metadata.py index c84bc8b..4b728ed 100644 --- a/tests/test_metadata.py +++ b/tests/test_metadata.py @@ -296,18 +296,18 @@ def test_pytest_hardening_and_cache_defense(): def test_readme_badges_and_test_parity(): - """Verify README badges and comparative matrices reflect 282 passing tests and 2026-10-03.""" + """Verify README badges and comparative matrices reflect 302 passing tests and 2026-11-03.""" readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") readme_de = (REPO_ROOT / "README-DE.md").read_text(encoding="utf-8") - assert "Tests-282%20passed" in readme_en - assert "Tests-282%20passed" in readme_de - assert "Verified-2026--10--03" in readme_en - assert "Gepr%C3%BCft-2026--10--03" in readme_de + assert "Tests-302%20passed" in readme_en + assert "Tests-302%20passed" in readme_de + assert "Verified-2026--11--03" in readme_en + assert "Gepr%C3%BCft-2026--11--03" in readme_de assert "Contributing-Guidelines" in readme_en assert "Contributing-Guidelines" in readme_de - assert "282 Pytest + 10 Node" in readme_en - assert "282 Pytest + 10 Node" in readme_de + assert "302 Pytest + 10 Node" in readme_en + assert "302 Pytest + 10 Node" in readme_de def test_ci_lifecycle_workflows_and_labels():