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

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());

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,
@@ -78,6 +75,13 @@ use crate::{
     login_options::auth_login_options,
     logout::logout,
     logout_all::logout_all,
+    match3d::{
+        click_match3d_item, create_match3d_agent_session, delete_match3d_work,
+        execute_match3d_agent_action, finish_match3d_time_up, get_match3d_agent_session,
+        get_match3d_run, get_match3d_work_detail, get_match3d_works, list_match3d_gallery,
+        publish_match3d_work, put_match3d_work, restart_match3d_run, start_match3d_run,
+        stop_match3d_run, stream_match3d_agent_message, submit_match3d_agent_message,
+    },
     password_entry::password_entry,
     password_management::{change_password, reset_password},
     phone_auth::{phone_login, send_phone_code},
@@ -105,10 +109,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,
@@ -135,7 +139,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",
@@ -172,6 +175,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 {
@@ -702,6 +712,116 @@ pub fn build_router(state: AppState) -> Router {
                 require_bearer_auth,
             )),
         )
+        .route(
+            "/api/creation/match3d/sessions",
+            post(create_match3d_agent_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/sessions/{session_id}",
+            get(get_match3d_agent_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/sessions/{session_id}/messages",
+            post(submit_match3d_agent_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/sessions/{session_id}/messages/stream",
+            post(stream_match3d_agent_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/sessions/{session_id}/actions",
+            post(execute_match3d_agent_action).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/sessions/{session_id}/compile",
+            post(execute_match3d_agent_action).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/works",
+            get(get_match3d_works).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/match3d/works/{profile_id}",
+            get(get_match3d_work_detail)
+                .patch(put_match3d_work)
+                .put(put_match3d_work)
+                .delete(delete_match3d_work)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/creation/match3d/works/{profile_id}/publish",
+            post(publish_match3d_work).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route("/api/runtime/match3d/gallery", get(list_match3d_gallery))
+        .route(
+            "/api/runtime/match3d/works/{profile_id}/runs",
+            post(start_match3d_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/match3d/runs/{run_id}",
+            get(get_match3d_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/match3d/runs/{run_id}/click",
+            post(click_match3d_item).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/match3d/runs/{run_id}/stop",
+            post(stop_match3d_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/match3d/runs/{run_id}/restart",
+            post(restart_match3d_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/match3d/runs/{run_id}/time-up",
+            post(finish_match3d_time_up).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/runtime/puzzle/agent/sessions",
             post(create_puzzle_agent_session)
@@ -1993,6 +2113,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]
@@ -2099,6 +2221,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]
@@ -3314,6 +3605,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();

server-rs/crates/api-server/src/main.rs

@@ -40,6 +40,7 @@ mod llm_model_routing;
 mod login_options;
 mod logout;
 mod logout_all;
+mod match3d;
 mod password_entry;
 mod password_management;
 mod phone_auth;

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),

server-rs/crates/api-server/src/runtime_profile.rs

@@ -5,18 +5,18 @@ 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,
@@ -24,13 +24,12 @@ use shared_contracts::runtime::{
     PROFILE_WALLET_LEDGER_SOURCE_TYPE_PUZZLE_AUTHOR_INCENTIVE_CLAIM,
     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;
@@ -217,27 +216,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("邀请码仅注册时填写"),
     ))
 }
 
@@ -334,6 +320,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>,
@@ -490,18 +507,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 {
@@ -519,6 +524,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),
@@ -528,6 +557,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 {
@@ -549,7 +592,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,
@@ -715,6 +758,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(