# customer_service

**Repository Path**: rich_mona/customer_service

## Basic Information

- **Project Name**: customer_service
- **Description**: 客服工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 客服知识库工具

面向客服团队的本地知识库管理与快速检索工具。前台用于搜索、查看和复制标准回复；后台用于内容维护、分类管理、AI 辅助整理、系统设置和 JSON 数据备份。

## 技术栈

- React 19 + TypeScript
- Vite
- Tailwind CSS
- Radix UI / shadcn 风格组件
- Lucide Icons
- Node.js 原生 HTTP 服务
- 本地 JSON 文件存储

## 快速开始

安装依赖：

```bash
npm install
```

开发模式：

```bash
npm run dev
```

构建生产产物：

```bash
npm run build
```

启动生产服务：

```bash
npm run serve
```

默认访问地址：

```text
http://localhost:13230/
```

修改端口：

```bash
PORT=13231 npm run serve
```

## 功能概览

### 前台搜索

- 支持标题、正文、关键词、标签和关联词搜索。
- 支持分类筛选、关键词高亮、内容详情查看。
- 支持图片预览、附件下载、多个附件打包下载。
- PC 端复制按钮使用就地反馈，复制成功后按钮短暂显示绿色“已复制”状态。
- 移动端采用吸顶搜索栏、紧凑列表和底部详情抽屉。
- 快捷搜索：
  - Windows / Linux: `Ctrl+K`
  - macOS: `Command+K`
  - 通用: `/`

### 后台内容管理

- 内容列表适合大量知识条目浏览。
- 点击内容条目默认进入编辑；右侧预览按钮用于查看详情。
- 支持搜索、分类筛选、排序、批量选择、批量删除、批量调整分类。
- 分类筛选按需请求后端：`GET /api/data?categoryId=xxx`，避免总是全量加载内容。
- 新建内容支持两种模式：
  - `智能导入`：粘贴原始反馈或聊天记录后，由后端代理调用 AI 整理成标准知识条目。
  - `手动编辑`：维护标题、分类、正文、关键词、标签、关联词和附件。

### 分类管理

- 支持一级分类和子分类。
- 支持新增、编辑、删除分类。
- 支持 AI 智能分类：
  - 后端只读取文章 `id`、`title`、`keywords`，不会读取正文。
  - OpenAI 兼容接口使用 JSON 模式，强制返回可解析分类结构。
  - 返回结构包含 `categories / categoryName / articleIds / subCategories` 后，前端预览并可应用。

### 系统设置

- 在线 AI 配置：
  - Provider: OpenAI / DeepSeek / Anthropic / 自定义 OpenAI 兼容接口。
  - API Key、Base URL、Model。
  - 测试连接和保存配置。
- 数据导入与导出：
  - 导出标准 JSON 备份。
  - 从标准 JSON 备份导入恢复。
  - 当前仅支持上传标准的 JSON 备份文件。
- 常规设置：
  - 自定义前台首页标题。
  - 自定义标题旁图标。

## 数据存储

默认数据目录：

```text
data/
```

主要文件：

```text
data/db.json             # 分类、内容、复制历史
data/ai-settings.json    # 后端保存的 AI 配置，包含 API Key
data/attachments/        # 新上传附件
```

可通过环境变量指定数据目录：

```bash
KNOWLEDGE_DATA_DIR=/path/to/data npm run serve
```

历史兼容：

- 新附件路径为 `/api/attachments/:filename`。
- 后端兼容旧路径 `/uploads/:filename`，会按同一套附件读取逻辑返回文件流。
- 兼容路由会查找 `data/attachments/` 和项目根目录 `uploads/`。

## AI 安全模型

AI Key 不再保存在浏览器中。后台系统设置保存 AI 配置时，会写入后端的 `data/ai-settings.json`。

前端不会直接请求 OpenAI、DeepSeek 或 Anthropic，而是统一请求本服务：

```text
POST /api/ai/proxy
```

后端再根据已保存配置代理调用大模型服务。这样可以避免 API Key 暴露在前端代码、浏览器请求或 localStorage 中。

说明：

- `GET /api/ai/settings` 只返回公开配置和 `hasApiKey`，不会返回真实 API Key。
- 智能导入支持 OpenAI 兼容接口和 Anthropic。
- 智能分类依赖 OpenAI 兼容 JSON 模式；Anthropic 不用于该后端分类接口。

## 后端接口

服务入口：`server.mjs`

- `GET /api/data`  
  获取完整知识库数据。

- `GET /api/data?categoryId=xxx`  
  只返回指定分类下的内容，同时返回分类和复制历史。

- `PUT /api/data`  
  保存完整知识库数据。

- `GET /api/backup`  
  导出备份数据，附件会内联为 Data URL。

- `POST /api/import`  
  导入标准 JSON 备份数据。

- `GET /api/ai/settings`  
  获取公开 AI 配置，不返回真实 API Key。

- `PUT /api/ai/settings`  
  保存 AI 配置到后端数据目录。

- `POST /api/ai/proxy`  
  后端代理 AI 操作，支持 `validate`、`optimize`、`categories`。

- `POST /api/ai/categories`  
  兼容旧智能分类入口，内部使用后端保存的 AI 配置。

- `GET /api/attachments/:filename`  
  读取附件资源。

- `GET /uploads/:filename`  
  兼容旧附件路径。

## 常用命令

```bash
npm run dev       # Vite 开发服务
npm run build     # TypeScript + Vite 构建
npm run serve     # 使用 server.mjs 服务 dist 和 API，默认 13230 端口
npm run start     # 构建后启动 server.mjs
npm run lint      # ESLint
```

## 目录结构

```text
src/
  components/
    admin/        # 后台管理、内容编辑、分类管理、系统设置
    search/       # 前台搜索首页
    ui/           # 通用 UI 组件
  services/       # 数据、AI、应用设置服务
  types/          # TypeScript 类型
  utils/          # 文件、附件、格式化等工具
server.mjs        # 静态资源、API、AI 代理和附件服务
data/db.json      # 默认 JSON 数据库
```

## 备注

- 本项目面向单机或轻量部署场景，数据默认保存在本地 JSON 文件。
- 目前 `PUT /api/data` 是整体写入 JSON 文件；多人同时写入场景需要额外设计并发控制、鉴权、审计和备份策略。
- 导入会覆盖当前数据，操作前建议先导出备份。