Tilauksen täsmäytys Stripestä

Yhteenveto

• Laukaisin: funktiokutsu sync_saas_subscription_from_stripe(customer_id, force=False). Kutsujat: kirjautuminen (auth_provider.py:415 JWT-polku, auth_provider.py:513 Cognito-access-token-polku) ja operaattoriskriptit (scripts/list-saas-tenant-lifecycle.py:30, scripts/list-veraframe-cloud-tenants.py:28)
• Lopputulos: tenantin tilaustila ja tuoteoikeudet vastaavat Stripen totuutta, tai konfiguraatio palautetaan koskemattomana
• Idempotentti: kyllä. Lisäksi vaimennettu: ilman force-lippua täsmäytys ohitetaan, jos edellisestä on alle 900 sekuntia

Tämä on webhookin itsekorjausmekanismi. Webhook on ensisijainen päivityspolku, mutta se voi viivästyä, kadota tai kaatua DLQ:hun — silloin tenantin tila konvergoi takaisin Stripeen seuraavassa kirjautumisessa.

Sekvenssi

sequenceDiagram
    participant K as Kutsuja (kirjautuminen / skripti)
    participant S as sync_saas_subscription_from_stripe
    participant Cfg as CONFIG_BUCKET
    participant Stripe
    participant U as update_saas_subscription

    K->>S: customer_id (force?)
    S->>Cfg: load_customer_config
    S->>S: portit: stripe? tekninen? tunnukset? vaimennus?
    S->>Stripe: GET /v1/subscriptions/{id}
    S->>Stripe: GET /v1/subscriptions?customer=…&status=all
    Stripe-->>S: enintään 10 tilausta
    S->>S: valitse käyttökelpoisin tilaus
    S->>U: update_saas_subscription(status, ajoitus, tunnukset)
    U->>Cfg: save_customer_config
    S->>Cfg: save_customer_config (toinen kirjoitus)
    S-->>K: päivitetty konfiguraatio

Vaiheet

Vaihe 1 — Neljä porttia

• Mitä: täsmäytys keskeytyy heti ja palauttaa konfiguraation muuttumattomana, jos mikä tahansa seuraavista pätee:
  1. billing_provider != "stripe" (saas_onboarding.py:1276) — operaattorin luoma tai internal-laskutettu tenantti
  2. technical_account on tosi (saas_onboarding.py:1278) — sisäiset demot ja testitenantit
  3. sekä stripe_subscription_id että stripe_customer_id puuttuvat (saas_onboarding.py:1283)
  4. edellisestä täsmäytyksestä on alle STRIPE_SYNC_INTERVAL_SECONDS = 900 s eikä force ole päällä (saas_onboarding.py:1288)
• Koodi: saas_onboarding.py:1274–1289
• Data: Tenantin saas-lohko (ei näytteessä)
• Miksi vaimennus: funktio ajetaan jokaisella kirjautumisella. Ilman 15 minuutin porttia jokainen sisäänkirjautuminen tekisi 1–2 Stripe-kutsua ennen kuin käyttäjä näkee mitään.

Vaihe 2 — Tilausten haku Stripestä

• Mitä: jos stripe_subscription_id on tiedossa, se haetaan suoraan (GET /v1/subscriptions/{id}) ja siitä täydennetään puuttuva stripe_customer_id. Sen jälkeen haetaan asiakkaan kaikki tilaukset (status=all, limit=10).
• Koodi: saas_onboarding.py:549 (_fetch_stripe_subscription), saas_onboarding.py:569 (_list_stripe_customer_subscriptions), kutsut saas_onboarding.py:1293 ja saas_onboarding.py:1297
• Data: Stripen tilausobjektit (status, current_period_end, cancel_at, cancel_at_period_end, items.data[0].price.id)
• Huom: HTTP-kutsut tehdään urllib.requestilla 30 s aikakatkaisulla — ei requests-kirjastoa eikä Stripen SDK:ta. Tämä on projektin yleinen kaava.

Vaihe 3 — Käyttökelpoisimman tilauksen valinta

• Mitä: listalta valitaan ensimmäinen tilaus, jonka tila on active, trialing, past_due tai unpaid. Jos yhtään ei löydy, käytetään listan ensimmäistä; jos lista on tyhjä, suoraan haettua tilausta; jos sitäkään ei ole, palataan koskematta konfiguraatioon.
• Koodi: saas_onboarding.py:1300–1311
• Data: valittu tilausobjekti
• Miksi näin: uudelleenaktivointi ja toistuva testaaminen jättävät asiakkaalle useita tilauksia. Ilman tätä valintaa tenantti voisi jäädä vanhan canceled-tilauksen mukaiseen tilaan, vaikka uusi maksettu tilaus on voimassa. active_like_statuses sisältää tarkoituksella myös past_duen ja unpaidin: ne ovat "olemassa oleva asiakkuus, jossa on maksuongelma", eivät päättynyt asiakkuus.

Vaihe 4 — Tilan kirjoitus

• Mitä: update_saas_subscription kutsutaan Stripestä luetuilla arvoilla. Aikaleimat muunnetaan Unix-sekunneista ISO-muotoon, ja last_stripe_sync_at asetetaan tähän hetkeen. plan annetaan konfiguraatiosta, ei Stripestä — Stripen hinta-id ei siis voi muuttaa pakettia.
• Koodi: saas_onboarding.py:1319–1330
• Data ulos: Tenantin saas-lohko (ei näytteessä) · Tuoteominaisuudet ja compliance (ei näytteessä)
• Prosessi: Tilauksen tilan päivitys (ei näytteessä)

Vaihe 5 — Toinen tallennus

• Mitä: palautettu konfiguraatio kopioidaan syvästi ja tallennetaan uudelleen (save_customer_config), vaikka vaihe 4 on jo tallentanut sen.
• Koodi: saas_onboarding.py:1331–1334
• Huom: tämä on ylimääräinen kirjoitus samasta sisällöstä — kaksi put_objectia jokaisesta täsmäytyksestä, joka johtaa päivitykseen. Ei virheellinen, mutta turha; deepcopy-rivit saas_onboarding.py:1331–1333 eivät myöskään muuta sisältöä, koska update_saas_subscription on jo palauttanut oman kopionsa. > TODO: varmistettava — onko toisella tallennuksella tarkoitus, jota koodista ei näe (esim. rinnakkaisen kirjoituksen ylikirjoitus tahallaan).

Virhetilanteet

Kirjautuminen ei kaadu täsmäytyksen virheeseen. auth_provider.py:414 kutsuu funktiota omassa try/exceptissään ja jatkaa vanhalla konfiguraatiolla, jos täsmäytys heittää. Sama suoja on elinkaariskriptissä (scripts/list-saas-tenant-lifecycle.py:79), joka putoaa välimuistitettuun konfiguraatioon. Kirjautuminen siis toimii Stripe-katkonkin aikana — vanhoilla oikeuksilla.

Liittyvät

• Prosessit: Tilauksen tilan päivitys (ei näytteessä) · Stripe-tapahtuman käsittely
• Datavirta: Stripe-tapahtumasta tuoteoikeuksiksi
• Liiketoimintaprosessi: Cloud-tilauksen elinkaari