# 客服云（kefu_sys）

多租户在线客服 SaaS：租户坐席工作台 + 访客 Widget + 平台超管后台。

消息模型为 **HTTP 落库 + WebSocket 实时推送**；图片经对象存储（MinIO / S3 兼容）上传后以 URL 入消息。

---

## 功能总览

### 租户侧（坐席 / 主管 / 租户管理员）

| 模块 | 能力 |
|------|------|
| **工作台** | 会话列表、领取/转接/结束、文字与图片、输入中提示、内部备注、知识库快捷引用 |
| **实时通信** | 客服/访客 WebSocket（ws/wss）；推送可直接上屏；断线重连后按 `seq` 增量同步 |
| **访客 Widget** | 嵌入脚本、欢迎语、离线留言、结束评价（星级+快捷评语）、重新咨询 |
| **客户管理** | 客户档案、标签、历史会话、CSV 导出 |
| **对话记录** | 筛选、归档、详情回放、CSV 导出 |
| **知识库** | 分类树 CRUD、条目管理 |
| **数据统计** | KPI、趋势、响应分布、渠道分布、坐席绩效、CSV 报告导出 |
| **系统设置** | 基本信息、渠道与嵌入代码、坐席账号/配额、**自动分配策略**、欢迎语/工作时间/通知 |

### 平台侧（`platform_admin`）

| 模块 | 能力 |
|------|------|
| **运营概览** | 租户量、套餐分布、增长等 |
| **租户管理** | 开通/暂停/恢复、联系人与套餐 |
| **套餐定价** | 套餐 CRUD |
| **系统运维** | **真实 metrics**（CPU/内存/磁盘、24h 请求量与错误率、DB/WS/对象存储探测）、操作日志、平台公告 |

### 分配与会话

- **自动分配**（可配置）：`least_load`（负载最低）/ `round_robin`（轮询）
- **最大并发**：每位坐席 `active` 会话上限（0 = 不限）
- **人工**：领取、转接（事件记录操作人与目标）、结束与评价

---

## 技术架构

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  React + Vite   │────▶│  Gin API :8080   │────▶│  PostgreSQL     │
│  Antd/Tailwind  │ WS  │  JWT 多租户      │     │  (开发 :5433)   │
│  :5173          │◀────│  Hub 内存广播    │     └─────────────────┘
└─────────────────┘     │  metrics 中间件  │
                        └────────┬─────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ MinIO / S3      │
                        │ (开发 :9100)    │
                        └─────────────────┘
```

| 层 | 选型 |
|----|------|
| 前端 | React 19、Vite 8、Ant Design 6、Tailwind 4、React Router |
| 后端 | Go、Gin、GORM、JWT、Gorilla WebSocket |
| 数据库 | PostgreSQL（生产/开发主库）；测试可用 SQLite |
| 存储 | MinIO（S3 兼容），图片转 WebP |
| 实时 | 进程内 WebSocket Hub（单实例；多副本需后续 Redis 广播） |

### 消息链路（简要）

```
发送方 ──POST 消息/上传──▶ API 落库(seq 单调)
                              │
                              ├── WebSocket type=message 推送（可带消息体）
                              └── 对端追加或 after_seq 增量拉取
```

- 客服：`/api/ws`（子协议鉴权）
- 访客：`/api/widget/ws?session_id=…`（访客 token）
- 图片：先 `/uploads` 或 `/widget/upload`，再 `type=image` + URL

---

## 目录结构

```
kefu_sys/
├── docker-compose.dev.yml   # Postgres + MinIO
├── Makefile
├── docs/                    # 产品原型 / 需求 HTML
├── server/
│   ├── cmd/main.go          # 服务入口
│   ├── cmd/seed/            # 演示数据
│   └── internal/
│       ├── config/          # 环境变量配置
│       ├── handler/         # HTTP / Widget / 导出 / 分配
│       ├── metrics/         # 请求统计与运维指标
│       ├── middleware/      # JWT / 平台权限
│       ├── model/           # GORM 模型与消息序号
│       ├── storage/         # 对象存储抽象
│       └── ws/              # WebSocket Hub
└── web/
    ├── public/widget.js     # 嵌入脚本入口
    └── src/
        ├── pages/agent/     # 租户工作台等
        ├── pages/admin/     # 平台后台
        ├── widgets/         # 访客聊天组件
        └── services/        # API 与 CSV 下载
```

---

## 生产部署（腾讯云 Docker）

单机一键部署（Nginx + API + PostgreSQL + MinIO）：

```bash
# 服务器安装 Docker 后
chmod +x deploy/scripts/*.sh
./deploy/scripts/deploy.sh          # 首次会生成 deploy/.env.prod，请改公网地址
./deploy/scripts/deploy.sh --seed   # 可选：导入演示账号
```

说明见 **[deploy/README.md](deploy/README.md)**（安全组、HTTPS、COS 替换 MinIO、备份升级）。

---

## 本地开发

### 环境要求

- Go 1.22+（仓库 `go.mod` 声明见 `server/go.mod`）
- Node.js 20+
- Docker（数据库与 MinIO）

### 1. 基础设施

```bash
make db-up
# 或：docker compose -f docker-compose.dev.yml up -d
```

| 服务 | 地址 |
|------|------|
| PostgreSQL | `localhost:5433`（用户/库/密码见下表） |
| MinIO API | `http://localhost:9100` |
| MinIO 控制台 | `http://localhost:9101`（minioadmin / minioadmin） |

### 2. 后端

```bash
cd server
go mod download
go run ./cmd/main.go
# 默认 :8080
```

首次启动会 AutoMigrate。可选种子数据：

```bash
cd server && go run ./cmd/seed
```

### 3. 前端

```bash
cd web
npm install
npm run dev
# 默认 http://localhost:5173 ，/api 与 WS 代理到 :8080
```

### 4. 一键（Makefile）

```bash
make install   # 前后端依赖
make db-up
# 再分别启动后端与前端，或使用 make dev（按需调整）
```

### 默认账号（seed 后）

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 平台管理员 | `platform_admin` | `kefu_admin123` |
| 租户管理员 | `kefu_admin` | `kefu_admin123` |
| 主管 | `supervisor` | `kefu_admin123` |
| 坐席 | `agent1` / `agent2` / `agent3` | `kefu_admin123` |

### 常用入口

| 地址 | 说明 |
|------|------|
| http://localhost:5173/login | 登录 |
| http://localhost:5173/agent/dashboard | 客服工作台 |
| http://localhost:5173/admin | 平台后台 |
| http://localhost:5173/widget/preview | 访客 Widget 预览 |
| 渠道嵌入 | 设置 → 渠道管理 → 复制 script（`data-id` 为 channel_key） |

---

## 主要环境变量

后端通过环境变量加载（可 `server/.env` 配合 shell `set -a`）：

| 变量 | 默认 | 说明 |
|------|------|------|
| `SERVER_PORT` | `8080` | HTTP 端口 |
| `GIN_MODE` | `debug` | Gin 模式 |
| `DB_HOST` / `DB_PORT` | `localhost` / `5433` | 数据库 |
| `DB_USER` / `DB_PASSWORD` / `DB_NAME` | `postgres` / `postgres` / `kefu_sys` | |
| `JWT_SECRET` | 内置开发密钥 | **生产务必修改** |
| `STORAGE_ENDPOINT` | `localhost:9100` | MinIO/S3 |
| `STORAGE_ACCESS_KEY` / `STORAGE_SECRET_KEY` | `minioadmin` | |
| `STORAGE_BUCKET` | `kefu` | |
| `STORAGE_PUBLIC_BASE_URL` | `http://localhost:9100/kefu` | 浏览器访问前缀 |

---

## 角色与权限（概要）

| 角色 | 范围 |
|------|------|
| `platform_admin` | 平台租户/套餐/运维（`TenantID=0`） |
| `admin` | 租户管理员：设置、坐席、全量会话等 |
| `supervisor` | 主管：统计、客户、会话监管 |
| `agent` | 一线：本人会话 + 排队领取；客户可见范围为相关会话客户 |

Widget 访客使用 `visitor_token`，与会话绑定，不走 JWT 坐席体系。

---

## API 分组（摘录）

| 前缀 | 说明 |
|------|------|
| `POST /api/login` | 登录 |
| `/api/widget/*` | 访客 init/消息/留言/评价/上传/WS |
| `/api/ws` | 坐席 WebSocket |
| `/api/sessions/*` | 会话、消息、`after_seq` 增量、导出 |
| `/api/customers/*` | 客户 CRUD、导出 |
| `/api/statistics/*` | 统计与导出 |
| `/api/settings` | 租户设置（含分配策略） |
| `/api/staff` | 坐席账号 |
| `/api/admin/*` | 平台管理 + `ops/metrics` |
| `GET /health` | 健康检查 |

完整路由见 `server/internal/handler/router.go`。

---

## 测试

```bash
cd server && go test ./...
cd web && npx tsc --noEmit
```

集成测试覆盖鉴权隔离、自动分配、转接、Widget 等（`handler` 包内）。

---

## 产品现状与后续方向

### 已具备（适合演示 / 中小单实例）

- 完整接待闭环：进线 → 分配 → 聊天 → 转接/结束 → 评价 → 重新咨询  
- 租户隔离、坐席配额、知识库、统计与 CSV 导出  
- 运维页进程级真实负载与请求错误率  
- 分配策略可配置（负载最低 / 轮询 + 并发上限）

### 已知边界（有意未做或单实例限制）

| 项 | 说明 |
|----|------|
| 多 API 实例 | Hub 为进程内存；扩副本需 Redis Pub/Sub 等跨节点广播 |
| 独立消息队列 | 当前不需要；实时靠 WS Hub |
| 技能组 / 渠道专属坐席 | 未做；可在候选过滤层扩展 |
| 厂商推送（APNs/FCM） | 未做 |
| 微信/APP/电话渠道 | 模型预留，完整对接未做 |

### 建议演进顺序

1. 生产配置加固（JWT、HTTPS、存储与 DB 备份）  
2. 需要水平扩展时：Redis 会话广播 + sticky 或共享连接层  
3. 技能组 / 渠道路由  
4. 监控可对接 Prometheus（现有 metrics 可作过渡）

---

## 设计稿与需求

`docs/` 下保留各页面 HTML 原型与需求说明：

- `docs/spec/` 开发需求  
- `docs/agent/` 租户端页面  
- `docs/admin/` 平台端页面  

---

## 许可证

内部项目 / 按团队约定使用。未单独声明开源协议时，默认保留所有权利。