Portal procurement: real pricing/trial/quote spine + linked-gated checkout (vertical slice) (Stirling-Tools#6861)

## What this is

The enterprise procurement flow, built into the customer portal as a
**vertical slice** — one linked account can go the whole way from trial
to a paid, committed subscription, using real Stripe under the hood.

Procurement no longer lives as a nav tab. It sits on **Home** as a
deal-status hero and expands into a full-screen takeover, matching the
marketing prototype.

## The journey (what a customer does)

- **Start a trial** in one click — the deadline and next steps show on
the Home hero (no card, mock licence).
- **Build a quote** — a short form (volume → commitment & service →
details); pricing is computed server-side.
- **Generate the quote** — this creates a real **Stripe Quote** with a
proper **PDF** you can download and share, and it becomes a milestone
you can come back to.
- **Review & sign the agreement** — one combined agreement (MSA + Order
Form + EULA + DPA) with an itemised order form and an "I agree" (no
e-signature yet).
- **Accept** — Stripe creates the committed annual **subscription** and
its **first invoice**, which you can **pay or download right in the
app** (no waiting on email).
- Edit a quote any time — it remembers your inputs and company name; the
old Stripe quote is cancelled so it can't still be accepted.
- The hero also has quick actions: **key documents**, **invite
teammates**, **schedule a call**, and a **trial countdown** you can
extend.

## Architecture — Supabase vs Java

Pricing, deal/quote state, and the commercial journey live in **Java
(`:saas`)**. Everything that touches **Stripe** (writes + PDFs) lives in
**Supabase edge functions** — Java has no Stripe SDK and only reads
Stripe via the sync mirror. The portal calls both.

```mermaid
flowchart LR
  Portal["Portal (React · editor/src/portal)"]

  subgraph JAVA["Java :saas backend (trusted cloud)"]
    Pricing["Pricing engine (volume bands, SLA, term, add-ons)"]
    Deal["Deal + quote state, journey, snapshot"]
    Trial["Trial (mock Keygen licence seam)"]
    Authz["Auth: team resolve + leader gating"]
    Mirror["Reads Stripe via sync mirror (stripe.* tables)"]
  end

  subgraph SUPA["Supabase edge functions (own Stripe)"]
    Issue["issue-procurement-quote → create + finalize Stripe Quote"]
    Accept["accept-procurement-quote → subscription + finalize invoice"]
    Pdf["get-procurement-quote-pdf → proxy the quote PDF"]
    RPC["SECURITY DEFINER RPCs (read/write stirling_pdf, enforce team/leader)"]
  end

  Stripe["Stripe (Quotes · Subscription · Invoice)"]

  Portal -->|"price / build / trial / agreement / snapshot"| JAVA
  Portal -->|"issue / accept / download PDF"| SUPA
  SUPA --> Stripe
  SUPA --- RPC
  Mirror -. reads .-> Stripe
```

| Top-level feature | Handled in |
|---|---|
| Quote pricing (bands, SLA, term, add-ons) | **Java** |
| Deal + quote state, journey, snapshot | **Java** |
| Trial start / extend (mock licence) | **Java** |
| AuthN/Z (team resolve, leader gating) | **Java** |
| Issue quote → Stripe Quote + PDF | **Supabase edge fn** |
| Accept → subscription + invoice | **Supabase edge fn** |
| Quote PDF download | **Supabase edge fn** |
| Reading Stripe state | **Java** (sync mirror) |
| `stirling_pdf` writes from edge | **SECURITY DEFINER RPCs**
(service-role only) |

## Screenshots

<!-- Drag each PNG into the box below it before publishing. -->

**Home deal-status hero (trial)**
<img width="1920" height="1009" alt="hero-check"
src="https://github.com/user-attachments/assets/7ae21831-9578-4f4d-b91a-d3ab2cb171dc"
/>

**Issued quote milestone (with breakdown)**
<img width="1920" height="1009" alt="milestone-breakdown"
src="https://github.com/user-attachments/assets/3a463c67-3c6e-4f93-a1cc-59b250d54cc9"
/>


**Agreement step (itemised order form)**
<img width="1920" height="1009" alt="agreement-itemised"
src="https://github.com/user-attachments/assets/1a4efa16-d0a3-41d0-849c-a125b1492a34"
/>

**Key documents**
<img width="1920" height="1009" alt="keydocs-modal"
src="https://github.com/user-attachments/assets/5672d1d2-99d9-499e-9edf-d485df378e7f"
/>

**Subscription created (pay / download invoice)**
<img width="1920" height="1009" alt="accepted-check"
src="https://github.com/user-attachments/assets/3a8cbe9f-e72c-4389-b365-0c1749108b6f"
/>


## Mocked for now (scaffolding, not wired to real backends)

- **Key documents** ledger — static demo list.
- **Schedule a call** — static solutions-engineer + time slots.
- **Invite teammates** — routes to the existing Users view.
- **Simulate payment received** / **Reset procurement** — demo controls,
**off by default** in prod (flag-gated), 404 unless enabled.

## Deferred (separate follow-up PRs)

- **Real `invoice.paid` webhook** → go-live (today a demo button stands
in).
- **Keygen licence controller** — real licensing (currently a mock
seam).
- **Document sharing**.
- **Stirling admin / Deal Desk** view.
- **Minimum ACV floor** — pending a number from marketing (server-side
enforcement is a one-liner once decided).

## How to test

- **Frontend, no backend:** runs against MSW mocks (Storybook + mocks-on
dev) — the whole journey is clickable.
- **Real end-to-end:** apply the migrations (Flyway `V27–V29` / Supabase
`20260701–20260707`), deploy the three edge functions, ensure
**Invoicing Plus** is enabled on Stripe, and set
`STIRLING_PROCUREMENT_DEMO_CONTROLS_ENABLED=true` if you want the demo
controls.
- Paired SaaS PR: **Stirling-Tools/Stirling-PDF-SaaS#318**.

## Notes for reviewers

- Pricing is server-authoritative (client sends config, never amounts).
- Security review done: edge functions validate the JWT and enforce
**team membership** (and **leader** for issue/accept) via the RPC; demo
endpoints are flag-gated off. Only open item is the ACV floor (policy).

Author: ConnorYoh

app/saas/src/main/java/stirling/software/saas/config/SaasJpaConfig.java

@@ -18,13 +18,15 @@
             "stirling.software.saas.repository",
             "stirling.software.saas.billing.repository",
             "stirling.software.saas.ai.repository",
-            "stirling.software.saas.payg.repository"
+            "stirling.software.saas.payg.repository",
+            "stirling.software.saas.procurement.repository"
         })
 @EntityScan({
     "stirling.software.saas.accountlink",
     "stirling.software.saas.model",
     "stirling.software.saas.billing.model",
     "stirling.software.saas.ai.model",
-    "stirling.software.saas.payg"
+    "stirling.software.saas.payg",
+    "stirling.software.saas.procurement.model"
 })
 public class SaasJpaConfig {}

app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java

@@ -0,0 +1,321 @@
+package stirling.software.saas.procurement.api;
+
+import java.util.List;
+import java.util.Objects;
+
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.swagger.v3.oas.annotations.Hidden;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.enumeration.TeamRole;
+import stirling.software.proprietary.security.database.repository.UserRepository;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.saas.model.TeamMembership;
+import stirling.software.saas.procurement.config.ProcurementConfigurationProperties;
+import stirling.software.saas.procurement.model.ProcurementDeal;
+import stirling.software.saas.procurement.model.ProcurementQuote;
+import stirling.software.saas.procurement.pricing.QuoteConfig;
+import stirling.software.saas.procurement.pricing.QuoteLineItem;
+import stirling.software.saas.procurement.service.ProcurementService;
+import stirling.software.saas.repository.TeamMembershipRepository;
+import stirling.software.saas.util.AuthenticationUtils;
+
+/**
+ * The enterprise procurement journey for a linked team: read the deal snapshot, start/extend a
+ * (mock-licensed) trial, build a server-priced quote, and accept it. Stripe checkout itself is a
+ * Supabase edge function the portal calls with the accepted quote — this controller never touches
+ * Stripe. The caller's team is resolved from the authenticated principal; a team id is never
+ * trusted from the request. Mutations require the team leader.
+ */
+@Slf4j
+@Hidden
+@RestController
+@RequestMapping("/api/v1/procurement")
+@Profile("saas")
+public class ProcurementController {
+
+    // Local mapper to parse the stored line-items JSON; the saas context exposes no injectable
+    // ObjectMapper bean.
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    private final ProcurementService procurement;
+    private final TeamMembershipRepository memberRepo;
+    private final UserRepository userRepository;
+    private final ProcurementConfigurationProperties config;
+
+    public ProcurementController(
+            ProcurementService procurement,
+            TeamMembershipRepository memberRepo,
+            UserRepository userRepository,
+            ProcurementConfigurationProperties config) {
+        this.procurement = Objects.requireNonNull(procurement);
+        this.memberRepo = Objects.requireNonNull(memberRepo);
+        this.userRepository = Objects.requireNonNull(userRepository);
+        this.config = Objects.requireNonNull(config);
+    }
+
+    // ---- request / response DTOs -------------------------------------------
+
+    public record QuoteRequest(
+            long volume,
+            int users,
+            String deployment,
+            int termYears,
+            String serviceLevel,
+            boolean indemnification,
+            boolean training,
+            boolean qbr,
+            String currency,
+            String businessName) {
+        QuoteConfig toConfig() {
+            return new QuoteConfig(
+                    volume,
+                    users,
+                    deployment,
+                    termYears,
+                    serviceLevel,
+                    indemnification,
+                    training,
+                    qbr,
+                    currency);
+        }
+    }
+
+    public record QuoteResponse(
+            Long quoteId,
+            String quoteNumber,
+            String status,
+            String currency,
+            long annualNetMinor,
+            long tcvMinor,
+            List<QuoteLineItem> lineItems,
+            String validUntil,
+            String stripeQuoteId,
+            String invoiceUrl,
+            QuoteConfigEcho config) {}
+
+    /**
+     * The inputs the quote was priced from, echoed back so the builder can seed itself when the
+     * buyer re-edits an existing quote. {@code users} is not persisted (only the resulting volume
+     * is), so it is always 0 here; the builder treats the seeded volume as manually set.
+     */
+    public record QuoteConfigEcho(
+            long volume,
+            int users,
+            String deployment,
+            int termYears,
+            String serviceLevel,
+            boolean indemnification,
+            boolean training,
+            boolean qbr,
+            String currency,
+            String businessName) {}
+
+    public record SnapshotResponse(
+            Long dealId,
+            String stage,
+            String trialStartedAt,
+            String trialEndsAt,
+            int trialExtensionsUsed,
+            boolean licensed,
+            QuoteResponse latestQuote) {}
+
+    // ---- endpoints ----------------------------------------------------------
+
+    /**
+     * The team's deal snapshot. Always 200 with a single shape; an unstarted procurement returns an
+     * empty snapshot ({@code dealId == null}) so the portal can render the "start" state without
+     * special-casing an empty body.
+     */
+    @GetMapping
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> snapshot(Authentication auth) {
+        Long teamId = resolveTeam(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+        return ResponseEntity.ok(
+                procurement.getDeal(teamId).map(this::toSnapshot).orElse(EMPTY_SNAPSHOT));
+    }
+
+    private static final SnapshotResponse EMPTY_SNAPSHOT =
+            new SnapshotResponse(null, null, null, null, 0, false, null);
+
+    @PostMapping("/trial/start")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> startTrial(Authentication auth) {
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        return ResponseEntity.ok(toSnapshot(procurement.startTrial(teamId)));
+    }
+
+    @PostMapping("/trial/extend")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> extendTrial(Authentication auth) {
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        try {
+            return ResponseEntity.ok(toSnapshot(procurement.extendTrial(teamId)));
+        } catch (IllegalStateException e) {
+            return ResponseEntity.status(HttpStatus.CONFLICT).build();
+        }
+    }
+
+    @PostMapping("/quote")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<QuoteResponse> buildQuote(
+            @RequestBody QuoteRequest request, Authentication auth) {
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        return ResponseEntity.ok(
+                toQuote(
+                        procurement.buildQuote(
+                                teamId, request.toConfig(), request.businessName())));
+    }
+
+    // Issue + accept are Supabase edge functions (they own Stripe): issue-procurement-quote turns a
+    // draft into a finalized Stripe Quote; accept-procurement-quote accepts it into a subscription.
+    // Both persist their results via SECURITY DEFINER RPCs; the snapshot above reflects them.
+
+    /**
+     * Advance an issued quote to the agreement (security) stage, where the buyer reviews + agrees.
+     */
+    @PostMapping("/agreement")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> startAgreement(Authentication auth) {
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        try {
+            return ResponseEntity.ok(toSnapshot(procurement.startAgreement(teamId)));
+        } catch (IllegalStateException e) {
+            return ResponseEntity.status(HttpStatus.CONFLICT).build();
+        }
+    }
+
+    /**
+     * Demo/manual stand-in for the {@code invoice.paid} webhook: mark the deal live (issue the
+     * annual licence, advance to active). The real go-live is webhook-driven once payment settles.
+     */
+    @PostMapping("/go-live")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> goLive(Authentication auth) {
+        if (!config.isDemoControlsEnabled()) return ResponseEntity.notFound().build();
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        try {
+            return ResponseEntity.ok(toSnapshot(procurement.markLive(teamId)));
+        } catch (IllegalStateException e) {
+            return ResponseEntity.status(HttpStatus.CONFLICT).build();
+        }
+    }
+
+    /** Reset the team's procurement (delete the deal + quotes); returns the empty snapshot. */
+    @PostMapping("/reset")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<SnapshotResponse> reset(Authentication auth) {
+        if (!config.isDemoControlsEnabled()) return ResponseEntity.notFound().build();
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        procurement.resetDeal(teamId);
+        return ResponseEntity.ok(EMPTY_SNAPSHOT);
+    }
+
+    // ---- helpers ------------------------------------------------------------
+
+    /**
+     * Resolve the caller's team from their primary membership; null when unauthenticated/teamless.
+     */
+    private Long resolveTeam(Authentication auth) {
+        User user;
+        try {
+            user = AuthenticationUtils.getCurrentUser(auth, userRepository);
+        } catch (SecurityException e) {
+            return null;
+        }
+        List<TeamMembership> rows = memberRepo.findPrimaryMembership(user.getId());
+        return rows.isEmpty() ? null : rows.get(0).getTeam().getId();
+    }
+
+    /** Team id only when the caller is the team leader; null otherwise (commercial actions). */
+    private Long requireLeader(Authentication auth) {
+        User user;
+        try {
+            user = AuthenticationUtils.getCurrentUser(auth, userRepository);
+        } catch (SecurityException e) {
+            return null;
+        }
+        List<TeamMembership> rows = memberRepo.findPrimaryMembership(user.getId());
+        if (rows.isEmpty() || rows.get(0).getRole() != TeamRole.LEADER) return null;
+        return rows.get(0).getTeam().getId();
+    }
+
+    private SnapshotResponse toSnapshot(ProcurementDeal deal) {
+        QuoteResponse latest =
+                procurement.quotesForDeal(deal.getDealId()).stream()
+                        .findFirst()
+                        .map(this::toQuote)
+                        .orElse(null);
+        return new SnapshotResponse(
+                deal.getDealId(),
+                deal.getStage(),
+                str(deal.getTrialStartedAt()),
+                str(deal.getTrialEndsAt()),
+                deal.getTrialExtensionsUsed(),
+                deal.getLicenseRef() != null,
+                latest);
+    }
+
+    private QuoteResponse toQuote(ProcurementQuote q) {
+        return new QuoteResponse(
+                q.getQuoteId(),
+                q.getQuoteNumber(),
+                q.getStatus(),
+                q.getCurrency(),
+                q.getAnnualNetMinor(),
+                q.getTcvMinor(),
+                parseLineItems(q.getLineItemsJson()),
+                q.getValidUntil() == null ? null : q.getValidUntil().toString(),
+                q.getStripeQuoteId(),
+                q.getStripeInvoiceUrl(),
+                new QuoteConfigEcho(
+                        q.getVolume(),
+                        0,
+                        q.getDeployment(),
+                        q.getTermYears(),
+                        q.getServiceLevel(),
+                        q.isIndemnification(),
+                        q.isTraining(),
+                        q.isQbr(),
+                        q.getCurrency(),
+                        q.getBusinessName()));
+    }
+
+    private List<QuoteLineItem> parseLineItems(String json) {
+        if (json == null || json.isBlank()) return List.of();
+        try {
+            return OBJECT_MAPPER.readValue(
+                    json,
+                    OBJECT_MAPPER
+                            .getTypeFactory()
+                            .constructCollectionType(List.class, QuoteLineItem.class));
+        } catch (Exception e) {
+            log.warn("[procurement] failed to parse line items", e);
+            return List.of();
+        }
+    }
+
+    private static String str(Object o) {
+        return o == null ? null : o.toString();
+    }
+}

app/saas/src/main/java/stirling/software/saas/procurement/config/ProcurementConfigurationProperties.java

@@ -0,0 +1,33 @@
+package stirling.software.saas.procurement.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/** Tunables for the enterprise procurement flow. Prefix {@code stirling.procurement}. */
+@Getter
+@Setter
+@Component
+@Profile("saas")
+@ConfigurationProperties(prefix = "stirling.procurement")
+public class ProcurementConfigurationProperties {
+
+    /** Free trial length, in days (no card). */
+    private int trialDurationDays = 14;
+
+    /** Days added per trial extension. */
+    private int trialExtensionDays = 7;
+
+    /** Maximum number of trial extensions a buyer may take. */
+    private int maxTrialExtensions = 2;
+
+    /**
+     * Enables the demo-only endpoints (POST /reset, POST /go-live) that reset a team's procurement
+     * or mark it live without payment. Off by default; turn on ONLY in demo/dev environments —
+     * /go-live is a stand-in for the invoice.paid webhook and would let a leader activate unpaid.
+     */
+    private boolean demoControlsEnabled = false;
+}

app/saas/src/main/java/stirling/software/saas/procurement/license/EnterpriseLicenseService.java

@@ -0,0 +1,25 @@
+package stirling.software.saas.procurement.license;
+
+import java.time.LocalDateTime;
+
+/**
+ * Issues and modifies the customer-facing entitlement that actually unlocks the product for an
+ * enterprise deal — a Keygen licence (trial or annual, connected or air-gapped). This is the seam
+ * the real Keygen management client plugs into; today {@link MockEnterpriseLicenseService} records
+ * intent without calling Keygen. Distinct from the EE {@code KeygenLicenseVerifier}, which only
+ * verifies this instance's own licence.
+ */
+public interface EnterpriseLicenseService {
+
+    /** Issue a time-boxed trial licence for the team; returns the licence reference. */
+    String issueTrialLicense(Long teamId, LocalDateTime expiresAt);
+
+    /** Move a licence's expiry out (trial extension). */
+    void extendLicense(String licenseRef, LocalDateTime newExpiry);
+
+    /** Issue/upgrade to a committed annual licence with the quote's entitlements. */
+    String issueAnnualLicense(Long teamId, String deployment, LocalDateTime expiresAt);
+
+    /** Suspend a licence (e.g. payment failed, deal lost). */
+    void suspendLicense(String licenseRef);
+}