zyw-products

一个用于管理产品数据的库，支持多层级分类和向量搜索。

特性

• 🌐 网状分类结构: 支持子分类归属于多个父分类，产品可以同时属于多个分类
• 🌳 多层级分类管理: 支持最多4层分类结构，例如家电 > 电视机 > OLED电视 > 具体型号
• 🔍 产品搜索: 支持按品牌、型号、价格区间等多条件搜索
• 🔄 相似产品推荐: 基于向量相似度搜索相似产品
• 📝 产品文章平台: 支持为产品添加文章内容，支持文章搜索和向量相似性搜索
• 🖼️ 文件管理系统: 支持为产品添加图片和文件，支持按类型、标签搜索和向量相似性搜索
• 📄 分页支持: 所有搜索结果均支持分页
• 📊 类型安全: 使用 Zod 和 TypeScript 确保运行时和编译时类型安全
• 🔗 灵活集成: 可以使用库内置的 Prisma 客户端，或者使用您项目中已有的实例

安装

npm install zyw-products
# 或者使用 yarn
yarn add zyw-products

数据库配置

本库使用 Prisma 与 PostgreSQL 数据库通信，需要安装并启用 pgvector 扩展以支持向量搜索功能。

1. 确保您有一个可用的 PostgreSQL 数据库（推荐 12+ 版本）
2. 在数据库中启用 pgvector 扩展：

CREATE EXTENSION IF NOT EXISTS vector;

3. 在您的项目根目录创建 .env 文件，并设置数据库连接字符串：

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

4. 运行以下命令初始化数据库结构：

npx prisma generate
npx prisma db push

与现有 Prisma 项目集成

如果您的项目已经使用 Prisma，本库支持两种集成方式：

方式一：使用宿主项目的 Prisma 实例（推荐）

如果您已配置 @/prisma 路径别名并导出了 Prisma 实例，本库会自动检测并使用它：

// 在您的项目中 @/prisma 文件（例如 src/prisma/index.ts）
import { PrismaClient } from '@prisma/client';

export const prisma = new PrismaClient();
export default prisma;

确保在 tsconfig.json 中正确配置路径别名：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

方式二：手动设置 Prisma 实例

您也可以手动为本库指定要使用的 Prisma 客户端实例：

import { setPrismaClient } from 'zyw-products';
import { prisma } from './your-prisma-instance';

// 设置 Prisma 客户端实例
setPrismaClient(prisma);

// 之后使用 zyw-products 的功能会使用您提供的 Prisma 实例

基本使用

分类系统

本库支持灵活的网状分类结构，具有以下特点：

• 一个子分类可以有多个父分类
• 一个产品可以属于多个分类，同时指定一个主分类
• 支持递归查询所有子分类的产品

添加分类

import { addCategory } from 'zyw-products';

// 添加一级分类
const electronics = await addCategory({
  name: '家电',
  level: 1 // 根分类级别为1
});

const computers = await addCategory({
  name: '电脑',
  level: 1
});

// 添加二级分类
const tv = await addCategory({
  name: '电视机',
  level: 2,
  parentIds: [electronics.id] // 一个父分类
});

// 添加跨类别的二级分类
const laptops = await addCategory({
  name: '笔记本电脑',
  level: 2,
  parentIds: [electronics.id, computers.id] // 多个父分类
});

// 添加三级分类
const oledTv = await addCategory({
  name: 'OLED电视',
  level: 3,
  parentIds: [tv.id]
});

管理分类关系

import { addCategoryRelation, removeCategoryRelation } from 'zyw-products';

// 添加新的分类关系
await addCategoryRelation({
  parentId: entertainment.id, // 假设已有"娱乐设备"分类
  childId: tv.id // 将"电视机"也归类到"娱乐设备"下
});

// 移除分类关系
await removeCategoryRelation({
  parentId: electronics.id,
  childId: tv.id
});

获取分类

import { getCategoryWithChildren, getCategoryParents } from 'zyw-products';

// 获取分类及其所有子分类
const tvWithChildren = await getCategoryWithChildren(tv.id);
console.log(tvWithChildren.descendantCategories); // 包含所有子分类的平铺数组

// 获取分类的所有父级
const laptopParents = await getCategoryParents(laptops.id);
console.log(laptopParents); // 包含"家电"和"电脑"分类

产品管理

产品可以同时属于多个分类，方便从不同维度对产品进行分类和检索。

添加产品

import { addProduct } from 'zyw-products';

// 添加一个产品并关联到多个分类
const product = await addProduct({
  brand: 'Sony',
  model: 'K-77XR80',
  releaseDate: new Date('2023-05-15'),
  price: 19999,
  keywords: ['OLED', '4K', '智能电视'],
  mainFeatures: ['4K分辨率', 'OLED屏幕', '杜比视界'],
  parameters: {
    resolution: '3840 x 2160',
    size: '77英寸',
    hdr: true,
    smartTv: true,
    connections: {
      hdmi: 4,
      usb: 3,
      ethernet: 1
    }
  },
  categoryIds: [oledTv.id, premiumTv.id, smartTv.id], // 产品属于多个分类
  primaryCategoryId: oledTv.id, // 主分类ID
  // 可选: 向量数据 (如使用 OpenAI 的 embeddings)
  embedding: [0.123, -0.456, 0.789, /* ...更多数字直到1536维 */],
});

管理产品分类

import { addProductCategory, removeProductCategory } from 'zyw-products';

// 为产品添加新分类
await addProductCategory({
  productId: product.id,
  categoryId: newCategory.id,
  isPrimary: false // 设置是否为主分类
});

// 移除产品的某个分类
await removeProductCategory({
  productId: product.id,
  categoryId: oldCategory.id
});

搜索产品

import { searchProducts } from 'zyw-products';

// 基本搜索 (带分页)
const results = await searchProducts({
  query: 'OLED', // 通用搜索词
  categoryId: tvCategory.id, // 可选: 按分类过滤
  brand: 'Sony', // 可选: 按品牌过滤 
  minPrice: 10000, // 可选: 最低价格
  maxPrice: 30000, // 可选: 最高价格
  includeSubcategories: true, // 包含子分类的产品
  page: 1, // 默认第1页
  pageSize: 20 // 默认每页10条
});

console.log(`找到 ${results.total} 个产品，共 ${results.totalPages} 页`);
console.log(results.data); // 产品列表

向量搜索 (相似产品)

import { searchSimilarProducts } from 'zyw-products';

// 假设我们已经有了一个产品的向量表示
const productEmbedding = [0.1, 0.2, ...]; // 1536维向量

文章管理

文章系统允许为产品添加丰富的内容，例如产品说明、评测、使用指南等。

添加文章

import { addArticle } from 'zyw-products';

// 添加一篇文章并关联到产品
const article = await addArticle({
  title: 'Sony K-77XR80 详细评测',
  content: '这是一篇关于Sony K-77XR80电视的详细评测...',
  author: '张三',
  keywords: ['评测', 'OLED', 'Sony', '电视'],
  revision: 1,
  productId: product.id,
  // 可选: 文章内容的向量表示
  embedding: [0.111, -0.222, 0.333, /* ...更多数字 */],
  // 可选: 附加元数据
  metaData: {
    readTime: '15分钟',
    tags: ['专业评测', '图文并茂'],
    rating: 4.8
  }
});

更新文章

import { updateArticle } from 'zyw-products';

// 更新文章内容
const updatedArticle = await updateArticle({
  id: article.id,
  title: 'Sony K-77XR80 全面评测【更新版】',
  content: '更新后的内容...',
  revision: 2, // 增加修订版本
  // 其他字段保持不变
});

搜索文章

import { searchArticles } from 'zyw-products';

// 基本搜索
const articles = await searchArticles({
  query: 'OLED评测', // 通用搜索词
  productId: product.id, // 可选: 按产品ID过滤
  author: '张三', // 可选: 按作者过滤
  page: 1,
  pageSize: 10
});

console.log(`找到 ${articles.total} 篇文章`);
console.log(articles.data); // 文章列表

向量搜索（相似文章）

import { searchSimilarArticles } from 'zyw-products';

// 使用向量搜索相似文章
const similarArticles = await searchSimilarArticles({
  embedding: [0.111, -0.222, 0.333, /* ...更多数字 */], // 查询向量
  similarityThreshold: 0.75, // 相似度阈值
  productId: product.id, // 可选: 限定产品
  page: 1,
  pageSize: 10
});

console.log(similarArticles.data); // 相似文章列表

文件管理

文件系统允许为产品关联图片、文档或其他文件。

添加文件

import { addFile } from 'zyw-products';

// 添加一个图片文件
const image = await addFile({
  url: 'https://example.com/images/sony-tv-front.jpg', // 或本地路径
  type: 'image', // 文件类型
  mimeType: 'image/jpeg',
  tags: ['产品图', '正面图', '高清'],
  productId: product.id,
  // 可选: 文件的向量表示
  embedding: [0.444, -0.555, 0.666, /* ...更多数字 */],
  // 可选: 附加元数据
  metaData: {
    width: 1920,
    height: 1080,
    alt: 'Sony电视正面图',
    sizes: {
      thumbnail: 'https://example.com/images/sony-tv-front-thumb.jpg',
      medium: 'https://example.com/images/sony-tv-front-medium.jpg',
      large: 'https://example.com/images/sony-tv-front-large.jpg'
    },
    pixabayId: '12345678'
  }
});

更新文件

import { updateFile } from 'zyw-products';

// 更新文件信息
const updatedFile = await updateFile({
  id: image.id,
  tags: ['产品图', '正面图', '高清', '官方'],
  metaData: {
    ...image.metaData,
    attribution: '© Sony Corporation'
  }
});

搜索文件

import { searchFiles } from 'zyw-products';

// 基本搜索
const files = await searchFiles({
  query: '高清', // 通用搜索词
  productId: product.id, // 可选: 按产品ID过滤
  type: 'image', // 可选: 按文件类型过滤
  tags: ['产品图'], // 可选: 按标签过滤
  page: 1,
  pageSize: 20
});

console.log(`找到 ${files.total} 个文件`);
console.log(files.data); // 文件列表

向量搜索（相似文件）

import { searchSimilarFiles } from 'zyw-products';

// 使用向量搜索相似文件
const similarFiles = await searchSimilarFiles({
  embedding: [0.444, -0.555, 0.666, /* ...更多数字 */], // 查询向量
  similarityThreshold: 0.8, // 相似度阈值
  type: 'image', // 可选: 限定文件类型
  page: 1,
  pageSize: 20
});

console.log(similarFiles.data); // 相似文件列表

API 参考

查看完整文档获取详细的 API 参考。

贡献

欢迎贡献代码、报告问题或提出改进意见。请先查看贡献指南。

许可证

MIT