天蓬客服 · 系统功能手册

1. 系统概述

天蓬客服是一套面向企业的「智能在线客服 + 多租户工单」SaaS 系统。它把网站、微信、App、H5、小红书、闲鱼等多个渠道的客户咨询，统一汇聚到客服工作台，由坐席实时接待，并支持知识库自动应答、快捷回复、会话转接、工单流转与多租户账号隔离。

产品定位

• 企业对外：一个轻量、科技蓝白风格的客服入口，客户无需注册即可咨询。
• 坐席对内：一个实时工作台，集中处理所有渠道的会话、访客画像与工单。
• 管理员：一个后台，管理账号、坐席、套餐、支付、渠道与系统配置。

三大核心角色

2. 技术架构

系统采用「反代 → 应用容器 → 数据库」三层架构，单进程 Node 服务同时承载 API、WebSocket 与前端静态资源：

技术栈

路由模式（history）

前端使用 createWebHistory()，URL 无 #。直接访问 /admin、/agent、/embed 或刷新子路由时，由后端 app.get('*') 回退到 index.html 交由前端接管；其中登录后控制台页回退时注入 noindex，避免被搜索引擎收录为重复首页。

3. 核心功能

3.1 在线客服工作台（/agent）

坐席的统一工作界面：

• 实时会话：WebSocket 推送新消息、会话状态变更，无需刷新。
• 访客画像：姓名、来源渠道、标签、备注、历史会话。
• 会话操作：转接其他坐席、打标签、关闭会话。
• 快捷回复：常用话术一键发送。
• 知识库（机器人）：命中关键词时自动应答；__TRANSFER__ 指令触发转人工。
• 多渠道标识：每条会话按渠道显示品牌色（微信绿、小红书红、闲鱼橙等）。

3.2 多渠道接入

系统在 seed.js 预置渠道，管理员可在后台启用 / 禁用并填写配置：

接入某渠道 = 在后台填入对应开放平台凭证（如微信 AppID / AppSecret、小红书 Client Key、淘宝开放平台 AppKey 等），保存后该渠道咨询自动汇聚到工作台。

3.3 微信扫码登录 + 手机号绑定闸门

登录链路（server/routes/wechat.js）：

1. 客户扫码 → 微信 OAuth2 授权 → 回调 GET /api/wechat/callback。
2. 服务端按 openid 查找坐席；不存在则自动注册新账号 + 新坐席（扫码即注册）。
3. 手机号闸门：若该坐席未绑定手机号，不下发完整会话，而是下发 bindToken（HMAC-SHA256 签名，10 分钟有效）。
4. 前端弹出手机号绑定弹窗 → 调 /api/sms/send 发验证码 → /api/sms/verify 校验并绑定 → 换取完整会话令牌（写入 httpOnly Cookie）。

3.4 短信验证码（联麓信息）

模块：server/sms.js + server/routes/sms.js。

• 真实通道：配置联麓 MchId / AppId / key / SignName / TemplateId 后，调用模板短信 API 真实下发。
• 开发态（默认）：未配置真实凭证时，验证码不真实发送，仅在发送记录中回显（channel='dev'），便于联调。
• 限流：同手机号 60 秒冷却、10 分钟内最多 5 次、验证码有效期 10 分钟、最多试 5 次。
• 管理后台：/api/sms 分页展示发送记录（时间 / 手机号 / 场景 / 通道 / 状态 / 明细）；/api/sms/config 脱敏展示与保存联麓配置。

3.5 管理后台（/admin）

3.6 支付与套餐

• 套餐档位存于 meta.plans_config，动态读取。
• 下单：POST /api/workbench/orders（planKey + channel）。
• 支付：支付宝非沙箱走 verifyAlipay 验签；微信支付沙箱自动切换。
• 升级：幂等 applyPaid，避免重复计费。

3.7 SEO 与搜索引擎收录

控制台页（/admin、/agent、/embed）回退时注入 noindex,nofollow，不被收录为重复首页。

4. 数据模型（核心表）

5. 部署与运维

5.1 环境与依赖

• 服务器：1Panel + Docker + OpenResty 反代
• 域名：im.brt.sn.cn（HTTPS，Let's Encrypt）
• 数据库：1Panel MySQL 8.4，库名 tianpeng，监听 0.0.0.0:3306
• 应用容器：deploy-app-1（3000:3000），经 host.docker.internal 连宿主机 3306

5.2 一键部署

cd deploy
cp .env.prod .env        # 编辑 DB_PASSWORD / ADMIN_PASSWORD
bash up.sh               # 等价于 docker compose up -d --build

部署完成后：

• 健康检查：curl http://127.0.0.1:3000/api/health → {"ok":true,...}
• 管理后台：https://im.brt.sn.cn/admin
• 工作台：https://im.brt.sn.cn/agent

5.3 关键运维命令

docker compose ps                       # 查看容器状态
docker compose logs -f app              # 跟踪应用日志
docker compose restart app              # 重启应用
docker compose down                     # 停止
bash deploy/push-baidu.sh               # 手动触发百度推送

5.4 配置项（环境变量）

安全提示：默认弱口令 tianpeng888 已在 auth.js 中禁用（任何尝试都会被拒绝）。生产环境必须在 deploy/.env 中将 ADMIN_PASSWORD 配置为强密码或 bcrypt 哈希，否则后台无法登录。

6. 二次开发指引

6.1 目录结构

server/                后端
  index.js             Express 入口（路由挂载、静态托管、history 回退、sitemap）
  auth.js              会话/登录/管理员鉴权/手机号绑定令牌
  sms.js               联麓短信服务
  db.js                数据库访问层（含 ensureSchema 建表与渠道迁移）
  seed.js              示例数据（账号/坐席/会话/工单/知识库/渠道）
  views.js             会话视图组装
  routes/              auth / wechat / sms / channels / conversations / payments ...
web/
  src/
    router.js          Vue Router（history 模式）
    constants.js       渠道标签/品牌色/套餐样式 等共享常量（单一数据源）
    api.js             前端 API 封装
    components/         ChatPanel / VisitorPanel / ConversationList / 管理后台组件 ...
    views/             Landing / AgentConsole / AdminConsole / Embed
  public/
    robots.txt         SEO 爬虫规则
    og-image.jpg       品牌分享图
    pages/             静态内容页 + seo.css
deploy/
  Dockerfile / docker-compose.yml / .env.prod / up.sh / push-baidu.sh / setup-on-server.sh / README.md
docs/                  方案与手册

6.2 新增渠道步骤

1. server/seed.js 的 channels 数组追加一项（key / name / category / color / icon / enabled / desc）。
2. server/db.js ensureMigrations() 追加一条幂等 INSERT ... WHERE NOT EXISTS（存量库自动补齐）。
3. web/src/constants.js 的 CHANNEL_LABELS 补充中文标签；若需新品牌色，在 CHANNEL_COLORS 补充。
4. web/src/components/Icon.vue 补充渠道图标（如尚缺）。
5. web/src/views/ChannelView.vue 补充该渠道的接入引导（平台、字段、步骤）。

6.3 代码规范要点

• 共享常量集中：渠道标签、品牌色、套餐样式统一在 web/src/constants.js，禁止在组件内散落重复定义。
• 敏感信息脱敏：微信 AppSecret、联麓 key 等仅在服务端保存，对外接口一律走 maskXxx() 脱敏。
• 会话令牌安全：坐席 / 管理员令牌写入 httpOnly + SameSite=Strict Cookie（HTTPS 下加 Secure），降低 XSS 冒用。
• 多租户隔离：统计 / 广播 / 升级一律按 accountId 过滤，禁止全量 listAgents。
• 幂等迁移：db.ensureMigrations() 的渠道 / 字段补齐均用 WHERE NOT EXISTS 或「仅当为空时写入」，支持重复启动。

7. 常见问题（FAQ）

本手册随系统迭代更新。如有歧义，以线上 im.brt.sn.cn 实际行为与源码注释为准。