修复生成图片签名地址重复换签

将 refreshKey 调整为 signed URL 缓存版本号，同一路径同版本复用未过期签名地址。

让完整阿里云 OSS generated 地址在 hook 中先归一并走 read-url 换签。

补充前端回归测试，覆盖相同 refreshKey 不重复换签和完整 OSS 地址不裸写入图片。

更新运维文档与 Hermes 记忆，明确 refreshKey 不是每次绕过签名缓存。

src/hooks/useResolvedAssetReadUrl.test.tsx

@@ -116,6 +116,54 @@ describe('useResolvedAssetReadUrl', () => {
     );
   });
 
+  test('完整 OSS generated 地址也会先换签再写入 img', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          data: {
+            read: {
+              objectKey:
+                'generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png',
+              signedUrl: 'https://signed.example.com/puzzle.png',
+              expiresAt: '2099-01-01T00:10:00Z',
+            },
+          },
+          error: null,
+          meta: {
+            apiVersion: '2026-04-08',
+            routeVersion: '2026-04-08',
+            latencyMs: 1,
+            timestamp: '2099-01-01T00:00:00Z',
+          },
+        }),
+        {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        },
+      ),
+    );
+
+    render(
+      <ResolvedAssetImage
+        src="https://genarrative-release.oss-cn-beijing.aliyuncs.com/generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png"
+        alt="候选图"
+      />,
+    );
+
+    expect(screen.queryByRole('img', { name: '候选图' })).toBeNull();
+
+    const image = await screen.findByRole('img', { name: '候选图' });
+    expect(image.getAttribute('src')).toBe(
+      'https://signed.example.com/puzzle.png',
+    );
+    expect(String(vi.mocked(globalThis.fetch).mock.calls[0]?.[0])).toContain(
+      'legacyPublicPath=%2Fgenerated-puzzle-assets%2Fpuzzle-session-1%2Fcandidate-1%2Fasset-1%2Fimage.png',
+    );
+  });
+
   test('refreshKey changes force a fresh signed url request without mutating OSS signature query', async () => {
     vi.spyOn(globalThis, 'fetch').mockImplementation(
       async () =>

src/hooks/useResolvedAssetReadUrl.ts

@@ -1,8 +1,8 @@
 import { useEffect, useState } from 'react';
 
 import {
-  isGeneratedLegacyPath,
   resolveAssetReadUrl,
+  shouldResolveAssetReadUrl,
 } from '../services/assetReadUrlService';
 
 type UseResolvedAssetReadUrlOptions = {
@@ -18,7 +18,7 @@ export function useResolvedAssetReadUrl(
   const enabled = options.enabled !== false;
   const normalizedSource = source?.trim() ?? '';
   const shouldResolve =
-    enabled && Boolean(normalizedSource) && isGeneratedLegacyPath(normalizedSource);
+    enabled && shouldResolveAssetReadUrl(normalizedSource);
   const [resolvedUrl, setResolvedUrl] = useState(
     shouldResolve ? '' : normalizedSource,
   );

src/services/assetReadUrlService.test.ts

@@ -223,6 +223,51 @@ describe('assetReadUrlService', () => {
     );
   });
 
+  test('resolveAssetReadUrl reuses signed url for the same refreshKey version', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2099-01-01T00:00:00Z'));
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          data: {
+            read: {
+              objectKey:
+                'generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png',
+              signedUrl: 'https://signed.example.com/puzzle.png?x-oss-signature=stable',
+              expiresAt: '2099-01-01T00:10:00Z',
+            },
+          },
+          error: null,
+          meta: {
+            apiVersion: '2026-04-08',
+            routeVersion: '2026-04-08',
+            latencyMs: 1,
+            timestamp: '2099-01-01T00:00:00Z',
+          },
+        }),
+        {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        },
+      ),
+    );
+
+    const source =
+      '/generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png';
+    const first = await resolveAssetReadUrl(source, {
+      refreshKey: 'asset-version-1',
+    });
+    const second = await resolveAssetReadUrl(source, {
+      refreshKey: 'asset-version-1',
+    });
+
+    expect(first).toBe(second);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
   test('getSignedAssetReadUrl reuses cached signed url before expiry', async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date('2099-01-01T00:00:00Z'));

src/services/assetReadUrlService.ts

@@ -21,8 +21,8 @@ type AssetReadUrlResolveOptions = {
   expireSeconds?: number;
   /**
    * 图片内容可能在同一路径下被重新写入。
-   * 对 generated 私有资源只跳过本地签名缓存并重新换签，
-   * 不能给 OSS V4 签名 URL 追加一次性参数。
+   * 对 generated 私有资源作为签名 URL 缓存版本维度；
+   * 同一路径和同一 refreshKey 继续复用 signed URL，refreshKey 变化才重新换签。
    * 普通非签名 URL 仍可追加 `_v` 避免浏览器图片缓存。
    */
   refreshKey?: string | number | null;
@@ -87,6 +87,14 @@ function resolveGeneratedLegacyPathFromUrl(value: string) {
   }
 }
 
+export function shouldResolveAssetReadUrl(source: string | null | undefined) {
+  const value = source?.trim() ?? '';
+  return (
+    Boolean(value) &&
+    (isGeneratedLegacyPath(value) || Boolean(resolveGeneratedLegacyPathFromUrl(value)))
+  );
+}
+
 function normalizeLegacyPublicPath(value: string) {
   return `/${value.trim().replace(/^\/+/u, '')}`;
 }
@@ -103,6 +111,23 @@ function buildCacheKey(request: AssetReadUrlRequest) {
   return '';
 }
 
+function normalizeReadUrlCacheVersion(value: string | number | null | undefined) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return String(value).trim();
+}
+
+function buildVersionedCacheKey(
+  cacheKey: string,
+  cacheVersion: string | number | null | undefined,
+) {
+  const normalizedVersion = normalizeReadUrlCacheVersion(cacheVersion);
+  return cacheKey && normalizedVersion
+    ? `${cacheKey}:version:${encodeURIComponent(normalizedVersion)}`
+    : cacheKey;
+}
+
 function buildAssetReadSearchParams(request: AssetReadUrlRequest) {
   const searchParams = new URLSearchParams();
   if (request.objectKey?.trim()) {
@@ -173,9 +198,13 @@ export async function getSignedAssetReadUrl(
   signal?: AbortSignal,
   options: {
     bypassCache?: boolean;
+    cacheVersion?: string | number | null;
   } = {},
 ) {
-  const cacheKey = buildCacheKey(request);
+  const cacheKey = buildVersionedCacheKey(
+    buildCacheKey(request),
+    options.cacheVersion,
+  );
   const bypassCache = options.bypassCache === true;
   const cached =
     !bypassCache && cacheKey ? signedReadUrlCache.get(cacheKey) : undefined;
@@ -268,7 +297,7 @@ function appendCacheBustParam(
   }
 
   // OSS V4 签名会把 query 纳入签名计算，前端不能追加 `_v` 之类的缓存参数。
-  // 需要刷新时通过 refreshKey 绕过本地签名缓存，重新请求 `/api/assets/read-url`。
+  // 需要刷新时让 refreshKey 变化，形成新的签名缓存版本；同一版本继续复用 signed URL。
   if (/[?&]x-oss-signature(?:=|&|$)/u.test(url)) {
     return url;
   }
@@ -313,8 +342,7 @@ export async function resolveAssetReadUrl(
         },
         options.signal,
         {
-          bypassCache:
-            options.refreshKey !== null && options.refreshKey !== undefined,
+          cacheVersion: options.refreshKey,
         },
       );
       return signedUrl;
@@ -330,8 +358,7 @@ export async function resolveAssetReadUrl(
       },
       options.signal,
       {
-        bypassCache:
-          options.refreshKey !== null && options.refreshKey !== undefined,
+        cacheVersion: options.refreshKey,
       },
     );
     return signedUrl;