Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

Merge remote-tracking branch 'origin/master'
# Conflicts: # docs/technical/README.md # server-rs/crates/spacetime-client/src/module_bindings/mod.rs
2026-05-01 01:14:18 +08:00 · 2026-05-01 01:14:04 +08:00 · 2026-05-01 00:58:42 +08:00 · 2026-05-01 00:36:42 +08:00 · 2026-04-30 20:49:38 +08:00
56 changed files with 4493 additions and 738 deletions
--- a/.env.local
+++ b/.env.local
@@ -50,6 +50,15 @@ ALIYUN_OSS_ACCESS_KEY_SECRET="XblWGE6CO1WLnSBdMRVpL6lut4GSoS"
 RUST_SERVER_TARGET="http://127.0.0.1:3100"
 GENARRATIVE_API_TARGET="http://127.0.0.1:3100"

+GENARRATIVE_SPACETIME_SERVER_URL="http://127.0.0.1:3101"
+GENARRATIVE_SPACETIME_DATABASE="xushi-p4wfr"
+GENARRATIVE_SPACETIME_TOKEN=""
+
 GENARRATIVE_SPACETIME_MAINCLOUD_SERVER_URL="https://maincloud.spacetimedb.com"
 GENARRATIVE_SPACETIME_MAINCLOUD_DATABASE="xushi-p4wfr"
-GENARRATIVE_SPACETIME_MAINCLOUD_TOKEN="eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMUtQRzVXQlhTTjVCRDAyTjBNSlNONFJCNyIsImlzcyI6Imh0dHBzOi8vYXV0aC5zcGFjZXRpbWVkYi5jb20iLCJhdWQiOiJzcGFjZXRpbWVkYiIsImlhdCI6MTc3NjUxMjAyMiwiZXhwIjoxODM5NTg0MDIyfQ.UguSQDajalekrqs9oiUqLZiWjWK7VTgMQfdLVOhBQZpKX0VYUhNMSok9oBMJ4X655_NxV5TUUXZ4ON4HSJZrMMPc9aZyhS1b3i36vqI_zMPwLrAgfb1MqY5o0wNFl6Y0m0UQ3nsu7ZYxmxxgzF4My7So0Pv75QfXFS3-Uq1-QyO7lCxxgQ6vySbP_PEr7FZJsdPkNvAfP7mTaUh0yaV6SI7jXBsZ_mfdcWtElCNuvR9J3hvfAbx1qyeTgCJtgH4kNhiEOEIAYEFMEQkXd4rdLszmEgtlFubYZPsbMgqeZKx73feU6eGxlYhyPiRHF4AdosIfk3x2MAm_WzOd3efXDQ"
+GENARRATIVE_SPACETIME_MAINCLOUD_TOKEN="eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMUsyN05YUjBaQkRUVEVCNlFQQjFXNzU2MiIsImlzcyI6Imh0dHBzOi8vYXV0aC5zcGFjZXRpbWVkYi5jb20iLCJhdWQiOiJzcGFjZXRpbWVkYiIsImlhdCI6MTc3NzU1NTQ1NiwiZXhwIjoxODQwNjI3NDU2fQ.iy5qN-3lGPQnkya-wsABtqEgRk1VM2XGxTfxuLV5-eTMfX8cR20sWSx7pnoZcLEwYOkz6cEOb4krhMJmTeBax9Z114o_iwISau3wjjHbeKL9or-039zfYfKb3TtJo3_DZaJSu-ECcMZNl4P1zLmtoRSwl-_AMET4sGzPw0_qR-e49_QGDJz1EEhr7aphybl1xCejCebM8XiJjaRz48vL7-lkwBl90uP-0h7Xx8ToTT2h1egmlcYAvaJalVLHIQqzyYxPUT_Zw9TW7VYExZLhJWdGpQzEm0aXZ2fbch9qVrKpZP2xQ9YjppuLxUFFJeQwhmFf6yc67s6J7LqNvL2-ZA"
+
+# admin
+GENARRATIVE_ADMIN_USERNAME=admin
+GENARRATIVE_ADMIN_PASSWORD=123456
+ADMIN_API_TARGET=http://127.0.0.1:8082
--- a/apps/admin-web/index.html
+++ b/apps/admin-web/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>陶泥后台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/apps/admin-web/package.json
+++ b/apps/admin-web/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "@genarrative/admin-web",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "preview": "vite preview --host 127.0.0.1"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^5.0.4",
+    "lucide-react": "^0.546.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": "^6.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~5.8.2"
+  }
+}
--- a/apps/admin-web/src/api/adminApiClient.ts
+++ b/apps/admin-web/src/api/adminApiClient.ts
@@ -0,0 +1,238 @@
+import type {
+  AdminDebugHttpRequest,
+  AdminDebugHttpResponse,
+  AdminDisableProfileRedeemCodeRequest,
+  AdminLoginResponse,
+  AdminMeResponse,
+  AdminOverviewResponse,
+  AdminUpsertProfileInviteCodeRequest,
+  AdminUpsertProfileRedeemCodeRequest,
+  ApiErrorEnvelope,
+  ApiMeta,
+  ApiSuccessEnvelope,
+  ProfileInviteCodeAdminResponse,
+  ProfileRedeemCodeAdminResponse,
+} from './adminApiTypes';
+
+const API_RESPONSE_ENVELOPE_HEADER = 'x-genarrative-response-envelope';
+const ADMIN_API_BASE_URL = normalizeBaseUrl(
+  import.meta.env.VITE_ADMIN_API_BASE_URL ?? '',
+);
+
+interface AdminRequestOptions {
+  method?: string;
+  token?: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export class AdminApiError extends Error {
+  status: number;
+  code: string;
+  details: Record<string, unknown> | null;
+  meta: ApiMeta | null;
+  responseText: string;
+
+  constructor(params: {
+    message: string;
+    status: number;
+    code?: string;
+    details?: Record<string, unknown> | null;
+    meta?: ApiMeta | null;
+    responseText?: string;
+  }) {
+    super(params.message);
+    this.name = 'AdminApiError';
+    this.status = params.status;
+    this.code = params.code ?? 'ADMIN_API_ERROR';
+    this.details = params.details ?? null;
+    this.meta = params.meta ?? null;
+    this.responseText = params.responseText ?? '';
+  }
+}
+
+export function isAdminApiError(error: unknown): error is AdminApiError {
+  return error instanceof AdminApiError;
+}
+
+export function formatAdminApiError(error: unknown) {
+  if (isAdminApiError(error)) {
+    return error.message;
+  }
+
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+
+  return '请求失败';
+}
+
+export async function request<T>(
+  path: string,
+  options: AdminRequestOptions = {},
+): Promise<T> {
+  const method = options.method ?? 'GET';
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    [API_RESPONSE_ENVELOPE_HEADER]: 'v1',
+    ...(options.headers ?? {}),
+  };
+
+  const token = options.token?.trim();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const init: RequestInit = {
+    method,
+    headers,
+    signal: options.signal,
+  };
+
+  if (typeof options.body !== 'undefined') {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(options.body);
+  }
+
+  const response = await fetch(buildRequestUrl(path), init);
+  const responseText = await response.text();
+  const payload = parseJsonResponse(responseText);
+
+  if (!response.ok) {
+    throw buildAdminApiError(response, payload, responseText);
+  }
+
+  return unwrapSuccessPayload<T>(payload);
+}
+
+export function loginAdmin(username: string, password: string) {
+  return request<AdminLoginResponse>('/admin/api/login', {
+    method: 'POST',
+    body: {username, password},
+  });
+}
+
+export function getAdminMe(token: string) {
+  return request<AdminMeResponse>('/admin/api/me', {token});
+}
+
+export function getAdminOverview(token: string) {
+  return request<AdminOverviewResponse>('/admin/api/overview', {token});
+}
+
+export function debugAdminHttp(token: string, payload: AdminDebugHttpRequest) {
+  return request<AdminDebugHttpResponse>('/admin/api/debug/http', {
+    method: 'POST',
+    token,
+    body: payload,
+  });
+}
+
+export function upsertProfileRedeemCode(
+  token: string,
+  payload: AdminUpsertProfileRedeemCodeRequest,
+) {
+  return request<ProfileRedeemCodeAdminResponse>(
+    '/admin/api/profile/redeem-codes',
+    {
+      method: 'POST',
+      token,
+      body: payload,
+    },
+  );
+}
+
+export function upsertProfileInviteCode(
+  token: string,
+  payload: AdminUpsertProfileInviteCodeRequest,
+) {
+  return request<ProfileInviteCodeAdminResponse>(
+    '/admin/api/profile/invite-codes',
+    {
+      method: 'POST',
+      token,
+      body: payload,
+    },
+  );
+}
+
+export function disableProfileRedeemCode(
+  token: string,
+  payload: AdminDisableProfileRedeemCodeRequest,
+) {
+  return request<ProfileRedeemCodeAdminResponse>(
+    '/admin/api/profile/redeem-codes/disable',
+    {
+      method: 'POST',
+      token,
+      body: payload,
+    },
+  );
+}
+
+function normalizeBaseUrl(value: string) {
+  return value.trim().replace(/\/+$/, '');
+}
+
+function buildRequestUrl(path: string) {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${ADMIN_API_BASE_URL}${normalizedPath}`;
+}
+
+function parseJsonResponse(responseText: string): unknown {
+  if (!responseText.trim()) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(responseText) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function unwrapSuccessPayload<T>(payload: unknown): T {
+  if (isRecord(payload) && 'data' in payload) {
+    return (payload as ApiSuccessEnvelope<T>).data as T;
+  }
+
+  return payload as T;
+}
+
+function buildAdminApiError(
+  response: Response,
+  payload: unknown,
+  responseText: string,
+) {
+  const envelope = isRecord(payload) ? (payload as ApiErrorEnvelope) : null;
+  const errorPayload = envelope?.error;
+  const details = isRecord(errorPayload?.details)
+    ? errorPayload.details
+    : null;
+  const detailsMessage =
+    typeof details?.message === 'string' ? details.message.trim() : '';
+  const payloadMessage =
+    typeof errorPayload?.message === 'string' ? errorPayload.message.trim() : '';
+  const topLevelMessage =
+    typeof envelope?.message === 'string' ? envelope.message.trim() : '';
+  const message =
+    detailsMessage ||
+    payloadMessage ||
+    topLevelMessage ||
+    response.statusText ||
+    `HTTP ${response.status}`;
+
+  return new AdminApiError({
+    message,
+    status: response.status,
+    code: errorPayload?.code,
+    details,
+    meta: envelope?.meta ?? null,
+    responseText,
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -0,0 +1,148 @@
+export interface ApiMeta {
+  apiVersion?: string;
+  requestId?: string;
+  routeVersion?: string;
+  operation?: string;
+  latencyMs?: number;
+  timestamp?: string;
+}
+
+export interface ApiErrorPayload {
+  code?: string;
+  message?: string;
+  details?: {
+    message?: string;
+    [key: string]: unknown;
+  } | null;
+}
+
+export interface ApiSuccessEnvelope<T> {
+  ok?: boolean;
+  data?: T;
+  error?: ApiErrorPayload | null;
+  meta?: ApiMeta;
+}
+
+export interface ApiErrorEnvelope {
+  ok?: boolean;
+  data?: unknown;
+  error?: ApiErrorPayload;
+  meta?: ApiMeta;
+  message?: string;
+}
+
+export interface AdminSessionPayload {
+  subject: string;
+  username: string;
+  displayName: string;
+  roles: string[];
+  issuedAt: string;
+  expiresAt: string;
+}
+
+export interface AdminLoginResponse {
+  token: string;
+  admin: AdminSessionPayload;
+}
+
+export interface AdminMeResponse {
+  admin: AdminSessionPayload;
+}
+
+export interface AdminOverviewResponse {
+  service: AdminServiceOverviewPayload;
+  database: AdminDatabaseOverviewPayload;
+}
+
+export interface AdminServiceOverviewPayload {
+  bindHost: string;
+  bindPort: number;
+  jwtIssuer: string;
+  adminEnabled: boolean;
+  spacetimeServerUrl: string;
+  spacetimeDatabase: string;
+}
+
+export interface AdminDatabaseOverviewPayload {
+  databaseIdentity: string | null;
+  ownerIdentity: string | null;
+  hostType: string | null;
+  schemaTableNames: string[];
+  tableStats: AdminDatabaseTableStatPayload[];
+  fetchErrors: string[];
+}
+
+export interface AdminDatabaseTableStatPayload {
+  tableName: string;
+  rowCount: number | null;
+  errorMessage: string | null;
+}
+
+export interface AdminDebugHeaderInput {
+  name: string;
+  value: string;
+}
+
+export type AdminDebugHttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE';
+
+export interface AdminDebugHttpRequest {
+  method: AdminDebugHttpMethod;
+  path: string;
+  headers?: AdminDebugHeaderInput[];
+  body?: string;
+}
+
+export interface AdminDebugHttpResponse {
+  status: number;
+  statusText: string;
+  headers: AdminDebugHeaderInput[];
+  bodyText: string;
+  bodyJson: unknown | null;
+}
+
+export type ProfileRedeemCodeMode = 'public' | 'unique' | 'private';
+
+export interface AdminUpsertProfileRedeemCodeRequest {
+  code: string;
+  mode: ProfileRedeemCodeMode;
+  rewardPoints: number;
+  maxUses: number;
+  enabled: boolean;
+  allowedUserIds: string[];
+  allowedPublicUserCodes: string[];
+}
+
+export interface AdminUpsertProfileInviteCodeRequest {
+  inviteCode: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AdminDisableProfileRedeemCodeRequest {
+  code: string;
+}
+
+export interface ProfileRedeemCodeAdminResponse {
+  code: string;
+  mode: ProfileRedeemCodeMode;
+  rewardPoints: number;
+  maxUses: number;
+  globalUsedCount: number;
+  enabled: boolean;
+  allowedUserIds: string[];
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ProfileInviteCodeAdminResponse {
+  userId: string;
+  inviteCode: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
--- a/apps/admin-web/src/app/AdminApp.tsx
+++ b/apps/admin-web/src/app/AdminApp.tsx
@@ -0,0 +1,177 @@
+import {useCallback, useEffect, useState} from 'react';
+
+import {
+  formatAdminApiError,
+  getAdminMe,
+  isAdminApiError,
+  loginAdmin,
+} from '../api/adminApiClient';
+import type {
+  AdminSessionPayload,
+  ProfileInviteCodeAdminResponse,
+  ProfileRedeemCodeAdminResponse,
+} from '../api/adminApiTypes';
+import {
+  clearStoredAdminToken,
+  getStoredAdminToken,
+  setStoredAdminToken,
+} from '../auth/adminAuthStore';
+import {AdminDebugHttpPage} from '../pages/AdminDebugHttpPage';
+import {AdminInviteCodePage} from '../pages/AdminInviteCodePage';
+import {AdminLoginPage} from '../pages/AdminLoginPage';
+import {AdminOverviewPage} from '../pages/AdminOverviewPage';
+import {AdminRedeemCodePage} from '../pages/AdminRedeemCodePage';
+import {AdminShell} from './AdminShell';
+import type {AdminRouteId} from './adminRoutes';
+import {resolveAdminRoute, routeHash} from './adminRoutes';
+
+type SessionStatus = 'checking' | 'guest' | 'authenticated';
+
+export function AdminApp() {
+  const [status, setStatus] = useState<SessionStatus>('checking');
+  const [admin, setAdmin] = useState<AdminSessionPayload | null>(null);
+  const [token, setToken] = useState('');
+  const [routeId, setRouteId] = useState<AdminRouteId>(() =>
+    resolveAdminRoute(window.location.hash),
+  );
+  const [loginNotice, setLoginNotice] = useState('');
+  // 兑换码页会随页签切换卸载，最近操作记录需要放在会话层保留。
+  const [redeemResult, setRedeemResult] =
+    useState<ProfileRedeemCodeAdminResponse | null>(null);
+  const [inviteResult, setInviteResult] =
+    useState<ProfileInviteCodeAdminResponse | null>(null);
+
+  const clearSession = useCallback((message = '') => {
+    clearStoredAdminToken();
+    setToken('');
+    setAdmin(null);
+    setRedeemResult(null);
+    setInviteResult(null);
+    setStatus('guest');
+    setLoginNotice(message);
+  }, []);
+
+  useEffect(() => {
+    let isMounted = true;
+    const storedToken = getStoredAdminToken();
+
+    if (!storedToken) {
+      setStatus('guest');
+      return;
+    }
+
+    void getAdminMe(storedToken)
+      .then((response) => {
+        if (!isMounted) {
+          return;
+        }
+
+        setToken(storedToken);
+        setAdmin(response.admin);
+        setStatus('authenticated');
+      })
+      .catch((error: unknown) => {
+        if (!isMounted) {
+          return;
+        }
+
+        clearStoredAdminToken();
+        setToken('');
+        setAdmin(null);
+        setStatus('guest');
+        setLoginNotice(
+          isAdminApiError(error) && error.status === 401
+            ? '登录状态已失效'
+            : formatAdminApiError(error),
+        );
+      });
+
+    return () => {
+      isMounted = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    const handleHashChange = () => {
+      setRouteId(resolveAdminRoute(window.location.hash));
+    };
+
+    window.addEventListener('hashchange', handleHashChange);
+    return () => window.removeEventListener('hashchange', handleHashChange);
+  }, []);
+
+  const handleRouteChange = useCallback((nextRouteId: AdminRouteId) => {
+    setRouteId(nextRouteId);
+    const nextHash = routeHash(nextRouteId);
+    if (window.location.hash !== nextHash) {
+      window.location.hash = nextHash;
+    }
+  }, []);
+
+  const handleLogin = useCallback(async (username: string, password: string) => {
+    const response = await loginAdmin(username, password);
+    setStoredAdminToken(response.token);
+    setToken(response.token);
+    setAdmin(response.admin);
+    setRedeemResult(null);
+    setInviteResult(null);
+    setLoginNotice('');
+    setStatus('authenticated');
+  }, []);
+
+  const handleUnauthorized = useCallback(
+    (message = '登录状态已失效') => {
+      clearSession(message);
+    },
+    [clearSession],
+  );
+
+  const handleLogout = useCallback(() => {
+    clearSession('');
+  }, [clearSession]);
+
+  if (status === 'checking') {
+    return (
+      <main className="admin-loading-screen">
+        <div className="admin-loading-mark" />
+        <span>正在校验会话</span>
+      </main>
+    );
+  }
+
+  if (status === 'guest' || !admin || !token) {
+    return <AdminLoginPage notice={loginNotice} onLogin={handleLogin} />;
+  }
+
+  return (
+    <AdminShell
+      admin={admin}
+      routeId={routeId}
+      onLogout={handleLogout}
+      onRouteChange={handleRouteChange}
+    >
+      {routeId === 'overview' ? (
+        <AdminOverviewPage token={token} onUnauthorized={handleUnauthorized} />
+      ) : null}
+      {routeId === 'debug' ? (
+        <AdminDebugHttpPage token={token} onUnauthorized={handleUnauthorized} />
+      ) : null}
+      {routeId === 'redeem' ? (
+        <AdminRedeemCodePage
+          result={redeemResult}
+          token={token}
+          onUnauthorized={handleUnauthorized}
+          onResultChange={setRedeemResult}
+        />
+      ) : null}
+      {routeId === 'invite' ? (
+        <AdminInviteCodePage
+          result={inviteResult}
+          token={token}
+          onUnauthorized={handleUnauthorized}
+          onResultChange={setInviteResult}
+        />
+      ) : null}
+    </AdminShell>
+  );
+}
--- a/apps/admin-web/src/app/AdminShell.tsx
+++ b/apps/admin-web/src/app/AdminShell.tsx
@@ -0,0 +1,110 @@
+import {
+  Bug,
+  LayoutDashboard,
+  LogOut,
+  ShieldCheck,
+  TicketCheck,
+  TicketPercent,
+} from 'lucide-react';
+import type {ReactNode} from 'react';
+
+import type {AdminSessionPayload} from '../api/adminApiTypes';
+import type {AdminRouteId} from './adminRoutes';
+import {adminRoutes} from './adminRoutes';
+
+interface AdminShellProps {
+  admin: AdminSessionPayload;
+  routeId: AdminRouteId;
+  children: ReactNode;
+  onRouteChange: (routeId: AdminRouteId) => void;
+  onLogout: () => void;
+}
+
+const routeIcons = {
+  overview: LayoutDashboard,
+  debug: Bug,
+  redeem: TicketPercent,
+  invite: TicketCheck,
+} satisfies Record<AdminRouteId, typeof LayoutDashboard>;
+
+export function AdminShell({
+  admin,
+  routeId,
+  children,
+  onRouteChange,
+  onLogout,
+}: AdminShellProps) {
+  return (
+    <div className="admin-shell">
+      <aside className="admin-sidebar">
+        <div className="admin-brand">
+          <div className="admin-brand-icon">
+            <ShieldCheck size={20} aria-hidden="true" />
+          </div>
+          <div>
+            <strong>陶泥后台</strong>
+            <span>Admin</span>
+          </div>
+        </div>
+
+        <nav className="admin-nav" aria-label="后台导航">
+          {adminRoutes.map((route) => {
+            const Icon = routeIcons[route.id];
+            return (
+              <button
+                className="admin-nav-button"
+                data-active={route.id === routeId}
+                key={route.id}
+                title={route.label}
+                type="button"
+                onClick={() => onRouteChange(route.id)}
+              >
+                <Icon size={18} aria-hidden="true" />
+                <span>{route.label}</span>
+              </button>
+            );
+          })}
+        </nav>
+      </aside>
+
+      <div className="admin-main">
+        <header className="admin-topbar">
+          <div className="admin-user">
+            <span>{admin.displayName || admin.username}</span>
+            <small>{admin.roles.join(' / ')}</small>
+          </div>
+          <button
+            className="admin-icon-button"
+            title="退出登录"
+            type="button"
+            onClick={onLogout}
+          >
+            <LogOut size={18} aria-hidden="true" />
+            <span>退出</span>
+          </button>
+        </header>
+
+        <main className="admin-content">{children}</main>
+      </div>
+
+      <nav className="admin-bottom-nav" aria-label="后台导航">
+        {adminRoutes.map((route) => {
+          const Icon = routeIcons[route.id];
+          return (
+            <button
+              className="admin-bottom-nav-button"
+              data-active={route.id === routeId}
+              key={route.id}
+              title={route.label}
+              type="button"
+              onClick={() => onRouteChange(route.id)}
+            >
+              <Icon size={19} aria-hidden="true" />
+              <span>{route.label}</span>
+            </button>
+          );
+        })}
+      </nav>
+    </div>
+  );
+}
--- a/apps/admin-web/src/app/adminRoutes.ts
+++ b/apps/admin-web/src/app/adminRoutes.ts
@@ -0,0 +1,30 @@
+export type AdminRouteId = 'overview' | 'debug' | 'redeem' | 'invite';
+
+export interface AdminRouteDefinition {
+  id: AdminRouteId;
+  label: string;
+  hash: string;
+}
+
+export const adminRoutes: AdminRouteDefinition[] = [
+  {id: 'overview', label: '总览', hash: '#overview'},
+  {id: 'debug', label: 'API 调试', hash: '#debug'},
+  {id: 'redeem', label: '兑换码', hash: '#redeem'},
+  {id: 'invite', label: '邀请码', hash: '#invite'},
+];
+
+export function resolveAdminRoute(hash: string): AdminRouteId {
+  const normalizedHash = hash.trim().toLowerCase();
+  return (
+    adminRoutes.find((route) => route.hash === normalizedHash)?.id ??
+    'overview'
+  );
+}
+
+export function routeHash(routeId: AdminRouteId) {
+  return (
+    adminRoutes.find((route) => route.id === routeId)?.hash ??
+    adminRoutes[0]?.hash ??
+    '#overview'
+  );
+}
--- a/apps/admin-web/src/auth/adminAuthStore.ts
+++ b/apps/admin-web/src/auth/adminAuthStore.ts
@@ -0,0 +1,34 @@
+export const ADMIN_TOKEN_STORAGE_KEY = 'genarrative_admin_token';
+
+// 管理员 token 与玩家 token 分开保存，避免后台请求误复用玩家登录态。
+export function getStoredAdminToken() {
+  if (!canUseLocalStorage()) {
+    return '';
+  }
+
+  return window.localStorage.getItem(ADMIN_TOKEN_STORAGE_KEY)?.trim() || '';
+}
+
+export function setStoredAdminToken(token: string) {
+  if (!canUseLocalStorage()) {
+    return;
+  }
+
+  const nextToken = token.trim();
+  if (nextToken) {
+    window.localStorage.setItem(ADMIN_TOKEN_STORAGE_KEY, nextToken);
+    return;
+  }
+
+  window.localStorage.removeItem(ADMIN_TOKEN_STORAGE_KEY);
+}
+
+export function clearStoredAdminToken() {
+  setStoredAdminToken('');
+}
+
+function canUseLocalStorage() {
+  return (
+    typeof window !== 'undefined' && typeof window.localStorage !== 'undefined'
+  );
+}
--- a/apps/admin-web/src/main.tsx
+++ b/apps/admin-web/src/main.tsx
@@ -0,0 +1,18 @@
+import './styles/admin.css';
+
+import {StrictMode} from 'react';
+import {createRoot} from 'react-dom/client';
+
+import {AdminApp} from './app/AdminApp';
+
+const rootElement = document.getElementById('root');
+
+if (!rootElement) {
+  throw new Error('Missing #root container');
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <AdminApp />
+  </StrictMode>,
+);
--- a/apps/admin-web/src/pages/AdminDebugHttpPage.tsx
+++ b/apps/admin-web/src/pages/AdminDebugHttpPage.tsx
@@ -0,0 +1,214 @@
+import {Plus, Send, Trash2} from 'lucide-react';
+import {FormEvent, useMemo, useState} from 'react';
+
+import {debugAdminHttp} from '../api/adminApiClient';
+import type {
+  AdminDebugHeaderInput,
+  AdminDebugHttpMethod,
+  AdminDebugHttpResponse,
+} from '../api/adminApiTypes';
+import {formatUnknownJson, handlePageError} from './pageUtils';
+
+interface AdminDebugHttpPageProps {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}
+
+const httpMethods: AdminDebugHttpMethod[] = [
+  'GET',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+];
+
+export function AdminDebugHttpPage({
+  token,
+  onUnauthorized,
+}: AdminDebugHttpPageProps) {
+  const [method, setMethod] = useState<AdminDebugHttpMethod>('GET');
+  const [path, setPath] = useState('/healthz');
+  const [body, setBody] = useState('');
+  const [headers, setHeaders] = useState<AdminDebugHeaderInput[]>([]);
+  const [result, setResult] = useState<AdminDebugHttpResponse | null>(null);
+  const [errorMessage, setErrorMessage] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const jsonPreview = useMemo(
+    () => formatUnknownJson(result?.bodyJson),
+    [result?.bodyJson],
+  );
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (isSubmitting) {
+      return;
+    }
+
+    setErrorMessage('');
+    setIsSubmitting(true);
+    try {
+      const response = await debugAdminHttp(token, {
+        method,
+        path: path.trim(),
+        headers: headers.filter((header) => header.name.trim()),
+        body,
+      });
+      setResult(response);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  return (
+    <section className="admin-page">
+      <div className="admin-page-heading">
+        <div>
+          <h2>API 调试</h2>
+          <p>受控同源请求</p>
+        </div>
+      </div>
+
+      <div className="admin-two-column">
+        <form className="admin-panel admin-form" onSubmit={handleSubmit}>
+          <div className="admin-form-row">
+            <label className="admin-field admin-field-compact">
+              <span>Method</span>
+              <select
+                value={method}
+                onChange={(event) =>
+                  setMethod(event.target.value as AdminDebugHttpMethod)
+                }
+              >
+                {httpMethods.map((item) => (
+                  <option key={item} value={item}>
+                    {item}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="admin-field admin-field-fill">
+              <span>Path</span>
+              <input
+                value={path}
+                onChange={(event) => setPath(event.target.value)}
+              />
+            </label>
+          </div>
+
+          <section className="admin-subsection">
+            <div className="admin-subsection-heading">
+              <span>Headers</span>
+              <button
+                className="admin-ghost-button"
+                type="button"
+                onClick={() =>
+                  setHeaders((current) => [
+                    ...current,
+                    {name: '', value: ''},
+                  ])
+                }
+              >
+                <Plus size={16} aria-hidden="true" />
+              </button>
+            </div>
+            <div className="admin-header-editor">
+              {headers.map((header, index) => (
+                <div className="admin-header-row" key={index}>
+                  <input
+                    value={header.name}
+                    onChange={(event) =>
+                      setHeaders((current) =>
+                        current.map((item, itemIndex) =>
+                          itemIndex === index
+                            ? {...item, name: event.target.value}
+                            : item,
+                        ),
+                      )
+                    }
+                  />
+                  <input
+                    value={header.value}
+                    onChange={(event) =>
+                      setHeaders((current) =>
+                        current.map((item, itemIndex) =>
+                          itemIndex === index
+                            ? {...item, value: event.target.value}
+                            : item,
+                        ),
+                      )
+                    }
+                  />
+                  <button
+                    className="admin-ghost-button"
+                    title="移除"
+                    type="button"
+                    onClick={() =>
+                      setHeaders((current) =>
+                        current.filter((_, itemIndex) => itemIndex !== index),
+                      )
+                    }
+                  >
+                    <Trash2 size={16} aria-hidden="true" />
+                  </button>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <label className="admin-field">
+            <span>Body</span>
+            <textarea
+              rows={9}
+              value={body}
+              onChange={(event) => setBody(event.target.value)}
+            />
+          </label>
+
+          {errorMessage ? (
+            <div className="admin-alert" role="status">
+              {errorMessage}
+            </div>
+          ) : null}
+
+          <button
+            className="admin-primary-button"
+            disabled={isSubmitting || !path.trim().startsWith('/')}
+            type="submit"
+          >
+            <Send size={17} aria-hidden="true" />
+            <span>{isSubmitting ? '发送中' : '发送'}</span>
+          </button>
+        </form>
+
+        <section className="admin-panel admin-result-panel">
+          <div className="admin-panel-heading">
+            <h3>结果</h3>
+            <span>{result ? `${result.status} ${result.statusText}` : '-'}</span>
+          </div>
+          {result ? (
+            <>
+              <dl className="admin-info-list">
+                <div>
+                  <dt>Status</dt>
+                  <dd>{result.status}</dd>
+                </div>
+                <div>
+                  <dt>Headers</dt>
+                  <dd>{result.headers.length}</dd>
+                </div>
+              </dl>
+              <pre className="admin-code-block">
+                {jsonPreview || result.bodyText || '(empty)'}
+              </pre>
+            </>
+          ) : (
+            <div className="admin-empty-state">暂无结果</div>
+          )}
+        </section>
+      </div>
+    </section>
+  );
+}
--- a/apps/admin-web/src/pages/AdminInviteCodePage.tsx
+++ b/apps/admin-web/src/pages/AdminInviteCodePage.tsx
@@ -0,0 +1,158 @@
+import {Save} from 'lucide-react';
+import {FormEvent, useState} from 'react';
+
+import {upsertProfileInviteCode} from '../api/adminApiClient';
+import type {ProfileInviteCodeAdminResponse} from '../api/adminApiTypes';
+import {handlePageError} from './pageUtils';
+
+interface AdminInviteCodePageProps {
+  token: string;
+  result: ProfileInviteCodeAdminResponse | null;
+  onUnauthorized: (message?: string) => void;
+  onResultChange: (result: ProfileInviteCodeAdminResponse) => void;
+}
+
+export function AdminInviteCodePage({
+  token,
+  result,
+  onUnauthorized,
+  onResultChange,
+}: AdminInviteCodePageProps) {
+  const [inviteCode, setInviteCode] = useState('');
+  const [metadataText, setMetadataText] = useState('{}');
+  const [errorMessage, setErrorMessage] = useState('');
+  const [isSaving, setIsSaving] = useState(false);
+
+  async function handleSave(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (isSaving) {
+      return;
+    }
+
+    setErrorMessage('');
+    setIsSaving(true);
+    try {
+      const response = await upsertProfileInviteCode(token, {
+        inviteCode: inviteCode.trim(),
+        metadata: parseMetadata(metadataText),
+      });
+      onResultChange(response);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsSaving(false);
+    }
+  }
+
+  return (
+    <section className="admin-page">
+      <div className="admin-page-heading">
+        <div>
+          <h2>邀请码</h2>
+          <p>注册链路预置码</p>
+        </div>
+      </div>
+
+      <div className="admin-two-column admin-two-column-wide">
+        <form className="admin-panel admin-form" onSubmit={handleSave}>
+          <label className="admin-field">
+            <span>Invite Code</span>
+            <input
+              autoComplete="off"
+              value={inviteCode}
+              onChange={(event) => setInviteCode(event.target.value)}
+            />
+          </label>
+
+          <label className="admin-field">
+            <span>Metadata JSON</span>
+            <textarea
+              rows={10}
+              spellCheck={false}
+              value={metadataText}
+              onChange={(event) => setMetadataText(event.target.value)}
+            />
+          </label>
+
+          {errorMessage ? (
+            <div className="admin-alert" role="status">
+              {errorMessage}
+            </div>
+          ) : null}
+
+          <button
+            className="admin-primary-button"
+            disabled={isSaving || !inviteCode.trim() || !isMetadataReady(metadataText)}
+            type="submit"
+          >
+            <Save size={17} aria-hidden="true" />
+            <span>{isSaving ? '保存中' : '保存'}</span>
+          </button>
+        </form>
+
+        <section className="admin-panel admin-result-panel">
+          <div className="admin-panel-heading">
+            <h3>记录</h3>
+            <span>{result?.inviteCode ?? '-'}</span>
+          </div>
+          {result ? (
+            <dl className="admin-info-list">
+              <div>
+                <dt>User ID</dt>
+                <dd>{result.userId}</dd>
+              </div>
+              <div>
+                <dt>邀请码</dt>
+                <dd>{result.inviteCode}</dd>
+              </div>
+              <div>
+                <dt>创建</dt>
+                <dd>{result.createdAt}</dd>
+              </div>
+              <div>
+                <dt>更新</dt>
+                <dd>{result.updatedAt}</dd>
+              </div>
+              <div>
+                <dt>Metadata</dt>
+                <dd>
+                  <pre className="admin-code-block">
+                    {JSON.stringify(result.metadata, null, 2)}
+                  </pre>
+                </dd>
+              </div>
+            </dl>
+          ) : (
+            <div className="admin-empty-state">暂无记录</div>
+          )}
+        </section>
+      </div>
+    </section>
+  );
+}
+
+function parseMetadata(value: string): Record<string, unknown> {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return {};
+  }
+
+  const parsed = JSON.parse(trimmed) as unknown;
+  if (!isRecord(parsed)) {
+    throw new Error('Metadata 必须是 JSON 对象');
+  }
+  return parsed;
+}
+
+function isMetadataReady(value: string) {
+  try {
+    parseMetadata(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
--- a/apps/admin-web/src/pages/AdminLoginPage.tsx
+++ b/apps/admin-web/src/pages/AdminLoginPage.tsx
@@ -0,0 +1,83 @@
+import {LockKeyhole, ShieldCheck} from 'lucide-react';
+import {FormEvent, useState} from 'react';
+
+import {formatAdminApiError} from '../api/adminApiClient';
+
+interface AdminLoginPageProps {
+  notice: string;
+  onLogin: (username: string, password: string) => Promise<void>;
+}
+
+export function AdminLoginPage({notice, onLogin}: AdminLoginPageProps) {
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (isSubmitting) {
+      return;
+    }
+
+    setErrorMessage('');
+    setIsSubmitting(true);
+    try {
+      await onLogin(username.trim(), password);
+    } catch (error: unknown) {
+      setErrorMessage(formatAdminApiError(error));
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  return (
+    <main className="admin-login-screen">
+      <form className="admin-login-panel" onSubmit={handleSubmit}>
+        <div className="admin-login-brand">
+          <div className="admin-brand-icon admin-brand-icon-large">
+            <ShieldCheck size={26} aria-hidden="true" />
+          </div>
+          <div>
+            <h1>陶泥后台</h1>
+            <span>Admin Console</span>
+          </div>
+        </div>
+
+        <label className="admin-field">
+          <span>用户名</span>
+          <input
+            autoComplete="username"
+            value={username}
+            onChange={(event) => setUsername(event.target.value)}
+          />
+        </label>
+
+        <label className="admin-field">
+          <span>密码</span>
+          <input
+            autoComplete="current-password"
+            type="password"
+            value={password}
+            onChange={(event) => setPassword(event.target.value)}
+          />
+        </label>
+
+        {notice || errorMessage ? (
+          <div className="admin-alert" role="status">
+            {errorMessage || notice}
+          </div>
+        ) : null}
+
+        <button
+          className="admin-primary-button"
+          disabled={isSubmitting || !username.trim() || !password}
+          type="submit"
+        >
+          <LockKeyhole size={18} aria-hidden="true" />
+          <span>{isSubmitting ? '登录中' : '登录'}</span>
+        </button>
+      </form>
+    </main>
+  );
+}
--- a/apps/admin-web/src/pages/AdminOverviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminOverviewPage.tsx
@@ -0,0 +1,171 @@
+import {RefreshCw} from 'lucide-react';
+import {useCallback, useEffect, useState} from 'react';
+
+import {getAdminOverview} from '../api/adminApiClient';
+import type {
+  AdminDatabaseTableStatPayload,
+  AdminOverviewResponse,
+} from '../api/adminApiTypes';
+import {handlePageError} from './pageUtils';
+
+interface AdminOverviewPageProps {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}
+
+export function AdminOverviewPage({
+  token,
+  onUnauthorized,
+}: AdminOverviewPageProps) {
+  const [overview, setOverview] = useState<AdminOverviewResponse | null>(null);
+  const [errorMessage, setErrorMessage] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+
+  const loadOverview = useCallback(async () => {
+    setIsLoading(true);
+    setErrorMessage('');
+    try {
+      const response = await getAdminOverview(token);
+      setOverview(response);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [onUnauthorized, token]);
+
+  useEffect(() => {
+    void loadOverview();
+  }, [loadOverview]);
+
+  return (
+    <section className="admin-page">
+      <div className="admin-page-heading">
+        <div>
+          <h2>总览</h2>
+          <p>服务与数据库状态</p>
+        </div>
+        <button
+          className="admin-secondary-button"
+          disabled={isLoading}
+          type="button"
+          onClick={() => void loadOverview()}
+        >
+          <RefreshCw size={17} aria-hidden="true" />
+          <span>{isLoading ? '刷新中' : '刷新'}</span>
+        </button>
+      </div>
+
+      {errorMessage ? (
+        <div className="admin-alert" role="status">
+          {errorMessage}
+        </div>
+      ) : null}
+
+      <div className="admin-overview-grid">
+        <InfoPanel
+          title="服务"
+          rows={[
+            ['监听', overview ? `${overview.service.bindHost}:${overview.service.bindPort}` : '-'],
+            ['JWT issuer', overview?.service.jwtIssuer ?? '-'],
+            ['后台', overview?.service.adminEnabled ? '已启用' : '未启用'],
+          ]}
+        />
+        <InfoPanel
+          title="SpacetimeDB"
+          rows={[
+            ['Server', overview?.service.spacetimeServerUrl ?? '-'],
+            ['Database', overview?.service.spacetimeDatabase ?? '-'],
+            ['Identity', overview?.database.databaseIdentity ?? '-'],
+            ['Owner', overview?.database.ownerIdentity ?? '-'],
+            ['Host', overview?.database.hostType ?? '-'],
+          ]}
+        />
+      </div>
+
+      <section className="admin-panel">
+        <div className="admin-panel-heading">
+          <h3>表统计</h3>
+          <span>{overview?.database.schemaTableNames.length ?? 0} tables</span>
+        </div>
+        <div className="admin-table-wrap">
+          <table className="admin-table">
+            <thead>
+              <tr>
+                <th>表</th>
+                <th>行数</th>
+                <th>状态</th>
+              </tr>
+            </thead>
+            <tbody>
+              {(overview?.database.tableStats ?? []).map((stat) => (
+                <TableStatRow key={stat.tableName} stat={stat} />
+              ))}
+              {overview && overview.database.tableStats.length === 0 ? (
+                <tr>
+                  <td colSpan={3}>暂无统计</td>
+                </tr>
+              ) : null}
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      {overview?.database.fetchErrors.length ? (
+        <section className="admin-panel admin-panel-warning">
+          <div className="admin-panel-heading">
+            <h3>读取异常</h3>
+            <span>{overview.database.fetchErrors.length}</span>
+          </div>
+          <ul className="admin-error-list">
+            {overview.database.fetchErrors.map((message) => (
+              <li key={message}>{message}</li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+    </section>
+  );
+}
+
+function InfoPanel({
+  title,
+  rows,
+}: {
+  title: string;
+  rows: Array<[string, string]>;
+}) {
+  return (
+    <section className="admin-panel">
+      <div className="admin-panel-heading">
+        <h3>{title}</h3>
+      </div>
+      <dl className="admin-info-list">
+        {rows.map(([label, value]) => (
+          <div key={label}>
+            <dt>{label}</dt>
+            <dd>{value}</dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}
+
+function TableStatRow({stat}: {stat: AdminDatabaseTableStatPayload}) {
+  return (
+    <tr>
+      <td>{stat.tableName}</td>
+      <td>{typeof stat.rowCount === 'number' ? stat.rowCount : '-'}</td>
+      <td>
+        {stat.errorMessage ? (
+          <span className="admin-status admin-status-error">
+            {stat.errorMessage}
+          </span>
+        ) : (
+          <span className="admin-status admin-status-ok">OK</span>
+        )}
+      </td>
+    </tr>
+  );
+}
--- a/apps/admin-web/src/pages/AdminRedeemCodePage.tsx
+++ b/apps/admin-web/src/pages/AdminRedeemCodePage.tsx
@@ -0,0 +1,275 @@
+import {PowerOff, Save} from 'lucide-react';
+import {FormEvent, useState} from 'react';
+
+import {
+  disableProfileRedeemCode,
+  upsertProfileRedeemCode,
+} from '../api/adminApiClient';
+import type {
+  ProfileRedeemCodeAdminResponse,
+  ProfileRedeemCodeMode,
+} from '../api/adminApiTypes';
+import {handlePageError, splitLines} from './pageUtils';
+
+interface AdminRedeemCodePageProps {
+  token: string;
+  result: ProfileRedeemCodeAdminResponse | null;
+  onUnauthorized: (message?: string) => void;
+  onResultChange: (result: ProfileRedeemCodeAdminResponse) => void;
+}
+
+const redeemModes: Array<{value: ProfileRedeemCodeMode; label: string}> = [
+  {value: 'public', label: '公共码'},
+  {value: 'unique', label: '唯一码'},
+  {value: 'private', label: '私有码'},
+];
+
+export function AdminRedeemCodePage({
+  token,
+  result,
+  onUnauthorized,
+  onResultChange,
+}: AdminRedeemCodePageProps) {
+  const [code, setCode] = useState('');
+  const [mode, setMode] = useState<ProfileRedeemCodeMode>('public');
+  const [rewardPoints, setRewardPoints] = useState('100');
+  const [maxUses, setMaxUses] = useState('1');
+  const [enabled, setEnabled] = useState(true);
+  const [allowedUserIds, setAllowedUserIds] = useState('');
+  const [allowedPublicUserCodes, setAllowedPublicUserCodes] = useState('');
+  const [disableCode, setDisableCode] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+  const [disableErrorMessage, setDisableErrorMessage] = useState('');
+  const [isSaving, setIsSaving] = useState(false);
+  const [isDisabling, setIsDisabling] = useState(false);
+
+  async function handleSave(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (isSaving) {
+      return;
+    }
+
+    setErrorMessage('');
+    setIsSaving(true);
+    try {
+      const response = await upsertProfileRedeemCode(token, {
+        code: code.trim(),
+        mode,
+        rewardPoints: parsePositiveInteger(rewardPoints),
+        maxUses: parsePositiveInteger(maxUses),
+        enabled,
+        allowedUserIds: mode === 'private' ? splitLines(allowedUserIds) : [],
+        allowedPublicUserCodes:
+          mode === 'private' ? splitLines(allowedPublicUserCodes) : [],
+      });
+      onResultChange(response);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsSaving(false);
+    }
+  }
+
+  async function handleDisable(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (isDisabling) {
+      return;
+    }
+
+    setDisableErrorMessage('');
+    setIsDisabling(true);
+    try {
+      const response = await disableProfileRedeemCode(token, {
+        code: disableCode.trim(),
+      });
+      onResultChange(response);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setDisableErrorMessage);
+    } finally {
+      setIsDisabling(false);
+    }
+  }
+
+  return (
+    <section className="admin-page">
+      <div className="admin-page-heading">
+        <div>
+          <h2>兑换码</h2>
+          <p>创建、更新与停用</p>
+        </div>
+      </div>
+
+      <div className="admin-two-column admin-two-column-wide">
+        <form className="admin-panel admin-form" onSubmit={handleSave}>
+          <div className="admin-form-row">
+            <label className="admin-field admin-field-fill">
+              <span>Code</span>
+              <input
+                value={code}
+                onChange={(event) => setCode(event.target.value)}
+              />
+            </label>
+            <label className="admin-switch-field">
+              <input
+                checked={enabled}
+                type="checkbox"
+                onChange={(event) => setEnabled(event.target.checked)}
+              />
+              <span>启用</span>
+            </label>
+          </div>
+
+          <div className="admin-segmented-control" role="tablist">
+            {redeemModes.map((item) => (
+              <button
+                data-active={mode === item.value}
+                key={item.value}
+                type="button"
+                onClick={() => setMode(item.value)}
+              >
+                {item.label}
+              </button>
+            ))}
+          </div>
+
+          <div className="admin-form-row">
+            <label className="admin-field">
+              <span>奖励点数</span>
+              <input
+                min={1}
+                step={1}
+                type="number"
+                value={rewardPoints}
+                onChange={(event) => setRewardPoints(event.target.value)}
+              />
+            </label>
+            <label className="admin-field">
+              <span>最大次数</span>
+              <input
+                min={1}
+                step={1}
+                type="number"
+                value={maxUses}
+                onChange={(event) => setMaxUses(event.target.value)}
+              />
+            </label>
+          </div>
+
+          {mode === 'private' ? (
+            <div className="admin-form-row">
+              <label className="admin-field">
+                <span>内部 userId</span>
+                <textarea
+                  rows={6}
+                  value={allowedUserIds}
+                  onChange={(event) => setAllowedUserIds(event.target.value)}
+                />
+              </label>
+              <label className="admin-field">
+                <span>公开陶泥号</span>
+                <textarea
+                  rows={6}
+                  value={allowedPublicUserCodes}
+                  onChange={(event) =>
+                    setAllowedPublicUserCodes(event.target.value)
+                  }
+                />
+              </label>
+            </div>
+          ) : null}
+
+          {errorMessage ? (
+            <div className="admin-alert" role="status">
+              {errorMessage}
+            </div>
+          ) : null}
+
+          <button
+            className="admin-primary-button"
+            disabled={
+              isSaving ||
+              !code.trim() ||
+              !parsePositiveInteger(rewardPoints) ||
+              !parsePositiveInteger(maxUses)
+            }
+            type="submit"
+          >
+            <Save size={17} aria-hidden="true" />
+            <span>{isSaving ? '保存中' : '保存'}</span>
+          </button>
+        </form>
+
+        <div className="admin-stack">
+          <form className="admin-panel admin-form" onSubmit={handleDisable}>
+            <label className="admin-field">
+              <span>停用 Code</span>
+              <input
+                value={disableCode}
+                onChange={(event) => setDisableCode(event.target.value)}
+              />
+            </label>
+            {disableErrorMessage ? (
+              <div className="admin-alert" role="status">
+                {disableErrorMessage}
+              </div>
+            ) : null}
+            <button
+              className="admin-danger-button"
+              disabled={isDisabling || !disableCode.trim()}
+              type="submit"
+            >
+              <PowerOff size={17} aria-hidden="true" />
+              <span>{isDisabling ? '停用中' : '停用'}</span>
+            </button>
+          </form>
+
+          <section className="admin-panel admin-result-panel">
+            <div className="admin-panel-heading">
+              <h3>记录</h3>
+              <span>{result?.mode ?? '-'}</span>
+            </div>
+            {result ? (
+              <dl className="admin-info-list">
+                <div>
+                  <dt>Code</dt>
+                  <dd>{result.code}</dd>
+                </div>
+                <div>
+                  <dt>奖励</dt>
+                  <dd>{result.rewardPoints}</dd>
+                </div>
+                <div>
+                  <dt>最大次数</dt>
+                  <dd>{result.maxUses}</dd>
+                </div>
+                <div>
+                  <dt>全局已用</dt>
+                  <dd>{result.globalUsedCount}</dd>
+                </div>
+                <div>
+                  <dt>状态</dt>
+                  <dd>{result.enabled ? '启用' : '停用'}</dd>
+                </div>
+                <div>
+                  <dt>创建人</dt>
+                  <dd>{result.createdBy}</dd>
+                </div>
+                <div>
+                  <dt>更新</dt>
+                  <dd>{result.updatedAt}</dd>
+                </div>
+              </dl>
+            ) : (
+              <div className="admin-empty-state">暂无记录</div>
+            )}
+          </section>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function parsePositiveInteger(value: string) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
--- a/apps/admin-web/src/pages/pageUtils.ts
+++ b/apps/admin-web/src/pages/pageUtils.ts
@@ -0,0 +1,33 @@
+import {formatAdminApiError, isAdminApiError} from '../api/adminApiClient';
+
+export function handlePageError(
+  error: unknown,
+  onUnauthorized: (message?: string) => void,
+  setError: (message: string) => void,
+) {
+  if (isAdminApiError(error) && error.status === 401) {
+    onUnauthorized('登录状态已失效');
+    return;
+  }
+
+  setError(formatAdminApiError(error));
+}
+
+export function splitLines(value: string) {
+  return value
+    .split(/\r?\n|,/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function formatUnknownJson(value: unknown) {
+  if (value === null || typeof value === 'undefined') {
+    return '';
+  }
+
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
--- a/apps/admin-web/src/styles/admin.css
+++ b/apps/admin-web/src/styles/admin.css
@@ -0,0 +1,661 @@
+:root {
+  color: #17212b;
+  background: #eef3f6;
+  font-family:
+    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+    "Segoe UI", sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  min-width: 320px;
+  min-height: 100vh;
+  margin: 0;
+  background: #eef3f6;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+}
+
+button {
+  cursor: pointer;
+}
+
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.62;
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.admin-loading-screen,
+.admin-login-screen {
+  display: grid;
+  min-height: 100dvh;
+  place-items: center;
+  padding: 20px;
+}
+
+.admin-loading-screen {
+  gap: 12px;
+  color: #5c6b77;
+}
+
+.admin-loading-mark {
+  width: 24px;
+  height: 24px;
+  border: 3px solid #d1dde6;
+  border-top-color: #126e82;
+  border-radius: 50%;
+  animation: admin-spin 0.8s linear infinite;
+}
+
+.admin-login-screen {
+  background:
+    linear-gradient(145deg, rgba(18, 110, 130, 0.12), transparent 36%),
+    linear-gradient(315deg, rgba(165, 94, 54, 0.12), transparent 34%),
+    #eef3f6;
+}
+
+.admin-login-panel,
+.admin-panel {
+  border: 1px solid #d8e2e8;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 12px 36px rgba(23, 33, 43, 0.08);
+}
+
+.admin-login-panel {
+  display: grid;
+  width: min(100%, 420px);
+  gap: 18px;
+  padding: 28px;
+}
+
+.admin-login-brand,
+.admin-brand {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.admin-login-brand h1 {
+  margin: 0;
+  color: #17212b;
+  font-size: 26px;
+  line-height: 1.16;
+}
+
+.admin-login-brand span,
+.admin-brand span {
+  color: #667682;
+  font-size: 12px;
+}
+
+.admin-brand-icon {
+  display: grid;
+  width: 38px;
+  height: 38px;
+  place-items: center;
+  border: 1px solid #bcd2db;
+  border-radius: 8px;
+  color: #126e82;
+  background: #e7f3f5;
+}
+
+.admin-brand-icon-large {
+  width: 48px;
+  height: 48px;
+}
+
+.admin-shell {
+  display: grid;
+  min-height: 100dvh;
+  grid-template-columns: 232px minmax(0, 1fr);
+}
+
+.admin-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+  border-right: 1px solid #d8e2e8;
+  background: #ffffff;
+  padding: 22px 18px;
+}
+
+.admin-brand strong {
+  display: block;
+  font-size: 17px;
+}
+
+.admin-nav {
+  display: grid;
+  gap: 8px;
+}
+
+.admin-nav-button,
+.admin-bottom-nav-button,
+.admin-icon-button,
+.admin-primary-button,
+.admin-secondary-button,
+.admin-danger-button,
+.admin-ghost-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 8px;
+  white-space: nowrap;
+}
+
+.admin-nav-button {
+  justify-content: flex-start;
+  gap: 10px;
+  min-height: 42px;
+  padding: 0 12px;
+  color: #52616d;
+  background: transparent;
+}
+
+.admin-nav-button[data-active="true"] {
+  color: #0f5666;
+  background: #e7f3f5;
+}
+
+.admin-main {
+  display: grid;
+  min-width: 0;
+  grid-template-rows: 64px minmax(0, 1fr);
+}
+
+.admin-topbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 12px;
+  border-bottom: 1px solid #d8e2e8;
+  background: rgba(255, 255, 255, 0.86);
+  padding: 0 24px;
+}
+
+.admin-user {
+  display: grid;
+  justify-items: end;
+  gap: 2px;
+}
+
+.admin-user span {
+  font-weight: 650;
+}
+
+.admin-user small {
+  color: #667682;
+}
+
+.admin-content {
+  min-width: 0;
+  padding: 24px;
+  overflow: auto;
+}
+
+.admin-page {
+  display: grid;
+  gap: 18px;
+  max-width: 1180px;
+  margin: 0 auto;
+}
+
+.admin-page-heading,
+.admin-panel-heading,
+.admin-subsection-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.admin-page-heading h2,
+.admin-panel-heading h3 {
+  margin: 0;
+  color: #17212b;
+}
+
+.admin-page-heading h2 {
+  font-size: 25px;
+}
+
+.admin-page-heading p {
+  margin: 3px 0 0;
+  color: #667682;
+}
+
+.admin-panel {
+  display: grid;
+  gap: 16px;
+  min-width: 0;
+  padding: 18px;
+}
+
+.admin-panel-heading h3 {
+  font-size: 16px;
+}
+
+.admin-panel-heading span {
+  color: #667682;
+  font-size: 13px;
+}
+
+.admin-panel-warning {
+  border-color: #efc894;
+  background: #fffaf3;
+}
+
+.admin-overview-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.admin-two-column {
+  display: grid;
+  grid-template-columns: minmax(0, 0.9fr) minmax(320px, 1.1fr);
+  gap: 16px;
+  align-items: start;
+}
+
+.admin-two-column-wide {
+  grid-template-columns: minmax(0, 1.1fr) minmax(300px, 0.9fr);
+}
+
+.admin-stack,
+.admin-form {
+  display: grid;
+  gap: 16px;
+}
+
+.admin-form-row {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  align-items: end;
+}
+
+.admin-field {
+  display: grid;
+  min-width: 0;
+  gap: 7px;
+  color: #4c5c68;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.admin-field-fill {
+  min-width: 0;
+}
+
+.admin-field-compact {
+  max-width: 160px;
+}
+
+.admin-field input,
+.admin-field select,
+.admin-field textarea {
+  width: 100%;
+  min-height: 42px;
+  border: 1px solid #cbd8e0;
+  border-radius: 8px;
+  color: #17212b;
+  background: #fbfdfe;
+  padding: 9px 11px;
+  outline: none;
+}
+
+.admin-field textarea {
+  min-height: 112px;
+  resize: vertical;
+}
+
+.admin-field input:focus,
+.admin-field select:focus,
+.admin-field textarea:focus {
+  border-color: #126e82;
+  box-shadow: 0 0 0 3px rgba(18, 110, 130, 0.16);
+}
+
+.admin-switch-field {
+  display: inline-flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  min-height: 42px;
+  color: #4c5c68;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.admin-switch-field input {
+  width: 18px;
+  height: 18px;
+  accent-color: #126e82;
+}
+
+.admin-primary-button,
+.admin-secondary-button,
+.admin-danger-button,
+.admin-icon-button {
+  gap: 8px;
+  min-height: 40px;
+  padding: 0 14px;
+  font-weight: 700;
+}
+
+.admin-primary-button {
+  color: #ffffff;
+  background: #126e82;
+}
+
+.admin-secondary-button,
+.admin-icon-button {
+  border: 1px solid #cbd8e0;
+  color: #2f4550;
+  background: #ffffff;
+}
+
+.admin-danger-button {
+  color: #ffffff;
+  background: #a44242;
+}
+
+.admin-ghost-button {
+  width: 34px;
+  height: 34px;
+  color: #52616d;
+  background: #eef3f6;
+}
+
+.admin-alert {
+  border: 1px solid #efc0bd;
+  border-radius: 8px;
+  color: #8a2f2f;
+  background: #fff4f3;
+  padding: 10px 12px;
+  font-size: 13px;
+}
+
+.admin-info-list {
+  display: grid;
+  gap: 10px;
+  margin: 0;
+}
+
+.admin-info-list div {
+  display: grid;
+  grid-template-columns: minmax(90px, 0.34fr) minmax(0, 1fr);
+  gap: 12px;
+  align-items: baseline;
+}
+
+.admin-info-list dt {
+  color: #667682;
+  font-size: 12px;
+}
+
+.admin-info-list dd {
+  min-width: 0;
+  margin: 0;
+  overflow-wrap: anywhere;
+  color: #17212b;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.admin-table-wrap {
+  overflow: auto;
+}
+
+.admin-table {
+  width: 100%;
+  min-width: 620px;
+  border-collapse: collapse;
+}
+
+.admin-table th,
+.admin-table td {
+  border-bottom: 1px solid #e4edf2;
+  padding: 10px;
+  text-align: left;
+  vertical-align: top;
+}
+
+.admin-table th {
+  color: #667682;
+  font-size: 12px;
+}
+
+.admin-status {
+  display: inline-flex;
+  max-width: 460px;
+  border-radius: 999px;
+  padding: 3px 8px;
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+
+.admin-status-ok {
+  color: #17623c;
+  background: #e6f5ed;
+}
+
+.admin-status-error {
+  color: #8a2f2f;
+  background: #fff1ef;
+}
+
+.admin-error-list {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+  padding-left: 18px;
+  color: #8a5a1b;
+  overflow-wrap: anywhere;
+}
+
+.admin-subsection {
+  display: grid;
+  gap: 10px;
+}
+
+.admin-subsection-heading {
+  color: #4c5c68;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.admin-header-editor {
+  display: grid;
+  gap: 8px;
+}
+
+.admin-header-row {
+  display: grid;
+  grid-template-columns: minmax(0, 0.8fr) minmax(0, 1fr) 34px;
+  gap: 8px;
+  align-items: center;
+}
+
+.admin-header-row input {
+  min-width: 0;
+  min-height: 38px;
+  border: 1px solid #cbd8e0;
+  border-radius: 8px;
+  padding: 8px 10px;
+}
+
+.admin-result-panel {
+  min-height: 260px;
+}
+
+.admin-code-block {
+  max-height: 520px;
+  margin: 0;
+  overflow: auto;
+  border: 1px solid #dce6ec;
+  border-radius: 8px;
+  background: #17212b;
+  color: #e9f2f4;
+  padding: 14px;
+  font-family:
+    "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.admin-empty-state {
+  display: grid;
+  min-height: 140px;
+  place-items: center;
+  border: 1px dashed #cbd8e0;
+  border-radius: 8px;
+  color: #667682;
+  background: #fbfdfe;
+}
+
+.admin-segmented-control {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 6px;
+  border: 1px solid #d8e2e8;
+  border-radius: 8px;
+  background: #eef3f6;
+  padding: 4px;
+}
+
+.admin-segmented-control button {
+  min-height: 36px;
+  border: 0;
+  border-radius: 6px;
+  color: #52616d;
+  background: transparent;
+  font-weight: 700;
+}
+
+.admin-segmented-control button[data-active="true"] {
+  color: #0f5666;
+  background: #ffffff;
+  box-shadow: 0 2px 8px rgba(23, 33, 43, 0.08);
+}
+
+.admin-bottom-nav {
+  display: none;
+}
+
+@keyframes admin-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (max-width: 980px) {
+  .admin-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .admin-sidebar {
+    display: none;
+  }
+
+  .admin-main {
+    grid-template-rows: 58px minmax(0, 1fr);
+  }
+
+  .admin-topbar {
+    justify-content: space-between;
+    padding: 0 14px;
+  }
+
+  .admin-content {
+    padding: 16px 14px 86px;
+  }
+
+  .admin-overview-grid,
+  .admin-two-column,
+  .admin-two-column-wide,
+  .admin-form-row {
+    grid-template-columns: 1fr;
+  }
+
+  .admin-field-compact {
+    max-width: none;
+  }
+
+  .admin-bottom-nav {
+    position: fixed;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 20;
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    border-top: 1px solid #d8e2e8;
+    background: rgba(255, 255, 255, 0.94);
+    padding: 8px 10px calc(8px + env(safe-area-inset-bottom));
+    backdrop-filter: blur(10px);
+  }
+
+  .admin-bottom-nav-button {
+    display: grid;
+    gap: 4px;
+    min-height: 48px;
+    color: #667682;
+    background: transparent;
+    font-size: 11px;
+    font-weight: 700;
+  }
+
+  .admin-bottom-nav-button[data-active="true"] {
+    color: #0f5666;
+    background: #e7f3f5;
+  }
+}
+
+@media (max-width: 560px) {
+  .admin-login-panel,
+  .admin-panel {
+    padding: 16px;
+  }
+
+  .admin-login-brand h1,
+  .admin-page-heading h2 {
+    font-size: 22px;
+  }
+
+  .admin-info-list div {
+    grid-template-columns: 1fr;
+    gap: 3px;
+  }
+
+  .admin-header-row {
+    grid-template-columns: 1fr;
+  }
+
+  .admin-header-row .admin-ghost-button {
+    width: 100%;
+  }
+
+  .admin-icon-button span {
+    display: none;
+  }
+}
--- a/apps/admin-web/src/vite-env.d.ts
+++ b/apps/admin-web/src/vite-env.d.ts
@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_ADMIN_API_BASE_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
--- a/apps/admin-web/tsconfig.json
+++ b/apps/admin-web/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": false,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "allowJs": false,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}
--- a/apps/admin-web/vite.config.ts
+++ b/apps/admin-web/vite.config.ts
@@ -0,0 +1,43 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import react from '@vitejs/plugin-react';
+import {defineConfig, loadEnv} from 'vite';
+
+const adminWebRoot = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(adminWebRoot, '../..');
+
+export default defineConfig(({mode}) => {
+  const repoEnv = loadEnv(mode, repoRoot, '');
+  const appEnv = loadEnv(mode, adminWebRoot, '');
+  const env = {...repoEnv, ...appEnv};
+  const apiTarget =
+    env.ADMIN_API_TARGET ||
+    env.GENARRATIVE_API_TARGET ||
+    `http://127.0.0.1:${env.GENARRATIVE_API_PORT || '3100'}`;
+
+  return {
+    root: adminWebRoot,
+    envDir: repoRoot,
+    plugins: [react()],
+    server: {
+      proxy: {
+        '/admin/api': {
+          target: apiTarget,
+          changeOrigin: true,
+          secure: false,
+        },
+        '/healthz': {
+          target: apiTarget,
+          changeOrigin: true,
+          secure: false,
+        },
+      },
+    },
+    build: {
+      outDir: 'dist',
+      emptyOutDir: true,
+      chunkSizeWarningLimit: 600,
+    },
+  };
+});
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,9 +11,9 @@
 - [规划与优先级](./planning/README.md)：当前阶段的迭代排序与落地优先级。
 - [参考目录](./reference/README.md)：脚本/Function 速查入口。
  重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
- [PRD](./prd)：产品需求与阶段计划；新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)。
+- [PRD](./prd)：产品需求与阶段计划；后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)。

-SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和 Jenkins 数据库迁移流水线见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)。
+SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和 Jenkins 数据库迁移流水线见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。

 ## 推荐阅读顺序

--- a/docs/prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md
+++ b/docs/prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md
@@ -0,0 +1,168 @@
+# 后台管理独立前端工程 PRD
+
+日期：`2026-04-30`
+
+## 1. 目标
+
+本 PRD 定义当前项目的后台管理独立前端工程 v1。目标不是重做一套后端，也不是把玩家端前端改造成后台，而是在 monorepo 内新增一个独立管理端应用，正式承接已经从 `api-server` 内嵌页面移出的后台 UI。
+
+首版目标：
+
+1. 后台 UI 独立落在 `apps/admin-web`，不再写入 Rust 源码字符串。
+2. 管理数据、业务规则、权限校验和写操作继续统一走 `server-rs/crates/api-server`。
+3. v1 只接管已有管理能力：管理员登录、当前管理员信息、服务/数据库概览、受控 API 调试、兑换码管理、注册邀请码管理。
+4. 保持管理端清爽、可扫读、移动端可用，不在界面堆大段规则说明。
+
+## 2. 用户与使用场景
+
+### 2.1 目标用户
+
+1. 项目开发者：用于本地或测试环境快速查看 `api-server` 与 SpacetimeDB 连接状态。
+2. 运维/运营人员：用于创建、更新、停用兑换码，预置注册邀请码，以及确认后台接口是否可用。
+3. 后续后台功能开发者：以本工程作为后续用户、作品、资产、审核等管理模块的承载壳。
+
+### 2.2 首版高频场景
+
+1. 管理员打开后台登录页，输入环境变量配置的管理员用户名和密码。
+2. 登录后进入总览页，确认当前服务监听、JWT issuer、SpacetimeDB server/database、schema 表数量和关键表统计。
+3. 在 API 调试页对当前 `api-server` 的同源相对路径发起受控请求，排查接口状态。
+4. 在兑换码管理页创建或更新公共码、唯一码、私有码，并在需要时停用兑换码。
+5. 在邀请码管理页创建或更新注册链路使用的邀请码与 metadata。
+
+## 3. 功能范围
+
+### 3.1 包含
+
+1. 独立前端工程骨架：`apps/admin-web`。
+2. 登录页：
+   - 调用 `POST /admin/api/login`。
+   - 登录成功后保存管理员 Bearer token。
+   - 登录失败直接展示后端返回的错误消息。
+3. 管理端 Shell：
+   - 顶部显示当前管理员、登录状态和退出按钮。
+   - 侧边或底部导航包含“总览”“API 调试”“兑换码”“邀请码”。
+   - 移动端导航改为底部或顶部紧凑标签。
+4. 总览页：
+   - 调用 `GET /admin/api/me` 恢复管理员会话。
+   - 调用 `GET /admin/api/overview` 展示服务和数据库概览。
+   - 表统计允许部分失败，并直接展示失败项。
+5. API 调试页：
+   - 调用 `POST /admin/api/debug/http`。
+   - 只允许填写同源相对路径，不提供绝对 URL 输入暗示。
+   - 调试结果在独立结果面板展示状态码、响应头、响应文本和 JSON 预览。
+6. 兑换码管理页：
+   - 调用 `POST /admin/api/profile/redeem-codes` 创建/更新兑换码。
+   - 调用 `POST /admin/api/profile/redeem-codes/disable` 停用兑换码。
+   - 支持 `public`、`unique`、`private` 三种模式。
+   - 私有码支持输入内部 `userId` 和公开陶泥号，提交给后端统一解析。
+7. 邀请码管理页：
+   - 调用 `POST /admin/api/profile/invite-codes` 创建/更新注册邀请码。
+   - 支持输入 JSON 对象 metadata，提交前做基础 JSON 对象校验，最终校验以服务端为准。
+
+### 3.2 不包含
+
+1. 不新建后台专用后端服务、BFF、Express 服务或 PostgreSQL 数据面。
+2. 不让管理端直接连接 SpacetimeDB TypeScript SDK。
+3. 不新增 SpacetimeDB 表结构。
+4. 不实现完整用户管理、作品审核、资产审核、充值订单后台。
+5. 不实现多角色权限体系、管理员 refresh session、多端会话管理。
+6. 不保留 `GET /admin` 同源内嵌页面作为正式后台入口。
+
+## 4. 页面与交互要求
+
+### 4.1 登录页
+
+登录页只保留必要输入和状态反馈：
+
+1. 用户名输入框。
+2. 密码输入框。
+3. 登录按钮。
+4. 登录失败状态。
+5. 后台未启用状态。
+
+后台未启用时，前端根据 `POST /admin/api/login` 的 `503` 响应展示不可登录状态，不额外引导用户在页面配置环境变量。
+
+### 4.2 总览页
+
+总览页必须能快速扫读：
+
+1. 服务状态：监听地址、端口、JWT issuer。
+2. SpacetimeDB 配置：server URL、database。
+3. 数据库元信息：database identity、owner identity、host type。
+4. 表清单与表统计：展示成功计数和失败原因。
+
+总览页不展示任意 SQL 输入框。
+
+### 4.3 API 调试页
+
+API 调试页是受控接口调试台，不是通用代理工具：
+
+1. method 使用选择控件。
+2. path 只接受 `/xxx` 形式。
+3. headers 使用结构化键值编辑。
+4. body 使用文本框。
+5. 结果展示在固定结果面板，不在按钮下方临时插入内容。
+
+### 4.4 兑换码管理页
+
+兑换码管理页首版采用一个创建/更新表单和一个停用表单：
+
+1. code：提交前可在前端 trim，但最终标准化以服务端为准。
+2. mode：`public`、`unique`、`private`。
+3. rewardPoints：必须为正整数，最终校验以服务端为准。
+4. maxUses：必须为正整数，最终校验以服务端为准。
+5. enabled：创建/更新时可切换。
+6. allowedUserIds：私有码允许的内部用户 ID 列表。
+7. allowedPublicUserCodes：私有码允许的公开陶泥号列表。
+
+提交成功后展示后端返回的兑换码记录；失败时展示后端错误消息。
+
+### 4.5 邀请码管理页
+
+邀请码管理页首版采用一个创建/更新表单和一个结果面板：
+
+1. inviteCode：提交前可在前端 trim，最终标准化以服务端为准。
+2. metadata：必须是 JSON 对象；空值按 `{}` 提交。
+3. 提交成功后展示后端返回的 userId、inviteCode、createdAt、updatedAt 和 metadata。
+4. 失败时展示后端错误消息。
+
+## 5. 数据与权限边界
+
+1. 管理端所有请求必须经过 `/admin/api/*`。
+2. 管理端持有的管理员 token 只用于后台接口，不复用玩家登录 token。
+3. 普通玩家 token 访问管理接口应被后端拒绝。
+4. 管理端不持久化密码。
+5. token 首版可保存在 localStorage；退出登录时立即清除。
+6. SpacetimeDB 表、reducer、procedure、迁移和权限判断均不由管理端直接处理。
+
+## 6. 验收标准
+
+1. `apps/admin-web` 可以独立启动和构建。
+2. 登录页可完成管理员登录，错误和未启用状态展示清楚。
+3. 登录后刷新页面可通过 `GET /admin/api/me` 恢复会话。
+4. 总览页可展示 `GET /admin/api/overview` 的服务与数据库数据。
+5. API 调试页可通过后端调试接口访问 `/healthz`。
+6. 兑换码管理页可创建/更新、停用兑换码，并展示返回记录。
+7. 邀请码管理页可创建/更新注册邀请码，并展示返回记录。
+8. `GET /admin` 保持 404，不恢复旧内嵌页面。
+9. `npm run check:encoding` 通过。
+
+## 7. 首版任务拆解
+
+首版编码按以下模块收口，避免独立后台工程继续扩散成未定义功能：
+
+1. 工程骨架：创建 `apps/admin-web`，补齐 Vite、TypeScript、React 入口和独立构建脚本。
+2. API client：只封装 `/admin/api/*`，统一处理 Bearer token、统一 envelope 和后端错误消息。
+3. 登录与会话：实现登录、启动恢复、`401` 清理、退出登录四个状态流。
+4. 页面 Shell：实现桌面侧栏/顶部栏与移动端紧凑导航，不在未登录状态渲染后台导航。
+5. 总览页：展示 `service`、`database`、`tableStats`、`fetchErrors`，部分失败不阻断整页。
+6. API 调试页：实现 method、path、headers、body 输入和独立结果面板。
+7. 兑换码页：实现创建/更新、停用、三种 mode 切换和私有码用户列表输入。
+8. 邀请码页：实现注册邀请码创建/更新、metadata JSON 对象输入和最近记录展示。
+9. 验证：完成后台工程 typecheck/build、根工程编码检查，以及 `/admin` 仍为 404 的后端验证。
+
+## 8. 交互修正记录
+
+### 8.1 兑换码记录页签保持
+
+兑换码管理页的“记录”面板展示最近一次创建、更新或停用接口返回的兑换码记录。该记录在管理端会话内切换“总览”“API 调试”“兑换码”页签时必须保留，避免运营人员切页核对信息后丢失刚返回的结果。退出登录、登录新会话或刷新浏览器页面时可以清空该前端会话态；持久化查询能力后续由新的后端查询接口承接，不在首版用前端伪造历史列表。
--- a/docs/prd/MY_TAB_INVITE_CODE_REDEMPTION_PRD_2026-04-16.md
+++ b/docs/prd/MY_TAB_INVITE_CODE_REDEMPTION_PRD_2026-04-16.md
@@ -2,6 +2,8 @@

 更新时间：`2026-04-16`

+> 2026-04-30 更新：用户侧邀请码填写入口已迁到注册环节，当前落地以 `docs/technical/PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md` 为准；“我的 Tab”不再保留填邀请码入口。
+
 ## 0. 目标

 把“填邀请码”做成用户激活早期的一次性绑定动作，完成：
--- a/docs/technical/ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md
+++ b/docs/technical/ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md
@@ -2,6 +2,10 @@

 日期：`2026-04-23`

+更新：`2026-04-30`
+
+> 状态说明：本文件中的管理员鉴权、`/admin/api/*` 管理接口、数据库概览与受控 API 调试设计继续有效；同源内嵌 HTML/CSS/JS 后台页面已废弃。后续后台 UI 迁移到独立前端工程，当前 `api-server` 不再挂载 `GET /admin` 页面入口。独立后台前端的产品边界见 [`../prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md`](../prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，技术方案见 [`ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md`](./ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
+
 ## 1. 目标

 为当前 Rust `api-server` 增加一套同源后台管理服务，满足以下首版目标：
@@ -10,7 +14,7 @@
 2. 支持独立的管理员鉴权，不允许普通玩家 JWT 越权访问。
 3. 支持在后台查看当前服务与数据库概览信息。
 4. 支持在后台测试当前 `api-server` 已挂载接口。
-5. 保持首版工程足够轻量，不新建额外独立服务进程，不引入第二套前端工程。
+5. 保持管理能力继续收口在 `server-rs`，管理 UI 由独立后台前端工程承接。

 ## 2. 背景与约束

@@ -24,19 +28,20 @@

 1. 后端统一落在 `server-rs`，不回退到 `server-node`。
 2. 不额外新起独立管理服务进程。
-3. 首版以“一个受保护管理域 + 一个同源后台页面”为落地形态。
+3. 管理 API 继续作为受保护管理域挂载在 `api-server`。
 4. 数据库信息必须尽量读取真实数据库侧信息，不能只展示硬编码假数据。

 ## 3. 首版范围

 ### 3.1 包含

-1. `GET /admin`：后台管理页面入口。
-2. `POST /admin/api/login`：管理员用户名密码登录。
-3. `GET /admin/api/me`：当前管理员会话信息。
-4. `GET /admin/api/overview`：服务与数据库概览。
-5. `POST /admin/api/debug/http`：受控 HTTP 接口调试。
-6. 基于 Bearer JWT 的管理员鉴权中间件。
+1. `POST /admin/api/login`：管理员用户名密码登录。
+2. `GET /admin/api/me`：当前管理员会话信息。
+3. `GET /admin/api/overview`：服务与数据库概览。
+4. `POST /admin/api/debug/http`：受控 HTTP 接口调试。
+5. `POST /admin/api/profile/redeem-codes`：兑换码创建/更新。
+6. `POST /admin/api/profile/redeem-codes/disable`：兑换码停用。
+7. 基于 Bearer JWT 的管理员鉴权中间件。

 ### 3.2 不包含

@@ -44,7 +49,7 @@
 2. 管理员 refresh cookie / 多端会话管理。
 3. 后台直接写库、删库、执行 reducer。
 4. 任意 SQL 执行器。
-5. 新建独立 React/Vite 管理端工程。
+5. `api-server` 内嵌 HTML/CSS/JS 后台页面。

 ## 4. 总体方案

@@ -60,13 +65,13 @@

 ### 4.2 页面形态

-后台管理页面采用 `api-server` 直接返回一份内嵌 HTML/CSS/JS 的管理页。
+后台管理页面不再由 `api-server` 直接返回内嵌 HTML/CSS/JS。`api-server` 仅保留管理 API，页面由独立后台前端工程调用这些接口。

 原因：

-1. 首版目标是“可用的后台能力”，不是新建一套复杂前端基建。
-2. 管理页面交互相对简单，直接内嵌更易随服务端一起部署。
-3. 可以避免新增构建链和静态资源发布路径。
+1. 管理 UI 需要独立演进，不应继续堆在 Rust 源码字符串中。
+2. `server-rs` 继续负责鉴权、聚合和写操作，符合前端只做表现的工程约束。
+3. 删除 `GET /admin` 后，当前服务访问该路径应返回 `404`。

 ### 4.3 数据库信息来源

@@ -129,7 +134,7 @@ claims 设计：

 ## 6. 后台页面设计

-首版页面包含三个主区域：
+本节已由独立后台前端工程方案接管。历史同源页面曾包含三个主区域：

 1. 登录卡片。
 2. 数据库概览面板。
@@ -223,7 +228,7 @@ claims 设计：

 默认策略：

-1. 若未配置用户名或密码，则后台登录接口返回 `503`，后台页面显示“后台未启用”。
+1. 若未配置用户名或密码，则后台登录接口返回 `503`，独立后台前端自行展示未启用状态。
 2. 默认管理员 token TTL 为 `4` 小时。

 ## 10. 测试要求
@@ -240,21 +245,27 @@ claims 设计：

 ## 11. 路由清单

-首版新增路由：
+当前保留的管理 API 路由：

-1. `GET /admin`
-2. `POST /admin/api/login`
-3. `GET /admin/api/me`
-4. `GET /admin/api/overview`
-5. `POST /admin/api/debug/http`
+1. `POST /admin/api/login`
+2. `GET /admin/api/me`
+3. `GET /admin/api/overview`
+4. `POST /admin/api/debug/http`
+5. `POST /admin/api/profile/redeem-codes`
+6. `POST /admin/api/profile/redeem-codes/disable`
+
+`GET /admin` 已取消挂载，后续由独立后台前端工程承接页面入口。

 ## 12. 完成定义

-满足以下条件时，本任务视为完成：
+当前管理 API 保留与内嵌页面移除满足以下条件时，本任务视为完成：

 1. `api-server` 内存在受保护后台管理域。
 2. 管理员用户名密码可登录。
 3. 普通用户 token 无法访问后台接口。
 4. 后台能看到服务和数据库真实概览。
 5. 后台能调试当前服务 HTTP 接口。
-6. 路由索引与技术文档已同步更新。
+6. 兑换码管理 API 可由管理员 token 调用。
+7. `GET /admin` 不再挂载，访问返回 `404`。
+8. 独立后台前端 PRD 与技术方案已补齐。
+9. 路由索引与技术文档已同步更新。
--- a/docs/technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md
+++ b/docs/technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md
@@ -0,0 +1,446 @@
+# 后台管理独立前端工程技术方案
+
+日期：`2026-04-30`
+
+对应 PRD：[后台管理独立前端工程 PRD](../prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)
+
+落地状态：`2026-04-30` 已创建 `apps/admin-web` 独立前端工程，包含登录、总览、API 调试、兑换码管理和注册邀请码管理首版页面；根工程已补 `admin-web:*` 转发脚本。
+
+## 1. 结论
+
+后台管理端采用独立前端工程，路径固定为 `apps/admin-web`。它只负责 UI 表现、输入采集、请求发起和结果渲染；所有鉴权、聚合、写操作、SpacetimeDB 访问和业务校验继续收口在 `server-rs/crates/api-server`。
+
+本方案接管旧 `api-server` 内嵌 HTML/CSS/JS 页面，旧 `GET /admin` 不再挂载。后续后台入口由独立前端工程部署产物承接。
+
+## 2. 工程结构
+
+建议首版结构：
+
+```text
+apps/
+└─ admin-web/
+   ├─ index.html
+   ├─ package.json
+   ├─ tsconfig.json
+   ├─ vite.config.ts
+   └─ src/
+      ├─ main.tsx
+      ├─ app/
+      │  ├─ AdminApp.tsx
+      │  ├─ AdminShell.tsx
+      │  └─ adminRoutes.ts
+      ├─ api/
+      │  ├─ adminApiClient.ts
+      │  └─ adminApiTypes.ts
+      ├─ auth/
+      │  └─ adminAuthStore.ts
+      ├─ pages/
+      │  ├─ AdminLoginPage.tsx
+      │  ├─ AdminOverviewPage.tsx
+      │  ├─ AdminDebugHttpPage.tsx
+      │  ├─ AdminRedeemCodePage.tsx
+      │  └─ AdminInviteCodePage.tsx
+      └─ styles/
+         └─ admin.css
+```
+
+首版可使用独立 `package.json`，不要求立刻把根工程改成 npm workspace。后续如果根工程统一 workspace，再把 `apps/admin-web` 纳入统一脚本。
+
+## 3. 技术栈
+
+1. React + TypeScript + Vite。
+2. 图标使用 `lucide-react`。
+3. 样式首版使用普通 CSS 或 CSS Modules，不引入新的大型 UI 组件库。
+4. 请求使用浏览器 `fetch` 封装，不新增状态管理库。
+5. 不引入 SpacetimeDB TypeScript SDK；管理端不直连 SpacetimeDB。
+
+## 4. API 边界
+
+### 4.1 基础约定
+
+所有管理端请求使用同一个 `adminApiClient`：
+
+1. base URL 由 `VITE_ADMIN_API_BASE_URL` 配置。
+2. 未配置时默认同源空前缀。
+3. 有 token 时附加 `Authorization: Bearer <token>`。
+4. 后端统一响应 envelope 时，前端读取 `data`；错误优先读取 `error.details.message`，再读 `error.message`，最后回退到 HTTP 状态。
+
+前端统一按以下响应形状解析，不在页面组件里重复拆 envelope：
+
+```ts
+export interface ApiSuccessEnvelope<T> {
+  data: T;
+  meta?: unknown;
+}
+
+export interface ApiErrorEnvelope {
+  error?: {
+    code?: string;
+    message?: string;
+    details?: {
+      message?: string;
+      [key: string]: unknown;
+    } | null;
+  };
+  meta?: unknown;
+}
+```
+
+`adminApiClient` 暴露 `request<T>()`、`get<T>()`、`post<T>()` 三层即可。页面只拿到成功数据或抛出的中文错误消息，不直接处理 `Response`。
+
+### 4.2 已有管理接口
+
+| 功能 | 方法与路径 | 鉴权 |
+| --- | --- | --- |
+| 管理员登录 | `POST /admin/api/login` | 无 |
+| 当前管理员 | `GET /admin/api/me` | 管理员 Bearer |
+| 服务与数据库概览 | `GET /admin/api/overview` | 管理员 Bearer |
+| 受控 HTTP 调试 | `POST /admin/api/debug/http` | 管理员 Bearer |
+| 创建/更新兑换码 | `POST /admin/api/profile/redeem-codes` | 管理员 Bearer |
+| 停用兑换码 | `POST /admin/api/profile/redeem-codes/disable` | 管理员 Bearer |
+| 创建/更新注册邀请码 | `POST /admin/api/profile/invite-codes` | 管理员 Bearer |
+
+### 4.3 前端类型命名
+
+后台前端首版不引入自动生成 contract。为了避免字段漂移，`apps/admin-web/src/api/adminApiTypes.ts` 必须按 `shared-contracts` 的 camelCase JSON 字段命名：
+
+```ts
+export interface AdminSessionPayload {
+  subject: string;
+  username: string;
+  displayName: string;
+  roles: string[];
+  issuedAt: string;
+  expiresAt: string;
+}
+
+export interface AdminLoginResponse {
+  token: string;
+  admin: AdminSessionPayload;
+}
+
+export interface AdminOverviewResponse {
+  service: AdminServiceOverviewPayload;
+  database: AdminDatabaseOverviewPayload;
+}
+
+export interface AdminServiceOverviewPayload {
+  bindHost: string;
+  bindPort: number;
+  jwtIssuer: string;
+  adminEnabled: boolean;
+  spacetimeServerUrl: string;
+  spacetimeDatabase: string;
+}
+
+export interface AdminDatabaseOverviewPayload {
+  databaseIdentity: string | null;
+  ownerIdentity: string | null;
+  hostType: string | null;
+  schemaTableNames: string[];
+  tableStats: AdminDatabaseTableStatPayload[];
+  fetchErrors: string[];
+}
+
+export interface AdminDatabaseTableStatPayload {
+  tableName: string;
+  rowCount: number | null;
+  errorMessage: string | null;
+}
+
+export interface AdminDebugHeaderInput {
+  name: string;
+  value: string;
+}
+
+export interface AdminDebugHttpRequest {
+  method: string;
+  path: string;
+  headers?: AdminDebugHeaderInput[];
+  body?: string;
+}
+
+export interface AdminDebugHttpResponse {
+  status: number;
+  statusText: string;
+  headers: AdminDebugHeaderInput[];
+  bodyText: string;
+  bodyJson: unknown | null;
+}
+```
+
+兑换码类型同样保持 camelCase：
+
+```ts
+export type ProfileRedeemCodeMode = 'public' | 'unique' | 'private';
+
+export interface AdminUpsertProfileRedeemCodeRequest {
+  code: string;
+  mode: ProfileRedeemCodeMode;
+  rewardPoints: number;
+  maxUses: number;
+  enabled: boolean;
+  allowedUserIds: string[];
+  allowedPublicUserCodes: string[];
+}
+
+export interface AdminDisableProfileRedeemCodeRequest {
+  code: string;
+}
+
+export interface AdminUpsertProfileInviteCodeRequest {
+  inviteCode: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ProfileRedeemCodeAdminResponse {
+  code: string;
+  mode: ProfileRedeemCodeMode;
+  rewardPoints: number;
+  maxUses: number;
+  globalUsedCount: number;
+  enabled: boolean;
+  allowedUserIds: string[];
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ProfileInviteCodeAdminResponse {
+  userId: string;
+  inviteCode: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### 4.4 登录 contract
+
+请求：
+
+```json
+{
+  "username": "root",
+  "password": "secret123"
+}
+```
+
+成功数据：
+
+```json
+{
+  "token": "<admin bearer token>",
+  "admin": {
+    "subject": "admin:root",
+    "username": "root",
+    "displayName": "root",
+    "roles": ["admin"],
+    "issuedAt": "2026-04-30T00:00:00Z",
+    "expiresAt": "2026-04-30T04:00:00Z"
+  }
+}
+```
+
+`503` 表示后台未启用；`401` 表示用户名或密码错误。
+
+### 4.5 总览 contract
+
+`GET /admin/api/overview` 返回：
+
+1. `service`：`bindHost`、`bindPort`、`jwtIssuer`、`adminEnabled`、`spacetimeServerUrl`、`spacetimeDatabase`。
+2. `database`：`databaseIdentity`、`ownerIdentity`、`hostType`、`schemaTableNames`、`tableStats`、`fetchErrors`。
+
+后端读取 SpacetimeDB schema 时必须请求 `/v1/database/{database}/schema?version=9`。SpacetimeDB 2.x schema HTTP API 缺少 `version` query 会返回 `400 missing field version`，后台页面只能展示读取异常，不能拿到真实表名。
+
+后端读取表行数时必须按 SpacetimeDB 2.x `/sql` 响应解析：接口返回 statement result 数组，单条结果内的 `schema.elements` 描述列名，`rows` 是按列顺序排列的数组行，例如 `rows: [[0]]`。后台服务不能再假设响应是 `{ rows: [{ row_count: 0 }] }` 的对象行形状；为了兼容小版本差异，可保留对象行兜底解析。
+
+`tableStats` 中单表失败必须展示 `errorMessage`，不能让整页变成空白。
+
+### 4.6 API 调试 contract
+
+请求：
+
+```json
+{
+  "method": "GET",
+  "path": "/healthz",
+  "headers": [],
+  "body": ""
+}
+```
+
+限制由后端执行：
+
+1. `path` 只允许同源相对路径。
+2. 禁止绝对 URL。
+3. 禁止调试 `/admin/api/login`。
+4. 禁止覆盖危险请求头。
+5. 请求体大小和超时由后端收口。
+
+### 4.7 兑换码管理 contract
+
+创建/更新请求：
+
+```json
+{
+  "code": "WELCOME2026",
+  "mode": "public",
+  "rewardPoints": 100,
+  "maxUses": 1,
+  "enabled": true,
+  "allowedUserIds": [],
+  "allowedPublicUserCodes": []
+}
+```
+
+停用请求：
+
+兑换码管理页的最近一次接口返回记录由 `AdminApp` 维护为管理端会话态，并传入 `AdminRedeemCodePage` 渲染。页面页签通过 hash 切换时子页面会卸载，不能把最近记录只放在兑换码页面内部 `useState` 中，否则切换到其他页签再返回会展示“暂无记录”。该会话态只用于保留当前操作结果，不作为兑换码历史列表；退出登录或重新登录时清空。
+
+```json
+{
+  "code": "WELCOME2026"
+}
+```
+
+成功返回兑换码记录：
+
+```json
+{
+  "code": "WELCOME2026",
+  "mode": "public",
+  "rewardPoints": 100,
+  "maxUses": 1,
+  "globalUsedCount": 0,
+  "enabled": true,
+  "allowedUserIds": [],
+  "createdBy": "admin:root",
+  "createdAt": "2026-04-30T00:00:00Z",
+  "updatedAt": "2026-04-30T00:00:00Z"
+}
+```
+
+前端只做基础输入约束，最终标准化、私有码用户解析、次数和奖励合法性以 `server-rs` 为准。
+
+### 4.8 邀请码管理 contract
+
+创建/更新请求：
+
+```json
+{
+  "inviteCode": "SPRING2026",
+  "metadata": {
+    "batch": "spring"
+  }
+}
+```
+
+成功返回邀请码记录：
+
+```json
+{
+  "userId": "admin",
+  "inviteCode": "SPRING2026",
+  "metadata": {
+    "batch": "spring"
+  },
+  "createdAt": "2026-04-30T00:00:00Z",
+  "updatedAt": "2026-04-30T00:00:00Z"
+}
+```
+
+邀请码页的 metadata 输入必须先在前端解析为 JSON 对象；空字符串按 `{}` 处理，数组、字符串、数字等非对象值直接提示错误。最终标准化、长度限制和邀请码合法性以 `server-rs` 为准。
+
+## 5. 鉴权与会话
+
+1. token key 固定为 `genarrative_admin_token`。
+2. token 首版存 localStorage。
+3. 应用启动时如果存在 token，先调用 `GET /admin/api/me`。
+4. `401` 时清空 token 并回到登录页。
+5. `403` 时展示无权限状态，不自动重试。
+6. 退出登录只清理本地 token；首版没有后台 refresh session 和服务端会话吊销。
+
+## 6. 页面实现要点
+
+1. `AdminShell` 承载导航、当前管理员、退出按钮和页面容器。
+2. 登录页不进入 `AdminShell`，避免未登录时展示后台导航。
+3. 总览页加载失败时展示后端错误，不吞掉 `fetchErrors`。
+4. API 调试页的 headers 使用键值行编辑，提交前转为 `[{ name, value }]`。
+5. 兑换码页的 `mode=private` 时展示允许用户输入区；其他模式提交空数组。
+6. 邀请码页只提交 `inviteCode` 与 JSON 对象 metadata，不在前端复制后端邀请码规则。
+7. 所有按钮的 loading 状态必须锁定重复提交。
+8. 移动端优先：表单单列，导航紧凑，结果面板可横向/纵向滚动。
+
+## 7. 部署与联调
+
+### 7.1 本地联调
+
+1. 启动后端：`npm run api-server:maincloud`。
+2. 启动后台前端：在 `apps/admin-web` 执行 `npm run dev`。
+3. 后台 dev server 通过 Vite proxy 转发 `/admin/api` 到 `ADMIN_API_TARGET`；未配置时默认 `http://127.0.0.1:3100`。
+4. 若使用非 3100 端口，在仓库根目录 `.env.local` 设置 `ADMIN_API_TARGET=http://127.0.0.1:<api-server-port>`，并重启后台前端 dev server。
+5. `GENARRATIVE_API_PORT` 控制 Rust `api-server` 监听端口；`ADMIN_API_TARGET` 只控制后台前端 dev proxy 目标，二者需要指向同一个端口。
+
+### 7.2 构建部署
+
+首版构建产物由独立后台工程输出到 `apps/admin-web/dist`。部署可以选择：
+
+1. 独立静态站点域名，例如 `https://admin.example.com`。
+2. 与主站同域不同路径，由网关把后台静态资源和 `/admin/api/*` 分别路由到正确目标。
+
+无论哪种方式，`server-rs` 仍然是唯一管理 API 后端。
+
+### 7.3 后台工程脚本
+
+`apps/admin-web/package.json` 首版至少提供以下脚本：
+
+```json
+{
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "preview": "vite preview --host 127.0.0.1"
+  }
+}
+```
+
+如果后续接入根 npm workspace，再在根 `package.json` 增加转发脚本；本轮不要为了后台工程强行重排现有前端脚本。
+
+当前根工程同步提供以下转发脚本：
+
+1. `npm run admin-web:dev`
+2. `npm run admin-web:typecheck`
+3. `npm run admin-web:build`
+4. `npm run admin-web:preview`
+
+## 8. 测试计划
+
+1. `apps/admin-web`：
+   - 登录成功和失败。
+   - token 恢复、过期清理、退出登录。
+   - 总览页正常数据、部分表统计失败、整体请求失败。
+   - API 调试成功访问 `/healthz`，绝对 URL 被后端拒绝。
+   - 兑换码 public/unique/private 表单提交和停用。
+   - 邀请码表单提交、metadata JSON 对象校验和结果展示。
+2. 根工程：
+   - `npm run check:encoding`。
+   - 后续接入根 workspace 后，补充后台工程 build/typecheck 脚本。
+3. 后端：
+   - 继续保留 `cargo test -p api-server --manifest-path server-rs/Cargo.toml admin`。
+   - 修改后端管理 API 后必须运行 `npm run api-server:maincloud` 并手动验证 `/admin` 为 404、`/admin/api/login` 可用。
+
+## 9. 后续扩展边界
+
+后续新增用户管理、作品审核、资产审核、订单/充值管理时，必须先补对应 PRD 和技术方案，并在 `server-rs` 增加受保护管理 API。不要让 `apps/admin-web` 直接读取 SpacetimeDB 或复制业务规则。
+
+## 10. 实施顺序
+
+1. 先创建 `apps/admin-web` 工程骨架，确保空应用可 `dev/build`。
+2. 再实现 `adminApiTypes` 与 `adminApiClient`，用 `/admin/api/login` 做第一条真实链路。
+3. 接入 `adminAuthStore` 和启动恢复逻辑，确认 `401` 会清理本地 token。
+4. 完成 `AdminShell` 与四页路由，再分别接入总览、API 调试、兑换码和邀请码接口。
+5. 最后补测试、运行 `npm run check:encoding`，并确认 `GET /admin` 仍由 `api-server` 返回 `404`。
+
+当前实现已完成第 1 至第 4 步。验证以实际命令输出为准。
--- a/docs/technical/PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md
+++ b/docs/technical/PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md
@@ -0,0 +1,55 @@
+# 注册环节邀请码与管理员邀请码方案
+
+更新时间：`2026-04-30`
+
+## 背景
+
+旧版“我的 Tab 填邀请码”设计把邀请码绑定放在登录后的个人面板中，容易让老账号重复发现入口，也不利于承接带邀请码的分享链接。本方案将邀请码填写收口到注册链路：未登录用户打开带 `inviteCode` 或 `invite_code` 查询参数的链接时，前端自动打开注册弹窗并预填邀请码。
+
+## 落地边界
+
+1. 注册入口复用当前手机号验证码登录自动建号能力，不新增独立注册系统。
+2. 已登录用户不自动弹注册弹窗；登录后的“我的 Tab”只保留“邀请好友”，不再提供“填邀请码”入口。
+3. 邀请码只在本次手机号验证码登录创建新账号时尝试绑定。老账号登录时即使请求体带邀请码，也不会绑定。
+4. 链接邀请码无效或不可用时不阻断注册，登录响应返回短错误提示，由前端展示；不写邀请关系、不发邀请奖励。
+5. 普通登录态下的 `/api/profile/referrals/redeem-code` 不再允许手动填码，统一返回“邀请码仅注册时填写”。
+
+## 数据与接口
+
+`profile_invite_code` 增加 `metadata_json` 字段，默认 `{}`，用于保存渠道、活动、批次等元数据。旧迁移导入数据缺失该字段时由 `migration.rs` 补 `{}`。
+
+新增管理员接口：
+
+- `POST /admin/api/profile/invite-codes`
+
+请求：
+
+```json
+{
+  "inviteCode": "SPRING2026",
+  "metadata": {
+    "campaign": "spring"
+  }
+}
+```
+
+管理员邀请码写入 SpacetimeDB 时使用虚拟主体：
+
+```text
+admin:{管理员用户名}:{邀请码}
+```
+
+管理员码只做归因和被邀请人奖励，不给虚拟主体写邀请人钱包流水。
+
+手机号登录响应新增：
+
+- `created`：本次登录是否创建新账号。
+- `referral`：注册邀请码绑定结果；仅当本次提交了邀请码时返回。
+
+## 验收标准
+
+1. 未登录用户访问 `/?inviteCode=ABC123` 自动打开注册弹窗并预填 `ABC123`。
+2. 有效邀请码注册成功后，被邀请人获得陶泥币奖励，邀请关系落库。
+3. 无效邀请码注册成功但不绑定，并返回短提示。
+4. 管理员可添加邀请码并写入 metadata，重复提交同管理员同码更新 metadata。
+5. 管理员邀请码被使用时不产生 `admin:*` 虚拟主体的钱包流水。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -5,6 +5,7 @@
 ## 文档列表

 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
+- [PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md](./PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md)：冻结邀请码从“我的 Tab 填写”迁到注册环节的前后端边界、`profile_invite_code.metadata_json` 表结构扩展、管理员邀请码虚拟主体和奖励规则。
 - [MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md](./MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md)：冻结抓大鹅 Match3D 首版 demo 的独立玩法域、表与 procedure、HTTP facade、前端即时反馈/后端权威确认协议，以及可并行开发包。
 - [MATCH3D_DOMAIN_AND_CONTRACTS_STAGE1_2026-04-30.md](./MATCH3D_DOMAIN_AND_CONTRACTS_STAGE1_2026-04-30.md)：冻结抓大鹅 Match3D B1+B2 的纯领域规则 crate、Rust/TypeScript shared contracts，以及 Stage1 不触碰 SpacetimeDB 表和 api-server 的边界。
 - [MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md](./MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md)：记录抓大鹅 F1 创作入口、Agent 工作区、参考图入口、本地 mock client 与后续 B5 HTTP facade 替换点。
@@ -13,6 +14,7 @@
 - [PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md](./PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md)：记录平台首页底部 dock 在手机浏览器地址栏展开时脱离可见区域的根因，以及 `100dvh`、固定底部锚点和安全区占位的修复口径。
 - [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
 - [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。
+- [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)：冻结后台管理独立前端工程 `apps/admin-web` 的技术方案，明确管理端只做表现、全部数据和写操作走 `server-rs` 的 `/admin/api/*`，并接管旧 `GET /admin` 内嵌页面的 UI 职责。
 - [RPG_PROMPT_FRONTEND_REMOVAL_AND_SERVER_RS_MIGRATION_2026-04-28.md](./RPG_PROMPT_FRONTEND_REMOVAL_AND_SERVER_RS_MIGRATION_2026-04-28.md)：冻结 RPG 提示词禁止存在前端的边界，明确前端只保留 API client，角色私聊/NPC 对话/剧情续写等 prompt 统一收口到 `server-rs`。
 - [RPG_CREATION_RESULT_VIEW_BACKEND_TRUTH_MIGRATION_2026-04-28.md](./RPG_CREATION_RESULT_VIEW_BACKEND_TRUTH_MIGRATION_2026-04-28.md)：冻结 RPG 创作结果页保存、Agent session/result preview 真相优先级和结果页入口裁决迁移到后端 result-view 的落地边界。
 - [RPG_CREATION_PROFILE_GENERATION_BACKEND_MIGRATION_2026-04-28.md](./RPG_CREATION_PROFILE_GENERATION_BACKEND_MIGRATION_2026-04-28.md)：记录 RPG 创作 profile 生成移除非浏览器 legacy AI 回退，统一通过 `server-rs` 的 `/api/runtime/custom-world/profile` 生成世界底稿。
@@ -53,7 +55,7 @@
 - [CREATION_AGENT_PUBLISH_GATE_NORMALIZE_WRITEBACK_FIX_2026-04-24.md](./CREATION_AGENT_PUBLISH_GATE_NORMALIZE_WRITEBACK_FIX_2026-04-24.md)：记录结果页 profile 归一化回写丢失顶层 `worldHook / playerPremise` 导致 publish gate 继续误报结构 blocker 的根因，并冻结前端归一化保留发布字段的修复口径。

 - [CUSTOM_WORLD_RESULT_ENTITY_GENERATION_FIX_2026-04-24.md](./CUSTOM_WORLD_RESULT_ENTITY_GENERATION_FIX_2026-04-24.md)：记录世界结果页在 Agent 草稿模式下新增场景、新增 NPC 生成成功但结果页字段不可用的根因，并冻结 `api-server` 生成归一化层补齐 profile 字段的修复口径。
- [ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md](./ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md)：冻结 Rust `api-server` 内后台管理服务首版方案，明确管理员用户名密码登录、管理员 JWT 鉴权、数据库概览、受控 API 调试台与同源管理页面的落地边界。
+- [ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md](./ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md)：冻结 Rust `api-server` 内后台管理 API 首版方案；同源内嵌页面已取消，管理员登录、管理员 JWT 鉴权、数据库概览、受控 API 调试台和兑换码管理 API 保留给独立后台前端工程复用。
 - [SPACETIME_MODULE_LIB_RS_SPLIT_EXECUTION_2026-04-23.md](./SPACETIME_MODULE_LIB_RS_SPLIT_EXECUTION_2026-04-23.md)：冻结 `server-rs/crates/spacetime-module/src/lib.rs` 的模块地图、二级落位点与迁移顺序，要求后续 SpacetimeDB 主工程改动按对应模块落位，不再继续堆回单大文件。
 - [CUSTOM_WORLD_DRAFT_FOUNDATION_API_SERVER_LLM_MIGRATION_2026-04-23.md](./CUSTOM_WORLD_DRAFT_FOUNDATION_API_SERVER_LLM_MIGRATION_2026-04-23.md)：冻结 `draft_foundation` 从 SpacetimeDB 内部规则编译迁到 `api-server + platform-llm` 的边界，明确草稿必须由 `api-server` 真实调 LLM 生成，SpacetimeDB 只负责落库。
 - [CUSTOM_WORLD_AGENT_LLM_REPLY_RESTORE_2026-04-22.md](./CUSTOM_WORLD_AGENT_LLM_REPLY_RESTORE_2026-04-22.md)：恢复 Custom World Agent 聊天必须走大模型推理的 Rust 落地方案，冻结 submit/finalize 两阶段职责、旧 Node 提示词原样搬运、SSE 流式回复与 session 回写边界。
@@ -70,7 +72,7 @@
 - [JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md](./JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md)：冻结 Jenkins `构建 / 部署 / 构建并部署` 三条流水线的职责、版本号传递、上游触发门禁、本地目录部署脚本、发布包覆盖策略，以及部署阶段 SpacetimeDB schema 冲突自动导出、清库发布、导入回灌能力。
 - [JENKINS_DEPLOY_ENV_BOM_FIX_2026-04-25.md](./JENKINS_DEPLOY_ENV_BOM_FIX_2026-04-25.md)：记录 Jenkins 部署时 `.env.local` 首行 UTF-8 BOM 导致 `start.sh` 加载失败的根因，并冻结发布包构建、部署脚本和启动脚本的环境文件净化规则。
 - [RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md](./RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md)：冻结 Rust 本地一键联调脚本与 Ubuntu 发布包构建脚本的执行口径，覆盖 `npm run dev:rust`、`npm run build:rust:ubuntu`、Vite release、Linux `api-server`、SpacetimeDB wasm、启动停止脚本、默认 scp 上传、安全清库开关，以及发布包内 schema 冲突自动迁移脚本。
- [RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md](./RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md)：记录当前 Rust `api-server` 已挂载的 101 条 Axum 路由，并补充管理后台入口与管理接口索引，按 auth、assets、runtime、custom world、story、generated path 等挂载面归类，用于对照 Node 能力基线与切流 smoke 清单。
+- [RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md](./RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md)：记录当前 Rust `api-server` 已挂载的 Axum 路由，并补充管理 API 索引，按 auth、assets、runtime、custom world、story、generated path 等挂载面归类，用于对照 Node 能力基线与切流 smoke 清单。
 - [BACKEND_REWRITE_CROSS_CUTTING_GOVERNANCE_2026-04-22.md](./BACKEND_REWRITE_CROSS_CUTTING_GOVERNANCE_2026-04-22.md)：冻结后端重写收口阶段的横向治理规则，覆盖 TypeScript contract 到 Rust DTO 映射、SpacetimeDB schema 演进、大对象 / workflow cache 存储边界和文档维护门禁。
 - [PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md](./PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md)：`platform-llm` 文本模型网关首版设计，冻结 OpenAI 兼容 `/chat/completions`、SSE 增量解析、错误模型与重试边界。
 - [API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md](./API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md)：`api-server` 接入 `platform-llm` 的最小代理设计，冻结 `/api/llm/chat/completions` 的配置、状态注入与首版非流式兼容边界。
--- a/docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md
+++ b/docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md
@@ -1,6 +1,6 @@
 # Rust API Server 路由索引（2026-04-23）

-更新时间：`2026-04-23`
+更新时间：`2026-04-30`

 ## 1. 文档目标

@@ -10,9 +10,9 @@

 ## 2. 当前统计

-当前 Rust `api-server` 从 `app.rs` 可抽取到 `101` 条路由：
+当前 Rust `api-server` 从 `app.rs` 可抽取到 `102` 条路由：

-1. 管理后台接口：`5` 条。
+1. 管理后台 API：`6` 条。
 2. 内部鉴权调试接口：`2` 条。
 3. AI task 接口：`9` 条。
 4. assets / OSS 接口：`15` 条。
@@ -26,13 +26,16 @@

 ## 3. 路由清单

-### 3.1 管理后台
+### 3.1 管理后台 API

-1. `GET /admin`
-2. `POST /admin/api/login`
-3. `GET /admin/api/me`
-4. `GET /admin/api/overview`
-5. `POST /admin/api/debug/http`
+1. `POST /admin/api/login`
+2. `GET /admin/api/me`
+3. `GET /admin/api/overview`
+4. `POST /admin/api/debug/http`
+5. `POST /admin/api/profile/redeem-codes`
+6. `POST /admin/api/profile/redeem-codes/disable`
+
+`GET /admin` 同源内嵌页面入口已取消挂载，后台 UI 后续由独立前端工程承接。

 ### 3.2 内部鉴权调试

--- a/package.json
+++ b/package.json
@@ -8,6 +8,10 @@
    "dev:rust": "node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh",
    "dev:rust:logs": "node scripts/run-bash-script.mjs scripts/spacetime-logs-local.sh",
    "dev:web": "node scripts/dev-web-rust.mjs",
+    "admin-web:dev": "npm --prefix apps/admin-web run dev --",
+    "admin-web:build": "npm --prefix apps/admin-web run build --",
+    "admin-web:typecheck": "npm --prefix apps/admin-web run typecheck --",
+    "admin-web:preview": "npm --prefix apps/admin-web run preview --",
    "spacetime:publish:maincloud": "node scripts/run-bash-script.mjs scripts/spacetime-publish-maincloud.sh",
    "spacetime:generate": "node scripts/generate-spacetime-bindings.mjs",
    "api-server:maincloud": "node scripts/api-server-maincloud.mjs",
--- a/packages/shared/src/contracts/auth.ts
+++ b/packages/shared/src/contracts/auth.ts
@@ -65,7 +65,7 @@ export type AuthPasswordResetResponse = {

 export type AuthPhoneSendCodeRequest = {
  phone: string;
-  scene?: 'login' | 'bind_phone' | 'change_phone';
+  scene?: 'login' | 'bind_phone' | 'change_phone' | 'reset_password';
  captchaChallengeId?: string;
  captchaAnswer?: string;
 };
@@ -80,11 +80,23 @@ export type AuthPhoneSendCodeResponse = {
 export type AuthPhoneLoginRequest = {
  phone: string;
  code: string;
+  inviteCode?: string;
 };

 export type AuthPhoneLoginResponse = {
  token: string;
  user: AuthUser;
+  created: boolean;
+  referral: AuthPhoneLoginReferral | null;
+};
+
+export type AuthPhoneLoginReferral = {
+  ok: boolean;
+  message: string | null;
+  inviteeRewardGranted: boolean;
+  inviterRewardGranted: boolean;
+  inviteeBalanceAfter: number | null;
+  inviterBalanceAfter: number | null;
 };

 export type AuthMeResponse = {
--- a/packages/shared/src/contracts/runtime.ts
+++ b/packages/shared/src/contracts/runtime.ts
@@ -176,6 +176,19 @@ export type RedeemProfileRewardCodeResponse = {
  ledgerEntry: ProfileWalletLedgerEntry;
 };

+export type AdminUpsertProfileInviteCodeRequest = {
+  inviteCode: string;
+  metadata?: Record<string, unknown> | null;
+};
+
+export type ProfileInviteCodeAdminResponse = {
+  userId: string;
+  inviteCode: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
 export type ProfilePlayedWorkSummary = {
  worldKey: string;
  ownerUserId: string | null;
--- a/server-rs/crates/api-server/src/admin.rs
+++ b/server-rs/crates/api-server/src/admin.rs
@@ -11,7 +11,7 @@ use axum::{
        header::{AUTHORIZATION, CONTENT_TYPE},
    },
    middleware::Next,
-    response::{Html, Response},
+    response::Response,
 };
 use reqwest::Client;
 use serde::Deserialize;
@@ -76,6 +76,9 @@ const DATABASE_OVERVIEW_TABLES: &[&str] = &[
    "asset_object",
    "asset_entity_binding",
 ];
+// SpacetimeDB 2.x 的 schema HTTP API 要求显式传入 BSATN JSON 版本。
+// 后台总览只读取表名，固定使用当前 CLI 2.1.0 兼容的版本参数即可。
+const SPACETIME_SCHEMA_VERSION_QUERY: &str = "version=9";

 #[derive(Clone, Debug)]
 pub struct AuthenticatedAdmin {
@@ -100,17 +103,6 @@ struct SpacetimeSchemaTable {
    name: Option<String>,
 }

-#[derive(Debug, Deserialize)]
-struct SpacetimeSqlRow {
-    #[serde(flatten)]
-    columns: serde_json::Map<String, Value>,
-}
-
-#[derive(Debug, Deserialize)]
-struct SpacetimeSqlResponse {
-    rows: Option<Vec<SpacetimeSqlRow>>,
-}
-
 impl AuthenticatedAdmin {
    pub fn new(session: AdminSessionPayload) -> Self {
        Self { session }
@@ -121,10 +113,6 @@ impl AuthenticatedAdmin {
    }
 }

-pub async fn admin_console_page() -> Html<&'static str> {
-    Html(ADMIN_CONSOLE_HTML)
-}
-
 pub async fn admin_login(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
@@ -287,7 +275,7 @@ async fn fetch_database_overview(state: &AppState) -> AdminDatabaseOverviewPaylo

    let schema = fetch_spacetime_json::<SpacetimeSchemaResponse>(
        &client,
-        &format!("{server_root}/v1/database/{database}/schema"),
+        &build_spacetime_schema_url(server_root, database),
        token,
    )
    .await
@@ -353,6 +341,10 @@ async fn fetch_database_overview(state: &AppState) -> AdminDatabaseOverviewPaylo
    }
 }

+fn build_spacetime_schema_url(server_root: &str, database: &str) -> String {
+    format!("{server_root}/v1/database/{database}/schema?{SPACETIME_SCHEMA_VERSION_QUERY}")
+}
+
 async fn fetch_spacetime_json<T>(
    client: &Client,
    url: &str,
@@ -409,17 +401,63 @@ async fn fetch_spacetime_sql_count(
    }

    let payload = response
-        .json::<SpacetimeSqlResponse>()
+        .json::<Value>()
        .await
        .map_err(|error| format!("SQL 响应解析失败：{error}"))?;
-    let row = payload
-        .rows
-        .and_then(|rows| rows.into_iter().next())
-        .ok_or_else(|| "SQL 结果为空".to_string())?;
-    extract_sql_count(row.columns)
+    parse_spacetime_sql_count_response(payload)
 }

-fn extract_sql_count(columns: serde_json::Map<String, Value>) -> Result<u64, String> {
+fn parse_spacetime_sql_count_response(payload: Value) -> Result<u64, String> {
+    match payload {
+        // SpacetimeDB 2.x /sql 返回 statement result 数组，每个 result 内含 schema 与 rows。
+        Value::Array(statements) => {
+            let statement = statements
+                .into_iter()
+                .next()
+                .ok_or_else(|| "SQL 结果为空".to_string())?;
+            extract_sql_count_from_statement(statement)
+        }
+        // 保留兼容旧对象形状，便于本地/远端 API 小版本差异时仍能读取计数。
+        Value::Object(statement) => extract_sql_count_from_statement(Value::Object(statement)),
+        _ => Err("SQL 响应格式非法".to_string()),
+    }
+}
+
+fn extract_sql_count_from_statement(statement: Value) -> Result<u64, String> {
+    let Value::Object(mut statement) = statement else {
+        return Err("SQL statement 结果格式非法".to_string());
+    };
+
+    let schema = statement.remove("schema");
+    let rows = statement
+        .remove("rows")
+        .ok_or_else(|| "SQL 响应缺少 rows 字段".to_string())?;
+    extract_sql_count_from_rows(rows, schema.as_ref())
+}
+
+fn extract_sql_count_from_rows(rows: Value, schema: Option<&Value>) -> Result<u64, String> {
+    let Value::Array(rows) = rows else {
+        return Err("SQL rows 字段格式非法".to_string());
+    };
+    let row = rows.first().ok_or_else(|| "SQL 结果为空".to_string())?;
+    extract_sql_count_from_row(row, schema)
+}
+
+fn extract_sql_count_from_row(row: &Value, schema: Option<&Value>) -> Result<u64, String> {
+    match row {
+        Value::Object(columns) => extract_sql_count(columns),
+        Value::Array(values) => {
+            let count_index = schema.and_then(find_sql_count_column_index).unwrap_or(0);
+            values
+                .get(count_index)
+                .ok_or_else(|| "SQL 结果缺少 count 字段".to_string())
+                .and_then(parse_count_value)
+        }
+        value => parse_count_value(value),
+    }
+}
+
+fn extract_sql_count(columns: &serde_json::Map<String, Value>) -> Result<u64, String> {
    for key in ["row_count", "count", "COUNT(*)"] {
        if let Some(value) = columns.get(key) {
            return parse_count_value(value);
@@ -432,6 +470,25 @@ fn extract_sql_count(columns: serde_json::Map<String, Value>) -> Result<u64, Str
        .and_then(parse_count_value)
 }

+fn find_sql_count_column_index(schema: &Value) -> Option<usize> {
+    let elements = schema.get("elements")?.as_array()?;
+    elements.iter().position(|element| {
+        element
+            .get("name")
+            .and_then(extract_sql_schema_name)
+            .map(|name| matches!(name, "row_count" | "count" | "COUNT(*)"))
+            .unwrap_or(false)
+    })
+}
+
+fn extract_sql_schema_name(value: &Value) -> Option<&str> {
+    match value {
+        Value::String(text) => Some(text.as_str()),
+        Value::Object(object) => object.get("some").and_then(Value::as_str),
+        _ => None,
+    }
+}
+
 fn parse_count_value(value: &Value) -> Result<u64, String> {
    match value {
        Value::Number(number) => number
@@ -602,520 +659,14 @@ fn build_admin_session_payload(session: crate::state::AdminSession) -> AdminSess
    }
 }

-// 首版后台页面内嵌在 api-server，避免新增独立前端工程与静态资源发布链。
-static ADMIN_CONSOLE_HTML: &str = r#"<!doctype html>
-<html lang="zh-CN">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <title>Genarrative 管理后台</title>
-  <style>
-    :root {
-      --bg: linear-gradient(180deg, #f4efe5 0%, #e7ddd0 100%);
-      --panel: rgba(255, 249, 240, 0.92);
-      --panel-strong: #fffaf2;
-      --line: rgba(90, 61, 41, 0.14);
-      --text: #2f241d;
-      --muted: #7b6657;
-      --accent: #b45a2f;
-      --accent-strong: #8f431f;
-      --ok: #2c7a54;
-      --danger: #a63f2f;
-      --shadow: 0 20px 50px rgba(70, 41, 19, 0.12);
-      --radius: 20px;
-      --font: "Microsoft YaHei", "PingFang SC", "Segoe UI", sans-serif;
-    }
-    * { box-sizing: border-box; }
-    body {
-      margin: 0;
-      font-family: var(--font);
-      color: var(--text);
-      background: var(--bg);
-      min-height: 100vh;
-    }
-    .shell {
-      max-width: 1180px;
-      margin: 0 auto;
-      padding: 20px 16px 40px;
-    }
-    .hero {
-      display: flex;
-      justify-content: space-between;
-      align-items: flex-start;
-      gap: 16px;
-      margin-bottom: 18px;
-    }
-    .hero h1 {
-      margin: 0;
-      font-size: 28px;
-      line-height: 1.1;
-      letter-spacing: 0.02em;
-    }
-    .hero p {
-      margin: 10px 0 0;
-      color: var(--muted);
-      font-size: 14px;
-    }
-    .status-chip {
-      padding: 10px 14px;
-      border-radius: 999px;
-      background: rgba(180, 90, 47, 0.1);
-      color: var(--accent-strong);
-      font-size: 13px;
-      white-space: nowrap;
-    }
-    .grid {
-      display: grid;
-      grid-template-columns: 340px minmax(0, 1fr);
-      gap: 16px;
-    }
-    .panel {
-      background: var(--panel);
-      border: 1px solid var(--line);
-      border-radius: var(--radius);
-      box-shadow: var(--shadow);
-      backdrop-filter: blur(12px);
-    }
-    .panel-head {
-      padding: 18px 18px 0;
-    }
-    .panel-head h2 {
-      margin: 0;
-      font-size: 18px;
-    }
-    .panel-head p {
-      margin: 8px 0 0;
-      color: var(--muted);
-      font-size: 13px;
-    }
-    .panel-body {
-      padding: 18px;
-    }
-    .form {
-      display: grid;
-      gap: 12px;
-    }
-    label {
-      display: grid;
-      gap: 6px;
-      font-size: 13px;
-      color: var(--muted);
-    }
-    input, textarea, select {
-      width: 100%;
-      border: 1px solid rgba(78, 53, 37, 0.12);
-      border-radius: 14px;
-      background: var(--panel-strong);
-      color: var(--text);
-      font: inherit;
-      padding: 12px 14px;
-      outline: none;
-    }
-    textarea {
-      min-height: 140px;
-      resize: vertical;
-    }
-    .btn-row {
-      display: flex;
-      gap: 10px;
-      flex-wrap: wrap;
-    }
-    button {
-      border: none;
-      border-radius: 14px;
-      padding: 11px 16px;
-      background: var(--accent);
-      color: #fff8f2;
-      font: inherit;
-      cursor: pointer;
-    }
-    button.secondary {
-      background: rgba(180, 90, 47, 0.14);
-      color: var(--accent-strong);
-    }
-    button:disabled {
-      opacity: 0.6;
-      cursor: wait;
-    }
-    .stack {
-      display: grid;
-      gap: 16px;
-    }
-    .metrics {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
-      gap: 12px;
-    }
-    .metric {
-      padding: 14px;
-      border-radius: 16px;
-      border: 1px solid var(--line);
-      background: rgba(255,255,255,0.45);
-    }
-    .metric .k {
-      font-size: 12px;
-      color: var(--muted);
-    }
-    .metric .v {
-      margin-top: 8px;
-      font-size: 18px;
-      font-weight: 700;
-    }
-    .data-grid {
-      display: grid;
-      gap: 10px;
-    }
-    .row {
-      display: grid;
-      grid-template-columns: 160px 1fr;
-      gap: 10px;
-      font-size: 13px;
-      align-items: start;
-      padding: 10px 0;
-      border-bottom: 1px solid rgba(78, 53, 37, 0.08);
-    }
-    .row:last-child {
-      border-bottom: none;
-    }
-    .row .k {
-      color: var(--muted);
-    }
-    .table-list {
-      display: grid;
-      gap: 10px;
-      max-height: 420px;
-      overflow: auto;
-      padding-right: 4px;
-    }
-    .table-item {
-      display: flex;
-      justify-content: space-between;
-      gap: 12px;
-      padding: 12px 14px;
-      border-radius: 14px;
-      background: rgba(255,255,255,0.52);
-      border: 1px solid rgba(78, 53, 37, 0.08);
-      align-items: center;
-    }
-    .table-item small {
-      color: var(--muted);
-      display: block;
-      margin-top: 4px;
-    }
-    .count {
-      font-weight: 700;
-      white-space: nowrap;
-    }
-    .count.err {
-      color: var(--danger);
-      font-weight: 600;
-    }
-    .result-panel {
-      border-radius: 16px;
-      border: 1px solid var(--line);
-      background: rgba(255,255,255,0.55);
-      padding: 14px;
-      display: grid;
-      gap: 10px;
-    }
-    pre {
-      margin: 0;
-      white-space: pre-wrap;
-      word-break: break-word;
-      font-size: 12px;
-      line-height: 1.5;
-      background: rgba(47, 36, 29, 0.06);
-      border-radius: 14px;
-      padding: 12px;
-      overflow: auto;
-    }
-    .hint {
-      font-size: 12px;
-      color: var(--muted);
-    }
-    .err-text { color: var(--danger); }
-    .ok-text { color: var(--ok); }
-    @media (max-width: 900px) {
-      .grid { grid-template-columns: 1fr; }
-      .hero { flex-direction: column; }
-      .row { grid-template-columns: 1fr; gap: 4px; }
-    }
-  </style>
-</head>
-<body>
-  <div class="shell">
-    <div class="hero">
-      <div>
-        <h1>Genarrative 管理后台</h1>
-        <p>查看服务状态、数据库概览，并对当前 API 做受控调试。</p>
-      </div>
-      <div id="admin-status" class="status-chip">未登录</div>
-    </div>
-
-    <div class="grid">
-      <div class="stack">
-        <section class="panel">
-          <div class="panel-head">
-            <h2>管理员登录</h2>
-            <p>使用配置的后台账号进入管理域。</p>
-          </div>
-          <div class="panel-body">
-            <form id="login-form" class="form">
-              <label>用户名
-                <input id="login-username" name="username" autocomplete="username" />
-              </label>
-              <label>密码
-                <input id="login-password" name="password" type="password" autocomplete="current-password" />
-              </label>
-              <div class="btn-row">
-                <button id="login-submit" type="submit">登录后台</button>
-                <button id="login-clear" class="secondary" type="button">清空令牌</button>
-              </div>
-              <div id="login-message" class="hint"></div>
-            </form>
-          </div>
-        </section>
-
-        <section class="panel">
-          <div class="panel-head">
-            <h2>API 调试</h2>
-            <p>对当前服务做同源受控请求。</p>
-          </div>
-          <div class="panel-body">
-            <form id="debug-form" class="form">
-              <label>方法
-                <select id="debug-method">
-                  <option>GET</option>
-                  <option>POST</option>
-                  <option>PUT</option>
-                  <option>DELETE</option>
-                  <option>PATCH</option>
-                </select>
-              </label>
-              <label>路径
-                <input id="debug-path" value="/healthz" />
-              </label>
-              <label>附加请求头（JSON 数组）
-                <textarea id="debug-headers">[]</textarea>
-              </label>
-              <label>请求体
-                <textarea id="debug-body"></textarea>
-              </label>
-              <div class="btn-row">
-                <button id="debug-submit" type="submit">发送调试请求</button>
-              </div>
-            </form>
-          </div>
-        </section>
-      </div>
-
-      <div class="stack">
-        <section class="panel">
-          <div class="panel-head">
-            <h2>数据库概览</h2>
-            <p>读取当前服务配置和 SpacetimeDB 数据库真相。</p>
-          </div>
-          <div class="panel-body">
-            <div class="btn-row" style="margin-bottom:14px;">
-              <button id="refresh-overview" type="button">刷新概览</button>
-            </div>
-            <div id="overview-metrics" class="metrics"></div>
-            <div id="overview-detail" class="data-grid" style="margin-top:14px;"></div>
-            <div id="overview-errors" class="hint err-text" style="margin-top:10px;"></div>
-            <div id="overview-tables" class="table-list" style="margin-top:14px;"></div>
-          </div>
-        </section>
-
-        <section class="panel">
-          <div class="panel-head">
-            <h2>调试结果</h2>
-            <p>返回状态、响应头和内容预览。</p>
-          </div>
-          <div class="panel-body">
-            <div id="debug-result" class="result-panel">
-              <div class="hint">尚未执行调试请求。</div>
-            </div>
-          </div>
-        </section>
-      </div>
-    </div>
-  </div>
-
-  <script>
-    const TOKEN_KEY = 'genarrative_admin_token';
-    const statusEl = document.getElementById('admin-status');
-    const loginMessageEl = document.getElementById('login-message');
-    const overviewMetricsEl = document.getElementById('overview-metrics');
-    const overviewDetailEl = document.getElementById('overview-detail');
-    const overviewTablesEl = document.getElementById('overview-tables');
-    const overviewErrorsEl = document.getElementById('overview-errors');
-    const debugResultEl = document.getElementById('debug-result');
-
-    function getToken() {
-      return window.localStorage.getItem(TOKEN_KEY) || '';
-    }
-
-    function setToken(token) {
-      if (!token) {
-        window.localStorage.removeItem(TOKEN_KEY);
-        return;
-      }
-      window.localStorage.setItem(TOKEN_KEY, token);
-    }
-
-    function setStatus(text, ok) {
-      statusEl.textContent = text;
-      statusEl.style.background = ok ? 'rgba(44,122,84,0.12)' : 'rgba(180,90,47,0.1)';
-      statusEl.style.color = ok ? '#2c7a54' : '#8f431f';
-    }
-
-    async function request(path, options = {}) {
-      const headers = new Headers(options.headers || {});
-      const token = getToken();
-      if (token) {
-        headers.set('authorization', `Bearer ${token}`);
-      }
-      if (options.json !== undefined) {
-        headers.set('content-type', 'application/json');
-        options.body = JSON.stringify(options.json);
-      }
-      const response = await fetch(path, { ...options, headers });
-      const text = await response.text();
-      let data = null;
-      try { data = text ? JSON.parse(text) : null; } catch (_) {}
-      if (!response.ok) {
-        const message = data?.error?.message || data?.message || text || `HTTP ${response.status}`;
-        throw new Error(message);
-      }
-      return data?.data ?? data;
-    }
-
-    function renderOverview(overview) {
-      const service = overview.service || {};
-      const database = overview.database || {};
-      const stats = Array.isArray(database.tableStats) ? database.tableStats : [];
-      overviewMetricsEl.innerHTML = `
-        <div class="metric"><div class="k">后台状态</div><div class="v">${service.adminEnabled ? '已启用' : '未启用'}</div></div>
-        <div class="metric"><div class="k">服务监听</div><div class="v">${service.bindHost || '-'}:${service.bindPort || '-'}</div></div>
-        <div class="metric"><div class="k">SpacetimeDB</div><div class="v">${service.spacetimeDatabase || '-'}</div></div>
-        <div class="metric"><div class="k">统计表数</div><div class="v">${stats.length}</div></div>
-      `;
-      overviewDetailEl.innerHTML = `
-        <div class="row"><div class="k">JWT Issuer</div><div>${service.jwtIssuer || '-'}</div></div>
-        <div class="row"><div class="k">Spacetime 服务</div><div>${service.spacetimeServerUrl || '-'}</div></div>
-        <div class="row"><div class="k">数据库 Identity</div><div>${database.databaseIdentity || '-'}</div></div>
-        <div class="row"><div class="k">Owner Identity</div><div>${database.ownerIdentity || '-'}</div></div>
-        <div class="row"><div class="k">Host Type</div><div>${database.hostType || '-'}</div></div>
-        <div class="row"><div class="k">Schema 表数量</div><div>${(database.schemaTableNames || []).length}</div></div>
-      `;
-      overviewTablesEl.innerHTML = stats.map((item) => `
-        <div class="table-item">
-          <div>
-            <strong>${item.tableName}</strong>
-            ${item.errorMessage ? `<small class="err-text">${item.errorMessage}</small>` : ''}
-          </div>
-          <div class="count ${item.errorMessage ? 'err' : ''}">${item.rowCount ?? '失败'}</div>
-        </div>
-      `).join('');
-      overviewErrorsEl.textContent = (database.fetchErrors || []).join(' | ');
-    }
-
-    function renderDebugResult(result) {
-      const headerText = (result.headers || []).map((item) => `${item.name}: ${item.value}`).join('\n');
-      debugResultEl.innerHTML = `
-        <div><strong>状态：</strong><span class="${result.status < 400 ? 'ok-text' : 'err-text'}">${result.status} ${result.statusText}</span></div>
-        <div><strong>响应头</strong><pre>${headerText || '(无)'}</pre></div>
-        <div><strong>响应体预览</strong><pre>${result.bodyText || '(空)'}</pre></div>
-        <div><strong>响应 JSON</strong><pre>${result.bodyJson ? JSON.stringify(result.bodyJson, null, 2) : '(不是 JSON)'}</pre></div>
-      `;
-    }
-
-    async function loadMe() {
-      const token = getToken();
-      if (!token) {
-        setStatus('未登录', false);
-        return;
-      }
-      try {
-        const result = await request('/admin/api/me');
-        setStatus(`管理员：${result.admin.displayName}`, true);
-      } catch (error) {
-        setToken('');
-        setStatus('未登录', false);
-      }
-    }
-
-    async function loadOverview() {
-      try {
-        const overview = await request('/admin/api/overview');
-        renderOverview(overview);
-      } catch (error) {
-        overviewMetricsEl.innerHTML = '';
-        overviewDetailEl.innerHTML = '';
-        overviewTablesEl.innerHTML = '';
-        overviewErrorsEl.textContent = error.message;
-      }
-    }
-
-    document.getElementById('login-form').addEventListener('submit', async (event) => {
-      event.preventDefault();
-      loginMessageEl.textContent = '正在登录...';
-      try {
-        const result = await request('/admin/api/login', {
-          method: 'POST',
-          json: {
-            username: document.getElementById('login-username').value,
-            password: document.getElementById('login-password').value,
-          },
-        });
-        setToken(result.token);
-        loginMessageEl.textContent = '登录成功';
-        await loadMe();
-        await loadOverview();
-      } catch (error) {
-        loginMessageEl.textContent = error.message;
-      }
-    });
-
-    document.getElementById('login-clear').addEventListener('click', () => {
-      setToken('');
-      setStatus('未登录', false);
-      loginMessageEl.textContent = '已清空本地令牌';
-    });
-
-    document.getElementById('refresh-overview').addEventListener('click', async () => {
-      await loadOverview();
-    });
-
-    document.getElementById('debug-form').addEventListener('submit', async (event) => {
-      event.preventDefault();
-      debugResultEl.innerHTML = '<div class="hint">正在请求...</div>';
-      try {
-        const headers = JSON.parse(document.getElementById('debug-headers').value || '[]');
-        const result = await request('/admin/api/debug/http', {
-          method: 'POST',
-          json: {
-            method: document.getElementById('debug-method').value,
-            path: document.getElementById('debug-path').value,
-            headers,
-            body: document.getElementById('debug-body').value,
-          },
-        });
-        renderDebugResult(result);
-      } catch (error) {
-        debugResultEl.innerHTML = `<div class="err-text">${error.message}</div>`;
-      }
-    });
-
-    loadMe().then(loadOverview);
-  </script>
-</body>
-</html>"#;
-
 #[cfg(test)]
 mod tests {
-    use super::{build_body_preview, build_debug_base_url, normalize_debug_path, trim_preview};
+    use super::{
+        build_body_preview, build_debug_base_url, build_spacetime_schema_url, normalize_debug_path,
+        parse_spacetime_sql_count_response, trim_preview,
+    };
    use axum::{http::StatusCode, response::IntoResponse};
+    use serde_json::json;

    #[test]
    fn normalize_debug_path_rejects_absolute_url() {
@@ -1161,6 +712,91 @@ mod tests {
        assert_eq!(trim_preview(&text).chars().count(), 4000);
    }

+    #[test]
+    fn build_spacetime_schema_url_includes_required_version_query() {
+        let url = build_spacetime_schema_url("http://127.0.0.1:3101", "xushi-p4wfr");
+
+        assert_eq!(
+            url,
+            "http://127.0.0.1:3101/v1/database/xushi-p4wfr/schema?version=9"
+        );
+    }
+
+    #[test]
+    fn parse_spacetime_sql_count_response_accepts_statement_array_rows() {
+        let payload = json!([
+            {
+                "schema": {
+                    "elements": [
+                        {
+                            "name": {
+                                "some": "row_count"
+                            },
+                            "algebraic_type": {
+                                "U64": []
+                            }
+                        }
+                    ]
+                },
+                "rows": [[7]],
+                "total_duration_micros": 116,
+                "stats": {
+                    "rows_inserted": 0,
+                    "rows_deleted": 0,
+                    "rows_updated": 0
+                }
+            }
+        ]);
+
+        let count =
+            parse_spacetime_sql_count_response(payload).expect("statement array should parse");
+
+        assert_eq!(count, 7);
+    }
+
+    #[test]
+    fn parse_spacetime_sql_count_response_uses_schema_column_index() {
+        let payload = json!([
+            {
+                "schema": {
+                    "elements": [
+                        {
+                            "name": {
+                                "some": "table_name"
+                            }
+                        },
+                        {
+                            "name": {
+                                "some": "row_count"
+                            }
+                        }
+                    ]
+                },
+                "rows": [["runtime_setting", "12"]]
+            }
+        ]);
+
+        let count =
+            parse_spacetime_sql_count_response(payload).expect("schema column index should parse");
+
+        assert_eq!(count, 12);
+    }
+
+    #[test]
+    fn parse_spacetime_sql_count_response_keeps_object_row_compatibility() {
+        let payload = json!({
+            "rows": [
+                {
+                    "row_count": "3"
+                }
+            ]
+        });
+
+        let count = parse_spacetime_sql_count_response(payload).expect("object row should parse");
+
+        assert_eq!(count, 3);
+    }
+
    #[test]
    fn build_body_preview_handles_utf8() {
        let preview = build_body_preview("后台测试".as_bytes());
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -13,10 +13,7 @@ use tower_http::{
 use tracing::{Level, Span, error, info, info_span, warn};

 use crate::{
-    admin::{
-        admin_console_page, admin_debug_http, admin_login, admin_me, admin_overview,
-        require_admin_auth,
-    },
+    admin::{admin_debug_http, admin_login, admin_me, admin_overview, require_admin_auth},
    ai_tasks::{
        append_ai_text_chunk, attach_ai_result_reference, cancel_ai_task, complete_ai_stage,
        complete_ai_task, create_ai_task, fail_ai_task, start_ai_task, start_ai_task_stage,
@@ -110,10 +107,10 @@ use crate::{
    },
    runtime_inventory::get_runtime_inventory_state,
    runtime_profile::{
-        admin_disable_profile_redeem_code, admin_upsert_profile_redeem_code,
-        create_profile_recharge_order, get_profile_dashboard, get_profile_play_stats,
-        get_profile_recharge_center, get_profile_referral_invite_center, get_profile_wallet_ledger,
-        redeem_profile_referral_invite_code, redeem_profile_reward_code,
+        admin_disable_profile_redeem_code, admin_upsert_profile_invite_code,
+        admin_upsert_profile_redeem_code, create_profile_recharge_order, get_profile_dashboard,
+        get_profile_play_stats, get_profile_recharge_center, get_profile_referral_invite_center,
+        get_profile_wallet_ledger, redeem_profile_referral_invite_code, redeem_profile_reward_code,
    },
    runtime_save::{
        delete_runtime_snapshot, get_runtime_snapshot, list_profile_save_archives,
@@ -138,7 +135,6 @@ pub fn build_router(state: AppState) -> Router {
    let slow_request_threshold_ms = state.config.slow_request_threshold_ms;

    Router::new()
-        .route("/admin", get(admin_console_page))
        .route("/admin/api/login", post(admin_login))
        .route(
            "/admin/api/me",
@@ -175,6 +171,13 @@ pub fn build_router(state: AppState) -> Router {
                require_admin_auth,
            )),
        )
+        .route(
+            "/admin/api/profile/invite-codes",
+            post(admin_upsert_profile_invite_code).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_admin_auth,
+            )),
+        )
        .route(
            "/healthz",
            get(|Extension(request_context): Extension<_>| async move {
@@ -1962,6 +1965,8 @@ mod tests {
            payload["user"]["phoneNumberMasked"],
            Value::String("138****8000".to_string())
        );
+        assert_eq!(payload["created"], Value::Bool(true));
+        assert!(payload["referral"].is_null());
    }

    #[tokio::test]
@@ -2068,6 +2073,175 @@ mod tests {
            serde_json::from_slice(&second_body).expect("second login payload should be json");

        assert_eq!(first_payload["user"]["id"], second_payload["user"]["id"]);
+        assert_eq!(first_payload["created"], Value::Bool(true));
+        assert_eq!(second_payload["created"], Value::Bool(false));
+        assert!(second_payload["referral"].is_null());
+    }
+
+    #[tokio::test]
+    async fn phone_login_invite_code_failure_does_not_block_created_user() {
+        let config = AppConfig {
+            sms_auth_enabled: true,
+            ..AppConfig::default()
+        };
+        let app = build_router(AppState::new(config).expect("state should build"));
+
+        let send_code_response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/send-code")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13600136000",
+                            "scene": "login"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("send code request should build"),
+            )
+            .await
+            .expect("send code request should succeed");
+        assert_eq!(send_code_response.status(), StatusCode::OK);
+
+        let login_response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/login")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13600136000",
+                            "code": "123456",
+                            "inviteCode": "SPRING2026"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("login request should build"),
+            )
+            .await
+            .expect("login request should succeed");
+
+        assert_eq!(login_response.status(), StatusCode::OK);
+        let body = login_response
+            .into_body()
+            .collect()
+            .await
+            .expect("login body should collect")
+            .to_bytes();
+        let payload: Value = serde_json::from_slice(&body).expect("login payload should be json");
+
+        assert!(payload["token"].as_str().is_some());
+        assert_eq!(payload["created"], Value::Bool(true));
+        assert_eq!(payload["referral"]["ok"], Value::Bool(false));
+        assert_eq!(
+            payload["referral"]["message"],
+            Value::String("邀请码无效，已继续注册".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn phone_login_existing_user_ignores_invite_code() {
+        let config = AppConfig {
+            sms_auth_enabled: true,
+            ..AppConfig::default()
+        };
+        let app = build_router(AppState::new(config).expect("state should build"));
+
+        let first_send_code_response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/send-code")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13500135000",
+                            "scene": "login"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("send code request should build"),
+            )
+            .await
+            .expect("send code request should succeed");
+        assert_eq!(first_send_code_response.status(), StatusCode::OK);
+
+        let first_login_response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/login")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13500135000",
+                            "code": "123456"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("first login request should build"),
+            )
+            .await
+            .expect("first login request should succeed");
+        assert_eq!(first_login_response.status(), StatusCode::OK);
+
+        let second_send_code_response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/send-code")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13500135000",
+                            "scene": "login"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("send code request should build"),
+            )
+            .await
+            .expect("send code request should succeed");
+        assert_eq!(second_send_code_response.status(), StatusCode::OK);
+
+        let second_login_response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/auth/phone/login")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "phone": "13500135000",
+                            "code": "123456",
+                            "inviteCode": "SPRING2026"
+                        })
+                        .to_string(),
+                    ))
+                    .expect("second login request should build"),
+            )
+            .await
+            .expect("second login request should succeed");
+
+        assert_eq!(second_login_response.status(), StatusCode::OK);
+        let body = second_login_response
+            .into_body()
+            .collect()
+            .await
+            .expect("second login body should collect")
+            .to_bytes();
+        let payload: Value =
+            serde_json::from_slice(&body).expect("second login payload should be json");
+
+        assert_eq!(payload["created"], Value::Bool(false));
+        assert!(payload["referral"].is_null());
    }

    #[tokio::test]
@@ -3283,6 +3457,23 @@ mod tests {
        );
    }

+    #[tokio::test]
+    async fn admin_page_route_is_not_mounted() {
+        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .uri("/admin")
+                    .body(Body::empty())
+                    .expect("admin page request should build"),
+            )
+            .await
+            .expect("admin page request should succeed");
+
+        assert_eq!(response.status(), StatusCode::NOT_FOUND);
+    }
+
    #[tokio::test]
    async fn admin_login_returns_token_when_configured() {
        let mut config = AppConfig::default();
--- a/server-rs/crates/api-server/src/phone_auth.rs
+++ b/server-rs/crates/api-server/src/phone_auth.rs
@@ -9,7 +9,8 @@ use module_auth::{
 };
 use serde_json::json;
 use shared_contracts::auth::{
-    PhoneLoginRequest, PhoneLoginResponse, PhoneSendCodeRequest, PhoneSendCodeResponse,
+    PhoneLoginReferralResponse, PhoneLoginRequest, PhoneLoginResponse, PhoneSendCodeRequest,
+    PhoneSendCodeResponse,
 };
 use time::OffsetDateTime;
 use tracing::{info, warn};
@@ -110,6 +111,7 @@ pub async fn phone_login(
            AppError::from_status(StatusCode::BAD_REQUEST).with_message("手机号登录暂未启用")
        );
    }
+    let invite_code = payload.invite_code.clone();
    let result = match state
        .phone_auth_service()
        .login(
@@ -146,6 +148,18 @@ pub async fn phone_login(
            return Err(map_phone_auth_error(error));
        }
    };
+    let created = result.created;
+    let referral = if created {
+        bind_referral_invite_code_on_registration(
+            &state,
+            &request_context,
+            result.user.id.clone(),
+            invite_code,
+        )
+        .await
+    } else {
+        None
+    };
    let session_client = resolve_session_client_context(&headers);
    let signed_session = create_auth_session(
        &state,
@@ -174,11 +188,55 @@ pub async fn phone_login(
            PhoneLoginResponse {
                token: signed_session.access_token,
                user: map_auth_user_payload(result.user),
+                created,
+                referral,
            },
        ),
    ))
 }

+async fn bind_referral_invite_code_on_registration(
+    state: &AppState,
+    request_context: &RequestContext,
+    user_id: String,
+    invite_code: Option<String>,
+) -> Option<PhoneLoginReferralResponse> {
+    let invite_code = invite_code
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())?;
+    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
+    match state
+        .spacetime_client()
+        .redeem_profile_referral_invite_code(user_id, invite_code, updated_at_micros as i64)
+        .await
+    {
+        Ok(record) => Some(PhoneLoginReferralResponse {
+            ok: true,
+            message: Some("邀请码已绑定".to_string()),
+            invitee_reward_granted: record.invitee_reward_granted,
+            inviter_reward_granted: record.inviter_reward_granted,
+            invitee_balance_after: Some(record.invitee_balance_after),
+            inviter_balance_after: Some(record.inviter_balance_after),
+        }),
+        Err(error) => {
+            warn!(
+                request_id = request_context.request_id(),
+                operation = request_context.operation(),
+                error = %error,
+                "注册邀请码绑定失败，登录流程继续"
+            );
+            Some(PhoneLoginReferralResponse {
+                ok: false,
+                message: Some("邀请码无效，已继续注册".to_string()),
+                invitee_reward_granted: false,
+                inviter_reward_granted: false,
+                invitee_balance_after: None,
+                inviter_balance_after: None,
+            })
+        }
+    }
+}
+
 fn map_phone_auth_scene(raw_scene: Option<&str>) -> Result<PhoneAuthScene, AppError> {
    match raw_scene.unwrap_or("login").trim() {
        "login" => Ok(PhoneAuthScene::Login),
--- a/server-rs/crates/api-server/src/runtime_profile.rs
+++ b/server-rs/crates/api-server/src/runtime_profile.rs
@@ -5,31 +5,30 @@ use axum::{
    response::Response,
 };
 use module_runtime::{
-    PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK, RuntimeProfileMembershipBenefitRecord,
-    RuntimeProfileRechargeCenterRecord, RuntimeProfileRechargeOrderRecord,
-    RuntimeProfileRechargeProductRecord, RuntimeProfileRedeemCodeMode,
-    RuntimeProfileRedeemCodeRecord, RuntimeProfileRewardCodeRedeemRecord,
-    RuntimeProfileWalletLedgerSourceType, RuntimeReferralInviteCenterRecord,
-    RuntimeReferralRedeemRecord,
+    PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK, RuntimeProfileInviteCodeRecord,
+    RuntimeProfileMembershipBenefitRecord, RuntimeProfileRechargeCenterRecord,
+    RuntimeProfileRechargeOrderRecord, RuntimeProfileRechargeProductRecord,
+    RuntimeProfileRedeemCodeMode, RuntimeProfileRedeemCodeRecord,
+    RuntimeProfileRewardCodeRedeemRecord, RuntimeProfileWalletLedgerSourceType,
+    RuntimeReferralInviteCenterRecord,
 };
 use serde_json::{Value, json};
 use shared_contracts::runtime::{
-    AdminDisableProfileRedeemCodeRequest, AdminUpsertProfileRedeemCodeRequest,
-    CreateProfileRechargeOrderRequest, CreateProfileRechargeOrderResponse,
-    PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_CONSUME,
+    AdminDisableProfileRedeemCodeRequest, AdminUpsertProfileInviteCodeRequest,
+    AdminUpsertProfileRedeemCodeRequest, CreateProfileRechargeOrderRequest,
+    CreateProfileRechargeOrderResponse, PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_CONSUME,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_REFUND,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_INVITE_INVITEE_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_INVITE_INVITER_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_POINTS_RECHARGE,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_REDEEM_CODE_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_SNAPSHOT_SYNC, ProfileDashboardSummaryResponse,
-    ProfileMembershipBenefitResponse, ProfileMembershipResponse, ProfilePlayStatsResponse,
-    ProfilePlayedWorkSummaryResponse, ProfileRechargeCenterResponse, ProfileRechargeOrderResponse,
-    ProfileRechargeProductResponse, ProfileRedeemCodeAdminResponse,
+    ProfileInviteCodeAdminResponse, ProfileMembershipBenefitResponse, ProfileMembershipResponse,
+    ProfilePlayStatsResponse, ProfilePlayedWorkSummaryResponse, ProfileRechargeCenterResponse,
+    ProfileRechargeOrderResponse, ProfileRechargeProductResponse, ProfileRedeemCodeAdminResponse,
    ProfileReferralInviteCenterResponse, ProfileWalletLedgerEntryResponse,
    ProfileWalletLedgerResponse, RedeemProfileReferralInviteCodeRequest,
-    RedeemProfileReferralInviteCodeResponse, RedeemProfileRewardCodeRequest,
-    RedeemProfileRewardCodeResponse,
+    RedeemProfileRewardCodeRequest, RedeemProfileRewardCodeResponse,
 };
 use spacetime_client::SpacetimeClientError;
 use time::OffsetDateTime;
@@ -213,27 +212,14 @@ pub async fn get_profile_referral_invite_center(
 }

 pub async fn redeem_profile_referral_invite_code(
-    State(state): State<AppState>,
+    State(_state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-    Json(payload): Json<RedeemProfileReferralInviteCodeRequest>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    Json(_payload): Json<RedeemProfileReferralInviteCodeRequest>,
 ) -> Result<Json<Value>, Response> {
-    let user_id = authenticated.claims().user_id().to_string();
-    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
-    let record = state
-        .spacetime_client()
-        .redeem_profile_referral_invite_code(user_id, payload.invite_code, updated_at_micros as i64)
-        .await
-        .map_err(|error| {
-            runtime_profile_error_response(
-                &request_context,
-                map_runtime_profile_client_error(error),
-            )
-        })?;
-
-    Ok(json_success_body(
-        Some(&request_context),
-        build_redeem_profile_referral_invite_code_response(record),
+    Err(runtime_profile_error_response(
+        &request_context,
+        AppError::from_status(StatusCode::BAD_REQUEST).with_message("邀请码仅注册时填写"),
    ))
 }

@@ -330,6 +316,37 @@ pub async fn admin_disable_profile_redeem_code(
    ))
 }

+pub async fn admin_upsert_profile_invite_code(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(admin): Extension<AuthenticatedAdmin>,
+    Json(payload): Json<AdminUpsertProfileInviteCodeRequest>,
+) -> Result<Json<Value>, Response> {
+    let metadata_json = normalize_admin_invite_code_metadata(payload.metadata)
+        .map_err(|error| runtime_profile_error_response(&request_context, error))?;
+    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
+    let record = state
+        .spacetime_client()
+        .admin_upsert_profile_invite_code(
+            admin.session().username.clone(),
+            payload.invite_code,
+            metadata_json,
+            updated_at_micros as i64,
+        )
+        .await
+        .map_err(|error| {
+            runtime_profile_error_response(
+                &request_context,
+                map_runtime_profile_client_error(error),
+            )
+        })?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_profile_invite_code_admin_response(record),
+    ))
+}
+
 pub async fn get_profile_play_stats(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
@@ -486,18 +503,6 @@ fn build_profile_referral_invite_center_response(
    }
 }

-fn build_redeem_profile_referral_invite_code_response(
-    record: RuntimeReferralRedeemRecord,
-) -> RedeemProfileReferralInviteCodeResponse {
-    RedeemProfileReferralInviteCodeResponse {
-        center: build_profile_referral_invite_center_response(record.center),
-        invitee_reward_granted: record.invitee_reward_granted,
-        inviter_reward_granted: record.inviter_reward_granted,
-        invitee_balance_after: record.invitee_balance_after,
-        inviter_balance_after: record.inviter_balance_after,
-    }
-}
-
 fn build_redeem_profile_reward_code_response(
    record: RuntimeProfileRewardCodeRedeemRecord,
 ) -> RedeemProfileRewardCodeResponse {
@@ -515,6 +520,30 @@ fn build_redeem_profile_reward_code_response(
    }
 }

+fn normalize_admin_invite_code_metadata(metadata: Option<Value>) -> Result<String, AppError> {
+    let metadata = match metadata {
+        Some(Value::Null) | None => json!({}),
+        Some(value) if value.is_object() => value,
+        Some(_) => {
+            return Err(AppError::from_status(StatusCode::BAD_REQUEST)
+                .with_message("邀请码 metadata 必须是 JSON 对象")
+                .with_details(json!({ "field": "metadata" })));
+        }
+    };
+    let metadata_json = serde_json::to_string(&metadata).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_message(format!("邀请码 metadata 序列化失败：{error}"))
+            .with_details(json!({ "field": "metadata" }))
+    })?;
+    if metadata_json.len() > 4096 {
+        return Err(AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_message("邀请码 metadata 不能超过 4096 bytes")
+            .with_details(json!({ "field": "metadata" })));
+    }
+
+    Ok(metadata_json)
+}
+
 fn parse_profile_redeem_code_mode(raw: &str) -> Result<RuntimeProfileRedeemCodeMode, String> {
    match raw.trim().to_ascii_lowercase().as_str() {
        "public" => Ok(RuntimeProfileRedeemCodeMode::Public),
@@ -524,6 +553,20 @@ fn parse_profile_redeem_code_mode(raw: &str) -> Result<RuntimeProfileRedeemCodeM
    }
 }

+fn build_profile_invite_code_admin_response(
+    record: RuntimeProfileInviteCodeRecord,
+) -> ProfileInviteCodeAdminResponse {
+    let metadata =
+        serde_json::from_str::<Value>(&record.metadata_json).unwrap_or_else(|_| json!({}));
+    ProfileInviteCodeAdminResponse {
+        user_id: record.user_id,
+        invite_code: record.invite_code,
+        metadata,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
 fn build_profile_redeem_code_admin_response(
    record: RuntimeProfileRedeemCodeRecord,
 ) -> ProfileRedeemCodeAdminResponse {
@@ -545,7 +588,7 @@ fn build_profile_redeem_code_admin_response(
 mod tests {
    use module_runtime::RuntimeProfileWalletLedgerSourceType;

-    use super::format_profile_wallet_ledger_source_type;
+    use super::{format_profile_wallet_ledger_source_type, normalize_admin_invite_code_metadata};

    use axum::{
        body::Body,
@@ -705,6 +748,60 @@ mod tests {
        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
    }

+    #[tokio::test]
+    async fn profile_referral_redeem_code_rejects_authenticated_manual_fill() {
+        let state = seed_authenticated_state().await;
+        let token = issue_access_token(&state);
+        let app = build_router(state);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/profile/referrals/redeem-code")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(r#"{"inviteCode":"SY12345678"}"#))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("body should collect")
+            .to_bytes();
+        let payload: Value =
+            serde_json::from_slice(&body).expect("response body should be valid json");
+        assert_eq!(
+            payload["error"]["message"],
+            Value::String("邀请码仅注册时填写".to_string())
+        );
+    }
+
+    #[test]
+    fn admin_invite_code_metadata_accepts_only_json_object() {
+        assert_eq!(
+            normalize_admin_invite_code_metadata(None).expect("empty metadata should default"),
+            "{}"
+        );
+        assert_eq!(
+            normalize_admin_invite_code_metadata(Some(serde_json::json!({
+                "channel": "spring",
+                "source": "banner"
+            })))
+            .expect("object metadata should serialize"),
+            r#"{"channel":"spring","source":"banner"}"#
+        );
+
+        let error = normalize_admin_invite_code_metadata(Some(serde_json::json!("spring")))
+            .expect_err("non-object metadata should reject");
+        assert_eq!(error.message(), "邀请码 metadata 必须是 JSON 对象");
+    }
+
    #[tokio::test]
    async fn profile_dashboard_compat_route_matches_main_route_error_shape() {
        assert_compat_route_matches_main_route_error_shape(
--- a/server-rs/crates/module-runtime/src/lib.rs
+++ b/server-rs/crates/module-runtime/src/lib.rs
@@ -17,6 +17,8 @@ pub const MAX_BROWSE_HISTORY_BATCH_SIZE: usize = 100;
 pub const PROFILE_WALLET_LEDGER_LIST_LIMIT: usize = 50;
 pub const PROFILE_REFERRAL_REWARD_POINTS: u64 = 30;
 pub const PROFILE_REFERRAL_DAILY_INVITER_REWARD_LIMIT: u32 = 10;
+pub const PROFILE_INVITE_CODE_METADATA_DEFAULT_JSON: &str = "{}";
+const PROFILE_INVITE_CODE_METADATA_MAX_BYTES: usize = 4096;
 pub const SAVE_SNAPSHOT_VERSION: u32 = 2;
 pub const DEFAULT_SAVE_ARCHIVE_SUMMARY_TEXT: &str = "继续推进上一次保存的故事。";
 pub const PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK: &str = "mock";
@@ -502,6 +504,33 @@ pub struct RuntimeProfileRedeemCodeAdminProcedureResult {
    pub error_message: Option<String>,
 }

+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct RuntimeProfileInviteCodeAdminUpsertInput {
+    pub admin_user_id: String,
+    pub invite_code: String,
+    pub metadata_json: String,
+    pub updated_at_micros: i64,
+}
+
+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct RuntimeProfileInviteCodeSnapshot {
+    pub user_id: String,
+    pub invite_code: String,
+    pub metadata_json: String,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct RuntimeProfileInviteCodeAdminProcedureResult {
+    pub ok: bool,
+    pub record: Option<RuntimeProfileInviteCodeSnapshot>,
+    pub error_message: Option<String>,
+}
+
 #[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RuntimeReferralInviteCenterSnapshot {
@@ -615,6 +644,7 @@ pub enum RuntimeProfileFieldError {
    MissingLedgerId,
    InvalidWalletAmount,
    MissingInviteCode,
+    InvalidInviteCodeMetadata,
    MissingRedeemCode,
    InvalidRedeemCodeReward,
    InvalidRedeemCodeMaxUses,
@@ -916,6 +946,17 @@ pub struct RuntimeProfileRedeemCodeRecord {
    pub updated_at_micros: i64,
 }

+#[derive(Clone, Debug, PartialEq)]
+pub struct RuntimeProfileInviteCodeRecord {
+    pub user_id: String,
+    pub invite_code: String,
+    pub metadata_json: String,
+    pub created_at: String,
+    pub created_at_micros: i64,
+    pub updated_at: String,
+    pub updated_at_micros: i64,
+}
+
 #[derive(Clone, Debug, PartialEq)]
 pub struct RuntimeReferralInviteCenterRecord {
    pub user_id: String,
@@ -1141,6 +1182,25 @@ pub fn build_runtime_profile_redeem_code_admin_disable_input(
    })
 }

+pub fn build_runtime_profile_invite_code_admin_upsert_input(
+    admin_user_id: String,
+    invite_code: String,
+    metadata_json: String,
+    updated_at_micros: i64,
+) -> Result<RuntimeProfileInviteCodeAdminUpsertInput, RuntimeProfileFieldError> {
+    let admin_user_id = normalize_runtime_profile_user_id(admin_user_id)?;
+    let invite_code =
+        normalize_invite_code(invite_code).ok_or(RuntimeProfileFieldError::MissingInviteCode)?;
+    let metadata_json = normalize_invite_code_metadata_json(metadata_json)?;
+
+    Ok(RuntimeProfileInviteCodeAdminUpsertInput {
+        admin_user_id,
+        invite_code,
+        metadata_json,
+        updated_at_micros,
+    })
+}
+
 pub fn build_runtime_profile_play_stats_get_input(
    user_id: String,
 ) -> Result<RuntimeProfilePlayStatsGetInput, RuntimeProfileFieldError> {
@@ -1523,6 +1583,20 @@ pub fn build_runtime_profile_redeem_code_record(
    }
 }

+pub fn build_runtime_profile_invite_code_record(
+    snapshot: RuntimeProfileInviteCodeSnapshot,
+) -> RuntimeProfileInviteCodeRecord {
+    RuntimeProfileInviteCodeRecord {
+        user_id: snapshot.user_id,
+        invite_code: snapshot.invite_code,
+        metadata_json: snapshot.metadata_json,
+        created_at: format_utc_micros(snapshot.created_at_micros),
+        created_at_micros: snapshot.created_at_micros,
+        updated_at: format_utc_micros(snapshot.updated_at_micros),
+        updated_at_micros: snapshot.updated_at_micros,
+    }
+}
+
 pub fn build_runtime_profile_played_world_record(
    snapshot: RuntimeProfilePlayedWorldSnapshot,
 ) -> RuntimeProfilePlayedWorldRecord {
@@ -1947,6 +2021,25 @@ pub fn normalize_invite_code(value: String) -> Option<String> {
    }
 }

+pub fn normalize_invite_code_metadata_json(
+    value: String,
+) -> Result<String, RuntimeProfileFieldError> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return Ok(PROFILE_INVITE_CODE_METADATA_DEFAULT_JSON.to_string());
+    }
+    if trimmed.len() > PROFILE_INVITE_CODE_METADATA_MAX_BYTES {
+        return Err(RuntimeProfileFieldError::InvalidInviteCodeMetadata);
+    }
+
+    let parsed = serde_json::from_str::<Value>(trimmed)
+        .map_err(|_| RuntimeProfileFieldError::InvalidInviteCodeMetadata)?;
+    if !parsed.is_object() {
+        return Err(RuntimeProfileFieldError::InvalidInviteCodeMetadata);
+    }
+    serde_json::to_string(&parsed).map_err(|_| RuntimeProfileFieldError::InvalidInviteCodeMetadata)
+}
+
 pub fn normalize_redeem_code(value: String) -> Option<String> {
    normalize_invite_code(value)
 }
@@ -1958,6 +2051,9 @@ impl std::fmt::Display for RuntimeProfileFieldError {
            Self::MissingLedgerId => f.write_str("profile.wallet_ledger_id 不能为空"),
            Self::InvalidWalletAmount => f.write_str("profile.wallet_amount 必须大于 0"),
            Self::MissingInviteCode => f.write_str("referral.invite_code 不能为空"),
+            Self::InvalidInviteCodeMetadata => {
+                f.write_str("邀请码 metadata 必须是 JSON 对象且不超过 4096 bytes")
+            }
            Self::MissingRedeemCode => f.write_str("兑换码不能为空"),
            Self::InvalidRedeemCodeReward => f.write_str("兑换码奖励无效"),
            Self::InvalidRedeemCodeMaxUses => f.write_str("兑换次数必须大于 0"),
@@ -2202,6 +2298,41 @@ mod tests {
        );
    }

+    #[test]
+    fn invite_code_metadata_defaults_to_empty_object() {
+        assert_eq!(
+            normalize_invite_code_metadata_json(" ".to_string()).expect("blank metadata defaults"),
+            "{}"
+        );
+    }
+
+    #[test]
+    fn invite_code_metadata_requires_json_object() {
+        assert_eq!(
+            normalize_invite_code_metadata_json("[]".to_string()).expect_err("array rejects"),
+            RuntimeProfileFieldError::InvalidInviteCodeMetadata
+        );
+        assert_eq!(
+            normalize_invite_code_metadata_json("{bad".to_string()).expect_err("bad json rejects"),
+            RuntimeProfileFieldError::InvalidInviteCodeMetadata
+        );
+    }
+
+    #[test]
+    fn build_admin_invite_code_input_normalizes_code_and_compacts_metadata() {
+        let input = build_runtime_profile_invite_code_admin_upsert_input(
+            " admin-user ".to_string(),
+            " spring-2026 ".to_string(),
+            r#"{ "channel": "spring", "batch": 1 }"#.to_string(),
+            1_776_000_000_000_000,
+        )
+        .expect("admin invite input should build");
+
+        assert_eq!(input.admin_user_id, "admin-user");
+        assert_eq!(input.invite_code, "SPRING2026");
+        assert_eq!(input.metadata_json, r#"{"batch":1,"channel":"spring"}"#);
+    }
+
    #[test]
    fn profile_dashboard_record_formats_optional_timestamp() {
        let record = build_runtime_profile_dashboard_record(RuntimeProfileDashboardSnapshot {
--- a/server-rs/crates/shared-contracts/src/auth.rs
+++ b/server-rs/crates/shared-contracts/src/auth.rs
@@ -164,6 +164,8 @@ pub struct PhoneSendCodeResponse {
 pub struct PhoneLoginRequest {
    pub phone: String,
    pub code: String,
+    #[serde(default)]
+    pub invite_code: Option<String>,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
@@ -171,6 +173,19 @@ pub struct PhoneLoginRequest {
 pub struct PhoneLoginResponse {
    pub token: String,
    pub user: AuthUserPayload,
+    pub created: bool,
+    pub referral: Option<PhoneLoginReferralResponse>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PhoneLoginReferralResponse {
+    pub ok: bool,
+    pub message: Option<String>,
+    pub invitee_reward_granted: bool,
+    pub inviter_reward_granted: bool,
+    pub invitee_balance_after: Option<u64>,
+    pub inviter_balance_after: Option<u64>,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
--- a/server-rs/crates/shared-contracts/src/runtime.rs
+++ b/server-rs/crates/shared-contracts/src/runtime.rs
@@ -296,6 +296,14 @@ pub struct AdminUpsertProfileRedeemCodeRequest {
    pub allowed_public_user_codes: Vec<String>,
 }

+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminUpsertProfileInviteCodeRequest {
+    pub invite_code: String,
+    #[serde(default)]
+    pub metadata: Option<serde_json::Value>,
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct AdminDisableProfileRedeemCodeRequest {
@@ -317,6 +325,16 @@ pub struct ProfileRedeemCodeAdminResponse {
    pub updated_at: String,
 }

+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ProfileInviteCodeAdminResponse {
+    pub user_id: String,
+    pub invite_code: String,
+    pub metadata: serde_json::Value,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
 fn default_true() -> bool {
    true
 }
--- a/server-rs/crates/spacetime-client/src/lib.rs
+++ b/server-rs/crates/spacetime-client/src/lib.rs
@@ -130,7 +130,7 @@ use module_puzzle::{
 };
 use module_runtime::{
    RuntimeBrowseHistoryRecord, RuntimePlatformTheme as DomainRuntimePlatformTheme,
-    RuntimeProfileDashboardRecord, RuntimeProfilePlayStatsRecord,
+    RuntimeProfileDashboardRecord, RuntimeProfileInviteCodeRecord, RuntimeProfilePlayStatsRecord,
    RuntimeProfileRechargeCenterRecord, RuntimeProfileRechargeOrderRecord,
    RuntimeProfileRedeemCodeMode as DomainRuntimeProfileRedeemCodeMode,
    RuntimeProfileRedeemCodeRecord, RuntimeProfileRewardCodeRedeemRecord,
@@ -139,7 +139,8 @@ use module_runtime::{
    RuntimeSnapshotRecord, build_runtime_browse_history_clear_input,
    build_runtime_browse_history_list_input, build_runtime_browse_history_record,
    build_runtime_browse_history_sync_input, build_runtime_profile_dashboard_get_input,
-    build_runtime_profile_dashboard_record, build_runtime_profile_play_stats_get_input,
+    build_runtime_profile_dashboard_record, build_runtime_profile_invite_code_admin_upsert_input,
+    build_runtime_profile_invite_code_record, build_runtime_profile_play_stats_get_input,
    build_runtime_profile_play_stats_record, build_runtime_profile_recharge_center_get_input,
    build_runtime_profile_recharge_center_record,
    build_runtime_profile_recharge_order_create_input,
--- a/server-rs/crates/spacetime-client/src/mapper.rs
+++ b/server-rs/crates/spacetime-client/src/mapper.rs
@@ -203,6 +203,19 @@ impl From<module_runtime::RuntimeProfileRedeemCodeAdminDisableInput>
    }
 }

+impl From<module_runtime::RuntimeProfileInviteCodeAdminUpsertInput>
+    for RuntimeProfileInviteCodeAdminUpsertInput
+{
+    fn from(input: module_runtime::RuntimeProfileInviteCodeAdminUpsertInput) -> Self {
+        Self {
+            admin_user_id: input.admin_user_id,
+            invite_code: input.invite_code,
+            metadata_json: input.metadata_json,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
 impl From<module_runtime::RuntimeReferralInviteCenterGetInput>
    for RuntimeReferralInviteCenterGetInput
 {
@@ -886,6 +899,26 @@ pub(crate) fn map_runtime_profile_redeem_code_admin_procedure_result(
    ))
 }

+pub(crate) fn map_runtime_profile_invite_code_admin_procedure_result(
+    result: RuntimeProfileInviteCodeAdminProcedureResult,
+) -> Result<RuntimeProfileInviteCodeRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::Procedure(
+            result
+                .error_message
+                .unwrap_or_else(|| "SpacetimeDB procedure 返回未知错误".to_string()),
+        ));
+    }
+
+    let snapshot = result.record.ok_or_else(|| {
+        SpacetimeClientError::Procedure("SpacetimeDB procedure 未返回 invite code 快照".to_string())
+    })?;
+
+    Ok(build_runtime_profile_invite_code_record(
+        map_runtime_profile_invite_code_snapshot(snapshot),
+    ))
+}
+
 pub(crate) fn map_runtime_profile_play_stats_procedure_result(
    result: RuntimeProfilePlayStatsProcedureResult,
 ) -> Result<RuntimeProfilePlayStatsRecord, SpacetimeClientError> {
@@ -1910,6 +1943,18 @@ pub(crate) fn map_runtime_profile_redeem_code_snapshot(
    }
 }

+pub(crate) fn map_runtime_profile_invite_code_snapshot(
+    snapshot: RuntimeProfileInviteCodeSnapshot,
+) -> module_runtime::RuntimeProfileInviteCodeSnapshot {
+    module_runtime::RuntimeProfileInviteCodeSnapshot {
+        user_id: snapshot.user_id,
+        invite_code: snapshot.invite_code,
+        metadata_json: snapshot.metadata_json,
+        created_at_micros: snapshot.created_at_micros,
+        updated_at_micros: snapshot.updated_at_micros,
+    }
+}
+
 pub(crate) fn map_runtime_profile_played_world_snapshot(
    snapshot: RuntimeProfilePlayedWorldSnapshot,
 ) -> module_runtime::RuntimeProfilePlayedWorldSnapshot {
@@ -2783,6 +2828,13 @@ pub(crate) fn map_puzzle_run_snapshot(snapshot: DomainPuzzleRunSnapshot) -> Puzz
 pub(crate) fn map_puzzle_runtime_level_snapshot(
    snapshot: DomainPuzzleRuntimeLevelSnapshot,
 ) -> PuzzleRuntimeLevelRecord {
+    let started_at_ms = if snapshot.started_at_ms == 0 {
+        // 中文注释：旧 run_json 没有计时字段时只补一个可用开始时间，其余限时字段保持旧默认值。
+        current_unix_millis_for_legacy_puzzle_snapshot()
+    } else {
+        snapshot.started_at_ms
+    };
+
    PuzzleRuntimeLevelRecord {
        run_id: snapshot.run_id,
        level_index: snapshot.level_index,
@@ -2794,7 +2846,7 @@ pub(crate) fn map_puzzle_runtime_level_snapshot(
        cover_image_src: snapshot.cover_image_src,
        board: map_puzzle_board_snapshot(snapshot.board),
        status: snapshot.status.as_str().to_string(),
-        started_at_ms: snapshot.started_at_ms,
+        started_at_ms,
        cleared_at_ms: snapshot.cleared_at_ms,
        elapsed_ms: snapshot.elapsed_ms,
        time_limit_ms: snapshot.time_limit_ms,
@@ -2812,6 +2864,13 @@ pub(crate) fn map_puzzle_runtime_level_snapshot(
    }
 }

+fn current_unix_millis_for_legacy_puzzle_snapshot() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|duration| duration.as_millis().min(u128::from(u64::MAX)) as u64)
+        .unwrap_or(1)
+}
+
 pub(crate) fn map_puzzle_leaderboard_entry(
    snapshot: module_puzzle::PuzzleLeaderboardEntry,
 ) -> PuzzleLeaderboardEntryRecord {
--- a/server-rs/crates/spacetime-client/src/module_bindings/admin_upsert_profile_invite_code_procedure.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/admin_upsert_profile_invite_code_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::runtime_profile_invite_code_admin_procedure_result_type::RuntimeProfileInviteCodeAdminProcedureResult;
+use super::runtime_profile_invite_code_admin_upsert_input_type::RuntimeProfileInviteCodeAdminUpsertInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct AdminUpsertProfileInviteCodeArgs {
+    pub input: RuntimeProfileInviteCodeAdminUpsertInput,
+}
+
+impl __sdk::InModule for AdminUpsertProfileInviteCodeArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `admin_upsert_profile_invite_code`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait admin_upsert_profile_invite_code {
+    fn admin_upsert_profile_invite_code(&self, input: RuntimeProfileInviteCodeAdminUpsertInput) {
+        self.admin_upsert_profile_invite_code_then(input, |_, _| {});
+    }
+
+    fn admin_upsert_profile_invite_code_then(
+        &self,
+        input: RuntimeProfileInviteCodeAdminUpsertInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<RuntimeProfileInviteCodeAdminProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl admin_upsert_profile_invite_code for super::RemoteProcedures {
+    fn admin_upsert_profile_invite_code_then(
+        &self,
+        input: RuntimeProfileInviteCodeAdminUpsertInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<RuntimeProfileInviteCodeAdminProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, RuntimeProfileInviteCodeAdminProcedureResult>(
+                "admin_upsert_profile_invite_code",
+                AdminUpsertProfileInviteCodeArgs { input },
+                __callback,
+            );
+    }
+}
--- a/server-rs/crates/spacetime-client/src/module_bindings/mod.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/mod.rs
@@ -11,6 +11,7 @@ use spacetimedb_sdk::__codegen::{
 	__ws,
 };

+pub mod admin_upsert_profile_invite_code_procedure;
 pub mod ai_result_reference_type;
 pub mod ai_result_reference_input_type;
 pub mod ai_result_reference_kind_type;
@@ -329,6 +330,9 @@ pub mod runtime_platform_theme_type;
 pub mod runtime_profile_dashboard_get_input_type;
 pub mod runtime_profile_dashboard_procedure_result_type;
 pub mod runtime_profile_dashboard_snapshot_type;
+pub mod runtime_profile_invite_code_admin_procedure_result_type;
+pub mod runtime_profile_invite_code_admin_upsert_input_type;
+pub mod runtime_profile_invite_code_snapshot_type;
 pub mod runtime_profile_membership_benefit_snapshot_type;
 pub mod runtime_profile_membership_snapshot_type;
 pub mod runtime_profile_membership_status_type;
@@ -560,6 +564,7 @@ pub mod upsert_runtime_setting_and_return_procedure;
 pub mod upsert_runtime_snapshot_and_return_procedure;
 pub mod use_puzzle_runtime_prop_procedure;

+pub use admin_upsert_profile_invite_code_procedure::admin_upsert_profile_invite_code;
 pub use ai_result_reference_type::AiResultReference;
 pub use ai_result_reference_input_type::AiResultReferenceInput;
 pub use ai_result_reference_kind_type::AiResultReferenceKind;
@@ -878,6 +883,9 @@ pub use runtime_platform_theme_type::RuntimePlatformTheme;
 pub use runtime_profile_dashboard_get_input_type::RuntimeProfileDashboardGetInput;
 pub use runtime_profile_dashboard_procedure_result_type::RuntimeProfileDashboardProcedureResult;
 pub use runtime_profile_dashboard_snapshot_type::RuntimeProfileDashboardSnapshot;
+pub use runtime_profile_invite_code_admin_procedure_result_type::RuntimeProfileInviteCodeAdminProcedureResult;
+pub use runtime_profile_invite_code_admin_upsert_input_type::RuntimeProfileInviteCodeAdminUpsertInput;
+pub use runtime_profile_invite_code_snapshot_type::RuntimeProfileInviteCodeSnapshot;
 pub use runtime_profile_membership_benefit_snapshot_type::RuntimeProfileMembershipBenefitSnapshot;
 pub use runtime_profile_membership_snapshot_type::RuntimeProfileMembershipSnapshot;
 pub use runtime_profile_membership_status_type::RuntimeProfileMembershipStatus;
--- a/server-rs/crates/spacetime-client/src/module_bindings/profile_invite_code_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/profile_invite_code_type.rs
@@ -15,6 +15,7 @@ use spacetimedb_sdk::__codegen::{
 pub struct ProfileInviteCode {
    pub user_id: String,
    pub invite_code: String,
+    pub metadata_json: String,
    pub created_at: __sdk::Timestamp,
    pub updated_at: __sdk::Timestamp,
 }
@@ -31,6 +32,7 @@ impl __sdk::InModule for ProfileInviteCode {
 pub struct ProfileInviteCodeCols {
    pub user_id: __sdk::__query_builder::Col<ProfileInviteCode, String>,
    pub invite_code: __sdk::__query_builder::Col<ProfileInviteCode, String>,
+    pub metadata_json: __sdk::__query_builder::Col<ProfileInviteCode, String>,
    pub created_at: __sdk::__query_builder::Col<ProfileInviteCode, __sdk::Timestamp>,
    pub updated_at: __sdk::__query_builder::Col<ProfileInviteCode, __sdk::Timestamp>,
 }
@@ -41,6 +43,7 @@ impl __sdk::__query_builder::HasCols for ProfileInviteCode {
        ProfileInviteCodeCols {
            user_id: __sdk::__query_builder::Col::new(table_name, "user_id"),
            invite_code: __sdk::__query_builder::Col::new(table_name, "invite_code"),
+            metadata_json: __sdk::__query_builder::Col::new(table_name, "metadata_json"),
            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),

--- a/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_procedure_result_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::runtime_profile_invite_code_snapshot_type::RuntimeProfileInviteCodeSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct RuntimeProfileInviteCodeAdminProcedureResult {
+    pub ok: bool,
+    pub record: Option<RuntimeProfileInviteCodeSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for RuntimeProfileInviteCodeAdminProcedureResult {
+    type Module = super::RemoteModule;
+}
--- a/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_upsert_input_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_upsert_input_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct RuntimeProfileInviteCodeAdminUpsertInput {
+    pub admin_user_id: String,
+    pub invite_code: String,
+    pub metadata_json: String,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for RuntimeProfileInviteCodeAdminUpsertInput {
+    type Module = super::RemoteModule;
+}
--- a/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_snapshot_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct RuntimeProfileInviteCodeSnapshot {
+    pub user_id: String,
+    pub invite_code: String,
+    pub metadata_json: String,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for RuntimeProfileInviteCodeSnapshot {
+    type Module = super::RemoteModule;
+}
--- a/server-rs/crates/spacetime-client/src/runtime.rs
+++ b/server-rs/crates/spacetime-client/src/runtime.rs
@@ -346,6 +346,35 @@ impl SpacetimeClient {
        .await
    }

+    pub async fn admin_upsert_profile_invite_code(
+        &self,
+        admin_user_id: String,
+        invite_code: String,
+        metadata_json: String,
+        updated_at_micros: i64,
+    ) -> Result<RuntimeProfileInviteCodeRecord, SpacetimeClientError> {
+        let procedure_input = build_runtime_profile_invite_code_admin_upsert_input(
+            admin_user_id,
+            invite_code,
+            metadata_json,
+            updated_at_micros,
+        )
+        .map_err(|error| SpacetimeClientError::Runtime(error.to_string()))?
+        .into();
+
+        self.call_after_connect(move |connection, sender| {
+            connection
+                .procedures()
+                .admin_upsert_profile_invite_code_then(procedure_input, move |_, result| {
+                    let mapped = result
+                        .map_err(|error| SpacetimeClientError::Procedure(error.to_string()))
+                        .and_then(map_runtime_profile_invite_code_admin_procedure_result);
+                    send_once(&sender, mapped);
+                });
+        })
+        .await
+    }
+
    pub async fn get_profile_play_stats(
        &self,
        user_id: String,
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -1101,6 +1101,14 @@ fn normalize_migration_row(table_name: &str, value: &serde_json::Value) -> serde
                .or_insert(serde_json::Value::Null);
        }
    }
+    if table_name == "profile_invite_code" {
+        if let Some(object) = next_value.as_object_mut() {
+            // 中文注释：邀请码 metadata 晚于邀请表加入，旧迁移包按空对象兼容。
+            object
+                .entry("metadata_json".to_string())
+                .or_insert_with(|| serde_json::Value::String("{}".to_string()));
+        }
+    }
    if table_name == "big_fish_creation_session" {
        if let Some(object) = next_value.as_object_mut() {
            // 中文注释：旧迁移包没有公开游玩次数字段，导入时按新建作品默认 0 兼容。
--- a/server-rs/crates/spacetime-module/src/runtime/profile.rs
+++ b/server-rs/crates/spacetime-module/src/runtime/profile.rs
@@ -70,6 +70,7 @@ pub struct ProfileInviteCode {
    pub(crate) user_id: String,
    #[unique]
    pub(crate) invite_code: String,
+    pub(crate) metadata_json: String,
    pub(crate) created_at: Timestamp,
    pub(crate) updated_at: Timestamp,
 }
@@ -528,6 +529,25 @@ pub fn admin_disable_profile_redeem_code(
    }
 }

+#[spacetimedb::procedure]
+pub fn admin_upsert_profile_invite_code(
+    ctx: &mut ProcedureContext,
+    input: RuntimeProfileInviteCodeAdminUpsertInput,
+) -> RuntimeProfileInviteCodeAdminProcedureResult {
+    match ctx.try_with_tx(|tx| admin_upsert_profile_invite_code_record(tx, input.clone())) {
+        Ok(record) => RuntimeProfileInviteCodeAdminProcedureResult {
+            ok: true,
+            record: Some(record),
+            error_message: None,
+        },
+        Err(message) => RuntimeProfileInviteCodeAdminProcedureResult {
+            ok: false,
+            record: None,
+            error_message: Some(message),
+        },
+    }
+}
+
 pub(crate) fn list_profile_save_archive_rows(
    ctx: &ReducerContext,
    input: RuntimeProfileSaveArchiveListInput,
@@ -1534,10 +1554,14 @@ fn redeem_profile_referral_invite_code_record(
        ),
        bound_at,
    )?;
-    let today_inviter_reward_count =
-        count_today_profile_referral_inviter_rewards(ctx, &inviter_code.user_id, bound_at);
-    let inviter_reward_granted =
-        today_inviter_reward_count < PROFILE_REFERRAL_DAILY_INVITER_REWARD_LIMIT;
+    let is_admin_invite_code = is_admin_profile_invite_code_user_id(&inviter_code.user_id);
+    let today_inviter_reward_count = if is_admin_invite_code {
+        0
+    } else {
+        count_today_profile_referral_inviter_rewards(ctx, &inviter_code.user_id, bound_at)
+    };
+    let inviter_reward_granted = !is_admin_invite_code
+        && today_inviter_reward_count < PROFILE_REFERRAL_DAILY_INVITER_REWARD_LIMIT;
    let inviter_balance_after = if inviter_reward_granted {
        apply_profile_wallet_delta(
            ctx,
@@ -1753,6 +1777,56 @@ fn admin_disable_profile_redeem_code_record(
    Ok(build_profile_redeem_code_snapshot_from_row(&inserted))
 }

+fn admin_upsert_profile_invite_code_record(
+    ctx: &ReducerContext,
+    input: RuntimeProfileInviteCodeAdminUpsertInput,
+) -> Result<RuntimeProfileInviteCodeSnapshot, String> {
+    let validated_input = build_runtime_profile_invite_code_admin_upsert_input(
+        input.admin_user_id,
+        input.invite_code,
+        input.metadata_json,
+        input.updated_at_micros,
+    )
+    .map_err(|error| error.to_string())?;
+    let updated_at = Timestamp::from_micros_since_unix_epoch(validated_input.updated_at_micros);
+    let user_id = build_admin_profile_invite_code_user_id(
+        &validated_input.admin_user_id,
+        &validated_input.invite_code,
+    );
+
+    if let Some(existing) = ctx
+        .db
+        .profile_invite_code()
+        .invite_code()
+        .find(&validated_input.invite_code)
+    {
+        if existing.user_id != user_id {
+            return Err("邀请码已被其他用户占用".to_string());
+        }
+        ctx.db
+            .profile_invite_code()
+            .user_id()
+            .delete(&existing.user_id);
+        let inserted = ctx.db.profile_invite_code().insert(ProfileInviteCode {
+            user_id,
+            invite_code: validated_input.invite_code,
+            metadata_json: validated_input.metadata_json,
+            created_at: existing.created_at,
+            updated_at,
+        });
+        return Ok(build_profile_invite_code_snapshot_from_row(&inserted));
+    }
+
+    let inserted = ctx.db.profile_invite_code().insert(ProfileInviteCode {
+        user_id,
+        invite_code: validated_input.invite_code,
+        metadata_json: validated_input.metadata_json,
+        created_at: updated_at,
+        updated_at,
+    });
+    Ok(build_profile_invite_code_snapshot_from_row(&inserted))
+}
+
 fn build_profile_referral_invite_center_snapshot(
    ctx: &ReducerContext,
    user_id: &str,
@@ -1825,6 +1899,7 @@ fn ensure_profile_invite_code(ctx: &ReducerContext, user_id: &str) -> ProfileInv
    ctx.db.profile_invite_code().insert(ProfileInviteCode {
        user_id: user_id.to_string(),
        invite_code,
+        metadata_json: PROFILE_INVITE_CODE_METADATA_DEFAULT_JSON.to_string(),
        created_at: ctx.timestamp,
        updated_at: ctx.timestamp,
    })
@@ -1856,6 +1931,14 @@ fn count_today_profile_referral_inviter_rewards(
        .count() as u32
 }

+fn is_admin_profile_invite_code_user_id(user_id: &str) -> bool {
+    user_id.starts_with("admin:")
+}
+
+fn build_admin_profile_invite_code_user_id(admin_user_id: &str, invite_code: &str) -> String {
+    format!("admin:{}:{}", admin_user_id, invite_code)
+}
+
 fn profile_wallet_balance(ctx: &ReducerContext, user_id: &str) -> u64 {
    ctx.db
        .profile_dashboard_state()
@@ -2206,6 +2289,18 @@ fn build_profile_redeem_code_snapshot_from_row(
    }
 }

+fn build_profile_invite_code_snapshot_from_row(
+    row: &ProfileInviteCode,
+) -> RuntimeProfileInviteCodeSnapshot {
+    RuntimeProfileInviteCodeSnapshot {
+        user_id: row.user_id.clone(),
+        invite_code: row.invite_code.clone(),
+        metadata_json: row.metadata_json.clone(),
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
 fn build_profile_wallet_ledger_snapshot_from_row(
    row: &ProfileWalletLedger,
 ) -> RuntimeProfileWalletLedgerEntrySnapshot {
--- a/spacetime.json
+++ b/spacetime.json
@@ -1,4 +1,4 @@
 {
-  "server": "http://127.0.0.1:3101",
+  "server": "local",
  "module-path": "./server-rs/crates/spacetime-module"
 }
--- a/src/components/auth/AuthGate.test.tsx
+++ b/src/components/auth/AuthGate.test.tsx
@@ -88,13 +88,19 @@ const mockUser: AuthUser = {

 beforeEach(() => {
  vi.clearAllMocks();
+  window.history.replaceState(null, '', '/');
  authMocks.consumeAuthCallbackResult.mockReturnValue(null);
  authMocks.ensureStoredAccessToken.mockResolvedValue('jwt-existing-token');
  authMocks.getCurrentAuthUser.mockResolvedValue({
    user: null,
    availableLoginMethods: ['phone'],
  });
-  authMocks.loginWithPhoneCode.mockResolvedValue(mockUser);
+  authMocks.loginWithPhoneCode.mockResolvedValue({
+    token: 'jwt-phone',
+    user: mockUser,
+    created: false,
+    referral: null,
+  });
  authMocks.authEntry.mockResolvedValue(mockUser);
  authMocks.changePassword.mockResolvedValue(mockUser);
  authMocks.logoutAllAuthSessions.mockResolvedValue(undefined);
@@ -287,6 +293,7 @@ test('auth gate opens a login modal for protected actions and resumes after logi
    expect(authMocks.loginWithPhoneCode).toHaveBeenCalledWith(
      '13800000000',
      '123456',
+      undefined,
    );
    expect(authMocks.getCurrentAuthUser).toHaveBeenCalledTimes(1);
    expect(onAuthenticated).toHaveBeenCalledTimes(1);
@@ -295,6 +302,44 @@ test('auth gate opens a login modal for protected actions and resumes after logi
  expect(screen.queryByRole('dialog', { name: '账号入口' })).toBeNull();
 });

+test('auth gate opens register tab and preloads invite code from url', async () => {
+  const user = userEvent.setup();
+  window.history.replaceState(null, '', '/?inviteCode=spring-2026');
+  authMocks.getAuthLoginOptions.mockResolvedValue({
+    availableLoginMethods: ['phone'],
+  });
+
+  render(
+    <AuthGate>
+      <div>公开内容</div>
+    </AuthGate>,
+  );
+
+  const dialog = await screen.findByRole('dialog', { name: '账号入口' });
+  await waitFor(() => {
+    expect(
+      within(dialog)
+        .getByRole('tab', { name: '注册' })
+        .getAttribute('aria-selected'),
+    ).toBe('true');
+  });
+  expect(
+    (within(dialog).getByLabelText('邀请码') as HTMLInputElement).value,
+  ).toBe('SPRING2026');
+
+  await user.type(within(dialog).getByLabelText('手机号'), '13800000000');
+  await user.type(within(dialog).getByLabelText('验证码'), '123456');
+  await user.click(within(dialog).getByRole('button', { name: '注册' }));
+
+  await waitFor(() => {
+    expect(authMocks.loginWithPhoneCode).toHaveBeenCalledWith(
+      '13800000000',
+      '123456',
+      'SPRING2026',
+    );
+  });
+});
+
 test('auth state refresh keeps mounted platform content and local tab state', async () => {
  const user = userEvent.setup();
  authMocks.getCurrentAuthUser.mockResolvedValue({
--- a/src/components/auth/AuthGate.tsx
+++ b/src/components/auth/AuthGate.tsx
@@ -59,6 +59,14 @@ type AuthStatus =

 const FALLBACK_LOGIN_METHODS: AuthLoginMethod[] = ['password'];

+function readInviteCodeFromLocation(): string {
+  const params = new URLSearchParams(window.location.search || '');
+  return (params.get('inviteCode') || params.get('invite_code') || '')
+    .trim()
+    .replace(/[^0-9a-z]/gi, '')
+    .toUpperCase();
+}
+
 function normalizeAvailableLoginMethods(
  methods: AuthLoginMethod[] | null | undefined,
 ): AuthLoginMethod[] {
@@ -83,6 +91,10 @@ export function AuthGate({ children }: AuthGateProps) {
  const [bindingPhone, setBindingPhone] = useState(false);
  const [wechatLoading, setWechatLoading] = useState(false);
  const [showLoginModal, setShowLoginModal] = useState(false);
+  const [loginInitialMode, setLoginInitialMode] = useState<
+    'login' | 'register'
+  >('login');
+  const [pendingInviteCode, setPendingInviteCode] = useState('');
  const [showSettingsModal, setShowSettingsModal] = useState(false);
  const [settingsEntryMode, setSettingsEntryMode] = useState<
    'settings' | 'account'
@@ -102,6 +114,7 @@ export function AuthGate({ children }: AuthGateProps) {
  const [changePhoneCaptchaChallenge, setChangePhoneCaptchaChallenge] =
    useState<AuthCaptchaChallenge | null>(null);
  const pendingProtectedActionRef = useRef<(() => void) | null>(null);
+  const autoOpenedInviteCodeRef = useRef<string | null>(null);
  const hasRenderedPlatformContentRef = useRef(false);
  const canKeepPlatformContentMounted =
    hasRenderedPlatformContentRef.current &&
@@ -169,6 +182,8 @@ export function AuthGate({ children }: AuthGateProps) {
  const closeLoginModal = useCallback(() => {
    pendingProtectedActionRef.current = null;
    setShowLoginModal(false);
+    setLoginInitialMode('login');
+    setPendingInviteCode('');
    setLoginCaptchaChallenge(null);
    setError('');
  }, []);
@@ -187,6 +202,8 @@ export function AuthGate({ children }: AuthGateProps) {
      }

      pendingProtectedActionRef.current = postLoginAction ?? null;
+      setLoginInitialMode('login');
+      setPendingInviteCode('');
      setShowLoginModal(true);
    },
    [readyUser],
@@ -224,6 +241,24 @@ export function AuthGate({ children }: AuthGateProps) {
    openLoginModal();
  }, [openLoginModal, readyUser]);

+  useEffect(() => {
+    if (status !== 'unauthenticated' || readyUser || showLoginModal) {
+      return;
+    }
+    const inviteCode = readInviteCodeFromLocation();
+    if (!inviteCode) {
+      return;
+    }
+    if (autoOpenedInviteCodeRef.current === inviteCode) {
+      return;
+    }
+    autoOpenedInviteCodeRef.current = inviteCode;
+    pendingProtectedActionRef.current = null;
+    setPendingInviteCode(inviteCode);
+    setLoginInitialMode('register');
+    setShowLoginModal(true);
+  }, [readyUser, showLoginModal, status]);
+
  useEffect(() => {
    let isActive = true;

@@ -703,6 +738,8 @@ export function AuthGate({ children }: AuthGateProps) {
            wechatLoading={wechatLoading}
            error={error}
            captchaChallenge={loginCaptchaChallenge}
+            initialMode={loginInitialMode}
+            initialInviteCode={pendingInviteCode}
            onClose={closeLoginModal}
            onSendCode={async (phone, scene, captcha) => {
              setSendingCode(true);
@@ -727,14 +764,21 @@ export function AuthGate({ children }: AuthGateProps) {
                setSendingCode(false);
              }
            }}
-            onPhoneSubmit={async (phone, code) => {
+            onPhoneSubmit={async (phone, code, inviteCode) => {
              setLoggingIn(true);
              setError('');
              try {
-                const nextUser = await loginWithPhoneCode(phone, code);
+                const response = await loginWithPhoneCode(
+                  phone,
+                  code,
+                  inviteCode,
+                );
                setStoredLastLoginPhone(phone);
                setLoginCaptchaChallenge(null);
-                activateReadyUser(nextUser);
+                if (response.referral && !response.referral.ok) {
+                  setError(response.referral.message || '邀请码未绑定');
+                }
+                activateReadyUser(response.user);
              } catch (loginError) {
                setError(
                  loginError instanceof Error
--- a/src/components/auth/LoginScreen.tsx
+++ b/src/components/auth/LoginScreen.tsx
@@ -10,7 +10,7 @@ import { getStoredLastLoginPhone } from '../../services/authService';
 import { CaptchaChallengeField } from './CaptchaChallengeField';

 type SmsScene = 'login' | 'reset_password';
-type LoginTab = 'phone' | 'password';
+type LoginTab = 'phone' | 'password' | 'register';

 type LoginScreenProps = {
  isOpen: boolean;
@@ -21,6 +21,8 @@ type LoginScreenProps = {
  wechatLoading: boolean;
  error: string;
  captchaChallenge: AuthCaptchaChallenge | null;
+  initialMode?: 'login' | 'register';
+  initialInviteCode?: string;
  onClose: () => void;
  onSendCode: (
    phone: string,
@@ -33,7 +35,11 @@ type LoginScreenProps = {
    cooldownSeconds: number;
    expiresInSeconds: number;
  }>;
-  onPhoneSubmit: (phone: string, code: string) => Promise<void>;
+  onPhoneSubmit: (
+    phone: string,
+    code: string,
+    inviteCode?: string,
+  ) => Promise<void>;
  onPasswordSubmit: (phone: string, password: string) => Promise<void>;
  onResetPassword: (
    phone: string,
@@ -52,6 +58,8 @@ export function LoginScreen({
  wechatLoading,
  error,
  captchaChallenge,
+  initialMode = 'login',
+  initialInviteCode = '',
  onClose,
  onSendCode,
  onPhoneSubmit,
@@ -66,6 +74,7 @@ export function LoginScreen({
  const [resetPhone, setResetPhone] = useState('');
  const [resetCode, setResetCode] = useState('');
  const [resetPasswordValue, setResetPasswordValue] = useState('');
+  const [inviteCode, setInviteCode] = useState(initialInviteCode);
  const [captchaAnswer, setCaptchaAnswer] = useState('');
  const [cooldownSeconds, setCooldownSeconds] = useState(0);
  const [resetCooldownSeconds, setResetCooldownSeconds] = useState(0);
@@ -88,16 +97,23 @@ export function LoginScreen({
    setResetPhone('');
    setResetCode('');
    setResetPasswordValue('');
+    setInviteCode(initialInviteCode);
    setCaptchaAnswer('');
    setCooldownSeconds(0);
    setResetCooldownSeconds(0);
    setHint('');
-    setActiveLoginTab(phoneLoginEnabled ? 'phone' : 'password');
-  }, [isOpen, phoneLoginEnabled]);
+    setActiveLoginTab(
+      initialMode === 'register' && phoneLoginEnabled
+        ? 'register'
+        : phoneLoginEnabled
+          ? 'phone'
+          : 'password',
+    );
+  }, [initialInviteCode, initialMode, isOpen, phoneLoginEnabled]);

  useEffect(() => {
    if (
-      activeLoginTab === 'phone' &&
+      (activeLoginTab === 'phone' || activeLoginTab === 'register') &&
      !phoneLoginEnabled &&
      passwordLoginEnabled
    ) {
@@ -196,9 +212,11 @@ export function LoginScreen({
          />
        ) : (
          <div className="flex flex-col gap-5 px-5 py-5">
-            {phoneLoginEnabled && passwordLoginEnabled ? (
+            {phoneLoginEnabled ? (
              <div
-                className="grid grid-cols-2 gap-2"
+                className={`grid gap-2 ${
+                  passwordLoginEnabled ? 'grid-cols-3' : 'grid-cols-2'
+                }`}
                role="tablist"
                aria-label="登录方式"
              >
@@ -208,11 +226,19 @@ export function LoginScreen({
                >
                  短信登录
                </LoginTabButton>
+                {passwordLoginEnabled ? (
+                  <LoginTabButton
+                    active={activeLoginTab === 'password'}
+                    onClick={() => setActiveLoginTab('password')}
+                  >
+                    密码登录
+                  </LoginTabButton>
+                ) : null}
                <LoginTabButton
-                  active={activeLoginTab === 'password'}
-                  onClick={() => setActiveLoginTab('password')}
+                  active={activeLoginTab === 'register'}
+                  onClick={() => setActiveLoginTab('register')}
                >
-                  密码登录
+                  注册
                </LoginTabButton>
              </div>
            ) : null}
@@ -312,6 +338,42 @@ export function LoginScreen({
              />
            ) : null}

+            {phoneLoginEnabled && activeLoginTab === 'register' ? (
+              <PhoneCodeForm
+                phone={phone}
+                code={code}
+                inviteCode={inviteCode}
+                captchaAnswer={captchaAnswer}
+                captchaChallenge={captchaChallenge}
+                cooldownSeconds={cooldownSeconds}
+                sendingCode={sendingCode}
+                loggingIn={loggingIn}
+                error={error}
+                hint={hint}
+                submitLabel="注册"
+                enabled={phoneLoginEnabled}
+                showPhoneField
+                showInviteCodeField
+                onPhoneChange={setPhone}
+                onCodeChange={setCode}
+                onInviteCodeChange={setInviteCode}
+                onCaptchaAnswerChange={setCaptchaAnswer}
+                onSendCode={async () => {
+                  setHint('');
+                  const result = await onSendCode(phone, 'login', {
+                    challengeId: captchaChallenge?.challengeId,
+                    answer: captchaAnswer,
+                  });
+                  setCooldownSeconds(result.cooldownSeconds);
+                  setHint(
+                    `短信请求已提交，验证码有效期约 ${Math.max(1, Math.round(result.expiresInSeconds / 60))} 分钟。`,
+                  );
+                  setCaptchaAnswer('');
+                }}
+                onSubmit={() => onPhoneSubmit(phone, code, inviteCode)}
+              />
+            ) : null}
+
            {!passwordLoginEnabled &&
            !phoneLoginEnabled &&
            !wechatLoginEnabled ? (
@@ -358,6 +420,7 @@ function LoginTabButton({
 function PhoneCodeForm({
  phone,
  code,
+  inviteCode = '',
  captchaAnswer,
  captchaChallenge,
  cooldownSeconds,
@@ -368,14 +431,17 @@ function PhoneCodeForm({
  submitLabel,
  enabled,
  showPhoneField,
+  showInviteCodeField = false,
  onPhoneChange,
  onCodeChange,
+  onInviteCodeChange,
  onCaptchaAnswerChange,
  onSendCode,
  onSubmit,
 }: {
  phone: string;
  code: string;
+  inviteCode?: string;
  captchaAnswer: string;
  captchaChallenge: AuthCaptchaChallenge | null;
  cooldownSeconds: number;
@@ -386,8 +452,10 @@ function PhoneCodeForm({
  submitLabel: string;
  enabled: boolean;
  showPhoneField: boolean;
+  showInviteCodeField?: boolean;
  onPhoneChange: (value: string) => void;
  onCodeChange: (value: string) => void;
+  onInviteCodeChange?: (value: string) => void;
  onCaptchaAnswerChange: (value: string) => void;
  onSendCode: () => Promise<void>;
  onSubmit: () => Promise<void>;
@@ -418,6 +486,19 @@ function PhoneCodeForm({
        </label>
      ) : null}

+      {showInviteCodeField ? (
+        <label className="grid gap-2 text-sm text-[var(--platform-text-base)]">
+          <span>邀请码</span>
+          <input
+            className="platform-input"
+            autoComplete="off"
+            value={inviteCode}
+            onChange={(event) => onInviteCodeChange?.(event.target.value)}
+            placeholder="邀请码"
+          />
+        </label>
+      ) : null}
+
      <label className="grid gap-2 text-sm text-[var(--platform-text-base)]">
        <span>验证码</span>
        <div className="flex gap-3">
--- a/src/components/rpg-entry/RpgEntryHomeView.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.tsx
@@ -47,7 +47,6 @@ import type {
  ProfileReferralInviteCenterResponse,
  ProfileSaveArchiveSummary,
  ProfileWalletLedgerResponse,
-  RedeemProfileReferralInviteCodeResponse,
  RedeemProfileRewardCodeResponse,
 } from '../../../packages/shared/src/contracts/runtime';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
@@ -57,7 +56,6 @@ import { copyTextToClipboard } from '../../services/clipboard';
 import {
  getRpgProfileReferralInviteCenter,
  getRpgProfileWalletLedger,
-  redeemRpgProfileReferralInviteCode,
  redeemRpgProfileRewardCode,
 } from '../../services/rpg-entry/rpgProfileClient';
 import type { CustomWorldProfile } from '../../types';
@@ -144,7 +142,7 @@ const PLATFORM_HOME_TABS: PlatformHomeTab[] = [
 const AVATAR_MAX_FILE_SIZE = 5 * 1024 * 1024;
 const AVATAR_OUTPUT_SIZE = 256;
 const AVATAR_ALLOWED_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);
-type ProfilePopupPanel = 'invite' | 'redeem' | 'community';
+type ProfilePopupPanel = 'invite' | 'community';
 type MobileHomeChannel = 'recommend' | 'today' | 'category';
 type PlatformRankingTab = 'hot' | 'remix' | 'new' | 'like';

@@ -1841,34 +1839,21 @@ function RewardCodeRedeemModal({
 function ProfileReferralModal({
  panel,
  center,
-  inviteCodeInput,
  isLoading,
-  isSubmitting,
  error,
  success,
  onClose,
-  onInputChange,
  onCopyInvite,
-  onSubmitRedeem,
 }: {
  panel: ProfilePopupPanel;
  center: ProfileReferralInviteCenterResponse | null;
-  inviteCodeInput: string;
  isLoading: boolean;
-  isSubmitting: boolean;
  error: string | null;
  success: string | null;
  onClose: () => void;
-  onInputChange: (value: string) => void;
  onCopyInvite: () => void;
-  onSubmitRedeem: () => void;
 }) {
-  const title =
-    panel === 'invite'
-      ? '邀请好友'
-      : panel === 'redeem'
-        ? '填邀请码'
-        : '玩家社区';
+  const title = panel === 'invite' ? '邀请好友' : '玩家社区';

  return (
    <div className="fixed inset-0 z-[80] flex items-center justify-center bg-black/42 px-3 py-5">
@@ -1911,7 +1896,7 @@ function ProfileReferralModal({
              <div className="h-20 animate-pulse rounded-xl bg-zinc-100" />
              <div className="h-10 animate-pulse rounded-xl bg-zinc-100" />
            </div>
-          ) : panel === 'invite' ? (
+          ) : (
            <div className="mt-5 space-y-3">
              <div className="rounded-xl bg-zinc-50 px-4 py-4 text-center">
                <div className="text-[11px] font-bold text-zinc-500">
@@ -1951,31 +1936,6 @@ function ProfileReferralModal({
                </div>
              </div>
            </div>
-          ) : (
-            <div className="mt-5 space-y-3">
-              {center?.hasRedeemedCode ? (
-                <div className="rounded-xl bg-emerald-50 px-4 py-4 text-center text-sm font-bold text-emerald-700">
-                  已填写邀请码
-                </div>
-              ) : (
-                <>
-                  <input
-                    value={inviteCodeInput}
-                    onChange={(event) => onInputChange(event.target.value)}
-                    placeholder="输入邀请码"
-                    className="w-full rounded-xl border border-zinc-200 bg-zinc-50 px-4 py-3 text-center text-base font-black tracking-[0.14em] outline-none focus:border-[#ff4056]"
-                  />
-                  <button
-                    type="button"
-                    onClick={onSubmitRedeem}
-                    disabled={isSubmitting || !inviteCodeInput.trim()}
-                    className="w-full rounded-xl bg-[#ff4056] px-4 py-3 text-sm font-black text-white disabled:opacity-60"
-                  >
-                    {isSubmitting ? '提交中' : '确认填写'}
-                  </button>
-                </>
-              )}
-            </div>
          )}

          {error ? (
@@ -2153,10 +2113,8 @@ export function RpgEntryHomeView({
  const [referralCenter, setReferralCenter] =
    useState<ProfileReferralInviteCenterResponse | null>(null);
  const [isLoadingReferral, setIsLoadingReferral] = useState(false);
-  const [isSubmittingReferral, setIsSubmittingReferral] = useState(false);
  const [referralError, setReferralError] = useState<string | null>(null);
  const [referralSuccess, setReferralSuccess] = useState<string | null>(null);
-  const [inviteCodeInput, setInviteCodeInput] = useState('');
  const [selectedCategoryTag, setSelectedCategoryTag] = useState<string | null>(
    null,
  );
@@ -2519,30 +2477,6 @@ export function RpgEntryHomeView({
      },
    );
  };
-  const submitReferralInviteCode = () => {
-    if (isSubmittingReferral || !inviteCodeInput.trim()) {
-      return;
-    }
-
-    setIsSubmittingReferral(true);
-    setReferralError(null);
-    setReferralSuccess(null);
-    void redeemRpgProfileReferralInviteCode(inviteCodeInput)
-      .then((response: RedeemProfileReferralInviteCodeResponse) => {
-        setReferralCenter(response.center);
-        setInviteCodeInput('');
-        setReferralSuccess(
-          response.inviteeRewardGranted ? '已获得30陶泥币' : '填写成功',
-        );
-        void onRechargeSuccess?.();
-      })
-      .catch((error: unknown) => {
-        setReferralError(
-          error instanceof Error ? error.message : '填写邀请码失败',
-        );
-      })
-      .finally(() => setIsSubmittingReferral(false));
-  };
  const openRewardCodeModal = () => {
    setIsRewardCodeOpen(true);
    setRewardCodeError(null);
@@ -3061,17 +2995,12 @@ export function RpgEntryHomeView({

          <section className={`${PANEL_SURFACE_CLASS} px-4 py-3.5`}>
            <SectionHeader title="常用功能" detail="快捷入口" />
-            <div className="grid grid-cols-3 gap-3">
+            <div className="grid grid-cols-2 gap-3">
              <ProfileShortcutButton
                label="邀请好友"
                icon={UserPlus}
                onClick={() => openProfilePopupPanel('invite')}
              />
-              <ProfileShortcutButton
-                label="填邀请码"
-                icon={Ticket}
-                onClick={() => openProfilePopupPanel('redeem')}
-              />
              <ProfileShortcutButton
                label="玩家社区"
                icon={MessageCircle}
@@ -3506,15 +3435,11 @@ export function RpgEntryHomeView({
          <ProfileReferralModal
            panel={profilePopupPanel}
            center={referralCenter}
-            inviteCodeInput={inviteCodeInput}
            isLoading={isLoadingReferral}
-            isSubmitting={isSubmittingReferral}
            error={referralError}
            success={referralSuccess}
            onClose={() => setProfilePopupPanel(null)}
-            onInputChange={setInviteCodeInput}
            onCopyInvite={copyInviteInfo}
-            onSubmitRedeem={submitReferralInviteCode}
          />
        ) : null}
        {rewardCodeModal}
@@ -3628,15 +3553,11 @@ export function RpgEntryHomeView({
        <ProfileReferralModal
          panel={profilePopupPanel}
          center={referralCenter}
-          inviteCodeInput={inviteCodeInput}
          isLoading={isLoadingReferral}
-          isSubmitting={isSubmittingReferral}
          error={referralError}
          success={referralSuccess}
          onClose={() => setProfilePopupPanel(null)}
-          onInputChange={setInviteCodeInput}
          onCopyInvite={copyInviteInfo}
-          onSubmitRedeem={submitReferralInviteCode}
        />
      ) : null}
      {isProfilePlayStatsOpen ? (
--- a/src/services/authService.test.ts
+++ b/src/services/authService.test.ts
@@ -219,15 +219,20 @@ describe('authService', () => {
      },
    });

-    const user = await loginWithPhoneCode('13800138000', '123456');
+    const response = await loginWithPhoneCode(
+      '13800138000',
+      '123456',
+      'spring-2026',
+    );

-    expect(user.username).toBe('138****8000');
+    expect(response.user.username).toBe('138****8000');
    expect(apiClientMocks.requestJson).toHaveBeenCalledWith(
      '/api/auth/phone/login',
      expect.objectContaining({
        body: JSON.stringify({
          phone: '13800138000',
          code: '123456',
+          inviteCode: 'SPRING2026',
        }),
      }),
      '登录失败',
--- a/src/services/authService.ts
+++ b/src/services/authService.ts
@@ -65,6 +65,13 @@ export function normalizePhoneInput(phoneInput: string) {
  return phoneInput.replace(/[^\d+]/gu, '').trim();
 }

+export function normalizeInviteCodeInput(inviteCode: string | undefined) {
+  return (inviteCode ?? '')
+    .trim()
+    .replace(/[^0-9a-z]/gi, '')
+    .toUpperCase();
+}
+
 export function getStoredLastLoginPhone() {
  if (typeof window === 'undefined') {
    return '';
@@ -145,7 +152,12 @@ export async function sendPhoneLoginCode(
  return response;
 }

-export async function loginWithPhoneCode(phone: string, code: string) {
+export async function loginWithPhoneCode(
+  phone: string,
+  code: string,
+  inviteCode?: string,
+) {
+  const normalizedInviteCode = normalizeInviteCodeInput(inviteCode);
  const response = await requestJson<AuthPhoneLoginResponse>(
    '/api/auth/phone/login',
    {
@@ -154,6 +166,7 @@ export async function loginWithPhoneCode(phone: string, code: string) {
      body: JSON.stringify({
        phone: normalizePhoneInput(phone),
        code: code.trim(),
+        ...(normalizedInviteCode ? { inviteCode: normalizedInviteCode } : {}),
      }),
    },
    '登录失败',
@@ -161,7 +174,7 @@ export async function loginWithPhoneCode(phone: string, code: string) {
  );

  setStoredAccessToken(response.token, { emit: false });
-  return response.user;
+  return response;
 }

 export async function bindWechatPhone(phone: string, code: string) {
Author	SHA1	Message	Date
kdletters	9d0235e529	Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative Some checks failed CI / verify (push) Has been cancelled Details	2026-05-01 01:14:18 +08:00
kdletters	e18f09069c	Merge remote-tracking branch 'origin/master' # Conflicts: # docs/technical/README.md # server-rs/crates/spacetime-client/src/module_bindings/mod.rs	2026-05-01 01:14:04 +08:00
kdletters	29cf68a31a	Merge branch 'codex/web-admin' # Conflicts: # server-rs/crates/api-server/src/admin.rs	2026-05-01 00:58:42 +08:00
kdletters	28b77a5ff5	Fix admin SQL count parsing for local SpacetimeDB	2026-05-01 00:36:42 +08:00
kdletters	42aab671ed	Implement registration invite code flow and admin invite codes	2026-04-30 20:49:38 +08:00