清掉 api-server 两条编译告警：未使用导入与测试态死代码

- server-rs/crates/api-server/src/tripo3d/routes.rs：删除未使用的 Model3dJobTarget 导入，同批使用的 Model3dJobKind 等保留
- server-rs/crates/api-server/src/state.rs：map_editor_generation_pricing_persistence_error 只被 cfg(not(test)) 分支调用，补 cfg_attr(test, allow(dead_code))，与同文件 seed_editor_generation_pricing_config 的既有写法一致
- 验证：cargo check --workspace --all-targets 零告警零错误

.dockerignore

@@ -30,8 +30,3 @@ server-rs/.data
 server-rs/.spacetimedb
 
 public/generated-*
-
-scripts/loadtest/data/*.local.json
-scripts/loadtest/data/k6-*.log
-scripts/loadtest/data/k6-*summary*.md
-scripts/loadtest/data/latest-*-prefix.txt

.env.example

@@ -237,6 +237,8 @@ GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 
 # 官网客户端下载检测渠道：dev、release 或自定义渠道；修改后重启 API 服务。
 # Windows/macOS 是系统维度，不填写 dev-win/dev-mac。
+# 客户端埋点也复用该渠道：dev 对应 https://dev.genarrative.world，release 对应 https://www.genarrative.world。
+# 埋点不接受其它渠道；本地 dev 且 GENARRATIVE_ENV 为 development（默认）/test/container 时允许 loopback 地址及可变端口。
 GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL="dev"
 
 # Optional: official VikingDB credentials for regenerating build-tag similarities

.eslintrc.cjs

@@ -365,7 +365,6 @@ module.exports = {
     'src/types.ts',
     'src/types/**',
     'src/uiAssets.ts',
-    'scripts/loadtest/**',
     'packages/shared/src/contracts/jumpHop.ts',
     'packages/shared/src/contracts/match3dAgent.ts',
     'packages/shared/src/contracts/match3dRuntime.ts',

.gitea/workflows/project-ci.yml

@@ -561,7 +561,9 @@ jobs:
         run: bash scripts/ci-npm-ci-with-retry.sh
 
       - name: Validate CI cache maintenance behavior
-        run: python3 -m unittest discover -s scripts -p 'test_gitea_cache_*.py'
+        run: |
+          python3 -m unittest discover -s scripts -p 'test_gitea_cache_*.py'
+          node --test scripts/export-ci-npm-download-cache.test.mjs
 
       - name: Run repository checks
         run: npm run check:repository-ci

.gitignore

@@ -89,10 +89,15 @@ spacetime.local.json
 deploy/container/api-server.env
 deploy/container/worker-smoke/
 
-# Local load-test data extracted from private migration files
+# 仓库根目录下手工下载的 3D 样例模型（Tripo 联调 / 查看器排查用），不入库；
-scripts/loadtest/data/*.local.json
+# glTF / FBX 多文件产物会带着 .bin 缓冲与贴图落在同一目录，一并忽略
-
+/*.[gG][lL][bB]
-# Local load-test run artifacts
+/*.[gG][lL][tT][fF]
-scripts/loadtest/data/k6-*.log
+/*.[fF][bB][xX]
-scripts/loadtest/data/k6-*summary*.md
+/*.[bB][iI][nN]
-scripts/loadtest/data/latest-*-prefix.txt
+/*.[pP][nN][gG]
+/*.[jJ][pP][gG]
+/*.[jJ][pP][eE][gG]
+/*.[wW][eE][bB][pP]
+/*.[kK][tT][xX]2
+/*.[tT][gG][aA]

CONTEXT.md

@@ -50,6 +50,86 @@ _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成
 
 ## Language
 
+### 3D Model Generation
+
+**3D 模型生成操作**:
+由文本提示或平台图片引用驱动、可异步查询并最终产生模型文件的 provider-neutral 操作；操作状态和产品资源结果分开建模。
+_Avoid_: 直接把第三方 provider task 当作产品资源、把模型 URL 当作永久资源地址
+
+**Provider task**:
+第三方 3D 生成平台返回的任务引用与任务快照，只存在于 provider adapter 的 Rust 边界内；它不是 Genarrative 的内部操作 ID。
+_Avoid_: 把 Tripo task ID 当作稳定产品 operationId、让 SDK 类型穿透 api-server
+
+**临时 provider URL**:
+第三方任务完成后返回的短时模型下载地址，必须通过显式下载流程转换为本地或持久化资源，不能直接当作长期资产地址。
+_Avoid_: 永久 OSS URL、资源 ID
+
+**模型 artifact**:
+由 text-to-model、image-to-model 或 multiview-to-model 任务产生、待应用层登记和持久化的模型文件结果；provider adapter 只提供可下载结果，不负责生成 resourceId 或 assetId。
+_Avoid_: 仅 UI 中展示的模型链接、没有来源任务的静态文件
+
+**Tripo API facade**:
+面向站内已认证调用方的全新 Tripo 3D 生成 API 上下文，负责把 API operation、用户归属、异步状态、产物持久化和正式资源引用连接起来；它独立于历史 Hyper3D adapter，不复用其路由、契约或实现。
+_Avoid_: 把 Tripo API 当成 Hyper3D 的 provider 替换、让 Hyper3D 路由悄悄切换到 Tripo
+
+**Tripo operation**:
+Genarrative 为一次 Tripo 生成请求分配的内部异步操作标识；客户端只看到 operationId，Tripo provider task 只作为服务端 checkpoint 保存，二者不是同一个 ID。
+_Avoid_: 将 Tripo taskId 直接当公开 operationId、把 SDK task 状态模型穿透到 API
+
+**模型产物持久化**:
+Tripo 任务完成后，服务端下载模型与预览、写入受控对象存储并登记资源元数据，成功后才把 Tripo operation 置为 completed；本期按完整字节写入，流式上传是后续目标。
+_Avoid_: 返回临时签名 URL作为永久资源、在 API handler 中把完整模型读成 Vec<u8>
+
+**3D 生成底价**:
+一次 3D 生成在指定端点和模型版本下、按是否带贴图区分的基准泥点价，不包含任何叠加项，也不随请求的其它参数变化。
+_Avoid_: 把底价与加价项合并成一个档位价、把 provider 的 credit 数值当底价
+
+**3D 生成加价项**:
+叠加在底价之上、由请求参数判定的可选泥点加价；每个端点各自持有一份加价项价目，同一加价项在不同端点可以是不同价。
+_Avoid_: 全局唯一一份加价项价目、按用途而不是按请求参数判定加价
+
+**定价配置归一化**:
+读取持久化定价时把它与当前契约对齐的过程：缺的键用受控默认值补齐，契约之外的遗留键剔除并告警；它只发生在读取方向，写入方向仍要求完整合法。
+_Avoid_: 把「省略即沿用」当作保存语义、把归一化当成静默改价
+
+**模型生成落点**:
+3D 生成结果要进入的平台容器，调用方必须在工程资源与素材库资产之间显式二选一；工程分支可附带画布占位框回填，素材库分支必须给出目录与标签。
+_Avoid_: 两个都不给就默认落素材库、把落点混进 provider 请求参数
+
+**模型输入资源引用**:
+image-to-model 请求对平台已有图片的明确 tagged 引用，可指向项目资源或素材库资产；服务端负责 owner 校验和 OSS 对象解析，不接受把多种来源塞进裸 `input` 字符串。
+_Avoid_: 任意远程 URL、data URL、未区分语义的 resourceId/assetId 字符串
+
+**3D 模型生成工具**:
+图片画布工程里从底部工具栏打开、给出「文生 3D 模型」与「图生 3D 模型」两个子项的画布生成工具；提交后按画布既有生成链路的占位框、任务侧栏与失败退款口径推进，产物落成 **3D 模型资源**。
+_Avoid_: 独立 3D 生成页、把 3D 生成做成玩法类型或作品、把 3D 生成接进画布 Agent 对话
+
+**3D 生成定价**:
+3D 模型生成工具在提交前展示的泥点价格，来自编辑器生成定价查询的 `model3d` 段；该段缺失即入口不可提交，前端不内置兜底数值。该段的权威事实源是 SpacetimeDB 定价表里的两段强类型列，公开读取时投影回迁移前的旧形状。
+_Avoid_: 前端写死 3D 价格、借用图片模型的兜底定价配置、按 0 元放行、把内部两段结构直接暴露给画布
+
+**定价版本（乐观锁）**:
+后台读取完整模型定价时一并拿到的版本号（SpacetimeDB 行的更新时间微秒值），保存时必须原样回传；与服务端当前版本不一致即整笔拒绝并返回 409，提示重新读取，避免静默覆盖他人的改价。
+_Avoid_: 在前端自造或缓存该版本、把版本不匹配当成可重试的普通失败、把「省略字段」当成「沿用当前值」
+
+### 3D 模型资源预览
+
+**3D 模型资源**:
+类别为 `model3d` 的平台资源 / 素材，一个资源同时持有模型本体与模型预览图两个对象；客户端默认消费预览图，模型本体只在 3D 查看器里加载。
+_Avoid_: 只有模型文件的资源、把模型本体当图片素材、为模型新增并列媒体类型
+
+**模型预览图**:
+3D 模型资源的静态代表图，落在资源投影的 `imageSrc` 与 `thumbnailSrc` 上，供画布卡片、素材缩略图、后台列表和精选卡片使用。
+_Avoid_: 用模型本体充当预览、按需实时渲染缩略图、把预览图当模型真相
+
+**模型本体**:
+3D 模型资源里的可下载模型文件，只由资源的 `objectKey` 指向，格式以对象内容类型为准。
+_Avoid_: 把模型本体当图片地址、用预览图字段承载模型文件、按文件扩展名推断格式
+
+**3D 查看器预览**:
+在资源上打开模态把模型本体交给 3D 查看器渲染的只读能力，不修改资源、不产出新资源，也不是画布图层本身的编辑操作。
+_Avoid_: 在画布里内联渲染模型、把预览当编辑、为预览产出新资源
+
 ### Puzzle Clear
 
 **拼消消**:
@@ -194,6 +274,14 @@ _Avoid_: 进度通知、快照轮询、第二套历史
 把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
 _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 
+**项目对话输入**:
+AGC 项目对话的输入只有自然语言回合（含 `@` 素材引用与附件）；需要动作时由 Runtime 工具与确认卡承接，不从输入文本解析控制词。
+_Avoid_: 斜杠命令、聊天命令草稿、命令发现列表
+
+**项目命令 id**:
+AGC 运行期工具与项目权限策略使用的稳定标识（`GAME_CREATION_APP_COMMANDS` 与 `GameCreationAppPermission`），由 Rust 运行期策略校验与 App 权限审计 / 项目前置条件判定消费，不是用户输入语法。
+_Avoid_: 把命令 id 当作可输入的聊天命令、为权限位补聊天入口
+
 **引用候选**:
 输入区可以命中的对象集合（`@` 素材、`$` Skill），由宿主按种类注入；输入区不判断候选属于哪一类。
 _Avoid_: 输入区自己读项目清单或应用目录、把候选取值写死在组件里
@@ -210,6 +298,18 @@ _Avoid_: 给附件或运行画面区域造候选、为它们保留输入区内
 引用在正文文本里的形态（`@显示名` / `$名称` / `@附件名`）及其反解析；出站与解析必须同一口径，token 前后各留一个空白。
 _Avoid_: 出站与解析各写一套、在空白边界之外再补兼容别名、让解析依赖具体种类的字段
 
+**引用名**:
+引用自己的名字，同时就是它在正文里的 token（资源显示名、Skill 名、附件名）；内部不允许出现空白，空白统一经 `normalizeMentionName` 折成 `-`。
+_Avoid_: 名字与 token 各存一份、靠补兼容别名或 `resourceId` 兜底来消化空白
+
+**引用候选枚举**:
+一种引用种类当前就绪的全部可引用对象，与候选菜单共用同一份集合；区别只在没有查询过滤和条数上限。
+_Avoid_: 拿菜单查询当枚举、为粘贴另建一份候选清单
+
+**引用粘贴解析**:
+把粘贴进来的纯文本按引用文本语法反解析回正文引用；只有身份唯一且逐字确认的 token 才成为引用，其余按原文保留。
+_Avoid_: 猜文件名或路径、为不确定的 token 挑一个候选、改写用户粘贴的其余文字
+
 **引用输入区**:
 只负责编辑与渲染引用的共享输入组件；候选、身份解析与文本语法都来自注入的 provider，它不持有项目清单、不访问后端。
 _Avoid_: 输入区自己拉 Skill 目录、把选择器面板塞在输入区内部
@@ -240,6 +340,7 @@ _Avoid_: 待发送附件列表与正文芯片并存、提交时再拼一遍附
 - **引用输入区** 由宿主注入的若干 **引用 provider** 组成；**引用候选** 与 **引用文本语法** 都来自 provider，输入区不判断引用种类。
 - **引用选择器** 不属于 **引用输入区**：它自己拿数据，确认后只通过输入区的插入缝交付引用。
 - 只有带触发符的 **引用 provider** 会产生候选；**静默 provider** 没有触发符，只能由外部插入或草稿回填进入正文。
+- **引用粘贴解析** 与出站显示是同一条 **引用文本语法** 的两端；**静默 provider** 的 token（`@附件名` / `@区域标签`）没有候选，因此粘贴时不重建。
 - **附件芯片** 是本轮附件的唯一事实源；附件导入失败时不产生芯片。
 
 ## Example dialogue

apps/admin-web/src/api/adminApiClient.test.ts

@@ -7,6 +7,7 @@ import {
   getAdminFeatureGateConfig,
   getAdminUserDetail,
   importAdminAgcTemplates,
+  listAdminAgcTrackingEvents,
   listAdminGameDistributionReviews,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
@@ -24,6 +25,30 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
+test('客户端埋点查询传递筛选和游标并复用后台认证', async () => {
+  const payload = { entries: [], nextCursor: null };
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ ok: true, data: payload }), {
+      status: 200,
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  expect(
+    await listAdminAgcTrackingEvents('token', {
+      userId: 'user+1',
+      projectId: 'project-1',
+      cursor: 'page/2',
+      limit: 50,
+    }),
+  ).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/agc/tracking-events?userId=user%2B1&projectId=project-1&cursor=page%2F2&limit=50',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer token' }),
+    }),
+  );
+});
+
 test('模板管理读取和更新复用认证封装，提交 revision 和封面但不提交 ZIP 或版本', async () => {
   const library = { revision: 'revision-new', writable: true, templates: [] };
   const fetchMock = vi.fn().mockImplementation(

apps/admin-web/src/api/adminApiClient.ts

@@ -1,6 +1,8 @@
 import type {
   AdminAccountListResponse,
   AdminAgcTemplateLibraryResponse,
+  AdminAgcTrackingEventListResponse,
+  AdminAgcTrackingEventQuery,
   AdminConfirmEditorShowcaseCampaignImageUploadRequest,
   AdminCreateAccountRequest,
   AdminCreateAccountResponse,
@@ -55,6 +57,7 @@ import type {
   AdminUpdateAccountResponse,
   AdminUpdateAgcTemplateRequest,
   AdminUploadedEditorShowcaseCampaignImage,
+  AdminUpsertEditorGenerationPricingRequest,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertFeatureGateConfigRequest,
   AdminUpsertProfileInviteCodeRequest,
@@ -409,6 +412,31 @@ export function listAdminTrackingEventKeys(token: string) {
   );
 }
 
+export function listAdminAgcTrackingEvents(
+  token: string,
+  query: AdminAgcTrackingEventQuery = {},
+) {
+  return request<AdminAgcTrackingEventListResponse>(
+    `/admin/api/agc/tracking-events${buildQueryString((params) => {
+      for (const key of [
+        'userId',
+        'projectId',
+        'creativeTaskId',
+        'agentRunId',
+        'eventName',
+        'clientVersion',
+        'startTime',
+        'endTime',
+        'cursor',
+      ] as const) {
+        appendQueryParam(params, key, query[key]);
+      }
+      appendNumericQueryParam(params, 'limit', query.limit);
+    })}`,
+    { token },
+  );
+}
+
 export function listAdminErrorReports(
   token: string,
   query: {
@@ -489,7 +517,7 @@ export function getAdminEditorGenerationPricing(token: string) {
 
 export function upsertAdminEditorGenerationPricing(
   token: string,
-  payload: EditorGenerationPricingConfigPayload,
+  payload: AdminUpsertEditorGenerationPricingRequest,
 ) {
   return request<EditorGenerationPricingConfigPayload>(
     '/admin/api/editor-generation-pricing',

apps/admin-web/src/api/adminApiTypes.ts

@@ -428,8 +428,42 @@ export interface EditorGenerationModelPricingPayload {
   prices?: Record<string, number>;
 }
 
+/** 某个 3D 模型版本在「无贴图 / 带贴图」两种形态下的泥点底价。 */
+export interface EditorGenerationModel3dVersionPricePayload {
+  noTexture: number;
+  texture: number;
+}
+
+/**
+ * 单个 3D 生成端点的整套定价：模型版本底价 + 该端点自己的加价项价目。
+ *
+ * 键集合由后端契约决定，后台只改数值：模型版本键与加价项键都直接来自接口返回，
+ * 不在前端硬编码清单，也不能新增、删除或停用。
+ */
+export interface EditorGenerationModel3dEndpointPricingPayload {
+  versionPrices: Record<string, EditorGenerationModel3dVersionPricePayload>;
+  addOnPrices: Record<string, number>;
+}
+
+/** 3D 生成定价段：两个端点并列，各持自己的设置。 */
+export interface EditorGenerationModel3dPricingPayload {
+  textToModelPricing: EditorGenerationModel3dEndpointPricingPayload;
+  imageToModelPricing: EditorGenerationModel3dEndpointPricingPayload;
+}
+
 export interface EditorGenerationPricingConfigPayload {
   models: Record<string, EditorGenerationModelPricingPayload>;
+  /** 后端尚未配置 3D 段时缺省；缺失即 3D 生成不可提交，后台也不能新建整段。 */
+  model3d?: EditorGenerationModel3dPricingPayload | null;
+  /** 当前定价版本：保存时原样回传做乐观锁，冲突时后端返回 409。 */
+  updatedAtMicros: number;
+}
+
+/** 后台保存定价的请求体：`models` 与 3D 两段都必须显式给出，外加读取到的定价版本。 */
+export interface AdminUpsertEditorGenerationPricingRequest {
+  models: Record<string, EditorGenerationModelPricingPayload>;
+  model3d: EditorGenerationModel3dPricingPayload | null;
+  expectedUpdatedAtMicros: number;
 }
 
 export interface AdminEditorAssetListQuery {
@@ -820,6 +854,44 @@ export interface AdminTrackingEventListResponse {
   entries: AdminTrackingEventEntryPayload[];
 }
 
+export interface AdminAgcTrackingEventQuery {
+  userId?: string;
+  projectId?: string;
+  creativeTaskId?: string;
+  agentRunId?: string;
+  eventName?: string;
+  clientVersion?: string;
+  startTime?: string;
+  endTime?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface AdminAgcTrackingEventEntry {
+  eventId: string;
+  schemaVersion: number;
+  eventName: string;
+  eventTime: string;
+  userId: string;
+  editorSessionId: string;
+  projectId: string | null;
+  creativeTaskId: string | null;
+  agentRunId: string | null;
+  agentTurnId: string | null;
+  status: string | null;
+  errorCode: string | null;
+  source: string;
+  clientVersion: string;
+  properties: Record<string, unknown>;
+  batchId: string;
+  receivedAt: string;
+}
+
+export interface AdminAgcTrackingEventListResponse {
+  entries: AdminAgcTrackingEventEntry[];
+  nextCursor: string | null;
+}
+
 export interface AdminTrackingEventKeyPayload {
   eventKey: string;
   eventTitle: string;

apps/admin-web/src/app/AdminApp.tsx

@@ -20,6 +20,7 @@ import {
 import { AdminAccountsPage } from '../pages/AdminAccountsPage';
 import { AdminAgcModelsPage } from '../pages/AdminAgcModelsPage';
 import { AdminAgcTemplatesPage } from '../pages/AdminAgcTemplatesPage';
+import { AdminAgcTrackingPage } from '../pages/AdminAgcTrackingPage';
 import { AdminDashboardPage } from '../pages/AdminDashboardPage';
 import { AdminDatabaseTablesPage } from '../pages/AdminDatabaseTablesPage';
 import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
@@ -233,6 +234,12 @@ export function AdminApp() {
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {activeRouteId === 'agc-tracking' ? (
+        <AdminAgcTrackingPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'error-reports' ? (
         <AdminErrorReportsPage
           token={token}

apps/admin-web/src/app/AdminShell.tsx

@@ -40,6 +40,7 @@ const routeIcons = {
   tables: Database,
   debug: Bug,
   tracking: Table2,
+  'agc-tracking': Table2,
   'error-reports': Bug,
   'gray-release': GitBranch,
   redeem: TicketPercent,

apps/admin-web/src/app/adminRoutes.test.ts

@@ -8,6 +8,22 @@ import {
   routeHash,
 } from './adminRoutes';
 
+test('客户端埋点路由遵守成员页签权限', () => {
+  expect(resolveAdminRoute('#agc-tracking')).toBe('agc-tracking');
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['agc-tracking'],
+    }).map((route) => route.id),
+  ).toEqual(['agc-tracking']);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['tracking'],
+    }).some((route) => route.id === 'agc-tracking'),
+  ).toBe(false);
+});
+
 test('后台默认进入 Dashboard', () => {
   expect(adminRoutes[0]).toEqual({
     id: 'dashboard',
@@ -43,12 +59,6 @@ test('后台灰度发布路由可通过导航和 hash 访问', () => {
   expect(routeHash('gray-release')).toBe('#gray-release');
 });
 
-test('后台不再暴露旧创作模板管理路由', () => {
-  expect(resolveAdminRoute('#creation-entry')).toBe('dashboard');
-  expect(resolveAdminRoute('#creation-announcement')).toBe('dashboard');
-  expect(resolveAdminRoute('#work-visibility')).toBe('dashboard');
-});
-
 test('后台素材查询路由可通过导航和 hash 访问', () => {
   expect(adminRoutes).toContainEqual({
     id: 'editor-assets',

apps/admin-web/src/app/adminRoutes.ts

@@ -5,6 +5,7 @@ export type AdminRouteId =
   | 'tables'
   | 'debug'
   | 'tracking'
+  | 'agc-tracking'
   | 'error-reports'
   | 'gray-release'
   | 'redeem'
@@ -41,6 +42,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
   { id: 'tables', label: '表查询', hash: '#tables' },
   { id: 'debug', label: 'API 调试', hash: '#debug' },
   { id: 'tracking', label: '埋点数据', hash: '#tracking' },
+  { id: 'agc-tracking', label: '客户端埋点', hash: '#agc-tracking' },
   { id: 'error-reports', label: '错误报告', hash: '#error-reports' },
   { id: 'gray-release', label: '灰度发布', hash: '#gray-release' },
   { id: 'redeem', label: '兑换码', hash: '#redeem' },

apps/admin-web/src/pages/AdminAgcTemplatesPage.test.tsx

@@ -339,7 +339,10 @@ test.each([409, 503])(
     await confirmWrite();
     const message = await screen.findByRole('alert');
     const feedback = message.parentElement!;
-    expect(document.activeElement).toBe(feedback);
+    // 聚焦发生在 React passive effect 里（AdminAgcTemplatesPage 的 feedback 聚焦 useEffect），
+    // 而 findByRole 在 alert 节点一挂上就返回，可能早于该 effect 执行；这里等聚焦落地，
+    // 避免在 CI 负载下抢跑。断言口径不变：焦点最终必须落在提示区而不是弹窗面板。
+    await waitFor(() => expect(document.activeElement).toBe(feedback));
     expect(feedback.tabIndex).toBe(-1);
     expect(focus).toHaveBeenCalledWith({ preventScroll: true });
     expect(viewport.scrollTop).toBe(20);

apps/admin-web/src/pages/AdminAgcTrackingPage.test.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  AdminApiError,
+  listAdminAgcTrackingEvents,
+} from '../api/adminApiClient';
+import type { AdminAgcTrackingEventEntry } from '../api/adminApiTypes';
+import { AdminAgcTrackingPage } from './AdminAgcTrackingPage';
+
+vi.mock('../api/adminApiClient', async (original) => ({
+  ...(await original<typeof import('../api/adminApiClient')>()),
+  listAdminAgcTrackingEvents: vi.fn(),
+}));
+vi.mock('../components/AdminUserReferenceButton', () => ({
+  AdminUserReferenceButton: () => null,
+}));
+
+const entry: AdminAgcTrackingEventEntry = {
+  eventId: 'event-1',
+  schemaVersion: 1,
+  eventName: 'project_save',
+  eventTime: '2026-09-21T12:00:00.123Z',
+  userId: 'user-1',
+  editorSessionId: 'session-1',
+  projectId: 'project-1',
+  creativeTaskId: 'project-1',
+  agentRunId: null,
+  agentTurnId: null,
+  status: 'success',
+  errorCode: null,
+  source: 'gui',
+  clientVersion: '1.0',
+  properties: { reason: 'manual' },
+  batchId: 'batch-1',
+  receivedAt: '2026-09-21T12:15:00.000Z',
+};
+
+beforeEach(() => {
+  vi.mocked(listAdminAgcTrackingEvents).mockReset();
+});
+afterEach(cleanup);
+
+test('翻页沿用游标，筛选和刷新从第一页重新查询，详情保留 null 和事件属性', async () => {
+  vi.mocked(listAdminAgcTrackingEvents)
+    .mockResolvedValueOnce({ entries: [entry], nextCursor: 'cursor-page-2' })
+    .mockResolvedValueOnce({
+      entries: [{ ...entry, eventId: 'event-2' }],
+      nextCursor: null,
+    })
+    .mockResolvedValue({ entries: [entry], nextCursor: 'cursor-new' });
+  render(<AdminAgcTrackingPage token="admin-token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('保存项目', { selector: 'td' });
+  expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith('admin-token', {
+    cursor: undefined,
+    limit: 50,
+  });
+  fireEvent.click(screen.getByText('查看详情'));
+  const dialog = screen.getByRole('dialog');
+  expect(within(dialog).getAllByText('—').length).toBe(3);
+  expect(within(dialog).getByText(/"reason": "manual"/)).toBeTruthy();
+  expect(within(dialog).getByText(entry.eventTime)).toBeTruthy();
+  fireEvent.click(within(dialog).getByLabelText('关闭详情'));
+  fireEvent.click(screen.getByText('下一页'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith('admin-token', {
+      cursor: 'cursor-page-2',
+      limit: 50,
+    }),
+  );
+  await waitFor(() =>
+    expect(screen.getByText('查询').closest('button')?.disabled).toBe(false),
+  );
+  fireEvent.click(screen.getByText('上一页'));
+  await screen.findByText('第 1 页');
+  expect(listAdminAgcTrackingEvents).toHaveBeenCalledTimes(2);
+  fireEvent.change(screen.getByLabelText('项目 ID'), {
+    target: { value: 'project-2' },
+  });
+  fireEvent.click(screen.getByText('查询'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith(
+      'admin-token',
+      expect.objectContaining({
+        projectId: 'project-2',
+        cursor: undefined,
+        limit: 50,
+      }),
+    ),
+  );
+  expect(screen.getByText('第 1 页')).toBeTruthy();
+  await waitFor(() =>
+    expect(screen.getByText('刷新').closest('button')?.disabled).toBe(false),
+  );
+  fireEvent.click(screen.getByText('刷新'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenCalledTimes(4),
+  );
+});
+
+test('空结果、权限失败与登录失效沿用后台反馈', async () => {
+  const unauthorized = vi.fn();
+  vi.mocked(listAdminAgcTrackingEvents)
+    .mockResolvedValueOnce({ entries: [], nextCursor: null })
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 403, message: '无权访问客户端埋点' }),
+    )
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 401, message: '登录失效' }),
+    );
+  render(<AdminAgcTrackingPage token="token" onUnauthorized={unauthorized} />);
+  await screen.findByText('暂无客户端埋点数据');
+  fireEvent.click(screen.getByText('刷新'));
+  expect((await screen.findByRole('alert')).textContent).toContain(
+    '无权访问客户端埋点',
+  );
+  fireEvent.click(screen.getByText('刷新'));
+  await waitFor(() =>
+    expect(unauthorized).toHaveBeenCalledWith('登录状态已失效'),
+  );
+});

apps/admin-web/src/pages/AdminAgcTrackingPage.tsx

@@ -0,0 +1,379 @@
+import { Modal } from '@genarrative/shared/components';
+import { FormEvent, useEffect, useRef, useState } from 'react';
+
+import { listAdminAgcTrackingEvents } from '../api/adminApiClient';
+import type {
+  AdminAgcTrackingEventEntry,
+  AdminAgcTrackingEventListResponse,
+  AdminAgcTrackingEventQuery,
+} from '../api/adminApiTypes';
+import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
+import { handlePageError } from './pageUtils';
+
+const eventLabels: Record<string, string> = {
+  editor_session_start: '编辑器会话开始',
+  editor_session_end: '编辑器会话结束',
+  editor_focus_start: '编辑器获得焦点',
+  editor_focus_end: '编辑器失去焦点',
+  project_create_success: '项目创建成功',
+  project_open: '打开项目',
+  creative_task_submit: '首次提交创作目标',
+  agent_run_completed: 'Agent 运行完成',
+  agent_run_failed: 'Agent 运行失败',
+  project_revision_created: '项目产生修改',
+  preview_ready: '预览就绪',
+  project_save: '保存项目',
+};
+
+const fieldLabels: Record<keyof AdminAgcTrackingEventEntry, string> = {
+  eventId: '事件 ID',
+  schemaVersion: '事件版本',
+  eventName: '事件类型',
+  eventTime: '发生时间',
+  userId: '用户 ID',
+  editorSessionId: '编辑器会话 ID',
+  projectId: '项目 ID',
+  creativeTaskId: '创作目标 ID',
+  agentRunId: 'Agent run ID',
+  agentTurnId: 'Agent turn ID',
+  status: '结果',
+  errorCode: '错误码',
+  source: '来源',
+  clientVersion: '客户端版本',
+  properties: '事件属性',
+  batchId: '批次 ID',
+  receivedAt: '入库时间',
+};
+
+function formatTime(value: string) {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN');
+}
+
+export function AdminAgcTrackingPage({
+  token,
+  onUnauthorized,
+}: {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}) {
+  const [filters, setFilters] = useState({
+    userId: '',
+    projectId: '',
+    eventName: '',
+    startTime: '',
+    endTime: '',
+  });
+  const [query, setQuery] = useState<AdminAgcTrackingEventQuery>({});
+  const [cursors, setCursors] = useState<Array<string | undefined>>([
+    undefined,
+  ]);
+  const [page, setPage] = useState(0);
+  const [refresh, setRefresh] = useState(0);
+  const [entries, setEntries] = useState<AdminAgcTrackingEventEntry[]>([]);
+  const [nextCursor, setNextCursor] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  const [detail, setDetail] = useState<AdminAgcTrackingEventEntry | null>(null);
+  const cursor = cursors[page];
+  // 首页没有入站游标，返回首页时保留原快照，刷新才获取新数据。
+  const firstPage = useRef<{
+    token: string;
+    query: AdminAgcTrackingEventQuery;
+    response: AdminAgcTrackingEventListResponse;
+  } | null>(null);
+
+  useEffect(() => {
+    const saved = firstPage.current;
+    if (!cursor && saved?.token === token && saved.query === query) {
+      setEntries(saved.response.entries);
+      setNextCursor(saved.response.nextCursor);
+      setError('');
+      setLoading(false);
+      return;
+    }
+    let active = true;
+    setLoading(true);
+    setError('');
+    setEntries([]);
+    setNextCursor(null);
+    void listAdminAgcTrackingEvents(token, { ...query, cursor, limit: 50 })
+      .then((response) => {
+        if (!active) return;
+        if (!cursor) firstPage.current = { token, query, response };
+        setEntries(response.entries);
+        setNextCursor(response.nextCursor);
+      })
+      .catch((failure: unknown) => {
+        if (active) handlePageError(failure, onUnauthorized, setError);
+      })
+      .finally(() => {
+        if (active) setLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [token, query, cursor, refresh, onUnauthorized]);
+
+  function resetPages() {
+    firstPage.current = null;
+    setCursors([undefined]);
+    setPage(0);
+    setDetail(null);
+  }
+
+  function search(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (
+      filters.startTime &&
+      filters.endTime &&
+      new Date(filters.startTime) >= new Date(filters.endTime)
+    ) {
+      setError('结束时间必须晚于开始时间');
+      return;
+    }
+    resetPages();
+    setQuery({
+      userId: filters.userId.trim(),
+      projectId: filters.projectId.trim(),
+      eventName: filters.eventName,
+      startTime: filters.startTime
+        ? new Date(filters.startTime).toISOString()
+        : undefined,
+      endTime: filters.endTime
+        ? new Date(filters.endTime).toISOString()
+        : undefined,
+    });
+  }
+
+  function related(
+    key: 'creativeTaskId' | 'agentRunId' | 'clientVersion',
+    value: string,
+  ) {
+    resetPages();
+    setFilters({
+      userId: '',
+      projectId: '',
+      eventName: '',
+      startTime: '',
+      endTime: '',
+    });
+    setQuery({ [key]: value });
+  }
+
+  return (
+    <section className="admin-page admin-page-wide">
+      <div className="admin-page-heading">
+        <div>
+          <h2>客户端埋点</h2>
+          <p>按发生时间倒序展示</p>
+        </div>
+        <button
+          type="button"
+          className="admin-secondary-button"
+          disabled={loading}
+          onClick={() => {
+            resetPages();
+            setRefresh((value) => value + 1);
+          }}
+        >
+          刷新
+        </button>
+      </div>
+      <form className="admin-panel admin-form" onSubmit={search}>
+        <div className="admin-filter-grid">
+          {(['userId', 'projectId'] as const).map((key) => (
+            <label key={key} className="admin-field">
+              <span>{fieldLabels[key]}</span>
+              <input
+                value={filters[key]}
+                onChange={(event) =>
+                  setFilters({ ...filters, [key]: event.target.value })
+                }
+              />
+            </label>
+          ))}
+          <label className="admin-field">
+            <span>事件类型</span>
+            <select
+              value={filters.eventName}
+              onChange={(event) =>
+                setFilters({ ...filters, eventName: event.target.value })
+              }
+            >
+              <option value="">全部</option>
+              {Object.entries(eventLabels).map(([value, label]) => (
+                <option key={value} value={value}>
+                  {label}
+                </option>
+              ))}
+            </select>
+          </label>
+          {(['startTime', 'endTime'] as const).map((key) => (
+            <label key={key} className="admin-field">
+              <span>
+                {key === 'startTime'
+                  ? '发生时间起点（含）'
+                  : '发生时间终点（不含）'}
+              </span>
+              <input
+                type="datetime-local"
+                value={filters[key]}
+                onChange={(event) =>
+                  setFilters({ ...filters, [key]: event.target.value })
+                }
+              />
+            </label>
+          ))}
+        </div>
+        <div className="admin-action-row">
+          <button
+            type="submit"
+            className="admin-primary-button"
+            disabled={loading}
+          >
+            查询
+          </button>
+        </div>
+        {(['creativeTaskId', 'agentRunId', 'clientVersion'] as const)
+          .filter((key) => query[key])
+          .map((key) => (
+            <p key={key}>
+              {fieldLabels[key]}：{query[key]}（重新查询可清除）
+            </p>
+          ))}
+      </form>
+      {error ? (
+        <p role="alert" className="admin-error-message">
+          {error}
+        </p>
+      ) : null}
+      <div className="admin-panel">
+        <div className="admin-table-wrap">
+          <table className="admin-table">
+            <thead>
+              <tr>
+                {[
+                  '入库时间',
+                  '发生时间',
+                  '用户',
+                  '事件名称',
+                  '项目',
+                  '来源',
+                  '结果',
+                  '客户端版本',
+                  '详情',
+                ].map((label) => (
+                  <th key={label}>{label}</th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {entries.map((entry) => (
+                <tr key={entry.eventId}>
+                  <td>{formatTime(entry.receivedAt)}</td>
+                  <td>{formatTime(entry.eventTime)}</td>
+                  <td>
+                    {entry.userId}
+                    <AdminUserReferenceButton
+                      token={token}
+                      userId={entry.userId}
+                      onUnauthorized={onUnauthorized}
+                    />
+                  </td>
+                  <td>{eventLabels[entry.eventName] ?? entry.eventName}</td>
+                  <td>{entry.projectId ?? '—'}</td>
+                  <td>{entry.source}</td>
+                  <td>{entry.status ?? '—'}</td>
+                  <td>{entry.clientVersion}</td>
+                  <td>
+                    <button
+                      type="button"
+                      className="admin-ghost-button"
+                      onClick={() => setDetail(entry)}
+                    >
+                      查看详情
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        {loading ? (
+          <p role="status">加载中…</p>
+        ) : !error && entries.length === 0 ? (
+          <p>暂无客户端埋点数据</p>
+        ) : null}
+        <div className="admin-action-row">
+          <button
+            type="button"
+            className="admin-secondary-button"
+            disabled={loading || page === 0}
+            onClick={() => setPage((value) => value - 1)}
+          >
+            上一页
+          </button>
+          <span>第 {page + 1} 页</span>
+          <button
+            type="button"
+            className="admin-secondary-button"
+            disabled={loading || !nextCursor}
+            onClick={() => {
+              if (!nextCursor) return;
+              setCursors([...cursors.slice(0, page + 1), nextCursor]);
+              setPage(page + 1);
+            }}
+          >
+            下一页
+          </button>
+        </div>
+      </div>
+      {detail ? (
+        <Modal
+          open
+          title="客户端埋点详情"
+          closeLabel="关闭详情"
+          onClose={() => setDetail(null)}
+          className="genarrative-ui"
+        >
+          <dl>
+            {(
+              Object.keys(fieldLabels) as Array<
+                keyof AdminAgcTrackingEventEntry
+              >
+            )
+              .filter((key) => key !== 'properties')
+              .map((key) => (
+                <div key={key}>
+                  <dt>{fieldLabels[key]}</dt>
+                  <dd style={{ overflowWrap: 'anywhere' }}>
+                    {detail[key] == null ? '—' : String(detail[key])}
+                  </dd>
+                </div>
+              ))}
+          </dl>
+          <div className="admin-action-row">
+            {(['creativeTaskId', 'agentRunId', 'clientVersion'] as const).map(
+              (key) =>
+                detail[key] ? (
+                  <button
+                    type="button"
+                    key={key}
+                    className="admin-secondary-button"
+                    onClick={() => related(key, detail[key]!)}
+                  >
+                    查询同一{fieldLabels[key]}
+                  </button>
+                ) : null,
+            )}
+          </div>
+          <h3>事件属性</h3>
+          <pre style={{ whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }}>
+            {JSON.stringify(detail.properties, null, 2)}
+          </pre>
+        </Modal>
+      ) : null}
+    </section>
+  );
+}

apps/admin-web/src/pages/AdminDatabaseTablesPage.tsx

@@ -2641,48 +2641,6 @@ const databaseTableLabelMap: Record<string, string> = {
   profile_recharge_order: '充值订单',
   profile_feedback_submission: '反馈提交',
   profile_save_archive: '存档记录',
-  story_session: '剧情会话',
-  story_event: '剧情事件',
-  npc_state: 'NPC 状态',
-  inventory_slot: '背包槽位',
-  battle_state: '战斗状态',
-  treasure_record: '宝藏记录',
-  quest_record: '任务记录',
-  quest_log: '任务日志',
-  player_progression: '玩家进度',
-  chapter_progression: '章节进度',
-  custom_world_profile: '自定义世界档案',
-  custom_world_session: '自定义世界会话',
-  custom_world_agent_session: '自定义世界 Agent 会话',
-  custom_world_agent_message: '自定义世界 Agent 消息',
-  custom_world_agent_operation: '自定义世界 Agent 操作',
-  custom_world_draft_card: '自定义世界草稿卡片',
-  custom_world_gallery_entry: '自定义世界画廊条目',
-  puzzle_agent_session: '拼图 Agent 会话',
-  puzzle_agent_message: '拼图 Agent 消息',
-  puzzle_work_profile: '拼图作品档案',
-  puzzle_event: '拼图事件',
-  puzzle_runtime_run: '拼图运行记录',
-  puzzle_leaderboard_entry: '拼图排行榜条目',
-  match3d_agent_session: '抓大鹅 Agent 会话',
-  match3d_agent_message: '抓大鹅 Agent 消息',
-  match3d_work_profile: '抓大鹅作品档案',
-  match3d_runtime_run: '抓大鹅运行记录',
-  square_hole_agent_session: '方洞挑战 Agent 会话',
-  square_hole_agent_message: '方洞挑战 Agent 消息',
-  square_hole_work_profile: '方洞挑战作品档案',
-  square_hole_runtime_run: '方洞挑战运行记录',
-  visual_novel_agent_session: '视觉小说 Agent 会话',
-  visual_novel_agent_message: '视觉小说 Agent 消息',
-  visual_novel_work_profile: '视觉小说作品档案',
-  visual_novel_runtime_run: '视觉小说运行记录',
-  visual_novel_runtime_history_entry: '视觉小说历史条目',
-  visual_novel_runtime_event: '视觉小说运行事件',
-  big_fish_creation_session: '大鱼吃小鱼创建会话',
-  big_fish_agent_message: '大鱼吃小鱼 Agent 消息',
-  big_fish_asset_slot: '大鱼吃小鱼资产槽位',
-  big_fish_event: '大鱼吃小鱼事件',
-  big_fish_runtime_run: '大鱼吃小鱼运行记录',
   asset_object: '资产对象',
   asset_entity_binding: '资产实体绑定',
   asset_event: '资产事件',
@@ -2724,48 +2682,6 @@ const databaseTableDescriptionMap: Record<string, string> = {
   profile_recharge_order: '充值订单表',
   profile_feedback_submission: '反馈提交记录表',
   profile_save_archive: '用户存档记录表',
-  story_session: '剧情会话表',
-  story_event: '剧情事件表',
-  npc_state: 'NPC 状态表',
-  inventory_slot: '背包槽位表',
-  battle_state: '战斗状态表',
-  treasure_record: '宝藏记录表',
-  quest_record: '任务记录表',
-  quest_log: '任务日志表',
-  player_progression: '玩家进度表',
-  chapter_progression: '章节进度表',
-  custom_world_profile: '自定义世界档案表',
-  custom_world_session: '自定义世界会话表',
-  custom_world_agent_session: '自定义世界 Agent 会话表',
-  custom_world_agent_message: '自定义世界 Agent 消息表',
-  custom_world_agent_operation: '自定义世界 Agent 操作表',
-  custom_world_draft_card: '自定义世界草稿卡片表',
-  custom_world_gallery_entry: '自定义世界画廊条目表',
-  puzzle_agent_session: '拼图 Agent 会话表',
-  puzzle_agent_message: '拼图 Agent 消息表',
-  puzzle_work_profile: '拼图作品档案表',
-  puzzle_event: '拼图事件表',
-  puzzle_runtime_run: '拼图运行记录表',
-  puzzle_leaderboard_entry: '拼图排行榜条目表',
-  match3d_agent_session: '抓大鹅 Agent 会话表',
-  match3d_agent_message: '抓大鹅 Agent 消息表',
-  match3d_work_profile: '抓大鹅作品档案表',
-  match3d_runtime_run: '抓大鹅运行记录表',
-  square_hole_agent_session: '方洞挑战 Agent 会话表',
-  square_hole_agent_message: '方洞挑战 Agent 消息表',
-  square_hole_work_profile: '方洞挑战作品档案表',
-  square_hole_runtime_run: '方洞挑战运行记录表',
-  visual_novel_agent_session: '视觉小说 Agent 会话表',
-  visual_novel_agent_message: '视觉小说 Agent 消息表',
-  visual_novel_work_profile: '视觉小说作品档案表',
-  visual_novel_runtime_run: '视觉小说运行记录表',
-  visual_novel_runtime_history_entry: '视觉小说历史条目表',
-  visual_novel_runtime_event: '视觉小说运行事件表',
-  big_fish_creation_session: '大鱼吃小鱼创建会话表',
-  big_fish_agent_message: '大鱼吃小鱼 Agent 消息表',
-  big_fish_asset_slot: '大鱼吃小鱼资产槽位表',
-  big_fish_event: '大鱼吃小鱼事件表',
-  big_fish_runtime_run: '大鱼吃小鱼运行记录表',
   asset_object: '资产对象表',
   asset_entity_binding: '资产实体绑定表',
   asset_event: '资产事件表',

apps/admin-web/src/pages/AdminEditorGenerationModel3dPricingSection.tsx

@@ -0,0 +1,136 @@
+import type { EditorGenerationModel3dPricingPayload } from '../api/adminApiTypes';
+import {
+  EDITOR_MODEL3D_ENDPOINT_SECTIONS,
+  editorModel3dAddOnLabel,
+  parsePositiveInteger,
+  updateEditorModel3dEndpointPricing,
+} from './adminEditorGenerationPricing';
+
+interface AdminEditorGenerationModel3dPricingSectionProps {
+  model3d: EditorGenerationModel3dPricingPayload;
+  onChange: (next: EditorGenerationModel3dPricingPayload) => void;
+}
+
+/**
+ * 3D 生成定价区块：按端点分成「文生 3D」与「图生 3D」两组，每组是该端点自己的
+ * 「模型版本 × {无贴图, 带贴图}」底价表与加价项单值输入。
+ *
+ * 键集合全部来自接口返回，后台只能改数值：不能新增、删除键，也不能停用整段。
+ */
+export function AdminEditorGenerationModel3dPricingSection({
+  model3d,
+  onChange,
+}: AdminEditorGenerationModel3dPricingSectionProps) {
+  function updateEndpoint(
+    section: (typeof EDITOR_MODEL3D_ENDPOINT_SECTIONS)[number]['key'],
+    updater: Parameters<typeof updateEditorModel3dEndpointPricing>[2],
+  ) {
+    onChange(updateEditorModel3dEndpointPricing(model3d, section, updater));
+  }
+
+  return (
+    <section className="admin-panel admin-pricing-model-card">
+      <div className="admin-pricing-model-heading">
+        <strong>3D 生成定价</strong>
+        <span className="admin-pricing-unit">按次</span>
+      </div>
+      <p className="admin-pricing-model3d-hint">
+        模型版本与加价项由后端契约给出，只能改数值；两段必须完整给出，缺失即 3D
+        生成不可提交。
+      </p>
+      <div className="admin-pricing-grid">
+        {EDITOR_MODEL3D_ENDPOINT_SECTIONS.map(({ key, label }) => (
+          <section className="admin-panel admin-pricing-model-card" key={key}>
+            <div className="admin-pricing-model-heading">
+              <strong>{label}</strong>
+            </div>
+            <div className="admin-pricing-model3d-list">
+              {Object.entries(model3d[key].versionPrices).map(
+                ([version, price]) => (
+                  <div className="admin-pricing-model3d-row" key={version}>
+                    <span className="admin-pricing-model3d-row-label">
+                      {version}
+                    </span>
+                    <label className="admin-field">
+                      <span>无贴图</span>
+                      <input
+                        aria-label={`${label} ${version} 无贴图`}
+                        min={1}
+                        step={1}
+                        type="number"
+                        value={price.noTexture}
+                        onChange={(event) =>
+                          updateEndpoint(key, (current) => ({
+                            ...current,
+                            versionPrices: {
+                              ...current.versionPrices,
+                              [version]: {
+                                ...price,
+                                noTexture: parsePositiveInteger(
+                                  event.target.value,
+                                ),
+                              },
+                            },
+                          }))
+                        }
+                      />
+                    </label>
+                    <label className="admin-field">
+                      <span>带贴图</span>
+                      <input
+                        aria-label={`${label} ${version} 带贴图`}
+                        min={1}
+                        step={1}
+                        type="number"
+                        value={price.texture}
+                        onChange={(event) =>
+                          updateEndpoint(key, (current) => ({
+                            ...current,
+                            versionPrices: {
+                              ...current.versionPrices,
+                              [version]: {
+                                ...price,
+                                texture: parsePositiveInteger(
+                                  event.target.value,
+                                ),
+                              },
+                            },
+                          }))
+                        }
+                      />
+                    </label>
+                  </div>
+                ),
+              )}
+            </div>
+            <div className="admin-form-row">
+              {Object.entries(model3d[key].addOnPrices).map(
+                ([addOn, price]) => (
+                  <label className="admin-field" key={addOn}>
+                    <span>{editorModel3dAddOnLabel(addOn)}</span>
+                    <input
+                      aria-label={`${label} ${editorModel3dAddOnLabel(addOn)}`}
+                      min={1}
+                      step={1}
+                      type="number"
+                      value={price}
+                      onChange={(event) =>
+                        updateEndpoint(key, (current) => ({
+                          ...current,
+                          addOnPrices: {
+                            ...current.addOnPrices,
+                            [addOn]: parsePositiveInteger(event.target.value),
+                          },
+                        }))
+                      }
+                    />
+                  </label>
+                ),
+              )}
+            </div>
+          </section>
+        ))}
+      </div>
+    </section>
+  );
+}

apps/admin-web/src/pages/AdminEditorGenerationPricingPage.test.tsx

@@ -5,20 +5,23 @@ import userEvent from '@testing-library/user-event';
 import { beforeEach, expect, test, vi } from 'vitest';
 
 import {
+  AdminApiError,
   getAdminEditorGenerationPricing,
   upsertAdminEditorGenerationPricing,
 } from '../api/adminApiClient';
 import type { EditorGenerationPricingConfigPayload } from '../api/adminApiTypes';
 import { AdminEditorGenerationPricingPage } from './AdminEditorGenerationPricingPage';
 
-vi.mock('../api/adminApiClient', () => ({
+vi.mock('../api/adminApiClient', async () => {
-  formatAdminApiError: vi.fn((error: unknown) =>
+  const actual = await vi.importActual<typeof import('../api/adminApiClient')>(
-    error instanceof Error ? error.message : '请求失败',
+    '../api/adminApiClient',
-  ),
+  );
-  getAdminEditorGenerationPricing: vi.fn(),
+  return {
-  isAdminApiError: vi.fn(() => false),
+    ...actual,
-  upsertAdminEditorGenerationPricing: vi.fn(),
+    getAdminEditorGenerationPricing: vi.fn(),
-}));
+    upsertAdminEditorGenerationPricing: vi.fn(),
+  };
+});
 
 const pricing: EditorGenerationPricingConfigPayload = {
   models: {
@@ -41,36 +44,80 @@ const pricing: EditorGenerationPricingConfigPayload = {
     'audio1.0': { unit: 'perGeneration', price: 5 },
     'chirp-v5': { unit: 'perGeneration', price: 12 },
   },
+  model3d: {
+    textToModelPricing: {
+      versionPrices: {
+        'v3.1-20260211': { noTexture: 8, texture: 16 },
+        'P2-20260801': { noTexture: 80, texture: 88 },
+      },
+      addOnPrices: {
+        hdTexture: 8,
+        ultraTexture: 16,
+        quadMesh: 4,
+        generateParts: 16,
+      },
+    },
+    imageToModelPricing: {
+      versionPrices: {
+        'v3.1-20260211': { noTexture: 16, texture: 24 },
+        'P2-20260801': { noTexture: 80, texture: 88 },
+      },
+      addOnPrices: {
+        hdTexture: 8,
+        ultraTexture: 16,
+        quadMesh: 4,
+        generateParts: 16,
+      },
+    },
+  },
+  updatedAtMicros: 1_700_000_000_000_000,
 };
 
+function savedPricing(
+  overrides: Partial<EditorGenerationPricingConfigPayload> = {},
+) {
+  return {
+    ...pricing,
+    updatedAtMicros: pricing.updatedAtMicros + 1,
+    ...overrides,
+  };
+}
+
 beforeEach(() => {
   vi.clearAllMocks();
   vi.mocked(getAdminEditorGenerationPricing).mockResolvedValue(pricing);
-  vi.mocked(upsertAdminEditorGenerationPricing).mockResolvedValue({
+  vi.mocked(upsertAdminEditorGenerationPricing).mockResolvedValue(
-    ...pricing,
+    savedPricing({
-    models: {
+      models: {
-      ...pricing.models,
+        ...pricing.models,
-      'gpt-image-2': {
+        'gpt-image-2': {
-        unit: 'perGeneration',
+          unit: 'perGeneration',
-        prices: { '1K': 20, '2K': 58 },
+          prices: { '1K': 20, '2K': 58 },
+        },
       },
-    },
+    }),
-  });
+  );
 });
 
-test('模型定价后台按模型展示单位并保存尺寸定价', async () => {
+async function renderPage() {
-  const user = userEvent.setup();
   render(
     <AdminEditorGenerationPricingPage
       token="admin-token"
       onUnauthorized={vi.fn()}
     />,
   );
+  await screen.findByText('3D 生成定价');
+}
+
+test('模型定价后台按模型展示单位并保存尺寸定价', async () => {
+  const user = userEvent.setup();
+  await renderPage();
 
   expect((await screen.findAllByText('按次')).length).toBeGreaterThan(0);
   expect(screen.getAllByText('按秒').length).toBeGreaterThan(0);
-  const gptImage2kInput = screen.getByLabelText('gpt-image-2 2K');
+  fireEvent.change(screen.getByLabelText('gpt-image-2 2K'), {
-  fireEvent.change(gptImage2kInput, { target: { value: '58' } });
+    target: { value: '58' },
+  });
   await user.click(screen.getByRole('button', { name: '保存定价' }));
   await user.click(screen.getByRole('button', { name: '确认' }));
 
@@ -90,3 +137,99 @@ test('模型定价后台按模型展示单位并保存尺寸定价', async () =>
     );
   });
 });
+
+test('3D 区块按端点渲染版本底价与加价项，并随保存回传整段与定价版本', async () => {
+  const user = userEvent.setup();
+  await renderPage();
+
+  expect(screen.getByText('文生 3D')).toBeTruthy();
+  expect(screen.getByText('图生 3D')).toBeTruthy();
+  expect(screen.getAllByText('高清贴图').length).toBeGreaterThan(0);
+
+  fireEvent.change(screen.getByLabelText('文生 3D v3.1-20260211 带贴图'), {
+    target: { value: '18' },
+  });
+  fireEvent.change(screen.getByLabelText('图生 3D P2-20260801 无贴图'), {
+    target: { value: '86' },
+  });
+  fireEvent.change(screen.getByLabelText('文生 3D 四边形网格'), {
+    target: { value: '6' },
+  });
+
+  await user.click(screen.getByRole('button', { name: '保存定价' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));
+
+  await waitFor(() => {
+    expect(upsertAdminEditorGenerationPricing).toHaveBeenCalledWith(
+      'admin-token',
+      expect.objectContaining({
+        expectedUpdatedAtMicros: pricing.updatedAtMicros,
+        model3d: {
+          textToModelPricing: expect.objectContaining({
+            versionPrices: expect.objectContaining({
+              'v3.1-20260211': { noTexture: 8, texture: 18 },
+            }),
+            addOnPrices: expect.objectContaining({ quadMesh: 6 }),
+          }),
+          imageToModelPricing: expect.objectContaining({
+            versionPrices: expect.objectContaining({
+              'P2-20260801': { noTexture: 86, texture: 88 },
+            }),
+          }),
+        },
+      }),
+    );
+  });
+});
+
+test('数值小于 1 时禁用保存并给出中文提示', async () => {
+  const user = userEvent.setup();
+  await renderPage();
+
+  fireEvent.change(screen.getByLabelText('文生 3D 四边形网格'), {
+    target: { value: '0' },
+  });
+
+  expect(await screen.findByText(/以下价格必须是不小于 1 的整数/)).toBeTruthy();
+  const saveButton = screen.getByRole('button', {
+    name: '保存定价',
+  }) as HTMLButtonElement;
+  expect(saveButton.disabled).toBe(true);
+  await user.click(saveButton);
+  expect(upsertAdminEditorGenerationPricing).not.toHaveBeenCalled();
+});
+
+test('保存遇到 409 时提示重新读取且不覆盖本地改动', async () => {
+  const user = userEvent.setup();
+  vi.mocked(upsertAdminEditorGenerationPricing).mockRejectedValue(
+    new AdminApiError({ message: '定价冲突', status: 409 }),
+  );
+  await renderPage();
+
+  await user.click(screen.getByRole('button', { name: '保存定价' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));
+
+  expect(
+    await screen.findByText('定价已被其他人更新，请重新读取后再编辑保存'),
+  ).toBeTruthy();
+  expect(screen.getByRole('button', { name: '重新读取' })).toBeTruthy();
+});
+
+test('后端未配置 3D 段时给出提示并禁止保存', async () => {
+  vi.mocked(getAdminEditorGenerationPricing).mockResolvedValue({
+    ...pricing,
+    model3d: null,
+  });
+  render(
+    <AdminEditorGenerationPricingPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  expect(await screen.findByText(/当前部署未配置 3D 定价段/)).toBeTruthy();
+  expect(
+    (screen.getByRole('button', { name: '保存定价' }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+});

apps/admin-web/src/pages/AdminEditorGenerationPricingPage.tsx

@@ -3,14 +3,22 @@ import { FormEvent, useEffect, useState } from 'react';
 
 import {
   getAdminEditorGenerationPricing,
+  isAdminApiError,
   upsertAdminEditorGenerationPricing,
 } from '../api/adminApiClient';
 import type {
+  EditorGenerationModel3dPricingPayload,
   EditorGenerationModelPricingPayload,
   EditorGenerationPricingConfigPayload,
   EditorGenerationPricingUnitPayload,
 } from '../api/adminApiTypes';
 import { useAdminWriteConfirm } from '../components/useAdminWriteConfirm';
+import { AdminEditorGenerationModel3dPricingSection } from './AdminEditorGenerationModel3dPricingSection';
+import {
+  buildAdminEditorGenerationPricingRequest,
+  collectInvalidEditorGenerationPricingLabels,
+  parsePositiveInteger,
+} from './adminEditorGenerationPricing';
 import { handlePageError } from './pageUtils';
 
 interface AdminEditorGenerationPricingPageProps {
@@ -20,6 +28,8 @@ interface AdminEditorGenerationPricingPageProps {
 
 const emptyPricing: EditorGenerationPricingConfigPayload = {
   models: {},
+  model3d: null,
+  updatedAtMicros: 0,
 };
 
 const unitLabels: Record<EditorGenerationPricingUnitPayload, string> = {
@@ -27,6 +37,9 @@ const unitLabels: Record<EditorGenerationPricingUnitPayload, string> = {
   perSecond: '按秒',
 };
 
+const PRICING_VERSION_CONFLICT_MESSAGE =
+  '定价已被其他人更新，请重新读取后再编辑保存';
+
 export function AdminEditorGenerationPricingPage({
   token,
   onUnauthorized,
@@ -36,6 +49,7 @@ export function AdminEditorGenerationPricingPage({
   const [isLoading, setIsLoading] = useState(false);
   const [isSaving, setIsSaving] = useState(false);
   const [errorMessage, setErrorMessage] = useState('');
+  const [isPricingVersionStale, setIsPricingVersionStale] = useState(false);
   const { confirmWrite, confirmDialog } = useAdminWriteConfirm();
 
   useEffect(() => {
@@ -46,6 +60,7 @@ export function AdminEditorGenerationPricingPage({
   async function refreshPricing() {
     setIsLoading(true);
     setErrorMessage('');
+    setIsPricingVersionStale(false);
     try {
       setPricing(await getAdminEditorGenerationPricing(token));
     } catch (error: unknown) {
@@ -57,10 +72,11 @@ export function AdminEditorGenerationPricingPage({
 
   async function handleSave(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
-    if (isSaving) {
+    if (isSaving || !canSave) {
       return;
     }
     setErrorMessage('');
+    setIsPricingVersionStale(false);
     const confirmed = await confirmWrite({
       action: '保存模型定价',
       target: '图片画布生成',
@@ -71,8 +87,18 @@ export function AdminEditorGenerationPricingPage({
 
     setIsSaving(true);
     try {
-      setPricing(await upsertAdminEditorGenerationPricing(token, pricing));
+      setPricing(
+        await upsertAdminEditorGenerationPricing(
+          token,
+          buildAdminEditorGenerationPricingRequest(pricing),
+        ),
+      );
     } catch (error: unknown) {
+      if (isAdminApiError(error) && error.status === 409) {
+        setErrorMessage(PRICING_VERSION_CONFLICT_MESSAGE);
+        setIsPricingVersionStale(true);
+        return;
+      }
       handlePageError(error, onUnauthorized, setErrorMessage);
     } finally {
       setIsSaving(false);
@@ -120,6 +146,15 @@ export function AdminEditorGenerationPricingPage({
     });
   }
 
+  function updateModel3dPrice(next: EditorGenerationModel3dPricingPayload) {
+    setPricing((current) => ({ ...current, model3d: next }));
+  }
+
+  const invalidPriceLabels =
+    collectInvalidEditorGenerationPricingLabels(pricing);
+  const isModel3dMissing = !pricing.model3d;
+  const canSave = invalidPriceLabels.length === 0 && !isModel3dMissing;
+
   return (
     <section className="admin-page admin-page-wide">
       <div className="admin-page-heading">
@@ -141,6 +176,31 @@ export function AdminEditorGenerationPricingPage({
       {errorMessage ? (
         <div className="admin-alert" role="status">
           {errorMessage}
+          {isPricingVersionStale ? (
+            <button
+              className="admin-secondary-button"
+              disabled={isLoading}
+              type="button"
+              onClick={refreshPricing}
+            >
+              <RefreshCcw size={17} aria-hidden="true" />
+              <span>重新读取</span>
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+
+      {isModel3dMissing ? (
+        <div className="admin-alert" role="status">
+          当前部署未配置 3D 定价段（缺失即 3D
+          生成不可提交）：需先由受控默认配置提供两段价格，
+          后台不在页面里新建或停用整段。
+        </div>
+      ) : null}
+
+      {invalidPriceLabels.length > 0 ? (
+        <div className="admin-alert" role="status">
+          {`以下价格必须是不小于 1 的整数：${invalidPriceLabels.join('、')}`}
         </div>
       ) : null}
 
@@ -156,9 +216,16 @@ export function AdminEditorGenerationPricingPage({
           )}
         </div>
 
+        {pricing.model3d ? (
+          <AdminEditorGenerationModel3dPricingSection
+            model3d={pricing.model3d}
+            onChange={updateModel3dPrice}
+          />
+        ) : null}
+
         <button
           className="admin-primary-button"
-          disabled={isSaving}
+          disabled={isSaving || !canSave}
           type="submit"
         >
           <Save size={17} aria-hidden="true" />
@@ -223,8 +290,3 @@ function renderModelPricingCard({
     </section>
   );
 }
-
-function parsePositiveInteger(value: string) {
-  const parsed = Number.parseInt(value, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
-}

apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx

@@ -175,6 +175,107 @@ test('灰度发布页可选择模板库并默认启用零比例灰度', async ()
   );
 });
 
+test('灰度发布页可选择游戏发布开关，默认保持「未开启即开放」语义', async () => {
+  const user = userEvent.setup();
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  await screen.findByRole('button', { name: 'editor.new-toolbar' });
+  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), [
+    'game-distribution',
+  ]);
+
+  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
+    'game-distribution:publish',
+  );
+  expect(
+    (screen.getByLabelText('Gate Key 目标') as HTMLSelectElement).value,
+  ).toBe('publish');
+  // 该开关的语义是「未配置/关闭 = 默认开放」，所以选中后不能默认打开收紧。
+  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
+    false,
+  );
+  expect((screen.getByLabelText('灰度比例') as HTMLInputElement).value).toBe(
+    '0',
+  );
+  expect(
+    (screen.getByLabelText('描述') as HTMLTextAreaElement).value,
+  ).toContain('游戏发布入口灰度');
+});
+
+test('灰度发布页保存游戏发布开关时写入白名单与比例', async () => {
+  const user = userEvent.setup();
+  vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({
+    gates: [
+      ...configResponse.gates,
+      {
+        gateKey: 'game-distribution:publish',
+        enabled: true,
+        rolloutPercent: 20,
+        allowUserIds: ['user-internal'],
+        allowUserTags: [],
+        denyUserIds: [],
+        description: '游戏发布入口灰度',
+        updatedAt: '2026-09-22T10:00:00Z',
+      },
+    ],
+  });
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  await screen.findByRole('button', { name: 'editor.new-toolbar' });
+  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), [
+    'game-distribution',
+  ]);
+  fireEvent.click(screen.getByLabelText('启用'));
+  fireEvent.change(screen.getByLabelText('灰度比例'), {
+    target: { value: '20' },
+  });
+  fireEvent.change(screen.getByLabelText('允许用户 ID'), {
+    target: { value: 'user-internal' },
+  });
+  fireEvent.change(screen.getByLabelText('描述'), {
+    target: { value: '游戏发布入口灰度' },
+  });
+  await user.click(screen.getByRole('button', { name: '保存配置' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));
+
+  await waitFor(() =>
+    expect(upsertAdminFeatureGateConfig).toHaveBeenCalledWith('admin-token', {
+      gateKey: 'game-distribution:publish',
+      enabled: true,
+      rolloutPercent: 20,
+      allowUserIds: ['user-internal'],
+      allowUserTags: [],
+      denyUserIds: [],
+      description: '游戏发布入口灰度',
+    }),
+  );
+});
+
+test('未创建的预设开关在后台可见并可一键配置', async () => {
+  const user = userEvent.setup();
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  const row = await screen.findByText('game-distribution:publish');
+  expect(row).not.toBeNull();
+  // 该开关默认未创建：列表里给出「配置」入口，点击后按默认关闭填充表单。
+  const configureButton = row.closest('tr')?.querySelector('button');
+  expect(configureButton).not.toBeNull();
+  await user.click(configureButton!);
+
+  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
+    'game-distribution:publish',
+  );
+  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
+    false,
+  );
+});
+
 test('灰度发布页保存时转换数组和百分比', async () => {
   const user = userEvent.setup();
   vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({

apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx

@@ -28,6 +28,7 @@ interface GateTargetOption {
 const GATE_PREFIX_LABELS: Record<string, string> = {
   'image-editor': '画布',
   agc: '客户端',
+  'game-distribution': '游戏分发',
 };
 
 const FIXED_GATE_TARGETS: GateTargetOption[] = [
@@ -45,6 +46,14 @@ const FIXED_GATE_TARGETS: GateTargetOption[] = [
     label: 'Agent 侧边栏',
     description: '画布 Agent 入口灰度',
   },
+  {
+    prefix: 'game-distribution',
+    suffix: 'publish',
+    key: 'game-distribution:publish',
+    label: '游戏发布',
+    description:
+      '游戏发布入口灰度：未配置或关闭时对已登录作者默认开放，开启后只放行白名单 / 灰度命中',
+  },
 ];
 
 export function AdminGrayReleaseConfigPage({
@@ -197,6 +206,11 @@ export function AdminGrayReleaseConfigPage({
     setErrorMessage('');
   }
 
+  // 预设里尚未创建行的开关也要可见：运营需要先看到 key 才能配置灰度。
+  const unconfiguredGateTargets = FIXED_GATE_TARGETS.filter(
+    (option) => !gates.some((gate) => gate.gateKey === option.key),
+  );
+
   function buildPayload(): AdminUpsertFeatureGateConfigRequest {
     return {
       gateKey: gateKey.trim(),
@@ -443,6 +457,53 @@ export function AdminGrayReleaseConfigPage({
             </div>
           )}
         </section>
+
+        <section className="admin-panel">
+          <div className="admin-panel-heading">
+            <h3>可配置开关</h3>
+            <span>{unconfiguredGateTargets.length}</span>
+          </div>
+          {unconfiguredGateTargets.length ? (
+            <div className="admin-table-wrap">
+              <table className="admin-table admin-table-compact">
+                <thead>
+                  <tr>
+                    <th>Gate</th>
+                    <th>说明</th>
+                    <th>操作</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {unconfiguredGateTargets.map((option) => (
+                    <tr key={option.key}>
+                      <td>
+                        {option.key}
+                        <small>
+                          {GATE_PREFIX_LABELS[option.prefix] ?? option.prefix} ·{' '}
+                          {option.label}
+                        </small>
+                      </td>
+                      <td>{option.description}</td>
+                      <td>
+                        <button
+                          className="admin-text-button"
+                          type="button"
+                          onClick={() => applyGateTarget(option)}
+                        >
+                          配置
+                        </button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          ) : (
+            <div className="admin-empty-state">
+              {isLoading ? '加载中' : '预设开关都已创建'}
+            </div>
+          )}
+        </section>
       </div>
 
       {confirmDialog}

apps/admin-web/src/pages/adminEditorGenerationPricing.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from 'vitest';
+
+import type { EditorGenerationPricingConfigPayload } from '../api/adminApiTypes';
+import {
+  buildAdminEditorGenerationPricingRequest,
+  collectInvalidEditorGenerationPricingLabels,
+  editorModel3dAddOnLabel,
+  parsePositiveInteger,
+} from './adminEditorGenerationPricing';
+
+function pricingFixture(): EditorGenerationPricingConfigPayload {
+  return {
+    models: {
+      'gpt-image-2': { unit: 'perGeneration', prices: { '1K': 3, '2K': 5 } },
+      'audio1.0': { unit: 'perGeneration', price: 5 },
+    },
+    model3d: {
+      textToModelPricing: {
+        versionPrices: { 'v3.1-20260211': { noTexture: 8, texture: 16 } },
+        addOnPrices: { hdTexture: 8, unknownAddOn: 7 },
+      },
+      imageToModelPricing: {
+        versionPrices: { 'v3.1-20260211': { noTexture: 16, texture: 24 } },
+        addOnPrices: { hdTexture: 8 },
+      },
+    },
+    updatedAtMicros: 42,
+  };
+}
+
+test('数值解析把空串、非数字与 0 收敛成 0', () => {
+  expect(parsePositiveInteger('12')).toBe(12);
+  expect(parsePositiveInteger('')).toBe(0);
+  expect(parsePositiveInteger('abc')).toBe(0);
+  expect(parsePositiveInteger('0')).toBe(0);
+  expect(parsePositiveInteger('-3')).toBe(0);
+});
+
+test('未登记的 3D 加价项键回退显示原键名', () => {
+  expect(editorModel3dAddOnLabel('hdTexture')).toBe('高清贴图');
+  expect(editorModel3dAddOnLabel('unknownAddOn')).toBe('unknownAddOn');
+});
+
+test('校验覆盖模型档位与 3D 两段的全部数值', () => {
+  expect(collectInvalidEditorGenerationPricingLabels(pricingFixture())).toEqual(
+    [],
+  );
+
+  const invalid = pricingFixture();
+  const invalidImagePricing = invalid.models['gpt-image-2'];
+  const invalidTextEndpoint = invalid.model3d?.textToModelPricing;
+  const invalidImageEndpoint = invalid.model3d?.imageToModelPricing;
+  if (
+    !invalidImagePricing?.prices ||
+    !invalidTextEndpoint ||
+    !invalidImageEndpoint
+  ) {
+    throw new Error('夹具必须包含图片档位与 3D 两段');
+  }
+  const imageVersionPrice = invalidImageEndpoint.versionPrices['v3.1-20260211'];
+  if (!imageVersionPrice) {
+    throw new Error('夹具必须包含图生 3D 的版本底价');
+  }
+  invalidImagePricing.prices['2K'] = 0;
+  invalidTextEndpoint.addOnPrices.hdTexture = 0;
+  imageVersionPrice.noTexture = 0;
+  expect(collectInvalidEditorGenerationPricingLabels(invalid)).toEqual([
+    'gpt-image-2 2K',
+    '文生 3D 高清贴图',
+    '图生 3D v3.1-20260211 无贴图',
+  ]);
+});
+
+test('保存请求整段回传两段与定价版本，3D 缺失时回传 null', () => {
+  const pricing = pricingFixture();
+  expect(buildAdminEditorGenerationPricingRequest(pricing)).toEqual({
+    models: pricing.models,
+    model3d: pricing.model3d,
+    expectedUpdatedAtMicros: 42,
+  });
+  expect(
+    buildAdminEditorGenerationPricingRequest({ ...pricing, model3d: null }),
+  ).toEqual({
+    models: pricing.models,
+    model3d: null,
+    expectedUpdatedAtMicros: 42,
+  });
+});

apps/admin-web/src/pages/adminEditorGenerationPricing.ts

@@ -0,0 +1,116 @@
+import type {
+  AdminUpsertEditorGenerationPricingRequest,
+  EditorGenerationModel3dEndpointPricingPayload,
+  EditorGenerationModel3dPricingPayload,
+  EditorGenerationPricingConfigPayload,
+} from '../api/adminApiTypes';
+
+/** 3D 端点在两个并列段里的字段名与后台展示名。 */
+export const EDITOR_MODEL3D_ENDPOINT_SECTIONS = [
+  { key: 'textToModelPricing', label: '文生 3D' },
+  { key: 'imageToModelPricing', label: '图生 3D' },
+] as const satisfies ReadonlyArray<{
+  key: keyof EditorGenerationModel3dPricingPayload;
+  label: string;
+}>;
+
+/**
+ * 3D 加价项键到中文标签。键来自接口返回，这里只负责展示；遇到未登记的键回退显示原键名，
+ * 不因为标签缺失就把该项漏掉。
+ */
+const EDITOR_MODEL3D_ADD_ON_LABELS: Record<string, string> = {
+  hdTexture: '高清贴图',
+  ultraTexture: '超高清贴图',
+  hdGeometry: '高清几何',
+  quadMesh: '四边形网格',
+  smartLowPoly: '智能低面',
+  generateParts: '分件生成',
+};
+
+export function editorModel3dAddOnLabel(addOn: string) {
+  return EDITOR_MODEL3D_ADD_ON_LABELS[addOn] ?? addOn;
+}
+
+/** 输入框文本转整数；空串、非数字、0 与负数一律收敛成 0，交给提交前校验拦住。 */
+export function parsePositiveInteger(value: string) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function isPositiveMudPoints(value: number | null | undefined) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}
+
+/**
+ * 提交前校验：所有泥点数值都必须是不小于 1 的整数，返回不合法项的展示名。
+ *
+ * 后端仍会独立校验一遍；这里只是不把明显非法的 payload 发出去，避免保存后才报错。
+ */
+export function collectInvalidEditorGenerationPricingLabels(
+  pricing: EditorGenerationPricingConfigPayload,
+) {
+  const labels: string[] = [];
+  for (const [model, modelPricing] of Object.entries(pricing.models)) {
+    if (modelPricing.prices) {
+      for (const [tier, price] of Object.entries(modelPricing.prices)) {
+        if (!isPositiveMudPoints(price)) {
+          labels.push(`${model} ${tier}`);
+        }
+      }
+      continue;
+    }
+    if (!isPositiveMudPoints(modelPricing.price)) {
+      labels.push(`${model} 泥点`);
+    }
+  }
+
+  const model3d = pricing.model3d;
+  if (model3d) {
+    for (const { key, label } of EDITOR_MODEL3D_ENDPOINT_SECTIONS) {
+      const endpointPricing = model3d[key];
+      for (const [version, price] of Object.entries(
+        endpointPricing.versionPrices,
+      )) {
+        if (!isPositiveMudPoints(price.noTexture)) {
+          labels.push(`${label} ${version} 无贴图`);
+        }
+        if (!isPositiveMudPoints(price.texture)) {
+          labels.push(`${label} ${version} 带贴图`);
+        }
+      }
+      for (const [addOn, price] of Object.entries(
+        endpointPricing.addOnPrices,
+      )) {
+        if (!isPositiveMudPoints(price)) {
+          labels.push(`${label} ${editorModel3dAddOnLabel(addOn)}`);
+        }
+      }
+    }
+  }
+  return labels;
+}
+
+/**
+ * 组装保存请求：`models` 与 3D 两段整段回传，并带上读取时拿到的定价版本做乐观锁。
+ * 3D 段缺失时回传 `null`——服务端会以 400 拒绝，后台不允许在这里静默新建或丢弃整段。
+ */
+export function buildAdminEditorGenerationPricingRequest(
+  pricing: EditorGenerationPricingConfigPayload,
+): AdminUpsertEditorGenerationPricingRequest {
+  return {
+    models: pricing.models,
+    model3d: pricing.model3d ?? null,
+    expectedUpdatedAtMicros: pricing.updatedAtMicros,
+  };
+}
+
+/** 单个端点段的不可变更新：底价与加价项各改一处，其余原样保留。 */
+export function updateEditorModel3dEndpointPricing(
+  model3d: EditorGenerationModel3dPricingPayload,
+  section: keyof EditorGenerationModel3dPricingPayload,
+  updater: (
+    current: EditorGenerationModel3dEndpointPricingPayload,
+  ) => EditorGenerationModel3dEndpointPricingPayload,
+): EditorGenerationModel3dPricingPayload {
+  return { ...model3d, [section]: updater(model3d[section]) };
+}

apps/admin-web/src/styles/admin.css

@@ -2972,6 +2972,34 @@ button:disabled {
   gap: 10px;
 }
 
+.admin-pricing-model3d-list {
+  display: grid;
+  gap: 10px;
+}
+
+.admin-pricing-model3d-row {
+  display: grid;
+  grid-template-columns: minmax(0, 1.2fr) repeat(2, minmax(0, 1fr));
+  align-items: end;
+  gap: 10px;
+}
+
+.admin-pricing-model3d-row-label {
+  color: #5c3a26;
+  font-size: 13px;
+  font-weight: 700;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+  padding-bottom: 10px;
+}
+
+.admin-pricing-model3d-hint {
+  color: #7b5a45;
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 0;
+}
+
 .admin-pricing-unit {
   flex: 0 0 auto;
   border-radius: 999px;
@@ -3022,6 +3050,7 @@ button:disabled {
   .admin-two-column-wide,
   .admin-accounts-layout,
   .admin-pricing-grid,
+  .admin-pricing-model3d-row,
   .admin-form-row,
   .admin-filter-grid,
   .admin-table-query-grid,