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 + 刷新令牌
本地运行
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
# 首次部署：在腾讯云 MySQL 上先建库（见 backend/scripts/init_db.sql），再执行：
flask db upgrade
python run.py # 或 gunicorn -k eventlet -w 1 run:app
Docker
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 控制台 创建项目并添加 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 做历史。
构建
cd android-app
./gradlew assembleDebug
将 build.gradle 中 applicationId 与后端地址配置为实际环境后安装运行。
质量与部署
- 测试: 后端
pytest，目标单元测试覆盖率 ≥85% - 部署: Docker 容器化，可配合 CI/CD 流水线
- 扩展: 无状态 API + Redis，支持水平扩展
许可证
内部项目，按公司规定使用。