@teamix-evo/skills 0.12.1 → 0.13.0

package/src/teamix-evo-code-uni-manager/api-layering.md

@@ -2,13 +2,13 @@
 
 > ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 2 的强制读取项。任何涉及后端通信的代码必须先读本文件。
 
-> **核心原则**：组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`，通过 `src/hooks/` 暴露给组件。
+> **核心原则**：组件不直接 fetch。每个业务领域的代码聚合在 `src/features/<domain>/`，通过 hooks 暴露给组件。
 >
-> **uni-manager 增强**：多租户 / 多区域 / 跨云上下文（tenantId / regionId / cloudProvider）通过 **`src/lib/http.ts` 的 request interceptor 自动注入**，service 函数与 hook 不感知；只有"显式跨上下文"的少数 API 才在调用处显式覆盖。
+> **uni-manager 增强**：多租户 / 多区域 / 跨云上下文（tenantId / regionId / cloudProvider）通过 **`src/lib/http.ts` 的 request interceptor 自动注入**，api 函数与 hook 不感知；只有"显式跨上下文"的少数 API 才在调用处显式覆盖。
 
 ---
 
-## 三层结构
+## Feature-based 三层结构
 
 ```
 ┌────────────────────────────────────┐
@@ -21,8 +21,8 @@
                │ 仅通过 hook
                ▼
 ┌────────────────────────────────────┐
-│  src/hooks/use<Domain>*.ts         │  Hook 层：状态管理 + 缓存
-│  - 包装请求生命周期                 │
+│  src/features/<domain>/hooks.ts    │  Hook 层：状态管理 + 缓存(react-query 等)
+│  - 包装请求生命周期(loading/error) │
 │  - 处理缓存 / 重试 / 失效           │
 │  - 不写具体的 URL / payload 拼装    │
 │  - queryKey 含 tenantId / regionId │  ← uni-manager 强化：键值带上下文
@@ -30,7 +30,7 @@
                │ 调用纯函数
                ▼
 ┌────────────────────────────────────┐
-│  src/services/<domain>.ts          │  Service 层：请求纯函数
+│  src/features/<domain>/api.ts      │  API 层：请求纯函数
 │  - 输入参数 → 输出 Promise<T>      │
 │  - 拼 URL / 序列化 / 反序列化       │
 │  - 不依赖 React                    │
@@ -46,38 +46,52 @@
 └────────────────────────────────────┘
 ```
 
+### 目录结构
+
+```
+src/features/
+├── instance/         # 实例领域
+│   ├── api.ts        # 请求纯函数(listInstances, createInstance, ...)
+│   ├── api.cloud.ts  # 跨云查询(显式覆盖 interceptor，并发多 cloud)
+│   ├── hooks.ts      # react-query 封装(useInstanceList, useCreateInstance, ...)
+│   ├── types.ts      # 领域类型(Instance, InstanceStatus, InstanceListParams, ...)
+│   ├── mocks.ts      # 本地 mock 数据(开发阶段)
+│   └── schema.ts     # zod schema(CreateInstanceInputSchema, ...)
+├── tenant/           # 租户管理
+│   ├── api.ts
+│   ├── hooks.ts
+│   ├── types.ts
+│   └── mocks.ts
+├── region/           # 区域元数据
+│   └── ...
+└── audit-log/        # 操作日志
+    └── ...
+```
+
+新增一个业务领域 = 新增一个 `features/<domain>/` 文件夹，不会让任何一个目录膨胀。
+
 ---
 
-## §1 · `src/services/` 约定
+## §1 · `features/<domain>/api.ts` 约定
 
 ### 文件组织
 
-按**领域**（domain）拆，**不**按 HTTP 动词拆。
-
-```
-src/services/
-├── instance.ts       # 实例领域：list / get / create / start / stop / release
-├── database.ts       # 数据库领域
-├── tenant.ts         # 租户管理（meta，不是上下文）
-├── region.ts         # 区域元数据
-├── audit-log.ts      # 操作日志
-└── index.ts          # 统一 re-export（可选）
-```
+按**领域**（domain）拆为独立文件夹，每个领域的请求函数放 `api.ts`。
 
 ❌ 不要按动词拆：`getInstances.ts` / `createInstance.ts` —— 会爆文件数。
 
 ### 函数签名约定（uni-manager）
 
 ```ts
-// src/services/instance.ts
+// src/features/instance/api.ts
 import { http } from '@/lib/http';
 import type {
   Instance,
   InstanceListParams,
   CreateInstanceInput,
-} from '@/types/instance';
+} from './types';
 
-// ✅ 标准：service 不显式拼 tenantId / regionId / cloudProvider
+// ✅ 标准：api 不显式拼 tenantId / regionId / cloudProvider
 //    interceptor 会从当前 TenantContext 读取并加 header
 export async function listInstances(
   params: InstanceListParams,
@@ -120,37 +134,39 @@ export async function listInstancesAcrossTenants(
 要点：
 
 - **纯函数**（不依赖 React 上下文，可以在 SSR / Node 测试中单独跑）
-- **类型来自 `src/types/`**，不要在 service 文件里就地定义 domain 类型
-- **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理（归一化在 `src/lib/http.ts`）
-- **不写 console.log / 业务弹窗**
+- **类型来自同目录 `./types`**，同一领域内用相对路径引用
+- **错误不在 api 层处理** —— 抛出去给 hook / 全局 interceptor 处理（归一化在 `src/lib/http.ts`）
+- **不写 console.log / 业务弹窗** —— 是数据通道，不是 UI 通道
 - **不显式拼 tenantId / regionId** —— 让 interceptor 注入；显式覆盖只用于跨上下文场景
 
 ### 反模式
 
-- ❌ `fetch('https://api.example.com/...')` 写死 host
-- ❌ 每个 service 函数加 `tenantId: string` 参数 —— 应该走 interceptor
-- ❌ service 函数返回 `{ loading, data, error }`（那是 hook 该做的）
-- ❌ 在 service 里 `import { toast } from 'sonner'`
-- ❌ 一个 service 函数同时拼 URL、做业务计算、改全局 store
+- ❌ `fetch('https://api.example.com/...')` 写死 host（应该用 `http` wrapper）
+- ❌ 每个 api 函数加 `tenantId: string` 参数 —— 应该走 interceptor
+- ❌ api 函数返回 `{ loading, data, error }`（那是 hook 该做的）
+- ❌ 在 api 里 `import { toast } from 'sonner'` 弹通知（归到 hook 或全局 interceptor）
+- ❌ 一个 api 函数同时拼 URL、做业务计算、改全局 store
 
 ---
 
-## §2 · `src/hooks/` 约定
+## §2 · `features/<domain>/hooks.ts` 约定
 
 ### 命名
 
 - Query 类：`useInstanceList`、`useInstance(id)`、`useUserProfile`
 - Mutation 类：`useCreateInstance`、`useReleaseInstance`、`useUpdateUser`
 
+同一领域的 query + mutation hooks 聚合在一个 `hooks.ts` 里。
+
 ### 实现（以 `@tanstack/react-query` 为例 — uni-manager 增强 queryKey）
 
 ```ts
-// src/hooks/useInstanceList.ts
+// src/features/instance/hooks.ts
 import { useQuery } from '@tanstack/react-query';
-import { listInstances } from '@/services/instance';
+import { listInstances } from './api';
 import { useTenant } from '@/contexts/TenantContext';
 import { useRegion } from '@/contexts/RegionContext';
-import type { InstanceListParams } from '@/types/instance';
+import type { InstanceListParams } from './types';
 
 export function useInstanceList(params: InstanceListParams) {
   const { tenantId } = useTenant();
@@ -165,9 +181,9 @@ export function useInstanceList(params: InstanceListParams) {
 ```
 
 ```ts
-// src/hooks/useCreateInstance.ts
+// src/features/instance/hooks.ts (续)
 import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { createInstance } from '@/services/instance';
+import { createInstance } from './api';
 import { useTenant } from '@/contexts/TenantContext';
 
 export function useCreateInstance() {
@@ -184,11 +200,11 @@ export function useCreateInstance() {
 
 ### 反模式
 
-- ❌ Hook 里再次拼 URL（违反"service 拼 URL"边界）
+- ❌ Hook 里再次拼 URL（违反"api 拼 URL"边界）
 - ❌ queryKey 不包含 tenantId / regionId —— 切换租户后旧数据被复用
-- ❌ 一个 hook 调多个 service 把数据缝合 —— 缝合应该在 service 层
+- ❌ 一个 hook 调多个领域的 api 把数据缝合 —— 缝合应该在 api 层（返回组合好的 DTO）
 - ❌ Hook 里写业务跳转 / 路由切换 —— 由组件接 `mutation.onSuccess` callback 处理
-- ❌ 在 hook 里手动加 `tenantId` 到 service 入参 —— 走 interceptor
+- ❌ 在 hook 里手动加 `tenantId` 到 api 入参 —— 走 interceptor
 
 ---
 
@@ -306,9 +322,9 @@ export function useTenant() {
 
 ### 反模式
 
-- ❌ 在 service 里再 `import axios` 直接用（应该用 `http`）
-- ❌ 多份 `http` 实例
-- ❌ 把 tenantId / regionId 放到每个 service 的 url query 里（应该走 header）
+- ❌ 在 api 里再 `import axios` 直接用（应该用 `http`）
+- ❌ 多份 `http` 实例（分包拆 fetch 应该用一个 instance + 不同 baseURL config）
+- ❌ 把 tenantId / regionId 放到每个 api 的 url query 里（应该走 header）
 - ❌ 把 tenantId 当 React state 在每个组件里 prop drilling
 - ❌ tenantId 切换后不清 query cache —— 要么 queryKey 含 tenantId（推荐），要么显式 `qc.clear()`
 
@@ -317,16 +333,16 @@ export function useTenant() {
 ## §4 · 类型分层
 
 ```
-src/types/
-├── instance.ts       # Instance、InstanceStatus、InstanceListParams、CreateInstanceInput
-├── tenant.ts         # Tenant、TenantContext
-├── region.ts         # Region、CloudProvider
-└── api.ts            # 通用 ApiResponse<T>、Pagination<T>
+src/features/instance/types.ts    # Instance、InstanceStatus、InstanceListParams、CreateInstanceInput
+src/features/tenant/types.ts      # Tenant、TenantMeta、...
+src/features/region/types.ts      # Region、CloudProvider、...
+src/types/api.ts                  # 通用 ApiResponse<T>、Pagination<T>（跨领域共享）
 ```
 
-- **Domain 类型**放 `src/types/<domain>.ts`，被 service / hook / component 共享
-- **API 入参 / 出参类型**：与 domain 类型分开命名
-- **不要**让组件 props 类型直接 `import` service 的内部类型
+- **Domain 类型**（如 `Instance`）放 `src/features/<domain>/types.ts`，同领域内用相对路径 `./types` 引用
+- 组件消费时用 `@/features/instance/types` 引入
+- **跨领域通用类型**（如 `ApiResponse<T>`、`Pagination<T>`）放 `src/types/api.ts`
+- **API 入参 / 出参类型**：与 domain 类型分开命名（`InstanceListParams` vs `Instance`），但放同一个 `types.ts`
 
 ---
 
@@ -334,12 +350,12 @@ src/types/
 
 某些场景**允许**绕过本规范，但需要在代码注释里说明原因：
 
-| 场景                                   | 允许                                            |
-| -------------------------------------- | ----------------------------------------------- |
-| 静态资源 fetch                         | 组件直接 `fetch` 可，不用进 service             |
-| 第三方 SDK（地图、支付）有自己的客户端 | 包装层放 `src/lib/<sdk>.ts`                     |
-| 跨租户管理员视图（显式覆盖 header）    | service 接 `contextOverride` 参数（见 §1 示例） |
-| 一次性的诊断 / 调试代码                | 临时 fetch 可，但 PR 合并前必须清理或归位       |
+| 场景                                     | 允许                                              |
+| ---------------------------------------- | ------------------------------------------------- |
+| 静态资源 fetch（读 `public/` 下的 json） | 组件直接 `fetch` 可，不用进 features              |
+| 第三方 SDK（地图、支付）有自己的客户端   | 包装层放 `src/lib/<sdk>.ts`，不强制走 features    |
+| 跨租户管理员视图（显式覆盖 header）      | api 接 `contextOverride` 参数（见 §1 示例）       |
+| 一次性的诊断 / 调试代码                  | 临时 fetch 可，但 PR 合并前必须清理或归位         |
 
 ---
 
@@ -362,9 +378,9 @@ src/types/
 ```
 ## 数据层改动
 
-- src/types/instance.ts: 新增 `InstanceListParams`、`InstanceStatus`
-- src/services/instance.ts: 新增 `listInstances`、`releaseInstance`（纯函数，使用 `@/lib/http`，不显式拼 tenantId）
-- src/hooks/useInstanceList.ts: 包 `useQuery`，queryKey=['instances', tenantId, regionId, params]
+- src/features/instance/types.ts: 新增 `InstanceListParams`、`InstanceStatus`
+- src/features/instance/api.ts: 新增 `listInstances`、`releaseInstance`（纯函数，使用 `@/lib/http`，不显式拼 tenantId）
+- src/features/instance/hooks.ts: 新增 `useInstanceList`(useQuery, key=['instances', tenantId, regionId, params])
 - src/pages/instances/index.tsx: 仅消费 `useInstanceList`，不直接 fetch；URL 同步 tenantId / regionId
 - src/lib/http.ts: 已有 interceptor 注入 X-Tenant-Id / X-Region-Id，无需修改
 ```

package/src/teamix-evo-code-uni-manager/checklist.md

@@ -8,10 +8,10 @@
 
 ## 1. 复用判定 ✓
 
-- [ ] 新建 UI 组件前，查过 `@teamix-evo/ui` 注册表（MCP `list_components` / `find_components`）
+- [ ] 新建 UI 组件前，查过 `@teamix-evo/ui` 注册表（`.teamix-evo/meta/ui/manifest.json` + `<id>.md`）
 - [ ] 新建 UI 组件前，查过 `biz-ui/uni-manager`（um-topbar 等）+ §2 概念占位拼装表
 - [ ] 新建 UI 组件前，grep 过本项目 `src/components/`
-- [ ] 新建工具函数前，grep 过 `src/utils/` `src/lib/` `src/hooks/`
+- [ ] 新建工具函数前，grep 过 `src/utils/` `src/lib/` `src/features/`
 - [ ] 没有重复实现 ui 包已经提供的能力（Button、Input、Dialog、DataTable 等）
 - [ ] 没有 fork ui 包源码改样式（改样式应当走 design token）
 - [ ] **组件兜底铁律**：找不到现成实物时优先 ui 原子件组合，未自撸基础件
@@ -21,24 +21,24 @@
 
 - [ ] 组件**没有**直接调 `fetch` / `axios`
 - [ ] 组件**没有**直接读 `import.meta.env` / `process.env`
-- [ ] 所有后端调用都落在 `src/services/<domain>.ts`，且是纯函数
-- [ ] Service 函数**不依赖 React**（没有 `useXxx`、没有 `useState`）
-- [ ] Service 函数**不弹通知 / 不跳路由**
-- [ ] Service 函数**不显式拼 `tenantId` / `regionId` / `cloudProvider`** —— 走 interceptor 注入
-- [ ] 数据 hook 在 `src/hooks/`，使用统一的数据库（react-query / swr，不混用）
+- [ ] 所有后端调用都落在 `src/features/<domain>/api.ts`，且是纯函数
+- [ ] API 函数**不依赖 React**（没有 `useXxx`、没有 `useState`）
+- [ ] API 函数**不弹通知 / 不跳路由**
+- [ ] API 函数**不显式拼 `tenantId` / `regionId` / `cloudProvider`** —— 走 interceptor 注入
+- [ ] 数据 hook 在 `src/features/<domain>/hooks.ts`，使用统一的数据库（react-query / swr，不混用）
 - [ ] 数据 hook 的 `queryKey` 含 `tenantId` / `regionId`（确保切换上下文时 cache 自动失效）
 - [ ] 全局只有一份 http 实例，在 `src/lib/http.ts`
 - [ ] `lib/http.ts` interceptor 已注入 `X-Tenant-Id` / `X-Region-Id` / `X-Cloud-Provider`
 
 ## 3. 目录归位 ✓
 
-- [ ] 新文件位于约定的顶层目录（`pages/`、`components/`、`services/`、`hooks/`、`stores/`、`types/`、`utils/`、`lib/`、`contexts/`）
-- [ ] **没有**新增同义层（如 `views/`、`api/`、`helpers/`）
+- [ ] 业务领域代码（api/hooks/types/mocks）放在 `src/features/<domain>/`
+- [ ] 新文件位于约定的顶层目录（`pages/`、`components/`、`features/`、`stores/`、`utils/`、`lib/`、`contexts/`）
+- [ ] **没有**新增同义层（如 `views/`、`services/`、`helpers/` 与现有目录并存）
 - [ ] 仅在单个页面使用的组件 / hook 放在 `src/pages/<id>/_components/` 或 `_hooks/`（下划线前缀）
-- [ ] 跨页面复用的组件 / hook 才升到 `src/components/` `src/hooks/`
+- [ ] 跨页面复用的组件升到 `src/components/`；跨领域共享的 hook 放 `src/hooks/`（极少数，如 useDebounce / useDangerConfirm）
 - [ ] 跨云 / 跨租户专属组件放在 `src/components/cloud/`（CloudBadge / RegionBadge / ContextSwitcher）
 - [ ] 危险操作组件放在 `src/components/danger/` 或 `src/hooks/useDangerConfirm.ts`
-- [ ] React Hook 在 `hooks/`，不在 `utils/`
 - [ ] 类型声明文件没有运行时代码（纯类型）
 
 ## 4. 命名 ✓
@@ -54,15 +54,15 @@
 - [ ] 跨目录 import 走 `@/*` 别名
 - [ ] **未发生反向依赖**：
   - `components/` 没有 import `pages/`
-  - `services/` 没有 import `hooks/` `components/` `pages/`
-  - `hooks/` 没有 import `pages/`
-  - `utils/` `lib/` `types/` 没有 import 业务层
+  - `features/<domain>/api.ts` 没有 import `hooks` `components/` `pages/`
+  - `features/<domain>/hooks.ts` 没有 import `pages/`
+  - `utils/` `lib/` 没有 import 业务层
 - [ ] 页面私有目录（`_components/` `_hooks/`）**没有**被其他页面 import
 
 ## 6. 类型 ✓
 
-- [ ] Domain 类型放 `src/types/<domain>.ts`
-- [ ] Service 函数有显式的入参 / 返回 `Promise<T>` 类型
+- [ ] Domain 类型放 `src/features/<domain>/types.ts`，不在 api / component 文件就地定义
+- [ ] API 函数有显式的入参 / 返回 `Promise<T>` 类型
 - [ ] 没有 `any`
 - [ ] Hook 的返回类型由 `react-query` / `swr` 自动推断
 
@@ -74,7 +74,7 @@
 
 ## 8. 副作用与可测性 ✓
 
-- [ ] Service 函数是纯函数
+- [ ] API 函数是纯函数（同样输入 → 同样输出，无隐式全局读写）
 - [ ] 工具函数（`src/utils/`）是纯函数
 - [ ] 没有在模块顶层（import 时）发请求 / 弹通知 / 改全局状态
 - [ ] 异步操作有错误处理路径
@@ -84,7 +84,7 @@
 （若改动涉及表单 — 详见 [`forms-and-validation.md`](forms-and-validation.md)）
 
 - [ ] 表单状态用 `react-hook-form`，**未用** `useState` 拼字段
-- [ ] 校验用 `zod` schema，schema 落 `src/services/<domain>.schema.ts`
+- [ ] 校验用 `zod` schema，schema 落 `src/features/<domain>/schema.ts`
 - [ ] 类型从 schema 推导（`z.infer<...>`）
 - [ ] 错误信息写在 schema 里
 - [ ] 提交走 mutation hook
@@ -123,7 +123,7 @@
 
 （详见 [`testing.md`](testing.md)）
 
-- [ ] 新增纯函数有同名 `*.test.ts`（**必测**）
+- [ ] 新增纯函数（`src/utils/`、`src/features/*/api.ts`）有同名 `*.test.ts`（**必测**）
 - [ ] 新增 zod schema 有 `parse` 成功 / 失败用例（**必测**）
 - [ ] 关键业务路径（创建实例 / 切租户 / 删除资源）有组件 / hook 测试（**必测**）
 - [ ] 测试文件就近放在 `<source>.test.ts(x)`
@@ -151,11 +151,11 @@
 
 1. **组件直接 fetch / axios** —— 数据层未分层
 2. **新建 Button / Input / Dialog 等基础组件** —— 重造 ui 包能力
-3. **services 函数依赖 React** —— 边界穿透
-4. **services 函数显式拼 tenantId / regionId 在 url query** —— 应走 header interceptor
-5. **`src/views/` 与 `src/pages/` 并存** —— 同义层污染
+3. **features/*/api.ts 函数依赖 React** —— 边界穿透
+4. **api 函数显式拼 tenantId / regionId 在 url query** —— 应走 header interceptor
+5. **`src/views/` 与 `src/pages/` 并存（或 `src/services/` 与 `src/features/`）** —— 同义层污染
 6. **响应里没有复用决策日志** —— 流程未跑通
-7. **反向依赖**（service 引 hook、component 引 page）
+7. **反向依赖**（api 引 hook、component 引 page）—— 依赖图破坏
 8. **多份 http 实例** —— 鉴权 / 上下文 header 无法统一
 9. **没有全局 ErrorBoundary** —— 异常直接白屏给用户
 10. **表单用 `useState` 拼字段** —— 弃 react-hook-form + zod
@@ -177,15 +177,15 @@
 ## 编码合规自检（uni-manager）
 
 - 复用判定: ✅ 复用 ui Button / DataTable + biz-ui/uni-manager um-topbar；🆕 新写 InstanceStatusBadge（业务状态映射）
-- 数据层: ✅ services/instance.ts 纯函数；✅ hooks/useInstanceList.ts queryKey 含 tenantId / regionId；✅ 组件未 fetch；✅ http.ts interceptor 已注入上下文
-- 目录: ✅ 页面在 pages/instances/；✅ 跨云组件在 components/cloud/CloudBadge.tsx
+- 数据层: ✅ features/instance/api.ts 纯函数；✅ features/instance/hooks.ts queryKey 含 tenantId / regionId；✅ 组件未 fetch；✅ http.ts interceptor 已注入上下文
+- 目录: ✅ 页面在 pages/instances/；✅ 领域代码在 features/instance/；✅ 跨云组件在 components/cloud/CloudBadge.tsx
 - 命名: ✅ kebab 目录 / Pascal 组件 / camel hook
 - 边界: ✅ 全部走 @/\*；✅ 无反向依赖
-- 类型: ✅ types/instance.ts 集中声明
-- 表单: ✅ useForm + zodResolver；✅ 删除走 useDangerConfirm（输入名称）
+- 类型: ✅ features/instance/types.ts 集中声明
+- 表单(若涉及): ✅ useForm + zodResolver；✅ schema 在 features/instance/schema.ts；✅ 删除走 useDangerConfirm（输入名称）
 - 错误/加载: ✅ 三态全处理；✅ ErrorBoundary 已在 App 根；✅ 跨云 404 fallback 已加
 - 路由: ✅ React.lazy + Suspense；✅ tenantId/regionId 进 URL；✅ um-topbar 切换改写 URL
-- 测试: ✅ instance.test.ts msw handler 验证 X-Tenant-Id；✅ schema parse 失败用例已加
+- 测试: ✅ features/instance/api.test.ts msw handler 验证 X-Tenant-Id；✅ schema parse 失败用例已加
 - design 协作: ✅ UM1/UM2/UM3 一致性三件套已自检
 - 红线: ✅ 全过（含 uni-manager UM 4 条红线）
 

package/src/teamix-evo-code-uni-manager/error-and-loading.md

@@ -352,9 +352,9 @@ function InstanceDetailPage() {
 | `alert('保存失败')`                          | 阻断用户、丑、不可样式化          | `toast.error()`                                   |
 | ErrorBoundary 不上报                         | 错过线上 bug                      | `onError` 接 `reportError`                        |
 | reportError 不带 tenant/region 上下文        | 排障无法定位                      | `monitor.ts` 自动注入 active context              |
-| service 里 `try/catch` 吞错                  | 上层失去判断依据                  | 让 error 抛上来,hook / boundary 决定              |
+| api 里 `try/catch` 吞错                      | 上层失去判断依据                  | 让 error 抛上来,hook / boundary 决定              |
 | 跨云资源 404 用通用 ErrorPanel 兜底          | 用户看不出是上下文问题            | 用 `CloudResourceNotFound` + cloud/region badge   |
-| 跨云聚合查询全或全无                         | 一个 region 失败,其他可用结果丢失 | service 层返结构化结果,UI 显示部分成功 + 失败提示 |
+| 跨云聚合查询全或全无                         | 一个 region 失败,其他可用结果丢失 | api 层返结构化结果,UI 显示部分成功 + 失败提示     |
 
 ---