zentao-api 0.2.0-beta.1 → 0.2.0

package/README.md

@@ -1,14 +1,24 @@
 # zentao-api
 
+[![npm version](https://img.shields.io/npm/v/zentao-api)](https://www.npmjs.com/package/zentao-api)
+[![license](https://img.shields.io/npm/l/zentao-api)](./LICENSE)
+[![node](https://img.shields.io/node/v/zentao-api)](https://nodejs.org)
+
+Browser & Node.js SDK for [ZenTao](https://www.zentao.net) (禅道) API v2.
+
 `zentao-api` 是一个面向禅道 API v2 的轻量 JavaScript/TypeScript SDK，可用于 Node.js 18+、浏览器打包工具以及 CDN/script 标签场景。
 
-## 安装
+---
+
+## 安装 / Install
 
 ```sh
 npm install zentao-api
 ```
 
-## 客户端
+## 快速开始 / Quick Start
+
+### 创建客户端
 
 ```ts
 import { ZentaoClient } from 'zentao-api';
@@ -23,14 +33,16 @@ const products = await client.get('/products');
 
 `baseUrl` 是禅道站点根地址。SDK 会在内部追加 `/api.php/v2`。
 
-如果还没有 token：
+### 账号密码登录
+
+如果还没有 token，可以使用账号密码登录：
 
 ```ts
 const client = new ZentaoClient('https://zentao.example.com');
 const token = await client.login('admin', 'password');
 ```
 
-## 全局客户端与模块请求
+### 全局客户端与模块请求
 
 ```ts
 import { ZentaoClient, request, setGlobalOptions } from 'zentao-api';
@@ -51,51 +63,71 @@ const result = await request('product/list', {});
 const result = await request('bug/list', { product: 1 }, { limit: '10' });
 ```
 
-## 真实环境测试
+### 从本地 Profile 恢复
 
-真实环境测试不会包含在默认 `bun test` 或 `bun run check` 中，需要显式运行：
+SDK 支持将登录信息持久化到本地（Node.js: `~/.config/zentao/zentao.json`，浏览器: `localStorage`），后续可直接恢复客户端：
 
-```sh
-bun run test:real
+```ts
+const client = await ZentaoClient.fromProfile();
+// 或指定 profile key
+const client = await ZentaoClient.fromProfile('admin@https://zentao.example.com');
 ```
 
-如果需要保留本轮测试创建出的临时数据以便手动检查：
+## API 概览
 
-```sh
-bun run test:real -- --keep-test-data
-```
+### ZentaoClient
 
-也可以用环境变量开启同样的行为：
+| 方法 | 说明 |
+|------|------|
+| `client.get<T>(path)` | GET 请求 |
+| `client.post<T>(path, body)` | POST 请求 |
+| `client.put<T>(path, body)` | PUT 请求 |
+| `client.delete<T>(path)` | DELETE 请求 |
+| `client.login(account, password)` | 账号密码登录，返回 token |
+| `client.request(path, options?)` | 通用请求（底层方法） |
+| `ZentaoClient.init(options)` | 创建全局单例客户端 |
+| `ZentaoClient.create(options)` | 工厂方法创建客户端 |
+| `ZentaoClient.fromProfile(key?)` | 从持久化 profile 恢复客户端 |
 
-```sh
-ZENTAO_KEEP_TEST_DATA=true bun run test:real
-```
+### 模块请求
 
-测试会优先读取 `.env.local`，如果不存在则读取 `env.local`。支持的变量：
+| 函数 | 说明 |
+|------|------|
+| `request(name, params?, options?)` | 按 `"module/action"` 格式调用已注册模块 |
+| `defineModules(modules, options?)` | 注册或扩展模块定义 |
+| `defineModuleActions(module, actions)` | 为已有模块追加或替换动作 |
+| `getModule(name)` | 获取模块定义 |
+| `getModuleAction(module, action)` | 获取指定动作定义 |
+| `setGlobalOptions(options)` | 设置全局默认选项 |
+| `getGlobalOptions()` | 获取当前全局选项 |
 
-```ini
-ZENTAO_URL=https://zentao.example.com
-ZENTAO_ACCOUNT=admin
-ZENTAO_PASSWORD=password
-# 或直接提供 Token
-ZENTAO_TOKEN=your-token
-# 可选
-ZENTAO_REVIEWER=admin
-ZENTAO_KEEP_TEST_DATA=false
-ZENTAO_TIMEOUT=30000
-ZENTAO_INSECURE=false
-```
+## 错误处理
 
-`ZENTAO_REVIEWER` 用于启用了需求评审规则的环境；未设置时会复用 `ZENTAO_ACCOUNT`。
+SDK 所有传输层错误均通过 `ZentaoError` 抛出，包含稳定的错误码：
 
-运行时会先打印脱敏后的环境信息，然后创建一个名称带 `zentao-api-real-` 前缀的临时产品。后续每个 API 步骤都会打印步骤名、接口名和关键结果。测试会围绕这个产品执行一条可回收的真实写入流程：验证产品详情/列表/更新，创建并查询 3 个需求，创建/更新/查询产品计划并把需求关联到计划，创建/更新项目和执行，基于需求创建 3 个任务并验证任务列表、详情、优先级修改、启动、完成和删除，再创建 3 个 Bug 并验证列表、详情、描述修改和解决。默认清理阶段会按任务、Bug、执行、项目、需求、计划、产品的逆序尽量删除所有临时数据；传入 `--keep-test-data` 时会跳过最终清理并打印保留数据的关键 ID。
+```ts
+import { ZentaoError } from 'zentao-api';
+
+try {
+  await client.get('/products');
+} catch (error) {
+  if (error instanceof ZentaoError) {
+    console.error(error.code);    // e.g. 'E_HTTP_ERROR', 'E_TIMEOUT', 'E_NETWORK_ERROR'
+    console.error(error.message);
+  }
+}
+```
+
+> **注意**：服务端返回 `{ status: "fail" }` 时 SDK 不会抛出异常，按原始响应内容返回。仅 HTTP/网络/超时等传输层错误会抛出 `ZentaoError`。
 
 ## 扩展模块
 
-生成的模块定义来自 `scripts/update-registry.ts`。你可以在调用 `request()` 前扩展模块，或新增、替换动作。同名模块默认合并定义：同名动作会替换，未知动作会追加；需要整体替换模块时传入 `{ relace: true }`。
+生成的模块定义来自 `scripts/update-registry.ts`。你可以在调用 `request()` 前扩展模块，或新增、替换动作。
+
+### 新增模块
 
 ```ts
-import { defineModuleActions, defineModules } from 'zentao-api';
+import { defineModules } from 'zentao-api';
 
 defineModules({
   name: 'custom',
@@ -110,19 +142,47 @@ defineModules({
     },
   ],
 });
+```
+
+### 为已有模块追加动作
+
+```ts
+import { defineModuleActions } from 'zentao-api';
 
 defineModuleActions('bug', {
   name: 'archive',
   type: 'action',
   method: 'PUT',
   path: '/bugs/{bugID}/archive',
-  pathParams: { bugID: 1 },
+  pathParams: { bugID: 'Bug ID' },
   resultType: 'text',
 });
 ```
 
+### 合并与替换
+
+同名模块默认**合并**定义：同名动作会替换，未知动作会追加。如需**整体替换**模块，传入 `{ replace: true }`：
+
+```ts
+defineModules(myModule, { replace: true });
+```
+
 如果扩展定义拆分在多个文件中，请在应用启动入口中显式导入这些文件，确保它们在调用 `request()` 前完成注册。
 
+## TypeScript 支持
+
+SDK 提供完整的 TypeScript 类型定义，所有公共类型均可直接导入：
+
+```ts
+import type {
+  ZentaoClientOptions,
+  ModuleDefinition,
+  ModuleAction,
+  ResponseData,
+  RequestOptions,
+} from 'zentao-api';
+```
+
 ## 浏览器
 
 浏览器打包工具可以正常导入这个包：
@@ -134,13 +194,77 @@ import { ZentaoClient } from 'zentao-api';
 如果使用 script 标签，请使用浏览器构建包，并从 `window.ZentaoAPI` 读取 API：
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/zentao-api@1.0.0/dist/browser/zentao-api.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/zentao-api@latest/dist/browser/zentao-api.global.js"></script>
 <script>
   console.log(window.ZentaoAPI.VERSION, window.ZentaoAPI.BUILD);
   const client = new window.ZentaoAPI.ZentaoClient('https://zentao.example.com');
 </script>
 ```
 
-浏览器直接请求要求禅道服务器允许 CORS。浏览器代码也会把 token 暴露给前端；如果这不可接受，请使用后端代理。
+> **CORS**：浏览器直接请求要求禅道服务器允许 CORS。浏览器代码也会把 token 暴露给前端；如果这不可接受，请使用后端代理。
+>
+> **TLS**：`insecure` TLS 选项仅适用于 Node.js，在浏览器运行时会抛出错误。
+
+## 测试
+
+```sh
+bun test              # 单元测试
+bun run test:coverage # 含覆盖率的单元测试
+bun run check         # 完整 CI 流程：测试 + 类型检查 + 注册表 + 构建 + 冒烟测试
+```
+
+### 真实环境测试
+
+真实环境测试需要连接到运行中的禅道实例，不包含在默认 `bun test` 中：
+
+```sh
+bun run test:real
+bun run test:real -- --keep-test-data   # 保留临时数据以便手动检查
+```
+
+测试会优先读取 `.env.local`，如果不存在则读取 `env.local`。支持的环境变量：
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ZENTAO_URL` | 禅道站点地址 | *(必填)* |
+| `ZENTAO_ACCOUNT` | 登录账号 | *(必填)* |
+| `ZENTAO_PASSWORD` | 登录密码 | *(必填)* |
+| `ZENTAO_TOKEN` | 直接提供 Token（替代账号密码） | — |
+| `ZENTAO_REVIEWER` | 需求评审人（未设置时复用 `ZENTAO_ACCOUNT`） | — |
+| `ZENTAO_KEEP_TEST_DATA` | 保留临时测试数据 | `false` |
+| `ZENTAO_TIMEOUT` | 请求超时（ms） | `30000` |
+| `ZENTAO_INSECURE` | 跳过 TLS 证书验证 | `false` |
+
+## 项目结构
+
+```
+zentao-api/
+├── src/
+│   ├── client/         # ZentaoClient 核心实现
+│   ├── modules/        # 模块注册表与解析逻辑
+│   │   ├── generated.ts  # 自动生成，勿手动编辑
+│   │   ├── registry.ts   # 运行时注册表
+│   │   └── resolve.ts    # 路径模板与参数解析
+│   ├── request/        # 高阶请求函数
+│   ├── profiles/       # 本地 profile 持久化
+│   ├── misc/           # 错误、全局选项、环境检测
+│   ├── types/          # TypeScript 类型定义
+│   ├── utils/          # 通用工具函数
+│   └── index.ts        # 公共 API 入口
+├── scripts/            # 构建与代码生成脚本
+├── tests/              # 单元测试与真实环境测试
+├── data/               # OpenAPI 规范文件
+└── dist/               # 构建产物
+```
+
+## 贡献
+
+欢迎贡献代码！请确保提交前通过完整检查：
+
+```sh
+bun run check
+```
+
+## 许可证 / License
 
-`insecure` TLS 选项仅适用于 Node.js，在浏览器运行时会抛出错误。
+[MIT](./LICENSE)