补充项目 README：架构、功能、本地启动与边界说明

2026-07-15 15:14:13 +08:00
parent c43f420875
commit 2b18d654b3
1 changed files with 285 additions and 0 deletions
@@ -0,0 +1,285 @@
+# 客服云（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 下载
+```
+
+---
+
+## 本地开发
+
+### 环境要求
+
+- 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/` 平台端页面  
+
+---
+
+## 许可证
+
+内部项目 / 按团队约定使用。未单独声明开源协议时，默认保留所有权利。