feat(workflow-editor): 前端接上三渲二的建资产入口与路线选择

frontend/src/entities/character/index.test.ts

@@ -15,6 +15,7 @@ const characterDto = {
         name: '常态造型',
         description: '旅行装束',
         preview_url: 'https://cdn.windup.test/outfit.png',
+        model_3d_url: 'https://cdn.windup.test/outfit.glb',
         actions: [
           {
             id: 'walk',
@@ -118,6 +119,7 @@ describe('characterApis', () => {
               name: '常态造型',
               description: '旅行装束',
               previewUrl: 'https://cdn.windup.test/outfit.png',
+              model3dUrl: 'https://cdn.windup.test/outfit.glb',
               actions: [
                 {
                   id: 'walk',
@@ -226,6 +228,22 @@ describe('characterApis', () => {
     })
   })
 
+  it('defaults model3dUrl to null when the outfit has no 3D asset yet', async () => {
+    const characterApis = await loadCharacterApis(async () =>
+      jsonResponse({
+        ...characterDto,
+        character_data: {
+          version: 2,
+          outfits: [{ ...characterDto.character_data.outfits[0], model_3d_url: undefined }],
+        },
+      }),
+    )
+
+    const character = await characterApis.get('51')
+
+    expect(character.outfits[0]?.model3dUrl).toBeNull()
+  })
+
   it('deletes one Character through the backend resource path', async () => {
     let request: Request | undefined
     const characterApis = await loadCharacterApis(async (input, init) => {

frontend/src/entities/character/index.ts

@@ -42,6 +42,8 @@ export interface Outfit {
   name: string
   description: string | null
   previewUrl: string | null
+  /** 该造型已确认的绑骨 3D 模型；null = 三渲二在此造型上不可用，动作生成走 i2v。 */
+  model3dUrl: string | null
   actions: Action[]
 }
 
@@ -106,6 +108,7 @@ interface CharacterOutfitDto {
   name: string
   description: string | null
   preview_url: string | null
+  model_3d_url?: string | null
   actions: CharacterActionDto[]
 }
 
@@ -164,6 +167,7 @@ function mapOutfit(dto: CharacterOutfitDto, characterId: string): Outfit {
     name: dto.name,
     description: dto.description,
     previewUrl: dto.preview_url,
+    model3dUrl: dto.model_3d_url ?? null,
     actions: dto.actions.map((action) => mapAction(action, dto.id)),
   }
 }
@@ -209,6 +213,7 @@ function toOutfitDto(outfit: Outfit): CharacterOutfitDto {
     name: outfit.name,
     description: outfit.description,
     preview_url: outfit.previewUrl,
+    model_3d_url: outfit.model3dUrl,
     actions: outfit.actions.map(toActionDto),
   }
 }

frontend/src/entities/character/outfit-playback.test.ts

@@ -10,6 +10,7 @@ function makeOutfit(frameCount: number): Outfit {
     name: '常态造型',
     description: null,
     previewUrl: null,
+    model3dUrl: null,
     actions: [
       {
         id: 'walk',

frontend/src/entities/generation/api.test.ts

@@ -214,6 +214,7 @@ describe('createGenerationApis', () => {
       reference_video_url: null,
       reference_image_urls: ['https://cdn.test/frame-1.png', 'https://cdn.test/extra.png'],
       num_frames: 32,
+      outfit_id: 'default',
     })
     expect(generation.result).toEqual({
       type: 'complete_animation',

frontend/src/entities/generation/api.ts

@@ -511,6 +511,9 @@ export function createGenerationApis(config: GenerationApiConfig): GenerationApi
           reference_video_url: null,
           reference_image_urls: referenceImageUrls,
           num_frames: 32,
+          // 后端据此查该造型的 model_3d_url 决定路线（三渲二 / i2v，#122）；不发就恒为
+          // None，路线永远选不中。
+          outfit_id: nonEmptyString(input.outfitId, 'outfitId'),
         })
         expectations.set(generation.id, expectation)
         return generation as Generation<T['type']>

frontend/src/entities/index.ts

@@ -78,6 +78,20 @@ export type {
 } from './generation'
 export type { GenerationApiConfig, GenerationTransport } from './generation/api'
 
+/* 三渲二资产 —— 母版预检结果与造型级 3D 模型的建造状态 */
+export { createRender3DApis, render3DApis, Render3DContractError } from './render3d/api'
+export type {
+  MasterFacts,
+  MasterPrecheckReport,
+  MasterRejectCode,
+  MasterWarning,
+  MasterWarningCode,
+  Render3DApis,
+  Render3DAsset,
+  Render3DAssetCost,
+  Render3DAssetState,
+} from './render3d'
+
 /* 媒体上传 —— 页面只依赖公开工厂与不透明引用，不处理 multipart 协议。 */
 export { createMediaApis } from './media/api'
 export type { MediaApis, MediaCategory, MediaReference } from './media'

frontend/src/entities/render3d/api.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ApiClient } from '@/shared/api'
+import { createRender3DApis, Render3DContractError } from './api'
+
+function clientReturning(data: unknown): { client: ApiClient; calls: string[] } {
+  const calls: string[] = []
+  const client: ApiClient = {
+    request: vi.fn(async (path: string, options?: { method?: string }) => {
+      calls.push(`${options?.method ?? 'GET'} ${path}`)
+      return data
+    }) as ApiClient['request'],
+    requestList: vi.fn() as ApiClient['requestList'],
+  }
+  return { client, calls }
+}
+
+const ASSET = {
+  asset_key: 'character-7/outfit-default',
+  state: 'awaiting_review',
+  model_3d_url: null,
+  review_model_url: 'https://cdn.test/pending.glb',
+  error: null,
+  cost: {
+    model3d_credits: 20,
+    autorig_credits: 10,
+    total_credits: 30,
+    total_cny: 3.6,
+    billing: 'postpaid',
+    scope: 'per_outfit_once',
+  },
+}
+
+const REPORT = {
+  accepted: true,
+  reject_code: null,
+  detail: '母版 400×600',
+  facts: {
+    width: 400,
+    height: 600,
+    subject_ratio: 0.19,
+    subject_area_ratio: 0.14,
+    limb_segments: [2, 2, 2, 2],
+    components: [33600],
+  },
+  warnings: [{ code: 'limbs_fused', detail: '两腿之间量不到空隙' }],
+}
+
+describe('三渲二资产适配器', () => {
+  it('把后端的蛇形字段翻成实体形状', async () => {
+    const { client } = clientReturning(ASSET)
+    const asset = await createRender3DApis(client).getOutfitAsset('7', 'outfit-default')
+
+    expect(asset.state).toBe('awaiting_review')
+    expect(asset.reviewModelUrl).toBe('https://cdn.test/pending.glb')
+    expect(asset.cost.totalCredits).toBe(30)
+    expect(asset.cost.totalCny).toBe(3.6)
+  })
+
+  it('四个动作各自打到自己的路径上', async () => {
+    const { client, calls } = clientReturning(ASSET)
+    const apis = createRender3DApis(client)
+    await apis.getOutfitAsset('7', 'outfit-default')
+    await apis.buildOutfitAsset('7', 'outfit-default')
+    await apis.approveOutfitAsset('7', 'outfit-default')
+    await apis.discardOutfitAsset('7', 'outfit-default')
+
+    expect(calls).toEqual([
+      'GET /render3d/characters/7/outfits/outfit-default',
+      'POST /render3d/characters/7/outfits/outfit-default/build',
+      'POST /render3d/characters/7/outfits/outfit-default/approve',
+      'POST /render3d/characters/7/outfits/outfit-default/discard',
+    ])
+  })
+
+  it('认不出的状态直接拒收', async () => {
+    const { client } = clientReturning({ ...ASSET, state: 'almost_done' })
+    await expect(createRender3DApis(client).getOutfitAsset('7', 'a')).rejects.toBeInstanceOf(
+      Render3DContractError,
+    )
+  })
+
+  it('成本字段缺一个就拒收——界面拿它让用户做付费决定', async () => {
+    const { total_cny: _dropped, ...partial } = ASSET.cost
+    const { client } = clientReturning({ ...ASSET, cost: partial })
+    await expect(createRender3DApis(client).getOutfitAsset('7', 'a')).rejects.toBeInstanceOf(
+      Render3DContractError,
+    )
+  })
+
+  it('预检结果带回量到的形态与警告', async () => {
+    const { client } = clientReturning(REPORT)
+    const report = await createRender3DApis(client).precheckMaster('https://cdn.test/m.png')
+
+    expect(report.accepted).toBe(true)
+    expect(report.facts?.limbSegments).toEqual([2, 2, 2, 2])
+    expect(report.warnings).toEqual([{ code: 'limbs_fused', detail: '两腿之间量不到空隙' }])
+  })
+
+  it('通过却带着拒绝码属于后端两处判定分叉，必须拒收', async () => {
+    // 放行的话界面会显示"这张可用"而建资产那一步拒收，用户只看到一个无从解释的失败。
+    const { client } = clientReturning({ ...REPORT, reject_code: 'aspect_too_wide' })
+    await expect(
+      createRender3DApis(client).precheckMaster('https://cdn.test/m.png'),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('被拒却没有拒绝码同样拒收', async () => {
+    const { client } = clientReturning({ ...REPORT, accepted: false, facts: null, warnings: [] })
+    await expect(
+      createRender3DApis(client).precheckMaster('https://cdn.test/m.png'),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('认不出的警告码拒收——界面会按码选文案，静默丢弃等于漏报', async () => {
+    const { client } = clientReturning({
+      ...REPORT,
+      warnings: [{ code: 'has_text', detail: '画面里有文字' }],
+    })
+    await expect(
+      createRender3DApis(client).precheckMaster('https://cdn.test/m.png'),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+})
+
+describe('三渲二适配器的形状守卫', () => {
+  // 这些分支挡的是"后端换了形状但没人发现"。放行的话,坏值会一路流到界面上:
+  // 用户看到的是 NaN 积分或空白状态,而错误的来源在两层之外。
+  async function precheckWith(payload: unknown) {
+    const { client } = clientReturning(payload)
+    return createRender3DApis(client).precheckMaster('https://cdn.test/master.png', {
+      width: 64,
+      height: 64,
+    })
+  }
+
+  it('facts 不是对象时拒收', async () => {
+    await expect(precheckWith({ ...REPORT, facts: 'not-an-object' })).rejects.toBeInstanceOf(
+      Render3DContractError,
+    )
+  })
+
+  it('量出来的尺寸不是有限数字时拒收', async () => {
+    await expect(
+      precheckWith({ ...REPORT, facts: { ...REPORT.facts, width: 'wide' } }),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('limb_segments 不是数组时拒收', async () => {
+    await expect(
+      precheckWith({ ...REPORT, facts: { ...REPORT.facts, limb_segments: 3 } }),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('limb_segments 里混进非数字时拒收', async () => {
+    await expect(
+      precheckWith({ ...REPORT, facts: { ...REPORT.facts, limb_segments: [1, '2'] } }),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('warnings 不是数组时拒收', async () => {
+    await expect(precheckWith({ ...REPORT, warnings: 'none' })).rejects.toBeInstanceOf(
+      Render3DContractError,
+    )
+  })
+
+  it('警告缺 detail 时拒收——界面要拿它告诉用户具体哪里不合格', async () => {
+    await expect(
+      precheckWith({ ...REPORT, warnings: [{ code: 'limbs_fused' }] }),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('accepted 不是布尔值时拒收', async () => {
+    await expect(precheckWith({ ...REPORT, accepted: 'yes' })).rejects.toBeInstanceOf(
+      Render3DContractError,
+    )
+  })
+
+  it('facts 缺席时是合法的——预检被拒时后端不量形态', async () => {
+    const report = await precheckWith({
+      ...REPORT,
+      accepted: false,
+      reject_code: 'aspect_too_wide',
+      facts: null,
+    })
+    expect(report.facts).toBeNull()
+  })
+
+  it('认不出的拒绝码拒收——界面按码选文案，静默丢弃等于漏报', async () => {
+    await expect(
+      precheckWith({ ...REPORT, accepted: false, reject_code: 'no_such_reason' }),
+    ).rejects.toBeInstanceOf(Render3DContractError)
+  })
+
+  it('整个预检结果不是对象时拒收', async () => {
+    await expect(precheckWith(['报告'])).rejects.toBeInstanceOf(Render3DContractError)
+  })
+})