zentao-api 0.1.0 → 0.2.0-beta.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Catouse
+Copyright (c) 2026 Sun Hao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,190 +1,280 @@
-# [zentao-api](https://github.com/catouse/zentao-api)
+# zentao-api
 
-[![CI](https://github.com/catouse/zentao-api/actions/workflows/main.yml/badge.svg)](https://github.com/catouse/zentao-api/actions/workflows/main.yml)
+[![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)
 
-禅道 API 调用模块。
+Browser & Node.js SDK for [ZenTao](https://www.zentao.net) (禅道) API v2.
 
-## 使用方法
+`zentao-api` 是一个面向禅道 API v2 的轻量 JavaScript/TypeScript SDK，可用于 Node.js 18+、浏览器打包工具以及 CDN/script 标签场景。
 
-### 安装
+---
 
-```bash
-npm install --save zentao-api
+## 安装 / Install
+
+```sh
+npm install zentao-api
 ```
 
-### 请求任何禅道 API
+## 快速开始 / Quick Start
 
-通过构建 `Zentao` API 调用实例，你可以使用链式方法 ``zentao.m(moduleName).f(methodName)...get()`` 来非常方便调用禅道任何 API。
+### 创建客户端
 
-```js
-import { Zentao } form 'zentao-api';
+```ts
+import { ZentaoClient } from 'zentao-api';
 
-// 创建一个禅道 API 调用对象
-const zentao = new Zentao({
-  	url: 'https://demo.zentao.net/',
-  	account: 'demo',
-    password: '123456'
+const client = new ZentaoClient({
+  baseUrl: 'https://zentao.example.com',
+  token: 'your-token',
 });
 
-// 调用 product-all 获取所有产品信息
-const productAllResult = await zentao
-  	.m('product')
-  	.f('all')
-    .get();
-
-// 输出产品列表
-console.log('All products', productAllResult.data.products);
-
-// 调用 product-view 获取产品详细信息
-const productViewResult = await zentao
-		.m('product')
-    .f('view')
-    .withParams({productID: 1})
-    .get();
-
-// 输出产品信息
-console.log('All products', productViewResult.data.prodcut);
-
-// 调用 prodcut-add 添加新的产品到禅道
-const productCreateResult = await zentao
-    .m('product')
-    .f('create')
-    .post({
-      name: 'New product',
-      code: 'new_product_code'
-    });
-
-if (productCreateResult.status) {
-  	console.log('"New product" added.');
-}
+const products = await client.get('/products');
 ```
 
-你可以访问 <https://catouse.github.io/zentao-api/> 来查看所有可用 API 和详细示例。
+`baseUrl` 是禅道站点根地址。SDK 会在内部追加 `/api.php/v2`。
+
+### 账号密码登录
+
+如果还没有 token，可以使用账号密码登录：
 
-### 禅道 12 常用方法调用
+```ts
+const client = new ZentaoClient('https://zentao.example.com');
+const token = await client.login('admin', 'password');
+```
 
-针对禅道 12 版本，通过内置的 `Zentao12` 调用类可以直接调用一些常见方法：
+### 全局客户端与模块请求
 
-```js
-import { Zentao12 } form 'zentao-api';
+```ts
+import { ZentaoClient, request, setGlobalOptions } from 'zentao-api';
 
-// 创建一个禅道12 API 调用对象
-const zentao = new Zentao12({
-  	url: 'https://demo.zentao.net/',
-  	account: 'demo',
-    password: '123456'
+ZentaoClient.init({
+  baseUrl: 'https://zentao.example.com',
+  token: 'your-token',
 });
 
-// 调用 product-all 获取所有产品信息
-const productAllResult = await zentao.getProductList();
-// 输出产品列表
-console.log('All products', productAllResult.data.products);
+setGlobalOptions({ recPerPage: '50' });
+
+const result = await request('product/list', {});
+```
 
-// 调用 product-view 获取产品详细信息
-const productViewResult = await zentao.getProduct({productID: 1})
-// 输出产品信息
-console.log('All products', productViewResult.data.prodcut);
+单次调用的选项会覆盖全局选项：
 
-// 调用 prodcut-add 添加新的产品到禅道
-const productCreateResult = await zentao.addProduct({
-    name: 'New product',
-    code: 'new_product_code'
-});
-if (productCreateResult.status) {
-  	console.log('"New product" added.');
+```ts
+const result = await request('bug/list', { product: 1 }, { limit: '10' });
+```
+
+### 从本地 Profile 恢复
+
+SDK 支持将登录信息持久化到本地（Node.js: `~/.config/zentao/zentao.json`，浏览器: `localStorage`），后续可直接恢复客户端：
+
+```ts
+const client = await ZentaoClient.fromProfile();
+// 或指定 profile key
+const client = await ZentaoClient.fromProfile('admin@https://zentao.example.com');
+```
+
+## API 概览
+
+### 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 恢复客户端 |
+
+### 模块请求
+
+| 函数 | 说明 |
+|------|------|
+| `request(name, params?, options?)` | 按 `"module/action"` 格式调用已注册模块 |
+| `defineModules(modules, options?)` | 注册或扩展模块定义 |
+| `defineModuleActions(module, actions)` | 为已有模块追加或替换动作 |
+| `getModule(name)` | 获取模块定义 |
+| `getModuleAction(module, action)` | 获取指定动作定义 |
+| `setGlobalOptions(options)` | 设置全局默认选项 |
+| `getGlobalOptions()` | 获取当前全局选项 |
+
+## 错误处理
+
+SDK 所有传输层错误均通过 `ZentaoError` 抛出，包含稳定的错误码：
+
+```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);
+  }
 }
 ```
 
- `Zentao12` 实例上所有可用的方法包括：
+> **注意**：服务端返回 `{ status: "fail" }` 时 SDK 不会抛出异常，按原始响应内容返回。仅 HTTP/网络/超时等传输层错误会抛出 `ZentaoError`。
+
+## 扩展模块
+
+生成的模块定义来自 `scripts/update-registry.ts`。你可以在调用 `request()` 前扩展模块，或新增、替换动作。
 
-* addBug
-* addDept
-* addProduct
-* addProject
-* addTask
-* addUser
-* finishTask
-* getBug
-* getBugCreateParams
-* getBugList
-* getBugResolveParams
-* getDeptList
-* getProduct
-* getProductCreateParams
-* getProductList
-* getProject
-* getProjectCreateParams
-* getProjectList
-* getTask
-* getTaskCreateParams
-* getTaskFinishParams
-* getTaskList
-* getUserCreateParams
-* getUserList
-* resolveBug
+### 新增模块
 
-`Zentao12` 继承自 `Zentao`，所以你仍然可以在 `Zentao12` 上调用 `zentao.m().f()...get()` 链式方法来请求禅道提供的任何 API。
+```ts
+import { defineModules } from 'zentao-api';
 
-你可以访问 <https://catouse.github.io/zentao-api/> 来查看所有可用 API 和详细示例。
+defineModules({
+  name: 'custom',
+  actions: [
+    {
+      name: 'list',
+      type: 'list',
+      method: 'GET',
+      path: '/custom',
+      resultType: 'list',
+      resultGetter: 'items',
+    },
+  ],
+});
+```
 
-## 开发
+### 为已有模块追加动作
 
-该项目框架基于 [`TSdx`](https://tsdx.io/)，完全使用 [TypeScript](https://www.typescriptlang.org/) 开发。
+```ts
+import { defineModuleActions } from 'zentao-api';
 
-如果希望参与本项目开发，可以先了解以下内容。
+defineModuleActions('bug', {
+  name: 'archive',
+  type: 'action',
+  method: 'PUT',
+  path: '/bugs/{bugID}/archive',
+  pathParams: { bugID: 1 },
+  resultType: 'text',
+});
+```
 
-### 启动开发模式
+### 合并与替换
 
-在开发目录执行 `npm install` 来安装依赖，然后执行如下命令启动开发模式：
+同名模块默认**合并**定义：同名动作会替换，未知动作会追加。如需**整体替换**模块，传入 `{ replace: true }`：
 
-```bash
-npm start
+```ts
+defineModules(myModule, { replace: true });
 ```
 
-该命令会立即编译项目，并且在 /dist 目录生成编译后的文件，编译完成后改命令并不会退出，而是持续监听 `src/` 目录下的文件变更，并适时自动重新编译。
+如果扩展定义拆分在多个文件中，请在应用启动入口中显式导入这些文件，确保它们在调用 `request()` 前完成注册。
 
-### 构建
+## TypeScript 支持
 
-如果仅仅需要一次构建编译，只需要执行：
+SDK 提供完整的 TypeScript 类型定义，所有公共类型均可直接导入：
 
-```bash
-npm build
+```ts
+import type {
+  ZentaoClientOptions,
+  ModuleDefinition,
+  ModuleAction,
+  ResponseData,
+  RequestOptions,
+} from 'zentao-api';
 ```
 
-### 测试
+## 浏览器
 
-该项目使用 `jest` 进行测试，执行如下命令即可：
+浏览器打包工具可以正常导入这个包：
 
-```bash
-npm test
+```ts
+import { ZentaoClient } from 'zentao-api';
 ```
 
-### 生成 API 文档
+如果使用 script 标签，请使用浏览器构建包，并从 `window.ZentaoAPI` 读取 API：
 
-该项目使用 [TypeDoc](https://typedoc.org/) 来根据源码中的注视自动生成 API 文档，只需要执行如下命令：
+```html
+<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**：浏览器直接请求要求禅道服务器允许 CORS。浏览器代码也会把 token 暴露给前端；如果这不可接受，请使用后端代理。
+>
+> **TLS**：`insecure` TLS 选项仅适用于 Node.js，在浏览器运行时会抛出错误。
 
-```bash
-npm run doc
+## 测试
+
+```sh
+bun test              # 单元测试
+bun run test:coverage # 含覆盖率的单元测试
+bun run check         # 完整 CI 流程：测试 + 类型检查 + 注册表 + 构建 + 冒烟测试
 ```
 
-### 包大小分析
+### 真实环境测试
 
-该项目使用 [`size-limit`](https://github.com/ai/size-limit) 来帮助分析包大小，只需要执行如下命令：
+真实环境测试需要连接到运行中的禅道实例，不包含在默认 `bun test` 中：
 
-```bash
-npm run size
+```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` |
 
-```bash
-npm run analyze
+## 项目结构
+
+```
+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/               # 构建产物
 ```
 
-### 代码检查
+## 贡献
 
-执行：
+欢迎贡献代码！请确保提交前通过完整检查：
 
-```bash
-npm run lint
+```sh
+bun run check
 ```
+
+### 提交规范
+
+使用英文，前缀格式：`*|+|- <type>: <message>`
+
+- `*` — 修改 (change)
+- `+` — 新增 (add)
+- `-` — 移除 (remove)
+
+不使用 emoji。
+
+## 许可证 / License
+
+[MIT](./LICENSE)