查看“︁Ystack”︁的源代码


= Services and responsibilities =
== Auth / Identity (Keycloak) ==
* Responsibility: Authentication, user identity, SSO, OIDC tokens.
* Data owned: Keycloak user record (sub), basic profile attributes.
* Notes: Other services store keycloak_id as foreign reference only.

== Customer Service (customer profile / account)==

* Responsibility: canonical customer profile (name, emails, billing address, company, contact info), payment-customer mapping (e.g., providerCustomerId), invoice delivery preferences, links to internal user records.
* Data owned: customer table (customer_id, keycloak_id, contact info, provider customer id, metadata).
* API examples: GET/PUT customer, attach payment method token, list customer’s subscriptions/orders.
* When to call: read-heavy for CRM and billing, write when profile changes.

== Product / Plan (Catalog) Service ==

* Responsibility: define and manage plans, price points, features, trial configuration, promotions/coupons, entitlements (features JSON).
* Data owned: plans, SKUs, pricing tiers, feature flags, metadata.
* Notes: Admin interfaces to create/retire plans; this is authoritative for what users can buy.

== Order / Checkout Service ==

* Responsibility: orchestrate purchase flows and create “orders” as transient/immutable records that represent a purchase attempt. Validate requested plan, pricing, coupons, compute totals and taxes, create provider checkout session or payment intent.
* Data owned: orders (order_id, customer_id, plan_id, price_at_purchase, status: created/processing/succeeded/failed/expired, idempotency key).
* Notes: Produces events (OrderCreated, OrderSucceeded, OrderFailed) consumed by Billing/Subscription and Customer services. Should be idempotent (use idempotency key).

== Subscription / Billing Service ==

* Responsibility: map orders into subscriptions, maintain subscription lifecycle (trialing, active, past_due, canceled), reconcile provider subscription state with local state, schedule renewals and billing windows, track current_period_start/end, cancel_at_period_end flags.
* Data owned: subscriptions table, subscription status history, subscription invoices (link to invoices table).
* Notes: Acts on provider webhooks and Order events to create/update local subscription rows.

== Payment Gateway Adapter ==
* Responsibility: encapsulate provider SDKs (Stripe, Paddle, etc.), create customers, payment methods, checkout sessions, subscriptions, invoices; normalize webhook payloads and verify signatures.
* Data owned: none (keeps provider ids for mapping).
* Notes: Keep this pluggable; return normalized result objects and propagate provider ids back to Order/Billing/Customer services.

== Invoice & Payments Service (or module inside Billing) ==

* Responsibility: store invoices and payments, record payment attempts, refunds, reconciliation with provider invoices, retention of raw payloads for audits.
* Data owned: invoices, payments, receipts.
* Notes: Expose APIs to query invoices and download receipts.

== Usage / Metering Service (optional, for metered billing) ==

* Responsibility: record per-feature usage (tokens, API calls), aggregate usage for billing periods, report usage to provider or generate usage-based invoices.
* Data owned: usage_records, aggregates.
* Notes: Support batching and idempotency (external_id) to avoid double-counting.

[[Category:Ystack]]
[[Category:DDD]]
[[Category:Distributed]]