fix: correct membership back flow and add onboarding paywall

docs/BUG_HISTORY.md

@@ -2584,3 +2584,19 @@
 - 相关记录：BUG-128、BUG-129、BUG-136、ERR-095、ERR-099、ERR-103
 - 复发自：无
 - 修复版本：待新 SHA 的 Release Gate 验证
+
+## BUG-152 | 订单返回套餐后再次返回会重新进入订单页
+
+- 状态：resolved（local candidate）
+- 首次发现：2026-08-10
+- 最近更新：2026-08-10
+- 影响面：`/membership` 与 `/membership/orders` 的浏览器返回历史；支付、订单读取、兑换与 production 未改动。
+- 用户现象：从套餐与会员页进入订单记录，点击返回套餐页后，再点击套餐页返回，会再次进入订单记录页，形成往返循环。
+- 触发条件：套餐页用普通 Link 将订单页压入历史记录，订单页返回时又用普通 Link 将套餐页再次压入历史记录。
+- 根因：订单页的“返回套餐与会员”是返回语义，却使用了默认 push 导航，历史栈变成 `套餐页 → 订单页 → 套餐页`。
+- 修复：订单页返回 Link 使用 Next.js 原生 `replace`，将当前订单页历史项替换为套餐页；套餐页再次返回时回到进入套餐前的原入口。
+- 验证：聚焦 membership 合同测试锁定返回 Link 的 `replace` 语义；前端生产构建 `next build --webpack` 通过；`git diff --check` 通过。未 push、deploy 或触碰 production。
+- 防复发：固定目标的“返回上级页”不能再次 push 当前上级页；会员页回归测试持续锁定订单页返回的 replace 语义。
+- 相关记录：无
+- 复发自：无
+- 修复版本：本地候选提交（未 push / deploy）

frontend/src/app/globals.css

@@ -749,6 +749,7 @@ button:disabled { cursor: default; opacity: .45; }
 .avatar-randomize { justify-self: start; }
 .avatar-notice { margin-top: var(--space-4); }
 .redeem-modal { width: min(100%, 420px); }
+.paywall-modal { width: min(100%, 480px); }
 .logout-modal { width: min(100%, 400px); }
 .account-modal h2, .auth-panel h1, .admin-header h1 { font-family: var(--font-display); font-weight: 400; letter-spacing: -.5px; text-wrap: balance; }
 .account-modal h2 { margin: 0; font-size: var(--type-display-sm); letter-spacing: -.025em; }
@@ -758,6 +759,14 @@ button:disabled { cursor: default; opacity: .45; }
 .redeem-balance span { color: var(--color-ink-secondary); font-size: var(--type-caption); }
 .redeem-balance strong { color: var(--color-ink); font-size: var(--type-title-lg); font-variant-numeric: tabular-nums; font-weight: 400; }
 .account-redeem-form { padding-top: var(--space-5); }
+.paywall-intro { display: flex; align-items: flex-start; gap: var(--space-4); padding-bottom: var(--space-5); }
+.paywall-mark { width: 44px; height: 44px; display: grid; flex: 0 0 auto; place-items: center; border-radius: 50%; background: var(--color-action-soft); color: var(--color-action); }
+.paywall-mark svg { width: 20px; height: 20px; }
+.paywall-intro b { display: block; color: var(--color-ink); font-family: var(--font-display); font-size: var(--type-title-md); font-weight: 400; }
+.paywall-intro p { margin: var(--space-1) 0 0; color: var(--color-ink-secondary); font-size: var(--type-body-sm); line-height: 1.6; text-wrap: pretty; }
+.paywall-footer { display: flex; align-items: center; justify-content: space-between; gap: var(--space-4); margin-top: var(--space-6); padding-top: var(--space-5); border-top: 1px solid var(--color-border); }
+.paywall-footer span { color: var(--color-ink-secondary); font-size: var(--type-caption); }
+.paywall-footer > a, .paywall-footer > button { flex: 0 0 auto; text-decoration: none; }
 .logout-copy { margin: 0; color: var(--color-ink-secondary); font-size: var(--type-body-md); line-height: 1.6; text-wrap: pretty; }
 .dialog-actions { display: flex; justify-content: flex-end; gap: var(--space-2); margin-top: var(--space-6); }
 .sheet-section { border-bottom: 1px solid var(--color-border); padding: var(--space-6) 0; border-color: var(--color-border); }
@@ -910,6 +919,8 @@ input:not([class^="ant-"]):not([class*=" ant-"]):not(.ant-picker input):disabled
   .starter-content span { font-size: var(--type-title-sm); }
   .account-modal h2 { font-size: var(--type-title-lg); }
   .account-redeem-form > div { grid-template-columns: 1fr; }
+  .paywall-footer { align-items: stretch; flex-direction: column; }
+  .paywall-footer > a, .paywall-footer > button { width: 100%; }
   .dialog-actions { flex-direction: column-reverse; }
   .dialog-actions > button { width: 100%; }
   .auth-story { min-height: 220px; padding: var(--space-6) var(--space-5); }

frontend/src/app/membership/orders/page.tsx

@@ -84,7 +84,7 @@ export default function MembershipOrdersPage() {
       <div className="membership-shell">
         <header className="membership-header">
           <div className="membership-header-left">
-            <Link className="membership-back" href="/membership" aria-label="返回套餐与会员">
+            <Link className="membership-back" href="/membership" replace aria-label="返回套餐与会员">
               <ArrowLeft aria-hidden="true" />
               <span>返回</span>
             </Link>

frontend/src/app/page.tsx

@@ -20,6 +20,7 @@ import { ChatMessageContent } from "@/components/chat-message-content";
 import { GeneratePersonalReportButton } from "@/components/personal-report/generate-personal-report-button";
 import { AgentAvatar, ChatMessageRow } from "@/components/chat-message-row";
 import { ModelSelector } from "@/components/model-selector";
+import { OnboardingRedeemPaywall } from "@/components/onboarding-redeem-paywall";
 import {
   LocationSearchCombobox,
   type ResolvedBirthLocation,
@@ -74,7 +75,11 @@ import {
 } from "@/lib/birth-time-guided-preview";
 import { defaultGuidedJyotishTopics, generalGuidedJyotishTopics } from "@/lib/guided-jyotish-topics";
 import { keepFocusWithin } from "@/lib/focus-trap";
-import { BALANCE_SYNC_KEY, BALANCE_CHANGED_EVENT, membershipHref } from "@/lib/membership";
+import {
+  BALANCE_SYNC_KEY,
+  BALANCE_CHANGED_EVENT,
+  membershipHref,
+} from "@/lib/membership";
 import { chatMessageViews, type ChatMessage } from "@/lib/chat-message-view";
 import { writeChatSession } from "@/lib/chat-session-write-contract";
 import { consultationReportMarkdown } from "@/lib/consultation-report-export";
@@ -1027,6 +1032,7 @@ export default function Home() {
   const [onboardingError, setOnboardingError] = useState("");
   const [onboardingStep, setOnboardingStep] = useState<OnboardingStep>("name");
   const [onboardingJustCompleted, setOnboardingJustCompleted] = useState(false);
+  const [onboardingPaywallOpen, setOnboardingPaywallOpen] = useState(false);
   const [birthTimeJourney, setBirthTimeJourney] = useState<JourneyClientResponse | null>(null);
   const [birthTimeError, setBirthTimeError] = useState("");
   const [birthTimeAssessmentPhase, setBirthTimeAssessmentPhase] = useState<BirthTimeAssessmentPhase | null>(null);
@@ -1037,6 +1043,7 @@ export default function Home() {
   const accountDialog = useRef<HTMLElement>(null);
   const dialogReturnTarget = useRef<HTMLButtonElement | null>(null);
   const closeButton = useRef<HTMLButtonElement>(null);
+  const onboardingPaywallShown = useRef(false);
   const composerInput = useRef<HTMLTextAreaElement>(null);
   const starterWorkbench = useRef<HTMLDivElement>(null);
   const pendingConsultation = useRef<PendingConsultation | null>(null);
@@ -1709,6 +1716,18 @@ export default function Home() {
     }
   }, [accountId, activeAccountDialog, hydrated, onboardingStep, presetMessageFinished, profileComplete]);
 
+  useEffect(() => {
+    if (uiPreview.current
+      || onboardingPaywallShown.current
+      || !starterHomeVisible
+      || !account
+      || account.credits > 0
+      || account.activeSubscription?.status === "active"
+      || activeAccountDialog !== null) return;
+    onboardingPaywallShown.current = true;
+    setOnboardingPaywallOpen(true);
+  }, [account, activeAccountDialog, starterHomeVisible]);
+
   useEffect(() => {
     if (activeAccountDialog === null) return;
     window.requestAnimationFrame(() => {
@@ -1964,18 +1983,10 @@ export default function Home() {
     dialogReturnTarget.current = returnTarget ?? accountTrigger.current;
     setAccountMenuOpen(false);
     setAccountError("");
-    switch (dialog) {
-      case "profile":
-        setProfileDraft(profile);
-        setProfileNotice("");
-        setAvatarNotice("");
-        break;
-      case "logout":
-        break;
-      default: {
-        const unreachable: never = dialog;
-        return unreachable;
-      }
+    if (dialog === "profile") {
+      setProfileDraft(profile);
+      setProfileNotice("");
+      setAvatarNotice("");
     }
     setActiveAccountDialog(dialog);
   }
@@ -3048,9 +3059,10 @@ export default function Home() {
     pinned: pinnedSessionIds.includes(session.id),
     archived: archivedSessionIds.includes(session.id),
   }));
+  const modalOpen = activeAccountDialog !== null || onboardingPaywallOpen;
 
   return (
-    <SidebarProvider escapeBlocked={accountMenuOpen || activeAccountDialog !== null}>
+    <SidebarProvider escapeBlocked={accountMenuOpen || modalOpen}>
       <main className="chat-app">
         <AppSidebar
           sessions={sidebarSessions}
@@ -3108,7 +3120,7 @@ export default function Home() {
             </section>
           </div>
         ) : null}
-        <SidebarInset className="chat-panel" inert={activeAccountDialog !== null}>
+        <SidebarInset className="chat-panel" inert={modalOpen}>
           <header className="chat-header">
             <SidebarTrigger placement="inset" />
           <div>
@@ -3552,6 +3564,13 @@ export default function Home() {
           </section>
         </div>
       )}
+      {onboardingPaywallOpen && account && (
+        <OnboardingRedeemPaywall
+          credits={account.credits}
+          onClose={() => setOnboardingPaywallOpen(false)}
+          onCreditsChanged={(credits) => setAccount((current) => current ? { ...current, credits } : current)}
+        />
+      )}
       </main>
     </SidebarProvider>
   );

frontend/src/components/onboarding-redeem-paywall.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import Link from "next/link";
+import { Gift, X } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import type { FormEvent } from "react";
+import { keepFocusWithin } from "@/lib/focus-trap";
+import { membershipHref, notifyBalanceChanged, redeemErrorMessage } from "@/lib/membership";
+
+type OnboardingRedeemPaywallProps = {
+  credits: number;
+  onClose: () => void;
+  onCreditsChanged: (credits: number) => void;
+};
+
+export function OnboardingRedeemPaywall({
+  credits,
+  onClose,
+  onCreditsChanged,
+}: OnboardingRedeemPaywallProps) {
+  const [code, setCode] = useState("");
+  const [error, setError] = useState("");
+  const [message, setMessage] = useState("");
+  const [pending, setPending] = useState(false);
+  const [unlocked, setUnlocked] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    const returnTarget = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const focusFrame = window.requestAnimationFrame(() => inputRef.current?.focus());
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      window.requestAnimationFrame(() => returnTarget?.focus());
+    };
+  }, []);
+
+  function close() {
+    if (!pending) onClose();
+  }
+
+  async function redeem(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const trimmedCode = code.trim();
+    if (!trimmedCode || pending || unlocked) return;
+    setPending(true);
+    setError("");
+    setMessage("");
+    try {
+      const response = await fetch("/api/redeem", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code: trimmedCode }),
+      });
+      const payload = await response.json().catch(() => null);
+      if (response.status === 401) {
+        window.location.assign("/login");
+        return;
+      }
+      if (!response.ok) throw new Error(redeemErrorMessage(response.status, payload));
+      const result = payload as { awardedCredits?: number; credits: number; message?: string };
+      const awarded = typeof result.awardedCredits === "number" ? result.awardedCredits : result.credits;
+      onCreditsChanged(result.credits);
+      setCode("");
+      setUnlocked(true);
+      setMessage(result.message || `已到账 ${awarded} 点，现在可以开始完整咨询。`);
+      notifyBalanceChanged(result.credits);
+    } catch (caught) {
+      setError(caught instanceof Error ? caught.message : "兑换失败，请稍后重试");
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="account-modal-overlay" onMouseDown={close}>
+      <section
+        className="account-modal paywall-modal"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="onboarding-paywall-title"
+        onMouseDown={(event) => event.stopPropagation()}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") close();
+          else keepFocusWithin(event.nativeEvent, event.currentTarget);
+        }}
+      >
+        <div className="dialog-header">
+          <h2 id="onboarding-paywall-title">解锁完整咨询</h2>
+          <button className="dialog-close" aria-label="关闭" type="button" onClick={close} disabled={pending}>
+            <X aria-hidden="true" />
+          </button>
+        </div>
+        <div className="paywall-intro">
+          <span className="paywall-mark" aria-hidden="true"><Gift /></span>
+          <div>
+            <b>入门问题已经准备好</b>
+            <p>填写兑换码，解锁后续咨询、生时校正与完整解读。</p>
+          </div>
+        </div>
+        <div className="redeem-balance">
+          <span>当前可用点数</span>
+          <strong>{credits} 点</strong>
+        </div>
+        <form className="redeem-form account-redeem-form" onSubmit={redeem}>
+          <label htmlFor="onboarding-redeem-code">兑换码</label>
+          <div>
+            <input
+              id="onboarding-redeem-code"
+              ref={inputRef}
+              autoComplete="off"
+              value={code}
+              onChange={(event) => {
+                setCode(event.target.value);
+                setError("");
+                setMessage("");
+                setUnlocked(false);
+              }}
+              placeholder="输入完整兑换码"
+            />
+            <button className="button-primary" type="submit" disabled={!code.trim() || pending || unlocked}>
+              {pending ? "兑换中" : unlocked ? "已解锁" : "兑换并继续"}
+            </button>
+          </div>
+          {error && <p className="form-error" role="alert">{error}</p>}
+          {message && <p className="form-success" role="status">{message}</p>}
+        </form>
+        <div className="paywall-footer">
+          <span>{unlocked ? "点数已到账，可以继续选择问题。" : "还没有兑换码？"}</span>
+          {unlocked ? (
+            <button className="button-primary" type="button" onClick={close}>开始咨询</button>
+          ) : (
+            <Link className="button-secondary" href={membershipHref("onboarding-paywall")}>查看套餐与会员</Link>
+          )}
+        </div>
+      </section>
+    </div>
+  );
+}

frontend/tests/membership-page.test.ts

@@ -5,6 +5,8 @@ import test from "node:test";
 const projectFile = (path: string) => new URL(`../${path}`, import.meta.url);
 const readProjectFile = (path: string) => readFileSync(projectFile(path), "utf8");
 const globalStyles = readProjectFile("src/app/globals.css");
+const homePageSource = readProjectFile("src/app/page.tsx");
+const onboardingPaywallSource = readProjectFile("src/components/onboarding-redeem-paywall.tsx");
 const pageSource = readProjectFile("src/app/membership/page.tsx");
 const ordersPageSource = readProjectFile("src/app/membership/orders/page.tsx");
 const tabsSource = readProjectFile("src/components/ui/tabs.tsx");
@@ -216,6 +218,22 @@ test("independent orders page preserves loading, empty, error, refresh and list
   assert.match(membershipLib, /paid: "已支付"/);
 });
 
+test("orders return replaces its history entry so membership back cannot reopen orders", () => {
+  assert.match(ordersPageSource, /<Link className="membership-back" href="\/membership" replace/);
+});
+
+test("finished starter questions open the redeem paywall only for accounts without access", () => {
+  assert.match(homePageSource, /!starterHomeVisible/);
+  assert.match(homePageSource, /account\.credits > 0/);
+  assert.match(homePageSource, /account\.activeSubscription\?\.status === "active"/);
+  assert.match(homePageSource, /setOnboardingPaywallOpen\(true\)/);
+  assert.match(homePageSource, /<OnboardingRedeemPaywall/);
+  assert.match(onboardingPaywallSource, /入门问题已经准备好/);
+  assert.match(onboardingPaywallSource, /fetch\("\/api\/redeem"/);
+  assert.match(onboardingPaywallSource, /兑换并继续/);
+  assert.match(onboardingPaywallSource, /membershipHref\("onboarding-paywall"\)/);
+});
+
 test("payment and plan copy points users to the separate orders page", () => {
   assert.match(pageSource, /本页会自动检查支付状态并刷新余额。/);
   assert.match(pageSource, /「订单记录」页面/);

frontend/tests/sidebar-contract.test.ts

@@ -173,9 +173,10 @@ test("removes the user-facing admin entry and routes credit control to membershi
 test("composes the chat page with the app sidebar shell", () => {
   const page = readProjectFile("src/app/page.tsx");
 
-  assert.match(page, /<SidebarProvider escapeBlocked=\{accountMenuOpen \|\| activeAccountDialog !== null\}>/);
+  assert.match(page, /const modalOpen = activeAccountDialog !== null \|\| onboardingPaywallOpen/);
+  assert.match(page, /<SidebarProvider escapeBlocked=\{accountMenuOpen \|\| modalOpen\}>/);
   assert.match(page, /<main className="chat-app">[\s\S]*<AppSidebar\b/);
-  assert.match(page, /<SidebarInset className="chat-panel" inert=\{activeAccountDialog !== null\}>/);
+  assert.match(page, /<SidebarInset className="chat-panel" inert=\{modalOpen\}>/);
   assert.match(page, /<SidebarTrigger placement="inset" \/>/);
 });
 
@@ -192,7 +193,7 @@ test("blocks the provider mobile Escape action behind layered account UI", () =>
   const page = readProjectFile("src/app/page.tsx");
   const sidebar = readProjectFile("src/components/ui/sidebar.tsx");
 
-  assert.match(page, /escapeBlocked=\{accountMenuOpen \|\| activeAccountDialog !== null\}/);
+  assert.match(page, /escapeBlocked=\{accountMenuOpen \|\| modalOpen\}/);
   assert.match(sidebar, /event\.key === "Escape" && isMobile && openMobile && !escapeBlocked/);
 });