LS Inspection Archive SDK

LS Inspection Archive 系统的 Node.js SDK，提供类型安全的 API 接口。

功能特点

• 🛡️ 完整的 TypeScript 类型支持
• 🔄 支持环境变量配置（Node.js 环境）
• 📦 支持文件上传（File/Buffer）
• 📝 详细的 API 文档
• 🚀 基于 axios 的现代化 HTTP 客户端
• 🏗️ 使用构建器模式创建检测数据
• 🌐 支持 ESM 和 CommonJS
• 🌍 同时支持 Node.js 和浏览器环境

安装

# 使用 npm
npm install ls-inspection-archive form-data

# 使用 yarn
yarn add ls-inspection-archive form-data

# 使用 pnpm
pnpm add ls-inspection-archive form-data

快速开始

在浏览器环境中使用（React/Vue 等）

import { InspectionArchiveClient } from 'ls-inspection-archive';

// 在浏览器环境中，必须直接传入配置
const client = new InspectionArchiveClient(
  'https://api.example.com',
  'your-secret-key'
);

// 使用示例
async function handleInspection() {
  try {
    // 从文件输入框获取文件
    const fileInput = document.querySelector<HTMLInputElement>('input[type="file"]');
    const file = fileInput?.files?.[0];

    if (file) {
      const result = await client.reportInspection(
        'BATCH001',
        'PASS',
        [{ itemId: 'item1', value: 100, isQualified: true }],
        file  // 直接传入 File 对象
      );
      console.log('上报成功:', result);
    }
  } catch (error) {
    console.error('上报失败:', error);
  }
}

在 Node.js 环境中使用

import { InspectionArchiveClient } from 'ls-inspection-archive';
import { readFileSync } from 'fs';

// 方式1：通过环境变量配置
process.env.LS_ARCHIVE_API_BASE = 'https://api.example.com';
process.env.LS_ARCHIVE_API_KEY = 'your-secret-key';
const client = new InspectionArchiveClient();

// 方式2：直接传入配置
const client = new InspectionArchiveClient(
  'https://api.example.com',
  'your-secret-key'
);

// 使用 Buffer 上报
const imageBuffer = readFileSync('image.jpg');
await client.reportInspection(
  'BATCH001',
  'PASS',
  [{ itemId: 'item1', value: 100, isQualified: true }],
  imageBuffer
);

上报检测数据

// 创建检测详情
const details = [
  {
    itemId: 'item1',
    value: 100,
    isQualified: true,
    description: '测试项目1'
  },
  {
    itemId: 'item2',
    value: 200,
    isQualified: false,
    description: '测试项目2'
  }
];

// 浏览器环境：使用 File 对象
const fileInput = document.querySelector<HTMLInputElement>('input[type="file"]');
const file = fileInput?.files?.[0];
if (file) {
  await client.reportInspection(
    'BATCH001',
    'PASS',
    details,
    file
  );
}

// Node.js 环境：使用 Buffer
import { readFileSync } from 'fs';
const imageBuffer = readFileSync('image.jpg');
await client.reportInspection(
  'BATCH001',
  'PASS',
  details,
  imageBuffer
);

获取检测记录

// 获取最新的10条记录
const records = await client.getInspectionRecords();

// 获取指定数量的记录
const records = await client.getInspectionRecords(20);

// 处理返回的记录
records.forEach(record => {
  console.log(`批次号: ${record.batchNumber}`);
  console.log(`检测结果: ${record.result}`);
  console.log(`创建时间: ${record.createdAt}`);
});

API 参考

InspectionArchiveClient

构造函数

constructor(baseUrl?: string, secretKey?: string)

• baseUrl: API 基础 URL
• secretKey: API 密钥

方法

reportInspection

上报检测数据。

async reportInspection(
  batchNumber: string,
  result: string,
  details: InspectionDetail[],
  imageFile?: File | Buffer
): Promise<InspectionRecord>

参数：

• batchNumber: 批次号
• result: 检测结果 ('PASS' | 'FAIL' | 'WARNING' | 'ERROR')
• details: 检测详情列表
• imageFile: 可选的图片文件
  • 浏览器环境：File 对象
  • Node.js 环境：Buffer

getInspectionRecords

获取检测记录列表。

async getInspectionRecords(limit: number = 10): Promise<InspectionRecord[]>

参数：

• limit: 返回记录数量限制，默认 10 条

类型定义

InspectionResult

检测结果类型。

type InspectionResult = 'PASS' | 'FAIL' | 'WARNING' | 'ERROR';

InspectionDetail

检测详情接口。

interface InspectionDetail {
  itemId: string;
  value: number;
  isQualified: boolean;
  description?: string;
}

InspectionRecord

检测记录接口。

interface InspectionRecord {
  id: string;
  robotId: string;
  batchNumber: string;
  operatorId: string;
  result: string;
  imageData?: string;
  createdAt: Date;
  updatedAt: Date;
  isDeleted: boolean;
}

环境变量

SDK 支持通过环境变量进行配置：

• LS_ARCHIVE_API_BASE: API 基础 URL
• LS_ARCHIVE_API_KEY: API 密钥

错误处理

SDK 会抛出以下类型的错误：

• 配置错误：当缺少必要的配置参数时
• API 错误：当 API 返回非成功状态码时
• 数据验证错误：当输入数据不符合要求时
• 文件处理错误：当文件上传失败时

try {
  const fileInput = document.querySelector<HTMLInputElement>('input[type="file"]');
  const file = fileInput?.files?.[0];

  if (file) {
    await client.reportInspection('BATCH001', 'PASS', details, file);
  }
} catch (error) {
  if (error instanceof Error) {
    console.error('上报失败:', error.message);
  }
}

开发

安装依赖

npm install

构建

npm run build

运行测试

npm test

代码检查

npm run lint

许可证

MIT