plan(s0): chunk 2 - backend extraction step-by-step (W1, W2, W4)

2026-06-24 14:18:45 +02:00
parent c6ed37e6e0
commit 7b2a93f542
1 changed files with 236 additions and 0 deletions
@@ -159,3 +159,239 @@ See § 8 for step-by-step.
 ---

 *Plan continues in the next section — backend extraction step-by-step.*
+
+---
+
+## 4. Backend extraction — step-by-step
+
+### 4.1 W1 — Repo scaffolding
+
+**Goal:** Create the directory layout + skeleton `pom.xml` files + npm workspace structure.
+
+**Steps:**
+
+1. **W1-1** In the `plate-auth` repo root, create:
+   ```
+   plate-auth/
+   ├── pom.xml                          # parent POM, packaging=pom
+   ├── plate-auth-starter/
+   │   ├── pom.xml                      # the published artifact
+   │   └── src/{main,test}/{java,resources}/
+   ├── packages/
+   │   └── auth/
+   │       ├── package.json             # @platesoft/auth
+   │       └── src/
+   ├── package.json                     # workspace root
+   ├── pnpm-workspace.yaml              # if pnpm; npm/yarn equivalent works
+   ├── .gitea/workflows/                # Gitea Actions
+   ├── CHANGELOG.md
+   └── README.md
+   ```
+2. **W1-2** Parent `pom.xml`: `<groupId>de.platesoft</groupId>`, `<artifactId>plate-auth-parent</artifactId>`,
+   `<version>${revision}</version>` (CI-injected), `<packaging>pom</packaging>`,
+   `<modules><module>plate-auth-starter</module></modules>`. Inherit from `spring-boot-starter-parent:4.1.0`.
+3. **W1-3** `plate-auth-starter/pom.xml`: `<artifactId>plate-auth-starter</artifactId>`,
+   deps copied from InspectFlow `backend/pom.xml` minus app-specific (no ONNX, no openpdf, no pdfbox):
+   ```
+   web, data-jpa, security, validation, actuator, mail,
+   hibernate-envers, postgresql, flyway,
+   jjwt-api/impl/jackson,
+   mapstruct, lombok, logstash-logback,
+   h2 (test scope), testcontainers (test scope)
+   ```
+4. **W1-4** Root `package.json` + `pnpm-workspace.yaml` configured to pick up `packages/*`.
+5. **W1-5** `packages/auth/package.json`: `"name": "@platesoft/auth"`, `"version": "0.1.0"`,
+   peerDeps on `next@>=15`, `next-auth@^5.0.0-beta`, `react@>=19`.
+6. **W1-6** Add `.gitignore`, `.editorconfig`, basic `README.md` linking to the wiki.
+7. **W1-7** Commit + push to `main`. CI must pass on empty modules (just compiles).
+
+**Done when:** `mvn -B verify` and `pnpm -r build` both succeed on a fresh clone.
+
+### 4.2 W2-A — Backend: copy + rename classes
+
+**Goal:** Mechanical move from `de.platesoft.inspectflow.*` → `de.platesoft.auth.*` for every auth class.
+
+**Steps (per source class — repeat for the inventory in Sprint-0-Assessment § 1.1):**
+
+1. **W2-1** Copy class file from `inspectflow/backend/src/main/java/de/platesoft/inspectflow/<pkg>/<X>.java`
+   to `plate-auth/plate-auth-starter/src/main/java/de/platesoft/auth/<pkg>/<X>.java`.
+2. **W2-2** Update `package` declaration: `package de.platesoft.auth.<pkg>;`.
+3. **W2-3** Update **internal imports** (i.e. imports of other classes we are also moving) to the new
+   package. Use search-replace, but verify each file compiles independently after.
+4. **W2-4** **Leave behind**: any reference to `Company`, `OnboardingService`, `TenantAutoMapService` —
+   replace with an SPI call (see W4 below). DO NOT move these classes.
+
+**Class-by-class checklist:**
+
+- [ ] `filter/JwtAuthenticationFilter.java` — direct move, no rewrites
+- [ ] `filter/OrgContextResolver.java` — direct move
+- [ ] `config/SecurityConfig.java` — direct move, **but**: replace InspectFlow-specific permit-list
+  (`/api/companies/*/public-info`) with config-driven list from `PlateAuthProperties.cors.additionalPermitPaths`
+- [ ] `service/JwtService.java` — direct move; rename `@Value("${jwt.secret}")` → `@Value("${plate.auth.jwt.secret}")`
+- [ ] `service/OAuthService.java` — move + **swap** `tenantAutoMapService.maybeAutoMap(...)` call for
+  `onboardingHook.onFirstSignIn(...)` (SPI)
+- [ ] `service/ExchangeService.java` — direct move
+- [ ] `service/MembershipService.java` — move + **swap** `companyRepository.findById(...)` for
+  `orgValidator.exists(orgType, orgId)` / `orgDisplayNameResolver.displayName(...)` calls
+- [ ] `service/InvitationService.java` — direct move (Sprint 14.3 already abstracted the mailer)
+- [ ] `service/AccessRequestService.java` — direct move
+- [ ] `service/LoginEventService.java` — direct move
+- [ ] `service/AuthService.java` — direct move (password login/register)
+- [ ] `controller/AuthController.java` — direct move
+- [ ] `controller/OAuthController.java` — direct move
+- [ ] `controller/InvitationController.java` — direct move
+- [ ] `controller/AccessRequestController.java` — direct move
+- [ ] `controller/AdminAuditController.java` — direct move
+- [ ] `entity/User.java` — direct move
+- [ ] `entity/UserIdentity.java` — direct move
+- [ ] `entity/Membership.java` — direct move
+- [ ] `entity/Invitation.java` — direct move
+- [ ] `entity/AccessRequest.java` — direct move
+- [ ] `entity/LoginEvent.java` — direct move
+- [ ] `entity/RevInfo.java` (Envers revinfo with actor) — direct move
+- [ ] `repository/*` — all auth-related repositories — direct move
+- [ ] `dto/request/*` and `dto/response/*` — direct move
+- [ ] `enums/*` — direct move (Role, OrgType, MembershipRole, MembershipStatus, InvitationStatus,
+  AccessRequestStatus, LoginProvider)
+
+**Done when:** `plate-auth-starter` compiles in isolation. No references to `de.platesoft.inspectflow.*`
+remain in moved classes.
+
+### 4.3 W2-B — Configuration namespace
+
+**Goal:** Consolidate all `@Value("${...}")` injections into a single
+`@ConfigurationProperties("plate.auth")` class.
+
+**Steps:**
+
+1. **W2-8** Create `de.platesoft.auth.PlateAuthProperties`:
+   ```java
+   @ConfigurationProperties(prefix = "plate.auth")
+   @Data
+   public class PlateAuthProperties {
+       private Jwt jwt = new Jwt();
+       private Exchange exchange = new Exchange();
+       private Registration registration = new Registration();
+       private Cors cors = new Cors();
+       private Providers providers = new Providers();
+
+       @Data public static class Jwt {
+           private String secret;
+           private Duration accessExpiration = Duration.ofMinutes(15);
+           private Duration refreshExpiration = Duration.ofDays(30);
+           private String issuer = "plate-auth";
+       }
+       @Data public static class Exchange {
+           private String secret;
+           private Duration maxAge = Duration.ofSeconds(60);
+           private Duration nonceTtl = Duration.ofMinutes(5);
+       }
+       @Data public static class Registration {
+           private boolean enabled = false;
+       }
+       @Data public static class Cors {
+           private List<String> allowedOrigins = new ArrayList<>();
+           private List<String> additionalPermitPaths = new ArrayList<>();
+       }
+       @Data public static class Providers {
+           private ProviderToggle google = new ProviderToggle(true);
+           private ProviderToggle microsoft = new ProviderToggle(false);
+           private ProviderToggle emailMagicLink = new ProviderToggle(false);
+       }
+       @Data @AllArgsConstructor @NoArgsConstructor public static class ProviderToggle {
+           private boolean enabled;
+       }
+   }
+   ```
+2. **W2-9** Inject `PlateAuthProperties` (constructor injection) into every service that previously read
+   `@Value("${jwt....}")` etc. Replace `@Value` annotations.
+3. **W2-10** Add `META-INF/spring-configuration-metadata.json` (or rely on `spring-boot-configuration-processor`
+   annotation processor — preferred — add it to the build).
+4. **W2-11** Bean-validate critical fields:
+   ```java
+   @NotBlank @Size(min=32) private String secret;       // both jwt.secret and exchange.secret
+   ```
+
+**Done when:** No `@Value("${jwt....}")` or `@Value("${nextauth....}")` strings remain. All config flows
+through `PlateAuthProperties`. App fails fast at startup if `secret` is missing or <32 chars.
+
+### 4.4 W2-C — Auto-configuration
+
+**Goal:** Make the starter "just work" when added as a dependency.
+
+**Steps:**
+
+1. **W2-12** Create `de.platesoft.auth.PlateAuthAutoConfiguration`:
+   ```java
+   @AutoConfiguration
+   @EnableConfigurationProperties(PlateAuthProperties.class)
+   @ComponentScan(basePackages = "de.platesoft.auth")
+   @EntityScan(basePackages = "de.platesoft.auth.entity")
+   @EnableJpaRepositories(basePackages = "de.platesoft.auth.repository")
+   @ConditionalOnProperty(prefix = "plate.auth", name = "enabled", havingValue = "true", matchIfMissing = true)
+   public class PlateAuthAutoConfiguration {
+       // Default SPI beans, ConditionalOnMissingBean — see W4
+   }
+   ```
+2. **W2-13** Register the auto-config:
+   ```
+   src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
+   ```
+   Contents: single line `de.platesoft.auth.PlateAuthAutoConfiguration`.
+3. **W2-14** Verify that adding the starter to a minimal Spring Boot 4 app, setting `plate.auth.jwt.secret`
+   + `plate.auth.exchange.secret` env vars, and `spring.datasource.url` to a Postgres, makes the app boot
+   and serve `/api/auth/config`.
+
+**Done when:** Smoke test app (in `plate-auth-tests/`) boots and responds to `/api/auth/config`.
+
+### 4.5 W4 — SPI design + default implementations
+
+**Goal:** Five SPI interfaces with sensible defaults so consumers can override selectively.
+
+**Steps:**
+
+1. **W4-1** Create the 5 SPI interfaces under `de.platesoft.auth.spi`:
+   ```java
+   public interface OrgValidator {
+       boolean exists(OrgType type, UUID orgId);
+   }
+   public interface OrgDisplayNameResolver {
+       String displayName(OrgType type, UUID orgId);
+   }
+   public interface InvitationMailer {
+       void sendInvitation(Invitation invitation, String acceptUrl);
+   }
+   public interface AccessRequestMailer {
+       void notifyAdmins(AccessRequest request);
+       void notifyRequester(AccessRequest request);  // on decision
+   }
+   public interface OnboardingHook {
+       void onFirstSignIn(User user, LoginProvider provider);
+       default void onSubsequentSignIn(User user, LoginProvider provider) { /* no-op */ }
+   }
+   ```
+2. **W4-2** Default implementations (annotated `@ConditionalOnMissingBean`, registered in
+   `PlateAuthAutoConfiguration`):
+   - `DefaultOrgValidator` — **does NOT exist as a default**; auto-config requires the consumer to
+     provide one if T2 endpoints are used. If absent, T2 endpoints fail-fast on first invocation with a
+     clear error: "Provide a `de.platesoft.auth.spi.OrgValidator` bean to use plate-auth multi-tenancy."
+   - `DefaultOrgDisplayNameResolver` — returns `type + ":" + orgId.toString()`
+   - `LoggingInvitationMailer` — logs the accept URL at INFO level
+   - `LoggingAccessRequestMailer` — logs notifications at INFO level
+   - `NoOpOnboardingHook` — no-op
+3. **W4-3** Wire each service to its SPI dep via constructor injection:
+   - `MembershipService` ← `OrgValidator`, `OrgDisplayNameResolver`
+   - `InvitationService` ← `InvitationMailer`, `OrgDisplayNameResolver`
+   - `AccessRequestService` ← `AccessRequestMailer`, `OrgDisplayNameResolver`
+   - `OAuthService` ← `OnboardingHook`
+4. **W4-4** Document each SPI with Javadoc including:
+   - When it is called
+   - What happens if the consumer doesn't provide one (which default kicks in)
+   - Migration: if a previous version's signature changed, link to CHANGELOG
+
+**Done when:** A consumer can register a single `OrgValidator` bean and have T2 fully functional. Default
+mailers log instead of crashing.
+
+---
+
+*Plan continues — frontend extraction, Flyway, publishing.*