qing-client 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # qing-client
 
-Qing 平台统一 SDK - 插件化架构 (v2)
+Qing 平台统一 SDK - 插件化架构
 
 ---
 
@@ -11,6 +11,7 @@ Qing 平台统一 SDK - 插件化架构 (v2)
 - **前后端统一**：一套 SDK 支持前端（网关）和后端（直连）两种模式
 - **自动 Token 管理**：全局 setToken/clearToken 自动同步到所有服务
 - **服务隔离**：每个服务独立目录，互不影响
+- **HTTP 错误监控**：支持 `onHttpError` / `onUnauthorized` 回调，便于统一处理
 
 ---
 
@@ -82,37 +83,39 @@ await client.setToken('xxx');
 
 ---
 
-## 可用服务（17 个）
+## 可用服务（15 个）
 
 ### 核心服务
 
-| 服务 | 说明 | 注册名 |
-|------|------|--------|
-| AuthService | 认证与登录 | `auth` |
-| MsgService | 消息中心 | `msg` |
-| UserService | 用户管理 | `user` |
-| TokenService | Token 管理（微信等） | `token` |
-| FileService | 文件服务 | `file` / `files` |
+| 服务 | 说明 | 注册名 | API 文档 |
+|------|------|--------|----------|
+| AuthService | 认证与登录 | `auth` | [auth.md](./docs/api/auth.md) |
+| MsgService | 消息中心 / 邮件 / 飞书 | `msg` | [msg.md](./docs/api/msg.md) |
+| UserService | 用户管理 | `user` | [user.md](./docs/api/user.md) |
+| TokenService | 微信 Token 管理 | `token` | [token.md](./docs/api/token.md) |
+| FileService | 文件与文件夹管理 | `file` | [file.md](./docs/api/file.md) |
 
 ### AI 相关
 
-| 服务 | 说明 | 注册名 |
-|------|------|--------|
-| AiService | AI 对话/会话 | `ai` |
-| AigcService | AIGC 能力 | `aigc` |
-| ProviderService | 大模型供应商 | `providers` |
-| UsageService | 用量统计 | `providers` |
+| 服务 | 说明 | 注册名 | API 文档 |
+|------|------|--------|----------|
+| AiService | AI 对话 / 助手 / 会话 | `ai` | [ai.md](./docs/api/ai.md) |
+| AigcService | AIGC 生成与图像处理 | `aigc` | [aigc.md](./docs/api/aigc.md) |
+| ProviderService | 大模型供应商管理 | `provider` | [provider.md](./docs/api/provider.md) |
+| UsageService | Token 用量统计 | `usage` | [usage.md](./docs/api/usage.md) |
 
 ### 业务服务
 
-| 服务 | 说明 | 注册名 |
-|------|------|--------|
-| AuditLogService | 审计日志 | `logs` |
-| FrontHostService | 静态 HTML 托管 | `gateway-h5` |
-| OrgService | 组织与多租户 | `org` |
-| DeliveryStreamService | 投递流 | `delivery-stream` |
-| EzAbilityService | Ez AI 能力 | `ez-ability` |
-| ImService | IM 群组 | `im` |
+| 服务 | 说明 | 注册名 | API 文档 |
+|------|------|--------|----------|
+| AuditLogService | 审计日志 | `audit` | [audit.md](./docs/api/audit.md) |
+| FrontHostService | 前端 HTML 托管 | `fronthost` | [fronthost.md](./docs/api/fronthost.md) |
+| OrgService | 组织 / 项目 / 应用管理 | `org` | [org.md](./docs/api/org.md) |
+| DeliveryStreamService | 投递流 / 版本 / 需求 | `deliveryStream` | [delivery-stream.md](./docs/api/delivery-stream.md) |
+| EzAbilityService | AI 需求枚举与 PRD 生成 | `ezAbility` | [ez-ability.md](./docs/api/ez-ability.md) |
+| ImService | IM 群组与消息 | `im` | [im.md](./docs/api/im.md) |
+
+> **注册名** 即 `client.services.<注册名>` 中的 key。完整 API 参考见 [docs/api/](./docs/api/README.md)。
 
 ---
 
@@ -213,13 +216,30 @@ client.setUserContext({
 
 ---
 
+## HTTP 错误监控
+
+```typescript
+const client = new Client({
+  gatewayUrl: '...',
+  onHttpError(statusCode, error, ctx) {
+    console.error(`[${ctx.serviceName}] ${ctx.path} → ${statusCode}`);
+    if (statusCode >= 500) reportToSentry(error);
+  },
+  onUnauthorized() {
+    router.push('/login');
+  },
+});
+```
+
+---
+
 ## 新增服务
 
 参见 [SDK-GENERATION.md](./docs/SDK-GENERATION.md)
 
 1. 在 `src/services/{name}/` 创建服务目录
 2. 生成 `types.ts` 和 `{Name}Service.ts`
-3. 在 `src/services/index.ts` 和 `src/index.ts` 添加导出
+3. 在 `src/index.ts` 添加导出
 4. 使用方通过 `.use(YourService)` 注册
 
 ---
@@ -233,11 +253,11 @@ src/
 │   ├── BaseClient.ts        # 服务基类
 │   └── index.ts
 ├── types/                   # 公共类型和契约
-│   ├── common.ts            # 通用类型
-│   ├── config.ts            # 配置类型
-│   ├── service-contract.ts  # 服务契约
+│   ├── common.ts            # 通用类型（ApiResponse / TokenStorage 等）
+│   ├── config.ts            # 配置类型（ClientConfig）
+│   ├── service-contract.ts  # 服务契约（ServicePlugin / TokenAware 等）
 │   └── index.ts
-├── services/                # 服务目录（17 个服务）
+├── services/                # 服务目录（15 个服务）
 │   ├── auth/                # 认证服务
 │   ├── msg/                 # 消息服务
 │   ├── user/                # 用户服务
@@ -255,7 +275,7 @@ src/
 │   ├── im/                  # IM 服务
 │   └── index.ts
 ├── docs/
-│   └── SDK-GENERATION.md    # 生成指南
+│   └── SDK-GENERATION.md    # 服务生成指南
 └── index.ts                 # 包入口
 ```
 
@@ -270,24 +290,12 @@ npm install
 # 构建
 npm run build
 
-# 开发模式
-npm run dev
+# 发布
+npm run rele
 ```
 
 ---
 
-## 与旧版对比
-
-| 方面 | 旧版 (v0.x) | 新版 (v2.0) |
-|------|------------|-------------|
-| 新增服务 | 改 6+ 文件 | 改 2 文件 + 注册 |
-| 类型推导 | 手动维护 | Module Augmentation 自动 |
-| Token 管理 | 遍历硬编码 | 自动收集 TokenAware |
-| 服务隔离 | 耦合在一起 | 完全独立目录 |
-| 代码重复 | setToken 遍历 16 次 | 自动收集处理 |
-
----
-
 ## License
 
 MIT

package/docs/SDK-GENERATION.md

@@ -0,0 +1,327 @@
+# SDK 服务生成指南
+
+本文档描述如何为新的后端服务生成对应的 SDK 代码。
+
+---
+
+## 目录结构约定
+
+```
+src/
+├── core/                    # 核心框架（不要修改）
+│   ├── Client.ts            # 主客户端
+│   ├── BaseClient.ts        # 服务基类
+│   └── index.ts
+├── types/                   # 公共类型（不要修改）
+│   ├── common.ts
+│   ├── config.ts
+│   ├── service-contract.ts
+│   └── index.ts
+├── services/                # 服务目录
+│   ├── auth/                # 示例服务
+│   │   ├── AuthService.ts   # 服务实现
+│   │   ├── types.ts         # 类型定义
+│   │   └── index.ts         # 导出
+│   ├── msg/
+│   │   └── ...
+│   └── {新服务名}/          # 新服务放这里
+│       └── ...
+├── docs/
+│   └── SDK-GENERATION.md    # 本文档
+└── index.ts                 # 包入口
+```
+
+---
+
+## 生成步骤
+
+### 第一步：创建服务目录
+
+在 `src/services/` 下创建以服务名命名的目录（如 `im/`）。
+
+```
+src/services/im/
+├── ImService.ts
+├── types.ts
+└── index.ts
+```
+
+---
+
+### 第二步：生成类型定义 (`types.ts`)
+
+根据后端 API 接口定义，生成对应的 TypeScript 类型。
+
+```typescript
+// src/services/im/types.ts
+
+export interface Group {
+  id: string;
+  name: string;
+  ownerId: string;
+  memberCount: number;
+  createdAt: string;
+}
+
+export interface CreateGroupRequest {
+  name: string;
+  memberIds: string[];
+  requireAdmin?: boolean;
+}
+
+export interface GroupQueryParams {
+  page?: number;
+  limit?: number;
+}
+
+// ... 其他类型
+```
+
+---
+
+### 第三步：生成服务实现 (`ImService.ts`)
+
+**必须遵循以下模板**：
+
+```typescript
+// src/services/im/ImService.ts
+
+import { BaseClient } from '../../core/BaseClient';
+import { ClientConfig, TokenStorage, RequestOptions } from '../../types';
+import { Group, CreateGroupRequest, GroupQueryParams } from './types';
+
+/**
+ * IM 群组服务
+ *
+ * @example
+ * ```typescript
+ * const groups = await client.services.im.getGroups();
+ * ```
+ */
+export class ImService extends BaseClient {
+  // ========== 必须的静态属性 ==========
+  /** 服务名称（用于注册到 client.services 的 key） */
+  static readonly serviceName = 'im';
+
+  /** API 路径（对应 /api/im） */
+  static readonly servicePath = 'im';
+
+  // ========== 必须的实例属性 ==========
+  get serviceName(): string {
+    return 'im';
+  }
+
+  // ========== 构造函数 ==========
+  constructor(config: ClientConfig, tokenStorage: TokenStorage) {
+    super(config, 'im', tokenStorage);
+  }
+
+  // ========== 业务方法 ==========
+
+  async getGroups(params?: GroupQueryParams, options?: RequestOptions): Promise<Group[]> {
+    return this.request<Group[]>('/groups', {
+      ...options,
+      method: 'GET',
+      params,
+    });
+  }
+
+  async createGroup(request: CreateGroupRequest, options?: RequestOptions): Promise<Group> {
+    return this.request<Group>('/groups', {
+      ...options,
+      method: 'POST',
+      body: request,
+    });
+  }
+
+  // ... 其他方法
+}
+
+// ========== 必须的类型扩展 ==========
+/**
+ * 扩展 Client.Services 接口
+ * 使 client.services.im 具有完整类型推导
+ */
+declare module '../../core/Client' {
+  interface Services {
+    im: ImService;
+  }
+}
+```
+
+---
+
+### 第四步：创建导出文件 (`index.ts`)
+
+```typescript
+// src/services/im/index.ts
+
+export { ImService } from './ImService';
+export * from './types';
+```
+
+---
+
+### 第五步：在包入口添加导出
+
+在 `src/index.ts` 中添加服务类和类型的导出：
+
+```typescript
+// src/index.ts
+
+// ... 已有代码 ...
+
+// ========== 服务 ==========
+export { ImService } from './services/im/ImService';  // 新增
+
+// ========== 服务类型 ==========
+export type {
+  Group,
+  CreateGroupRequest,
+  GroupQueryParams,
+} from './services/im/types';  // 新增
+```
+
+---
+
+### 第六步（如需后端直连）：在 ClientConfig 中添加服务 URL
+
+如果需要后端模式直连该服务，需在 `src/types/config.ts` 的 `ClientConfig` 接口中添加对应的 URL 字段：
+
+```typescript
+export interface ClientConfig {
+  // ...
+  /** IM 服务地址 */
+  imServiceUrl?: string;
+  // ...
+}
+```
+
+---
+
+## 服务类必须实现的接口
+
+```typescript
+class YourService extends BaseClient {
+  static readonly serviceName = 'yourService';     // 必填：注册到 client.services 的 key
+  static readonly servicePath = 'your-service';    // 必填：API 路径前缀
+
+  get serviceName(): string { return 'yourService'; } // 必填：实例属性
+
+  constructor(config: ClientConfig, tokenStorage: TokenStorage) {
+    super(config, 'your-service', tokenStorage);   // servicePath 传给 BaseClient
+  }
+
+  // 业务方法...
+}
+
+// 类型扩展（必填）
+declare module '../../core/Client' {
+  interface Services {
+    yourService: YourService;
+  }
+}
+```
+
+> **注意**：`serviceName`（camelCase）用于注册和访问 `client.services.xxx`；`servicePath`（kebab-case）用于拼接 API URL `/api/xxx`。两者可能不同。
+
+---
+
+## 请求方法说明
+
+BaseClient 提供了两个请求方法：
+
+### `request<T>(path, options)`
+
+用于普通请求。
+
+```typescript
+// GET 请求
+return this.request<User>('/user/123', {
+  method: 'GET',
+});
+
+// POST 请求
+return this.request<User>('/user', {
+  method: 'POST',
+  body: userData,
+});
+
+// 带查询参数
+return this.request<User[]>('/users', {
+  method: 'GET',
+  params: { page: 1, limit: 10 },
+});
+```
+
+### `paginatedRequest<T>(path, options)`
+
+用于分页请求，返回带 pagination 的响应。
+
+```typescript
+return this.paginatedRequest<User>('/users', {
+  method: 'GET',
+  params: { page: 1, limit: 10 },
+});
+// 返回: { success, data: User[], pagination: { page, perPage, total, totalPages } }
+```
+
+---
+
+## 使用方注册示例
+
+```typescript
+import { Client, AuthService, MsgService, ImService } from 'qing-client';
+
+const client = new Client({
+  gatewayUrl: 'https://api.example.com',
+  projectId: 'xxx',
+})
+  .use(AuthService)
+  .use(MsgService)
+  .use(ImService);
+
+await client.setToken('xxx');
+
+// 完整类型推导
+client.services.im.getGroups();
+```
+
+---
+
+## 检查清单
+
+生成新服务后，请检查：
+
+- [ ] 服务目录已创建在 `src/services/{name}/`
+- [ ] `types.ts` 包含所有请求/响应类型
+- [ ] 服务类继承 `BaseClient`
+- [ ] 静态属性 `serviceName` 和 `servicePath` 已定义
+- [ ] 实例属性 `get serviceName()` 已实现（返回值与静态 `serviceName` 一致）
+- [ ] 构造函数签名为 `(config: ClientConfig, tokenStorage: TokenStorage)`
+- [ ] `declare module` 类型扩展已添加（key 与 `serviceName` 一致）
+- [ ] `index.ts` 导出文件已创建
+- [ ] `src/index.ts` 已添加服务类和类型的导出
+- [ ] （可选）`src/types/config.ts` 已添加后端模式服务 URL 字段
+
+---
+
+## AI 提示词模板
+
+如果使用 AI 生成 SDK，可以使用以下提示词：
+
+```
+请根据以下后端 API 接口定义，生成 qing-client SDK 的服务代码。
+
+接口定义：
+[粘贴 API 文档或接口描述]
+
+要求：
+1. 遵循 SDK-GENERATION.md 中的目录结构和代码模板
+2. 服务名为 {service-name}
+3. 生成 types.ts（类型定义）和 {ServiceName}.ts（服务实现）
+4. 必须包含静态属性 serviceName 和 servicePath
+5. 必须在文件末尾添加 declare module 类型扩展
+6. 所有方法使用 this.request<T>() 进行请求
+7. 添加完整的 JSDoc 注释
+```

package/docs/api/README.md

@@ -0,0 +1,81 @@
+# API 参考文档
+
+qing-client SDK 所有服务的 API 文档索引。
+
+每个文档包含：方法列表、参数类型、返回值类型、使用示例。
+
+---
+
+## 核心服务
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AuthService | 认证与登录 | 9 | [auth.md](./auth.md) |
+| MsgService | 消息中心 / 邮件 / 飞书 | 12 | [msg.md](./msg.md) |
+| UserService | 用户管理 | 10 | [user.md](./user.md) |
+| TokenService | 微信 Token 管理 | 5 | [token.md](./token.md) |
+| FileService | 文件与文件夹管理 | 22 | [file.md](./file.md) |
+
+## AI 相关
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AiService | AI 对话 / 助手 / 会话 | 30 | [ai.md](./ai.md) |
+| AigcService | AIGC 生成与图像处理 | 14 | [aigc.md](./aigc.md) |
+| ProviderService | 大模型供应商管理 | 16 | [provider.md](./provider.md) |
+| UsageService | Token 用量统计 | 6 | [usage.md](./usage.md) |
+
+## 业务服务
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AuditLogService | 审计日志 | 2 | [audit.md](./audit.md) |
+| FrontHostService | 前端 HTML 托管 | 9 | [fronthost.md](./fronthost.md) |
+| OrgService | 组织 / 项目 / 应用管理 | 27 | [org.md](./org.md) |
+| DeliveryStreamService | 投递流 / 版本 / 需求 | 17 | [delivery-stream.md](./delivery-stream.md) |
+| EzAbilityService | AI 需求枚举与 PRD 生成 | 14 | [ez-ability.md](./ez-ability.md) |
+| ImService | IM 群组与消息 | 3 | [im.md](./im.md) |
+
+---
+
+## 通用约定
+
+### RequestOptions
+
+所有方法的最后一个参数都支持 `RequestOptions`，用于覆盖本次请求的上下文：
+
+```typescript
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  headers?: Record<string, string>;
+  params?: Record<string, any>;
+  body?: any;
+  projectId?: string;   // 覆盖本次请求的项目 ID
+  orgId?: string;       // 覆盖本次请求的组织 ID
+  appId?: string;       // 覆盖本次请求的应用 ID
+  userContext?: UserContext; // 覆盖本次请求的用户上下文（后端模式）
+}
+```
+
+### 响应格式
+
+SDK 会自动解包 `{ success, data, message }` 格式的响应，方法返回值直接是 `data` 部分。
+
+分页请求返回 `PaginatedResponse<T>`：
+
+```typescript
+interface PaginatedResponse<T> {
+  success: boolean;
+  data: T[];
+  pagination: {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+### 错误处理
+
+请求失败时抛出 `Error`，错误消息格式为 `[服务名服务] 错误信息 (路径: /xxx)`。可通过 `ClientConfig.onHttpError` 回调统一处理。