zentao-api 0.6.9 → 0.7.1

package/dist/modules/override.js

@@ -1,7 +1,28 @@
-import { extendModuleAction, defineModuleActions } from './define.js';
+import { extendModuleAction, defineModules, defineModuleActions } from './define.js';
 import { extractResult } from './resolve.js';
 import { snapshotToMarkdown } from '../utils/doc-helper/markdown.js';
 import { isRecord } from '../utils/index.js';
+import { request } from '../request/index.js';
+import { ZentaoError } from '../misc/errors.js';
+/** 这些内置接口要求 JSON，不能把 HTTP 200 的 PHP/SQL 错误文本视为成功。 */
+const requestJSON = async ({ request: command, body, bodyType, client, timeout, insecure }) => {
+    const response = await client.request(command.path, {
+        method: command.action.method.toUpperCase(),
+        query: command.query, body, bodyType, timeout, insecure, responseType: 'response',
+    });
+    const responseText = await response.text();
+    try {
+        return JSON.parse(responseText);
+    }
+    catch {
+        return {
+            status: 'fail',
+            message: `Invalid JSON response from ${command.module}/${command.action.name}.`,
+            httpStatus: response.status,
+            responseText,
+        };
+    }
+};
 /**
  * 内置覆盖 / 扩展定义。
  *
@@ -64,6 +85,264 @@ import { isRecord } from '../utils/index.js';
  * @internal
  */
 export function applyBuiltinOverrides() {
+    defineModules({
+        name: 'db',
+        display: '数据库',
+        actions: [
+            {
+                name: 'query',
+                minVersion: ['22.7', 'biz13.7', 'max8.7', 'ipd5.7'],
+                display: '执行 SQL 查询',
+                description: '返回查询结果行及分页；使用 raw: true 可获取原始响应中的 SQL、列信息和执行耗时。',
+                type: 'list',
+                method: 'post',
+                path: '/db/query',
+                resultType: 'list',
+                resultGetter: 'rows',
+                pagerGetter: { pageID: 'page', recPerPage: 'limit', recTotal: 'total' },
+                request: requestJSON,
+                requestBody: {
+                    required: true,
+                    schema: {
+                        type: 'object',
+                        required: ['sql'],
+                        properties: {
+                            sql: { type: 'string', description: 'SQL 查询语句' },
+                            page: { type: 'integer', description: '页码，默认 1' },
+                            limit: { type: 'integer', description: '每页记录数，默认 100' },
+                        },
+                    },
+                    example: { sql: 'select * from zt_config', page: 4, limit: 3 },
+                },
+            },
+            {
+                name: 'tables',
+                minVersion: ['22.7', 'biz13.7', 'max8.7', 'ipd5.7'],
+                display: '获取数据库表列表',
+                type: 'list',
+                method: 'get',
+                path: '/db/tables',
+                resultType: 'list',
+                resultGetter: 'tables',
+                request: requestJSON,
+            },
+            {
+                name: 'table',
+                minVersion: ['22.7', 'biz13.7', 'max8.7', 'ipd5.7'],
+                display: '获取数据库表结构',
+                description: 'meta 返回表信息、主键和列定义；sql 返回包含表信息、dialect 和建表 SQL 的对象。',
+                type: 'get',
+                method: 'get',
+                path: '/db/tables/{table}',
+                pathParams: { table: '数据库表名，例如 zt_config' },
+                params: [{
+                        name: 'type',
+                        type: 'string',
+                        description: '表结构返回格式',
+                        defaultValue: 'meta',
+                        options: [{ value: 'meta', label: '元数据' }, { value: 'sql', label: '建表 SQL' }],
+                    }],
+                resultType: 'object',
+                resultGetter: data => isRecord(data) ? data.table ?? data : data,
+                request: requestJSON,
+            },
+        ],
+    });
+    // 知识库接口尚未纳入 OpenAPI，需部署对应商业知识库扩展。
+    const knowledgeMinVersion = ['biz13.7', 'max8.7', 'ipd5.7'];
+    const knowledgeType = {
+        type: 'string',
+        description: '知识类型，省略或空字符串表示不限；text/file 不可与非空 objectType 同时使用。',
+        options: [
+            { value: 'object', label: '对象知识' },
+            { value: 'text', label: '文本知识' },
+            { value: 'file', label: '文件知识' },
+        ],
+    };
+    const knowledgeObjectType = {
+        type: 'string',
+        description: '来源对象类型；单独指定时按 type=object 筛选，每次只接受一个编码。',
+        options: [
+            { value: 'story', label: '需求' },
+            { value: 'task', label: '任务' },
+            { value: 'case', label: '测试用例' },
+            { value: 'bug', label: 'Bug' },
+            { value: 'plan', label: '产品计划' },
+            { value: 'release', label: '发布' },
+            { value: 'feedback', label: '反馈' },
+            { value: 'ticket', label: '工单' },
+            { value: 'doc', label: '文档（含接口文档）' },
+            { value: 'issue', label: '问题' },
+            { value: 'risk', label: '风险' },
+            { value: 'opportunity', label: '机会' },
+            { value: 'practice', label: '最佳实践' },
+            { value: 'component', label: '组件' },
+        ],
+    };
+    defineModules([
+        {
+            name: 'knowledgelib',
+            display: '知识库',
+            description: '需部署商业知识库扩展，仅返回已发布且当前用户可访问的知识库。',
+            actions: [],
+        },
+        {
+            name: 'knowledge',
+            display: '知识',
+            description: '需部署商业知识库扩展，支持浏览知识、向量搜索、正文关键词搜索和读取已保存正文。',
+            actions: [],
+        },
+    ]);
+    defineModuleActions('knowledgelib', {
+        name: 'list',
+        minVersion: knowledgeMinVersion,
+        display: '获取知识库列表',
+        type: 'list',
+        method: 'get',
+        path: '/ai/knowledgelibs',
+        resultType: 'list',
+        resultGetter: 'data',
+        pagerGetter: 'pager',
+        request: requestJSON,
+        params: [
+            {
+                name: 'type',
+                type: 'string',
+                description: '库类型，省略或空字符串时合并两类可见库',
+                options: [{ value: 'my', label: '我的知识库' }, { value: 'team', label: '组织知识库' }],
+            },
+            { name: 'keyword', type: 'string', description: '知识库名称或描述关键词，首尾空白会被移除' },
+            { name: 'pageID', type: 'number', defaultValue: 1, description: '页码，从 1 开始的正整数' },
+            { name: 'recPerPage', type: 'number', defaultValue: 20, description: '每页条数，范围 1～100' },
+        ],
+    });
+    defineModuleActions('knowledge', [
+        {
+            name: 'list',
+            minVersion: knowledgeMinVersion,
+            display: '获取知识库内知识列表',
+            description: '返回当前用户可见的知识条目，按本地 ID 降序排列；不支持标题关键词查询。',
+            type: 'list',
+            method: 'get',
+            path: '/ai/knowledgelibs/{libID}/knowledges',
+            pathParams: { libID: '本地知识库 ID，正整数' },
+            resultType: 'list',
+            resultGetter: 'data',
+            pagerGetter: 'pager',
+            request: requestJSON,
+            params: [
+                { name: 'type', ...knowledgeType },
+                { name: 'objectType', ...knowledgeObjectType },
+                { name: 'pageID', type: 'number', defaultValue: 1, description: '页码，从 1 开始的正整数' },
+                { name: 'recPerPage', type: 'number', defaultValue: 20, description: '每页条数，范围 1～100' },
+            ],
+        },
+        {
+            name: 'embeddingsSearch',
+            minVersion: knowledgeMinVersion,
+            display: '多知识库向量搜索',
+            description: '仅检索已有索引，需 ai.searchknowledgelib 权限。按匹配度降序返回片段，不分页；用 knowledgeID 获取完整正文，chunkID 仅标识片段。',
+            type: 'list',
+            method: 'post',
+            path: '/ai/knowledges/embeddingssearch',
+            resultType: 'list',
+            resultGetter: 'data',
+            request: requestJSON,
+            requestBody: {
+                required: true,
+                mediaType: 'application/json',
+                schema: {
+                    type: 'object',
+                    required: ['keyword', 'libIDs'],
+                    example: { keyword: '如何处理接口请求超时', libIDs: [12, 18], minSimilarity: 0.7, limit: 5 },
+                    properties: {
+                        keyword: { type: 'string', minLength: 1, description: '搜索问题或关键词，去除首尾空白后不能为空' },
+                        libIDs: {
+                            type: 'array',
+                            minItems: 1,
+                            items: { type: 'integer', minimum: 1 },
+                            description: '本地知识库 ID 的非空正整数数组，例如 [12,18]；不接受字符串元素，重复 ID 自动去重',
+                        },
+                        type: knowledgeType,
+                        objectType: knowledgeObjectType,
+                        minSimilarity: { type: 'number', minimum: 0, maximum: 1, defaultValue: 0.5, description: '最小匹配度，范围 [0,1]' },
+                        limit: { type: 'integer', minimum: 1, maximum: 100, defaultValue: 5, description: '整次多库搜索最多返回的片段数，范围 1～100' },
+                    },
+                },
+            },
+        },
+        {
+            name: 'search',
+            minVersion: knowledgeMinVersion,
+            display: '多知识库正文关键词搜索',
+            description: '需 ai.searchknowledgelib 权限，仅按字面文本匹配已保存的 content，标题不参与，不依赖向量索引。返回完整正文及 contentType，每条知识只返回一次，按知识 ID 降序分页。',
+            type: 'list',
+            method: 'post',
+            path: '/ai/knowledges/search',
+            resultType: 'list',
+            resultGetter: 'data',
+            pagerGetter: 'pager',
+            request: requestJSON,
+            requestBody: {
+                required: true,
+                mediaType: 'application/json',
+                schema: {
+                    type: 'object',
+                    required: ['keywords', 'libIDs'],
+                    example: { keywords: ['登录', '超时'], libIDs: [12, 18], matchMode: 'any', pageID: 1, recPerPage: 20 },
+                    properties: {
+                        keywords: {
+                            type: 'array',
+                            minItems: 1,
+                            items: { type: 'string', minLength: 1 },
+                            description: '非空关键词数组，每项去除首尾空白后为 1～200 个 Unicode 字符，去重后最多 20 项；%、_ 和反斜杠按普通字符匹配',
+                        },
+                        libIDs: {
+                            type: 'array',
+                            minItems: 1,
+                            items: { type: 'integer', minimum: 1 },
+                            description: '本地知识库 ID 的非空正整数数组，例如 [12,18]；不接受字符串元素，重复 ID 自动去重',
+                        },
+                        matchMode: {
+                            type: 'string',
+                            defaultValue: 'any',
+                            description: '正文关键词匹配方式；仅省略时使用 any，空字符串和 null 无效',
+                            options: [{ value: 'any', label: '包含任一关键词' }, { value: 'all', label: '同一条正文包含全部关键词' }],
+                        },
+                        type: knowledgeType,
+                        objectType: knowledgeObjectType,
+                        pageID: { type: 'integer', minimum: 1, defaultValue: 1, description: '页码，从 1 开始的正整数' },
+                        recPerPage: { type: 'integer', minimum: 1, maximum: 100, defaultValue: 20, description: '每页条数，范围 1～100' },
+                    },
+                },
+            },
+        },
+        {
+            name: 'get',
+            minVersion: knowledgeMinVersion,
+            display: '获取知识详细内容',
+            description: '返回已保存的完整正文及来源信息，不触发文件提取、知识同步或索引更新。按 contentType 解释正文，尚未保存正文时 content 可为空。',
+            type: 'get',
+            method: 'get',
+            path: '/ai/knowledges/{knowledgeID}',
+            pathParams: { knowledgeID: '本地知识条目 ID，正整数；不可使用 chunkID 或来源对象 objectID' },
+            resultType: 'object',
+            resultGetter: 'data',
+            request: requestJSON,
+        },
+    ]);
+    for (const [moduleName, actionName] of [['product', 'create'], ['product', 'update'], ['feedback', 'close']]) {
+        extendModuleAction(moduleName, actionName, { request: requestJSON });
+    }
+    // 产品描述是字符串；仅修正该字段，保留上游 OpenAPI 数据和其他请求体字段。
+    for (const actionName of ['create', 'update']) {
+        extendModuleAction('product', actionName, (action) => {
+            const properties = action.requestBody.schema.properties;
+            properties.desc.type = 'string';
+            delete properties.desc.items;
+            return action;
+        });
+    }
     // 创建执行时，需要添加产品字段
     extendModuleAction('execution', 'create', (action) => {
         const required = action.requestBody.schema?.required;
@@ -101,8 +380,8 @@ export function applyBuiltinOverrides() {
                 schema.properties.reviewer ??= {
                     type: 'array',
                     items: { type: 'string' },
-                    description: '评审人员',
                 };
+                schema.properties.reviewer.description = '评审人员，如果无需评审则不传';
                 if (schema.required) {
                     schema.required = schema.required.filter(name => name !== 'reviewer');
                 }
@@ -121,6 +400,50 @@ export function applyBuiltinOverrides() {
             });
         });
     });
+    // confirmClose 是控制器参数，留在 JSON body 中会被误当成反馈表字段。
+    extendModuleAction('feedback', 'close', {
+        beforeRequest: async (command) => {
+            const data = { ...command.data };
+            const query = { ...command.query };
+            if (Object.hasOwn(data, 'confirmClose')) {
+                query.confirmClose = data.confirmClose;
+                delete data.confirmClose;
+            }
+            return { data, query };
+        },
+    });
+    // 确认表单会重置缺省字段；仅补齐可写字段，不回传详情中的其他属性。
+    extendModuleAction('bug', 'confirm', {
+        request: async ({ request: command, body, bodyType, client, timeout, insecure, options }) => {
+            const data = { ...body };
+            const fields = ['status', 'assignedTo', 'type', 'pri', 'deadline', 'mailto'];
+            const missing = fields.filter(field => data[field] === undefined);
+            if (missing.length) {
+                const response = await request('bug/get', { id: command.id }, {
+                    client, timeout, insecure, throwOnFail: true,
+                    forceRefreshConfig: options.forceRefreshConfig,
+                    skipVersionCheckOnConfigError: options.skipVersionCheckOnConfigError,
+                });
+                const current = response.data;
+                if (!isRecord(current) || missing.some(field => current[field] === undefined)) {
+                    throw new ZentaoError('E_API_FAILED', { message: 'Bug details are incomplete; confirmation was not sent.' });
+                }
+                for (const field of missing) {
+                    data[field] = field === 'mailto' && typeof current[field] === 'string'
+                        ? current[field].split(',').filter(Boolean)
+                        : current[field];
+                }
+            }
+            if (typeof data.status !== 'string' || !data.status.trim()) {
+                throw new ZentaoError('E_INVALID_PARAM', { param: 'status', value: String(data.status) });
+            }
+            // 已关闭 Bug 的指派人是特殊标记，API 会把它当成账号校验，需调用方明确指定。
+            if (data.assignedTo === 'closed') {
+                throw new ZentaoError('E_INVALID_PARAM', { param: 'assignedTo', value: 'closed' });
+            }
+            return requestJSON({ request: command, body: data, bodyType, client, timeout, insecure, options });
+        },
+    });
     // 修改 acl 字段默认值为 open
     [
         ['product', 'create'],

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-09-12T05:43:34.253Z";
-const fallbackVersion = "0.6.9";
+const fallbackBuild = "2026-09-30T11:35:46.717Z";
+const fallbackVersion = "0.7.1";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.9",
+  "version": "0.7.1",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",