plan: add Migration-InspectFlow.md (dep swap + Flyway baseline + rollback)

2026-06-24 14:32:48 +02:00
parent e6ba33b769
commit 35cb5e76c3
1 changed files with 563 additions and 0 deletions
@@ -0,0 +1,563 @@
 # Migration Guide: InspectFlow → plate-auth
 **Status:** Draft v1
 **Date:** 2026-06-24
 **Owner:** Patrick
 **Audience:** InspectFlow maintainer performing the dependency swap from in-tree auth code to `plate-auth-starter`
 **Target plate-auth version:** `0.1.0` (after `0.0.1` validation tag)
 > This guide is **InspectFlow-specific**. For greenfield consumers, see [Integration-Guide.md](Integration-Guide.md).
 ---
 ## 1. What this migration does
 Replaces InspectFlow's hand-rolled auth code with a dependency on `plate-auth-starter` + `@platesoft/auth`. After this migration:
 - ~25 backend classes under `de.platesoft.inspectflow.{security,filter,service,controller,entity,repository,dto,enums}` are **deleted** and become a single Maven dependency.
 - ~5–8 frontend files under `frontend/{auth.ts, app/api/[...path]/route.ts, app/api/auth/[...nextauth]/route.ts, lib/hmac.ts}` are **deleted** and become a single npm dependency + a 5-line `auth.ts`.
 - Flyway migrations `V26..V31` are **kept** but marked as baseline rows in the new `flyway_schema_history_auth` table so plate-auth's `V1..V5` are not re-applied.
 - InspectFlow keeps `Company` entity + `OrgValidator` SPI implementation + onboarding logic — **T3 stays in-house**.
 **Goal:** zero behavioral change for end-users. All E2E tests stay green. ([Sprint-0-Testplan.md § 6](Sprint-0-Testplan.md))
 ---
 ## 2. Prerequisites
 Before starting:
 - [ ] InspectFlow on **Spring Boot 4.1.0** (bump from 4.0.7 if needed — Sprint 14.7 prerequisite, see [Open-Questions.md](Open-Questions.md) Q08)
 - [ ] plate-auth `0.0.1` validation tag has been published and you can resolve it from Gitea
 - [ ] All Sprint 14.6 work merged to `main` (clean baseline)
 - [ ] Database backup taken
 - [ ] Sparkboard has **already** consumed plate-auth `0.0.1` successfully (proves the library works against a real consumer)
 - [ ] Feature branch: `feature/plate-auth-migration`
 If any of these is false, **stop** and resolve first.
 ---
 ## 3. Migration overview
 ```mermaid
 flowchart LR
  S0[Sprint 14.6 baseline] --> A[Step A: Add deps]
  A --> B[Step B: Delete moved backend classes]
  B --> C[Step C: Rename config keys]
  C --> D[Step D: Add SPI implementations]
  D --> E[Step E: Flyway baseline rows]
  E --> F[Step F: Frontend swap]
  F --> G[Step G: Run E2E suite]
  G -->|green| H[Step H: Merge + delete dead code]
  G -->|red| R[Rollback]
 ```
 Estimated effort: **1–2 days** for an experienced maintainer assuming the library works as advertised. Most time is verification, not coding.
 ---
 ## 4. Step A — Add dependencies
 ### 4.1 Backend `pom.xml`
 ```xml
 <dependency>
    <groupId>de.platesoft</groupId>
    <artifactId>plate-auth-starter</artifactId>
    <version>0.1.0</version>
 </dependency>
 ```
 Add Gitea Maven repo + credentials if not already present (see [Integration-Guide.md § 3.1](Integration-Guide.md)).
 ### 4.2 Frontend `package.json`
 ```bash
 cd frontend
 pnpm add @platesoft/auth@0.1.0
 ```
 `.npmrc` must contain the `@platesoft:` scope mapping.
 ### 4.3 Verify build still passes
 ```bash
 cd backend && mvn clean compile
 cd frontend && pnpm install
 ```
 No code changes yet — both halves should still build cleanly with the new deps idle alongside the existing in-tree code.
 ---
 ## 5. Step B — Delete moved backend classes
 These classes are now provided by `plate-auth-starter`. Delete the InspectFlow-local copy after verifying the package and class name match exactly.
 ### 5.1 Classes to delete
 | InspectFlow path | Replaced by |
 |------------------|-------------|
 | [`backend/src/main/java/de/platesoft/inspectflow/service/JwtService.java`](backend/src/main/java/de/platesoft/inspectflow/service/JwtService.java:1) | `de.platesoft.auth.service.JwtService` |
 | [`backend/src/main/java/de/platesoft/inspectflow/filter/JwtAuthenticationFilter.java`](backend/src/main/java/de/platesoft/inspectflow/filter/JwtAuthenticationFilter.java:1) | `de.platesoft.auth.filter.JwtAuthenticationFilter` |
 | [`backend/src/main/java/de/platesoft/inspectflow/config/SecurityConfig.java`](backend/src/main/java/de/platesoft/inspectflow/config/SecurityConfig.java:1) | Auto-config in `PlateAuthAutoConfiguration` (see § 5.4 below) |
 | `…/inspectflow/service/ExchangeService.java` | `de.platesoft.auth.service.ExchangeService` |
 | `…/inspectflow/service/HmacEnvelope.java` | `de.platesoft.auth.crypto.HmacEnvelope` |
 | `…/inspectflow/service/MembershipService.java` | `de.platesoft.auth.service.MembershipService` |
 | `…/inspectflow/service/InvitationService.java` | `de.platesoft.auth.service.InvitationService` |
 | `…/inspectflow/service/AccessRequestService.java` | `de.platesoft.auth.service.AccessRequestService` |
 | `…/inspectflow/service/AuthService.java` (login/signup/reset) | `de.platesoft.auth.service.AuthService` |
 | `…/inspectflow/controller/AuthController.java` | `de.platesoft.auth.controller.AuthController` |
 | `…/inspectflow/controller/MembershipController.java` | `de.platesoft.auth.controller.MembershipController` |
 | `…/inspectflow/controller/InvitationController.java` | `de.platesoft.auth.controller.InvitationController` |
 | `…/inspectflow/controller/AccessRequestController.java` | `de.platesoft.auth.controller.AccessRequestController` |
 | `…/inspectflow/controller/AdminAuditController.java` | `de.platesoft.auth.controller.AdminAuditController` |
 | `…/inspectflow/entity/User.java` | `de.platesoft.auth.entity.User` |
 | `…/inspectflow/entity/UserIdentity.java` | `de.platesoft.auth.entity.UserIdentity` |
 | `…/inspectflow/entity/Membership.java` | `de.platesoft.auth.entity.Membership` (with polymorphic FK — see § 6.3) |
 | `…/inspectflow/entity/Invitation.java` | `de.platesoft.auth.entity.Invitation` |
 | `…/inspectflow/entity/AccessRequest.java` | `de.platesoft.auth.entity.AccessRequest` |
 | `…/inspectflow/entity/LoginEvent.java` | `de.platesoft.auth.entity.LoginEvent` |
 | `…/inspectflow/repository/UserRepository.java` | `de.platesoft.auth.repository.UserRepository` |
 | `…/inspectflow/repository/MembershipRepository.java` | `de.platesoft.auth.repository.MembershipRepository` |
 | `…/inspectflow/repository/InvitationRepository.java` | `de.platesoft.auth.repository.InvitationRepository` |
 | `…/inspectflow/repository/AccessRequestRepository.java` | `de.platesoft.auth.repository.AccessRequestRepository` |
 | `…/inspectflow/repository/LoginEventRepository.java` | `de.platesoft.auth.repository.LoginEventRepository` |
 | `…/inspectflow/dto/...` (auth-related) | `de.platesoft.auth.dto.*` |
 ### 5.2 Classes to KEEP (T3 — InspectFlow-specific)
 These stay in InspectFlow because they encode the Company domain or onboarding logic:
 | Path | Reason |
 |------|--------|
 | `de.platesoft.inspectflow.entity.Company` | Concrete org table — InspectFlow's domain |
 | `de.platesoft.inspectflow.repository.CompanyRepository` | Same |
 | `de.platesoft.inspectflow.service.CompanyService` | Same |
 | `de.platesoft.inspectflow.service.OrgContextResolver` | Adapter — refactor to implement plate-auth's `OrgValidator` SPI |
 | `de.platesoft.inspectflow.service.OnboardingService` | App-specific onboarding (create default machines, etc.) |
 ### 5.3 Find-and-fix imports
 After deleting the classes in § 5.1, the rest of InspectFlow that references them (controllers, services that aren't auth-related) will fail to compile. Rewrite imports:
 ```bash
 # Find all consumers of the deleted packages
 cd backend
 grep -rln "de.platesoft.inspectflow.service.JwtService" src/main/java/
 grep -rln "de.platesoft.inspectflow.entity.User" src/main/java/
 # … repeat per deleted class
 # Replace package prefix
 find src/main/java -name "*.java" -exec sed -i '' \
  -e 's|de.platesoft.inspectflow.service.JwtService|de.platesoft.auth.service.JwtService|g' \
  -e 's|de.platesoft.inspectflow.entity.User|de.platesoft.auth.entity.User|g' \
  -e 's|de.platesoft.inspectflow.entity.Membership|de.platesoft.auth.entity.Membership|g' \
  {} +
 ```
 > **Take small steps.** Replace one package at a time and recompile. Big-bang sed will leave you with a sea of red.
 ### 5.4 SecurityConfig
 The starter ships its own `SecurityFilterChain` bean named `plateAuthSecurityChain`. InspectFlow's current [`SecurityConfig.java`](backend/src/main/java/de/platesoft/inspectflow/config/SecurityConfig.java:21) declares its own beans for `passwordEncoder`, `authenticationManager`, and a `filterChain`. Three of these are auto-provided by the starter:
 - `passwordEncoder` → `PlateAuthAutoConfiguration` provides `BCryptPasswordEncoder` with cost 10. Delete InspectFlow's.
 - `authenticationManager` → same. Delete InspectFlow's.
 - `filterChain` → starter's `plateAuthSecurityChain` covers `/auth/**` + JWT for the rest. **Keep** an InspectFlow-specific chain for paths that need custom rules (e.g. `/api/admin/**` requires `hasRole('ADMIN')`).
 ```java
 // InspectFlow keeps a focused chain:
@Bean
@Order(0)  // before plateAuthSecurityChain
 public SecurityFilterChain inspectflowAdminChain(HttpSecurity http) throws Exception {
    return http
        .securityMatcher("/api/admin/**")
        .authorizeHttpRequests(a -> a.anyRequest().hasRole("ADMIN"))
        .csrf(c -> c.disable())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .build();
 }
 ```
 ---
 ## 6. Step C — Rename config keys
 InspectFlow has historically scattered auth config across `inspectflow.*`, `jwt.*`, and `nextauth.*`. plate-auth consolidates everything under `plate.auth.*`.
 ### 6.1 Backend: `application.yml`
 Before:
 ```yaml
 jwt:
  secret: ${JWT_SECRET}
  access-expiration-minutes: 15
  refresh-expiration-days: 30
 nextauth:
  exchange-secret: ${EXCHANGE_SECRET}
  exchange-max-age-seconds: 60
 inspectflow:
  registration-enabled: false
  cors:
    allowed-origins: [...]
 ```
 After:
 ```yaml
 plate:
  auth:
    jwt:
      secret: ${JWT_SECRET}
      access-expiration: PT15M
      refresh-expiration: P30D
      issuer: inspectflow
    exchange:
      secret: ${EXCHANGE_SECRET}
      max-age: PT60S
      nonce-ttl: PT5M
    registration:
      enabled: false
    cors:
      allowed-origins: [...]
    providers:
      google:
        enabled: true
        client-id: ${GOOGLE_CLIENT_ID}
        client-secret: ${GOOGLE_CLIENT_SECRET}
 ```
 **Format changes:**
 - Numeric `*-minutes` / `*-seconds` / `*-days` → ISO-8601 `Duration` format (`PT15M`, `PT60S`, `P30D`). Spring Boot parses both `15m` and `PT15M`, but the starter validates the ISO form.
 ### 6.2 Frontend: `.env.local` / `.env.production`
 | Old | New |
 |-----|-----|
 | `JWT_SECRET` | (unused — backend only now) |
 | `EXCHANGE_SECRET` | `PLATE_AUTH_EXCHANGE_SECRET` |
 | `BACKEND_URL` | `PLATE_AUTH_BACKEND_URL` |
 | `NEXTAUTH_SECRET` | `NEXTAUTH_SECRET` (unchanged) |
 | `NEXTAUTH_URL` | `NEXTAUTH_URL` (unchanged) |
 | `GOOGLE_CLIENT_ID` | `GOOGLE_CLIENT_ID` (unchanged) |
 | `GOOGLE_CLIENT_SECRET` | `GOOGLE_CLIENT_SECRET` (unchanged) |
 Update `docker-compose.yml`, TrueNAS config, `.env.example`, and `.env.prod.example`.
 ### 6.3 Membership entity column changes
 Old InspectFlow `Membership`:
 ```java
@Entity
 public class Membership {
    @ManyToOne private User user;
    @ManyToOne private Company company;   // ← direct FK
    private Role role;
 }
 ```
 New plate-auth `Membership`:
 ```java
@Entity
 public class Membership {
    @ManyToOne private User user;
    private String orgType;               // "COMPANY"
    private Long orgId;                   // company.id
    private Role role;
 }
 ```
 **Migration:** the existing `memberships.company_id` column must be rewritten to `(org_type='COMPANY', org_id=company_id)`. Handled by the Flyway data-migration step in § 7.3.
 ---
 ## 7. Step D — Add SPI implementations
 InspectFlow plugs back into plate-auth via SPI beans. Add a new config class:
 ```java
 // backend/src/main/java/de/platesoft/inspectflow/auth/PlateAuthBindings.java
@Configuration
 public class PlateAuthBindings {
    @Bean
    public OrgValidator orgValidator(CompanyRepository companies) {
        return (orgType, orgId) ->
            "COMPANY".equals(orgType) && companies.existsById(orgId);
    }
    @Bean
    public OrgDisplayNameResolver orgDisplayNameResolver(CompanyRepository companies) {
        return (orgType, orgId) -> companies.findById(orgId)
            .map(Company::getName)
            .orElse("Unbekannt");
    }
    @Bean
    public InvitationMailer invitationMailer(InspectFlowMailService mail) {
        return mail::sendInvitation;  // delegate to existing mailer
    }
    @Bean
    public AccessRequestMailer accessRequestMailer(InspectFlowMailService mail) {
        return mail::sendAccessRequestNotification;
    }
    @Bean
    public OnboardingHook onboardingHook(OnboardingService onboarding) {
        return onboarding::onUserCreated;  // delegate to existing onboarding
    }
 }
 ```
 This replaces all five default SPI beans. The starter logs "User-provided OrgValidator detected, default disabled" at INFO on boot — verify this in your first run.
 ---
 ## 8. Step E — Flyway baseline rows
 InspectFlow's existing `flyway_schema_history` contains rows for `V26..V31` (your existing auth migrations). plate-auth ships its own migrations `V1..V5` and runs them against `flyway_schema_history_auth` (a separate table). The schema already has the tables — running `V1..V5` would fail.
 ### 8.1 Migration approach
 Add a new InspectFlow-local migration `V32__C_seed_plate_auth_history.sql`:
 ```sql
 -- Pre-populate flyway_schema_history_auth so plate-auth Flyway sees the tables as already migrated.
 -- The schema was created by InspectFlow's V26..V31; plate-auth's V1..V5 would otherwise re-apply them.
 CREATE TABLE IF NOT EXISTS flyway_schema_history_auth (
    installed_rank int NOT NULL,
    version varchar(50),
    description varchar(200) NOT NULL,
    type varchar(20) NOT NULL,
    script varchar(1000) NOT NULL,
    checksum int,
    installed_by varchar(100) NOT NULL,
    installed_on timestamp NOT NULL DEFAULT now(),
    execution_time int NOT NULL,
    success boolean NOT NULL,
    PRIMARY KEY (installed_rank)
 );
 INSERT INTO flyway_schema_history_auth
  (installed_rank, version, description, type, script, checksum, installed_by, execution_time, success)
 VALUES
  (1, '1', 'Create users',         'SQL', 'V1__C_create_users.sql',         NULL, 'inspectflow-migration', 0, true),
  (2, '2', 'Create user_identities','SQL', 'V2__C_create_user_identities.sql', NULL, 'inspectflow-migration', 0, true),
  (3, '3', 'Create memberships',   'SQL', 'V3__C_create_memberships.sql',   NULL, 'inspectflow-migration', 0, true),
  (4, '4', 'Create invitations',   'SQL', 'V4__C_create_invitations.sql',   NULL, 'inspectflow-migration', 0, true),
  (5, '5', 'Create login_events',  'SQL', 'V5__C_create_login_events.sql',  NULL, 'inspectflow-migration', 0, true)
 ON CONFLICT DO NOTHING;
 ```
 > **Checksum caveat.** Setting `checksum = NULL` makes Flyway skip checksum validation. If you want strict mode, run plate-auth on a scratch DB once, copy the checksums from its `flyway_schema_history_auth`, and paste them here.
 ### 8.2 Data migration: memberships.company_id → (org_type, org_id)
 Same migration file or separate `V33__C_rewrite_memberships_to_polymorphic.sql`:
 ```sql
 -- Add new columns
 ALTER TABLE memberships ADD COLUMN IF NOT EXISTS org_type varchar(64);
 ALTER TABLE memberships ADD COLUMN IF NOT EXISTS org_id bigint;
 -- Backfill from existing company_id
 UPDATE memberships SET org_type = 'COMPANY', org_id = company_id WHERE company_id IS NOT NULL;
 -- Index + non-null constraint
 CREATE INDEX IF NOT EXISTS idx_memberships_org ON memberships(org_type, org_id);
 ALTER TABLE memberships ALTER COLUMN org_type SET NOT NULL;
 ALTER TABLE memberships ALTER COLUMN org_id SET NOT NULL;
 -- Drop the old FK column (after verification!)
 -- ALTER TABLE memberships DROP CONSTRAINT memberships_company_id_fkey;
 -- ALTER TABLE memberships DROP COLUMN company_id;
 ```
 > **Caution.** Do **not** drop `company_id` in the same migration. Keep it as a shadow column until the next minor release and verify no code still reads it.
 ---
 ## 9. Step F — Frontend swap
 ### 9.1 Delete files
 - [`frontend/auth.ts`](frontend/auth.ts:1) → rewrite (5 lines, see § 9.3)
 - `frontend/app/api/auth/[...nextauth]/route.ts` → keep, no change needed
 - `frontend/app/api/[...path]/route.ts` → rewrite (3 lines, see § 9.4)
 - `frontend/lib/hmac.ts` (if exists) → delete; replaced by `@platesoft/auth/edge`
 - `frontend/lib/auth-config.ts` (if exists) → delete; replaced by `createAuthConfig` factory
 ### 9.2 Keep files
 - `frontend/middleware.ts` — InspectFlow keeps its own (custom redirect logic for unauth users)
 - `frontend/components/login-form.tsx` etc. if you have custom UI — leave them, ignore `@platesoft/auth/react`
 ### 9.3 New `frontend/auth.ts`
 ```typescript
 import { createAuthConfig } from "@platesoft/auth/server";
 import NextAuth from "next-auth";
 export const { handlers, auth, signIn, signOut } = NextAuth(
  createAuthConfig({
    backendUrl: process.env.PLATE_AUTH_BACKEND_URL!,
    exchangeSecret: process.env.PLATE_AUTH_EXCHANGE_SECRET!,
    nextAuthSecret: process.env.NEXTAUTH_SECRET!,
    providers: {
      google: {
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      },
    },
    pages: {
      signIn: "/login",
    },
  })
 );
 ```
 ### 9.4 New `frontend/app/api/[...path]/route.ts`
 ```typescript
 import { createProxyHandlers } from "@platesoft/auth/edge";
 export const runtime = "edge";
 export const { GET, POST, PUT, PATCH, DELETE } = createProxyHandlers({
  backendUrl: process.env.PLATE_AUTH_BACKEND_URL!,
  exchangeSecret: process.env.PLATE_AUTH_EXCHANGE_SECRET!,
 });
 ```
 That's it. Anything else InspectFlow needs (custom error pages, custom callbacks) is wired into NextAuth options that `createAuthConfig` exposes as overridable.
 ---
 ## 10. Step G — Run the E2E suite
 ```bash
 cd frontend
 pnpm exec playwright install --with-deps    # if not already
 pnpm exec playwright test
 ```
 All 30+ scenarios in [`frontend/e2e/`](frontend/e2e/) must pass green. The critical ones for this migration:
 - `auth-flow.unauth.spec.ts` — anonymous redirect, login form
 - `companies.spec.ts` — membership reads work
 - `admin-archive.spec.ts`, `admin-timeline.spec.ts`, `admin-migration.spec.ts` — admin role gate
 - `command-palette.spec.ts` — JWT-protected ops
 - Any "login as admin / login as user" setup script in `auth.setup.ts`
 If any test fails, **stop**. Diagnose via:
 1. Check backend logs for `OrgValidator` / SPI warnings.
 2. Check `login_events` table for the failing user.
 3. Diff the failing request between old + new code paths (proxy headers, exchange envelope shape).
 ---
 ## 11. Step H — Merge and clean up
 After all tests pass:
 1. Squash-merge `feature/plate-auth-migration` to `main`.
 2. Tag InspectFlow as `vX.Y+1.0` (minor bump — internal refactor with config breaking change for ops).
 3. Update `docs/` — add a section in [`docs/SPRINT-14-OVERVIEW.md`](docs/SPRINT-14-OVERVIEW.md) noting the carve-out + library version.
 4. **One sprint later**, drop `memberships.company_id` column in a follow-up migration (give yourself time to revert if production reveals issues).
 5. Subscribe to plate-auth `0.2.0` for the v0.2 feature wave (refresh rotation, magic-link, multi-key secrets).
 ---
 ## 12. Rollback procedure
 If the migration goes sideways:
 ### Code rollback
 ```bash
 git checkout main
 git revert feature/plate-auth-migration  # or just deploy the previous tag
 ```
 ### Database rollback
 The data migration in § 8.2 is **additive** (`memberships.org_type`, `org_id` are new columns). The old `company_id` column is preserved. Rolling back the code means the old `Membership` entity reads `company_id` again and ignores the new columns — safe.
 The Flyway baseline rows in `flyway_schema_history_auth` are harmless if the code is reverted — the table simply exists with 5 rows and no consumer.
 ### Secret rollback
 If you have already rotated `PLATE_AUTH_EXCHANGE_SECRET` and `EXCHANGE_SECRET` was different in the old code, restore the old env vars when reverting the code.
 ### Total downtime
 The migration is designed for **zero-downtime deploy**:
 - New columns added before code switch (additive).
 - New code reads new columns; old code reads old.
 - Stop the old replica, start the new — one request is in flight, at worst.
 If you cannot do zero-downtime, plan a 5-minute maintenance window.
 ---
 ## 13. What changes for end-users
 **Nothing.** Logins, sessions, sign-ups, invitations, access requests, admin views — all behave identically. The change is internal: same APIs, same UX, different code path.
 If a user reports a regression, treat it as a bug — file an InspectFlow ticket **and** a plate-auth ticket (since the regression is likely in the library, not in InspectFlow's residual code).
 ---
 ## 14. Common pitfalls (migration-specific)
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
 | Boot fails with `Field 'orgType' of Membership is null` | Forgot the data migration in § 8.2 | Run V33 manually |
 | Flyway: "checksum mismatch on V1" | Baseline rows in § 8.1 have wrong checksums | Set `flyway.validate-on-migrate=false` temporarily, or recompute checksums |
 | `OrgValidator` always returns false | Wrong `orgType` literal — case sensitive (`"COMPANY"` not `"company"`) | Check § 7 SPI binding |
 | Frontend cannot reach backend → 502 | `BACKEND_URL` rename to `PLATE_AUTH_BACKEND_URL` not propagated to all envs | Grep `BACKEND_URL` across repo + deploy configs |
 | E2E `companies.spec.ts` fails | `OrgDisplayNameResolver` SPI not registered → display name shows `Unbekannt` | Add bean in § 7 |
 | Admin chain order wrong → users get 403 on `/api/admin/...` | `@Order(0)` missing on `inspectflowAdminChain` | Add explicit order; default starter chain is `@Order(100)` |
 ---
 ## 15. Sign-off checklist
 Before declaring migration complete:
 - [ ] All Playwright E2E tests pass
 - [ ] Manual smoke test: log in via Google, password, accept invite, request access, approve as admin
 - [ ] `/admin/audit` shows `login_events` rows from both old and new code paths (timestamps span the migration)
 - [ ] No `WARN`/`ERROR` log entries from `de.platesoft.auth.*` in first 24h post-deploy
 - [ ] Database row counts before/after migration match (users, memberships, invitations, access_requests, login_events)
 - [ ] `memberships.org_type` is non-null on all rows (use SQL audit)
 - [ ] Deleted backend classes (§ 5.1) are actually deleted (no zombies)
 - [ ] Deleted frontend files (§ 9.1) are actually deleted
 ---
 ## 16. Cross-references
 - [Home.md](Home.md)
 - [Vision.md](Vision.md)
 - [Architecture.md](Architecture.md)
 - [Roadmap.md](Roadmap.md)
 - [Sprint-0-Assessment.md](Sprint-0-Assessment.md)
 - [Sprint-0-Plan.md](Sprint-0-Plan.md)
 - [Sprint-0-Testplan.md](Sprint-0-Testplan.md)
 - [Open-Questions.md](Open-Questions.md)
 - [Integration-Guide.md](Integration-Guide.md)
 ---
 **End of Migration-InspectFlow.md (v1).**