diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index cf817f6da..1692ab476 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -6171,3 +6171,15 @@
- 真正的问题是验证方式而非测试:改的是 `src/services/image-editor/editorProjectClient.ts`,验证却只跑了 `vitest src/components/image-editor`,改动面与验证面完全对不上。这个盲区在本次会话中期分析另一份 CI 日志时已由我自己指出过,却没有改掉习惯,于是同一个盲区再次漏出——而且这次不是难复现的跨文件竞态,是本地一跑就红的确定性失败。
- 约定:这条链路横跨 `src/components/image-editor/` 与 `src/services/image-editor/`,往后验证至少同时覆盖两处。不跑全量套件——本机有九条稳定的环境失败(符号链接、`0600` 权限模式、缺客户端 AppData 配置),噪音大于收益。
- 关联文档:`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-08-03 对账整段设界,并把提交前置预算变成真正的取消
+
+- 缺陷一(对账可被素材库读取永久挂住):对账用 `Promise.all` 同时等项目快照与 `refreshAssetLibrary`,而 `loadEditorAssetLibrary` 至今没有 `timeoutMs`(`composeAbortSignal` 缺失时不设默认值)。`.catch()` 只接住拒绝、接不住永不 settle;catch 体内的 await 不返回,`finally` 就永远不执行——占位归属登记与源图层锁都释放不掉,而到期清理又豁免已登记的占位,页面永久停在 `generating`,同一源图也无法再次操作,刷新前无解。
+- 这个洞是上一条修复留下的:给 `loadEditorProject` 加界时写的注释已经把机制说对了(「挂住会让 catch 迟迟不结束」),却只给同一个 `Promise.all` 里两个 await 中的一个加了界。逐个接口补超时这条路已经漏过一次。
+- 决策一:给**整段对账**设 75 秒上界,而不是继续逐个接口补。往对账里加任何新的 await 都自动受约束。超时必须**解析为 null 而不是拒绝**——这段代码本身位于 catch 内,抛出会穿出整个 async 函数,而调用方是 `void snapSelectedLayerToPerfectPixels(...)`,结果是未处理的 rejection;解析为 null 则落进既有的「权威项目快照读取失败」分支,语义正好一致。
+- 缺陷二(预算只停止等待、不取消):`withPerfectPixelPrePostBudget` 原先只是 `Promise.race`,超时后底层继续跑。直传 `fetch` 没有 signal,被放弃的上传会一路走到 confirm 并注册对象,用户重试再产生一份。
+- 决策二:把同一个 `AbortSignal` 贯穿凭证请求、直传 POST 与 confirm 三步,由前置预算到期时 `abort`。只中止直传会留下未 confirm 的 OSS 对象,只中止 confirm 又会让实体已写入却无记录——要停就整条链一起停。`requestJson` 从 `init.signal` 取信号并与自身超时合成,所以凭证与 confirm 只需在 init 里传入。
+- 未采纳评审建议的全量贯穿(再覆盖重试等待与 flush/save):那要再动两个模块,而收益只是少产生一些用户不可见的存储孤儿;`flushProjectPersistence` 现已有 60 秒上界,最多多挂 60 秒后自行结束。改动面从四个模块降到两个,绝大部分收益保留。
+- 后果分级要说清:缺陷一是永久性的 UI 卡死,缺陷二只是存储层孤儿对象(confirm 注册的是 asset object,不是素材库条目,用户基本不可见)。两者同为 P2 但不同量级。
+- 验证:新增用例让项目快照读取永不 settle,断言 120 秒后完美像素状态回到「空闲」——即 `finally` 确实执行。去掉对账 deadline 后该用例变红。`vitest src/components/image-editor src/services/image-editor` 974 通过,typecheck、eslint、check:encoding 通过。
+- 关联文档:`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
index 4586bae1c..4d28b0b12 100644
--- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
@@ -114,6 +114,9 @@ type EditorGenerationMediaReference = {
type EditorGenerationMediaReferenceOptions = {
allowRegisteredIds?: boolean;
requireImageObjectReference?: boolean;
+ // 中文注释:由调用方的阶段预算驱动。仅在最外层停止 await 不会取消已经启动的上传,
+ // 被放弃的那次会继续跑完并注册对象,用户重试再产生一份。
+ signal?: AbortSignal;
};
let editorGenerationUploadFallbackCounter = 0;
@@ -191,6 +194,7 @@ async function uploadEditorGenerationInlineMediaSource(
source: string,
mediaType: EditorMediaAssetUploadType,
projectId?: string | null,
+ signal?: AbortSignal,
) {
const normalizedProjectId = projectId?.trim() || 'unscoped';
const uploadId = createEditorGenerationMediaUploadId();
@@ -206,6 +210,7 @@ async function uploadEditorGenerationInlineMediaSource(
uploadId,
],
entityId: normalizedProjectId,
+ signal,
...(projectId?.trim()
? { metadata: { editor_project_id: projectId.trim() } }
: {}),
@@ -247,6 +252,7 @@ export async function resolveEditorGenerationMediaReference(
uploadSource,
mediaType,
projectId,
+ options.signal,
);
}
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
index dbf91e2e7..f812194d8 100644
--- a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
@@ -2680,6 +2680,52 @@ describe('useImageCanvasGenerationWorkflow', () => {
expect(applyProjectSnapshot).not.toHaveBeenCalled();
});
+ it('releases the perfect-pixel locks when reconciliation reads never settle', async () => {
+ // 中文注释:对账用 Promise.all 同时等项目快照与素材库刷新,而 loadEditorAssetLibrary
+ // 至今没有超时。任一读取永不 settle,catch 体内的 await 就不返回,finally 永远不执行——
+ // 占位归属登记与源图层锁都释放不掉,到期清理又豁免已登记的占位,页面会永久停在
+ // generating。整段对账因此必须有上界,且超时要解析为 null 落进「快照读取失败」分支,
+ // 不能抛——这段本身在 catch 内,抛出会变成未处理的 rejection。
+ vi.useFakeTimers();
+ try {
+ const applyProjectSnapshot = vi.fn();
+ snapImageToPerfectPixelsMock.mockRejectedValueOnce(new Error('网络中断'));
+ // 中文注释:永不 settle 的素材库读取。
+ loadEditorProjectMock.mockImplementationOnce(() => new Promise(() => {}));
+ render(
+ ,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: '完美像素' }));
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(1_000);
+ });
+ expect(
+ screen.getByRole('status', { name: '完美像素状态' }).textContent,
+ ).toBe('处理中');
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(120_000);
+ });
+
+ expect(
+ screen.getByRole('status', { name: '完美像素状态' }).textContent,
+ ).toBe('空闲');
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
it('treats a gateway-synthesized timeout as an unknown outcome and reconciles', async () => {
// 中文注释:网关自己合成的 504 只有 code / message,没有 details,所以既不是 transport
// 异常也拿不到 resultPersistenceStarted。按「有响应即结果已知」会跳过对账,而此时
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
index c524f5b45..56c286635 100644
--- a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
@@ -234,20 +234,57 @@ function createProjectLayerSnapshotFromLayer(
// 「过紧」,同样是回归。90 + 120 = 210 秒,落在 240 秒存活窗口内并留 30 秒余量。
export const PERFECT_PIXEL_PRE_POST_BUDGET_MS = 90_000;
+// 中文注释:未知结果对账整段的上界。
+//
+// 逐个接口补超时已经漏过一次:给 loadEditorProject 加界时,同一个 Promise.all 里的
+// refreshAssetLibrary 分支被漏掉,而 loadEditorAssetLibrary 至今没有 timeout。任一读取
+// 永不 settle 时,catch 体内的 await 就不会返回,`finally` 永远不执行——占位归属登记和
+// 源图层锁都释放不掉,到期清理又会豁免已登记的占位,页面会永久停在 generating。
+// 所以这里给整段设界:往对账里加任何新的 await 都自动受约束。
+//
+// 超时必须**解析为 null 而不是拒绝**。这段代码本身位于 catch 内,抛出会穿出整个 async
+// 函数,而调用方是 `void snapSelectedLayerToPerfectPixels(...)`,结果是未处理的 rejection。
+// 解析为 null 则落进既有的「权威项目快照读取失败」分支,语义正好一致。
+const PERFECT_PIXEL_RECONCILIATION_BUDGET_MS = 75_000;
+
+async function withPerfectPixelReconciliationDeadline(
+ work: Promise,
+): Promise {
+ let timer: ReturnType | undefined;
+ try {
+ return await Promise.race([
+ work,
+ new Promise((resolve) => {
+ timer = setTimeout(
+ () => resolve(null),
+ PERFECT_PIXEL_RECONCILIATION_BUDGET_MS,
+ );
+ }),
+ ]);
+ } finally {
+ if (timer !== undefined) {
+ clearTimeout(timer);
+ }
+ }
+}
+
async function withPerfectPixelPrePostBudget(
work: Promise,
deadlineAt: number,
timeoutMessage: string,
+ // 中文注释:到期时必须真的 abort,而不只是停止 await。这一段会往 OSS 写实体,
+ // 被放弃的上传若继续跑完并 confirm,就留下一份不可见的孤儿对象,而用户重试还会再写一份。
+ abortOnTimeout?: AbortController,
): Promise {
let timer: ReturnType | undefined;
try {
return await Promise.race([
work,
new Promise((_resolve, reject) => {
- timer = setTimeout(
- () => reject(new Error(timeoutMessage)),
- Math.max(0, deadlineAt - Date.now()),
- );
+ timer = setTimeout(() => {
+ abortOnTimeout?.abort(new Error(timeoutMessage));
+ reject(new Error(timeoutMessage));
+ }, Math.max(0, deadlineAt - Date.now()));
}),
]);
} finally {
@@ -1880,14 +1917,17 @@ export function useImageCanvasGenerationWorkflow({
}
const prePostDeadlineAt = Date.now() + PERFECT_PIXEL_PRE_POST_BUDGET_MS;
+ const prePostAbort = new AbortController();
const sourceImageSrc = await withPerfectPixelPrePostBudget(
resolveEditorGenerationMediaReference(
sourceLayer,
'image',
normalizedProjectId,
+ { signal: prePostAbort.signal },
),
prePostDeadlineAt,
'完美像素源图准备超时。',
+ prePostAbort,
);
await withPerfectPixelPrePostBudget(
flushProjectPersistence(),
@@ -1975,10 +2015,12 @@ export function useImageCanvasGenerationWorkflow({
// 弹登录框、其余一律吞掉,返回 `Promise` 不带成败信号;它本身还是可选
// prop。刷新成功时用户白赚一份新列表,失败时文案必须仍然成立,所以下面只给
// 「请确认」的指令,不给「已刷新」的事实断言。
- const [reconciled] = await Promise.all([
- loadEditorProject(normalizedProjectId).catch(() => null),
- Promise.resolve(refreshAssetLibrary?.()).catch(() => undefined),
- ]);
+ const reconciled = await withPerfectPixelReconciliationDeadline(
+ Promise.all([
+ loadEditorProject(normalizedProjectId).catch(() => null),
+ Promise.resolve(refreshAssetLibrary?.()).catch(() => undefined),
+ ]).then(([snapshot]) => snapshot),
+ );
if (reconciled) {
// 中文注释:判据必须看 dialog 的 status / generatedLayerId,**不能**看它在不在。
// 服务端成功回填时保留该 dialog 并就地改写(置 status: "idle"、写 generatedLayerId),
diff --git a/src/services/image-editor/editorMediaAssetUploadClient.ts b/src/services/image-editor/editorMediaAssetUploadClient.ts
index 366676891..5f5ed6d7a 100644
--- a/src/services/image-editor/editorMediaAssetUploadClient.ts
+++ b/src/services/image-editor/editorMediaAssetUploadClient.ts
@@ -42,6 +42,9 @@ export type EditorMediaAssetUploadOptions = {
pathSegments?: string[];
entityId?: string;
metadata?: Record;
+ // 中文注释:贯穿凭证、直传与 confirm 三步。只中止直传会留下未 confirm 的 OSS 对象,
+ // 只中止 confirm 又会让实体已写入却无记录——要停就整条链一起停。
+ signal?: AbortSignal;
};
const EDITOR_MEDIA_READ_EXPIRE_SECONDS = 60 * 60;
@@ -86,6 +89,7 @@ export async function uploadEditorMediaAssetObjectFile(
const ticket = await requestJson(
'/api/assets/direct-upload-tickets',
{
+ signal: options.signal,
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
@@ -112,11 +116,17 @@ export async function uploadEditorMediaAssetObjectFile(
{ retry: EDITOR_REQUEST_RETRY_OPTIONS },
);
- await postEditorDirectUploadFile(ticket.upload, file, '上传素材失败');
+ await postEditorDirectUploadFile(
+ ticket.upload,
+ file,
+ '上传素材失败',
+ options.signal,
+ );
const confirmed = await requestJson(
'/api/assets/objects/confirm',
{
+ signal: options.signal,
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
diff --git a/src/services/image-editor/editorRetryOptions.ts b/src/services/image-editor/editorRetryOptions.ts
index ecbd86d15..30443b67c 100644
--- a/src/services/image-editor/editorRetryOptions.ts
+++ b/src/services/image-editor/editorRetryOptions.ts
@@ -53,11 +53,15 @@ export async function postEditorDirectUploadFile(
upload: EditorDirectUploadTarget,
file: File,
errorMessage: string,
+ // 中文注释:调用方超时后仅停止 await 是不够的——这一步是唯一往 OSS 写实体的动作,
+ // 不取消的话被放弃的上传会继续跑完并注册对象,用户重试再产生一份,留下不可见的孤儿。
+ signal?: AbortSignal,
) {
for (let attempt = 0; ; attempt += 1) {
const response = await fetch(upload.host, {
method: 'POST',
body: buildDirectUploadFormData(upload, file),
+ signal,
});
if (response.ok) {