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

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

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

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

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

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;