@lark-apaas/coding-steering 0.1.32-dev.a87aa13 → 0.1.32-dev.b12eab4

package/steering/nestjs-react-fullstack/skills/nestjs-cache/SKILL.md

@@ -9,7 +9,7 @@ control-by-feature-ab: true
 
 # NestJS Caching 使用指南
 
-在 NestJS 后端为读多写少路径加缓存。平台已注入 `CACHE_MANAGER`，业务只需要：**判断该不该缓存 → 选一种使用姿势 → 遵守 Key 命名和 TTL 规范**。
+本 Skill 用于妙搭 NestJS 后端的缓存评估、接入、优化、审查和排障。先判断数据能否复用、谁可以读取、允许多旧，再确定 Key、TTL、失效方式和实现。平台已注入 `CACHE_MANAGER`，业务直接使用。触发本 Skill 只表示需要评估缓存；收益不足或正确性条件不满足时，说明原因并给出合适的处理方向。
 
 ## 前置约束：不要自己装配 `CacheModule`
 
@@ -47,37 +47,41 @@ export class BookModule {}
 │    c) 读得贵（触发外部收费 API / 高负载 RPC / 大结果集 SQL）
 │  ├─ 都不满足 → 不加。加了维护成本 > 收益
 │  └─ 满足任一 → 下一步
-├─ 是否是**授权敏感路径**？
-│    a) 该 handler / 方法被 `@CanRole` / `@Can` 装饰
-│    b) 返回值由 PostgreSQL RLS（Row Level Security）过滤（登录身份不同结果不同）
-│  ├─ 是 → 不加。授权决策 / RLS 过滤后的结果与身份强绑定，
-│  │       缓存 = 越权（陈旧 policy）或串号（不同用户读同一 key）
-│  └─ 否 → 下一步
+├─ 返回数据是否受身份或权限影响？
+│  ├─ 否 → 下一步
+│  └─ 是 → 每次请求仍须执行必要鉴权；缓存命中不能跳过方法内的权限检查
+│           身份相关结果必须隔离，权限变化后旧结果不得越权访问
+│           无法满足时 → 不缓存该结果；继续评估可独立复用的公共数据
 ├─ 业务可容忍 TTL 期内数据轻微陈旧（读到几秒前的旧值不影响正确性）？
 │  ├─ 否（要强一致，如库存/余额/权限当次判定）→ 不加
 │  └─ 是 → 下一步
-├─ 数据是"读多写少"（读远多于写，写触发时能明确 invalidate 哪些 key）？
-│  ├─ 否（写路径同样频繁、或 invalidate 范围爆炸）→ 不加，命中率上不去
-│  └─ 是 → 加缓存，选一种姿势（见下方）
-└─ 是否可能出现热点 key（一份数据被大量请求同时命中，如首页配置、公共字典）？
-   └─ 是 → 必须用 `cache.wrap` 拿 single-flight 语义，防击穿
+├─ 数据复用收益是否高于缓存维护成本？
+│    结合重复读取量、更新频率、允许的陈旧时间和失效成本判断；读多写少是优先信号
+│  ├─ 否，或无法满足一致性要求 → 不加
+│  └─ 是 → 可加；写入较频繁时，仍需确认失效方式可维护、预期命中率有价值
+└─ 是否存在同一 Key 的并发回源？
+   └─ 是 → 使用 `cache.wrap` 合并单进程内并发；多实例仍可能分别回源，继续评估源侧承载能力
 ```
 
-**判断技巧**：拿不准就问自己——"如果同一个用户 1 秒内连点 5 次，我希望后 4 次直接返回上次结果吗？" 是 → 加；否（每次必须重算）→ 不加。
+**判断技巧**：先确认相同输入是否会重复读取，再检查身份隔离、允许的陈旧时间和失效方式。连续请求可以返回相同结果，只是复用信号，不能替代这些检查。接口慢时也要检查索引、重复查询等源侧问题。
 
-**典型该加**：外部 open API 元数据 / 长尾字典表 / 用户 profile / 频繁读取的配置 / 慢报表聚合结果。
+**优先评估**：外部 API 元数据、公共字典、配置、热点详情、允许陈旧的报表，以及满足身份隔离和权限变化要求的用户资料。一个接口包含多步读取时，分别评估各步骤。
 
-**典型不该加**：金融流水、库存扣减、鉴权决策、事务型写路径、每次都不同参数的即席查询。
+**不使用缓存替代**：库存扣减、余额校验、授权决定等当次权威判断，以及事务型写入。历史记录和统计展示可单独评估；参数不重复、复用收益低的查询通常不加。
 
 ## Quick Reference
 
 | 场景 | 用法 |
 |------|------|
-| 读一次+回填 | `await cache.get(key)` → miss 时 fetch → `cache.set(key, val, ttlMs)` |
-| 热点 key 防击穿 | `await cache.wrap(key, () => loader(), ttlMs)` |
-| 幂等 GET 接口一键缓存 | `@UseInterceptors(CacheInterceptor)` + `@CacheKey` + `@CacheTTL` |
-| 写路径失效缓存 | `await cache.del(key)` |
-| TTL 单位 | 毫秒（cache-manager v6 起） |
+| 单次读缓存、未命中回源 | `get` → 未命中时读取源数据 → `set`；需并发合并时用 `wrap` |
+| 公共配置、字典、热点数据 | 使用平台共享缓存；`wrap` 仅合并单进程内对同一 Key 的并发读取 |
+| 可缓存的 GET 返回值 | `CacheInterceptor` + `CacheTTL`；静态 Key 仅用于所有相关请求结果相同的场景 |
+| 用户或租户维度的数据 | 先确认鉴权、身份隔离和权限变化要求，再选择手动缓存或受支持的动态 Key |
+| 列表、筛选、分页、报表 | Key 纳入影响结果的身份与有效查询参数；估算容量并明确失效方式 |
+| 反复读取不存在的资源 | 满足新数据可见性要求时缓存带类型标记的空结果；不缓存暂时故障 |
+| 一个接口包含多步读取 | 分别评估公共数据、用户数据和计算结果，只缓存满足条件的部分 |
+| 写后失效 | 业务数据提交成功后 `del` 相关 Key，并评估并发旧值回填 |
+| TTL 单位 | 毫秒；同时遵循平台允许的范围 |
 
 ## 三种使用姿势
 
@@ -112,9 +116,9 @@ export class ProfileService {
 
 ### B. `cache.wrap`（防击穿 / single-flight）
 
-热点 key 同时被 N 个请求命中时，只有一个 loader 会真正执行，其他并发请求等它结果。冷启动场景必须用这个而不是 A 方案。
+对同一缓存实例和 Key，`cache.wrap` 会合并同一进程内重叠的读取：只有一个 loader 执行，其他请求等待结果。热点或冷启动出现并发回源时优先使用。
 
-> **限定**：`wrap` 的 single-flight 是**单实例进程内**去重（v6 内嵌 `promise-coalesce`，本质是内存 Map）。多 pod 部署时每个实例的首个请求各自触发一次 loader → 最多 N 个 pod 并发回源 N 次，而非全局 1 次。要做真正的全局防击穿需额外配分布式锁。
+> **边界**：不同 FaaS 实例各自合并，`wrap` 不保证全局只回源一次。若源侧仍无法承受多实例并发，应根据平台已有能力选择进一步措施；不要假设 `CACHE_MANAGER` 自带分布式锁。
 
 ```typescript
 async getConfig(appApiName: string) {
@@ -128,9 +132,9 @@ async getConfig(appApiName: string) {
 
 ### C. `CacheInterceptor` + 装饰器（Controller 方法级）
 
-只适合**幂等 GET** 且返回值 JSON-safe。写请求、带循环引用 / Buffer / Date 的返回值、需要按登录用户维度分 key 的场景，不要用它——用 A 方案。
+仅用于可缓存的 GET，返回值须为 JSON-safe，缓存命中不能跳过必要鉴权或方法内的权限检查。默认按 URL 生成 Key，不会自动包含登录身份。身份相关结果须满足前述隔离与权限变化要求，再选择手动缓存或动态 Key。
 
-**`@CacheKey` 是静态常量**：所有请求都命中同一条缓存，会忽略路由参数 / query。带路由参数（如 `:apiName`）时**不要写 `@CacheKey`**，让 interceptor 按完整 URL 自动分 key；否则 app A 的结果会被返回给 app B（串号）。
+当前 `@nestjs/cache-manager@3.1.3` 的 `@CacheKey` 支持字符串和 Key 工厂函数。字符串 Key 是固定值，仅适用于相关请求结果相同的场景；动态 Key 应包含影响结果的路由、查询与身份维度。无身份等额外差异时，可不写 `@CacheKey` 并沿用 URL Key。已有项目先确认版本支持；示例中的 URL 方案仍可使用。
 
 ```typescript
 import { CacheInterceptor, CacheTTL } from '@nestjs/cache-manager';
@@ -151,13 +155,13 @@ export class AppsController {
 |------|------|------|
 | 业务前缀必需 | `profile:${userId}` | 避免多应用共用 Redis 时 key 冲突 |
 | 冒号分层 | `app:${apiName}:config:${env}` | 便于排障时 SCAN |
-| 参数拼接稳定 | 多参数按字典序拼接 | 避免 `?a=1&b=2` vs `?b=2&a=1` 命中不同 key |
+| 参数拼接稳定且完整 | 筛选、排序、分页等有效参数按固定字段顺序编码；按需加入可信的身份维度 | 相同条件得到相同 Key，不同结果不能因遗漏参数而共用 Key |
 | 禁用大对象作 key | 不要 `JSON.stringify(user)` 当 key | key 过长 / 特殊字符转义踩坑 |
 | Key 长度硬上限 | 必须 ≤ 512 字符 | 平台校验，超过直接跳过缓存 |
 
 ## 平台校验限制（硬门槛）
 
-平台会在缓存读写时做以下校验。**超过限制不会抛异常，而是本次请求跳过缓存 → 原读取逻辑正常执行 → Trace 记录 error_code**。写代码时按这套边界规划 key / TTL / value：
+以下是当前平台规定的 Key、TTL、数量和 Value 边界，业务代码按这些限制设计。缓存失败或拒写时，业务应使用正常回源结果；具体拒绝行为和 Trace 字段以部署版本的 SDK 与服务端契约为准。排障时核对实际错误，不仅凭本表推断原因。
 
 | 限制项 | 边界 | 超限行为 | error_code |
 |--------|------|----------|------------|
@@ -193,16 +197,16 @@ cache.get(key) 场景
 |------|----------|
 | Key 不加业务前缀 | 必须 `${业务域}:${resource}:${id}` 分层，避免多应用 / 多资源撞车 |
 | 空字符串 / `null` / `undefined` 当 key | 平台校验空 key，本次跳过缓存（`CACHE_KEY_INVALID`）；调用前先判空 |
-| 用户输入直接拼 key（`search:${rawQuery}`） | rawQuery 可能超 512 字符（`CACHE_KEY_TOO_LONG`）；先 hash 或截断 |
+| 用户输入直接拼 Key，或截断后作为 Key | 先规范化影响结果的完整参数，再计算摘要；不要用截断代替摘要。摘要只缩短 Key，不减少不同参数组合的数量，仍需评估平台配额 |
 | 把大对象 / JSON / SQL 塞进 key | 长度爆炸 + 特殊字符转义踩坑；用结构化 id 或摘要 |
 | Key 里放 traceId / timestamp / requestId | key 空间爆炸，撞 10,000 上限后新 key 不再写入（`CACHE_KEY_QUOTA_EXCEEDED`） |
-| 多参数拼接顺序不稳定 | 多参数按字典序拼接，避免 `?a=1&b=2` vs `?b=2&a=1` 命中不同 key |
+| 多参数拼接顺序不稳定或遗漏有效参数 | 固定字段顺序，包含所有影响结果的参数；规范化不能改变查询含义，例如有顺序语义的数组不能随意排序 |
 
 ### TTL 相关（v6 单位是**毫秒**）
 
 | 错误 | 正确做法 |
 |------|----------|
-| TTL 传秒（v5 旧思维，`60` = 想要 1 分钟） | v6 起是毫秒，`60_000` 才是 1 分钟；且 `60` = 60ms 会被平台拒（`CACHE_TTL_OUT_OF_RANGE`） |
+| TTL 单位误传为秒，例如用 `60` 表示 1 分钟 | `cache-manager` v5、v6 的 TTL 均以毫秒计，1 分钟应传 `60_000`。当前平台仍要求 TTL 在 `30_000 - 86_400_000` ms 内，`60` 不在允许范围内 |
 | TTL 传 `0` 想表达永久 | v6 `0` = 不过期，但平台也拒；接近永久用 `24 * 3600_000`（24h 上限） |
 | TTL 短于 30s | 平台拒（`CACHE_TTL_OUT_OF_RANGE`），本次不缓存；实际范围 `30_000 - 86_400_000` |
 
@@ -210,9 +214,9 @@ cache.get(key) 场景
 
 | 错误 | 正确做法 |
 |------|----------|
-| 缓存 Buffer / Date / 循环引用对象 | 序列化只保证 JSON-safe；复杂对象手动 toDTO |
-| 缓存 `null` 当"存在" | miss 就是 `null`，两者不可区分；表达"值就是空"用哨兵字符串（如 `'__EMPTY__'`）读到再转回 `null` |
-| 单 value 接近或超过 1 MB | 平台拒写（`CACHE_VALUE_TOO_LARGE`）；先投影裁剪或按分页 key 拆开；大 blob 用 CDN / 对象存储 |
+| 直接缓存 Buffer / Date / 循环引用对象 | 转成 JSON-safe DTO，并明确缓存命中与回源返回相同的数据结构；日期可转为约定的字符串，二进制使用文件地址 |
+| 缓存 `null` 表示“资源不存在” | 用带类型标记的结构，如 `{ kind: 'not-found' }`，与 miss 区分。只有允许延迟发现新数据时才缓存；TTL 遵循平台范围，超时和服务错误不能写成“不存在” |
+| 单 value 接近或超过 1 MB | 先裁剪字段或按分页 Key 拆分；大文件用 CDN / 对象存储。分页 Key 仍需纳入查询维度并估算数量 |
 
 ### API 姿势相关
 
@@ -220,18 +224,18 @@ cache.get(key) 场景
 |------|----------|
 | 业务模块里再 `CacheModule.register()` / `registerAsync(...)` | 平台已全局注册，直接 `@Inject(CACHE_MANAGER)`；重复注册会创建独立内存 store，不走 Redis、不 fail-open |
 | 用 `CacheInterceptor` 缓存写请求 | Interceptor 只适合幂等 GET；写请求用 A 方案，配 `cache.del(key)` |
-| `@CacheKey` 静态字符串包含用户维度，或带路由参数却写死 key | Interceptor 不感知登录态、静态 key 忽略路由参数/query → 串号；带用户或路由维度改用 A 方案手动拼 key |
+| 不同路由、查询或身份结果共用一个静态 `@CacheKey` | 静态 Key 不会区分这些结果；无额外身份差异时可用 URL Key，否则使用包含必要维度的动态 Key 或手动缓存，并满足鉴权要求 |
 | 高 QPS 热点用 A 方案而非 `wrap` | 击穿风险，冷启动 loader 会被并发触发 N 次；换 B 方案拿 single-flight（注意仍是单实例内去重） |
-| 用 `cache.wrap` 包写路径 | wrap 是"读 + 回填"模型；写路径 `.set()` 后再 `.del()` |
-| `set` 之后立刻 `get` 期望读到 | 平台侧写入 fire-and-forget，**即便 `await set` 也不保证同请求/下一 tick 可见**；写完后直接返回本地变量 |
+| 用 `cache.wrap` 包业务写入 | `wrap` 仅用于读取和回填。业务数据提交成功后，再 `cache.del(key)` 失效相关缓存；涉及详情和列表时分别确定相关 Key。删除缓存不能保证与并发读取强一致 |
+| 把 `await cache.set()` 等同于业务数据提交，或默认它一定不等待写入 | 当前锁定 SDK 会等待底层 `set`；服务端写入可见性取决于后端契约。缓存不能作为业务提交依据；写后直接使用本次计算或保存得到的结果，不用立即 `get` 来证明业务成功 |
 
 ### 授权 / 身份相关（可能导致越权）
 
 | 错误 | 正确做法 |
 |------|----------|
-| 缓存 `@CanRole` / `@Can` 装饰的 handler 返回值 | 授权决策与登录身份耦合，缓存陈旧 → 该拒的放行 = 越权；直接不加缓存 |
-| 用 `CacheInterceptor` 缓存"读取当前登录用户可见列表"（背后走 PostgreSQL RLS 过滤） | RLS 按 `current_user` / `set_config` 注入的租户/身份过滤，Interceptor 不感知身份 → 用户 A 的结果被用户 B 读到 = 越权串号；这类接口不加缓存，或用 A 方案手动把 `userId` / `tenantId` 拼进 key |
-| 手动缓存 RLS 保护表的查询结果，key 里没带身份维度（如 `list:tasks`） | 同上，多用户共享同一 key → 串号；key 必须至少含 `${tenantId}:${userId}`，且注意 key 空间是否会撞 10,000 上限 |
+| 看到 `@CanRole` / `@Can` 就直接拒绝缓存 | 每次请求保留必要鉴权；按返回数据的共享范围评估，命中不能跳过方法内的权限检查 |
+| 用默认 URL Key 缓存按当前身份过滤的结果 | URL 不能表达身份；需从可信请求上下文取得租户、用户等必要维度，隔离结果并满足权限变化要求 |
+| 认为 Key 带 `tenantId` / `userId` 就足够安全 | 身份隔离不能解决权限撤销；无法确保旧结果仍有权访问时，不缓存该结果。Key 数量仍须遵循平台配额 |
 
 ### 防御式代码
 
@@ -248,8 +252,14 @@ cache.get(key) 场景
 | 本地测缓存正常，线上不共享 / 重启就丢 | 业务模块里自己 `CacheModule.register()` 了，跑的是内存 store | 检查 `imports:` 是否含 `CacheModule.*`；删掉，直接 `@Inject(CACHE_MANAGER)` |
 | Interceptor 不生效 | 忘 `@UseInterceptors(CacheInterceptor)` 或 Controller 没注册 | 在 loader 加日志，观察是否每次请求都被调 |
 | TTL "不生效" | 传成秒、传 `0`、或超出 `30s - 24h` 平台范围 | Trace 里出现 `CACHE_TTL_OUT_OF_RANGE` 就是超范围 |
-| 数据陈旧 | 写路径没 `cache.del` 主动失效 | 更新时 log 出 del 的 key，比对读路径的 key |
+| 数据陈旧 | 写后未失效、删除失败、遗漏相关 Key，或旧的并发读取在删除后又回填 | 核对写入提交、删除和回填的先后顺序，检查缓存错误与 Key 覆盖范围；需要强一致的读取不要依赖缓存 |
 | Trace 出现 `CACHE_KEY_TOO_LONG` | key 里塞了整段 SQL / 用户输入 / JSON | 用 hash 或结构化 id 替换 |
 | Trace 出现 `CACHE_VALUE_TOO_LARGE` | 整表 / 大 list 直接缓存 | 分页缓存或投影裁剪，把单个 value 压到 1 MB 以内 |
 | Trace 出现 `CACHE_KEY_QUOTA_EXCEEDED` | key 空间失控（含 traceId / timestamp / 用户输入） | 收敛 key 模板，用有限的枚举维度 |
-| 并发压测下源侧被打爆 | 热点未用 `wrap` | 换 A → B，加 single-flight |
+| 并发压测下源侧被打爆 | 同一 Key 并发回源、Key 不稳定、缓存不可用或多实例同时冷启动 | 先核对 Key、命中与实例数；`wrap` 只合并单进程内并发，多实例压力需结合平台能力另行处理 |
+
+## 验证缓存行为
+
+按本次改动验证相关场景：命中时减少回源，未命中正常读取，`0` / `false` / 空字符串不被误判；影响结果的参数和身份维度正确隔离；写入后按约定失效；缓存不可用时正常回源且业务错误仍能暴露。
+
+涉及身份数据时，验证缓存命中不会跳过鉴权，并检查权限撤销后旧结果不可越权访问。涉及热点时区分单进程并发合并与多实例分别回源。无法运行的检查应说明原因，不将方案预期写成已验证结果。

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -11,7 +11,7 @@ match-template-name: nestjs-react-fullstack
 在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
 
 > **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
-> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件用 `miaoda file` CLI（见 `miaoda-file` skill）。二者与本 SDK 操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进服务端代码**。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
 
 ## 使用场景