From 296a7fced9b9648813c7d8e17e20e8e2516abaed Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Tue, 26 May 2026 19:59:14 +0800
Subject: [PATCH] fix: defer mini program phone auth until login

---
 .hermes/shared-memory/decision-log.md         |   7 +
 ...�项目基线】当�产�与工程约�-2026-05-15.md |   2 +
 miniprogram/pages/web-view/index.js           | 125 +++++++++++++--
 miniprogram/pages/web-view/index.wxml         |   4 +
 scripts/miniprogram-web-view-auth.test.ts     | 149 ++++++++++++++++++
 src/components/auth/AuthGate.test.tsx         |  29 ++++
 src/components/auth/AuthGate.tsx              |  41 ++++-
 src/components/auth/LoginScreen.tsx           |   9 +-
 src/services/authService.test.ts              |  81 +++++++++-
 src/services/authService.ts                   |  92 ++++++++++-
 10 files changed, 520 insertions(+), 19 deletions(-)
 create mode 100644 scripts/miniprogram-web-view-auth.test.ts

diff --git a/.hermes/shared-memory/decision-log.md b/.hermes/shared-memory/decision-log.md
index 840846b4..9855596e 100644
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -532,6 +532,13 @@
 - 验�方�：执行 `npm run check:encoding`�`node scripts/check-wechat-miniprogram-auth-smoke.mjs`�`cargo test -p shared-contracts wechat_bind_phone_request_accepts_mini_program_phone_code --manifest-path server-rs/Cargo.toml`�`cargo test -p api-server wechat_miniprogram_bind_phone_code_activates_pending_user --manifest-path server-rs/Cargo.toml -- --nocapture`。
 - 关�文档：`docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md`。
 
+## 2026-05-26 微信�程�进入�开 H5，登录按需走原生手机�授�
+
+- 背景：当�产��求微信�程�进入���立刻�手机�，而是默认直接进入 `web-view`，登录状�与 Web 端统一；�有 H5 触���护�作时�走微信手机�授�。
+- 决策：�程�壳首次进入�打开 H5，��把登录�当作�动�置�件；H5 侧在�程��行�触�登录时，�展示普通登录弹窗，而是跳转到�程�原生手机�授��程，授�结果�回�到 H5。未触�登录时��游客�，与 Web 端一致。
+- 影�范围：`miniprogram/pages/web-view/index.*`�`src/components/auth/AuthGate.tsx`�`src/components/auth/LoginScreen.tsx`�`src/services/authService.ts`�相关测试与说明文档。
+- 验�方�：执行 `npm run check:encoding`�`npm run typecheck`�`npx vitest run src/components/auth/AuthGate.test.tsx src/services/authService.test.ts scripts/miniprogram-web-view-auth.test.ts`。
+
 ## 2026-05-13 ��爱画先作为寓教于�独立本地 Demo �地
 
 - 背景：第三关 `��爱画` 需�默认出现在“�现 / 寓教于����下方，但本阶段�验�画��手部绘制�绘画魔法和本地�存闭环，�进入创作模��公开作�或正��久化。
diff --git a/docs/�项目基线】当�产�与工程约�-2026-05-15.md b/docs/�项目基线】当�产�与工程约�-2026-05-15.md
index 0007216b..76e7f907 100644
--- a/docs/�项目基线】当�产�与工程约�-2026-05-15.md
+++ b/docs/�项目基线】当�产�与工程约�-2026-05-15.md
@@ -44,6 +44,8 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与�游�平�。当
 1. 主站登录弹窗必须稳定展示 `短信登录` 与 `密�登录` 两个核心入�；`GET /api/auth/login-options` �能补充微信等环境相关入�，�能决定是���短信或密�登录。
 2. `login-options` 为空�失败��返回 `phone` 或�返回 `password` 时，�端���时展示验��登录页签和密�登录页签；短信能力真实�用性由��验��接�返回结果表达。
 3. 登录弹窗继续�用现有独立 modal 和页签结构，�在页�中新增功能说明类文案，也�把邀请�输入放回登录��。
+4. 微信�程� `web-view` 外壳默认�预登录，首次进入直接打开 H5，并��与 Web 端一致的未登录状�；�有 H5 触� `openLoginModal` / `requireAuth` 等��护入�时，�跳转�程�原生授��。
+5. �程�内需�登录时�展示 H5 登录弹窗，也�走手输手机� / 短信验���程；统一通过原生 `button open-type="getPhoneNumber"` 获�微信手机�授�，�调用 `/api/auth/wechat/miniprogram-login` 与 `/api/auth/wechat/bind-phone` ��系统登录�。
 
 ## 账户与充值
 
diff --git a/miniprogram/pages/web-view/index.js b/miniprogram/pages/web-view/index.js
index 534128d3..c199300b 100644
--- a/miniprogram/pages/web-view/index.js
+++ b/miniprogram/pages/web-view/index.js
@@ -1,3 +1,6 @@
+/* global Page, wx */
+/* eslint-disable no-console */
+
 const {
   API_BASE_URL,
   MINI_PROGRAM_APP_ID,
@@ -10,6 +13,8 @@ const MINI_PROGRAM_CLIENT_TYPE = 'mini_program';
 const MINI_PROGRAM_CLIENT_RUNTIME = 'wechat_mini_program';
 const CLIENT_INSTANCE_STORAGE_KEY = 'genarrative:mini-program-client-instance-id';
 const PAY_RESULT_STORAGE_KEY = 'genarrative:wechat-pay-result';
+const AUTH_RESULT_STORAGE_KEY = 'genarrative:mini-program-auth-result';
+const AUTH_ACTION_LOGIN = 'login';
 
 function isConfiguredEntryUrl(value) {
   const trimmed = String(value || '').trim();
@@ -57,6 +62,18 @@ function appendHashParams(url, params) {
   return `${baseUrl}#${rawHash}${separator}${pairs.join('&')}`;
 }
 
+function parseBooleanQueryFlag(value) {
+  return value === true || value === '1' || value === 'true' || value === 'yes';
+}
+
+function shouldStartAuthFromQuery(query) {
+  return String((query && query.authAction) || '').trim() === AUTH_ACTION_LOGIN;
+}
+
+function shouldReturnToPreviousPage(query) {
+  return String((query && query.returnTo) || '').trim() === 'previous';
+}
+
 function resolveWebViewUrl(authResult) {
   const entryUrl = String(WEB_VIEW_ENTRY_URL || '').trim();
   if (!isConfiguredEntryUrl(entryUrl)) {
@@ -75,6 +92,38 @@ function resolveWebViewUrl(authResult) {
   });
 }
 
+function persistAuthResult(authResult) {
+  wx.setStorageSync(AUTH_RESULT_STORAGE_KEY, JSON.stringify(authResult));
+}
+
+function consumeAuthResult() {
+  const rawValue = wx.getStorageSync(AUTH_RESULT_STORAGE_KEY);
+  if (!rawValue) {
+    return null;
+  }
+
+  wx.removeStorageSync(AUTH_RESULT_STORAGE_KEY);
+  try {
+    const parsed = JSON.parse(String(rawValue));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const token = String(parsed.token || '').trim();
+    if (!token) {
+      return null;
+    }
+
+    return {
+      token,
+      bindingStatus: String(parsed.bindingStatus || 'pending_bind_phone'),
+    };
+  } catch (error) {
+    console.error('[web-view] parse auth result failed', error);
+    return null;
+  }
+}
+
 function getClientInstanceId() {
   const stored = wx.getStorageSync(CLIENT_INSTANCE_STORAGE_KEY);
   if (stored) {
@@ -217,10 +266,12 @@ Page({
     errorMessage: '',
     loading: true,
     phoneBindingRequired: false,
+    returnToPreviousPage: false,
     webViewUrl: '',
   },
 
-  async onLoad() {
+  async onLoad(query = {}) {
+    this._lastLaunchQuery = query;
     // 中文注释：web-view �能打开已�置业务域�；未�置时展示本地�示，��空白页误判。
     if (!isConfiguredEntryUrl(WEB_VIEW_ENTRY_URL)) {
       this.setData({
@@ -231,6 +282,20 @@ Page({
       return;
     }
 
+    const forcedPhoneBinding = parseBooleanQueryFlag(query.phoneBindingRequired);
+    const returnToPreviousPage = shouldReturnToPreviousPage(query);
+    if (!shouldStartAuthFromQuery(query) && !forcedPhoneBinding) {
+      this.setData({
+        authResult: null,
+        errorMessage: '',
+        loading: false,
+        phoneBindingRequired: false,
+        returnToPreviousPage: false,
+        webViewUrl: resolveWebViewUrl(null),
+      });
+      return;
+    }
+
     if (!isConfiguredApiBaseUrl(API_BASE_URL)) {
       this.setData({
         errorMessage: '请先在 miniprogram/config.js 填写 API_BASE_URL。',
@@ -240,6 +305,14 @@ Page({
       return;
     }
 
+    this.setData({
+      loading: true,
+      phoneBindingRequired: false,
+      returnToPreviousPage,
+      errorMessage: '',
+      webViewUrl: '',
+    });
+
     try {
       const authResult = await resolveAuthResult();
       if (authResult.bindingStatus === 'pending_bind_phone') {
@@ -248,44 +321,56 @@ Page({
           errorMessage: '',
           loading: false,
           phoneBindingRequired: true,
+          returnToPreviousPage,
           webViewUrl: '',
         });
         return;
       }
 
+      if (returnToPreviousPage) {
+        persistAuthResult(authResult);
+        wx.navigateBack();
+        return;
+      }
+
       this.setData({
         authResult,
         errorMessage: '',
         loading: false,
         phoneBindingRequired: false,
+        returnToPreviousPage,
         webViewUrl: resolveWebViewUrl(authResult),
       });
     } catch (error) {
       this.setData({
         authResult: null,
         errorMessage:
-          error && error.message
-            ? error.message
-            : '微信登录失败，请���试。',
+          error && error.message ? error.message : '微信登录失败，请���试。',
         loading: false,
         phoneBindingRequired: false,
+        returnToPreviousPage,
         webViewUrl: '',
       });
     }
   },
 
   onShow() {
-    const result = wx.getStorageSync(PAY_RESULT_STORAGE_KEY);
-    if (!result || !this.data.webViewUrl) {
-      return;
+    const authResult = consumeAuthResult();
+    if (authResult) {
+      this.setData({
+        webViewUrl: resolveWebViewUrl(authResult),
+      });
     }
 
-    wx.removeStorageSync(PAY_RESULT_STORAGE_KEY);
-    this.setData({
-      webViewUrl: appendHashParams(this.data.webViewUrl, {
-        wx_pay_result: result,
-      }),
-    });
+    const result = wx.getStorageSync(PAY_RESULT_STORAGE_KEY);
+    if (result && this.data.webViewUrl) {
+      wx.removeStorageSync(PAY_RESULT_STORAGE_KEY);
+      this.setData({
+        webViewUrl: appendHashParams(this.data.webViewUrl, {
+          wx_pay_result: result,
+        }),
+      });
+    }
   },
 
   async handleGetPhoneNumber(event) {
@@ -318,6 +403,17 @@ Page({
         token: response.token,
         bindingStatus: 'active',
       };
+      if (this.data.returnToPreviousPage) {
+        persistAuthResult(nextAuthResult);
+        this.setData({
+          bindingPhone: false,
+          errorMessage: '',
+          loading: false,
+          phoneBindingRequired: false,
+        });
+        wx.navigateBack();
+        return;
+      }
       this.setData({
         authResult: nextAuthResult,
         bindingPhone: false,
@@ -344,9 +440,10 @@ Page({
       errorMessage: '',
       loading: true,
       phoneBindingRequired: false,
+      returnToPreviousPage: false,
       webViewUrl: '',
     });
-    this.onLoad();
+    this.onLoad(this._lastLaunchQuery || { authAction: AUTH_ACTION_LOGIN });
   },
 
   handleWebViewLoad(event) {
diff --git a/miniprogram/pages/web-view/index.wxml b/miniprogram/pages/web-view/index.wxml
index b9469f31..b8985678 100644
--- a/miniprogram/pages/web-view/index.wxml
+++ b/miniprogram/pages/web-view/index.wxml
@@ -1,5 +1,6 @@
 <block wx:if="{{webViewUrl}}">
   <web-view
+    id="genarrative-web-view"
     src="{{webViewUrl}}"
     bindload="handleWebViewLoad"
     binderror="handleWebViewError"
@@ -19,6 +20,9 @@
     <view wx:if="{{errorMessage}}" class="setup-text setup-text--danger">
       {{errorMessage}}
     </view>
+    <view wx:if="{{returnToPreviousPage}}" class="setup-text">
+      登录完��将自动返回。
+    </view>
     <button
       class="retry-button"
       open-type="getPhoneNumber"
diff --git a/scripts/miniprogram-web-view-auth.test.ts b/scripts/miniprogram-web-view-auth.test.ts
new file mode 100644
index 00000000..108d2a5f
--- /dev/null
+++ b/scripts/miniprogram-web-view-auth.test.ts
@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import vm from 'node:vm';
+
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const repoRoot = process.cwd();
+const pageScriptPath = join(
+  repoRoot,
+  'miniprogram',
+  'pages',
+  'web-view',
+  'index.js',
+);
+
+type MiniProgramPage = {
+  data: Record<string, unknown>;
+  setData: (patch: Record<string, unknown>) => void;
+  onLoad: (query?: Record<string, string>) => Promise<void>;
+};
+
+function createWxMock() {
+  return {
+    getStorageSync: vi.fn(() => ''),
+    getSystemInfoSync: vi.fn(() => ({ platform: 'ios' })),
+    login: vi.fn(),
+    navigateBack: vi.fn(),
+    removeStorageSync: vi.fn(),
+    request: vi.fn(),
+    setStorageSync: vi.fn(),
+  };
+}
+
+function loadWebViewPage(
+  wxMock: ReturnType<typeof createWxMock>,
+  configOverrides: Record<string, unknown> = {},
+) {
+  let pageConfig: Record<string, unknown> | null = null;
+  const source = readFileSync(pageScriptPath, 'utf8');
+  const sandbox = {
+    console,
+    getCurrentPages: () => [],
+    module: { exports: {} },
+    Page(config: Record<string, unknown>) {
+      pageConfig = config;
+    },
+    require(requestPath: string) {
+      if (requestPath === '../../config') {
+        return {
+          API_BASE_URL: 'https://www.genarrative.world/',
+          MINI_PROGRAM_APP_ID: 'wx-test-app',
+          MINI_PROGRAM_ENV: 'release',
+          WEB_VIEW_ENTRY_URL: 'https://www.genarrative.world/',
+          WEB_VIEW_SOURCE_QUERY: {
+            clientType: 'mini_program',
+            clientRuntime: 'wechat_mini_program',
+          },
+          ...configOverrides,
+        };
+      }
+      throw new Error(`Unexpected require: ${requestPath}`);
+    },
+    wx: wxMock,
+  };
+
+  vm.runInNewContext(source, sandbox, { filename: pageScriptPath });
+
+  if (!pageConfig) {
+    throw new Error('web-view page did not call Page()');
+  }
+
+  const page = {
+    ...pageConfig,
+    data: { ...(pageConfig.data as Record<string, unknown>) },
+    setData(patch: Record<string, unknown>) {
+      Object.assign(this.data, patch);
+    },
+  } as MiniProgramPage;
+
+  return page;
+}
+
+describe('mini-program web-view auth page', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('默认进入时直接打开 web-view，�触�微信登录请求', async () => {
+    const wxMock = createWxMock();
+    const page = loadWebViewPage(wxMock);
+
+    await page.onLoad({});
+
+    expect(wxMock.login).not.toHaveBeenCalled();
+    expect(wxMock.request).not.toHaveBeenCalled();
+    expect(page.data.loading).toBe(false);
+    expect(page.data.phoneBindingRequired).toBe(false);
+    expect(page.data.webViewUrl).toBe(
+      'https://www.genarrative.world/?clientType=mini_program&clientRuntime=wechat_mini_program',
+    );
+  });
+
+  test('默认匿�进入 web-view ��赖 API_BASE_URL �置', async () => {
+    const wxMock = createWxMock();
+    const page = loadWebViewPage(wxMock, {
+      API_BASE_URL: '',
+    });
+
+    await page.onLoad({});
+
+    expect(wxMock.login).not.toHaveBeenCalled();
+    expect(wxMock.request).not.toHaveBeenCalled();
+    expect(page.data.errorMessage).toBe('');
+    expect(page.data.webViewUrl).toBe(
+      'https://www.genarrative.world/?clientType=mini_program&clientRuntime=wechat_mini_program',
+    );
+  });
+
+  test('H5 请求登录时��动微信�程�登录并进入手机�授��', async () => {
+    const wxMock = createWxMock();
+    wxMock.login.mockImplementation(({ success }) => {
+      success({ code: 'wx-login-code' });
+    });
+    wxMock.request.mockImplementation(({ success }) => {
+      success({
+        statusCode: 200,
+        data: {
+          token: 'jwt-pending-wechat',
+          bindingStatus: 'pending_bind_phone',
+        },
+      });
+    });
+    const page = loadWebViewPage(wxMock);
+
+    await page.onLoad({ authAction: 'login', returnTo: 'previous' });
+
+    expect(wxMock.login).toHaveBeenCalledTimes(1);
+    expect(wxMock.request).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: 'https://www.genarrative.world/api/auth/wechat/miniprogram-login',
+        method: 'POST',
+        data: { code: 'wx-login-code' },
+      }),
+    );
+    expect(page.data.webViewUrl).toBe('');
+    expect(page.data.loading).toBe(false);
+    expect(page.data.phoneBindingRequired).toBe(true);
+  });
+});
diff --git a/src/components/auth/AuthGate.test.tsx b/src/components/auth/AuthGate.test.tsx
index 3120f30d..d8341460 100644
--- a/src/components/auth/AuthGate.test.tsx
+++ b/src/components/auth/AuthGate.test.tsx
@@ -26,6 +26,8 @@ const authMocks = vi.hoisted(() => ({
   getAuthAuditLogs: vi.fn(),
   getAuthRiskBlocks: vi.fn(),
   getAuthSessions: vi.fn(),
+  isWechatMiniProgramWebViewRuntime: vi.fn(() => false),
+  requestWechatMiniProgramPhoneLogin: vi.fn(),
   revokeAuthSessions: vi.fn(),
   sendPhoneLoginCode: vi.fn(),
   startWechatLogin: vi.fn(),
@@ -52,10 +54,12 @@ vi.mock('../../services/authService', () => ({
   getCurrentAuthUser: authMocks.getCurrentAuthUser,
   getAuthSessions: authMocks.getAuthSessions,
   getCaptchaChallengeFromError: vi.fn(() => null),
+  isWechatMiniProgramWebViewRuntime: authMocks.isWechatMiniProgramWebViewRuntime,
   liftAuthRiskBlock: vi.fn(),
   loginWithPhoneCode: authMocks.loginWithPhoneCode,
   logoutAllAuthSessions: authMocks.logoutAllAuthSessions,
   logoutAuthUser: authMocks.logoutAuthUser,
+  requestWechatMiniProgramPhoneLogin: authMocks.requestWechatMiniProgramPhoneLogin,
   redeemRegistrationInviteCode: authMocks.redeemRegistrationInviteCode,
   resetPassword: authMocks.resetPassword,
   revokeAuthSessions: authMocks.revokeAuthSessions,
@@ -152,6 +156,8 @@ beforeEach(() => {
     expiresInSeconds: 300,
   });
   authMocks.startWechatLogin.mockResolvedValue(undefined);
+  authMocks.isWechatMiniProgramWebViewRuntime.mockReturnValue(false);
+  authMocks.requestWechatMiniProgramPhoneLogin.mockResolvedValue(true);
 });
 
 async function acceptLegalConsent(
@@ -412,6 +418,29 @@ test('auth gate opens a login modal for protected actions and resumes after logi
   expect(screen.queryByRole('dialog', { name: '账�入�' })).toBeNull();
 });
 
+test('auth gate uses mini program auth bridge instead of opening login modal in mini program runtime', async () => {
+  const user = userEvent.setup();
+  authMocks.isWechatMiniProgramWebViewRuntime.mockReturnValue(true);
+  authMocks.getAuthLoginOptions.mockResolvedValue({
+    availableLoginMethods: ['phone', 'wechat'],
+  });
+
+  render(
+    <AuthGate>
+      <ProtectedActionButton onAuthenticated={vi.fn()} />
+    </AuthGate>,
+  );
+
+  await user.click(await screen.findByRole('button', { name: '进入作�' }));
+
+  await waitFor(() => {
+    expect(authMocks.requestWechatMiniProgramPhoneLogin).toHaveBeenCalledTimes(1);
+  });
+  expect(authMocks.startWechatLogin).not.toHaveBeenCalled();
+  expect(screen.queryByRole('dialog', { name: '账�入�' })).toBeNull();
+  expect(authMocks.isWechatMiniProgramWebViewRuntime).toHaveBeenCalled();
+});
+
 test('login modal requires first-time legal consent before sms login', async () => {
   const user = userEvent.setup();
 
diff --git a/src/components/auth/AuthGate.tsx b/src/components/auth/AuthGate.tsx
index e2dc89a6..404764b2 100644
--- a/src/components/auth/AuthGate.tsx
+++ b/src/components/auth/AuthGate.tsx
@@ -32,11 +32,13 @@ import {
   getAuthSessions,
   getCaptchaChallengeFromError,
   getCurrentAuthUser,
+  isWechatMiniProgramWebViewRuntime,
   liftAuthRiskBlock,
   loginWithPhoneCode,
   logoutAllAuthSessions,
   logoutAuthUser,
   redeemRegistrationInviteCode,
+  requestWechatMiniProgramPhoneLogin,
   resetPassword,
   revokeAuthSessions,
   sendPhoneLoginCode,
@@ -276,6 +278,22 @@ export function AuthGate({ children }: AuthGateProps) {
     setInitialSettingsSection(null);
   }, []);
 
+  const requestMiniProgramLogin = useCallback(() => {
+    setWechatLoading(true);
+    setError('');
+    void requestWechatMiniProgramPhoneLogin()
+      .catch((miniProgramError) => {
+        setError(
+          miniProgramError instanceof Error
+            ? miniProgramError.message
+            : '请在微信�程�内完�登录。',
+        );
+      })
+      .finally(() => {
+        setWechatLoading(false);
+      });
+  }, []);
+
   const openLoginModal = useCallback(
     (postLoginAction?: (() => void) | null) => {
       if (readyUser) {
@@ -284,9 +302,15 @@ export function AuthGate({ children }: AuthGateProps) {
       }
 
       pendingProtectedActionRef.current = postLoginAction ?? null;
+      if (isWechatMiniProgramWebViewRuntime()) {
+        setShowLoginModal(false);
+        requestMiniProgramLogin();
+        return;
+      }
+
       setShowLoginModal(true);
     },
-    [readyUser],
+    [readyUser, requestMiniProgramLogin],
   );
 
   const requireAuth = useCallback(
@@ -425,11 +449,26 @@ export function AuthGate({ children }: AuthGateProps) {
       void hydrate(++authHydrateVersionRef.current);
     };
 
+    const handleAuthHashChange = () => {
+      const callbackResult = consumeAuthCallbackResult();
+      if (!callbackResult) {
+        return;
+      }
+      if (callbackResult.error) {
+        setError(callbackResult.error);
+        return;
+      }
+      setStatus('checking');
+      void hydrate(++authHydrateVersionRef.current);
+    };
+
     window.addEventListener(AUTH_STATE_EVENT, handleAuthStateChange);
+    window.addEventListener('hashchange', handleAuthHashChange);
 
     return () => {
       isActive = false;
       window.removeEventListener(AUTH_STATE_EVENT, handleAuthStateChange);
+      window.removeEventListener('hashchange', handleAuthHashChange);
     };
   }, [restoreAuthSession]);
 
diff --git a/src/components/auth/LoginScreen.tsx b/src/components/auth/LoginScreen.tsx
index fc41169e..c255caa4 100644
--- a/src/components/auth/LoginScreen.tsx
+++ b/src/components/auth/LoginScreen.tsx
@@ -7,6 +7,9 @@ import type {
   AuthLoginMethod,
 } from '../../services/authService';
 import { getStoredLastLoginPhone } from '../../services/authService';
+import {
+  isWechatMiniProgramWebViewRuntime,
+} from '../../services/authService';
 import { LegalDocumentModal } from '../common/LegalDocumentModal';
 import {
   getLegalDocument,
@@ -83,6 +86,7 @@ export function LoginScreen({
   const passwordLoginEnabled = true;
   const phoneLoginEnabled = true;
   const wechatLoginEnabled = availableLoginMethods.includes('wechat');
+  const miniProgramRuntime = isWechatMiniProgramWebViewRuntime();
   const [activeLoginTab, setActiveLoginTab] = useState<LoginTab>('phone');
 
   useEffect(() => {
@@ -317,7 +321,7 @@ export function LoginScreen({
                   </button>
                 </div>
 
-                {wechatLoginEnabled ? (
+                {wechatLoginEnabled && !miniProgramRuntime ? (
                   <WechatButton
                     loading={wechatLoading}
                     disabled={submitDisabled}
@@ -364,7 +368,8 @@ export function LoginScreen({
 
             {!passwordLoginEnabled &&
             !phoneLoginEnabled &&
-            !wechatLoginEnabled ? (
+            !wechatLoginEnabled &&
+            !miniProgramRuntime ? (
               <div className="platform-subpanel rounded-2xl px-4 py-4 text-sm text-[var(--platform-text-base)]">
                 当�登录入�暂��用。
               </div>
diff --git a/src/services/authService.test.ts b/src/services/authService.test.ts
index d95502c7..8a925fac 100644
--- a/src/services/authService.test.ts
+++ b/src/services/authService.test.ts
@@ -20,8 +20,8 @@ import { clearStoredAccessToken, getStoredAccessToken } from './apiClient';
 import {
   authEntry,
   bindWechatPhone,
-  changePhoneNumber,
   changePassword,
+  changePhoneNumber,
   consumeAuthCallbackResult,
   getAuthAuditLogs,
   getAuthLoginOptions,
@@ -34,6 +34,7 @@ import {
   loginWithPhoneCode,
   logoutAllAuthSessions,
   redeemRegistrationInviteCode,
+  requestWechatMiniProgramPhoneLogin,
   revokeAuthSession,
   revokeAuthSessions,
   sendPhoneLoginCode,
@@ -408,6 +409,84 @@ describe('authService', () => {
     );
   });
 
+  it('requests mini program phone login by opening the native auth page', async () => {
+    const navigateTo = vi.fn((options: { url: string; success?: () => void }) => {
+      options.success?.();
+    });
+    vi.stubGlobal(
+      'window',
+      createWindowMock({
+        location: {
+          pathname: '/',
+          hash: '',
+          search: '?clientRuntime=wechat_mini_program',
+          assign: vi.fn(),
+        },
+        wx: {
+          miniProgram: {
+            navigateTo,
+          },
+        },
+      }),
+    );
+
+    const result = await requestWechatMiniProgramPhoneLogin();
+
+    expect(result).toBe(true);
+    expect(navigateTo).toHaveBeenCalledWith({
+      url: '/pages/web-view/index?authAction=login&returnTo=previous',
+      success: expect.any(Function),
+      fail: expect.any(Function),
+    });
+  });
+
+  it('waits for an existing WeChat JS SDK script before opening the native auth page', async () => {
+    const navigateTo = vi.fn((options: { url: string; success?: () => void }) => {
+      options.success?.();
+    });
+    const scriptListeners = new Map<string, EventListener>();
+    const existingScript = {
+      addEventListener: vi.fn(
+        (type: string, listener: EventListener) => {
+          scriptListeners.set(type, listener);
+        },
+      ),
+    };
+    vi.stubGlobal(
+      'window',
+      createWindowMock({
+        location: {
+          pathname: '/',
+          hash: '',
+          search: '?clientRuntime=wechat_mini_program',
+          assign: vi.fn(),
+        },
+      }),
+    );
+    vi.stubGlobal('document', {
+      querySelector: vi.fn(() => existingScript),
+      head: {
+        appendChild: vi.fn(),
+      },
+      createElement: vi.fn(),
+    });
+
+    const request = requestWechatMiniProgramPhoneLogin();
+    window.wx = {
+      miniProgram: {
+        navigateTo,
+      },
+    };
+    scriptListeners.get('load')?.(new Event('load'));
+
+    await expect(request).resolves.toBe(true);
+    expect(navigateTo).toHaveBeenCalledWith({
+      url: '/pages/web-view/index?authAction=login&returnTo=previous',
+      success: expect.any(Function),
+      fail: expect.any(Function),
+    });
+  });
+
   it('loads available login methods for the unauthenticated login screen', async () => {
     apiClientMocks.requestJson.mockResolvedValue({
       availableLoginMethods: ['phone', 'wechat'],
diff --git a/src/services/authService.ts b/src/services/authService.ts
index e7002375..0232d51c 100644
--- a/src/services/authService.ts
+++ b/src/services/authService.ts
@@ -20,8 +20,8 @@ import type {
   AuthRiskBlockSummary,
   AuthSessionsResponse,
   AuthSessionSummary,
-  AuthWechatBindPhoneResponse,
   AuthWechatBindPhoneRequest,
+  AuthWechatBindPhoneResponse,
   AuthWechatStartResponse,
   LogoutResponse,
   PublicUserSearchResponse,
@@ -55,6 +55,10 @@ export type ConsumedAuthCallback = {
   error: string | null;
 };
 
+const WECHAT_JS_SDK_URL = 'https://res.wx.qq.com/open/js/jweixin-1.6.0.js';
+const MINI_PROGRAM_AUTH_PAGE_URL =
+  '/pages/web-view/index?authAction=login&returnTo=previous';
+
 // 登录�公开认�入��能误带旧 token，也�能先触� refresh 探测，
 // �则无会�用户点击“获�验���时会先打出一�无�义的 /auth/refresh 401。
 const PUBLIC_AUTH_REQUEST_OPTIONS = {
@@ -80,6 +84,92 @@ export function clearRuntimeGuestTokenCache() {
   runtimeGuestTokenCache.value = null;
 }
 
+export function isWechatMiniProgramWebViewRuntime() {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const params = new URLSearchParams(window.location.search || '');
+  return (
+    params.get('clientRuntime') === 'wechat_mini_program' ||
+    params.get('clientType') === 'mini_program' ||
+    Boolean(window.wx?.miniProgram?.postMessage)
+  );
+}
+
+function loadWechatMiniProgramBridge() {
+  if (typeof window === 'undefined') {
+    return Promise.reject(new Error('请在微信�程�内完�登录'));
+  }
+
+  if (window.wx?.miniProgram?.navigateTo) {
+    return Promise.resolve(window.wx);
+  }
+
+  return new Promise<NonNullable<Window['wx']>>((resolve, reject) => {
+    const existingScript = document.querySelector<HTMLScriptElement>(
+      `script[src="${WECHAT_JS_SDK_URL}"]`,
+    );
+    const complete = () => {
+      if (window.wx?.miniProgram?.navigateTo) {
+        resolve(window.wx);
+      } else {
+        reject(new Error('请在微信�程�内完�登录'));
+      }
+    };
+
+    if (existingScript) {
+      if (window.wx?.miniProgram?.navigateTo) {
+        complete();
+        return;
+      }
+
+      existingScript.addEventListener('load', complete, { once: true });
+      existingScript.addEventListener(
+        'error',
+        () => reject(new Error('请在微信�程�内完�登录')),
+        { once: true },
+      );
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = WECHAT_JS_SDK_URL;
+    script.async = true;
+    script.onload = complete;
+    script.onerror = () => reject(new Error('请在微信�程�内完�登录'));
+    document.head.appendChild(script);
+  });
+}
+
+export async function requestWechatMiniProgramPhoneLogin() {
+  if (!isWechatMiniProgramWebViewRuntime()) {
+    return false;
+  }
+
+  const wxBridge = await loadWechatMiniProgramBridge();
+  const miniProgram = wxBridge.miniProgram;
+  const navigateTo = miniProgram?.navigateTo;
+  if (typeof navigateTo !== 'function') {
+    return false;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    navigateTo({
+      url: MINI_PROGRAM_AUTH_PAGE_URL,
+      success() {
+        resolve();
+      },
+      fail(error) {
+        reject(
+          new Error(error?.errMsg || '请在微信�程�内完�登录'),
+        );
+      },
+    });
+  });
+  return true;
+}
+
 export async function ensureRuntimeGuestToken() {
   if (isRuntimeGuestTokenFresh(runtimeGuestTokenCache.value)) {
     return runtimeGuestTokenCache.value!;