# AI-Customer-Service

**Repository Path**: my-rl/ai-customer-service

## Basic Information

- **Project Name**: AI-Customer-Service
- **Description**: 智能 AI 客服助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能 AI 客服助手 · SaaS 平台

面向中小企业的多租户智能客服 SaaS：**知识库 + RAG 问答 + 销售线索自动抽取 + 人工接管 + 开放 API**。

配套核心闭环页面共 15 个，覆盖「配置 → 灌知识 → 调策略 → 上线 → 看数据 → 拿线索」的完整业务链路。

---

## 1. 系统架构

```
┌──────────────────────────────────────────────────────────────────────────┐
│  浏览器                                                                   │
│  Vue 3 + TypeScript + Vite + Pinia + ECharts   （:5173 dev / :80 prod）   │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ REST /api  (Bearer JWT | X-API-Key)
┌───────────────────────────────▼──────────────────────────────────────────┐
│  SaaS 后端   Java 21 + Spring Boot 3.3.1   （:8080）                      │
│  Spring Security（JWT + API_KEY 双鉴权）· JPA · Flyway                    │
│  多租户隔离（tenant_id 强约束 + IDOR 防护）· Redis · RabbitMQ              │
│  Prometheus / Actuator / OpenTelemetry                                    │
└───────┬──────────────────────────────────────────────────────────────────┘
        │ MySQL 8            │ Redis              │ RabbitMQ
        │ 业务数据 + 租户数据  │ 幂等/限流/审计缓存   │ 异步 ingest / 导出任务
        │
        │ 内部 HTTP  /internal/v1/*   （X-Internal-Token）
┌───────▼──────────────────────────────────────────────────────────────────┐
│  AI 服务   Python 3.12 + FastAPI + Pydantic   （:8000）                    │
│  多 Provider Adapter（模型可插拔）                                          │
│  自研 RAG Orchestrator：FAQ → 向量召回 → Rerank → 阈值过滤 → LLM → 抽取      │
│  Embedding Adapter · 独立 Rerank Adapter · 线索抽取（正则 + 语义）           │
│  向量库：V1 pgvector（自动降级内存）                                        │
└──────────────────────────────────────────────────────────────────────────┘
```

技术选型与需求方给定清单完全一致，详见第 6 节。

---

## 2. 目录结构

```
AI-Customer-Service/
├── docs/API-CONTRACT.md              # 三层共享接口契约（唯一真源）
├── 设计文档/                          # 需求方提供的 PRD / ER 图 / 建表 SQL / 页面设计稿
├── frontend/                         # Vue 3 + TS 控制台（15 个业务页面）
├── backend/                          # Java 21 + Spring Boot 3 SaaS 后端
├── ai-service/                       # Python 3.12 + FastAPI AI 服务（169 个单测）
├── docker-compose.yml                # 一键起 MySQL/Redis/RabbitMQ/AI/后端/前端
└── README.md
```

---

## 3. 快速开始

### 3.1 一键起全栈（推荐，需要 Docker）

```bash
cp .env.example .env 2>/dev/null || true
docker compose up -d --build
```

| 服务 | 地址 |
|---|---|
| 前端控制台 | http://localhost |
| 后端 API / Swagger | http://localhost:8080/swagger-ui.html |
| AI 服务 / Swagger | http://localhost:8000/docs |
| RabbitMQ 管理台 | http://localhost:15672 |

### 3.2 本地开发（无 Docker）

```bash
# ① AI 服务
cd ai-service
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

# ② 后端（需要本机 MySQL 8 / Redis / RabbitMQ）
cd backend
JAVA_HOME=/path/to/jdk-21 mvn spring-boot:run -Dspring-boot.run.profiles=dev

# ③ 前端（默认走内置 Mock，无需后端即可完整体验 15 个页面）
cd frontend
npm install --registry=https://registry.npmmirror.com
npm run dev            # http://localhost:5173
```

> 前端默认 `VITE_USE_MOCK=true`，使用确定性 Mock 数据，**未启动后端也能跑通全部页面**。
> 联调时改为 `VITE_USE_MOCK=false`，请求会经 Vite 代理打到 `http://127.0.0.1:8080`。

演示账号：`chen@acme.com` / `admin123`（仅 dev profile 初始化）。

---

## 4. 核心业务规则（已实现）

| 规则 | 落地位置 |
|---|---|
| **多租户强隔离**：所有查询强制带 `tenant_id`，越权访问返回 403/404 而非数据 | `common/TenantContext`、各 `Service` 仓储方法 |
| **人工接管优先于 AI**：会话处于人工接管态时不生成 AI 回复，但仍持续抽取线索 | `MessageOrchestratorService` |
| **客户消息先落库**：先持久化客户消息，再调用 AI —— LLM 失败绝不丢消息 | `MessageOrchestratorService` |
| **LLM 失败不丢线索**：Provider 异常时降级为纯规则抽取，线索照常入库 | `ai-service/app/rag/orchestrator.py` 降级链 |
| **平台安全约束不可覆盖**：安全提示词强制追加在 system prompt 末尾，租户无法注入 | `ai-service/app/prompt/assembler.py` |
| **密钥安全**：LLM Provider Key 用 AES-256-GCM 加密存储；API Key 只存 SHA-256；密码 BCrypt | `crypto/CryptoService` |
| **写操作幂等**：基于 Redis 的幂等键，防止重复提交造成重复扣费/重复建单 | `Redis` + `RequestIdFilter` |

---

## 5. 关键链路

### 5.1 一次问答（含引用溯源与线索抽取）

```
客户消息
  → Java：租户校验 → 会话定位 → 判断是否人工接管中 → 客户消息先落库
  → Java → Python /internal/v1/chat（携带 Prompt、FAQ、字段定义、KB collection）
      → ① FAQ 精确/关键词匹配（≥0.82 高置信直接命中）
      → ② 向量召回（pgvector；Embedding 不可用则降级 BM25 关键词）
      → ③ Rerank 精排（Cohere/BGE/LLM；不可用则按召回相似度）
      → ④ 阈值过滤（<0.35 视为无命中 → 返回兜底话术并转人工）
      → ⑤ 上下文组装 + 引用溯源（来源/分值/片段）
      → ⑥ LLM 生成（严格超时 + 退避重试 + 结构化错误）
      → ⑦ 线索字段抽取（正则优先 → 语义兜底 → 校验）
  → Java：AI 回复落库 + 引用落库 + 线索 upsert（字段值 + 置信度 + 来源消息）
  → 前端：会话详情实时展示回复、引用卡片、已抽取字段
```

### 5.2 知识库灌入

```
上传文档 → Java 落库（文档 + 版本） → RabbitMQ 异步任务
        → Python /internal/v1/ingest（解析 → 切片 → 向量化 → 写向量库）
        → 回写切片数、失败原因；前端轮询进度
```

---

## 6. 技术栈对照

| 模块 | 要求 | 实现 |
|---|---|---|
| 前端 | Vue 3 + TypeScript | Vue 3.5 `<script setup>` + TS 5.6 + Vite 5 + Pinia + Vue Router(hash) + ECharts |
| SaaS 后端 | Java 21 + Spring Boot 3 | Spring Boot 3.3.1 + Java 21 + JPA + Flyway + Security + Redis + RabbitMQ |
| AI 服务 | Python 3.12 + FastAPI | FastAPI 0.141 + Uvicorn（3.12 兼容）+ 169 pytest 用例 |
| AI 数据模型 | Pydantic | Pydantic v2.13（`app/schemas/`） |
| LLM | 多 Provider Adapter | Registry 模式：OpenAI 兼容 / Claude 原生 / Azure，新增供应商零改路由 |
| RAG | 自研 Orchestrator | `app/rag/orchestrator.py`（未依赖 LlamaIndex/LangChain 也可独立运行） |
| Embedding | Provider Adapter | `app/providers/embeddings.py`，含零依赖哈希降级 |
| Rerank | 独立 Adapter | `app/providers/rerank.py`：Cohere / BGE / LLM / Similarity |
| 数据库 | MySQL 8 | MySQL 8.0 + Flyway 迁移（V1 建表 / V2 演示数据） |
| 缓存 | Redis | 幂等、限流、审计、会话上下文 |
| 消息队列 | RabbitMQ | 异步 ingest / 导出 |
| 向量库 | V1 pgvector | `PgVectorStore`（未配置 DSN 时静默降级内存向量库） |
| 文件存储 | OSS/S3/MinIO | 本地 `./data/uploads`（可替换为 S3 兼容实现） |
| API | REST / OpenAPI | springdoc-openapi + FastAPI 自动文档，契约见 `docs/API-CONTRACT.md` |
| Java↔Python | V1 HTTP | `/internal/v1/*` + `X-Internal-Token`（预留 gRPC 演进） |
| 部署 | Docker | 三端独立 Dockerfile + `docker-compose.yml` |
| 监控 | Prometheus + Grafana + OTel | Actuator + micrometer-registry-prometheus + 结构化 JSON 日志 |

---

## 7. 质量与验证

| 项目 | 结果 |
|---|---|
| 前端生产构建 | ✅ `✓ built in 3.95s` |
| 后端编译 | ✅ `BUILD SUCCESS`（JDK 21） |
| AI 服务单测 | ✅ `169 passed`（零网络、零数据库依赖） |
| AI 服务端到端 | ✅ `/health`、`/ingest`、`/extract`、`/embed`、`/rerank`、`/chat`、鉴权拒绝，全部按契约返回 |
| 降级链路 | ✅ 无外网、无 API Key、无向量库时仍然可用（返回结构化错误 + 兜底话术） |

```bash
# 复现验证
cd ai-service && python -m pytest -q
cd backend    && JAVA_HOME=/path/to/jdk-21 mvn -DskipTests compile
cd frontend   && npm run build
```

---

## 8. 文档索引

- [`docs/API-CONTRACT.md`](docs/API-CONTRACT.md) —— 统一响应外壳、错误码表、全部控制台接口、Java↔Python 契约、15 个页面路由映射
- [`docs/DEPLOYMENT-CENTOS.md`](docs/DEPLOYMENT-CENTOS.md) —— **CentOS 部署指引**：版本选型、Docker Compose 与裸机 systemd 两套方案、初始化、HTTPS、监控、备份、升级回滚、排障速查表、验收清单
- [`ai-service/README.md`](ai-service/README.md) —— AI 服务设计说明、环境变量、扩展新 Provider 指引
- [`backend/README.md`](backend/README.md) —— 后端结构、业务规则、环境变量
- `设计文档/` —— 需求方原始 PRD、ER 图、建表 SQL、核心闭环页面设计