合并主分支
解决简单冲突
This commit is contained in:
@@ -32,7 +32,7 @@ Prefer `scripts/genarrative_external_api.py` for runnable REST calls. It uses on
|
||||
- Use stable references such as `objectKey`, project resource ID, or asset ID in generation requests. Use `/assets/read-url` only for temporary preview/download access.
|
||||
- Preserve both warning channels after completion. A general `warning` can coexist with `sliceWarning`; do not discard either.
|
||||
- Do not invent missing derivatives. A source-preserved warning means the main source remains usable but requested post-processing failed. A slice warning means the complete transparent sheet is usable but individual slices are absent.
|
||||
- Keep generated artifacts in the canvas and asset library together. Character animation may need a post-completion library fallback from the first returned frame when no direct asset is present; the helper implements it.
|
||||
- Keep generated artifacts in the canvas and asset library together. Character animation accepts `assetFolderId` and `assetLabel`; its completed result directly returns the final `assetKind="character-animation"` resource and asset with formal sequence fields. Do not create a duplicate first-frame record.
|
||||
|
||||
## Documentation Navigation
|
||||
|
||||
@@ -107,6 +107,8 @@ client.generate_image(
|
||||
|
||||
Helper convenience methods wait locally, but the server still uses short asynchronous submit/status requests. For durable caller-controlled orchestration, call `submit_generation`, persist its `operationId` and idempotency key, then call `get_generation` or `wait_for_generation`.
|
||||
|
||||
For character animation, pass the canvas session and asset label to `animate_character`. The helper submits asynchronously and returns the completed compact result containing the authoritative formal `resource` and `asset`; do not synthesize a library asset from the first frame.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not change the fixed production base URL in generated examples.
|
||||
|
||||
@@ -46,7 +46,7 @@ Every generation row requires a stable `Idempotency-Key` header and returns HTTP
|
||||
| Image edit/redraw | `/api/external/v1/editor/images/edits` | `prompt`, `sourceImageSrc` | `referenceImageSrcs`, `model`, `size`, `projectId`, `assetFolderId`, `assetLabel`, `sourceResourceId`, `targetLayerId`, `canvasCompletion` |
|
||||
| Icon spritesheet | `/api/external/v1/editor/icon-spritesheets/generations` | `referenceImageSrc`, `iconDescriptions` | `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| UI asset extraction | `/api/external/v1/editor/ui-designs/assets/extractions` | `sourceImageSrc`, `aspectRatio`, `imageSize` | `screenColor`, `model`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `spritesheetLabel`, `canvasCompletion` |
|
||||
| Character animation | `/api/external/v1/editor/character-animations/generations` | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `canvasCompletion` |
|
||||
| Character animation | `/api/external/v1/editor/character-animations/generations` | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| Video generation | `/api/external/v1/editor/videos/generations` | `prompt`, `model`, `aspectRatio`, `durationSeconds`, `resolution`, `mode`, `sound` | `referenceImageSrcs`, `referenceVideoSrcs`, `referenceAudioSrcs`, `webSearchEnabled`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| Sound effect | `/api/external/v1/editor/audios/sound-effects/generations` | `prompt`, `duration` | `model`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
| Background music | `/api/external/v1/editor/audios/background-music/generations` | `gptDescriptionPrompt`, `makeInstrumental` | `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
@@ -64,7 +64,8 @@ Supply the `operationId` returned by submission. Poll no faster than `pollAfterM
|
||||
- Pass `projectId` and `canvasCompletion` to write generated output into the canvas.
|
||||
- Pass `assetFolderId` plus `assetLabel` for image, edit, icon spritesheet, video, sound effect, and BGM operations when supported.
|
||||
- UI extraction uses `assetFolderId` and `spritesheetLabel`.
|
||||
- Character animation does not accept the same library fields. If its completed compact result lacks a direct `asset`, create a library record from the first returned frame; do not duplicate one when an asset already exists.
|
||||
- Character animation accepts `assetFolderId` and `assetLabel`. Its completed compact result directly returns the final `assetKind="character-animation"` resource and asset with `imageSequenceFrames` and `imageSequenceDurationMs`; never create a duplicate first-frame resource or asset.
|
||||
- If a caller must manually create a `character-animation` resource or asset, put the authoritative frames and total sequence duration in `imageSequenceFrames` and `imageSequenceDurationMs`. Keep `generationInputs` replayable: it must not contain legacy runtime fields such as `characterAnimation`, `frames`, `previewVideoPath`, `frameCount`, `fps`, or `durationSeconds`.
|
||||
- Reload project/library state after completion when full current state is required.
|
||||
|
||||
## Reference Field Mapping
|
||||
|
||||
@@ -20,7 +20,7 @@ Before the first generation in a new conversation, obtain a canvas name unless t
|
||||
2. Read the asset library. Reuse a folder with the same label or create one with the canvas name.
|
||||
3. Retain `canvasName`, `projectId`, `assetFolderId`, and the current art spec in conversation state.
|
||||
|
||||
Generated artifacts must enter both the current canvas and its same-name library folder whenever the endpoint supports that invariant. Pass `projectId`, `assetFolderId`, the endpoint's label field, and `canvasCompletion`. Character animation may return no direct library asset; after completion, create one from the first returned frame only when the compact result still lacks an asset.
|
||||
Generated artifacts must enter both the current canvas and its same-name library folder whenever the endpoint supports that invariant. Pass `projectId`, `assetFolderId`, the endpoint's label field, and `canvasCompletion`. Character animation returns the final formal resource and asset directly; use those records and never create a duplicate from the first frame.
|
||||
|
||||
## Art Spec Routing
|
||||
|
||||
|
||||
@@ -98,7 +98,9 @@ A minimal `canvasCompletion` is:
|
||||
|
||||
`dialogId` is optional. Do not reconstruct canvas state from completion results. Reload the project and asset library when complete authoritative snapshots are needed.
|
||||
|
||||
Character animation may complete without a direct `asset` field. To preserve the canvas/library invariant, create a library asset from the first returned frame only if the compact result lacks one. Prefer `client.animate_character(..., canvasSession=session, canvasTitle="...")`, which implements this fallback.
|
||||
Character animation accepts `assetFolderId` and `assetLabel` and persists the final transparent sequence directly. Its completed compact result includes the authoritative `assetKind="character-animation"` resource and asset with `imageSequenceFrames` and `imageSequenceDurationMs`. Use those records directly and never synthesize a duplicate asset from the first frame.
|
||||
|
||||
For the lower-level asset/resource creation endpoints, `generationInputs` is replayable request context rather than a media-runtime container. When `assetKind` is `character-animation`, the server rejects legacy runtime keys including `characterAnimation`, `frames`, `previewVideoPath`, `frameCount`, `fps`, and `durationSeconds`; send the formal sequence through `imageSequenceFrames` and `imageSequenceDurationMs`. Internal processing audit keys such as `screenColorHex`, `mattingProvider`, and `mattingModel` are removed before persistence.
|
||||
|
||||
## Art Spec and Image Request
|
||||
|
||||
@@ -178,7 +180,9 @@ For character animation from a local-only source, use actual dimensions and a st
|
||||
"ratio": "9:16",
|
||||
"frameCount": 40,
|
||||
"durationSeconds": 5,
|
||||
"model": "seedance2.0-fast"
|
||||
"model": "seedance2.0-fast",
|
||||
"assetFolderId": "<assetFolderId>",
|
||||
"assetLabel": "角色呼吸动画"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -600,16 +600,14 @@ class GenarrativeExternalClient:
|
||||
source_layer_id: str,
|
||||
**fields: Any,
|
||||
) -> Any:
|
||||
session, asset_label = self._apply_canvas_session_fields(
|
||||
self._apply_canvas_session_fields(
|
||||
fields,
|
||||
fields.get("canvasTitle", "角色动画"),
|
||||
source_width,
|
||||
source_height,
|
||||
asset_label_field=None,
|
||||
asset_label_field="assetLabel",
|
||||
)
|
||||
prompt_text = self._apply_art_spec(fields, prompt_text)
|
||||
fields.pop("assetFolderId", None)
|
||||
fields.pop("assetLabel", None)
|
||||
idempotency_key = fields.pop("idempotencyKey", None)
|
||||
body = {
|
||||
"sourceLayerId": source_layer_id,
|
||||
@@ -624,34 +622,11 @@ class GenarrativeExternalClient:
|
||||
**fields,
|
||||
"model": "seedance2.0-fast",
|
||||
}
|
||||
result = self.submit_and_wait_generation(
|
||||
return self.submit_and_wait_generation(
|
||||
"/api/external/v1/editor/character-animations/generations",
|
||||
body,
|
||||
idempotency_key=idempotency_key,
|
||||
)
|
||||
if isinstance(session, dict) and isinstance(result, dict) and not result.get("asset"):
|
||||
frames = result.get("frames")
|
||||
first_frame = frames[0] if isinstance(frames, list) and frames else None
|
||||
folder_id = normalize_optional_text(session.get("assetFolderId"))
|
||||
if isinstance(first_frame, dict) and folder_id:
|
||||
asset = self.create_asset(
|
||||
folder_id,
|
||||
asset_label,
|
||||
first_frame["imageSrc"],
|
||||
int(first_frame["width"]),
|
||||
int(first_frame["height"]),
|
||||
prompt=result.get("prompt"),
|
||||
model=result.get("model"),
|
||||
provider="ark",
|
||||
taskId=result.get("taskId"),
|
||||
assetKind="character-animation",
|
||||
generationInputs={
|
||||
"frames": frames,
|
||||
"previewVideoPath": result.get("previewVideoPath"),
|
||||
},
|
||||
)
|
||||
result["asset"] = unwrap_envelope(asset).get("asset")
|
||||
return result
|
||||
|
||||
def generate_video(self, prompt: str, **fields: Any) -> Any:
|
||||
fields.pop("mode", None)
|
||||
@@ -732,14 +707,31 @@ def _self_test() -> None:
|
||||
"timeout": timeout,
|
||||
"headers": headers,
|
||||
})
|
||||
if path == "/api/external/v1/editor/assets":
|
||||
return {"asset": {"assetId": "editor-asset-demo"}}
|
||||
generated = {
|
||||
"taskId": "task-demo",
|
||||
"model": "seedance2.0-fast",
|
||||
"prompt": "角色呼吸",
|
||||
"previewVideoPath": "/generated/preview.mp4",
|
||||
"frames": [{"frameIndex": 1, "imageSrc": "/generated/frame01.png", "width": 512, "height": 768}],
|
||||
"frames": [{"imageSrc": "/generated/frame01.png", "width": 512, "height": 768}],
|
||||
"resource": {
|
||||
"resourceId": "editor-resource-demo",
|
||||
"assetKind": "character-animation",
|
||||
"sourceResourceId": "editor-resource-preview-demo",
|
||||
"imageSequenceFrames": [
|
||||
{"imageSrc": "/generated/frame01.png", "width": 512, "height": 768},
|
||||
{"imageSrc": "/generated/frame02.png", "width": 512, "height": 768},
|
||||
],
|
||||
"imageSequenceDurationMs": 4000,
|
||||
},
|
||||
"asset": {
|
||||
"assetId": "editor-asset-demo",
|
||||
"assetKind": "character-animation",
|
||||
"imageSequenceFrames": [
|
||||
{"imageSrc": "/generated/frame01.png", "width": 512, "height": 768},
|
||||
{"imageSrc": "/generated/frame02.png", "width": 512, "height": 768},
|
||||
],
|
||||
"imageSequenceDurationMs": 4000,
|
||||
},
|
||||
}
|
||||
if method == "POST":
|
||||
return {"operationId": "task-operation-demo", "status": "queued", "pollAfterMs": 1}
|
||||
@@ -760,10 +752,14 @@ def _self_test() -> None:
|
||||
assert calls[0]["timeout"] == DEFAULT_REQUEST_TIMEOUT_SECONDS
|
||||
assert calls[0]["headers"]["Idempotency-Key"]
|
||||
assert calls[0]["body"]["projectId"] == "proj-demo"
|
||||
assert calls[0]["body"]["assetFolderId"] == "editor-asset-folder-demo"
|
||||
assert calls[0]["body"]["assetLabel"] == "角色呼吸动画"
|
||||
assert calls[0]["body"]["canvasCompletion"]["title"] == "角色呼吸动画"
|
||||
assert calls[1]["path"] == "/api/external/v1/generations/task-operation-demo"
|
||||
assert calls[2]["path"] == "/api/external/v1/editor/assets"
|
||||
assert result["asset"]["assetId"] == "editor-asset-demo"
|
||||
assert result["asset"]["assetKind"] == "character-animation"
|
||||
assert len(result["asset"]["imageSequenceFrames"]) == 2
|
||||
assert result["asset"]["imageSequenceDurationMs"] == 4000
|
||||
calls.clear()
|
||||
client.generate_icon_spritesheet(
|
||||
"editor-resource-spec",
|
||||
|
||||
@@ -332,6 +332,14 @@ export interface AdminEditorAssetListQuery {
|
||||
limit?: number | null;
|
||||
}
|
||||
|
||||
export interface AdminEditorImageSequenceFramePayload {
|
||||
imageSrc: string;
|
||||
objectKey?: string | null;
|
||||
assetObjectId?: string | null;
|
||||
width: number;
|
||||
height: number;
|
||||
}
|
||||
|
||||
export interface AdminEditorAssetPayload {
|
||||
assetId: string;
|
||||
ownerUserId: string;
|
||||
@@ -362,6 +370,8 @@ export interface AdminEditorAssetPayload {
|
||||
taskGenerator: string;
|
||||
taskCostMudPoints: number;
|
||||
children: AdminEditorAssetPayload[];
|
||||
imageSequenceFrames?: AdminEditorImageSequenceFramePayload[] | null;
|
||||
imageSequenceDurationMs?: number | null;
|
||||
}
|
||||
|
||||
export interface AdminEditorAssetListResponse {
|
||||
@@ -413,6 +423,8 @@ export interface AdminEditorShowcaseAssetPayload {
|
||||
rejectedAt?: string | null;
|
||||
updatedAt: string;
|
||||
showcaseCategory?: string | null;
|
||||
imageSequenceFrames?: AdminEditorImageSequenceFramePayload[] | null;
|
||||
imageSequenceDurationMs?: number | null;
|
||||
}
|
||||
|
||||
export interface AdminEditorShowcaseListResponse {
|
||||
|
||||
@@ -0,0 +1,354 @@
|
||||
/* @vitest-environment jsdom */
|
||||
|
||||
import { act, fireEvent, render, screen, within } from '@testing-library/react';
|
||||
import { afterEach, expect, test, vi } from 'vitest';
|
||||
|
||||
import { getAdminAssetReadUrl } from '../api/adminApiClient';
|
||||
import { AdminEditorAssetPreviewDialog } from './AdminEditorAssetMedia';
|
||||
|
||||
vi.mock('../api/adminApiClient', () => ({
|
||||
getAdminAssetReadUrl: vi.fn(),
|
||||
isAdminApiError: vi.fn(
|
||||
(error: unknown) =>
|
||||
typeof error === 'object' &&
|
||||
error !== null &&
|
||||
'status' in error &&
|
||||
typeof error.status === 'number',
|
||||
),
|
||||
}));
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllMocks();
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
function createDeferred<T>() {
|
||||
let resolve!: (value: T | PromiseLike<T>) => void;
|
||||
let reject!: (reason?: unknown) => void;
|
||||
const promise = new Promise<T>((resolvePromise, rejectPromise) => {
|
||||
resolve = resolvePromise;
|
||||
reject = rejectPromise;
|
||||
});
|
||||
return { promise, resolve, reject };
|
||||
}
|
||||
|
||||
test('角色动作预览跨窗口回播时复用父级换签缓存并等待目标帧就绪', async () => {
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date('2026-07-04T10:50:00Z'));
|
||||
const frameObjectKeys = [
|
||||
'generated-animations/editor/task-cache/frame00.png',
|
||||
'generated-animations/editor/task-cache/frame01.png',
|
||||
'generated-animations/editor/task-cache/frame02.png',
|
||||
'generated-animations/editor/task-cache/frame03.png',
|
||||
'generated-animations/editor/task-cache/frame04.png',
|
||||
] as const;
|
||||
const delayedFrame = createDeferred<{
|
||||
read: {
|
||||
objectKey: string;
|
||||
signedUrl: string;
|
||||
expiresAt: string;
|
||||
};
|
||||
}>();
|
||||
vi.mocked(getAdminAssetReadUrl).mockImplementation((_token, request) => {
|
||||
const objectKey = request.objectKey ?? '';
|
||||
if (objectKey === frameObjectKeys[3]) {
|
||||
return delayedFrame.promise;
|
||||
}
|
||||
return Promise.resolve({
|
||||
read: {
|
||||
objectKey,
|
||||
signedUrl: `https://signed.example.com/${objectKey}`,
|
||||
expiresAt: '2026-07-04T11:00:00Z',
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
render(
|
||||
<AdminEditorAssetPreviewDialog
|
||||
entry={{
|
||||
assetId: 'asset-character-animation-cache',
|
||||
label: '缓存回播动作',
|
||||
imageSrc: `/${frameObjectKeys[0]}`,
|
||||
objectKey: frameObjectKeys[0],
|
||||
assetKind: 'character-animation',
|
||||
imageSequenceFrames: frameObjectKeys.map((objectKey) => ({
|
||||
imageSrc: `/${objectKey}`,
|
||||
objectKey,
|
||||
width: 192,
|
||||
height: 256,
|
||||
})),
|
||||
imageSequenceDurationMs: 500,
|
||||
}}
|
||||
token="admin-token"
|
||||
onClose={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
const dialog = screen.getByRole('dialog', { name: '素材预览' });
|
||||
fireEvent.click(within(dialog).getByRole('button', { name: '暂停角色动作' }));
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(120);
|
||||
});
|
||||
const initialFrames = Array.from(
|
||||
dialog.querySelectorAll<HTMLImageElement>(
|
||||
'.admin-asset-query-sequence-frame',
|
||||
),
|
||||
);
|
||||
expect(initialFrames).toHaveLength(3);
|
||||
initialFrames.forEach((frame) => fireEvent.load(frame));
|
||||
|
||||
fireEvent.click(within(dialog).getByRole('button', { name: '播放角色动作' }));
|
||||
for (const elapsedMs of [100, 40, 60, 40, 60]) {
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(elapsedMs);
|
||||
});
|
||||
}
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: frameObjectKeys[3],
|
||||
expireSeconds: 300,
|
||||
});
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(
|
||||
`https://signed.example.com/${frameObjectKeys[2]}`,
|
||||
);
|
||||
|
||||
await act(async () => {
|
||||
delayedFrame.resolve({
|
||||
read: {
|
||||
objectKey: frameObjectKeys[3],
|
||||
signedUrl: `https://signed.example.com/${frameObjectKeys[3]}`,
|
||||
expiresAt: '2026-07-04T11:00:00Z',
|
||||
},
|
||||
});
|
||||
await Promise.resolve();
|
||||
});
|
||||
const fourthFrame = resolveFrameByObjectKey(dialog, frameObjectKeys[3]);
|
||||
expect(fourthFrame?.style.opacity).toBe('0');
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(
|
||||
`https://signed.example.com/${frameObjectKeys[2]}`,
|
||||
);
|
||||
fireEvent.load(fourthFrame!);
|
||||
fireEvent.load(resolveFrameByObjectKey(dialog, frameObjectKeys[4])!);
|
||||
|
||||
for (let index = 0; index < 3; index += 1) {
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(100);
|
||||
});
|
||||
}
|
||||
expect(within(dialog).getByText('1/5')).toBeTruthy();
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(
|
||||
`https://signed.example.com/${frameObjectKeys[0]}`,
|
||||
);
|
||||
expect(
|
||||
vi
|
||||
.mocked(getAdminAssetReadUrl)
|
||||
.mock.calls.filter(
|
||||
([, request]) => request.objectKey === frameObjectKeys[0],
|
||||
),
|
||||
).toHaveLength(1);
|
||||
expect(
|
||||
dialog.querySelectorAll('.admin-asset-query-sequence-frame').length,
|
||||
).toBeLessThanOrEqual(3);
|
||||
});
|
||||
|
||||
test('角色动作预览打开超过五分钟后回绕播放会在过期窗口内自动换签', async () => {
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date('2099-01-01T00:00:00Z'));
|
||||
const frameObjectKeys = Array.from(
|
||||
{ length: 5 },
|
||||
(_, index) => `generated-animations/editor/task-expiry/frame0${index}.png`,
|
||||
);
|
||||
const requestCounts = new Map<string, number>();
|
||||
vi.mocked(getAdminAssetReadUrl).mockImplementation((_token, request) => {
|
||||
const objectKey = request.objectKey ?? '';
|
||||
const requestCount = (requestCounts.get(objectKey) ?? 0) + 1;
|
||||
requestCounts.set(objectKey, requestCount);
|
||||
return Promise.resolve({
|
||||
read: {
|
||||
objectKey,
|
||||
signedUrl: `https://signed.example.com/v${requestCount}/${objectKey}`,
|
||||
expiresAt:
|
||||
requestCount === 1 ? '2099-01-01T00:05:00Z' : '2099-01-01T00:10:00Z',
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
render(
|
||||
<AdminEditorAssetPreviewDialog
|
||||
entry={{
|
||||
assetId: 'asset-character-animation-expiry',
|
||||
label: '过期换签动作',
|
||||
imageSrc: `/${frameObjectKeys[0]}`,
|
||||
objectKey: frameObjectKeys[0],
|
||||
assetKind: 'character-animation',
|
||||
imageSequenceFrames: frameObjectKeys.map((objectKey) => ({
|
||||
imageSrc: `/${objectKey}`,
|
||||
objectKey,
|
||||
width: 192,
|
||||
height: 256,
|
||||
})),
|
||||
imageSequenceDurationMs: 5_000,
|
||||
}}
|
||||
token="admin-token"
|
||||
onClose={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
const dialog = screen.getByRole('dialog', { name: '素材预览' });
|
||||
fireEvent.click(within(dialog).getByRole('button', { name: '暂停角色动作' }));
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(120);
|
||||
});
|
||||
loadMountedFrames(dialog);
|
||||
|
||||
for (let index = 0; index < frameObjectKeys.length; index += 1) {
|
||||
fireEvent.click(
|
||||
within(dialog).getByRole('button', { name: '播放角色动作' }),
|
||||
);
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(1_000);
|
||||
});
|
||||
fireEvent.click(
|
||||
within(dialog).getByRole('button', { name: '暂停角色动作' }),
|
||||
);
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(120);
|
||||
});
|
||||
loadMountedFrames(dialog);
|
||||
}
|
||||
expect(within(dialog).getByText('1/5')).toBeTruthy();
|
||||
frameObjectKeys.forEach((objectKey) => {
|
||||
expect(requestCounts.get(objectKey)).toBe(1);
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(300_001);
|
||||
});
|
||||
loadMountedFrames(dialog);
|
||||
expect(resolveVisibleFrameSrc(dialog)).toContain('/v2/');
|
||||
|
||||
for (let index = 0; index < frameObjectKeys.length; index += 1) {
|
||||
fireEvent.click(
|
||||
within(dialog).getByRole('button', { name: '播放角色动作' }),
|
||||
);
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(1_000);
|
||||
});
|
||||
fireEvent.click(
|
||||
within(dialog).getByRole('button', { name: '暂停角色动作' }),
|
||||
);
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(120);
|
||||
});
|
||||
loadMountedFrames(dialog);
|
||||
}
|
||||
|
||||
expect(within(dialog).getByText('1/5')).toBeTruthy();
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(
|
||||
`https://signed.example.com/v2/${frameObjectKeys[0]}`,
|
||||
);
|
||||
frameObjectKeys.forEach((objectKey) => {
|
||||
expect(requestCounts.get(objectKey)).toBe(2);
|
||||
});
|
||||
expect(within(dialog).queryByText(/帧加载失败/u)).toBeNull();
|
||||
});
|
||||
|
||||
test('角色动作预览提前换签失败时保留已就绪帧并有限重试', async () => {
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date('2099-01-01T00:00:00Z'));
|
||||
const frameObjectKeys = [
|
||||
'generated-animations/editor/task-refresh-failure/frame00.png',
|
||||
'generated-animations/editor/task-refresh-failure/frame01.png',
|
||||
] as const;
|
||||
const requestCounts = new Map<string, number>();
|
||||
vi.mocked(getAdminAssetReadUrl).mockImplementation((_token, request) => {
|
||||
const objectKey = request.objectKey ?? '';
|
||||
const requestCount = (requestCounts.get(objectKey) ?? 0) + 1;
|
||||
requestCounts.set(objectKey, requestCount);
|
||||
if (objectKey === frameObjectKeys[0] && requestCount > 1) {
|
||||
return Promise.reject(new Error('refresh unavailable'));
|
||||
}
|
||||
return Promise.resolve({
|
||||
read: {
|
||||
objectKey,
|
||||
signedUrl: `https://signed.example.com/v${requestCount}/${objectKey}`,
|
||||
expiresAt:
|
||||
requestCount === 1 ? '2099-01-01T00:05:00Z' : '2099-01-01T00:10:00Z',
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
render(
|
||||
<AdminEditorAssetPreviewDialog
|
||||
entry={{
|
||||
assetId: 'asset-character-animation-refresh-failure',
|
||||
label: '换签失败动作',
|
||||
imageSrc: `/${frameObjectKeys[0]}`,
|
||||
objectKey: frameObjectKeys[0],
|
||||
assetKind: 'character-animation',
|
||||
imageSequenceFrames: frameObjectKeys.map((objectKey) => ({
|
||||
imageSrc: `/${objectKey}`,
|
||||
objectKey,
|
||||
width: 192,
|
||||
height: 256,
|
||||
})),
|
||||
imageSequenceDurationMs: 2_000,
|
||||
}}
|
||||
token="admin-token"
|
||||
onClose={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
const dialog = screen.getByRole('dialog', { name: '素材预览' });
|
||||
fireEvent.click(within(dialog).getByRole('button', { name: '暂停角色动作' }));
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(120);
|
||||
});
|
||||
loadMountedFrames(dialog);
|
||||
const readyFrameSrc = resolveVisibleFrameSrc(dialog);
|
||||
expect(readyFrameSrc).toBe(
|
||||
`https://signed.example.com/v1/${frameObjectKeys[0]}`,
|
||||
);
|
||||
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(270_100);
|
||||
});
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(readyFrameSrc);
|
||||
expect(within(dialog).queryByText(/帧加载失败/u)).toBeNull();
|
||||
|
||||
for (const retryWindowMs of [450, 1_250, 3_050]) {
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(retryWindowMs);
|
||||
});
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(readyFrameSrc);
|
||||
}
|
||||
expect(requestCounts.get(frameObjectKeys[0])).toBe(5);
|
||||
expect(within(dialog).queryByText(/帧加载失败/u)).toBeNull();
|
||||
|
||||
await act(async () => {
|
||||
await vi.advanceTimersByTimeAsync(20_000);
|
||||
});
|
||||
expect(requestCounts.get(frameObjectKeys[0])).toBe(5);
|
||||
expect(resolveVisibleFrameSrc(dialog)).toBe(readyFrameSrc);
|
||||
});
|
||||
|
||||
function loadMountedFrames(dialog: HTMLElement) {
|
||||
dialog
|
||||
.querySelectorAll<HTMLImageElement>('.admin-asset-query-sequence-frame')
|
||||
.forEach((frame) => fireEvent.load(frame));
|
||||
}
|
||||
|
||||
function resolveFrameByObjectKey(dialog: HTMLElement, objectKey: string) {
|
||||
return Array.from(
|
||||
dialog.querySelectorAll<HTMLImageElement>(
|
||||
'.admin-asset-query-sequence-frame',
|
||||
),
|
||||
).find((frame) => frame.src.endsWith(objectKey));
|
||||
}
|
||||
|
||||
function resolveVisibleFrameSrc(dialog: HTMLElement) {
|
||||
return Array.from(
|
||||
dialog.querySelectorAll<HTMLImageElement>(
|
||||
'.admin-asset-query-sequence-frame',
|
||||
),
|
||||
).find((frame) => frame.style.opacity === '1')?.src;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1068,7 +1068,7 @@ test('后台素材查询点击图片缩略图可打开放大预览', async () =>
|
||||
});
|
||||
});
|
||||
|
||||
test('后台素材查询将角色动画首帧 PNG 作为图片预览', async () => {
|
||||
test('后台素材查询在现有预览弹窗播放完整角色动作序列', async () => {
|
||||
const user = userEvent.setup();
|
||||
vi.mocked(listAdminEditorAssets).mockResolvedValueOnce({
|
||||
entries: [
|
||||
@@ -1081,17 +1081,65 @@ test('后台素材查询将角色动画首帧 PNG 作为图片预览', async ()
|
||||
assetKind: 'character-animation',
|
||||
thumbnailSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame00.png',
|
||||
imageSequenceFrames: [
|
||||
{
|
||||
imageSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame00.png',
|
||||
objectKey:
|
||||
'generated-animations/editor/source-1/task-1/frame00.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
{
|
||||
imageSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame01.png',
|
||||
objectKey:
|
||||
'generated-animations/editor/source-1/task-1/frame01.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
{
|
||||
imageSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame02.png',
|
||||
objectKey:
|
||||
'generated-animations/editor/source-1/task-1/frame02.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
{
|
||||
imageSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame03.png',
|
||||
objectKey:
|
||||
'generated-animations/editor/source-1/task-1/frame03.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
{
|
||||
imageSrc:
|
||||
'/generated-animations/editor/source-1/task-1/frame04.png',
|
||||
objectKey:
|
||||
'generated-animations/editor/source-1/task-1/frame04.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
],
|
||||
imageSequenceDurationMs: 250,
|
||||
},
|
||||
],
|
||||
nextCursor: null,
|
||||
});
|
||||
vi.mocked(getAdminAssetReadUrl).mockResolvedValue({
|
||||
read: {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame00.png',
|
||||
signedUrl: 'https://signed.example.com/character-animation-frame00.png',
|
||||
expiresAt: '2026-07-04T11:00:00Z',
|
||||
vi.mocked(getAdminAssetReadUrl).mockImplementation(
|
||||
async (_token, request) => {
|
||||
const objectKey = request.objectKey ?? undefined;
|
||||
return {
|
||||
read: {
|
||||
objectKey,
|
||||
signedUrl: `https://signed.example.com/${objectKey ?? ''}`,
|
||||
expiresAt: '2099-01-01T00:05:00Z',
|
||||
},
|
||||
};
|
||||
},
|
||||
});
|
||||
);
|
||||
|
||||
render(
|
||||
<AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
|
||||
@@ -1102,15 +1150,56 @@ test('后台素材查询将角色动画首帧 PNG 作为图片预览', async ()
|
||||
);
|
||||
|
||||
const dialog = await screen.findByRole('dialog', { name: '素材预览' });
|
||||
const image = await within(dialog).findByRole('img', {
|
||||
name: '图片预览：角色动作首帧',
|
||||
});
|
||||
await user.click(
|
||||
await within(dialog).findByRole('button', {
|
||||
name: '暂停角色动作',
|
||||
}),
|
||||
);
|
||||
await waitFor(() => {
|
||||
expect(image.getAttribute('src')).toBe(
|
||||
'https://signed.example.com/character-animation-frame00.png',
|
||||
expect(
|
||||
dialog.querySelectorAll('.admin-asset-query-sequence-frame'),
|
||||
).toHaveLength(3);
|
||||
});
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame00.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame01.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame02.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
expect(getAdminAssetReadUrl).not.toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame03.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
|
||||
const failedFrame = dialog.querySelector(
|
||||
'.admin-asset-query-sequence-frame',
|
||||
) as HTMLImageElement;
|
||||
fireEvent.error(failedFrame);
|
||||
expect(await within(dialog).findByText('1 帧加载失败')).toBeTruthy();
|
||||
await waitFor(() => {
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated-animations/editor/source-1/task-1/frame03.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
});
|
||||
const callsBeforeRetry = vi.mocked(getAdminAssetReadUrl).mock.calls.length;
|
||||
await user.click(
|
||||
within(dialog).getByRole('button', { name: '重试失败帧' }),
|
||||
);
|
||||
await waitFor(() => {
|
||||
expect(vi.mocked(getAdminAssetReadUrl).mock.calls.length).toBeGreaterThan(
|
||||
callsBeforeRetry,
|
||||
);
|
||||
});
|
||||
expect(within(dialog).queryByLabelText('视频预览：角色动作首帧')).toBeNull();
|
||||
expect(
|
||||
within(dialog).getByRole('button', { name: '暂停角色动作' }),
|
||||
).toBeTruthy();
|
||||
});
|
||||
|
||||
test('后台素材查询音频素材使用统一封面缩略图', async () => {
|
||||
|
||||
@@ -318,6 +318,101 @@ test('后台精选审核缩略图进入视口后换签并可打开图片预览',
|
||||
expect(screen.queryByRole('dialog', { name: '精选素材详情' })).toBeNull();
|
||||
});
|
||||
|
||||
test('后台精选审核在共用预览弹窗播放完整角色动作', async () => {
|
||||
vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
|
||||
entries: [
|
||||
{
|
||||
...pendingShowcaseAsset,
|
||||
label: '待机动作',
|
||||
assetKind: 'character-animation',
|
||||
imageSrc: '/generated/action/frame-01.png',
|
||||
objectKey: 'generated/action/frame-01.png',
|
||||
imageSequenceFrames: [
|
||||
{
|
||||
imageSrc: '/generated/action/frame-01.png',
|
||||
objectKey: 'generated/action/frame-01.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
{
|
||||
imageSrc: '/generated/action/frame-02.png',
|
||||
objectKey: 'generated/action/frame-02.png',
|
||||
width: 192,
|
||||
height: 256,
|
||||
},
|
||||
],
|
||||
imageSequenceDurationMs: 250,
|
||||
},
|
||||
],
|
||||
nextCursor: null,
|
||||
});
|
||||
vi.mocked(getAdminAssetReadUrl).mockImplementation(
|
||||
async (_token, request) => {
|
||||
const objectKey = request.objectKey ?? undefined;
|
||||
return {
|
||||
read: {
|
||||
objectKey,
|
||||
signedUrl: `https://signed.example.com/${objectKey ?? ''}`,
|
||||
expiresAt: '2099-01-01T00:05:00Z',
|
||||
},
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(
|
||||
<AdminEditorShowcaseReviewPage
|
||||
token="admin-token"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
fireEvent.click(await screen.findByTitle('预览素材'));
|
||||
|
||||
const dialog = await screen.findByRole('dialog', { name: '素材预览' });
|
||||
expect(
|
||||
await within(dialog).findByRole('button', { name: '暂停角色动作' }),
|
||||
).toBeTruthy();
|
||||
await waitFor(() => {
|
||||
expect(
|
||||
dialog.querySelectorAll('.admin-asset-query-sequence-frame'),
|
||||
).toHaveLength(2);
|
||||
});
|
||||
expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
|
||||
objectKey: 'generated/action/frame-02.png',
|
||||
expireSeconds: 300,
|
||||
});
|
||||
});
|
||||
|
||||
test('后台精选审核对损坏角色动作显示错误而不回退首帧', async () => {
|
||||
vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
|
||||
entries: [
|
||||
{
|
||||
...pendingShowcaseAsset,
|
||||
label: '损坏动作',
|
||||
assetKind: 'character-animation',
|
||||
imageSequenceFrames: null,
|
||||
imageSequenceDurationMs: null,
|
||||
},
|
||||
],
|
||||
nextCursor: null,
|
||||
});
|
||||
|
||||
render(
|
||||
<AdminEditorShowcaseReviewPage
|
||||
token="admin-token"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
fireEvent.click(await screen.findByTitle('预览素材'));
|
||||
|
||||
const dialog = await screen.findByRole('dialog', { name: '素材预览' });
|
||||
expect(
|
||||
within(dialog).getByLabelText('角色动作序列损坏：损坏动作'),
|
||||
).toBeTruthy();
|
||||
expect(
|
||||
within(dialog).queryByRole('img', { name: '图片预览：损坏动作' }),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
test('后台精选审核将无 objectKey 的绝对 OSS 图片地址换签后预览', async () => {
|
||||
vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
|
||||
entries: [
|
||||
|
||||
@@ -1703,6 +1703,58 @@ button:disabled {
|
||||
object-fit: contain;
|
||||
}
|
||||
|
||||
.admin-asset-query-sequence-preview {
|
||||
position: relative;
|
||||
width: min(100%, 720px);
|
||||
min-height: min(64dvh, 560px);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.admin-asset-query-sequence-frame {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
display: block;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
object-fit: contain;
|
||||
object-position: center;
|
||||
}
|
||||
|
||||
.admin-asset-query-sequence-controls {
|
||||
position: absolute;
|
||||
right: 12px;
|
||||
bottom: 12px;
|
||||
z-index: 2;
|
||||
display: flex;
|
||||
max-width: calc(100% - 24px);
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
border-radius: 999px;
|
||||
background: rgba(43, 31, 22, 0.82);
|
||||
color: #fff;
|
||||
padding: 6px 10px;
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
.admin-asset-query-sequence-controls button {
|
||||
display: grid;
|
||||
min-width: 44px;
|
||||
min-height: 44px;
|
||||
border: 0;
|
||||
background: transparent;
|
||||
color: inherit;
|
||||
cursor: pointer;
|
||||
padding: 0;
|
||||
place-items: center;
|
||||
}
|
||||
|
||||
.admin-asset-query-sequence-error {
|
||||
display: grid;
|
||||
color: #9d3127;
|
||||
place-items: center;
|
||||
}
|
||||
|
||||
.admin-asset-query-preview-audio {
|
||||
display: grid;
|
||||
justify-items: center;
|
||||
|
||||
@@ -2051,6 +2051,47 @@
|
||||
},
|
||||
"ExternalEditorAssetCreateRequest": {
|
||||
"type": "object",
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"assetKind": {
|
||||
"const": "character-animation"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"assetKind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"required": [
|
||||
"imageSequenceFrames",
|
||||
"imageSequenceDurationMs"
|
||||
],
|
||||
"properties": {
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/ExternalCharacterAnimationGenerationInputs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"else": {
|
||||
"not": {
|
||||
"anyOf": [
|
||||
{
|
||||
"required": [
|
||||
"imageSequenceFrames"
|
||||
]
|
||||
},
|
||||
{
|
||||
"required": [
|
||||
"imageSequenceDurationMs"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"required": [
|
||||
"folderId",
|
||||
"label",
|
||||
@@ -2132,16 +2173,71 @@
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
|
||||
},
|
||||
"imageSequenceFrames": {
|
||||
"type": "array",
|
||||
"minItems": 2,
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorImageSequenceFrame"
|
||||
}
|
||||
},
|
||||
"imageSequenceDurationMs": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
|
||||
},
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/JsonValue"
|
||||
"$ref": "#/components/schemas/JsonValue",
|
||||
"description": "可重放的生成输入。assetKind=character-animation 时不得包含 characterAnimation、frames、previewVideoPath、frameCount、fps 或 durationSeconds 等旧运行字段；正式媒体数据必须写入 imageSequenceFrames 和 imageSequenceDurationMs。服务端会移除 screenColorHex、mattingProvider、mattingModel 等内部处理审计字段。"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"ExternalEditorProjectResourceCreateRequest": {
|
||||
"type": "object",
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"assetKind": {
|
||||
"const": "character-animation"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"assetKind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"required": [
|
||||
"imageSequenceFrames",
|
||||
"imageSequenceDurationMs"
|
||||
],
|
||||
"properties": {
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/ExternalCharacterAnimationGenerationInputs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"else": {
|
||||
"not": {
|
||||
"anyOf": [
|
||||
{
|
||||
"required": [
|
||||
"imageSequenceFrames"
|
||||
]
|
||||
},
|
||||
{
|
||||
"required": [
|
||||
"imageSequenceDurationMs"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"required": [
|
||||
"imageSrc",
|
||||
"width",
|
||||
@@ -2215,14 +2311,71 @@
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
|
||||
},
|
||||
"imageSequenceFrames": {
|
||||
"type": "array",
|
||||
"minItems": 2,
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorImageSequenceFrame"
|
||||
}
|
||||
},
|
||||
"imageSequenceDurationMs": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
|
||||
},
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/JsonValue"
|
||||
"$ref": "#/components/schemas/JsonValue",
|
||||
"description": "可重放的生成输入。assetKind=character-animation 时不得包含 characterAnimation、frames、previewVideoPath、frameCount、fps 或 durationSeconds 等旧运行字段；正式媒体数据必须写入 imageSequenceFrames 和 imageSequenceDurationMs。服务端会移除 screenColorHex、mattingProvider、mattingModel 等内部处理审计字段。"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"ExternalCharacterAnimationGenerationInputs": {
|
||||
"not": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"characterAnimation"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"frames"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"previewVideoPath"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"frameCount"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"fps"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"durationSeconds"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"description": "assetKind=character-animation 时 generationInputs 不得包含旧运行字段；正式媒体数据使用 imageSequenceFrames 和 imageSequenceDurationMs。"
|
||||
},
|
||||
"ExternalEditorAssetUpdateRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2545,7 +2698,19 @@
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
|
||||
},
|
||||
"imageSequenceFrames": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorImageSequenceFrame"
|
||||
}
|
||||
},
|
||||
"imageSequenceDurationMs": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
|
||||
},
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/JsonValue"
|
||||
@@ -2688,6 +2853,18 @@
|
||||
"sourceType": {
|
||||
"type": "string"
|
||||
},
|
||||
"imageSequenceFrames": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorImageSequenceFrame"
|
||||
},
|
||||
"description": "assetKind=character-animation 时的完整可播放帧集合。"
|
||||
},
|
||||
"imageSequenceDurationMs": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
|
||||
},
|
||||
"prompt": {
|
||||
"type": [
|
||||
"string",
|
||||
@@ -2716,7 +2893,8 @@
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
|
||||
},
|
||||
"generationInputs": {
|
||||
"$ref": "#/components/schemas/JsonValue"
|
||||
@@ -3852,7 +4030,7 @@
|
||||
"string",
|
||||
"null"
|
||||
],
|
||||
"description": "角色动作绿幕预览视频写入账号素材库的文件夹；省略时写入默认项目素材文件夹。"
|
||||
"description": "角色动作预览视频和最终透明序列帧素材写入账号素材库的文件夹；省略时写入默认项目素材文件夹。"
|
||||
},
|
||||
"assetLabel": {
|
||||
"type": [
|
||||
@@ -3865,22 +4043,29 @@
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"EditorCharacterAnimationFrame": {
|
||||
"EditorImageSequenceFrame": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"frameIndex",
|
||||
"imageSrc",
|
||||
"objectKey",
|
||||
"assetObjectId",
|
||||
"width",
|
||||
"height"
|
||||
],
|
||||
"properties": {
|
||||
"frameIndex": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"imageSrc": {
|
||||
"type": "string"
|
||||
},
|
||||
"objectKey": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "帧对应的稳定 OSS Object Key；服务端据此重建持久 imageSrc，不能只提交临时签名 URL。"
|
||||
},
|
||||
"assetObjectId": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "帧对应的稳定资产对象 ID。"
|
||||
},
|
||||
"width": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
@@ -3889,7 +4074,9 @@
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"description": "图片序列帧。数组位置是唯一播放顺序，不携带额外序号字段；每帧必须同时携带 objectKey 与 assetObjectId，imageSrc 按 objectKey 规范化为持久站内路径。"
|
||||
},
|
||||
"EditorCharacterAnimationGenerationResponse": {
|
||||
"type": "object",
|
||||
@@ -3926,7 +4113,7 @@
|
||||
"frames": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorCharacterAnimationFrame"
|
||||
"$ref": "#/components/schemas/EditorImageSequenceFrame"
|
||||
}
|
||||
},
|
||||
"frameCount": {
|
||||
@@ -3964,6 +4151,28 @@
|
||||
],
|
||||
"description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
|
||||
},
|
||||
"resource": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/EditorProjectResource"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "最终透明角色动作对应的项目资源。携带 projectId 时，画布图层必须直接引用其 resourceId，不得再次创建重复资源。"
|
||||
},
|
||||
"asset": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/EditorAsset"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "最终透明角色动作素材。assetKind 为 character-animation，并直接包含序列帧字段。"
|
||||
},
|
||||
"queueState": {
|
||||
"anyOf": [
|
||||
{
|
||||
|
||||
@@ -5946,6 +5946,21 @@
|
||||
- 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。
|
||||
- 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。
|
||||
|
||||
## 2026-07-28 编辑器媒体类型统一由 assetKind 判定
|
||||
|
||||
- 决策：`assetKind` 是编辑器资源和素材唯一权威媒体类别；不新增或返回 `mediaType`。`character-animation` 渲染为序列帧，`video` 渲染为视频，`audio/sound-effect/background-music` 渲染为音频，其余类别渲染为图片。前端内部可保留派生的 `CanvasMediaType` 选择渲染器，但不能把它作为后端事实。
|
||||
- 持久化边界：`editor_project_resource` 与 `editor_asset` 表尾只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，默认均为 `None`；`editor_showcase_asset` 作为提交时冻结的审核与公开快照，同样在表尾保存这两个字段并从账号素材逐字段复制，旧行默认均为 `None`。正式帧对象和角色动作生成响应都不保存或返回 `frameIndex`，数组位置是唯一播放顺序；帧数取数组长度，FPS 由帧数和毫秒时长即时推导，不持久化 `frame_count`、`fps` 或通用 `duration_seconds`。后端处理抽帧和逐帧去背时仍保留内部 `frame_index`，仅用于乱序并发收口、OSS 命名、日志和错误定位；仓库内旧 helper 同步升级，不为它保留外部兼容字段。
|
||||
- 时长口径：`image_sequence_duration_ms` 只表示角色图片序列完整播放一次的毫秒时长，与音频 / 视频生成请求中的 `durationSeconds` 完全分离。角色动作与视频生成响应仍可携带各自既有的请求 / 结果级 `frameCount/fps/durationSeconds`；通用音视频秒数不进入资源 / 素材正式列、`EditorAsset`、`CanvasLayer` 或画布 layout，只允许把上传探测值或生成请求值格式化为用户可见字符串后写入 `generation_inputs_json.fields[]` 供素材详情展示。素材详情和画布 ZIP 用户可见元数据只透传实际存在的 `fields[]` 时长项；缺少时直接省略，不生成 `--:--` 占位。素材放置与工程恢复不做媒体探测，也不从 layout / resource 回退；音频播放只使用媒体 `loadedmetadata.duration`。不得为音频生成响应新增 `durationSeconds`，也不得把音视频秒数写入图片序列字段。前端角色动作播放器使用 `imageSequenceDurationMs / imageSequenceFrames.length`，Spine 导出时才换算秒数并推导 FPS。
|
||||
- 写入与复用边界：`assetKind=character-animation` 必须在 SpacetimeDB storage/procedure 边界同时提供至少两帧有效数组与大于 0 的图片序列毫秒时长；其他类别不得携带图片序列字段。同项目同源同媒体资源只允许 `None → Some` 单调回填，非空冲突失败关闭，延迟重试的 `updated_at` 取请求时间与既有时间的较大值。
|
||||
- 生成关联边界：角色动作生成响应同时返回已经持久化的最终 `resource` / `asset`；带项目上下文时前端结果图层必须直接使用 `resource.resourceId` 及其预览视频来源血缘，缺少 resource 直接失败。无项目放置也必须绑定响应中的正式账号素材，不能从响应 `frames` 构造无资产真相的本地动作结果。“动作（原始视频）”只是 `asset_kind = video` 的 provider 中间产物，其 `editor_project_resource` 与 `editor_asset` 两行都固定 `generation_inputs_json = NULL`，不得携带引用或开放参数复用；完整用户生成配方只保存在最终 `asset_kind = character-animation` 的序列资源 / 素材。角色动作规范化迁移对权威证明的 preview video 同样清空整份生成输入，但不改写其 `source_resource_id`。
|
||||
- repair 幂等边界：legacy 音频 repair 不再派生或回填任何资源级通用时长，因此新列上线前已完成 repair 的重放继续按原字段精确匹配；图片序列字段在音频行上均为 `None`。
|
||||
- 布局边界：`editor_project_resource` 的正式字段是角色动作唯一媒体真相；动作 layout 只保存资源引用和 placement，不保存帧、时长、预览、生成输入、资源元数据或顶层 `mediaType`。前端仍可从 `assetKind` 派生内部 `CanvasMediaType`，但后端响应清洗不得把普通 layer 的旧 `mediaType` 传回前端，也不得递归删除 `generationInputs.references[*].mediaType`。
|
||||
- 迁移边界（2026-08-04 收口）：存量 `generation_inputs_json.characterAnimation`、已证明动作行的 helper 顶层 `frames/previewVideoPath/frameCount/fps/durationSeconds`、`screenColorHex`、正式帧 `frameIndex`、误标预览 MP4 和动作 layout 副本，由 `normalize_editor_character_animation_metadata_and_return` 按 `asset → project-resource → showcase → canvas` 一次性规范化。顶层字段只有先证明动作身份后才解释；普通图片 / 视频任意 JSON 中的同名字段不动。canvas dry-run 可消费前置 scope 的计划态结果，但 apply 仍要求前置 scope 已物理完成；同 task 候选先按权威对象规划分类并排除预览视频，只有唯一最终图片序列可补建资源。正式序列每帧必须按首帧 bucket 的稳定路径精确匹配同 owner / task 的图片 `editor_character_animation` 对象并补齐 `objectKey/assetObjectId`。迁移永不验证 layout 复制的 `sourceResourceId`，补建资源采用最终素材的 DB 血缘；新生成直接来源链仍严格校验。正式/旧版冲突、最终候选为零或多个、对象不匹配形成 blocker；apply 必须绑定同批 dry-run SHA-256，结束后全量复核零匹配、零 blocker。迁移完成后删除 api-server、admin、Web 与 helper 的 action fallback。
|
||||
- 新写入边界：`assetKind=character-animation` 的 `generationInputs` 若含旧运行字段或 `screenColorHex`，正式帧若含 `frameIndex`，api-server 和 SpacetimeDB storage 均失败关闭；门禁只对角色动作生效，不误伤其它素材的任意 generation input JSON。
|
||||
- 交互边界：角色动作素材下载导出完整序列 ZIP；点击、HTML5 拖放和指针拖放创建可移动、循环播放且可保存恢复的序列图层。`assetKind=character-animation` 但缺少有效帧时按损坏素材失败关闭，不回退首帧 PNG。
|
||||
- 精选展示边界：`/creation` 精选卡片和预览弹窗继续扩展各自现有媒体 renderer，不复用或重构画布图层组件；卡片静止时只读取首帧，hover / focus 后才加载并播放完整序列，预览弹窗提供播放暂停。后台素材查询与精选审核继续共用 `AdminEditorAssetMedia`，列表只读首帧，预览弹窗才逐帧使用管理员换签。两端均按 `imageSequenceDurationMs / imageSequenceFrames.length` 切帧，下一帧未就绪时保留上一帧且禁止淡入；损坏动作不退回普通图片。
|
||||
- 精选帧授权边界：公开换签只对当前已通过、已展示、返还完成且未删除的精选动作，按同 owner 的冻结帧 `assetObjectId` / `objectKey` 形成 exact grant；不从 `imageSrc` 或前缀推导。隐藏、拒绝、删除或快照损坏后逐帧授权随当前事务真相撤销，`read-url` 与 `read-bytes` 继续共用该判断。
|
||||
|
||||
## 2026-07-24 后台用户详情展示历史花费泥点
|
||||
|
||||
- 口径：`historicalConsumedPoints` 表示用户历史总消费，只累计 `profile_wallet_ledger.source_type = asset_operation_consume` 且 `amount_delta < 0` 的绝对值；`asset_operation_refund` 不冲减，充值退款追回、余额重置、赠送和退款 hold 均不计入。
|
||||
@@ -6450,6 +6465,8 @@
|
||||
- local 状态：`local-*` 只是 ID 形状，不能直接解释为“素材仍在保存”。新上传 / 新生成素材是否 pending 取资源登记在途状态；严格满足兼容谓词的历史自包含本地角色动作序列是持久化终态，不得误报等待。若当前版本尚不能复制这类序列，以准确原因失败关闭；既非 pending 又不满足历史谓词的 unresolved local 图层也失败关闭，但不得承诺稍后一定自动恢复。layout PATCH pending 不参与资源登记判断，系统剪贴板图片导入不受影响。
|
||||
- schema 与迁移：在现有 `EditorCanvasLayer` 结构体末尾追加 `#[default(None::<String>)] asset_kind_override: Option<String>`，不删除、改名、重排或改类型。legacy 图层类型与资源默认相同则迁移为 `None`，不同则迁移为 override；资源无默认值时只有全部引用图层显式同值才补资源默认，否则保留各自 override；自包含历史序列的显式类型迁入 override，不伪造资源。同步 `migration.rs`、表目录 / 数据契约、生成 bindings、HTTP DTO 与结构化 canonical hash，并运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`。
|
||||
- 并发边界：未登记图层被禁止复制后，不再按临时资源 ID 合并项目资源创建请求，也不再用一次响应批量改写共享临时 ID。每个合法新增图层保留自己的响应快照与回调；layout PATCH 的串行 latest-wins 队列、共享资源的多布局引用和 session 资源快照按 `resourceId` 去重继续保留，它们与资源创建 single-flight 是不同机制。
|
||||
- 媒体兼容边界：override 只允许在资源默认类型的同一媒体族内变化。动作、视频各自独立成族，`audio/sound-effect/background-music` 同属音频族，其余类型与空默认值同属图片族。前端菜单禁用跨族标签且更新入口重复校验；后端对每个结构化图层按资源完整校验，跨族值清空后回退资源默认类型，不因该兼容错误拒绝整个保存。
|
||||
- 历史恢复：客户端读取到已持久化的跨族 override 时必须保留图层、回退资源默认类型、显示明确提示并自动提交清理后的布局；不得再用 `hydrateLayer() -> null -> filter(Boolean)` 静默隐藏持久层仍存在的图层。修复保存只替换命中图层的规范化布局项，其他尚不能 hydrate 的历史项原样保留，避免修复一个标签时顺带删除无关数据。
|
||||
|
||||
## 2026-08-03 Agent Runtime 原生工具合同本地失败关闭
|
||||
|
||||
|
||||
@@ -4033,6 +4033,34 @@
|
||||
- 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
|
||||
- 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
|
||||
|
||||
## 角色动作不能靠素材主图或通用生成输入恢复
|
||||
|
||||
- 现象：角色动作在整画布导出时正常，但从素材库单项下载只得到第一帧 PNG，拖回画布也成为普通静态图片。
|
||||
- 原因：`editor_asset.image_src` 只指向首帧；若 worker 把完整帧集塞进 `generation_inputs_json`，素材 DTO、用户输入清洗或画布布局任一层丢字段，就会退化成 PNG。再增加一个 `mediaType` 只能掩盖结果字段没有落到正式资源的问题。
|
||||
- 处理：worker 只把完整帧集与图片序列毫秒时长写入 `editor_project_resource` / `editor_asset` 的 `image_sequence_frames_json`、`image_sequence_duration_ms`；数组位置是唯一帧序，不保存 `frameIndex`，帧数和 FPS 均按需派生。`assetKind=character-animation` 决定序列渲染。素材映射、单项下载和拖回画布只读取这两个正式字段，项目 resource 在保存 / 刷新后继续作为主真相；动作 layout 只保留资源引用和 placement，不再复制正式媒体结果。账号素材提交精选审核时，`editor_showcase_asset` 必须冻结复制相同字段，公开 read model 只返回正式字段。外部 helper 只调用一次动作生成接口并直接使用响应 `resource` / `asset`。
|
||||
- 画布回填：角色动作会形成“原角色资源 → 预览视频资源 → 最终序列资源”的血缘链。生成响应必须返回已经持久化的最终 resource，前端图层直接使用其 `resourceId`；不能继续构造 `local-resource-character-animation-*`，否则 `appendCanvasLayersWithResources` 会再次创建重复资源。新图层的 `sourceResourceId` 同时使用最终 resource 的直接来源（预览视频 resource），不能继续沿用请求中的原角色 resource；否则结构化保存会在已生成并计费后因血缘不一致而拒绝。修复时只替换资源关联与血缘字段，不要顺带把动作图层显示尺寸从生成占位尺寸改成原始帧分辨率。
|
||||
- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。同一 task 可能同时存在误标为动作的预览 MP4 和最终首帧 PNG，候选查找必须先按权威对象类型做计划态分类，排除视频并要求唯一正式图片序列，不能按原始 `assetKind` 计数。账号素材仍有旧帧、但后来拖入画布的 project-resource 只剩清洗后 `fields/references` 时，project-resource dry-run 必须按同 owner / task / 首帧对象精确消费 asset 计划态结果；apply 仍要求前置 asset scope 已物理完成。canvas 判断已有 resource 是否为动作时也必须消费 project-resource 的计划态类型：旧库误标为动作、但权威对象证明为 preview MP4 且 layout 本身是 video 的图层直接跳过动作清理；layout 明确为 `image-sequence` 却指向该视频时继续形成 blocker，资源规划本身有 blocker 时也不得静默跳过。正式序列还要逐帧用稳定对象路径匹配同 owner / task 的已登记图片对象并补齐 `objectKey/assetObjectId`。迁移不得验证 layout 复制的 `sourceResourceId`：历史 layer 可能仍指向原角色，而最终素材已指向预览资源；清理副本后采用最终素材的 DB 血缘即可，新生成链路仍保持严格校验。正式与旧版结果冲突、候选为零或多个均形成 blocker；脚本诊断应直接打印 scope、ID、原因、owner/project/task、对象身份和来源资源，不能只报 blocker ID。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。
|
||||
- 新写入与验证：动作 `generationInputs` 出现 `characterAnimation/frames/previewVideoPath/frameCount/fps/durationSeconds/screenColorHex`，或正式帧出现 `frameIndex`，HTTP 与 storage 双层拒绝；其它 asset kind 的任意 JSON 不受该动作门禁影响。测试覆盖两种历史 JSON、无关顶层同名字段、正式/旧版相等与冲突、可选帧引用合并、screen color 和 frameIndex 清理、预览 MP4 重分类、幂等、blocker/hash apply、画布 placement 清理/资源补建、正式字段缺失失败关闭和 helper 单请求。
|
||||
|
||||
## 图片序列时长不要复用通用媒体秒数
|
||||
|
||||
- 现象：把角色动作、视频、音频和上传媒体都写进通用 `duration_seconds`，随后又尝试用持久化 `frame_count/fps/duration_seconds` 互相校验，造成取整口径、生成参数和实际播放时长彼此污染。
|
||||
- 原因：角色动作需要的是一组图片完整播放一次的精确时长；视频 / 音频的 `durationSeconds` 是生成请求或临时运行态参数。帧数已经由数组长度唯一确定，FPS 也可按需要推导，无需维护三份可冲突真相。
|
||||
- 处理：资源 / 素材只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，精选审核快照只冻结复制这两个正式字段。角色动作要求至少两帧且毫秒时长大于 0；播放器按 `时长毫秒 / 数组长度` 计算间隔，Spine 导出时再换算秒数并推导 FPS。音频 / 视频 `durationSeconds` 不映射到这两个字段。
|
||||
- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`。
|
||||
|
||||
## 精选角色动作显示首帧还要检查前端 renderer 与逐帧授权
|
||||
|
||||
- 现象：精选接口已经返回 `imageSequenceFrames` 和正确的 5 / 6 秒成本，但创作主页或后台审核仍只显示首帧；接入播放器后又可能只有第一帧成功、后续帧换签返回 404。
|
||||
- 原因：快照字段、展示 renderer 和私有对象授权是三道独立边界。公开 `imageSrc/objectKey` 只代表首帧，不能让前端自动获得完整帧集；顶层精选 exact grant 也不会自动覆盖其它帧对象。
|
||||
- 处理：公开精选模型必须把 `assetKind=character-animation` 映射到序列 renderer，并携带完整帧与毫秒时长；后台素材查询和精选审核共同透传同一字段并复用 `AdminEditorAssetMedia`。生成端不能在 `ProcessedEditorCharacterAnimationFrame → EditorCharacterAnimationFramePayload` 收口时丢弃逐帧 `assetObjectId/objectKey`，正式序列 JSON 必须保留已确认对象的稳定引用。公开授权在 SpacetimeDB 同一事务快照中只按有效精选动作的同 owner 逐帧 `assetObjectId/objectKey` 匹配，不能放宽 generated 前缀。列表未交互时只读首帧，打开或激活动作预览后也只挂载当前帧和有界预读窗口，避免再次制造换签突发；单帧换签或解码失败时跳过该帧、暂停全帧失败的序列并提供显式重试，不能长期显示空白或旧帧。卡片 hover 与 focus 分别跟踪，只要任一状态仍成立就继续播放，系统请求 `prefers-reduced-motion` 时卡片和弹窗默认暂停，用户仍可在弹窗中手动播放。
|
||||
- 验证：模型 / 组件测试覆盖 4 / 5 / 6 秒动作、损坏序列不回退 PNG、后台两页共用播放器和未激活列表不逐帧请求；SpacetimeDB 测试覆盖主对象、每帧对象、无关对象、跨 owner 与取消展示后的授权撤销。真实浏览器和端到端验收由人工单独执行，不把 unit / component 结果写成 E2E PASS。
|
||||
|
||||
## 可复用资源回填必须保持时间戳单调
|
||||
|
||||
- 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。
|
||||
- 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。
|
||||
|
||||
## 历史钱包消费不能从最近流水或通用订单快照推算
|
||||
|
||||
- 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
- 中央画布支持背景拖拽平移、滚轮二维平移、`Ctrl / Cmd + 滚轮` 缩放、缩放百分比菜单、显示所有元素和固定比例缩放。
|
||||
- 画布左下角提供 Lovart 式状态控件：背景色圆点、素材 / 图层入口、小地图开关；小地图显示图层缩略分布和当前视口框，点击小地图执行显示所有元素。
|
||||
- 画布 chrome 的边框、hover / 选中态、吸附 / 框选参考线、生成类按钮和通用 active 控件使用陶泥儿暖色主题（以 `--platform-accent`、陶土橙主按钮和深棕文字为基准），不得回退为黑色或蓝色主题；元素类型自身的识别色可继续保留。
|
||||
- 画布中的图片可展示、悬浮显示图片 Resolution 尺寸与边框，点击后在图片上方显示浮动工具栏；浮动工具栏只保留当前可执行的编辑动作，不放调整 / 复制 / 删除 / 查看信息占位按钮。图片右上角素材类型标签、图片信息角标和悬浮尺寸标签在画布缩小时必须按 viewport 反向缩放，保持屏幕可读尺寸。素材类型采用双层语义：`editor_project_resource.asset_kind` 是跨布局共享的资源默认类型，`editor_canvas_layer.asset_kind_override` 是当前布局实例可空的覆盖值，显示与功能判断统一使用 `effectiveAssetKind = assetKindOverride ?? resource.assetKind`；两层都为空时显示 `未知`。点击标签只修改或清除当前图层的 `assetKindOverride`，不能创建新资源、替换 `resourceId` 或修改其他引用同一资源的图层；清除覆盖后立即恢复继承资源默认类型，也不能触发图层选择 / 拖拽事件。图片信息角标使用圆形 `i` 图标，不使用中括号或花括号样式。图片不再维护独立展示 `Size` 字段，画布显示宽高统一取 `originalWidth/originalHeight`（图片信息中的 `Resolution`）。
|
||||
- 画布中的图片可展示、悬浮显示图片 Resolution 尺寸与边框，点击后在图片上方显示浮动工具栏；浮动工具栏只保留当前可执行的编辑动作，不放调整 / 复制 / 删除 / 查看信息占位按钮。图片右上角素材类型标签、图片信息角标和悬浮尺寸标签在画布缩小时必须按 viewport 反向缩放，保持屏幕可读尺寸。素材类型采用双层语义：`editor_project_resource.asset_kind` 是跨布局共享的资源默认类型，`editor_canvas_layer.asset_kind_override` 是当前布局实例可空的覆盖值，显示与功能判断统一使用 `effectiveAssetKind = assetKindOverride ?? resource.assetKind`；两层都为空时显示 `未知`。点击标签只修改或清除当前图层的 `assetKindOverride`，不能创建新资源、替换 `resourceId` 或修改其他引用同一资源的图层；清除覆盖后立即恢复继承资源默认类型，也不能触发图层选择 / 拖拽事件。标签覆盖必须与资源默认类型属于同一媒体族：`character-animation` 独立为动作族，`video` 独立为视频族，`audio/sound-effect/background-music` 属于音频族，其余类型和空默认值属于图片族；标签菜单禁用跨族选项，更新回调再次校验。加载到历史跨族 override 时不得静默过滤图层，必须清除内存 override、按资源默认类型恢复图层、向用户提示并排队修复保存。图片信息角标使用圆形 `i` 图标，不使用中括号或花括号样式。图片不再维护独立展示 `Size` 字段，画布显示宽高统一取 `originalWidth/originalHeight`（图片信息中的 `Resolution`）。
|
||||
- 默认工具为选择模式；底部工具栏采用 AI 画布工作流工具组：选择、抓手、上传、生成图片、生成视频、生成音乐、生成规范、生成角色形象、生成图标素材、生成 UI 设计图。底部栏不再展示文字工具、形状标注工具和导出工具；上传与生成图片之间、生成音乐与生成规范之间各有一个半图标高度分割线。
|
||||
- 鼠标中键拖拽始终平移画布；长按 Space 临时进入抓手模式，松开后恢复原工具。
|
||||
- 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层、生成占位框或画板的边缘与中心线；当移动元素接近两个同轴元素形成的等距位置时，支持横向或纵向等距吸附。
|
||||
@@ -197,7 +197,8 @@
|
||||
- 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入“上传素材”并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入“上传素材”并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；上传视频同样在创建素材和图层前读取视频 metadata 宽高，保证单层下载或 ZIP 导出的真实视频文件重新导入后仍按文件自身尺寸入画布；仅在无法解析尺寸时才使用对应媒体兜底尺寸。OSS 直传确认成功后，即时占位素材、即时画布图层和补充图片尺寸探测必须使用本次换签得到的 signed URL，不得把私有对象的裸 `/generated-*` 兼容路径交给浏览器读取；账号素材持久化仍只写 `legacyPublicPath`、`objectKey` 和 `assetObjectId`，禁止把会过期的 signed URL 写入资源或素材记录。
|
||||
- 音频 / 视频素材卡和画布媒体图层必须提供稳定的非文字视觉预览：优先使用 `thumbnailSrc` / 视频 `poster`，没有真实首帧或音频封面时使用由媒体类型、素材名和地址派生的确定性视觉底图。视频图层使用原生 `<video controls preload="metadata" playsInline>` 播放，外层图层仍承接选择和拖拽语义；音频图层播放前继续通过 `/api/assets/read-url` 换签。画布素材导出按 `mediaType` 保留真实媒体格式：图片进入 `images/`，音频 / 视频进入 `media/`，文件扩展名从响应 MIME、`objectKey` 或源 URL 推断，不得把音频 / 视频导出成 PNG。
|
||||
- 画布素材 ZIP 的 `metadata.json` 只保存前端信息弹窗和导出文件列表可见的展示快照：项目标题、导出时间、图层标题、文件路径、类型、生成输入、模型显示名、Task 短 ID、Object 显示值、Resolution / 时长和导出错误。导出的生成输入只保留用户实际填写或选择的内容；系统默认兜底提示词、固定工作流提示词、内置图标描述、UI 提取素材固定提示词等内置提示词即使存在于历史 `generationInputs`，也不得写入导出元数据。不得把 `projectId`、`layerId`、`resourceId`、`sourceAssetId`、`sourceResourceId`、原始 `prompt` / `actualPrompt` / `provider` 或画布坐标、锁定、隐藏等布局状态写入导出元数据；Object 字段仅沿用信息弹窗当前可见值。
|
||||
- `生成角色动作` 的完成结果按序列帧素材处理：图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。下载和 ZIP 导出必须因此得到序列帧 ZIP / frames 目录，不能回退为预览视频或首帧 PNG；后端抽帧后逐帧保存带绿幕源图，上传时消费并释放原帧字节，再用该对象的 600 秒 OSS URL 完成透明化并落盘透明帧素材。
|
||||
- `生成角色动作` 的完成结果按序列帧素材处理：`assetKind` 固定为 `character-animation`，图层主 `src` 使用首帧，前端内部据 `assetKind` 派生 `CanvasMediaType="image-sequence"` 选择播放器。`previewVideoPath` 只作为上游来源，不作为画布主媒体。下载和 ZIP 导出必须得到序列帧 ZIP / frames 目录，不能回退为预览视频或首帧 PNG；后端抽帧后逐帧保存带绿幕源图，上传时消费并释放原帧字节，再用该对象的 600 秒 OSS URL 完成透明化并落盘透明帧素材。
|
||||
- 素材库和项目资源 API 不返回独立 `mediaType`；前端只按 `assetKind` 映射渲染器：`character-animation → image-sequence`、`video → video`、`audio/sound-effect/background-music → audio`、其余 → image，不按扩展名猜类型。最终动作 asset / resource 平铺返回 `imageSequenceFrames/imageSequenceDurationMs`；正式帧对象不含 `frameIndex`，数组位置是唯一播放顺序，帧数取数组长度，FPS 按帧数与毫秒时长即时推导。只有至少两帧且播放时长大于 0 的角色动作素材才能进入序列播放器，否则按损坏素材失败关闭。预览视频作为独立 `assetKind=video` 资源保存，最终动作以 `sourceResourceId` 保留来源关系，不重复保存路径。从素材库点击、HTML5 拖放或指针拖放到画布时必须复制完整字段并先创建正式 project resource；新 layout 只保存 resource 引用和几何，不保存帧集或预览视频，刷新后从 project resource 恢复循环播放。历史 `local-*` 自包含动作布局仍可读取。
|
||||
- 素材面板支持按素材名、文件夹名、生成信息、用户可见模型、任务和媒体类型搜索，并支持选择模式框选，一次选中多个素材，并可批量移动或删除上传素材。Provider 与 `isEditorInternalProcessingModel(...)` 识别的内部处理模型不得进入搜索索引，避免出现隐藏字段可命中或命中但无可见匹配字段；原始审计元数据只保留给服务端和后台管理读取，普通用户（包括素材 owner）不得通过响应取得。
|
||||
- 图层面板支持按图层名、生成信息、用户可见模型、任务和媒体类型搜索；Provider 与内部处理模型同样不得进入搜索索引。普通用户图层快照也不得携带这些内部字段。支持选择多个图层后创建图层组，组名和 groupId 随画布布局保存。
|
||||
- 小地图支持拖拽视口框，拖动时画布 viewport 跟随移动；`pointermove` 更新必须通过 `requestAnimationFrame` 合帧，结束拖拽时 flush 最后一帧，避免高频 pointermove 直接压垮 React 渲染和项目持久化链路。
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -56,6 +56,8 @@ v1 只开放以下能力：
|
||||
- `unsupported-image-style`：请求的图片后处理风格未知或不适用于当前生成类型，接口按无风格继续生成。
|
||||
- `multiple-generation-warnings`：同一成功响应合并了不同 `code` 的多条非阻断告警，具体原因按顺序拼接在 `reason`。
|
||||
|
||||
手工调用 `POST /api/external/v1/editor/assets` 或 `POST /api/external/v1/editor/projects/{projectId}/resources` 创建 `assetKind=character-animation` 记录时，`generationInputs` 只保存可重放的生成输入，不接受 `characterAnimation`、`frames`、`previewVideoPath`、`frameCount`、`fps`、`durationSeconds` 等旧运行字段；完整正式帧序列和总时长必须分别写入 `imageSequenceFrames` 与 `imageSequenceDurationMs`。`screenColorHex`、`mattingProvider`、`mattingModel` 属于内部处理审计字段，External v1 会在持久化前移除。角色动作生成接口已经直接返回正式 resource / asset，正常调用方不应再手工复制第一帧创建重复记录。
|
||||
|
||||
provider 原图已保存但透明背景处理最终失败时，worker 保留原图稳定引用，不返回不存在的透明处理图，图标和 UI 也不继续拆分；有 `projectId + canvasCompletion` 时由原图完成画布写回。调用方应展示告警，但不得把 completed 任务改判为失败。该降级只覆盖透明背景处理的最终失败，phase 上报、原图或透明处理图持久化、画布写回失败仍使任务失败。图标 / UI 已成功生成透明图、只有自动拆分失败时继续使用既有 `sliceWarning`。通用 `warning` 与 `sliceWarning` 只在「透明背景最终失败」这一条上互斥；风格归一化或像素规整产生的通用 `warning` 可以与 `sliceWarning` 并存，compact result 不得丢弃任一条。
|
||||
|
||||
## 异步提交、查询与幂等
|
||||
|
||||
@@ -92,6 +92,8 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去
|
||||
|
||||
外部生成任务摘要投影与历史 payload 维护使用 `npm run spacetime:external-generation:maintain -- ...`，且只能由已授权 migration operator 的 SpacetimeDB CLI 登录态执行。脚本默认 dry-run、每次只处理一批，绝不自动循环全表；`--apply` 才写入。先发布包含 `external_generation_job_summary` 与 cursor 索引的 SpacetimeDB 模块，在维护模式内对事故时间以前的编辑器终态任务执行小批 dry-run，例如 `npm run spacetime:external-generation:maintain -- --database <database> --server-url <url> --limit 5 --completed-before-micros <micros>`；核对 `matched_count`、`before_bytes`、`after_bytes` 和 `inline_media_count` 后，保持本批输入 cursor 不变并追加 `--apply` 重跑同一批，即使最后一批 `has_more = false`，只要 dry-run 仍有 `matched_count` / `selected_count` 也必须 apply；只有 apply 成功后才使用它返回的 `next_cursor_job_id` 继续。B-tree cursor 的选择阶段最多反序列化 `limit + 1` 行，apply 会再按主键逐条读取选中行但不会同时保留整批 payload；如怀疑存在单行异常巨型历史 JSON，先用 `--limit 1`。payload 压缩硬限制 `source_module = editor-canvas`；终态压缩完成后，用 `--backfill-summaries` 先 dry-run、再 `--apply` 分批补齐仍缺失的活动任务或无内联媒体历史任务摘要，直到 `has_more = false`，最后再切换使用 summary procedure 的 api-server。Stdb 构建 artifact 和完整 release 包都必须包含 `scripts/spacetime-maintain-external-generation-jobs.mjs` 与 `scripts/spacetime-migration-common.mjs`。首次上线不得让 Full Build 从 Stdb 自动直落 API：`STDB_API_ROLLOUT_MODE` 默认 fail-closed 为 `pause-after-stdb`，必须填写受限的 `STDB_API_ROLLOUT_APPROVERS`；Stdb Publish 通过 `KEEP_MAINTENANCE_MODE` 保持维护文件并停止旧 API/controller/worker，暂停点最多等待 4 小时，完成上述维护并确认无后续批次后才由指定审批人放行 API。定时构建缺少审批人时必须在发布前失败，不能静默退回 `normal`；也可分开运行 Stdb publish、维护、API deploy 三个受控 Job。任一批次都不得处理 pending / running payload；不要用 runtime writer、bootstrap secret 或匿名 identity 代替 migration operator，也不要在未核对 dry-run 时直接 apply。
|
||||
|
||||
角色动作正式字段收口使用 `node scripts/spacetime-normalize-editor-character-actions.mjs --database <database> --server-url <url>`，且同样只能由已授权 migration operator 执行。必须先发布包含 normalization cursor 索引和 `normalize_editor_character_animation_metadata_and_return` 的 SpacetimeDB 模块，在 API / worker 仍处于维护模式时先运行默认全量 dry-run；脚本固定按 `asset → project-resource → showcase → canvas` 扫描，普通 scope 每批最多 25 行，canvas 每批最多 5 行。全量 dry-run 会在不写库的情况下把 asset 计划结果投影给同 owner / task / 首帧对象精确匹配的 project-resource，再把前置 scope 的计划结果投影给 canvas 检查；因此同 task 的误标预览 MP4 会先按权威视频对象排除，最终图片序列会逐帧核对并补齐精确 `asset_object` 身份。canvas 中仍引用误标 preview resource 的普通 video layer 会按 project-resource 计划态 `video` 跳过，只有 layout 明确声明动作却指向视频，或资源规划本身失败时才形成 blocker。apply 时仍要求前置 scope 已按顺序物理完成，不能跳过 asset 直接让 project-resource 借未落库结果。历史 canvas 复制的 `sourceResourceId` 不是迁移证据，不要因它仍指向原角色而手工改库，补建资源会采用最终账号素材的 DB 血缘。出现 blocker 时脚本会打印 ID、原因、owner、project、task、对象身份和来源资源；先据此区分最终候选为零 / 多个、正式与旧版冲突、帧对象不匹配或缺失资源，不得跳过 scope。确认 dry-run 后追加 `--apply`，脚本会对每批重新 dry-run、携带该批 SHA-256 apply，并在最后从头要求四个 scope 均为零匹配、零 blocker。只有该复核通过后才发布移除 action fallback 的 API / Web。Stdb build artifact 和完整 release 包必须同时包含 `scripts/spacetime-normalize-editor-character-actions.mjs` 与 `scripts/spacetime-migration-common.mjs`。本地切换分支时若要避免 dev publish 因 schema 冲突使用 `-c=on-conflict` 清库，启动命令必须追加 `--preserve-database`，让冲突直接失败。
|
||||
|
||||
自 2026-07-11 起，`Genarrative-Full-Build-And-Deploy` 的每日 04:00 timer 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，不得依赖下游 Job 默认值或提前各自发布；统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。上文“定时构建缺少审批人时失败”的旧口径不再作为当前 dev 定时发布行为。
|
||||
|
||||
Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。该阶段只能通过 `agent none` 和显式 `node(...)` 分配目标机，直接执行 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`；目标机不得 checkout Git、挂载 Git SSH 凭据或依赖 Jenkins workspace 源码。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。
|
||||
@@ -589,7 +591,7 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.
|
||||
|
||||
同一 API release 随包依赖还必须包含 `scripts/check-pingora-release-readiness.mjs` 与 `scripts/check-pingora-canary-live.mjs`。前者在 current release 上以 `--release-runtime-only` 汇总运行时复核，后者支撑目标 Nginx canary live smoke；缺少任一脚本时不能进入直连切换窗口。
|
||||
|
||||
`Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/production-runtime-writer-identity-rotate.mjs`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh`、`scripts/spacetime-migration-common.mjs`、`scripts/spacetime-maintain-external-generation-jobs.mjs`、`scripts/spacetime-migrate-editor-canvas-layout.mjs` 和 `scripts/database-backup-to-oss.mjs`，不得包含 `migration-bootstrap-secret.txt` 或任何原始 bootstrap secret。`Genarrative-Stdb-Module-Build` 只接受 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 指向的受保护 Jenkins Secret File：构建 shell 从临时文件读取原始值，强制校验为 64 位十六进制，计算 SHA-256，随后只通过 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET_SHA256` 注入 Rust 编译；WASM 因而只包含摘要，不包含可下载的原文，Stdb `release-manifest.json` 以 `migration_bootstrap_secret_sha256` 记录该非敏感摘要。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制上述非敏感产物，不在目标机器 checkout Git，并在发布阶段用同一个凭据 ID 再次挂载 Secret File；publish 必须再次校验 64 位十六进制、重算 SHA-256，并与 manifest 的 `migration_bootstrap_secret_sha256` 强制匹配后才可发布。Full Build 必须保证 Stdb Build / Publish 的 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 完全相同并把同一个 ID 同时透传，不能从构建 artifact 传 secret；ID 不同、manifest 缺摘要或摘要不匹配都必须在发布前失败。
|
||||
`Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/production-runtime-writer-identity-rotate.mjs`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh`、`scripts/spacetime-migration-common.mjs`、`scripts/spacetime-maintain-external-generation-jobs.mjs`、`scripts/spacetime-normalize-editor-character-actions.mjs`、`scripts/spacetime-migrate-editor-canvas-layout.mjs` 和 `scripts/database-backup-to-oss.mjs`，不得包含 `migration-bootstrap-secret.txt` 或任何原始 bootstrap secret。`Genarrative-Stdb-Module-Build` 只接受 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 指向的受保护 Jenkins Secret File：构建 shell 从临时文件读取原始值，强制校验为 64 位十六进制，计算 SHA-256，随后只通过 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET_SHA256` 注入 Rust 编译；WASM 因而只包含摘要，不包含可下载的原文，Stdb `release-manifest.json` 以 `migration_bootstrap_secret_sha256` 记录该非敏感摘要。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制上述非敏感产物，不在目标机器 checkout Git，并在发布阶段用同一个凭据 ID 再次挂载 Secret File；publish 必须再次校验 64 位十六进制、重算 SHA-256，并与 manifest 的 `migration_bootstrap_secret_sha256` 强制匹配后才可发布。Full Build 必须保证 Stdb Build / Publish 的 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 完全相同并把同一个 ID 同时透传，不能从构建 artifact 传 secret；ID 不同、manifest 缺摘要或摘要不匹配都必须在发布前失败。
|
||||
|
||||
三个 SCM Jenkinsfile 将 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 默认固定为 `genarrative-spacetime-bootstrap-secret-dev-file`。Secret File 的原文只存在于 Jenkins Credentials；credential ID、参数默认值和定时 / 发布行为以仓库 Jenkinsfile 为事实源，不能只改 Job UI，因为 Declarative Pipeline 下一次载入会重写参数定义。旧 Secret Text `genarrative-spacetime-bootstrap-secret-dev` 继续保留给 Database Import / Export，不得原地改类型或删除。
|
||||
|
||||
|
||||
@@ -163,7 +163,7 @@
|
||||
### Prompt 与生成契约
|
||||
|
||||
- 前端提交到 `POST /api/editor/character-animations/generations`。
|
||||
- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长，并可通过 `assetFolderId` 指定中间视频素材落点。`sourceImageSrc` 只允许传当前账号的 `objectKey`、项目资源 ID 或素材 ID；未持久化的本地临时图片必须先上传 OSS，不能提交 Data URL 或 Blob URL。后端解析稳定引用后必须校验对象属于当前 owner，再读取 OSS 内容。
|
||||
- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长，并可通过 `assetFolderId` 指定中间视频素材落点。携带 `canvasCompletion` 时必须同时提供非空 `projectId`，该校验必须在解析来源、调用 provider、持久化和预扣泥点之前完成，禁止无项目画布完成请求在产生费用或产物后才失败。`sourceImageSrc` 只允许传当前账号的 `objectKey`、项目资源 ID 或素材 ID；未持久化的本地临时图片必须先上传 OSS，不能提交 Data URL 或 Blob URL。后端解析稳定引用后必须校验对象属于当前 owner，再读取 OSS 内容。
|
||||
- 后端使用角色图片作为首帧和尾帧参考，模型固定映射到 `doubao-seedance-2-0-fast-260128`。
|
||||
- 后端在内联执行和队列入队前都会拒绝 Data URL / Blob URL；路由使用默认 JSON body limit，不再为内联图片请求单独放宽。
|
||||
- 后端 prompt 使用以下固定骨架，并把面板输入追加到 `动作描述：` 后：
|
||||
@@ -182,9 +182,11 @@
|
||||
- 后端先计算整批精确采样时刻，再用单个 FFmpeg filter graph 统一解码预览视频并输出 `32 / 40 / 48` 张源帧；不得为每帧重新启动 FFmpeg、重复解码同一视频，也不得用会改变现有尾帧安全时刻的粗粒度 `fps` 抽帧替代。批量命令成功后必须逐一确认全部目标帧文件存在，缺少任一帧都按整批失败处理并保留缺帧编号、目标时刻和输出路径诊断。
|
||||
- 每帧绿幕源图字节由上传 owned 消费（`frame.bytes` 移入 put，上传完成后释放原帧缓冲，不克隆保留）；后续父流程只持 object key，并为每帧向唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，不直接签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。每帧请求分别携带按父剩余绝对预算派生的 `maxQueueWaitMs` 和公式化 `callBudgetMs`；子 worker 在默认 `Q=2048` admission 保险丝和 `Semaphore(N=16)` 约束下排队，取得 provider permit 后才启动调用预算，每次 provider attempt 前重新签发 600 秒 GET URL，multipart 仅传 `image_url`（加 `background_mode=flat`、`seg_model=birefnet`、`cross_check=on` 与同一次生成已选定的 `screenColor`），不传 `file`。真实 provider attempt 按 `N × est × 2` 派生，调用预算按 `2 × attempt + 1s` 派生；冻结 `est=5000ms` 时分别为 `160s / 321s`，排队不侵蚀最多两次顺序 attempt 的完整窗口，`32 / 40 / 48` 帧也不再增加单帧 attempt。成功图片由子 worker 以内部 HTTP 二进制 body 返回父流程，不在子侧落 OSS；BgFilter 最终失败且父业务预算仍有效时，由父流程进入 `阿里云通用抠图（按签名 URL 单独下载）→ 本地 editor_green_screen（再按 object key 独立下载一次并在产出后释放）`。
|
||||
- BgFilter、阿里云或本地键色返回透明结果后，父流程继续通过现有最终帧 finalizer 转为 RGBA8，按宽高比居中放入最终目标尺寸，并使用 `RGBA(0,0,0,0)` 补边；最终帧 OSS 与业务写回仍由父流程完成。上述样例最终输出必须为 `323×480 RGBA8 PNG`，顶部和底部各 `23px` 透明 padding，内容区域完整保留抠图结果。
|
||||
- 全部 `32 / 40 / 48` 帧以覆盖本次所有帧的无序在途集合向内部 worker 提交，允许乱序完成并最终按 `frameIndex` 排序；BgFilter provider 的实际在途请求受唯一 worker 的 `N / Q` 限制。任一帧最终失败时先排空全部已启动 Future，再让整项任务失败退款，不发布缺帧动画。
|
||||
- 全部 `32 / 40 / 48` 帧以覆盖本次所有帧的无序在途集合向内部 worker 提交，允许乱序完成并最终按后端内部 `frame_index` 排序；该索引只服务并发收口、OSS 命名、日志和错误定位，不写入正式 asset / resource 帧对象。BgFilter provider 的实际在途请求受唯一 worker 的 `N / Q` 限制。任一帧最终失败时先排空全部已启动 Future，再让整项任务失败退款，不发布缺帧动画。
|
||||
- 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
|
||||
- 画板前端回填角色动作结果时，必须以 `frames[0].imageSrc` 创建 `mediaType: "image-sequence"`、`assetKind: "character-animation"` 图层，并把完整 `frames` 保存为图层 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。
|
||||
- 角色动作图层在画布中使用序列帧播放器循环展示透明 PNG 帧；刷新恢复时必须继续读取 `imageSequenceFrames`，不能回退到 `<video>` 预览。
|
||||
- 画板前端回填角色动作结果时，以正式 resource / asset 的 `assetKind: "character-animation"` 选择序列帧播放器并以首帧作为图层主图；带项目上下文的生成必须返回正式 project resource，图层直接使用其 `resourceId`。无项目放置只允许绑定响应中的正式账号素材，不从生成结果 `frames` 构造自包含 `local-resource-character-animation-*`；此时图层的 `sourceResourceId` 继续使用正式账号素材记录的直接来源，不回退成请求中的原角色资源。预览视频作为独立 `assetKind: "video"` 资源保存，但不复制进最终动作 layout。
|
||||
- 角色动作图层在画布中循环展示透明 PNG 帧；刷新恢复只从 project resource 的 `imageSequenceFrames/imageSequenceDurationMs` 读取正式结果。动作 layer layout 只保存 `layerId/resourceId` 和几何、层级、可见性等放置信息，不保存 `mediaType`、动作帧、时长、预览、生成输入或资源元数据副本；资源缺字段时按损坏数据失败关闭。
|
||||
- 点击角色动作图层下载时，必须打包下载序列帧 ZIP；画布素材 ZIP 导出时，角色动作写入 `sequences/<编号-标题>/frames/`，而不是导出预览视频。
|
||||
- 角色动作生成 BFF 在同一请求内保存两类账号素材：上游预览 MP4 使用 `assetKind=video` 并承载生成成本，最终透明帧集使用 `assetKind=character-animation` 且派生成本为 0；响应中的 `resource` / `asset` 固定指向最终透明帧集对应的项目资源与账号素材。调用方必须直接使用它们，不得再以第一帧调用资源或素材创建接口。
|
||||
- 最终项目资源和账号素材只把 `imageSequenceFrames/imageSequenceDurationMs` 写入正式媒体字段，并以 `sourceResourceId` 指向独立预览视频资源；正式帧对象和角色动作生成响应都不含 `frameIndex`，数组位置是唯一播放顺序，帧数和 FPS 均按需派生。`generationInputs` 只保存 `fields/references` 等用户可重放输入，`screenColorHex` 和动作运行结果均不落入其中。存量 `characterAnimation`、已确认动作行的 helper 顶层字段、`frameIndex`、误标预览 MP4 及动作 layout 副本由受 migration operator 限制的四阶段数据库 procedure 一次性规范化；迁移按权威对象类型排除同 task 的预览视频、只接受唯一最终图片序列并逐帧补齐登记对象身份，且不把 layout 复制的 `sourceResourceId` 当作历史血缘证据。CLI tuple 与 HTTP object 两种 procedure 返回都必须先归一为脚本内部统一的 `batch_sha256`，分页还必须拒绝未推进或重复出现的 cursor，避免安全校验误拒绝或生产迁移无限循环。该宽容只属于迁移；新生成仍严格使用“原角色资源 → 预览视频资源 → 最终序列资源”直接来源链。上线完成后 api-server、后台、Web 和外部 helper 不再读取 legacy fallback。新动作写入若提交旧运行字段或 `frameIndex`，HTTP 与 SpacetimeDB storage 均明确拒绝。
|
||||
- `frames[0].imageSrc` 仍作为后续动作素材快速编辑或再次生成动作时的透明帧来源。该规则不得跳过后端原有的视频生成、抽帧、透明化处理和帧素材落盘流程。
|
||||
|
||||
@@ -153,7 +153,7 @@ pipeline {
|
||||
|
||||
stage('Archive') {
|
||||
steps {
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm,build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/production-runtime-writer-identity-rotate.mjs,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/spacetime-migration-common.mjs,scripts/spacetime-maintain-external-generation-jobs.mjs,scripts/spacetime-migrate-editor-canvas-layout.mjs,scripts/spacetime-repair-editor-canvas-resources.mjs,scripts/database-backup-to-oss.mjs", fingerprint: true
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm,build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/production-runtime-writer-identity-rotate.mjs,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/spacetime-migration-common.mjs,scripts/spacetime-maintain-external-generation-jobs.mjs,scripts/spacetime-normalize-editor-character-actions.mjs,scripts/spacetime-migrate-editor-canvas-layout.mjs,scripts/spacetime-repair-editor-canvas-resources.mjs,scripts/database-backup-to-oss.mjs", fingerprint: true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -93,7 +93,7 @@ pipeline {
|
||||
copyArtifacts(
|
||||
projectName: params.BUILD_JOB_NAME,
|
||||
selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
|
||||
filter: "build/${params.BUILD_VERSION}/spacetime_module.wasm,build/${params.BUILD_VERSION}/spacetime_module.wasm.sha256,build/${params.BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/production-runtime-writer-identity-rotate.mjs,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/spacetime-migration-common.mjs,scripts/spacetime-maintain-external-generation-jobs.mjs,scripts/spacetime-migrate-editor-canvas-layout.mjs,scripts/spacetime-repair-editor-canvas-resources.mjs,scripts/database-backup-to-oss.mjs",
|
||||
filter: "build/${params.BUILD_VERSION}/spacetime_module.wasm,build/${params.BUILD_VERSION}/spacetime_module.wasm.sha256,build/${params.BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/production-runtime-writer-identity-rotate.mjs,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/spacetime-migration-common.mjs,scripts/spacetime-maintain-external-generation-jobs.mjs,scripts/spacetime-normalize-editor-character-actions.mjs,scripts/spacetime-migrate-editor-canvas-layout.mjs,scripts/spacetime-repair-editor-canvas-resources.mjs,scripts/database-backup-to-oss.mjs",
|
||||
target: '.',
|
||||
fingerprintArtifacts: true
|
||||
)
|
||||
|
||||
@@ -51,5 +51,6 @@ export * from './http';
|
||||
export * from './llm/narrativeLanguage';
|
||||
export * from './llm/parsers';
|
||||
export * from './stores/createProfileWalletStore';
|
||||
export * from './utils/signedReadUrlCache';
|
||||
|
||||
// should not export component, instead, they should be ref by relative path
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
import { describe, expect, test } from 'vitest';
|
||||
|
||||
import {
|
||||
parseSignedReadUrlExpiresAtMs,
|
||||
shouldReuseSignedReadUrlCacheEntry,
|
||||
} from './signedReadUrlCache';
|
||||
|
||||
describe('signedReadUrlCache', () => {
|
||||
test('只在签名地址距离过期超过安全窗口时复用', () => {
|
||||
const nowMs = Date.parse('2099-01-01T00:00:00Z');
|
||||
const entry = {
|
||||
signedUrl: 'https://signed.example.com/frame.png',
|
||||
expiresAtMs: parseSignedReadUrlExpiresAtMs('2099-01-01T00:05:00Z'),
|
||||
};
|
||||
|
||||
expect(shouldReuseSignedReadUrlCacheEntry(entry, nowMs)).toBe(true);
|
||||
expect(shouldReuseSignedReadUrlCacheEntry(entry, nowMs + 269_999)).toBe(
|
||||
true,
|
||||
);
|
||||
expect(shouldReuseSignedReadUrlCacheEntry(entry, nowMs + 270_000)).toBe(
|
||||
false,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,26 @@
|
||||
export const SIGNED_READ_URL_CACHE_SAFETY_WINDOW_MS = 30 * 1000;
|
||||
|
||||
export type SignedReadUrlCacheEntry = {
|
||||
signedUrl: string;
|
||||
expiresAtMs: number;
|
||||
};
|
||||
|
||||
export function parseSignedReadUrlExpiresAtMs(expiresAt: string) {
|
||||
if (!expiresAt) {
|
||||
return 0;
|
||||
}
|
||||
|
||||
const parsed = Date.parse(expiresAt);
|
||||
return Number.isFinite(parsed) ? parsed : 0;
|
||||
}
|
||||
|
||||
export function shouldReuseSignedReadUrlCacheEntry(
|
||||
entry: SignedReadUrlCacheEntry | undefined,
|
||||
nowMs = Date.now(),
|
||||
) {
|
||||
if (!entry) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return entry.expiresAtMs - SIGNED_READ_URL_CACHE_SAFETY_WINDOW_MS > nowMs;
|
||||
}
|
||||
@@ -558,6 +558,7 @@ copy_required_file "${SCRIPT_DIR}/spacetime-export-migration-json.mjs" "${TARGET
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-import-migration-json.mjs" "${TARGET_DIR}/scripts/database-import.mjs" "数据库导入脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-migration-common.mjs" "${TARGET_DIR}/scripts/spacetime-migration-common.mjs" "数据库迁移公共脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-maintain-external-generation-jobs.mjs" "${TARGET_DIR}/scripts/spacetime-maintain-external-generation-jobs.mjs" "外部生成任务维护脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-normalize-editor-character-actions.mjs" "${TARGET_DIR}/scripts/spacetime-normalize-editor-character-actions.mjs" "角色动作元数据规范化脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-authorize-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-authorize-migration-operator.mjs" "数据库迁移授权脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-revoke-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-revoke-migration-operator.mjs" "数据库迁移撤权脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/database-backup-to-oss.mjs" "${TARGET_DIR}/scripts/database-backup-to-oss.mjs" "数据库 OSS 备份脚本"
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user