@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/datahub.md

@@ -0,0 +1,832 @@
+# DataHub 数据中间层 / DataHub Data Middleware
+
+DataHub 是 Aithe UI 内置的轻量级数据中间层，提供统一的请求调度、缓存、去重、幂等防护、Mock 支持和 Loading 状态管理，帮助业务层以声明式方式与后端 API 交互。
+
+---
+
+## 架构概览
+
+```bash
+┌─────────────────────────────────────────────────────┐
+│                    业务层 (Business)                  │
+│   dataHub.request('/order/query', { id: '1' })      │
+└──────────────────────┬──────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────┐
+│                  DataHubCore 调度器                   │
+│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
+│  │ 策略识别 │→│ 请求拦截 │→│ 缓存检查  │→│ 去重/幂等 │ │
+│  └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
+│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
+│  │ 适配器   │→│ 响应拦截 │→│ 缓存写入  │→│ 错误处理  │ │
+│  └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
+└──────────────────────┬──────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────┐
+│                   适配器层 (Adapter)                  │
+│   FetchAdapter  │  MockAdapter  │  自定义 Adapter    │
+└─────────────────────────────────────────────────────┘
+```
+
+### 请求生命周期
+
+1. **合并配置** — 将默认配置与单次请求配置合并
+2. **解析策略** — 根据 URL 自动识别 `query`（查询）或 `submit`（提交）策略
+3. **生成 traceId** — 自动生成链路追踪 ID，或使用业务传入的 traceId
+4. **请求拦截** — 执行 `onRequest` 拦截器（如注入 Token）
+5. **缓存检查** — 查询类请求尝试命中缓存
+6. **去重/幂等** — 查询类请求自动去重，提交类请求自动幂等防护
+7. **适配器调用** — 通过注册的适配器发送实际请求
+8. **响应拦截** — 执行 `onResponse` 拦截器
+9. **业务错误处理** — HTTP 成功但业务 `code !== "Ok"` 时抛出 `DataHubError`
+10. **缓存写入** — 查询类请求成功后写入缓存
+11. **Loading 管理** — 自动维护全局 Loading 状态
+
+---
+
+## 快速上手
+
+### 导入与初始化
+
+```ts
+// 使用默认实例（推荐）
+import { dataHub } from '@aithe/aithe-ui';
+
+// 或创建独立实例
+import { DataHubCore } from '@aithe/aithe-ui';
+const dataHub = new DataHubCore({ baseURL: '/api' });
+```
+
+### 发起请求
+
+```ts
+// 查询请求（URL 包含 query/list/get 关键字，自动缓存+去重）
+const res = await dataHub.request('/order/query', { orderId: '123' });
+console.log(res.data); // 业务数据
+
+// 提交请求（自动幂等防护，防止重复提交）
+const res = await dataHub.request('/order/submit', { items: [] });
+
+// 使用 Mock 数据（开发阶段）
+const res = await dataHub.request(
+  '/order/query',
+  {},
+  {
+    mock: true,
+    mockData: { list: [], total: 0 },
+  },
+);
+```
+
+### 配置全局参数
+
+```ts
+dataHub.updateConfig({
+  baseURL: '/api/admin',
+  defaultTimeout: 15000,
+  defaultCacheTTL: 30000,
+  headers: { 'Content-Type': 'application/json' },
+});
+```
+
+---
+
+## 策略系统
+
+DataHub 根据 URL 最后一个路径段自动识别请求策略：
+
+| 策略     | 识别关键字             | 缓存 | 去重 | 幂等防护 | 可重试 |
+| -------- | ---------------------- | ---- | ---- | -------- | ------ |
+| `query`  | `query`、`list`、`get` | ✅   | ✅   | ❌       | ✅     |
+| `submit` | 其他所有路径           | ❌   | ❌   | ✅       | ❌     |
+
+### 自定义查询关键字
+
+```ts
+import { setQueryKeywords, getQueryKeywords } from '@aithe/aithe-ui';
+
+// 添加自定义关键字（替换默认列表）
+setQueryKeywords(['query', 'list', 'get', 'search', 'fetch']);
+
+// 查看当前关键字
+console.log(getQueryKeywords());
+```
+
+### 手动跳过策略
+
+```ts
+// 跳过缓存，强制发起新请求
+await dataHub.request('/order/query', { id: '1' }, { skipCache: true });
+
+// 跳过去重，允许同一请求并发执行
+await dataHub.request('/order/query', { id: '1' }, { skipDedup: true });
+
+// 跳过幂等防护，允许同一提交重复执行（如登录场景）
+await dataHub.request('/auth/login', params, { skipIdempotent: true });
+```
+
+---
+
+## 适配器
+
+适配器负责实际的 HTTP 通信，DataHub 内置两个零依赖适配器：
+
+### FetchAdapter
+
+基于 `window.fetch` 的生产适配器，默认启用。
+
+- 自动设置 `Content-Type: application/json`
+- 支持 `AbortController` 超时中断和外部取消
+- 默认使用 POST 方法
+
+### MockAdapter
+
+本地模拟适配器，用于开发阶段。
+
+- 返回符合 `DataHubAdapterResponse` 格式的模拟数据
+- 可配置 `mockDelay` 模拟网络延迟（默认 300ms）
+- 自动生成 mock traceId
+
+### 使用 Mock
+
+**单次请求 Mock：**
+
+```ts
+await dataHub.request(
+  '/user/query',
+  { id: '1' },
+  {
+    mock: true,
+    mockData: { name: 'Alice', age: 30 },
+    mockDelay: 500,
+  },
+);
+```
+
+**全局强制 Mock：**
+
+```ts
+dataHub.updateConfig({ forceMock: true });
+// 此后所有请求都走 MockAdapter
+```
+
+### 自定义适配器
+
+实现 `DataHubAdapter` 接口即可注册自定义适配器：
+
+```ts
+import type {
+  DataHubAdapter,
+  DataHubAdapterRequest,
+  DataHubAdapterResponse,
+} from '@aithe/aithe-ui';
+
+const axiosAdapter: DataHubAdapter = {
+  name: 'axios',
+  async request<T>(req: DataHubAdapterRequest): Promise<DataHubAdapterResponse<T>> {
+    const response = await fetch(req.url, {
+      method: req.options.method ?? 'POST',
+      headers: req.options.headers,
+      body: JSON.stringify(req.data),
+      signal: req.options.signal,
+    });
+    const data = await response.json();
+    return {
+      ok: response.ok && data.code === 'Ok',
+      status: response.status,
+      data,
+    };
+  },
+  abort(url: string) {
+    // 可选：取消指定 URL 的请求
+  },
+};
+
+dataHub.registerAdapter(axiosAdapter);
+
+// 使用自定义适配器
+await dataHub.request('/order/query', {}, { adapter: 'axios' });
+```
+
+---
+
+## 拦截器
+
+### 请求拦截器
+
+在请求发送前修改请求参数，常用于注入认证 Token：
+
+```ts
+dataHub.setRequestInterceptor((req) => {
+  const token = getToken();
+  if (token) {
+    req.options.headers = {
+      ...req.options.headers,
+      Authorization: `Bearer ${token}`,
+    };
+  }
+  return req;
+});
+```
+
+### 响应拦截器
+
+在响应返回前修改响应数据，常用于数据转换：
+
+```ts
+dataHub.setResponseInterceptor((res, req) => {
+  // 统一转换日期字段
+  if (res.data.data) {
+    res.data.data = transformDates(res.data.data);
+  }
+  return res;
+});
+```
+
+### 全局错误处理
+
+```ts
+dataHub.setErrorHandler((error, req) => {
+  console.error(`[DataHub] ${error.code}: ${error.message}`);
+  console.error(`  URL: ${error.url ?? req.url}`);
+  console.error(`  Trace: ${error.trace ?? 'N/A'}`);
+
+  // 401 自动跳转登录
+  if (error.status === 401 || error.code === 'Unauthorized') {
+    clearAuth();
+    location.hash = '#/login';
+  }
+});
+```
+
+---
+
+## 领域 Service 封装（推荐模式）
+
+建议按领域封装为 Service 类，通过静态方法组织接口，各页面直接调用：
+
+```ts
+// services/order-service.ts
+import dataHub, { type DataHubRequestOptions } from '@aithe/aithe-ui';
+
+export interface OrderListParams {
+  page: number;
+  size: number;
+  keyword?: string;
+}
+
+export interface OrderListData {
+  list: Order[];
+  total: number;
+}
+
+export class OrderService {
+  static getList(params: OrderListParams, options?: DataHubRequestOptions) {
+    return dataHub.request<OrderListData>('/order/query', params, {
+      ...options,
+      mock: true,
+      mockData: { list: [], total: 0 },
+    });
+  }
+}
+```
+
+```ts
+// page.ts
+import { OrderService } from './services/order-service';
+
+const res = await OrderService.getList({ page: 1, size: 10 });
+```
+
+---
+
+## 缓存
+
+DataHub 内置内存级 TTL 缓存，仅对查询类请求生效。
+
+### 工作机制
+
+- 缓存键由 `URL + 请求体` 生成，确保相同参数命中同一缓存
+- 写入时设置 TTL（默认 60000ms），过期后惰性淘汰
+- 命中缓存时直接返回，不经过适配器
+
+### 手动操作
+
+```ts
+import { cacheGet, cacheSet, cacheDelete, cacheClear } from '@aithe/aithe-ui';
+
+// 读取缓存
+const cached = cacheGet('/order/query', { id: '1' });
+
+// 写入缓存（TTL 120秒）
+cacheSet('/order/query', { id: '1' }, responseData, 120_000);
+
+// 删除指定缓存
+cacheDelete('/order/query', { id: '1' });
+
+// 清空所有缓存
+cacheClear();
+
+// 通过 DataHub 实例清空
+dataHub.clearCache();
+```
+
+---
+
+## 去重
+
+查询类请求自动去重，相同 URL + 请求体的并发请求共享同一个 Promise。
+
+### 工作机制
+
+- 第一个请求正常发起，后续相同请求复用其 Promise
+- 请求完成后自动清除去重记录
+- 跳过去重：`{ skipDedup: true }`
+
+### 手动操作
+
+```ts
+import { dedupClear } from '@aithe/aithe-ui';
+
+// 清空所有去重记录
+dedupClear();
+
+// 通过 DataHub 实例清空
+dataHub.clearDedup();
+```
+
+---
+
+## 幂等防护
+
+提交类请求自动启用幂等防护，防止同一请求在未完成前被重复提交。
+
+### 工作机制
+
+- 第一个请求正常执行
+- 后续相同请求在第一个请求完成前会被**拒绝**（抛出 `DataHubError`，code: `DuplicateSubmit`）
+- 请求完成（无论成功或失败）后自动释放锁，允许重试
+- 跳过幂等防护：`{ skipIdempotent: true }`（适用于登录等允许重试的场景）
+
+### 手动操作
+
+```ts
+import { idempotentClear } from '@aithe/aithe-ui';
+
+// 清空所有幂等锁
+idempotentClear();
+
+// 通过 DataHub 实例清空
+dataHub.clearIdempotent();
+```
+
+---
+
+## Loading 状态
+
+DataHub 自动维护全局 Loading 状态，基于引用计数支持并发请求场景。
+
+### 订阅 Loading 变更
+
+```ts
+// 全局 Loading（任意请求开始/结束）
+const unsubscribe = dataHub.onLoadingChange((loading) => {
+  console.log('Global loading:', loading);
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### 查询 Loading 状态
+
+```ts
+// 检查指定 URL 是否正在加载
+if (dataHub.isLoading('/order/query')) {
+  console.log('Order query is in progress');
+}
+```
+
+### 在 Lit 组件中使用
+
+```ts
+@customElement('my-page')
+export class MyPage extends LitElement {
+  private unsubscribe?: () => void;
+
+  connectedCallback(): void {
+    super.connectedCallback();
+    this.unsubscribe = dataHub.onLoadingChange(() => this.requestUpdate());
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.unsubscribe?.();
+  }
+
+  render() {
+    return html`
+      <aithe-spinner ?hidden=${!dataHub.isLoading('/order/query')}></aithe-spinner>
+      <!-- ... -->
+    `;
+  }
+}
+```
+
+---
+
+## 错误处理
+
+### DataHubError
+
+所有错误统一转换为 `DataHubError`：
+
+| 属性      | 类型      | 说明        |
+| --------- | --------- | ----------- |
+| `code`    | `string`  | 错误码      |
+| `message` | `string`  | 错误描述    |
+| `trace`   | `string?` | 链路追踪 ID |
+| `status`  | `number?` | HTTP 状态码 |
+| `url`     | `string?` | 请求 URL    |
+
+### 内置错误码
+
+| 错误码            | 触发场景                                 |
+| ----------------- | ---------------------------------------- |
+| `RequestAborted`  | 请求被 AbortController 中断              |
+| `NetworkError`    | 网络错误（DNS 解析失败、fetch 异常等）   |
+| `UnknownError`    | 其他未知错误                             |
+| `AdapterNotFound` | 指定的适配器未注册                       |
+| `DuplicateSubmit` | 幂等防护拦截的重复提交                   |
+| _(业务错误码)_    | 后端返回的 `code` 字段值（非 `"Ok"` 时） |
+
+### 错误处理示例
+
+```ts
+import { DataHubError } from '@aithe/aithe-ui';
+
+try {
+  const res = await dataHub.request('/order/submit', orderData);
+} catch (err) {
+  if (err instanceof DataHubError) {
+    switch (err.code) {
+      case 'DuplicateSubmit':
+        showToast('请勿重复提交');
+        break;
+      case 'NetworkError':
+        showToast('网络异常，请检查网络连接');
+        break;
+      case 'Unauthorized':
+        redirectToLogin();
+        break;
+      default:
+        showToast(`操作失败: ${err.message}`);
+    }
+    // 上报链路追踪 ID 用于问题排查
+    reportError(err.trace);
+  }
+}
+```
+
+---
+
+## APIStyle 业务协议解析
+
+DataHub 的 APIStyle 机制用于适配不同后端 API 的请求/响应协议格式。通过 `setAPIStyle()` 设置后，所有请求会自动进行**请求体包装**和**响应解包**。
+
+### 工作机制
+
+1. **请求阶段** — `onRequest` 修改请求体（如 `default` 风格包装为 `{ data: ... }`）
+2. **响应阶段** — `onResponse` 解析响应体为 `DataHubAPIResult`（`{ code, message, data }`）
+3. **校验阶段** — `isSuccess` 判断业务是否成功（如 `default` 风格要求 `code === 'Ok'`）
+4. **失败时** — 自动抛出 `DataHubError`，业务层无需手动判断业务状态码
+
+### 内置风格
+
+| 风格名    | 请求包装               | 响应解析                    | 成功条件              |
+| --------- | ---------------------- | --------------------------- | --------------------- |
+| `default` | `{ data: 原始请求体 }` | `{ code, message, data }`   | `code === 'Ok'`       |
+| `k8s`     | 不包装                 | `status.phase / conditions` | `phase === 'Running'` |
+| `raw`     | 不包装                 | 原样返回，`code` 固定 `Ok`  | 始终成功              |
+
+### 基本用法
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 使用内置 default 风格（推荐）
+dataHub.setAPIStyle('default');
+
+// 请求体自动包装为 { data: { ... } }
+// 响应自动解包，code !== 'Ok' 时自动抛出 DataHubError
+const data = await dataHub.request('/order/query', { orderId: '123' });
+console.log(data); // 业务数据，无需 .data
+```
+
+### 自定义 APIStyle
+
+实现 `DataHubAPIStyle` 接口即可适配自有后端协议：
+
+```ts
+import type {
+  DataHubAPIStyle,
+  DataHubAdapterRequest,
+  DataHubAdapterResponse,
+  DataHubAPIResult,
+} from '@aithe/aithe-ui';
+
+const myStyle: DataHubAPIStyle = {
+  name: 'my-api',
+  onRequest(req: DataHubAdapterRequest): void {
+    // 请求体包装：{ payload: 原始数据, timestamp: Date.now() }
+    req.data = { payload: req.data, timestamp: Date.now() };
+  },
+  onResponse<T>(res: DataHubAdapterResponse<T>): DataHubAPIResult<T> {
+    // 响应解包：{ success, errorMsg, result } → { code, message, data }
+    const body = res.data as any;
+    return {
+      code: body.success ? 'Ok' : 'Fail',
+      message: body.errorMsg ?? '',
+      data: body.result,
+    };
+  },
+  isSuccess(result: DataHubAPIResult): boolean {
+    return result.code === 'Ok';
+  },
+};
+
+dataHub.setAPIStyle(myStyle);
+```
+
+### 查询内置风格
+
+```ts
+import { getBuiltinStyle, getBuiltinStyleNames } from '@aithe/aithe-ui';
+
+// 获取内置风格实例
+const style = getBuiltinStyle('default');
+
+// 获取所有内置风格名称
+const names = getBuiltinStyleNames(); // ['default', 'k8s']
+```
+
+### 单次请求临时指定 APIStyle
+
+通过 `DataHubRequestOptions.apiStyle` 可以在单次请求中临时覆盖全局 APIStyle，无需修改全局设置：
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 使用内置风格名称
+const res1 = await dataHub.request('/api/foo', data, { apiStyle: 'k8s' });
+
+// 使用自定义 APIStyle 实例
+const res2 = await dataHub.request('/api/bar', data, { apiStyle: myStyle });
+
+// 不指定则使用全局 this.apiStyle
+const res3 = await dataHub.request('/api/baz', data);
+```
+
+这在以下场景非常有用：
+
+- 某个接口使用不同的后端协议（如大部分接口是 `default` 风格，个别接口是 `k8s` 风格）
+- 在领域 Service 封装中，为特定接口指定独立协议解析逻辑
+
+### 原始模式（Raw 风格）
+
+通过内置 `raw` 风格可以强制跳过本次请求的 APIStyle 处理（请求体包装和响应解包），直接返回原始 HTTP 响应数据：
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 使用内置 raw 风格，跳过 APIStyle 处理
+const raw = await dataHub.request('/api/foo', data, { apiStyle: 'raw' });
+// raw.data 为原始 JSON，不做任何业务协议解析
+```
+
+`raw` 风格的行为：
+
+- **请求阶段** — 不包装请求体，直接透传
+- **响应阶段** — 将 `res.data` 原样返回，`code` 固定为 `'Ok'`
+- **校验阶段** — 始终返回 `true`，不会因业务状态码抛出 `DataHubError`
+
+这在以下场景非常有用：
+
+- 对接不遵循统一业务协议的三方接口
+- 需要直接访问 HTTP 响应头或原始状态码
+- 临时调试后端返回的原始数据格式
+
+---
+
+## 类型参考
+
+### DataHubAdapterResponse\<T\>
+
+```ts
+interface DataHubAdapterResponse<T = unknown> {
+  ok: boolean; // HTTP 是否成功
+  status: number; // HTTP 状态码
+  data: T; // 响应体
+  headers?: Record<string, string>;
+}
+```
+
+### DataHubAPIResult\<T\>
+
+```ts
+interface DataHubAPIResult<T = unknown> {
+  code: string; // 业务状态码，"Ok" 表示成功
+  message: string; // 业务状态描述
+  data?: T; // 业务数据载荷
+}
+```
+
+### DataHubAPIStyle
+
+```ts
+interface DataHubAPIStyle {
+  readonly name: string;
+  onRequest(req: DataHubAdapterRequest): void;
+  onResponse<T = unknown>(res: DataHubAdapterResponse<T>): DataHubAPIResult<T>;
+  isSuccess(result: DataHubAPIResult): boolean;
+}
+```
+
+### DataHubRequestOptions
+
+```ts
+interface DataHubRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; // 默认 POST
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  timeout?: number; // 默认 30000
+  cacheTTL?: number; // 默认 60000
+  skipCache?: boolean;
+  skipDedup?: boolean;
+  skipIdempotent?: boolean;
+  mock?: boolean;
+  mockData?: unknown;
+  mockDelay?: number; // 默认 300
+  traceId?: string;
+  adapter?: string;
+  apiStyle?: DataHubAPIStyle | string; // 单次请求临时 APIStyle
+  [key: string]: unknown; // 扩展字段
+}
+```
+
+### DataHubConfig
+
+```ts
+interface DataHubConfig {
+  baseURL?: string;
+  defaultAdapter?: string; // 默认 "fetch"
+  defaultTimeout?: number; // 默认 30000
+  defaultCacheTTL?: number; // 默认 60000
+  headers?: Record<string, string>;
+  generateTraceId?: () => string;
+  traceHeaderKey?: string; // 默认 "X-B3-TraceId"
+  forceMock?: boolean;
+  onError?: (error: DataHubError, req: DataHubAdapterRequest) => void;
+  onRequest?: (req: DataHubAdapterRequest) => DataHubAdapterRequest | void;
+  onResponse?: (
+    res: DataHubAdapterResponse,
+    req: DataHubAdapterRequest,
+  ) => DataHubAdapterResponse | void;
+}
+```
+
+### DataHubAdapter
+
+```ts
+interface DataHubAdapter {
+  readonly name: string;
+  request<T = unknown>(req: DataHubAdapterRequest): Promise<DataHubAdapterResponse<T>>;
+  abort?(url: string): void;
+}
+```
+
+### DataHubStrategyConfig
+
+```ts
+interface DataHubStrategyConfig {
+  type: 'query' | 'submit';
+  cacheable: boolean; // query: true, submit: false
+  dedupable: boolean; // query: true, submit: false
+  idempotent: boolean; // query: false, submit: true
+  retryable: boolean; // query: true, submit: false
+}
+```
+
+---
+
+## DataHubCore API
+
+| 方法                               | 说明                    |
+| ---------------------------------- | ----------------------- |
+| `request<T>(url, data?, options?)` | 统一请求入口            |
+| `registerAdapter(adapter)`         | 注册适配器              |
+| `getAdapter(name)`                 | 获取已注册适配器        |
+| `setRequestInterceptor(handler)`   | 设置请求拦截器          |
+| `setResponseInterceptor(handler)`  | 设置响应拦截器          |
+| `setErrorHandler(handler)`         | 设置全局错误处理        |
+| `updateConfig(config)`             | 更新全局配置（合并）    |
+| `getConfig()`                      | 获取当前配置（只读）    |
+| `clearCache()`                     | 清空所有缓存            |
+| `clearDedup()`                     | 清空所有去重记录        |
+| `clearIdempotent()`                | 清空所有幂等锁          |
+| `onLoadingChange(fn)`              | 订阅 Loading 状态变更   |
+| `isLoading(url)`                   | 查询指定 URL 是否加载中 |
+
+---
+
+## 完整示例
+
+以下示例展示了一个典型的 Admin 应用的 DataHub 初始化流程：
+
+```ts
+// datahub/index.ts
+import dataHub, { type DataHubError } from '@aithe/aithe-ui';
+import { getToken, clearAuth } from '../store/auth';
+
+// 1. 配置请求拦截器（注入 Token）
+dataHub.setRequestInterceptor((req) => {
+  const token = getToken();
+  if (token) {
+    req.options.headers = {
+      ...req.options.headers,
+      Authorization: `Bearer ${token}`,
+    };
+  }
+  return req;
+});
+
+// 2. 配置全局错误处理
+dataHub.setErrorHandler((error: DataHubError, req) => {
+  console.error(`[DataHub] ${error.code} - ${error.message}`);
+  if (error.status === 401 || error.code === 'Unauthorized') {
+    clearAuth();
+    location.hash = '#/login';
+  }
+});
+
+// 3. 更新全局配置
+dataHub.updateConfig({
+  baseURL: '/api/admin',
+  defaultTimeout: 15000,
+  defaultCacheTTL: 30000,
+  headers: { 'Content-Type': 'application/json' },
+});
+```
+
+```ts
+// datahub/auth.ts
+import dataHub, { type DataHubRequestOptions } from '@aithe/aithe-ui';
+
+export interface LoginParams {
+  username: string;
+  password: string;
+}
+
+export interface LoginData {
+  token: string;
+  username: string;
+  role: string;
+}
+
+export async function login(params: LoginParams, options?: DataHubRequestOptions) {
+  return dataHub.request<LoginData>('/auth/login', params, {
+    ...options,
+    mock: true,
+    mockData: { token: 'mock-token', username: params.username, role: 'admin' },
+    skipIdempotent: true, // 允许重新登录
+  });
+}
+```
+
+```ts
+// datahub/dashboard.ts
+import dataHub, { type DataHubRequestOptions } from '@aithe/aithe-ui';
+
+export interface DashboardStats {
+  userCount: number;
+  roleCount: number;
+  uptime: string;
+}
+
+export async function getDashboardStats(options?: DataHubRequestOptions) {
+  return dataHub.request<DashboardStats>('/dashboard/query', undefined, {
+    ...options,
+    mock: true,
+    mockData: { userCount: 128, roleCount: 5, uptime: '99.9%' },
+  });
+}
+```
+
+---
+
+## 下一步
+
+- [使用指南](guide.md) — 组件通用 API、事件、插槽
+- [主题系统](theming.md) — 22 种内置主题、自定义主题
+- [国际化](i18n.md) — 多语言支持、自定义翻译
+- [API 参考](api/summary.md) — 全部组件详细 API