# 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
# 首次部署：在腾讯云 MySQL 上先建库（见 backend/scripts/init_db.sql），再执行：
flask db upgrade
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，支持水平扩展

## 许可证

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