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，支持水平扩展

许可证

内部项目，按公司规定使用。

README.md Unescape Escape

SAARS 全栈聊天助手平台

仓库结构

后端 (Flask)

本地运行

Docker

API 概览

知你客服 Agent 代理（方式一）

Android 客户端 (Java)

Room 离线

Socket.IO 实时

FCM 推送

知你客服入口

构建

质量与部署

许可证

README.md