可自部署的多平台客服系统，将 TikTok Shop 店铺／达人／TAP 联盟聊天和 WhatsApp 客户消息集中到一个团队共享的统一收件箱，支持多账号管理、会话分配和员工权限控制。
A self-hosted shared inbox for WhatsApp and TikTok Shop / TAP affiliate chat. Manage customer support conversations, agent assignments, role-based access, and text/image messages in one team inbox.
前端使用 React / Next.js，后端使用 FastAPI / SQLite；TikTok 使用项目内的协议模块，WhatsApp 使用 whatsapp-web.js。
- 主管查看全部会话、分配负责人、管理员工与平台连接。
- 员工仅能访问分配给自己的会话，包括历史、图片和发送接口。
- 文字、图片、内部备注、客户标签、会话搜索与完成状态。
- 消息落库后发送；重复请求去重。结果不明确时显示“结果待核对”，不会自动重发。
- WhatsApp 回执显示已发送、已送达、已读。工作台内部已读不会更改平台已读。
需要 Python 3.12+、Node.js 22.13+。在项目目录执行：
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
npm install
npm run build:server
.venv\Scripts\python.exe run.py --demo打开 http://localhost:5173/，可直接选择主管、小陈或小周体验。演示消息保存在 backend/state-demo，不会向平台发送。开发时使用 run.py --demo --dev。
正式模式去掉 --demo，数据保存在 backend/state。首次启动生成 admin@local 及随机密码，见该目录中的 bootstrap.txt。也可在首次启动前设置 INBOX_ADMIN_PASSWORD。查看密码后妥善保管或移除该文件；重复启动不会重置账号。
在项目根目录安装接入服务的依赖并启动。每个账号使用独立的登录目录。
cd bridges
npm ci
cd ..
$env:INBOX_BRIDGE_TOKEN = '替换为至少24字符的随机密钥'
node bridges/whatsapp.mjs在正式工作台的「平台连接」添加 WhatsApp，地址填写 http://127.0.0.1:8093，密钥填写上述值。点击「检查并同步」，使用对应 WhatsApp 扫描二维码，登录后再点击一次。
登录时自动导入最近 100 个会话各 50 条消息，之后持续接收新消息。历史范围取决于 WhatsApp Web 可读取的数据，重新连接时会再次导入上述范围的历史消息。图片支持 JPG / PNG / WebP，其他类型提示在平台查看。
一个 WhatsApp 账号运行一个接入进程。多个账号分别设置 WHATSAPP_STATE_DIR、WHATSAPP_CLIENT_ID、WHATSAPP_BRIDGE_PORT，并在工作台添加对应连接。服务器需要能持续运行浏览器。
创建 private/ 目录，将 bridges/tiktok.session.example 复制为 private/shop.session.json，填入账号有效的 IM token、ID 和 cookies。private/ 已加入忽略规则。shop_im_id 为店铺 IM 用户 ID，shop_id 为店铺 ID。TAP 账号另需 store_type=3、device_id、partner_id（合作伙伴 ID）。global 店铺设置 store_type_name=global。
$env:INBOX_BRIDGE_TOKEN = '替换为至少24字符的随机密钥'
.venv\Scripts\python.exe -m bridges.tiktok --session private/shop.session.json在工作台添加 TikTok 连接，默认地址 http://127.0.0.1:8094。消息协议、protobuf 定义及图片签名实现位于 bridges/protocol/。
支持已有会话的文字与图片收发；TikTok 图片和文字需要分开发送。平台协议变化或登录失效时需要更新适配器／会话文件并重启该接入进程。TAP 昵称缺失时显示会话编号。
使用 npm run build:server 生成 Node 服务，再以正式模式运行 run.py。Linux 中将 Python 路径改为 .venv/bin/python。后端保持一个进程；不要增加 Uvicorn worker 数量。
前后端及接入服务默认只监听本机。由 Nginx 提供 HTTPS，示例见 deploy/nginx.conf.example；设置 INBOX_SECURE_COOKIE=1。用 systemd 或其他进程管理器守护主服务与各接入进程。不要将演示模式对外开放。
INBOX_DATA_DIR 可指定数据目录。备份时停止服务，保存整个目录（数据库、secret.key、附件），同时备份接入进程的 bridges/state-*。这些目录、真实会话配置及 .env 均不可公开。
接入服务跨机器部署时，用 INBOX_BRIDGE_HOSTS 明确允许的主机，并自行配置专用网络／HTTPS；不建议直接暴露浏览器接入端口。
.venv\Scripts\python.exe -m pytest -q tests
npm run build:server