feat(cache): 新增 cache/types.ts 类型定义

src/shared/lib/cache/types.ts

@@ -0,0 +1,59 @@
+/**
+ * 缓存基础设施类型定义。
+ */
+
+/**
+ * cacheFn 包装器配置。
+ */
+export interface CacheFnOptions {
+  /**
+   * 缓存标签，用于按 tag 失效。
+   * 必填，至少 1 个。支持模板占位符 `{id}` 等，由 invalidateFor 填充。
+   */
+  readonly tags: readonly string[]
+  /**
+   * TTL 秒数。不传则永久缓存（仅靠 tag 失效）。
+   */
+  readonly ttl?: number
+  /**
+   * 自定义 key 段。默认根据 fn.name + 参数 JSON 自动生成。
+   * 推荐显式传入以便跨实例一致。
+   */
+  readonly keyParts?: readonly unknown[]
+}
+
+/**
+ * CacheStore 接口。memory 与 redis 两种实现。
+ */
+export interface CacheStore {
+  /**
+   * 获取或设置缓存值。
+   * - 命中且未过期：返回缓存值
+   * - 未命中或过期：调用 producer，写入缓存后返回
+   * - producer 抛错：透传错误，不写入缓存
+   */
+  getOrSet<T>(
+    key: string,
+    producer: () => Promise<T>,
+    options: { tags: readonly string[]; ttl?: number },
+  ): Promise<T>
+  /**
+   * 按 tag 批量失效。
+   * - 解析 tag 对应的 key 集合
+   * - 删除所有 key
+   * - 删除 tag 索引
+   */
+  invalidateTags(tags: readonly string[]): Promise<void>
+}
+
+/**
+ * 失效映射表规则。
+ */
+export interface InvalidationRule {
+  /** 服务端 cacheStore + Next.js revalidateTag 失效的标签 */
+  readonly tags: readonly string[]
+  /** 客户端 TanStack Query 失效的 queryKey 前缀 */
+  readonly queryKeys: readonly (readonly (string | number)[])[]
+  /** Next.js revalidatePath 失效的路径 */
+  readonly paths: readonly string[]
+}