Refactor/structured logging

.editorconfig

@@ -71,6 +71,20 @@ dotnet_style_readonly_field = true:suggestion
 # Unused usings flagged (kept as warning so analyzers surface them)
 dotnet_diagnostic.IDE0005.severity = warning
 
+# --- Logging (see docs/logging.md) ------------------------------------------
+
+# CA2254: the logging message template must be a compile-time constant. An interpolated or
+# concatenated template produces a distinct template per call, which destroys grouping in the
+# log backend and defeats structured querying. Error: there are zero violations today, so this
+# is a ratchet rather than a backlog.
+dotnet_diagnostic.CA2254.severity = error
+
+# CA1848: prefer the LoggerMessage source generator over the ILogger.LogX extension methods.
+# Suggestion rather than warning: it is required on hot paths and on anything carrying
+# classified data (redaction depends on it), but forcing it on every one of the ~250 remaining
+# call sites would be churn without benefit.
+dotnet_diagnostic.CA1848.severity = suggestion
+
 # --- Naming conventions -----------------------------------------------------
 
 # Interfaces start with I

.github/workflows/release-deploy.yml

@@ -151,28 +151,36 @@ jobs:
           ORDERING_WORKER_SECRET: ${{ secrets.ORDERING_WORKER_SECRET }}
           NOTIFICATION_WORKER_SECRET: ${{ secrets.NOTIFICATION_WORKER_SECRET }}
           PAYMENT_WORKER_SECRET: ${{ secrets.PAYMENT_WORKER_SECRET }}
+          LOGGING_REDACTION_HMAC_KEY: ${{ secrets.LOGGING_REDACTION_HMAC_KEY }}
         run: |
           azd env new "$AZURE_ENV_NAME" \
             --location "$AZURE_LOCATION" \
             --subscription "$AZURE_SUBSCRIPTION_ID"
           azd env set AZURE_RESOURCE_GROUP "$AZURE_RESOURCE_GROUP"
-          # Seed the infra parameters azd would otherwise prompt for. The 4 client
+          # Seed the infra parameters azd would otherwise prompt for. The client
           # secrets come from GitHub secrets (ephemeral, masked in logs); the two
           # non-secret parameters are fixed for DEV. Underscore key form matches azd.
+          #
+          # logging_redaction_hmac_key must stay STABLE across deployments of the same
+          # environment: rotating it re-hashes every classified log value, so records
+          # written before the rotation no longer group with records written after
+          # (see docs/logging.md § PII). Rotate deliberately, not per release.
           jq -n \
             --arg oidc "https://ordersphere-dev.eu.auth0.com/" \
             --arg bypass "true" \
             --arg bff "$BFF_CLIENT_SECRET" \
             --arg ordering "$ORDERING_WORKER_SECRET" \
             --arg notification "$NOTIFICATION_WORKER_SECRET" \
             --arg payment "$PAYMENT_WORKER_SECRET" \
+            --arg hmac "$LOGGING_REDACTION_HMAC_KEY" \
             '{infra:{parameters:{
               oidc_authority:$oidc,
               payment_bypass_providers:$bypass,
               bff_client_secret:$bff,
               ordering_worker_secret:$ordering,
               notification_worker_secret:$notification,
-              payment_worker_secret:$payment
+              payment_worker_secret:$payment,
+              logging_redaction_hmac_key:$hmac
             }}}' > ".azure/$AZURE_ENV_NAME/config.json"
 
       - name: Provision infrastructure

.mcp.json

@@ -2,15 +2,31 @@
   "mcpServers": {
     "aspire": {
       "command": "aspire",
-      "args": ["agent", "mcp"]
+      "args": [
+        "agent",
+        "mcp"
+      ]
     },
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest"]
+      "args": [
+        "@playwright/mcp@latest"
+      ]
     },
     "postgres": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres", "${ORDERSPHERE_PG_READONLY}"]
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-postgres",
+        "${ORDERSPHERE_PG_READONLY}"
+      ]
+    },
+    "seq": {
+      "command": "seqcli",
+      "args": [
+        "mcp",
+        "run"
+      ]
     }
   }
-}
+}

CLAUDE.md

@@ -34,6 +34,12 @@ These are the rules that are not derivable by reading existing code. For everyth
 - Soft-delete is enforced by a global query filter, not per-query: every `AuditableEntity` gets `builder.HasQueryFilter(x => !x.IsDeleted)` in its EF configuration, so queries inherit the filter automatically — do not repeat `!x.IsDeleted` in handlers. Use `IgnoreQueryFilters()` only where deleted rows must be read deliberately.
 - All I/O is `async`/`await`. No `.Result`, no `.Wait()`, no `.GetAwaiter().GetResult()`.
 - Nullable reference types are enabled. Treat warnings as real.
+- Log messages use constant templates with named placeholders — never interpolation or concatenation. `tenant_id`, `correlation_id`, `user_id` and `trace_id` are added by enrichment in ServiceDefaults; do not pass them as template arguments. A `Result` failure logs at `Warning`, not `Error`.
+- Personal data may only be logged through a `[LoggerMessage]` method whose parameter carries a classification attribute (`[DirectPii]`, `[PseudonymousId]`, `[FreeText]`) — redaction does not apply to plain `logger.LogX(...)` calls.
+
+## Logging
+
+Log schema, field names, level policy, EventId ranges and PII enforcement live in [`docs/logging.md`](docs/logging.md). Read it before adding a log statement in a hot path or one that touches customer data.
 
 ## UI and styling
 

Directory.Build.props

@@ -1,4 +1,4 @@
-<Project>
+<Project>
 
   <!--
     Solution-wide compiler and analysis settings.
@@ -26,7 +26,12 @@
       directive. Emitted only by the Razor source generator for .razor-derived
       code; not actionable in hand-written source. Suppressed solution-wide.
     -->
-    <NoWarn>$(NoWarn);CS8669</NoWarn>
+    <!--
+      EXTEXP0002: HmacRedactor is marked experimental in
+      Microsoft.Extensions.Compliance.Redaction. It is the deliberate choice for
+      PII in logs (correlatable without plaintext) - see docs/logging.md.
+    -->
+    <NoWarn>$(NoWarn);CS8669;EXTEXP0002</NoWarn>
   </PropertyGroup>
 
   <!-- Solution-weite Produktversion. Einziger Pflegeort; gilt für alle Projekte.

Directory.Packages.props

@@ -31,6 +31,14 @@
     <PackageVersion Include="AspNetCore.HealthChecks.NpgSql" Version="9.0.0" />
     <PackageVersion Include="FluentAssertions" Version="8.10.0" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery.Yarp" Version="10.9.0" />
+    <!-- Structured logging: enrichment (ILogEnricher/IStaticLogEnricher) and the
+         ExtendedLoggerFactory that carries enrichment tags into the OpenTelemetry
+         logger provider. See docs/logging.md. -->
+    <PackageVersion Include="Microsoft.Extensions.Telemetry" Version="10.9.0" />
+    <PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="10.9.0" />
+    <!-- Declarative PII redaction for classified [LoggerMessage] parameters. -->
+    <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.9.0" />
+    <PackageVersion Include="Microsoft.Extensions.Compliance.Redaction" Version="10.9.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.9.0" />
     <PackageVersion Include="ModelContextProtocol" Version="2.2.0" />
     <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="2.2.0" />
@@ -46,6 +54,11 @@
     <PackageVersion Include="Aspire.Hosting.Azure.ServiceBus" Version="13.5.3" />
     <PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="13.5.3" />
     <PackageVersion Include="Aspire.Npgsql.EntityFrameworkCore.PostgreSQL" Version="13.5.3" />
+    <!-- Seq: local-development log and trace viewer with a query language over the
+         enrichment properties. Container resource in the AppHost (run mode only),
+         additive OTLP exporter in ServiceDefaults. See docs/logging.md. -->
+    <PackageVersion Include="Aspire.Hosting.Seq" Version="13.5.3" />
+    <PackageVersion Include="Aspire.Seq" Version="13.5.3" />
     <PackageVersion Include="Azure.Communication.Email" Version="1.1.0" />
     <PackageVersion Include="QuestPDF" Version="2026.8.0" />
     <PackageVersion Include="Stripe.net" Version="52.4.1" />
@@ -95,6 +108,8 @@
     <PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.11" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.11" />
     <PackageVersion Include="coverlet.collector" Version="10.0.1" />
+    <!-- FakeLogger: lets tests assert on log level, EventId, enrichment tags and redaction. -->
+    <PackageVersion Include="Microsoft.Extensions.Diagnostics.Testing" Version="10.9.0" />
     <PackageVersion Include="ReportGenerator" Version="5.4.4" />
     <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.9.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.9.0" />

aspire.config.json

@@ -0,0 +1,5 @@
+{
+  "appHost": {
+    "path": "src/Hosting/OrderSphere.AppHost/OrderSphere.AppHost.csproj"
+  }
+}

docs/assessments/2026-05-07-v1.md

@@ -1,5 +1,11 @@
 # OrderSphere — Project assessment
 
+> **Correction (2026-09-06).** The observability rows below list Serilog. That was never
+> accurate: OrderSphere has only ever used Microsoft.Extensions.Logging with the
+> OpenTelemetry provider (`git log -S Serilog` returns no commit). See
+> [logging.md](../logging.md) for the actual pipeline.
+
+
 > **⚠️ SUPERSEDED (2026-06-17).** This document assesses the former Blazor Server monolith
 > (`OrderSphere.UI` + ASP.NET Identity, 7 projects), which has since been replaced by an 8-service
 > microservices platform. The bug IDs (B*) and critical issues (K*) below reference files that no

docs/assessments/2026-05-09-v1.md

@@ -1,5 +1,11 @@
 # OrderSphere — Project assessment
 
+> **Correction (2026-09-06).** The observability rows below list Serilog. That was never
+> accurate: OrderSphere has only ever used Microsoft.Extensions.Logging with the
+> OpenTelemetry provider (`git log -S Serilog` returns no commit). See
+> [logging.md](../logging.md) for the actual pipeline.
+
+
 > **⚠️ SUPERSEDED (2026-06-17).** This document assesses the former Blazor Server monolith
 > (`OrderSphere.UI` + ASP.NET Identity, 7 projects), which has since been replaced by an 8-service
 > microservices platform. The bug IDs (B*) and critical issues (K*) below reference files that no