Docs: update ARCHITECTURE + copilot instructions, add CLAUDE.md + USER_GUIDE
- ARCHITECTURE.md: reflect the implemented DI service layer, CAMTParser, OpenTelemetry/observability, the ported report engine, and CAMT+MT940 banking; mark the resolved observations. - copilot-instructions.md: add Services/DI, dual-format banking, observability and testing sections; add an Instruction-Sync banner. - CLAUDE.md (new): Claude Code project instructions mirroring the shared rules, plus build/test workflow notes. Both files state they must stay in sync. - USER_GUIDE.md (new, Fuchs/Docs): end-user process guide (login, invoices, reminders, requests, banking incl. MT940/CAMT upload, DATEV, reports). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
+39
-10
@@ -18,7 +18,8 @@ The **Fuchs Intranet** solution is a line-of-business web application for **Seba
|
||||
| **OCORE_web** | Class Library (shared) | Web utilities: MVC helpers, middleware, auth, captcha |
|
||||
| **OCORE_web_pdf** | Class Library (shared) | PDF generation (MigraDoc/PDFsharp, HTML→PDF) |
|
||||
| **OCORE_Charting** | Class Library (shared) | Data visualization / charting (ported System.Windows.Forms.DataVisualization) |
|
||||
| **MT940Parser** | Class Library (shared) | SWIFT MT940/MT942 bank statement parser |
|
||||
| **MT940Parser** | Class Library (external) | SWIFT MT940/MT942 bank statement parser |
|
||||
| **CAMTParser** | Class Library (in-repo) | ISO 20022 CAMT (camt.052/053/054) bank statement parser |
|
||||
|
||||
**All projects target `net10.0`.**
|
||||
|
||||
@@ -163,8 +164,12 @@ OCORE_Charting (standalone — referenced by solution but no direct project ref
|
||||
### 4.2 Singleton Configuration Object
|
||||
`Fuchs_intranet` is a manually-managed singleton (via `FuchsOcmsIntranet`) initialized at startup with `IConfiguration`. It holds connection strings, app settings, auth helpers, and DB connection factory methods.
|
||||
|
||||
### 4.3 Static Business Logic Classes
|
||||
Most business logic lives in **static classes** (`FuchsPdf`, `FuchsWidgets`, `FuchsReports`, `FuchsFdsEmail`, `Banking`) that receive the controller instance or `Fuchs_intranet` as a parameter. This is a legacy pattern from the VB.NET conversion.
|
||||
### 4.3 Service Layer (Dependency Injection)
|
||||
Business logic lives in **DI-registered services** under `Fuchs/Services/` behind interfaces, injected into `IntranetController`:
|
||||
`IComService`, `IPdfService`, `IInvoiceService`, `IReminderService`, `IReportService`, `IWidgetService`, `IBankingService`, `IMfrClientFactory`.
|
||||
Stateless services (`IPdfService`, `IBankingService`, `IMfrClientFactory`) are singletons; DB/request-scoped services are scoped (see `Program.cs`).
|
||||
`FdsInvoiceData` / `FdsReminderData` are now **pure data holders** (parse + properties); loading, persistence and PDF generation live in the services (fully async — no `Task.Run(...).Wait()`).
|
||||
`FuchsPdf` / `FuchsVisualization` remain as static rendering libraries used *by* the services. The earlier static, controller-coupled helpers (`FuchsWidgets`, `FuchsReports`, `Banking`, `FuchsFdsEmail`) have been removed.
|
||||
|
||||
### 4.4 SQL-First Data Access
|
||||
There is no ORM (no EF Core). All data access uses **ADO.NET via OCORE SQL helpers** (`getSQLDatatable_async`, `getSQLDataSet_async`, `setSQLValue_async`) calling stored procedures and inline SQL. `DataTable`/`DataRow` is the primary data transfer mechanism.
|
||||
@@ -177,9 +182,17 @@ Cookie-based authentication (`CookieAuthenticationDefaults`) with custom claims
|
||||
|
||||
---
|
||||
|
||||
## 5. DI Service Extraction Candidates
|
||||
## 5. Service Layer (implemented)
|
||||
|
||||
The following static classes and tightly-coupled code sections are strong candidates for refactoring into proper DI-registered services. This improves testability, decouples dependencies, and aligns with ASP.NET Core best practices.
|
||||
> **Status: DONE.** The services below are implemented and DI-registered in
|
||||
> `Program.cs`. The original extraction rationale is retained for reference /
|
||||
> history. `FuchsFdsEmail` → `IComService` (ProcessWeb Mailer API, inline
|
||||
> base64 attachments), `FuchsWidgets` → `IWidgetService`, `FuchsPdf` →
|
||||
> `IPdfService`, `Banking` → `IBankingService` (now MT940 **and** CAMT),
|
||||
> `FdsInvoiceData`/`FdsReminderData` → `IInvoiceService`/`IReminderService`
|
||||
> (data classes are now pure POCOs), `FuchsReports` → `IReportService`
|
||||
> (backed by the ported `FuchsVisualization` engine), `FdsMfrClient` →
|
||||
> `IMfrClientFactory`.
|
||||
|
||||
---
|
||||
|
||||
@@ -391,8 +404,24 @@ public class MfrClientFactory : IMfrClientFactory, IDisposable
|
||||
|
||||
## 7. Additional Observations
|
||||
|
||||
1. **`System.Configuration.ConfigurationManager` usage** in `FuchsFdsEmail.cs` directly violates the project's coding standards (`appsettings.json` only).
|
||||
2. **No dependency injection in `FdsInvoiceData`/`FdsReminderData`** — these classes receive the entire controller, creating circular-style dependencies.
|
||||
3. **`FdsMfrClient` is `new`-ed directly** in controller partials (e.g., `IntranetController.Invoices2.cs`) instead of being injected.
|
||||
4. **`OCORE_Charting`** is in the solution but not directly referenced by any project — verify if it's still needed.
|
||||
5. **Topshelf** in `Fuchs_DataService` could be replaced with native `dotnet` Worker Service hosting for .NET 10 alignment.
|
||||
1. ✅ **Resolved** — email/SMS moved off `ConfigurationManager` into `IComService` (ProcessWeb Mailer API).
|
||||
2. ✅ **Resolved** — `FdsInvoiceData`/`FdsReminderData` are now pure data holders; DB + PDF logic moved to `IInvoiceService`/`IReminderService`.
|
||||
3. ✅ **Resolved** — `FdsMfrClient` is created via `IMfrClientFactory` (no `new` in controllers).
|
||||
4. ✅ **Resolved** — `OCORE_Charting` is now used (transitively, via `OCORE_web`'s chart engine) by the report renderer (`FuchsVisualization`).
|
||||
5. ⏳ **Open** — **Topshelf** in `Fuchs_DataService` could be replaced with native `dotnet` Worker Service hosting for .NET 10 alignment.
|
||||
|
||||
---
|
||||
|
||||
## 8. Observability (OpenTelemetry)
|
||||
|
||||
- Instrumentation is centralised in `Fuchs/Observability/FuchsTelemetry.cs`: one `ActivitySource` and one `Meter` (`Fuchs.Intranet`).
|
||||
- **Metrics** — counters (`fuchs.invoices.rendered`, `fuchs.reminders.rendered`, `fuchs.reports.rendered`, `fuchs.emails.sent`/`.failed`, `fuchs.sms.sent`, `fuchs.banking.mt940.rows`, `fuchs.mfr.calls`) and duration histograms (`fuchs.pdf.render.duration`, `fuchs.report.render.duration`, `fuchs.email.send.duration`).
|
||||
- **Tracing** — ASP.NET Core, HttpClient and SqlClient instrumentation plus the app `ActivitySource`; services start spans for their key operations.
|
||||
- Configured in `Program.cs`. Always collected in-process; **OTLP export is opt-in** via `Fuchs:Telemetry:OtlpEndpoint` (and can be disabled with `Fuchs:Telemetry:Enabled=false`), so a missing collector never affects the app.
|
||||
- All services + handlers log entry/result/timing/errors via `ILogger<T>` with structured placeholders.
|
||||
|
||||
## 9. Bank Statement Parsing (MT940 + CAMT)
|
||||
|
||||
- `BankingService` (`IBankingService`) accepts **both** MT940 (SWIFT text, via the external `MT940Parser`) and **CAMT** (ISO 20022 camt.052/053/054 XML, via the in-repo `CAMTParser`).
|
||||
- `ParseToDatatable` **auto-detects** the format from content (XML → CAMT, else MT940) and maps either into the `fds__tt__bankingtransactions` schema; the `bam/up` handler and the frontend upload accept both.
|
||||
- `CAMTParser` matches elements by **local name** (namespace-agnostic) so it works across every camt schema version. When the banking schema changes, keep the MT940 and CAMT column mappings in `BankingService` aligned.
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
# Fuchs Intranet — Benutzerhandbuch
|
||||
|
||||
> Praxisleitfaden für Mitarbeiter:innen der Firma Sebastian Fuchs Bad und Heizung.
|
||||
> Beschreibt die täglichen Abläufe im Intranet. Technische Details siehe
|
||||
> `ARCHITECTURE.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Anmeldung & Konto
|
||||
|
||||
### Anmelden
|
||||
1. Intranet im Browser öffnen.
|
||||
2. E-Mail-Adresse und Passwort eingeben → **Anmelden**.
|
||||
3. Die Sitzung bleibt 8 Stunden aktiv (gleitend).
|
||||
|
||||
### Passwort vergessen
|
||||
1. „Passwort vergessen" wählen, **Nachname** und **E-Mail** eingeben.
|
||||
2. Es wird ein Bestätigungscode per **SMS** an die hinterlegte Mobilnummer gesendet.
|
||||
3. Code eingeben → das Passwort wird per E-Mail zugesandt.
|
||||
*(Aus Sicherheitsgründen erfolgt keine Rückmeldung, ob die Adresse existiert.)*
|
||||
|
||||
### Passwort ändern
|
||||
1. Konto → **Passwort ändern**.
|
||||
2. Bestätigungscode per SMS anfordern und eingeben.
|
||||
3. Altes Passwort + neues Passwort (mind. 6 Zeichen) zweimal eingeben.
|
||||
Das alte Passwort und die Code-Bestätigung werden geprüft.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dashboard (Widgets)
|
||||
- Nach der Anmeldung erscheinen die persönlichen **Widgets** (Kennzahlen, Tabellen, Hinweise).
|
||||
- Widgets werden aus der Datenbank gespeist; welche angezeigt werden, hängt an Ihrem Benutzerkonto.
|
||||
|
||||
---
|
||||
|
||||
## 3. Serviceaufträge (Requests)
|
||||
Serviceaufträge kommen aus dem MFR-ERP-System und werden regelmäßig automatisch synchronisiert.
|
||||
|
||||
**Typische Schritte:**
|
||||
1. **Liste** öffnen (nach Datum oder Suche).
|
||||
2. Auftrag öffnen → Details, Positionen und ggf. bereits vorhandene Rechnungen ansehen.
|
||||
3. **Rechnung vorbereiten** (`iget`/`sprep`): Positionen werden in eine Rechnung übernommen und als Vorschau (PDF) angezeigt.
|
||||
4. Bei Bedarf einzelne Aufträge **aus-/einblenden**.
|
||||
|
||||
---
|
||||
|
||||
## 4. Rechnungen (Invoices)
|
||||
|
||||
### Erstellen / Bearbeiten
|
||||
1. Aus einem Serviceauftrag eine Rechnung **vorbereiten** → Vorschau prüfen.
|
||||
2. **Speichern** (Entwurf) oder weiter **bearbeiten**. Entwürfe tragen ein Wasserzeichen.
|
||||
|
||||
### Finalisieren & Versenden
|
||||
1. **Bestätigen/Finalisieren**: Die Rechnung erhält eine Rechnungsnummer, das PDF wird erzeugt und gespeichert.
|
||||
2. Ist eine E-Mail-Adresse hinterlegt, wird die Rechnung **automatisch als PDF-Anhang** per E-Mail versendet.
|
||||
3. **Erneut senden** ist jederzeit möglich.
|
||||
|
||||
> **Hinweis Versand:** Der E-Mail-/SMS-Versand läuft über die ProcessWeb-Mailer-API
|
||||
> und ist über `Fuchs:Mailer:Enabled` geschaltet. Ist er deaktiviert, wird der
|
||||
> Versand nur protokolliert (kein echter Versand).
|
||||
|
||||
### Weitere Aktionen
|
||||
- **Bezahlt / Unbezahlt** markieren.
|
||||
- **Storno** oder **Gutschrift** erzeugen (einfach, als Kopie oder als Gutschrift).
|
||||
- **Zahlungen** und **Positionen** zu einer Rechnung einsehen.
|
||||
- **Rechnungs-PDF** anzeigen/herunterladen (gespeichertes Dokument oder neu erzeugt).
|
||||
|
||||
### Was steht auf der Rechnung
|
||||
Das PDF enthält Positionen, Netto/MwSt./Brutto, den **GiroCode (QR zur Überweisung)**
|
||||
sowie die gesetzlich relevanten Hinweise (u. a. §13b bzw. §35a-Lohnkostenhinweis,
|
||||
§14-Aufbewahrung, §48-Freistellungsbescheinigung, Steuernummer/USt-ID).
|
||||
|
||||
---
|
||||
|
||||
## 5. Zahlungserinnerungen (Reminders)
|
||||
1. Zu einer offenen Rechnung eine **Erinnerung vorbereiten** (Typ/Stufe wählen) → Vorschau.
|
||||
2. **Finalisieren**: PDF wird erzeugt; bei hinterlegter E-Mail erfolgt der Versand
|
||||
(Erinnerungs-PDF, ggf. inkl. Rechnungskopie, als Anhang).
|
||||
3. **Erneut senden** und **Erinnerungen nachschlagen** sind möglich.
|
||||
|
||||
---
|
||||
|
||||
## 6. Banking (Kontoumsätze)
|
||||
|
||||
### Umsätze importieren
|
||||
1. Banking → **Kontobericht hochladen**.
|
||||
2. Datei(en) wählen. Es werden **beide Formate** akzeptiert:
|
||||
- **MT940** (SWIFT-Text: `.sta`, `.mt940`, `.txt`)
|
||||
- **CAMT** (ISO 20022 XML: `.xml`, `.camt` — camt.052/053/054)
|
||||
3. Das System erkennt das Format automatisch, liest die Buchungen ein und führt sie
|
||||
in die Kontoumsätze über.
|
||||
|
||||
### Umsätze zuordnen
|
||||
- **Fragliche Überweisungen** anzeigen und prüfen.
|
||||
- Eine Transaktion einer **Rechnung zuordnen** (`ati`) oder als **erledigt** markieren (`smd`).
|
||||
- Per Rechnungsnummer nach passenden Rechnungen suchen (`vfi`).
|
||||
|
||||
---
|
||||
|
||||
## 7. DATEV-Export
|
||||
- **DATEV-Übersicht** für einen Stichtag/Zeitraum anzeigen (Dateien, Rechnungen).
|
||||
- **DATEV-ZIP** herunterladen — optional inkl. der Beleg-PDFs.
|
||||
|
||||
---
|
||||
|
||||
## 8. Berichte (Reports)
|
||||
1. **Katalog** öffnen — Liste aller verfügbaren Berichte mit Parametern.
|
||||
2. Bericht auswählen, Parameter setzen, ausführen:
|
||||
- als **HTML-Seite** (mit optionaler automatischer Aktualisierung),
|
||||
- als **HTML-Inhalt** (eingebettet),
|
||||
- oder als **Diagramm (PNG)**.
|
||||
|
||||
---
|
||||
|
||||
## 9. MFR-Synchronisation (Hintergrund)
|
||||
- Stammdaten (Firmen, Kontakte, Serviceaufträge, Rechnungen, Belege …) werden vom
|
||||
**Fuchs_DataService** regelmäßig aus dem MFR-ERP abgeglichen.
|
||||
- Administrator:innen können eine **Aktualisierung anstoßen** (`mfr_update`) bzw. die
|
||||
Verknüpfung einzelner Datensätze zurücksetzen.
|
||||
|
||||
---
|
||||
|
||||
## 10. Hilfe & Support
|
||||
- Bei Versandproblemen: prüfen, ob der Mailer aktiviert ist und ob eine gültige
|
||||
E-Mail-/Mobilnummer hinterlegt ist.
|
||||
- Technische Fehler werden protokolliert (Logging/OpenTelemetry); bitte mit
|
||||
Uhrzeit und betroffener Aktion an die IT melden:
|
||||
[info@processweb.de](mailto:info@processweb.de).
|
||||
Reference in New Issue
Block a user