chore(deploy): 本地部署脚本、容器配置与运行说明

PostgreSQL/pgvector 与 Redis 独立容器，后端、worker、前端可一键启停；不覆盖既有密钥。

LOCAL_DEPLOY.md

@@ -0,0 +1,92 @@
+# 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 离线推送和生产容量需在对应任务中配置或验证。