Files

T

2026-07-09 18:14:45 +08:00

12 KiB

Raw Blame History

FakeMessagePlatform 手工测试指南

基于 docs/plans/2026-07-09-brainstorming-fake-message-platform.md 和 docs/qa/2026-07-09-test-plan-round5.md 适用于开发者本地手工验证 FakeMessagePlatform 全链路消息流。

前置条件

PostgreSQL 16 + pgvector 运行在 localhost:5444，数据库 gochat_dev 已初始化
Redis 运行在 localhost:6379
Go 1.24+ 和 Node.js 20+ / pnpm 10+ 已安装
仓库根目录执行过 pnpm install
种子数据已加载（admin@gochat.local / changeme 账号存在）

Step 1：启动三个服务

打开三个终端窗口：

# 终端 1：GoChat 后端 (:3000)
cd /home/yanghao05/Projects/gochat
export GOROOT=/usr/lib/go-1.24 && export PATH=$GOROOT/bin:/home/yanghao05/.local/node-v22.20.0-linux-x64/bin:$PATH
export GOMODCACHE=/home/yanghao05/go/pkg/mod
pnpm dev:backend

# 终端 2：前端 Vite (:3036)
cd /home/yanghao05/Projects/gochat
export PATH="/home/yanghao05/.local/node-v22.20.0-linux-x64/bin:$PATH"
cd frontend && npx vite --port 3036

# 终端 3：FakeMessagePlatform (:9100)
cd /home/yanghao05/Projects/gochat
export PATH="/home/yanghao05/.local/node-v22.20.0-linux-x64/bin:$PATH"
cd channels/fake && npx tsx src/index.ts

等待 10-15 秒，然后验证三个服务健康：

curl http://127.0.0.1:3000/health          # 预期: {"status":"ok",...}
curl -o /dev/null -w '%{http_code}' http://127.0.0.1:3036/  # 预期: 200
curl http://127.0.0.1:9100/health          # 预期: {"status":"ok","service":"fake-message-platform"}

三个都通过才能继续。

Step 2：通过前端 UI 创建 Fake 渠道 Inbox

浏览器打开 http://127.0.0.1:3036/app/login
登录：admin@gochat.local / changeme
左侧栏点击「设置」展开子菜单
点击「收件箱」
点击「添加收件箱」
在渠道选择页面找到「Fake 测试平台」卡片，点击
填写表单：
- 频道名称：Fake Test Inbox
- 标识符 (Identifier)：fake_test_1
- Webhook URL：http://127.0.0.1:9100/receive
- Token：fake_test_token
点击「创建 Fake 频道」
在 agent 分配页面添加 admin 到此 inbox
返回收件箱列表，确认 "Fake Test Inbox" 出现在列表中

如果前端 UI 因浏览器问题不稳定，可以用 API 替代：

curl -X POST http://127.0.0.1:3000/api/v1/accounts/1/inboxes \
  -H "Content-Type: application/json" \
  -H "X-User-ID: 1" -H "X-Account-ID: 1" \
  -d '{
    "name": "Fake Test Inbox",
    "channel": {
      "type": "fake",
      "identifier": "fake_test_1",
      "webhook_url": "http://127.0.0.1:9100/receive",
      "token": "fake_test_token"
    }
  }'

预期返回 JSON 中 channel_type: "fake"，id: 2（或更大）。

Step 3：配置 FakeMessagePlatform 的 GoChat webhook URL

FakeMessagePlatform 需要知道 GoChat 的 webhook 端点和 token：

curl -X POST http://127.0.0.1:9100/api/config \
  -H 'Content-Type: application/json' \
  -d '{"webhook_url":"http://127.0.0.1:3000/webhooks/fake/fake_test_1","token":"fake_test_token"}'

预期返回：{"status":"ok"}

如果启动 FakeMessagePlatform 时已经设置了环境变量 GOCHAT_WEBHOOK_URL 和 GOCHAT_FAKE_TOKEN，则此步可跳过。但默认 URL 用的是 fake_inbox_1，需要改成你实际创建的 identifier。

Step 4：连通性测试

发送一条测试消息，验证 FakeMessagePlatform → GoChat 的链路通畅：

curl -X POST http://127.0.0.1:9100/api/send \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"smoke_test","sender_name":"连通性测试","content":"ping"}'

预期返回：

{"status":"sent","message_id":"fake_msg_...","gochat_status":200}

检查 FakeMessagePlatform 状态：

curl http://127.0.0.1:9100/api/status

预期 total_sent >= 1。

如果 gochat_status 不是 200，说明 webhook 未正确接收。检查：

FakeMessagePlatform 的 webhook_url 是否指向正确的 identifier
GoChat 后端日志是否出现 "Fake webhook received"（注意：后端 worker pool 日志很多，需要过滤查找）

Step 5：入站消息 — 客户发消息 → GoChat 创建会话

模拟客户"测试客户A"发一条消息：

curl -X POST http://127.0.0.1:9100/api/send \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_001","sender_name":"测试客户A","content":"你好，我需要帮助"}'

验证：

前端 Dashboard 应出现新会话（如果前端打开了的话）
通过 API 确认会话和消息已创建：

# 查看最新会话（替换 ID 为实际的会话 ID）
curl -s "http://127.0.0.1:3000/api/v1/accounts/1/conversations/4" \
  -H "X-User-ID: 1" -H "X-Account-ID: 1" | python3 -m json.tool | head -30

或直接查数据库确认：

PGPASSWORD=xiha02 psql -h 127.0.0.1 -p 5444 -U postgres -d gochat_dev -c \
  "SELECT id, content, sender_type, source_id FROM messages WHERE inbox_id=2 ORDER BY id DESC LIMIT 5"

预期：看到 content="你好，我需要帮助"，sender_type="contact"，source_id 以 "fake_msg_" 开头。

Step 6：出站消息 — 客服回复 → FakeMessagePlatform 收到

模拟客服在会话中回复（替换 4 为实际的会话 ID）：

curl -X POST "http://127.0.0.1:3000/api/v1/accounts/1/conversations/4/messages" \
  -H "X-User-ID: 1" -H "X-Account-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"content":"您好，有什么可以帮您？","message_type":"outgoing","private":false}'

验证 FakeMessagePlatform 收到了出站消息：

curl http://127.0.0.1:9100/api/messages?inbox_identifier=fake_test_1

预期返回的 received 数组中包含 content="您好，有什么可以帮您？"，sender.type 为 "agent"。

这一步验证了完整的双向消息流：

客户消息 → FakeMsgPlatform → GoChat webhook → 创建会话/消息
客服回复 → GoChat API → FakeProvider.SendMessage → POST /receive → FakeMsgPlatform 存储

Step 7：多客户并发会话

模拟两个不同客户同时发消息：

# 客户 B
curl -X POST http://127.0.0.1:9100/api/send \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_002","sender_name":"测试客户B","content":"退款咨询"}'

# 客户 C
curl -X POST http://127.0.0.1:9100/api/send \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_003","sender_name":"测试客户C","content":"技术支持"}'

验证创建了独立的会话：

PGPASSWORD=xiha02 psql -h 127.0.0.1 -p 5444 -U postgres -d gochat_dev -c \
  "SELECT c.id, c.status, ct.name FROM conversations c JOIN contacts ct ON c.contact_id=ct.id WHERE c.inbox_id=2 ORDER BY c.id"

预期：每个 sender_id 对应一个独立的会话和联系人。

Step 8：打字状态指示

模拟客户正在打字：

# 开始打字
curl -X POST http://127.0.0.1:9100/api/typing \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_001","typing":true}'

# 停止打字
curl -X POST http://127.0.0.1:9100/api/typing \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_001","typing":false}'

预期：两次请求都返回 {"status":"sent","typing":true/false}。

Step 9：关闭聊天窗口

模拟客户关闭聊天窗口（发送 session.end 事件）：

curl -X POST http://127.0.0.1:9100/api/close \
  -H 'Content-Type: application/json' \
  -d '{"inbox_identifier":"fake_test_1","sender_id":"customer_001"}'

验证 GoChat 创建了 "[session ended]" 系统消息：

PGPASSWORD=xiha02 psql -h 127.0.0.1 -p 5444 -U postgres -d gochat_dev -c \
  "SELECT id, content, source_id FROM messages WHERE content='[session ended]' AND inbox_id=2"

预期：至少一条记录，source_id 以 "fake_close_" 开头。

Step 10：消息附件

发送带图片附件的消息：

curl -X POST http://127.0.0.1:9100/api/send \
  -H 'Content-Type: application/json' \
  -d '{
    "inbox_identifier":"fake_test_1",
    "sender_id":"customer_001",
    "sender_name":"测试客户A",
    "content":"请看这张截图",
    "content_type":"image",
    "attachments":[{
      "url":"http://example.com/screenshot.png",
      "content_type":"image/png",
      "filename":"screenshot.png",
      "file_size":102400
    }]
  }'

验证消息以 image 类型创建：

PGPASSWORD=xiha02 psql -h 127.0.0.1 -p 5444 -U postgres -d gochat_dev -c \
  "SELECT id, content_type, content_attributes FROM messages WHERE inbox_id=2 AND content_type='image' ORDER BY id DESC LIMIT 3"

预期：content_type 为 "image"，content_attributes 中包含附件 URL。

Step 11：客服上下线状态（FakeMessagePlatform 侧记录）

模拟客服上线和下线（这些是 FakeMessagePlatform 内存中记录的状态，供测试脚本查询）：

# 客服上线
curl -X POST http://127.0.0.1:9100/api/agent/online \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"1","agent_name":"Admin"}'

# 查看状态
curl http://127.0.0.1:9100/api/status
# 预期：online_agents 中包含 agent_id="1"

# 客服下线
curl -X POST http://127.0.0.1:9100/api/agent/offline \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"1"}'

# 再次查看状态
curl http://127.0.0.1:9100/api/status
# 预期：online_agents 为空

Step 12：重置状态（可选）

在每次测试前重置 FakeMessagePlatform 的内存状态：

curl -X POST http://127.0.0.1:9100/api/reset

预期返回 {"status":"ok"}，之后 /api/status 显示所有计数为 0。

验证清单

三个服务全部启动且健康检查通过
Fake Inbox 成功创建（channel_type=fake）
FakeMessagePlatform webhook URL 已正确配置
连通性测试：发消息 → GoChat 返回 200
入站消息：客户发消息 → 创建 Contact + Conversation + Message
出站消息：客服回复 → FakeMessagePlatform /receive 收到
多客户并发：每个客户独立会话
打字状态：typing true/false 事件成功发送
会话关闭："[session ended]" 消息创建
消息附件：image 类型消息正确创建
客服上下线：FakeMessagePlatform 状态正确记录

常见问题排查

Q: FakeMessagePlatform 发消息返回 gochat_status 非 200

检查 FakeMessagePlatform 的 webhook URL：

curl http://127.0.0.1:9100/api/status

确认 webhook_url 指向 http://127.0.0.1:3000/webhooks/fake/<你的identifier>。

Q: GoChat webhook 返回 200 但没有创建会话

FakeWebhookHandler 在出错时也返回 200（遵循 webhook 惯例）。检查后端日志：

# 在后端终端中查找 "Fake webhook" 相关日志
# 注意 worker pool 的 "record not found" 日志是正常噪音，不影响消息流

或直接查数据库确认消息是否已写入。

Q: 客服回复没有到达 FakeMessagePlatform

确认 Fake Inbox 的 channel_config 中 webhook_url 指向 FakeMessagePlatform 的 /receive：

PGPASSWORD=xiha02 psql -h 127.0.0.1 -p 5444 -U postgres -d gochat_dev -c \
  "SELECT channel_config FROM inboxes WHERE channel_type='fake'"

预期 webhook_url 为 http://127.0.0.1:9100/receive。

Q: Meilisearch 连接失败

后端日志中可能出现 meilisearch index document: ... connection refused。这是因为 Meilisearch 未运行，搜索索引后台 job 会失败但不影响消息收发。如需完整搜索功能：

# 可选：启动 Meilisearch
cd /home/yanghao05/Projects/gochat/deploy/quickstart && docker compose up -d meilisearch

停止服务

测试完成后，在各终端按 Ctrl+C 停止服务。或批量停止：

kill $(lsof -t -i:3000 -i:3036 -i:9100) 2>/dev/null

12 KiB Raw Blame History Unescape Escape