From 43fd3ed96dfc42e09df7449f27999b8c1dfa88a4 Mon Sep 17 00:00:00 2001
From: Haitao Pan <manbuzhe2009@qq.com>
Date: Mon, 16 Mar 2026 20:15:42 +0800
Subject: [PATCH] docs: add stripe pricing setup guide

---
 .env.example                        |  9 +++++
 README.md                           | 16 +++++++++
 docs/integrations/stripe-billing.md | 51 +++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/integrations/stripe-billing.md

diff --git a/.env.example b/.env.example
index 55edf36..ca08874 100644
--- a/.env.example
+++ b/.env.example
@@ -27,3 +27,12 @@ CLOUDFLARE_WEB_ANALYTICS_SITE_TAG=
 # Root email whitelist for privileged user-creation actions (comma-separated)
 # Default: admin@svc.plus
 ROOT_EMAIL_WHITELIST=admin@svc.plus
+
+# Stripe public price ids used by /prices, product pages, and /panel/subscription
+# These values are safe to expose to the browser. Use Stripe test-mode price ids for local/dev.
+NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_PAYGO=
+NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_SUBSCRIPTION=
+NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_PAYGO=
+NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_SUBSCRIPTION=
+NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_PAYGO=
+NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_SUBSCRIPTION=
diff --git a/README.md b/README.md
index cf842f5..bc7317a 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,21 @@ cp .env.example .env
 
 更多说明见 `docs/getting-started/installation.md` 和 `.env.example`。
 
+## Stripe 配置 (Stripe Billing Setup)
+
+`/prices`、产品页和账户中心的购买入口现在统一读取前端公开的 Stripe `price_id`：
+
+| 变量                                               | 用途                |
+| -------------------------------------------------- | ------------------- |
+| `NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_PAYGO`           | Xstream 按量购买    |
+| `NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_SUBSCRIPTION`    | Xstream 订阅        |
+| `NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_PAYGO`         | XScopeHub 按量购买  |
+| `NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_SUBSCRIPTION`  | XScopeHub 订阅      |
+| `NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_PAYGO`        | XCloudFlow 按量购买 |
+| `NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_SUBSCRIPTION` | XCloudFlow 订阅     |
+
+这些值应填写为 Stripe Dashboard 中对应套餐的 `price_...` 标识。联调步骤见 `docs/integrations/stripe-billing.md`。
+
 ## 核心特性 & 技术栈 (Features & Tech Stack)
 
 核心特性：
@@ -107,6 +122,7 @@ yarn typecheck
 
 - OIDC: `docs/integrations/oidc-auth.md`
 - Cloudflare Web Analytics: `docs/integrations/cloudflare-web-analytics.md`
+- Stripe billing: `docs/integrations/stripe-billing.md`
 - Assistant / Integrations env setup: `docs/getting-started/installation.md`
 - Chinese installation guide: `docs/zh/getting-started/installation.md`
 
diff --git a/docs/integrations/stripe-billing.md b/docs/integrations/stripe-billing.md
new file mode 100644
index 0000000..6d6ee01
--- /dev/null
+++ b/docs/integrations/stripe-billing.md
@@ -0,0 +1,51 @@
+# Stripe Billing Integration
+
+This console now routes all purchase entry points through Stripe:
+
+- `/prices`
+- product detail pages
+- `/panel/subscription`
+
+The browser only needs public Stripe `price_id` values. Secret keys stay in `accounts.svc.plus`.
+
+## Required Environment Variables
+
+Set these in `console.svc.plus`:
+
+```bash
+NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_PAYGO=price_xxx
+NEXT_PUBLIC_STRIPE_PRICE_XSTREAM_SUBSCRIPTION=price_xxx
+NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_PAYGO=price_xxx
+NEXT_PUBLIC_STRIPE_PRICE_XSCOPEHUB_SUBSCRIPTION=price_xxx
+NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_PAYGO=price_xxx
+NEXT_PUBLIC_STRIPE_PRICE_XCLOUDFLOW_SUBSCRIPTION=price_xxx
+```
+
+If a value is missing, the related purchase button stays visible but reports that Stripe pricing is not configured.
+
+## Local Integration Checklist
+
+1. Configure all `NEXT_PUBLIC_STRIPE_PRICE_*` values with Stripe test-mode `price_...` ids.
+2. Start `accounts.svc.plus` with Stripe server-side settings.
+3. Start this console with `yarn dev`.
+4. Sign in with a normal user account.
+5. Open `/prices` or `/panel/subscription` and start checkout.
+6. Complete a Stripe test payment.
+7. Confirm the browser returns to `/panel/subscription?checkout=success...`.
+8. Confirm the subscription record appears in the subscription panel.
+9. Open "Manage Stripe billing" and confirm the customer portal opens.
+
+## Expected Flow
+
+1. The console calls `/api/auth/stripe/checkout`.
+2. The BFF proxies the request to `accounts.svc.plus` using the current account session.
+3. `accounts.svc.plus` creates the Stripe Checkout Session.
+4. Stripe redirects back to the console.
+5. Stripe webhooks update the account service subscription record.
+6. The console reads the final state from `/api/auth/subscriptions`.
+
+## Notes
+
+- The console does not store Stripe secret keys.
+- Sensitive payment methods such as crypto QR flows are intentionally removed from the purchase UI.
+- Use Stripe test mode first; do not validate this flow against live prices until webhook delivery is confirmed.