Fuchs_Intranet/.github/copilot-instructions.md

# Copilot Instructions

> ## ⚠️ Instruction Sync
> This file (`.github/copilot-instructions.md`) and the Claude Code instructions
> (`/CLAUDE.md`) are **two views of the same project rules and must stay in sync**.
> Whenever you change one, make the equivalent change in the other in the same
> commit. `CLAUDE.md` may add tool-specific workflow notes, but the shared
> project facts (architecture, coding standards, configuration, libraries,
> secrets, observability) must match.

## Project Overview
- **Fuchs Intranet** is an ASP.NET Core (.NET 10) web application — the intranet IS the entire website, served from `/`.
- Routes: `/{fn?}/{id?}/{code?}` → `IntranetController.Index`; `/do/{fn?}/{id?}/{code?}` → `IntranetController.Do`.
- Project structure (relative to `Fuchs/`):
  - `Controllers/` — `IntranetController` partials (no area)
  - `code/` — business logic, PDF, email, widgets, data models
  - `css/intranet/` — intranet SCSS source files
  - `js/intranet/` — intranet JS source files (modules in `js/intranet/modules/`)
  - `Data/` — static data assets (images for PDF, HTML files)
  - `Views/Intranet/` — Razor views; `Views/Shared/_Layout.cshtml`; `Views/Partials/`

## Coding Standards
- All code must be written in C#.
- Keep files to a limit of 400 (max 600) lines of code to ensure maintainability and readability. Proactively refactor larger files into smaller, focused classes or components as needed.
- Follow standard C# naming conventions (PascalCase for classes and methods, camelCase for variables and parameters).
- Use modern, performance-oriented C# .NET 10 features and best practices, such as async/await for asynchronous programming, LINQ for data manipulation, and dependency injection for better testability and maintainability.

## Configuration
- All application settings live in `Fuchs/appsettings.json` — **do not use `Web.config` or `System.Configuration.ConfigurationManager`**.
- App-specific settings are nested under the `"Fuchs"` key (e.g., `_config["Fuchs:SMS_APIKey"]`).
- Connection strings are stored under the standard `"ConnectionStrings"` key and read via `IConfiguration.GetConnectionString(...)`.
- `FuchsOcmsIntranet.Initialize(configuration)` must be called at app start (in `Program.cs`) before DI registration; `Fuchs_intranet` receives `IConfiguration` via its constructor.
- `appsettings.Development.json` (git-ignored) can override secrets for local development.

## Libraries
- Do not upgrade Spire.PDF beyond version 8.10.5.
- Make use of OCORE libraries where possible, especially for common tasks such as logging, configuration management, and data access.
- Whenever possible, prefer OCORE_web_pdf / OCORE PDF functions for PDF-related tasks over rewriting.
- Do not use OCMS or OCMS_sharp; use only OCORE or OCORE_web.
- For builds failing due to SixLabors.ImageSharp requiring a license (v4.0.0+), check copilot-instructions.md for the SixLabors license key/handling info before downgrading ImageSharp.

## Services & Dependency Injection
- Business logic lives in **DI-registered services** under `Fuchs/Services/` behind interfaces; inject them into `IntranetController` (constructor injection). Do **not** reintroduce static God-classes or pass the whole controller into helpers.
  - `IComService` (email/SMS via ProcessWeb Mailer API, attachments sent inline as base64), `IPdfService` (MigraDoc render), `IInvoiceService`, `IReminderService`, `IReportService` (SQL report engine via `FuchsVisualization`), `IWidgetService`, `IBankingService`, `IMfrClientFactory`.
  - Lifetimes: stateless services (`IPdfService`, `IBankingService`, `IMfrClientFactory`) are singletons; request-scoped DB services (`IInvoiceService`, `IReminderService`, `IReportService`, `IWidgetService`, `IComService`) are scoped. Register in `Program.cs`.
- `FdsInvoiceData` / `FdsReminderData` are **pure data holders** (parse + properties). Loading, persistence and PDF generation belong in the services — never `Task.Run(...).Wait()` sync-over-async.
- Data access stays SQL-first via OCORE helpers (`getSQLDataSet_async`, `setSQLValue_async`) + stored procedures; no EF Core.

## MFR ERP integration
- `MFR_RESTClient` talks to the **mfr (Mobile Field Report)** ERP over REST/OData. Its contract (base URLs, auth, OData conventions, pagination, error/retry, deep-create + document-upload) is documented in **`MFR_RESTClient/Docs/mfr_interface_description.md`** — **read it before changing the client**.
- The client uses HTTP Basic auth, a configurable timeout, and retries idempotent GETs on transient errors (429/5xx, network/timeout) with backoff. Create clients via `IMfrClientFactory` (don't `new` them). The legacy VB project files have been removed; the active project is `MFR_RESTClient.csproj`.

## Database
- The SQL schema source of truth is the **`Fuchs_Database`** SSDT project. The backend is SQL-first (stored procedures, table types like `fds__tt__bankingtransactions`, functions via OCORE helpers — no EF Core).
- When you change a stored proc name/params or a table type, update **both** the SSDT project and the calling C# in the same change. Verify every `[dbo].[…]` the backend calls actually exists in `Fuchs_Database`.

## Bank statement parsing (MT940 + CAMT)
- Two parsers feed the same banking pipeline: the external `MT940Parser` (SWIFT text) and the in-repo **`CAMTParser`** project (ISO 20022 camt.052/053/054 XML).
- `BankingService.ParseToDatatable` **auto-detects** the format (XML → CAMT, else MT940) and maps both into the `fds__tt__bankingtransactions` schema. The `bam/up` handler and the frontend file picker accept both (`.sta/.mt940/.txt` and `.xml/.camt`).
- `CAMTParser` is namespace-agnostic (matches elements by local name) so it handles every camt schema version. Keep both parsers' column mappings aligned when changing the banking schema.

## Observability
- Use **OpenTelemetry**. The app's instrumentation is centralised in `Fuchs/Observability/FuchsTelemetry.cs` (one `ActivitySource` + one `Meter`).
- When adding a meaningful operation: start an activity (`FuchsTelemetry.StartActivity(...)`), record the relevant counter/histogram, and log entry/result/timing/errors via the injected `ILogger<T>`. Prefer structured logging (named placeholders), never string interpolation in log messages.
- Tracing/metrics are always collected; OTLP export is opt-in via `Fuchs:Telemetry:OtlpEndpoint`. Don't add exporters that fail hard when no collector is present.

## Testing
- xUnit in `Fuchs.Tests`. For every service/handler change add tests covering **both** an intentionally succeeding and an intentionally failing path where feasible (use stubs/mocks; the test project has `InternalsVisibleTo`). DB-bound paths that can't be unit-tested should at least have their pure logic covered.

## Azure Key Vault — Secret Naming
- Secret names must satisfy the pattern `^[0-9a-zA-Z-]+$` (alphanumerics and hyphens only; no underscores, dots, or spaces).
- Hierarchy levels are separated by `--` (double hyphen), which maps to `:` in `IConfiguration`.
- Underscores within a name segment are encoded as a single `-` in Key Vault and decoded back to `_` when the key is reconstructed.
- The app prefix `fuchs` is prepended to every secret name.
- Format: `{appname}--{Section}--{key-with-hyphens-for-underscores}`
- Examples:
  - `fuchs--ConnectionStrings--ocms-ConnectionString`  →  `ConnectionStrings:ocms_ConnectionString`
  - `fuchs--Fuchs--SMS-APIKey`                         →  `Fuchs:SMS_APIKey`
  - `fuchs--Fuchs--Email--Main--password`              →  `Fuchs:Email:Main:password`
- When adding new secrets: replace every `_` in the original config key with `-` for the Key Vault name, and add the entry to `ManagedSecretKeys` in `appsettings.json` (using the same hyphenated form without the `fuchs--` prefix).