@cpzxrobot/sdk 1.3.116 → 1.3.118

package/AIFORM_GATEWAY.md

@@ -1,449 +1,399 @@
-# AI报表模板接口使用说明
+# AI报表 接口文档
 
-## 概述
+---
 
-AI报表模板接口用于管理工厂的AI报表模板，包括查询模板列表、新增和修改模板等功能。
-
-## 接口基础信息
-
-**Base URL**: `/api/v2/aiform/template`
-
-## 如何使用
-
-通过 `cpzxrobot().aiform.template` 访问AI报表模板相关功能。
-
-通过 `cpzxrobot().aiform.record` 访问文件上传和记录相关功能。
-
-## 可用方法
-
-### 1. 查询模板列表
-
-**方法**: `list(factoryId: number): Promise<AiformTemplateListResponse>`
+## 1. 按 factoryId 查询模板列表
 
 **接口路径**: `GET /api/v2/aiform/template/list/{factoryId}`
 
-**功能**: 根据工厂ID查询该工厂下的所有AI报表模板
+**接口描述**: 根据工厂ID查询该工厂下的所有AI报表模板
 
-**参数**:
-- `factoryId` (number): 工厂ID，必填
+**请求参数**:
 
-**返回值**:
-```typescript
-interface AiformTemplateListResponse {
-  code: number;           // 状态码
-  message: string;        // 提示信息
-  data: AiformTemplate[]; // 模板列表
-}
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| factoryId | path | Long | 是 | 工厂ID |
+
+**请求示例**:
 
-interface AiformTemplate {
-  id: number;           // 模板ID
-  factoryId: number;    // 工厂ID
-  name: string;         // 模板名称
-  content: string;      // 模板内容
-  attention?: string;   // 注意事项
-}
+```
+GET /api/v2/aiform/template/list/17231604990917
 ```
 
-**使用示例**:
-
-```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}`);
+**响应参数**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | int | 状态码 |
+| message | String | 提示信息 |
+| data | Array\<AiformTemplateVO\> | 模板列表 |
+
+**data 数组元素字段（AiformTemplateVO）**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| id | Long | 模板ID |
+| factoryId | Long | 工厂ID |
+| name | String | 模板名称 |
+| content | String | 模板内容 |
+| attention | TemplateAttention | 注意事项（对象） |
+
+**attention 字段（TemplateAttention）**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| hasFixedContent | Boolean | 是否有固定内容 |
+| fixedContentList | Array\<String\> | 固定内容列表 |
+| hasFixedRowContent | Boolean | 是否有固定行内容 |
+| rowContent | String | 行内容 |
+| hasFixedColumnContent | Boolean | 是否有固定列内容 |
+| columnContent | String | 列内容 |
+| otherNotes | String | 其他备注 |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "SUCCESS",
+  "data": [
+    {
+      "id": 1,
+      "factoryId": 17231604990917,
+      "name": "栋舍巡检报表",
+      "content": "进行分娩舍的巡检记录",
+      "attention": {
+        "hasFixedContent": false,
+        "fixedContentList": [],
+        "hasFixedRowContent": true,
+        "rowContent": "每头母猪和仔猪的日常记录情况",
+        "hasFixedColumnContent": false,
+        "columnContent": "",
+        "otherNotes": ""
+      }
     }
-  });
-} else {
-  console.error('获取模板列表失败:', response.message);
+  ]
 }
 ```
 
-### 2. 新增或修改模板
+---
 
-**方法**: `save(request: AiformTemplateSaveRequest): Promise<AiformTemplateSaveResponse>`
+## 2. 新增或修改模板
 
 **接口路径**: `POST /api/v2/aiform/template/save`
 
-**功能**: 新增或修改AI报表模板。当请求体中包含 `id` 时执行修改操作，不包含 `id` 时执行新增操作。
-
-**请求参数**:
-```typescript
-interface AiformTemplateSaveRequest {
-  id?: number;        // 模板ID（传则修改，不传则新增）
-  factoryId: number;  // 工厂ID，必填
-  name: string;       // 模板名称，必填
-  content: string;    // 模板内容，必填
-  attention?: string; // 注意事项，可选
+**接口描述**: 新增或修改AI报表模板。当请求体中包含 `id` 时执行修改操作，不包含 `id` 时执行新增操作。
+
+**请求头**:
+
+| Header | 值 |
+|--------|----|
+| Content-Type | application/json |
+
+**请求体参数（AiformTemplateVO）**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | Long | 否 | 模板ID（传则修改，不传则新增） |
+| factoryId | Long | 是 | 工厂ID |
+| name | String | 是 | 模板名称 |
+| content | String | 是 | 模板内容 |
+| attention | TemplateAttention | 否 | 注意事项（对象） |
+
+**attention 字段（TemplateAttention）**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| hasFixedContent | Boolean | 否 | 是否有固定内容 |
+| fixedContentList | Array\<String\> | 否 | 固定内容列表 |
+| hasFixedRowContent | Boolean | 否 | 是否有固定行内容 |
+| rowContent | String | 否 | 行内容 |
+| hasFixedColumnContent | Boolean | 否 | 是否有固定列内容 |
+| columnContent | String | 否 | 列内容 |
+| otherNotes | String | 否 | 其他备注 |
+
+**新增请求示例**:
+
+```json
+{
+  "factoryId": 17231604990917,
+  "name": "栋舍巡检报表",
+  "content": "进行分娩舍的巡检记录",
+  "attention": {
+    "hasFixedContent": false,
+    "fixedContentList": [],
+    "hasFixedRowContent": true,
+    "rowContent": "每头母猪和仔猪的日常记录情况",
+    "hasFixedColumnContent": false,
+    "columnContent": "",
+    "otherNotes": ""
+  }
 }
 ```
 
-**返回值**:
-```typescript
-interface AiformTemplateSaveResponse {
-  code: number;    // 状态码
-  message: string; // 提示信息
+**修改请求示例**:
+
+```json
+{
+  "id": 1,
+  "factoryId": 17231604990917,
+  "name": "栋舍巡检报表(修改)",
+  "content": "修改后的巡检记录内容",
+  "attention": {
+    "hasFixedContent": true,
+    "fixedContentList": ["温度", "湿度"],
+    "hasFixedRowContent": true,
+    "rowContent": "每头母猪和仔猪的日常记录情况",
+    "hasFixedColumnContent": false,
+    "columnContent": "",
+    "otherNotes": "需关注异常情况"
+  }
 }
 ```
 
-**使用示例**:
+**响应参数**:
 
-#### 新增模板
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | int | 状态码 |
+| 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);
+```json
+{
+  "code": 200,
+  "message": "SUCCESS"
 }
 ```
 
-#### 修改模板
-
-```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);
-}
-```
+---
+
+---
+
+# AI报表文件 接口
+
+**Base URL**: `/api/v2/aiform/file`
 
-### 3. 上传表格图片
+---
 
-**方法**: `upload(file: File, templateId: number): Promise<AiformFileUploadResponse>`
+## 3. 上传表格图片
 
 **接口路径**: `POST /api/v2/aiform/file/upload`
 
-**功能**: 上传表格图片到 MinIO，并关联到指定的模板。上传成功后自动异步触发大模型解析。
+**接口描述**: 上传表格图片到 MinIO，并关联到指定的模板。上传成功后自动触发大模型解析。返回文件记录（含 code），可通过接口4轮询文件状态，通过接口5根据 code 获取解析结果和预签名访问链接。
 
-**参数**:
-- `file` (File): 表格图片文件，必填
-- `templateId` (number): 关联的模板ID，必填
+**请求头**:
 
-**返回值**:
-```typescript
-interface AiformFileUploadResponse {
-  code: number;    // 状态码
-  message: string; // 提示信息
-  data: File;      // 文件记录
-}
+| Header | 值 |
+|--------|----|
+| Content-Type | multipart/form-data |
 
-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;
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| file | form-data | MultipartFile | 是 | 表格图片文件 |
+| templateId | form-data | Long | 是 | 关联的模板ID |
+
+**响应参数**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | int | 状态码 |
+| message | String | 提示信息 |
+| data | File | 文件记录 |
+
+**data 字段（File，通用文件表 `app_v2_file`）**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| id | Long | 文件记录ID |
+| code | String | 业务编码（用于调用详情接口） |
+| tableKey | Long | 关联业务ID（此处为模板ID） |
+| tableName | String | 关联业务表名（固定值 `aiform_template`） |
+| fileName | String | 原始文件名 |
+| storageName | String | 存储文件名（系统统一生成） |
+| fileUrl | String | MinIO存储路径 |
+| fileExt | String | 文件扩展名 |
+| server | String | 存储服务（minio） |
+| type | String | 文件类型（image） |
+| status | Integer | 状态：0-已上传 1-解析中 2-已解析 |
+| createUserId | Long | 创建用户ID |
+| createTime | String | 创建时间 |
+| updateTime | String | 更新时间 |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "SUCCESS",
+  "data": {
+    "id": 1,
+    "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "tableKey": 1,
+    "tableName": "aiform_template",
+    "fileName": "巡检报表20260301.png",
+    "storageName": "20260301120000000123.png",
+    "fileUrl": "aiform/1/20260301120000000123.png",
+    "fileExt": "png",
+    "server": "minio",
+    "type": "image",
+    "status": 0,
+    "createUserId": 100,
+    "createTime": "2026-03-01 12:00:00",
+    "updateTime": "2026-03-01 12:00:00"
   }
-  
-  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>`
+## 4. 根据模板ID查询上传记录
 
 **接口路径**: `GET /api/v2/aiform/file/list/{templateId}`
 
-**功能**: 根据模板ID查询该模板下所有上传的文件记录，按创建时间倒序排列。
+**接口描述**: 根据模板ID查询该模板下所有上传的文件记录，按创建时间倒序排列。返回精简的文件列表（FileVO），如需解析结果或预签名访问链接请调用接口5。
 
-**参数**:
-- `templateId` (number): 模板ID，必填
+**请求参数**:
 
-**返回值**:
-```typescript
-interface AiformFileListResponse {
-  code: number;    // 状态码
-  message: string; // 提示信息
-  data: File[];    // 文件记录列表
-}
-```
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| templateId | path | Long | 是 | 模板ID |
 
-**使用示例**:
-
-```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的上传记录
+```
+GET /api/v2/aiform/file/list/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++;
+**响应参数**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | int | 状态码 |
+| message | String | 提示信息 |
+| data | Array\<FileVO\> | 文件记录列表 |
+
+**data 数组元素字段（FileVO）**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | String | 业务编码（用于调用详情接口） |
+| storageName | String | 存储文件名 |
+| status | Integer | 状态：0-已上传 1-解析中 2-已解析 |
+| createUserId | Long | 创建用户ID |
+| createTime | String | 创建时间（RFC 3339 格式，如 `2026-03-02T10:00:00+08:00`） |
+| updateTime | String | 更新时间（RFC 3339 格式，如 `2026-03-02T10:05:00+08:00`） |
+
+**status 状态说明**:
+
+| 值 | 含义 |
+|----|------|
+| 0 | 已上传 |
+| 1 | 解析中 |
+| 2 | 已解析 |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "SUCCESS",
+  "data": [
+    {
+      "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "storageName": "20260302100000000456.png",
+      "status": 2,
+      "createUserId": 100,
+      "createTime": "2026-03-02T10:00:00+08:00",
+      "updateTime": "2026-03-02T10:05:00+08:00"
+    },
+    {
+      "code": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+      "storageName": "20260301120000000123.png",
+      "status": 0,
+      "createUserId": 100,
+      "createTime": "2026-03-01T12:00:00+08:00",
+      "updateTime": "2026-03-01T12:00:00+08:00"
     }
-  }
-  
-  if (attempts >= maxAttempts) {
-    console.log('解析超时，请稍后手动检查状态');
-  }
+  ]
 }
 ```
 
-## 错误处理
+---
 
-### 常见错误
+## 5. 根据文件code获取详情
 
-1. **参数验证错误**:
-   - `工厂ID不能为空` - 未提供factoryId参数
-   - `模板名称不能为空` - 未提供name参数
-   - `模板内容不能为空` - 未提供content参数
-   - `文件不能为空` - 未提供file参数
-   - `模板ID不能为空` - 未提供templateId参数
+**接口路径**: `GET /api/v2/aiform/file/detail/{code}`
 
-2. **API错误**:
-   - 当API返回非200状态码时，会抛出包含错误信息的异常
+**接口描述**: 根据文件业务编码（code）获取解析结果和预签名访问链接。需在列表接口中获取 code 后调用。
 
-### 错误处理示例
+**请求参数**:
 
-```javascript
-try {
-  // 尝试获取模板列表
-  const response = await cpzxrobot().aiform.template.list(1001);
-  console.log('模板列表:', response.data);
-} catch (error) {
-  console.error('操作失败:', error.message);
-}
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| code | path | String | 是 | 文件业务编码（上传或列表接口返回） |
 
-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);
-}
+```
+GET /api/v2/aiform/file/detail/a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-## 完整使用示例
-
-```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);
+**响应参数**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | int | 状态码 |
+| message | String | 提示信息 |
+| data | AiformParseResultVO | 解析结果详情 |
+
+**data 字段（AiformParseResultVO）**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| content | String | markdown 解析的表格内容 |
+| unclears | Array\<String\> | 疑似不清晰处的描述说明 |
+| description | String | 整体解析说明 |
+| parseResult | String | 解析结果（兼容旧数据或解析失败时的原始结果） |
+| accessUrl | String | 预签名访问链接（有效期7天） |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "SUCCESS",
+  "data": {
+    "content": "| 列1 | 列2 |\n|-----|-----|\n| 值1 | 值2 |",
+    "unclears": ["第3行第2列字迹模糊"],
+    "description": "表格共3行2列，已完整解析",
+    "parseResult": null,
+    "accessUrl": "https://minio.cpzxrobot.com/app/aiform/1/20260302100000000456.png?X-Amz-..."
   }
 }
-
-// 执行操作
-manageAITemplates();
 ```
 
-## 注意事项
+---
+
+**文件状态流转说明**:
+
+上传成功后系统自动异步调用大模型（Qwen3-VL-235B）解析图片，文件状态流转如下：
+
+- `0`（已上传）→ `1`（解析中）→ `2`（已解析）
+- 解析失败时回退为 `0`（已上传）
 
-1. **权限要求**: 使用这些接口需要具有相应的工厂管理权限
-2. **模板内容**: 模板内容支持使用模板变量（如 `{{date}}`），具体变量格式请参考AI报表系统的相关文档
-3. **参数验证**: 所有必填参数必须提供，否则会抛出错误
-4. **错误处理**: 建议使用 try-catch 捕获可能的错误
-5. **网络请求**: 这些接口是异步网络请求，需要使用 `async/await` 或 Promise 处理
+解析结果持久化到 `aiform_parse_result` 表，按 `content`（表格内容）、`unclears`（疑似不清晰处）、`description`（整体说明）三个字段存储，可通过接口5根据文件 code 获取。
 
-## 版本信息
+---
 
-- **SDK版本**: 1.3.114+
-- **接口版本**: v2
+## 公共错误响应
+
+```json
+{
+  "code": 400,
+  "message": "FAIL"
+}
+```

package/aiform_gateway.ts

@@ -5,6 +5,7 @@ import type {
   AiformTemplateSaveResponse,
   AiformFileUploadResponse,
   AiformFileListResponse,
+  AiformFileDetailResponse,
 } from ".";
 
 export class AiformGateway extends Object {
@@ -73,7 +74,6 @@ export class AiformGateway extends Object {
     return {
       /**
        * 上传表格图片
-       * @param file 表格图片文件
        * @param templateId 关联的模板ID
        * @returns Promise 包含文件记录信息
        */
@@ -100,7 +100,7 @@ export class AiformGateway extends Object {
       /**
        * 根据模板ID查询上传记录
        * @param templateId 模板ID
-       * @returns Promise 包含文件记录列表
+       * @returns Promise 包含文件记录列表（精简版）
        */
       list: async (templateId: number): Promise<AiformFileListResponse> => {
         const axios = await this.context.ready;
@@ -117,6 +117,27 @@ export class AiformGateway extends Object {
           return res.data;
         });
       },
+
+      /**
+       * 根据文件业务编码获取详情
+       * @param code 文件业务编码
+       * @returns Promise 包含解析结果详情
+       */
+      detail: async (code: string): Promise<AiformFileDetailResponse> => {
+        const axios = await this.context.ready;
+
+        // 参数验证
+        if (!code) {
+          throw new Error('文件业务编码不能为空');
+        }
+
+        return axios.get(`/api/v2/aiform/file/detail/${code}`).then((res) => {
+          if (res.data.code !== 200) {
+            throw new Error(res.data.message || '获取文件详情失败');
+          }
+          return res.data;
+        });
+      },
     };
   }
 }

package/dist/aiform_gateway.js

@@ -67,7 +67,6 @@ class AiformGateway extends Object {
         return {
             /**
              * 上传表格图片
-             * @param file 表格图片文件
              * @param templateId 关联的模板ID
              * @returns Promise 包含文件记录信息
              */
@@ -91,7 +90,7 @@ class AiformGateway extends Object {
             /**
              * 根据模板ID查询上传记录
              * @param templateId 模板ID
-             * @returns Promise 包含文件记录列表
+             * @returns Promise 包含文件记录列表（精简版）
              */
             list: (templateId) => __awaiter(this, void 0, void 0, function* () {
                 const axios = yield this.context.ready;
@@ -106,6 +105,24 @@ class AiformGateway extends Object {
                     return res.data;
                 });
             }),
+            /**
+             * 根据文件业务编码获取详情
+             * @param code 文件业务编码
+             * @returns Promise 包含解析结果详情
+             */
+            detail: (code) => __awaiter(this, void 0, void 0, function* () {
+                const axios = yield this.context.ready;
+                // 参数验证
+                if (!code) {
+                    throw new Error('文件业务编码不能为空');
+                }
+                return axios.get(`/api/v2/aiform/file/detail/${code}`).then((res) => {
+                    if (res.data.code !== 200) {
+                        throw new Error(res.data.message || '获取文件详情失败');
+                    }
+                    return res.data;
+                });
+            }),
         };
     }
 }

package/dist/mobile_platform.js

@@ -131,6 +131,11 @@ class MobilePlatform {
             return this.platform.callHandler("app.scanQrcode");
         });
     }
+    getUserFromCache(userId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.platform.callHandler("app.getUserFromCache", userId);
+        });
+    }
     setTitle(title) {
         this.platform.callHandler("app.setTitle", title);
     }

package/dist/user_gateway.js

@@ -313,6 +313,10 @@ class UserGateway extends Object {
             var factory = yield this.context.user.getSelectedFarm();
             var url = '/api/v1/user/info';
             if (userId) {
+                var userInCache = yield this.context.platform.getUserFromCache(userId);
+                if (userInCache) {
+                    return userInCache;
+                }
                 url += `/${userId}`;
             }
             return axios.get(url, {

package/dist/web_platform.js

@@ -395,6 +395,23 @@ class WebPlatform {
         }
         return Promise.resolve(this._selectedUnit);
     }
+    getUserFromCache(userId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 从本地缓存中获取用户数据
+            const userKey = `user_${userId}`;
+            const userData = localStorage.getItem(userKey);
+            if (userData) {
+                try {
+                    return JSON.parse(userData);
+                }
+                catch (error) {
+                    console.error('Failed to parse user data from cache:', error);
+                    return null;
+                }
+            }
+            return null;
+        });
+    }
     jumpToMiniApp(url) {
         window.location.href = url;
         return Promise.resolve();

package/dist/windows_platform.js

@@ -148,5 +148,12 @@ class WindwosMiniAppPlatform {
         // @ts-ignore
         (_a = window.miniapp) === null || _a === void 0 ? void 0 : _a.aiAssist(args);
     }
+    getUserFromCache(userId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // @ts-ignore
+            return yield ((_a = window.miniapp) === null || _a === void 0 ? void 0 : _a.getUserFromCache(userId));
+        });
+    }
 }
 exports.WindwosMiniAppPlatform = WindwosMiniAppPlatform;

package/mobile_platform.ts

@@ -130,6 +130,10 @@ export class MobilePlatform implements PlatformInterface {
     return this.platform.callHandler("app.scanQrcode");
   }
 
+  async getUserFromCache(userId: number): Promise<any> {
+    return this.platform.callHandler("app.getUserFromCache", userId);
+  }
+
   setTitle(title: string): void {
     this.platform.callHandler("app.setTitle", title);
   }

package/package.json

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

package/platform_interface.ts

@@ -34,4 +34,5 @@ export abstract class PlatformInterface {
   //change factory
   abstract openFactorySelector():void;
   abstract aiAssist(args:AiAssistRequest):void;
+  abstract getUserFromCache(userId: number): Promise<any>;
 }

package/types.d.ts

@@ -866,7 +866,7 @@ interface File {
   /** 文件记录ID */
   id: number;
   /** 业务编码 */
-  code?: string;
+  code: string;
   /** 关联业务ID（此处为模板ID） */
   tableKey: number;
   /** 关联业务表名（固定值 aiform_template） */
@@ -877,8 +877,6 @@ interface File {
   storageName: string;
   /** MinIO存储路径 */
   fileUrl: string;
-  /** 预签名访问链接（动态生成，有效期7天，不存数据库） */
-  accessUrl: string;
   /** 文件扩展名 */
   fileExt: string;
   /** 存储服务（minio） */
@@ -887,12 +885,48 @@ interface File {
   type: string;
   /** 状态：0-已上传 1-解析中 2-已解析 */
   status: number;
+  /** 创建用户ID */
+  createUserId: number;
   /** 创建时间 */
   createTime: string;
   /** 更新时间 */
   updateTime: string;
 }
 
+/**
+ * 文件列表项接口（FileVO）
+ */
+interface FileVO {
+  /** 业务编码（用于调用详情接口） */
+  code: string;
+  /** 存储文件名 */
+  storageName: string;
+  /** 状态：0-已上传 1-解析中 2-已解析 */
+  status: number;
+  /** 创建用户ID */
+  createUserId: number;
+  /** 创建时间（RFC 3339 格式） */
+  createTime: string;
+  /** 更新时间（RFC 3339 格式） */
+  updateTime: string;
+}
+
+/**
+ * 解析结果详情接口（AiformParseResultVO）
+ */
+interface AiformParseResultVO {
+  /** markdown 解析的表格内容 */
+  content: string;
+  /** 疑似不清晰处的描述说明 */
+  unclears: string[];
+  /** 整体解析说明 */
+  description: string;
+  /** 解析结果（兼容旧数据或解析失败时的原始结果） */
+  parseResult: string | null;
+  /** 预签名访问链接（有效期7天） */
+  accessUrl: string;
+}
+
 /**
  * 文件上传响应接口
  */
@@ -914,7 +948,19 @@ interface AiformFileListResponse {
   /** 提示信息 */
   message: string;
   /** 文件记录列表 */
-  data: File[];
+  data: FileVO[];
+}
+
+/**
+ * 文件详情响应接口
+ */
+interface AiformFileDetailResponse {
+  /** 响应码 */
+  code: number;
+  /** 提示信息 */
+  message: string;
+  /** 解析结果详情 */
+  data: AiformParseResultVO;
 }
 
 declare class Cpzxrobot {
@@ -1025,8 +1071,11 @@ declare module "@cpzxrobot/sdk" {
     AiformTemplateSaveRequest,
     AiformTemplateSaveResponse,
     File,
+    FileVO,
+    AiformParseResultVO,
     AiformFileUploadResponse,
     AiformFileListResponse,
+    AiformFileDetailResponse,
     AlarmRuleDetail,
     AlarmRuleListResponse,
     AlarmRuleDetailResponse,

package/user_gateway.ts

@@ -342,6 +342,11 @@ export class UserGateway extends Object {
     var factory = await this.context.user.getSelectedFarm()
     var url = '/api/v1/user/info'
     if (userId) {
+      var userInCache = await this.context.platform.getUserFromCache(userId);
+      if (userInCache) {
+        return userInCache
+      }
+
       url += `/${userId}`
     }
     return axios.get(url, {

package/web_platform.ts

@@ -399,6 +399,21 @@ export class WebPlatform implements PlatformInterface {
     return Promise.resolve(this._selectedUnit);
   }
 
+  async getUserFromCache(userId: number): Promise<any> {
+    // 从本地缓存中获取用户数据
+    const userKey = `user_${userId}`;
+    const userData = localStorage.getItem(userKey);
+    if (userData) {
+      try {
+        return JSON.parse(userData);
+      } catch (error) {
+        console.error('Failed to parse user data from cache:', error);
+        return null;
+      }
+    }
+    return null;
+  }
+
   jumpToMiniApp(url: string): Promise<void> {
     window.location.href = url;
     return Promise.resolve();

package/windows_platform.ts

@@ -139,4 +139,9 @@ export class WindwosMiniAppPlatform implements PlatformInterface {
     // @ts-ignore
     window.miniapp?.aiAssist(args);
   }
+
+  async getUserFromCache(userId: number): Promise<any> {
+    // @ts-ignore
+    return await window.miniapp?.getUserFromCache(userId);
+  }
 }