@cpzxrobot/sdk 1.3.114 → 1.3.116

package/AIFORM_GATEWAY.md

@@ -0,0 +1,449 @@
+# AI报表模板接口使用说明
+
+## 概述
+
+AI报表模板接口用于管理工厂的AI报表模板，包括查询模板列表、新增和修改模板等功能。
+
+## 接口基础信息
+
+**Base URL**: `/api/v2/aiform/template`
+
+## 如何使用
+
+通过 `cpzxrobot().aiform.template` 访问AI报表模板相关功能。
+
+通过 `cpzxrobot().aiform.record` 访问文件上传和记录相关功能。
+
+## 可用方法
+
+### 1. 查询模板列表
+
+**方法**: `list(factoryId: number): Promise<AiformTemplateListResponse>`
+
+**接口路径**: `GET /api/v2/aiform/template/list/{factoryId}`
+
+**功能**: 根据工厂ID查询该工厂下的所有AI报表模板
+
+**参数**:
+- `factoryId` (number): 工厂ID，必填
+
+**返回值**:
+```typescript
+interface AiformTemplateListResponse {
+  code: number;           // 状态码
+  message: string;        // 提示信息
+  data: AiformTemplate[]; // 模板列表
+}
+
+interface AiformTemplate {
+  id: number;           // 模板ID
+  factoryId: number;    // 工厂ID
+  name: string;         // 模板名称
+  content: string;      // 模板内容
+  attention?: string;   // 注意事项
+}
+```
+
+**使用示例**:
+
+```javascript
+// 查询工厂1001的模板列表
+const response = await cpzxrobot().aiform.template.list(1001);
+
+if (response.code === 200) {
+  const templates = response.data;
+  console.log(`找到 ${templates.length} 个模板:`);
+  
+  templates.forEach(template => {
+    console.log(`ID: ${template.id}, 名称: ${template.name}`);
+    console.log(`内容: ${template.content.substring(0, 100)}...`);
+    if (template.attention) {
+      console.log(`注意事项: ${template.attention}`);
+    }
+  });
+} else {
+  console.error('获取模板列表失败:', response.message);
+}
+```
+
+### 2. 新增或修改模板
+
+**方法**: `save(request: AiformTemplateSaveRequest): Promise<AiformTemplateSaveResponse>`
+
+**接口路径**: `POST /api/v2/aiform/template/save`
+
+**功能**: 新增或修改AI报表模板。当请求体中包含 `id` 时执行修改操作，不包含 `id` 时执行新增操作。
+
+**请求参数**:
+```typescript
+interface AiformTemplateSaveRequest {
+  id?: number;        // 模板ID（传则修改，不传则新增）
+  factoryId: number;  // 工厂ID，必填
+  name: string;       // 模板名称，必填
+  content: string;    // 模板内容，必填
+  attention?: string; // 注意事项，可选
+}
+```
+
+**返回值**:
+```typescript
+interface AiformTemplateSaveResponse {
+  code: number;    // 状态码
+  message: string; // 提示信息
+}
+```
+
+**使用示例**:
+
+#### 新增模板
+
+```javascript
+// 新增模板
+const response = await cpzxrobot().aiform.template.save({
+  factoryId: 1001,
+  name: "生产日报模板",
+  content: "## 生产日报\n\n日期: {{date}}\n\n产量: {{production}}\n\n质量: {{quality}}",
+  attention: "请确保填写真实数据"
+});
+
+if (response.code === 200) {
+  console.log('模板创建成功');
+} else {
+  console.error('模板创建失败:', response.message);
+}
+```
+
+#### 修改模板
+
+```javascript
+// 修改模板
+const response = await cpzxrobot().aiform.template.save({
+  id: 1, // 模板ID
+  factoryId: 1001,
+  name: "生产日报模板（更新版）",
+  content: "## 生产日报\n\n日期: {{date}}\n\n产量: {{production}}\n\n质量: {{quality}}\n\n备注: {{remark}}",
+  attention: "请确保填写真实数据，新增加了备注字段"
+});
+
+if (response.code === 200) {
+  console.log('模板更新成功');
+} else {
+  console.error('模板更新失败:', response.message);
+}
+```
+
+### 3. 上传表格图片
+
+**方法**: `upload(file: File, templateId: number): Promise<AiformFileUploadResponse>`
+
+**接口路径**: `POST /api/v2/aiform/file/upload`
+
+**功能**: 上传表格图片到 MinIO，并关联到指定的模板。上传成功后自动异步触发大模型解析。
+
+**参数**:
+- `file` (File): 表格图片文件，必填
+- `templateId` (number): 关联的模板ID，必填
+
+**返回值**:
+```typescript
+interface AiformFileUploadResponse {
+  code: number;    // 状态码
+  message: string; // 提示信息
+  data: File;      // 文件记录
+}
+
+interface File {
+  id: number;           // 文件记录ID
+  code?: string;        // 业务编码
+  tableKey: number;     // 关联业务ID（模板ID）
+  tableName: string;    // 关联业务表名（固定值 aiform_template）
+  fileName: string;     // 原始文件名
+  storageName: string;  // 存储文件名
+  fileUrl: string;      // MinIO存储路径
+  accessUrl: string;    // 预签名访问链接
+  fileExt: string;      // 文件扩展名
+  server: string;       // 存储服务（minio）
+  type: string;         // 文件类型（image）
+  status: number;       // 状态：0-已上传 1-解析中 2-已解析
+  createTime: string;   // 创建时间
+  updateTime: string;   // 更新时间
+}
+```
+
+**使用示例**:
+
+```javascript
+// HTML文件输入示例
+<input type="file" id="fileInput" accept="image/*">
+
+// 上传文件
+async function uploadFile() {
+  const fileInput = document.getElementById('fileInput');
+  const file = fileInput.files[0];
+  const templateId = 1; // 模板ID
+  
+  if (!file) {
+    alert('请选择文件');
+    return;
+  }
+  
+  try {
+    const response = await cpzxrobot().aiform.record.upload(file, templateId);
+    console.log('上传成功:', response.data);
+    console.log('文件状态:', getFileStatusText(response.data.status));
+    console.log('访问链接:', response.data.accessUrl);
+    
+    // 可以开始轮询状态
+    trackFileStatus(templateId, response.data.id);
+  } catch (error) {
+    console.error('上传失败:', error.message);
+  }
+}
+
+function getFileStatusText(status) {
+  const statusMap = {
+    0: '已上传',
+    1: '解析中',
+    2: '已解析'
+  };
+  return statusMap[status] || '未知';
+}
+
+// 绑定事件
+ document.getElementById('fileInput').addEventListener('change', uploadFile);
+```
+
+### 4. 根据模板ID查询上传记录
+
+**方法**: `list(templateId: number): Promise<AiformFileListResponse>`
+
+**接口路径**: `GET /api/v2/aiform/file/list/{templateId}`
+
+**功能**: 根据模板ID查询该模板下所有上传的文件记录，按创建时间倒序排列。
+
+**参数**:
+- `templateId` (number): 模板ID，必填
+
+**返回值**:
+```typescript
+interface AiformFileListResponse {
+  code: number;    // 状态码
+  message: string; // 提示信息
+  data: File[];    // 文件记录列表
+}
+```
+
+**使用示例**:
+
+```javascript
+// 获取模板的上传记录
+async function getTemplateRecords(templateId) {
+  try {
+    const response = await cpzxrobot().aiform.record.list(templateId);
+    
+    if (response.code === 200) {
+      const records = response.data;
+      console.log(`找到 ${records.length} 条上传记录:`);
+      
+      records.forEach((record, index) => {
+        console.log(`\n记录 ${index + 1}:`);
+        console.log(`文件名: ${record.fileName}`);
+        console.log(`状态: ${getFileStatusText(record.status)}`);
+        console.log(`创建时间: ${record.createTime}`);
+        console.log(`访问链接: ${record.accessUrl}`);
+      });
+    }
+  } catch (error) {
+    console.error('获取记录失败:', error.message);
+  }
+}
+
+// 调用示例
+getTemplateRecords(1); // 查询模板ID为1的上传记录
+```
+
+### 5. 轮询文件解析状态
+
+**功能**: 上传文件后，需要轮询文件状态以确认解析进度。
+
+**使用示例**:
+
+```javascript
+async function trackFileStatus(templateId, fileId) {
+  let status = 0; // 初始状态
+  let attempts = 0;
+  const maxAttempts = 30; // 最多轮询30次
+  
+  console.log('开始跟踪文件解析状态...');
+  
+  while (status !== 2 && attempts < maxAttempts) {
+    try {
+      const response = await cpzxrobot().aiform.record.list(templateId);
+      const fileRecord = response.data.find(record => record.id === fileId);
+      
+      if (fileRecord) {
+        status = fileRecord.status;
+        console.log(`当前状态: ${getFileStatusText(status)}`);
+        
+        if (status === 2) {
+          console.log('文件已成功解析！');
+          return;
+        }
+      }
+      
+      await new Promise(resolve => setTimeout(resolve, 5000)); // 每5秒轮询一次
+      attempts++;
+    } catch (error) {
+      console.error('轮询失败:', error.message);
+      await new Promise(resolve => setTimeout(resolve, 5000));
+      attempts++;
+    }
+  }
+  
+  if (attempts >= maxAttempts) {
+    console.log('解析超时，请稍后手动检查状态');
+  }
+}
+```
+
+## 错误处理
+
+### 常见错误
+
+1. **参数验证错误**:
+   - `工厂ID不能为空` - 未提供factoryId参数
+   - `模板名称不能为空` - 未提供name参数
+   - `模板内容不能为空` - 未提供content参数
+   - `文件不能为空` - 未提供file参数
+   - `模板ID不能为空` - 未提供templateId参数
+
+2. **API错误**:
+   - 当API返回非200状态码时，会抛出包含错误信息的异常
+
+### 错误处理示例
+
+```javascript
+try {
+  // 尝试获取模板列表
+  const response = await cpzxrobot().aiform.template.list(1001);
+  console.log('模板列表:', response.data);
+} catch (error) {
+  console.error('操作失败:', error.message);
+}
+
+try {
+  // 尝试保存模板
+  const response = await cpzxrobot().aiform.template.save({
+    factoryId: 1001,
+    name: "测试模板",
+    content: "模板内容"
+  });
+  console.log('保存成功:', response.message);
+} catch (error) {
+  console.error('保存失败:', error.message);
+}
+
+try {
+  // 尝试上传文件
+  const file = document.getElementById('fileInput').files[0];
+  const response = await cpzxrobot().aiform.record.upload(file, 1);
+  console.log('上传成功:', response.data);
+} catch (error) {
+  console.error('上传失败:', error.message);
+}
+
+try {
+  // 尝试获取上传记录
+  const response = await cpzxrobot().aiform.record.list(1);
+  console.log('上传记录:', response.data);
+} catch (error) {
+  console.error('获取记录失败:', error.message);
+}
+```
+
+## 完整使用示例
+
+```javascript
+async function manageAITemplates() {
+  try {
+    const aiform = cpzxrobot().aiform.template;
+    const factoryId = 1001;
+    
+    console.log('=== 管理AI报表模板 ===');
+    
+    // 1. 获取模板列表
+    console.log('\n1. 获取模板列表:');
+    const listResponse = await aiform.list(factoryId);
+    if (listResponse.code === 200) {
+      console.log(`找到 ${listResponse.data.length} 个模板:`);
+      listResponse.data.forEach((template, index) => {
+        console.log(`  ${index + 1}. ${template.name} (ID: ${template.id})`);
+      });
+    }
+    
+    // 2. 新增模板
+    console.log('\n2. 新增模板:');
+    const createResponse = await aiform.save({
+      factoryId: factoryId,
+      name: "新增测试模板",
+      content: "## 测试模板\n\n这是一个测试模板",
+      attention: "测试用模板"
+    });
+    console.log(`新增结果: ${createResponse.message}`);
+    
+    // 3. 再次获取模板列表
+    console.log('\n3. 再次获取模板列表:');
+    const updatedListResponse = await aiform.list(factoryId);
+    if (updatedListResponse.code === 200) {
+      console.log(`现在有 ${updatedListResponse.data.length} 个模板:`);
+      updatedListResponse.data.forEach((template, index) => {
+        console.log(`  ${index + 1}. ${template.name} (ID: ${template.id})`);
+      });
+    }
+    
+    // 4. 修改最后一个模板
+    if (updatedListResponse.data.length > 0) {
+      const lastTemplate = updatedListResponse.data[updatedListResponse.data.length - 1];
+      console.log(`\n4. 修改模板: ${lastTemplate.name}`);
+      
+      const updateResponse = await aiform.save({
+        id: lastTemplate.id,
+        factoryId: factoryId,
+        name: `${lastTemplate.name} (已更新)`,
+        content: lastTemplate.content + '\n\n更新时间: ' + new Date().toLocaleString(),
+        attention: lastTemplate.attention + ' - 已更新'
+      });
+      console.log(`修改结果: ${updateResponse.message}`);
+    }
+    
+    // 5. 最终模板列表
+    console.log('\n5. 最终模板列表:');
+    const finalListResponse = await aiform.list(factoryId);
+    if (finalListResponse.code === 200) {
+      console.log(`最终有 ${finalListResponse.data.length} 个模板:`);
+      finalListResponse.data.forEach((template, index) => {
+        console.log(`  ${index + 1}. ${template.name} (ID: ${template.id})`);
+      });
+    }
+    
+  } catch (error) {
+    console.error('操作失败:', error.message);
+  }
+}
+
+// 执行操作
+manageAITemplates();
+```
+
+## 注意事项
+
+1. **权限要求**: 使用这些接口需要具有相应的工厂管理权限
+2. **模板内容**: 模板内容支持使用模板变量（如 `{{date}}`），具体变量格式请参考AI报表系统的相关文档
+3. **参数验证**: 所有必填参数必须提供，否则会抛出错误
+4. **错误处理**: 建议使用 try-catch 捕获可能的错误
+5. **网络请求**: 这些接口是异步网络请求，需要使用 `async/await` 或 Promise 处理
+
+## 版本信息
+
+- **SDK版本**: 1.3.114+
+- **接口版本**: v2

package/aiform_gateway.ts

@@ -3,6 +3,8 @@ import type {
   AiformTemplateListResponse,
   AiformTemplateSaveRequest,
   AiformTemplateSaveResponse,
+  AiformFileUploadResponse,
+  AiformFileListResponse,
 } from ".";
 
 export class AiformGateway extends Object {
@@ -66,4 +68,55 @@ export class AiformGateway extends Object {
       },
     };
   }
+
+  get record() {
+    return {
+      /**
+       * 上传表格图片
+       * @param file 表格图片文件
+       * @param templateId 关联的模板ID
+       * @returns Promise 包含文件记录信息
+       */
+      upload: async (templateId: number): Promise<AiformFileUploadResponse> => {
+        const axios = await this.context.ready;
+
+        if (!templateId) {
+          throw new Error('模板ID不能为空');
+        }
+
+        return axios.upload(`/api/v2/aiform/file/upload`,{
+          title: "请选择要解析的表格图片",
+          data: {
+            templateId,
+          }
+        }).then((res) => {
+          if (res.data.code !== 200) {
+            throw new Error(res.data.message || '上传文件失败');
+          }
+          return res.data;
+        });
+      },
+
+      /**
+       * 根据模板ID查询上传记录
+       * @param templateId 模板ID
+       * @returns Promise 包含文件记录列表
+       */
+      list: async (templateId: number): Promise<AiformFileListResponse> => {
+        const axios = await this.context.ready;
+
+        // 参数验证
+        if (!templateId) {
+          throw new Error('模板ID不能为空');
+        }
+
+        return axios.get(`/api/v2/aiform/file/list/${templateId}`).then((res) => {
+          if (res.data.code !== 200) {
+            throw new Error(res.data.message || '获取文件列表失败');
+          }
+          return res.data;
+        });
+      },
+    };
+  }
 }

package/dist/aiform_gateway.js

@@ -63,5 +63,50 @@ class AiformGateway extends Object {
             }),
         };
     }
+    get record() {
+        return {
+            /**
+             * 上传表格图片
+             * @param file 表格图片文件
+             * @param templateId 关联的模板ID
+             * @returns Promise 包含文件记录信息
+             */
+            upload: (templateId) => __awaiter(this, void 0, void 0, function* () {
+                const axios = yield this.context.ready;
+                if (!templateId) {
+                    throw new Error('模板ID不能为空');
+                }
+                return axios.upload(`/api/v2/aiform/file/upload`, {
+                    title: "请选择要解析的表格图片",
+                    data: {
+                        templateId,
+                    }
+                }).then((res) => {
+                    if (res.data.code !== 200) {
+                        throw new Error(res.data.message || '上传文件失败');
+                    }
+                    return res.data;
+                });
+            }),
+            /**
+             * 根据模板ID查询上传记录
+             * @param templateId 模板ID
+             * @returns Promise 包含文件记录列表
+             */
+            list: (templateId) => __awaiter(this, void 0, void 0, function* () {
+                const axios = yield this.context.ready;
+                // 参数验证
+                if (!templateId) {
+                    throw new Error('模板ID不能为空');
+                }
+                return axios.get(`/api/v2/aiform/file/list/${templateId}`).then((res) => {
+                    if (res.data.code !== 200) {
+                        throw new Error(res.data.message || '获取文件列表失败');
+                    }
+                    return res.data;
+                });
+            }),
+        };
+    }
 }
 exports.AiformGateway = AiformGateway;

package/dist/production_gateway.js

@@ -52,6 +52,8 @@ class ProductionGateway extends Object {
                     params: {
                         factory_id: factoryId
                     }
+                }).then((res) => {
+                    return res.data;
                 });
             }),
             create: (request) => __awaiter(this, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cpzxrobot/sdk",
-  "version": "1.3.114",
+  "version": "1.3.116",
   "description": "提供给上海正芯数智APP第三方H5应用使用的SDK",
   "main": "dist/index.js",
   "scripts": {

package/production_gateway.ts

@@ -48,6 +48,8 @@ export class ProductionGateway extends Object {
           params: {
             factory_id: factoryId
           }
+        }).then((res) => {
+          return res.data;
         });
       },
       create: async (request: {

package/types.d.ts

@@ -859,6 +859,64 @@ interface AiformTemplateSaveResponse {
   message: string;
 }
 
+/**
+ * 文件记录接口（通用文件表 app_v2_file）
+ */
+interface File {
+  /** 文件记录ID */
+  id: number;
+  /** 业务编码 */
+  code?: string;
+  /** 关联业务ID（此处为模板ID） */
+  tableKey: number;
+  /** 关联业务表名（固定值 aiform_template） */
+  tableName: string;
+  /** 原始文件名 */
+  fileName: string;
+  /** 存储文件名（系统统一生成） */
+  storageName: string;
+  /** MinIO存储路径 */
+  fileUrl: string;
+  /** 预签名访问链接（动态生成，有效期7天，不存数据库） */
+  accessUrl: string;
+  /** 文件扩展名 */
+  fileExt: string;
+  /** 存储服务（minio） */
+  server: string;
+  /** 文件类型（image） */
+  type: string;
+  /** 状态：0-已上传 1-解析中 2-已解析 */
+  status: number;
+  /** 创建时间 */
+  createTime: string;
+  /** 更新时间 */
+  updateTime: string;
+}
+
+/**
+ * 文件上传响应接口
+ */
+interface AiformFileUploadResponse {
+  /** 响应码 */
+  code: number;
+  /** 提示信息 */
+  message: string;
+  /** 文件记录 */
+  data: File;
+}
+
+/**
+ * 文件列表响应接口
+ */
+interface AiformFileListResponse {
+  /** 响应码 */
+  code: number;
+  /** 提示信息 */
+  message: string;
+  /** 文件记录列表 */
+  data: File[];
+}
+
 declare class Cpzxrobot {
   transport: TransportGateway;
   ready: Promise<MyAxiosInstance>;
@@ -966,6 +1024,9 @@ declare module "@cpzxrobot/sdk" {
     AiformTemplateListResponse,
     AiformTemplateSaveRequest,
     AiformTemplateSaveResponse,
+    File,
+    AiformFileUploadResponse,
+    AiformFileListResponse,
     AlarmRuleDetail,
     AlarmRuleListResponse,
     AlarmRuleDetailResponse,