2026-03-07 09:01:00 +08:00
|
|
|
|
# SAARS 全栈聊天助手平台
|
|
|
|
|
|
|
|
|
|
|
|
企业级聊天助手平台，前后端分离，支持实时聊天、用户管理、内容审核。技术规范见项目根目录《全栈聊天助手平台开发技术规范》。
|
|
|
|
|
|
|
|
|
|
|
|
## 仓库结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
saars/
|
|
|
|
|
|
├── backend/ # Flask 后端
|
|
|
|
|
|
│ ├── app/
|
|
|
|
|
|
│ │ ├── api/ # REST 端点
|
|
|
|
|
|
│ │ ├── models/ # 数据模型
|
|
|
|
|
|
│ │ ├── services/ # 业务逻辑
|
|
|
|
|
|
│ │ ├── admin/ # Flask-Admin 管理
|
|
|
|
|
|
│ │ └── utils/
|
|
|
|
|
|
│ ├── tests/
|
|
|
|
|
|
│ ├── requirements.txt
|
|
|
|
|
|
│ └── Dockerfile
|
|
|
|
|
|
├── android-app/ # Android 客户端 (Java, MVVM)
|
|
|
|
|
|
│ ├── app/
|
|
|
|
|
|
│ │ ├── data/ # 数据层 (Retrofit, Room)
|
|
|
|
|
|
│ │ ├── domain/ # 领域层
|
|
|
|
|
|
│ │ └── presentation/# 表现层 (Activity, ViewModel)
|
|
|
|
|
|
│ └── build.gradle
|
|
|
|
|
|
├── docker-compose.yml
|
|
|
|
|
|
└── README.md
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 后端 (Flask)
|
|
|
|
|
|
|
|
|
|
|
|
- **框架**: Flask 2.3+, Flask-SocketIO, Flask-JWT-Extended, Flask-Admin
|
|
|
|
|
|
- **数据库**: 腾讯云 MySQL (liaotian_db)，SQLAlchemy ORM + PyMySQL，Flask-Migrate
|
|
|
|
|
|
- **缓存/队列**: Redis 7+
|
|
|
|
|
|
- **认证**: JWT + 刷新令牌
|
|
|
|
|
|
|
|
|
|
|
|
### 本地运行
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cd backend
|
|
|
|
|
|
python -m venv venv
|
|
|
|
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
|
|
|
|
pip install -r requirements.txt
|
|
|
|
|
|
export FLASK_ENV=development
|
|
|
|
|
|
export DATABASE_URL=mysql+pymysql://root:!Rjb12191@gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936/liaotian_db?charset=utf8mb4
|
|
|
|
|
|
export REDIS_URL=redis://localhost:6379/0
|
2026-03-07 10:29:17 +08:00
|
|
|
|
# 首次部署：在腾讯云 MySQL 上先建库（见 backend/scripts/init_db.sql），再执行：
|
|
|
|
|
|
flask db upgrade
|
2026-03-07 09:01:00 +08:00
|
|
|
|
python run.py # 或 gunicorn -k eventlet -w 1 run:app
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Docker
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
docker-compose up -d
|
|
|
|
|
|
# 后端监听 8052 端口（腾讯云已放行）；首次需在 backend 容器内: flask db init && flask db migrate -m "init" && flask db upgrade
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### API 概览
|
|
|
|
|
|
|
|
|
|
|
|
| 模块 | 路径前缀 | 说明 |
|
|
|
|
|
|
|----------|-----------------|----------------|
|
|
|
|
|
|
| 认证 | `/api/v1/auth` | 注册、登录、刷新、/me |
|
|
|
|
|
|
| 聊天 | `/api/v1/chat` | 会话列表、消息、撤回 |
|
|
|
|
|
|
| 文件 | `/api/v1/files` | 上传（图片/文档，最大 10MB） |
|
|
|
|
|
|
| 管理 | `/api/v1/admin` | 用户管理、会话审计、统计（需 admin 角色） |
|
|
|
|
|
|
| 知你客服 | `/api/v1/agent` | Agent 代理（方式一）：`POST /chat` 与知你客服对话 |
|
|
|
|
|
|
|
|
|
|
|
|
- 服务端口：**8052**（可在环境变量 `PORT` 或 docker-compose 中修改）
|
|
|
|
|
|
- 管理界面: `/admin`（需 Bearer Token 且角色为 admin）
|
|
|
|
|
|
|
|
|
|
|
|
### 知你客服 Agent 代理（方式一）
|
|
|
|
|
|
|
|
|
|
|
|
- 按《知你客服 Agent 智能聊天 App 接入方案》方式一：SAARS 后端用平台账号登录拿 Token，代 App 用户调平台执行 API，再返回回复。
|
|
|
|
|
|
- **配置**：在环境变量或 `docker-compose.yml` 中设置
|
|
|
|
|
|
`PLATFORM_BASE_URL`（如 `http://101.43.95.130:8037`）、`PLATFORM_USERNAME`、`PLATFORM_PASSWORD`、`PLATFORM_AGENT_ID`（知你客服的 Agent ID）。在低代码平台为对接创建一个账号，在 Agent 管理中复制「知你客服」的 ID 填入。
|
|
|
|
|
|
- **接口**：`POST /api/v1/agent/chat`，Body `{ "message": "用户输入", "user_id": "可选" }`，响应 `{ "reply": "客服回复" }`。需登录 SAARS 的 JWT。
|
|
|
|
|
|
|
|
|
|
|
|
## Android 客户端 (Java)
|
|
|
|
|
|
|
|
|
|
|
|
- **最小 SDK**: API 30 (Android 11)
|
|
|
|
|
|
- **架构**: MVVM, Architecture Components, Retrofit, Socket.IO Client, Room
|
|
|
|
|
|
- **UI**: Material Design 3, RecyclerView 消息列表
|
|
|
|
|
|
|
|
|
|
|
|
### Room 离线
|
|
|
|
|
|
|
|
|
|
|
|
- 会话列表、消息列表首次从本地 Room 加载（秒开），再拉取接口并写回 Room。
|
|
|
|
|
|
- 发送成功的消息会写入 Room，Socket 收到的新消息也会写入 Room，下次进入直接读本地。
|
|
|
|
|
|
|
|
|
|
|
|
### Socket.IO 实时
|
|
|
|
|
|
|
|
|
|
|
|
- 登录/注册成功后自动连接 Socket（query 带 token），进入聊天页会 `join_conversation`，退出会 `leave_conversation`。
|
|
|
|
|
|
- 后端发消息后通过 `broadcast_new_message` 推送到房间，客户端收到 `new_message` 后写入 Room 并刷新列表。
|
|
|
|
|
|
|
|
|
|
|
|
### FCM 推送
|
|
|
|
|
|
|
|
|
|
|
|
- 已接入 `firebase-messaging` 与 `ChatFirebaseMessagingService`，后台/进程被杀时由 FCM 下发通知。
|
|
|
|
|
|
- **启用步骤**：在 [Firebase 控制台](https://console.firebase.google.com/) 创建项目并添加 Android 应用，下载 `google-services.json` 放到 `android-app/app/`；在根目录 `build.gradle` 的 `plugins` 中增加 `id 'com.google.gms.google-services' version '4.4.0' apply false`，在 `app/build.gradle` 的 `plugins` 中取消注释 `id 'com.google.gms.google-services'`，同步后即可。可选：后端提供 `POST /api/v1/users/me/fcm_token` 保存 token，便于服务端发定向推送。
|
|
|
|
|
|
|
|
|
|
|
|
### 知你客服入口
|
|
|
|
|
|
|
|
|
|
|
|
- 会话列表页右下角有两个 FAB：**知你客服**（上方）、**新对话**（下方）。点击「知你客服」进入与知你客服 Agent 的对话页，消息通过 SAARS 后端代理转发到低代码平台执行 API，回复展示在列表中并写入 Room 做历史。
|
|
|
|
|
|
|
|
|
|
|
|
### 构建
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cd android-app
|
|
|
|
|
|
./gradlew assembleDebug
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
将 `build.gradle` 中 `applicationId` 与后端地址配置为实际环境后安装运行。
|
|
|
|
|
|
|
|
|
|
|
|
## 质量与部署
|
|
|
|
|
|
|
|
|
|
|
|
- **测试**: 后端 `pytest`，目标单元测试覆盖率 ≥85%
|
|
|
|
|
|
- **部署**: Docker 容器化，可配合 CI/CD 流水线
|
|
|
|
|
|
- **扩展**: 无状态 API + Redis，支持水平扩展
|
|
|
|
|
|
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
|
|
|
|
|
|
内部项目，按公司规定使用。
|
