diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index ffbf08631..e8ec2041f 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -6228,3 +6228,11 @@ - 决策：快照 helper 返回全部同 ID 原始记录。通用 queued completion 只要任一记录未收口就执行既有第二次 GET；完美像素要求 operation dialog 唯一，命中多条时失败关闭为 `conflict`，不按其中任意一条猜测结果。无需改变 hydrate、删除、后端或 OpenAPI。 - 验证：两条 `duplicate` 定向用例通过；`npm run typecheck`、改动文件级 ESLint 与 `npm run check:encoding` 通过，未运行目录或全仓测试套件。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 + +## 2026-08-04 完美像素对账读取改用请求全生命周期绝对截止 + +- 缺陷：`loadEditorProject` 的 `timeoutMs` 只包住业务 `fetch` 等响应头。缺 token 时的登录恢复发生在该 timer 建立前，401 后的共享 refresh 等待也不受它限制；收到响应头后 timer 已清理，成功和错误响应的 `response.text()` 又可继续永久挂起。任一环节不 settle，完美像素对账都无法重新检查 75 秒窗口，首次提交的 dialog ownership 与图层锁也无法进入 `finally` 释放。 +- 决策：`requestJson` 新增 opt-in `deadlineAt`，从函数入口建立一次 lifecycle signal，覆盖缺 token 补票、业务 fetch、401 refresh 等待、所有 GET attempt、退避和成功 / 错误响应体读取。等待共享 refresh 只取消当前调用者，不把该 signal 传入共享 refresh 请求，避免一次图片对账超时取消 AuthGate 或其它请求正在复用的刷新；signal 到期也不得被鉴权 catch 吞掉后继续发业务请求、清 token 或广播登录态变化。未传 `deadlineAt` 的调用保持既有 `timeoutMs` 行为。 +- 对账边界：窗口内每次 GET 的 deadline 为 `min(reconcileUntil, readStartedAt + 10 秒)`；operation 已过期但从未读取时仍执行一次即时 GET，该例外最多 10 秒。deadline 只把本次读取视为失败，不穿透成未处理 rejection；轮询随后返回 `pending-confirmation` 并让首次提交 / hydrate 恢复的既有清理链执行。 +- 验证范围：`apiClient` 定向覆盖缺 token 与 401 refresh 永久等待、响应体永久等待；`editorProjectClient` 钉住 deadline 透传且普通读取仍保留 60 秒默认 timeout；generation workflow 钉住窗口内和过期单次读取的 deadline。未扩大为全站请求超时迁移。 +- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index fab0487e5..06879a4d1 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -52,7 +52,7 @@ - 前端提交前先创建关闭 composer 的右侧生成占位，再解析或上传源图以取得稳定引用，随后把版本化 `perfectPixelOperation` 请求快照写入该占位并 flush 当前项目布局，最后才发送 POST。`canvasCompletion.dialogId` 同时作为 operation identity、稳定 task identity 的输入和本地源图上传 ID；同一 operation 的上传路径与后续 POST 请求都不得随机漂移。`sourceImageSrc` 优先由当前图层已有的 `objectKey / resourceId / sourceAssetId` 解析；尚未登记的浏览器本地图片只执行 `ticket → OSS PUT → confirm → objectKey`，不为这条持久化输入换取 signed URL。一个 `AbortSignal` 必须贯穿源文件 fetch / 图片解析边界、ticket、PUT、confirm，完整上传 helper 的可选换签也必须透传同一 signal。正式请求不得包含 `data:` / `blob:`、signed URL 或普通外链。后端在读取源图前必须把该字段解析为当前 owner 已登记的私有 OSS object key，并核对 project / resource / asset 归属。 - 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对最终 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；不得保存逻辑低分辨率图、诊断图或前后对比图。 - strict 的本次结果事实零写入边界截至首个最终 PNG PUT：所有可预判的引用、归属、类型、静态编码、元数据、网格适用性和 CPU 处理错误必须在此前失败；前置 owner-scoped 项目 / 素材读取仍可能按既有语义懒建默认 canvas / folder，这些基础记录不属于本次完美像素结果。最终 PNG 的 OSS PUT / HEAD 位于数据库事务外；验证上传结果后，asset object、project resource、账号素材与可选 canvas completion 由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中原子提交。operation 以 `owner + project + canvasCompletion.dialogId` 为作用域，task / object / resource / asset ID 稳定派生，object key 携带规范请求与输入 / 输出摘要形成的 fingerprint；同内容重放只返回原结果，输入漂移或部分既有事实失败关闭。HTTP timeout/drop 不能撤销已发往远端的 procedure，客户端仍须按稳定 `taskId / objectKey / resourceId` 对账，不能把未收到回包等同于未提交。 -- `POST /api/editor/images/pixel-art-snaps` 是有副作用的 unsafe POST。客户端不得为它配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前以 `401` 拒绝、刷新 token 后的既有认证恢复不属于业务副作用重放，保持通用行为。POST 回包中的 `project / resource / asset` 不是结果 verdict；首次成功回包、未知异常、人工 exact replay 和刷新恢复都只读取项目 GET。`perfectPixelOperation.submittedAt / reconcileUntil` 从稳定请求快照写入时建立统一 75 秒绝对窗口，POST 回包不能续期；读取必须立即执行一次，随后退避间隔不超过 5 秒，窗口已过期时仍执行一次即时 GET。固定判据为：匹配 task 的唯一 resource 加已收口 dialog / 关联图层才是画布成功；dialog 不存在但存在匹配 task resource 才是 asset-only 成功；dialog 仍 generating、dialog 不存在且无匹配 resource、项目始终不可读或窗口耗尽均保持 unknown。素材库刷新只在项目终态后 fire-and-forget，同步抛错、异步拒绝或永久挂起都不得阻塞 verdict、项目快照应用和执行锁释放。 +- `POST /api/editor/images/pixel-art-snaps` 是有副作用的 unsafe POST。客户端不得为它配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前以 `401` 拒绝、刷新 token 后的既有认证恢复不属于业务副作用重放，保持通用行为。POST 回包中的 `project / resource / asset` 不是结果 verdict；首次成功回包、未知异常、人工 exact replay 和刷新恢复都只读取项目 GET。`perfectPixelOperation.submittedAt / reconcileUntil` 从稳定请求快照写入时建立统一 75 秒绝对窗口，POST 回包不能续期；读取必须立即执行一次，随后退避间隔不超过 5 秒，窗口已过期时仍执行一次即时 GET。每次项目读取使用 `requestJson.deadlineAt` 覆盖缺 token 补票、业务 fetch、401 refresh、重试退避与响应体读取；窗口内单次最多 10 秒且不得越过 `reconcileUntil`，过期后的唯一即时读取最多额外 10 秒。固定判据为：匹配 task 的唯一 resource 加已收口 dialog / 关联图层才是画布成功；dialog 不存在但存在匹配 task resource 才是 asset-only 成功；dialog 仍 generating、dialog 不存在且无匹配 resource、项目始终不可读或窗口耗尽均保持 unknown。素材库刷新只在项目终态后 fire-and-forget，同步抛错、异步拒绝或永久挂起都不得阻塞 verdict、项目快照应用和执行锁释放。 - unknown 状态持久化为原 generation dialog 上的 `pending-confirmation + perfectPixelOperation`，普通删除和随源图层清理不得移除该 operation；用户只能继续 GET 对账或显式按原 identity 重放。人工重试只刷新观察窗口，POST JSON 必须与持久请求 byte-for-byte 一致，不得按当前画布、目录、类型或标题重建，也不得创建第二个 dialog / task / object / resource / asset。hydrate 后只做 GET，不自动 POST、上传或重建请求。处理成功但事务内权威 dialog 已删除时，后端保留 object / resource / asset 并返回 asset-only 事实，canvas / revision 不变；前端只有在项目 GET 看见匹配 task resource 后才能提示“已保存到素材库”。现有布局 CAS 没有 deletion tombstone，completion 与其它已持久化布局编辑冲突时继续按权威 revision 守卫收口；尚未防抖落库的本地编辑合并不在本批范围。 - 完美像素并发闸回归测试不得通过进程级队列 Atomic 的 before/after 判断“本用例未入队”。过期 deadline 用例只断言 `504`；queue guard 的 Drop 归还由独立用例覆盖，不引入 `--test-threads=1`、全局串行锁或其它串行化兜底。 - 项目快照对账生成占位时必须检查全部同 ID 原始记录，不得用首项短路：通用 queued completion 只要任一记录未收口就执行既有第二次 GET；完美像素要求 operation dialog 唯一，命中多条时失败关闭为 `conflict`，不得按首条记录猜测成功。 @@ -176,7 +176,7 @@ - 裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`；父流程解析并校验私有 OSS object key 后只调用一次唯一内部 `bgfilter-worker` 的 complex 链路，子 worker 负责签发 600 秒 URL、`N / Q` 限流和最多两次顺序 provider attempt，complex 失败不接入 fallback，成功二进制返回后仍由父流程完成最终持久化。有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。 - 2026-08-04 修订：完美像素前端已经让素材刷新退出 verdict，持久化 operation 请求快照与 `pending-confirmation`，并接入刷新后的 GET-only 恢复；是否成功只能由下面的项目 GET 正向证据判定。 - 完美像素前端第二批以 durable operation 为提交边界：生成占位必须持久化 `perfectPixelOperation = { version: 1, kind: "perfect-pixel", operationId, taskId, request, submittedAt, reconcileUntil }`，其中 `operationId` 等于规范化 dialog id、`taskId` 固定为 `pixel-art-snap-{operationId}`，`request` 是稳定源引用解析完成后的完整 `EditorPixelArtSnapInput`，`submittedAt / reconcileUntil` 构成从快照写入起算、不得被 POST 回包续期的 75 秒整链绝对窗口。完美像素 dialog id 使用跨标签随机 identity，不能复用每个标签页都会从 1 开始的局部计数器。inline 源图以该 identity 作为稳定 upload ID，只执行 object-only 上传，不等待 signed URL；快照不得包含 Data URL、Blob URL 或 signed URL。POST 前必须取得包含该 dialog 与 operation 快照的布局保存成功确认，保存冲突、鉴权失败、重试耗尽或无法确认时 POST 必须为零。人工重试只能原样重放该快照与同一 operation，不得重新 placement、上传、读取当前图层字段或暗中换 identity；快照缺失、损坏或与 dialog / project / task / completion 不匹配时失败关闭。首次提交或人工重试在途期间若 owner、project 或组件生命周期已经变化，旧响应的素材写入、项目应用、提示与对账副作用必须全部忽略，不能把前一账号的结果写入当前账号状态。 -- 完美像素 unknown-result 的 verdict 只来自项目 GET，POST 响应体不得直接判成功：找到唯一稳定 task resource 且 dialog 已收口、结果层精确指向该 resource 时为 `Applied`；resource 存在且 dialog 不存在时为 `DialogMissing`，结果只在素材库；dialog 仍 generating（包括匹配 resource 已先可见）或 dialog 不存在且无匹配 resource 时继续有界轮询；resource 与 dialog / layer 出现原子事务不可能产生的错配时保持待确认并提示冲突，禁止自动 POST。首个 GET 立即执行，此后退避不超过 5 秒；即使绝对窗口已过期也必须读取一次。`refreshAssetLibrary` 只在终态后 best-effort 触发，不进入轮询 deadline、`Promise.all` 或成功判断，同步 throw、异步 reject 和永久挂起均不得阻塞。轮询到期或 GET 失败后 dialog 转 `pending-confirmation`，保留 operation 与请求快照并释放页面 busy，不得伪装成普通失败或声称素材已保存。 +- 完美像素 unknown-result 的 verdict 只来自项目 GET，POST 响应体不得直接判成功：找到唯一稳定 task resource 且 dialog 已收口、结果层精确指向该 resource 时为 `Applied`；resource 存在且 dialog 不存在时为 `DialogMissing`，结果只在素材库；dialog 仍 generating（包括匹配 resource 已先可见）或 dialog 不存在且无匹配 resource 时继续有界轮询；resource 与 dialog / layer 出现原子事务不可能产生的错配时保持待确认并提示冲突，禁止自动 POST。首个 GET 立即执行，此后退避不超过 5 秒；即使绝对窗口已过期也必须读取一次。GET 的绝对 deadline 从进入 `requestJson` 起覆盖鉴权恢复、所有 attempt 和响应体读取；不能把只覆盖响应头的 `timeoutMs` 当成整次读取上界。单次 deadline 到期按一次读取失败处理，随后由轮询返回 `pending`，首次提交必须进入 `finally` 释放 dialog ownership 与图层锁，hydrate 恢复必须清理 recovery controller。`refreshAssetLibrary` 只在终态后 best-effort 触发，不进入轮询 deadline、`Promise.all` 或成功判断，同步 throw、异步 reject 和永久挂起均不得阻塞。轮询到期或 GET 失败后 dialog 转 `pending-confirmation`，保留 operation 与请求快照并释放页面 busy，不得伪装成普通失败或声称素材已保存。 - 完美像素恢复只对账、不重新执行：项目 hydrate 后识别带有效 operation 快照的 `generating` / `pending-confirmation` dialog，只按稳定 task/resource 做 GET-only 轮询，绝不 POST、重新上传、重新准备来源或为了恢复而先写布局；owner/project 切换、卸载或更高 revision 到来时旧轮询结果不得生效。新写入的 v1 operation 固定使用 75 秒跨度；为兼容第一批和滚动升级中的旧标签页，hydrate 仍接受跨度及未来时钟偏差不超过 240 秒的旧 v1 journal。若旧 `submittedAt` 位于可接受的未来区间，先把它规范化到当前时间，再把 `reconcileUntil` 压到 `min(持久截止, 规范化 submittedAt + 75 秒, 当前时间 + 75 秒)`；写回形状必须继续满足 `reconcileUntil >= submittedAt`，确保下次 hydrate 仍保留同一 identity。新 durable operation 无论在哪个标签页、是否超过 legacy TTL 都不得被 `requiresLiveSession` 或普通删除路径清理；TTL 只兼容完全没有 operation journal 字段的历史 inline 孤儿，字段存在但内容损坏时必须保留并失败关闭，清理 legacy 孤儿时必须同时更新 `project.layers` 与 `project.canvas.layers`。恢复到期仍持久保持 `pending-confirmation`，只有用户明确点击重试才进入 exact replay。 - legacy inline 占位的本会话归属必须由同一份封装 ownership 管理：同步 Set 在首个 await 前完成 `claim`，保证到期判定即时可见；`claim / release` 仅在 membership 真变化时推进 React 可观察的 version，`release` 即使发生时 dialogs 与 callbacks identity 都不变，也必须立即唤醒到期 effect 重新判定。禁止重新暴露可变 Set ref 或直接修改 `.current`，React 不会因为 ref 内容变化而重跑 effect。 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。 diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx index 2f4da4f58..af32df1ad 100644 --- a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx +++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx @@ -2710,7 +2710,7 @@ describe('useImageCanvasGenerationWorkflow', () => { expect(loadEditorProjectMock).toHaveBeenNthCalledWith( 1, 'project-1', - expect.objectContaining({ timeoutMs: 10_000 }), + expect.objectContaining({ deadlineAt: expect.any(Number) }), ); expect(snapImageToPerfectPixelsMock).toHaveBeenCalledTimes(1); expect(applyProjectSnapshot).toHaveBeenCalledWith(reconciledProject, { @@ -3197,7 +3197,7 @@ describe('useImageCanvasGenerationWorkflow', () => { }); expect(loadEditorProjectMock).toHaveBeenCalledWith( 'project-1', - expect.objectContaining({ timeoutMs: 10_000 }), + expect.objectContaining({ deadlineAt: expect.any(Number) }), ); expect(refreshAssetLibrary).toHaveBeenCalledTimes(1); expect(screen.getByTestId('dialog').textContent).not.toContain('failed'); @@ -3862,9 +3862,16 @@ describe('useImageCanvasGenerationWorkflow', () => { 'project-1', expect.objectContaining({ signal: expect.any(AbortSignal), - timeoutMs: 10_000, + deadlineAt: expect.any(Number), }), ); + const readOptions = loadEditorProjectMock.mock.calls[0]?.[1] as + | { deadlineAt?: number } + | undefined; + expect(readOptions?.deadlineAt).toBeLessThanOrEqual(Date.now() + 10_000); + expect(readOptions?.deadlineAt).toBeLessThanOrEqual( + hydratedDialog.perfectPixelOperation!.reconcileUntil, + ); expect(snapImageToPerfectPixelsMock).not.toHaveBeenCalled(); expect(applyProjectSnapshotWithoutHistory).toHaveBeenCalledTimes(1); expect(applyProjectSnapshot).not.toHaveBeenCalled(); @@ -3902,6 +3909,7 @@ describe('useImageCanvasGenerationWorkflow', () => { it('observes an expired hydrated operation at least once and leaves it pending when no result exists', async () => { const operationId = 'perfect-pixel-hydrated-expired'; + const readStartedAt = Date.now(); const hydratedDialog = createHydratedPerfectPixelDialog({ operationId, reconcileUntil: Date.now() - 1_000, @@ -3930,6 +3938,11 @@ describe('useImageCanvasGenerationWorkflow', () => { ); }); expect(loadEditorProjectMock).toHaveBeenCalledTimes(1); + const readOptions = loadEditorProjectMock.mock.calls[0]?.[1] as + | { deadlineAt?: number } + | undefined; + expect(readOptions?.deadlineAt).toBeGreaterThanOrEqual(readStartedAt); + expect(readOptions?.deadlineAt).toBeLessThanOrEqual(Date.now() + 10_000); expect(snapImageToPerfectPixelsMock).not.toHaveBeenCalled(); expect(applyProjectSnapshotWithoutHistory).not.toHaveBeenCalled(); expect(screen.getByTestId('dialog-error').textContent).toBe( diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts index 1cd03bbb2..5f0189700 100644 --- a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts +++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts @@ -391,17 +391,18 @@ async function reconcilePerfectPixelProject( } try { hasAttemptedRead = true; + const readStartedAt = Date.now(); + const remainingAtReadMs = operation.reconcileUntil - readStartedAt; + const readDeadlineAt = + remainingAtReadMs > 0 + ? Math.min( + operation.reconcileUntil, + readStartedAt + PERFECT_PIXEL_PROJECT_READ_TIMEOUT_MS, + ) + : readStartedAt + PERFECT_PIXEL_PROJECT_READ_TIMEOUT_MS; latestProject = await loadEditorProject(projectId, { signal: options.signal, - timeoutMs: Math.max( - 1, - Math.min( - PERFECT_PIXEL_PROJECT_READ_TIMEOUT_MS, - remainingAfterDelayMs > 0 - ? remainingAfterDelayMs - : PERFECT_PIXEL_PROJECT_READ_TIMEOUT_MS, - ), - ), + deadlineAt: readDeadlineAt, }); const verdict = inspectPerfectPixelProjectSnapshot( latestProject, diff --git a/src/services/apiClient.test.ts b/src/services/apiClient.test.ts index d411171bf..8bd1ba54a 100644 --- a/src/services/apiClient.test.ts +++ b/src/services/apiClient.test.ts @@ -55,6 +55,16 @@ function createResponseMock(params: { }; } +function createDeferred() { + let resolve!: (value: T) => void; + let reject!: (reason?: unknown) => void; + const promise = new Promise((resolvePromise, rejectPromise) => { + resolve = resolvePromise; + reject = rejectPromise; + }); + return { promise, resolve, reject }; +} + describe('apiClient', () => { const fetchMock = vi.fn(); const dispatchEventMock = vi.fn(); @@ -687,6 +697,83 @@ describe('apiClient', () => { expect(capturedError).toBeInstanceOf(Error); }); + it.each(['missing-token', 'unauthorized'] as const)( + 'bounds the %s refresh wait with an absolute request deadline', + async (refreshMode) => { + const refreshResponse = createDeferred< + ReturnType + >(); + if (refreshMode === 'unauthorized') { + setStoredAccessToken('expired-token', { emit: false }); + fetchMock + .mockResolvedValueOnce(createResponseMock({ status: 401 })) + .mockImplementationOnce(() => refreshResponse.promise); + } else { + fetchMock.mockImplementationOnce(() => refreshResponse.promise); + } + + const request = requestJson( + '/api/runtime/protected', + { method: 'GET' }, + '读取受保护数据失败', + { deadlineAt: Date.now() + 20 }, + ); + + await expect(request).rejects.toMatchObject({ name: 'TimeoutError' }); + expect(fetchMock).toHaveBeenCalledTimes( + refreshMode === 'unauthorized' ? 2 : 1, + ); + expect(fetchMock.mock.calls.at(-1)?.[0]).toBe('/api/auth/refresh'); + if (refreshMode === 'unauthorized') { + expect(getStoredAccessToken()).toBe('expired-token'); + } else { + expect(getStoredAccessToken()).toBe(''); + } + expect(dispatchEventMock).not.toHaveBeenCalled(); + + refreshResponse.resolve( + createResponseMock({ + status: 200, + body: JSON.stringify({ + ok: true, + data: { token: 'late-refresh-token' }, + error: null, + meta: { apiVersion: '2026-06-16' }, + }), + }), + ); + await vi.waitFor(() => { + expect(getStoredAccessToken()).toBe('late-refresh-token'); + }); + expect(dispatchEventMock).not.toHaveBeenCalled(); + }, + ); + + it.each([200, 400])( + 'bounds a %i response body read with the same absolute request deadline', + async (status) => { + setStoredAccessToken('body-timeout-token', { emit: false }); + const responseBody = createDeferred(); + const response = createResponseMock({ status }); + response.text.mockImplementationOnce(() => responseBody.promise); + fetchMock.mockResolvedValueOnce(response); + + const request = requestJson( + '/api/runtime/protected', + { method: 'GET' }, + '读取受保护数据失败', + { deadlineAt: Date.now() + 20 }, + ); + + await expect(request).rejects.toMatchObject({ name: 'TimeoutError' }); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(response.text).toHaveBeenCalledTimes(1); + + responseBody.resolve(''); + await responseBody.promise; + }, + ); + it('surfaces response metadata through ApiClientError', async () => { setStoredAccessToken('metadata-token', { emit: false }); fetchMock.mockResolvedValueOnce( diff --git a/src/services/apiClient.ts b/src/services/apiClient.ts index 435fc4b34..94211f5e0 100644 --- a/src/services/apiClient.ts +++ b/src/services/apiClient.ts @@ -49,6 +49,12 @@ export type ApiRequestOptions = { requestId?: string; }; +export type ApiJsonRequestOptions = ApiRequestOptions & { + // 从 requestJson 入口起覆盖鉴权、重试、业务请求和响应体读取的绝对截止时间。 + // 未传时保持既有 timeoutMs 仅约束单次业务 fetch 的语义。 + deadlineAt?: number; +}; + export const BACKGROUND_AUTH_REQUEST_OPTIONS = { authImpact: 'local', skipRefresh: true, @@ -317,6 +323,93 @@ function composeAbortSignal( }; } +function composeAbsoluteDeadlineSignal( + signal: AbortSignal | undefined, + deadlineAt: number | undefined, +) { + const hasDeadline = + typeof deadlineAt === 'number' && Number.isFinite(deadlineAt); + if (!hasDeadline) { + return { + signal, + hasDeadline: false, + cleanup: () => {}, + }; + } + + const controller = new AbortController(); + const remainingMs = Math.max(0, deadlineAt - Date.now()); + let timeoutId: ReturnType | undefined; + const cleanup = () => { + if (timeoutId !== undefined) { + clearTimeout(timeoutId); + } + signal?.removeEventListener('abort', onAbort); + }; + const onAbort = () => { + controller.abort(signal?.reason ?? createAbortError()); + }; + + if (signal?.aborted) { + controller.abort(signal.reason ?? createAbortError()); + } else { + signal?.addEventListener('abort', onAbort, { once: true }); + if (remainingMs <= 0) { + controller.abort(createTimeoutError(0)); + } else { + timeoutId = setTimeout(() => { + controller.abort(createTimeoutError(remainingMs)); + }, remainingMs); + } + } + + return { + signal: controller.signal, + hasDeadline: true, + cleanup, + }; +} + +function awaitWithAbortSignal( + work: Promise, + signal?: AbortSignal, +): Promise { + if (!signal) { + return work; + } + + return new Promise((resolve, reject) => { + let settled = false; + const cleanup = () => { + signal.removeEventListener('abort', onAbort); + }; + const settle = (callback: () => void) => { + if (settled) { + return; + } + settled = true; + cleanup(); + callback(); + }; + const onAbort = () => { + settle(() => reject(signal.reason ?? createAbortError())); + }; + + signal.addEventListener('abort', onAbort, { once: true }); + work.then( + (value) => { + settle(() => resolve(value)); + }, + (error: unknown) => { + settle(() => reject(error)); + }, + ); + if (signal.aborted) { + onAbort(); + } + }); +} + async function waitForRetry(ms: number, signal?: AbortSignal) { if (ms <= 0) { return; @@ -702,14 +795,17 @@ export async function fetchWithApiAuth( try { // 受保护请求在本地 access token 缺失时，先尝试用 refresh cookie 静默补票， // 避免把后端原始 “缺少 Bearer Token” 直接暴露给业务 UI。 - await ensureStoredAccessToken(); + await awaitWithAbortSignal(ensureStoredAccessToken(), requestSignal); requestHeaders = withAuthorizationHeaders(init.headers, options); requestHeaders[REQUEST_ID_HEADER] = requestId; hasAuthHeader = Boolean( requestHeaders.Authorization?.trim() || requestHeaders.authorization?.trim(), ); - } catch { + } catch (error) { + if (requestSignal?.aborted) { + throw requestSignal.reason ?? error; + } // 补票失败时继续走原始请求，让调用方按真实 401 分支处理。 } } @@ -735,13 +831,16 @@ export async function fetchWithApiAuth( !refreshAttempted ) { try { - await refreshAccessToken(); + await awaitWithAbortSignal(refreshAccessToken(), requestSignal); refreshAttempted = true; // refresh 成功只代表 access token 已补票成功， // 不能把当前业务请求的首次 401 直接放大成全局鉴权变更， // 否则像 Puzzle works 这类受保护列表会把单接口失败放大成整个平台重复 hydrate。 continue; } catch (refreshError) { + if (requestSignal?.aborted) { + throw requestSignal.reason ?? refreshError; + } const shouldClearAuth = hasAuthHeader && authFailurePolicy.clearAuthOnUnauthorized && @@ -771,6 +870,9 @@ export async function fetchWithApiAuth( return response; } } catch (error) { + if (requestSignal?.aborted) { + throw requestSignal.reason ?? error; + } if (!shouldRetryError(error, attempt, retry)) { throw error; } @@ -784,8 +886,9 @@ export async function fetchWithApiAuth( async function buildApiClientError( response: Response, fallbackMessage: string, + signal?: AbortSignal, ) { - const responseText = await response.text(); + const responseText = await awaitWithAbortSignal(response.text(), signal); const parsedError = parseApiErrorShape(responseText); const requestId = parsedError?.meta.requestId ?? @@ -820,17 +923,42 @@ export async function requestJson( url: string, init: RequestInit, fallbackMessage: string, - options: ApiRequestOptions = {}, + options: ApiJsonRequestOptions = {}, ): Promise { - const response = await fetchWithApiAuth(url, init, options); + const lifecycle = composeAbsoluteDeadlineSignal( + init.signal ?? undefined, + options.deadlineAt, + ); + const requestOptions = lifecycle.hasDeadline + ? { ...options, timeoutMs: undefined } + : options; + const requestInit = lifecycle.signal + ? { ...init, signal: lifecycle.signal } + : init; - if (!response.ok) { - throw await buildApiClientError(response, fallbackMessage); + try { + const response = await fetchWithApiAuth(url, requestInit, requestOptions); + + if (!response.ok) { + throw await buildApiClientError( + response, + fallbackMessage, + lifecycle.signal, + ); + } + + const responseText = await awaitWithAbortSignal( + response.text(), + lifecycle.signal, + ); + if (lifecycle.signal?.aborted) { + throw lifecycle.signal.reason ?? createAbortError(); + } + + return responseText + ? unwrapApiResponse(JSON.parse(responseText) as T) + : (null as T); + } finally { + lifecycle.cleanup(); } - - const responseText = await response.text(); - - return responseText - ? unwrapApiResponse(JSON.parse(responseText) as T) - : (null as T); } diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts index e06f3ca5d..c30557edc 100644 --- a/src/services/image-editor/editorProjectClient.test.ts +++ b/src/services/image-editor/editorProjectClient.test.ts @@ -371,6 +371,33 @@ describe('editorProjectClient', () => { ); }); + it('forwards an absolute lifecycle deadline when loading a project', async () => { + const controller = new AbortController(); + const deadlineAt = Date.now() + 10_000; + requestJsonMock.mockResolvedValueOnce({ + project: { + projectId: 'editor-project-1', + title: '角色设定板', + viewport: { x: 8, y: 9, scale: 1.5 }, + layers: [], + resources: [], + updatedAt: '2026-06-12T00:00:00.000Z', + }, + }); + + await loadEditorProject('editor-project-1', { + signal: controller.signal, + deadlineAt, + }); + + expect(requestJsonMock).toHaveBeenCalledWith( + '/api/editor/projects/editor-project-1', + { method: 'GET', signal: controller.signal }, + '读取图片画布工程失败', + { deadlineAt }, + ); + }); + it('renames and deletes an editor project', async () => { requestJsonMock .mockResolvedValueOnce({ diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts index 1d6229b34..d81484ca8 100644 --- a/src/services/image-editor/editorProjectClient.ts +++ b/src/services/image-editor/editorProjectClient.ts @@ -580,6 +580,7 @@ export type EditorCanvasSnapshot = { export type EditorProjectLoadOptions = { signal?: AbortSignal; timeoutMs?: number; + deadlineAt?: number; }; export type EditorProjectCreateInput = { @@ -789,6 +790,9 @@ export async function loadEditorProject( projectId: string, options: EditorProjectLoadOptions = {}, ) { + const hasAbsoluteDeadline = + typeof options.deadlineAt === 'number' && + Number.isFinite(options.deadlineAt); const response = await requestJson( `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}`, { @@ -796,10 +800,11 @@ export async function loadEditorProject( ...(options.signal ? { signal: options.signal } : {}), }, '读取图片画布工程失败', - // 中文注释：本文件多数接口都显式写了超时，这里此前没有——而 composeAbortSignal 在 - // timeoutMs 缺失时不设任何默认值。它是未知结果对账路径上的读取，挂住会让 catch 迟迟 - // 不结束，本会话对占位的归属登记要到 finally 才释放，连带把占位拖过存活窗口。 - { timeoutMs: options.timeoutMs ?? 60_000 }, + hasAbsoluteDeadline + ? { deadlineAt: options.deadlineAt } + : // 中文注释：普通项目读取继续保留既有单次 fetch timeout；完美像素对账显式传 + // deadlineAt，改由 requestJson 从鉴权恢复到响应体读取约束完整生命周期。 + { timeoutMs: options.timeoutMs ?? 60_000 }, ); return response.project; }