# ReplyPier 本机使用

## 打开演示页与客服工作台

- 网站悬浮客服演示：<http://127.0.0.1:3018/local-demo.html>
- 管理员 / 人工客服登录：<http://127.0.0.1:3018/>
- 会话工作台：<http://127.0.0.1:3018/conversations>

### 本机账号

| 身份 | 登录邮箱 | 用途 |
| --- | --- | --- |
| 管理员 | `admin@example.com` | 管理配置、查看全部会话与评分 |
| 客服 A | `support.a@example.com` | 接待、处理自己的会话 |
| 客服 B | `support.b@example.com` | 多客服协作与会话隔离 |

密码保存在 [本机账号文件](deploy/local/.state/test-accounts.json)，分别查看 `admin.password`、`agent_a.password`、`agent_b.password`。不要公开或提交该文件。不同客服使用不同浏览器或无痕窗口登录，避免账号互相覆盖。

### 使用流程

1. 以人工客服登录工作台，保持页面在线。
2. 在另一个浏览器窗口打开演示页，点击右下角悬浮按钮。
3. 提问知识库中已有答案的产品或售后问题。
4. 发“我要转人工。”，在工作台 Inbox 中找到待人工会话，点击 **Take over chat**。
5. 人工回复后，点击 **End Chat → End Chat & Request Rating**，访客可以提交星级和文字评价。
6. 管理员在 **Inbox → Closed** 查看对话，在 **Analytics → Agent Performance → Human Agents** 查看评分，在 **Analytics → Customers → View Details** 查看文字评价。

本机接待时段为每天全天，两名客服属于 `Local Support` 分组。示例知识为虚构政策，正式使用前应替换为实际业务资料。

## 启动、停止与日志

Mac 重启后，在终端执行：

```bash
cd /Users/a11/1020-1030/01-projects/replypier
./deploy/local/local.sh up
```

常用命令：

```bash
./deploy/local/local.sh status
./deploy/local/local.sh logs backend
./deploy/local/local.sh logs knowledge
./deploy/local/local.sh logs frontend
./deploy/local/local.sh restart
./deploy/local/local.sh stop
```

`stop` 停止本项目服务及数据库、缓存，不删除数据卷。`restart` 重启应用进程，保留数据库与缓存。未配置系统开机自启动。

修改前端源码后，执行 `./deploy/local/local.sh build`，再执行 `restart`。构建会根据已有 Widget ID 生成演示页。`setup` 用于安装依赖和构建，不覆盖已有环境配置，也不创建新管理员。

## 部署结构与数据

Python 后端、知识库 worker、前端预览服务在宿主机运行；PostgreSQL 与 Redis 在 Colima 虚拟机中运行。

| 服务 | 本机地址 |
| --- | --- |
| 工作台 / 演示页 | `127.0.0.1:3018` |
| API / Widget / Socket.IO | `127.0.0.1:8018` |
| PostgreSQL 16 + pgvector | `127.0.0.1:15432` |
| Redis | `127.0.0.1:16380` |

- Docker context：`colima-bytedesk`。
- Compose 项目名：`chattermate-local`。
- 数据库卷：`chattermate-local_postgres_data`。
- 配置：`backend/.env`、`frontend/.env`、`deploy/local/.env`。
- 运行文件、日志、构建产物、嵌入模型缓存：`deploy/local/.state/`。
- Widget 与演示配置：[test-environment.json](deploy/local/.state/test-environment.json)。
- 模型配置：DeepSeek / `deepseek-flash`；API Key 由应用加密保存在数据库中。

启动脚本使用上述 context、项目名和卷。不要随意改名、删除数据卷或关闭承载数据库的 Colima 虚拟机。

恢复数据时须同时保留数据库和 `backend/.env` 中的加密配置，否则加密保存的模型配置及消息可能无法读取。不要覆盖密钥、重置管理员，或将私有环境文件提交和对外分享。

## 会话权限检查

会话读取、接管、转交、加入 Socket 房间和发消息，都需要同时检查组织、角色和会话可见性。相应实现位于 [session_to_agent.py](backend/app/api/session_to_agent.py) 和 [widget_chat.py](backend/app/api/widget_chat.py)。

按需执行定向回归：

```bash
cd /Users/a11/1020-1030/01-projects/replypier/backend
ENV_FILE=/dev/null ENVIRONMENT=test NO_ENTERPRISE=1 .venv/bin/python -m pytest tests/api/test_session_to_agent.py -q -o addopts=''
```

## 网站接入与功能边界

服务地址仅监听本机。公网接入需要可访问的服务地址、HTTPS、真实网站域名及相应 CORS / Widget 配置，不能将 `127.0.0.1` 作为公网网站的服务地址。

固定客户长期绑定负责客服的身份映射与自动路由尚未定制。界面主要为英文；邮件邀请、重置密码、Firebase 离线推送和生产容量需在对应任务中配置或验证。