117 lines
5.3 KiB
HTML
117 lines
5.3 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<title>链接卡片私信 — 本地联调指南</title>
|
||
<style>
|
||
:root { color-scheme: light dark; }
|
||
body {
|
||
font-family: "Segoe UI", "Microsoft YaHei", sans-serif;
|
||
line-height: 1.65;
|
||
max-width: 820px;
|
||
margin: 0 auto;
|
||
padding: 24px 20px 48px;
|
||
color: #1e293b;
|
||
background: #f8fafc;
|
||
}
|
||
h1 { font-size: 1.5rem; margin-bottom: 0.25rem; }
|
||
h2 { font-size: 1.1rem; margin-top: 2rem; border-bottom: 1px solid #cbd5e1; padding-bottom: 0.35rem; }
|
||
.meta { color: #64748b; font-size: 0.9rem; margin-bottom: 1.5rem; }
|
||
ol, ul { padding-left: 1.25rem; }
|
||
li { margin: 0.45rem 0; }
|
||
code, pre {
|
||
font-family: Consolas, "Courier New", monospace;
|
||
font-size: 0.88rem;
|
||
}
|
||
pre {
|
||
background: #0f172a;
|
||
color: #e2e8f0;
|
||
padding: 14px 16px;
|
||
border-radius: 8px;
|
||
overflow-x: auto;
|
||
}
|
||
.box {
|
||
background: #fff;
|
||
border: 1px solid #e2e8f0;
|
||
border-radius: 10px;
|
||
padding: 14px 16px;
|
||
margin: 12px 0;
|
||
}
|
||
.warn { border-left: 4px solid #f59e0b; background: #fffbeb; }
|
||
.ok { border-left: 4px solid #10b981; background: #ecfdf5; }
|
||
table { width: 100%; border-collapse: collapse; font-size: 0.9rem; margin: 12px 0; }
|
||
th, td { border: 1px solid #e2e8f0; padding: 8px 10px; text-align: left; }
|
||
th { background: #f1f5f9; }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<h1>链接卡片私信 — 本地联调指南</h1>
|
||
<p class="meta">普通私信 Web IM 链接卡片（message_type=70），任意账号均可收发；与企业号 OpenAPI 模板卡无关。</p>
|
||
|
||
<h2>一、环境准备</h2>
|
||
<ol>
|
||
<li>启动后端与前端，确保能登录管理后台。</li>
|
||
<li>设置公网基础 URL（卡片落地页与封面必须外网可访问）：
|
||
<pre>KEFU_PUBLIC_BASE_URL=https://你的域名</pre>
|
||
本地调试可用内网穿透（ngrok / frp 等），不要用 localhost 作为卡片跳转地址。
|
||
</li>
|
||
<li>抖音账号完成 IM 凭证采集（Cookie + web_protect + keys），状态为「可 IM 直连」。</li>
|
||
</ol>
|
||
|
||
<h2>二、创建示例规则（约 3 分钟）</h2>
|
||
<ol>
|
||
<li>进入 <strong>自动回复规则</strong> → 新建规则。</li>
|
||
<li>匹配方式：<strong>包含</strong>；关键字：<code>深度研究</code>（或任意测试词）。</li>
|
||
<li>回复类型选 <strong>卡片</strong> → 点击 <strong>填入示例</strong>。</li>
|
||
<li>上传封面图（JPG/PNG，系统会转为 256×256）。</li>
|
||
<li>将「跳转链接」改为你的真实业务 URL。</li>
|
||
<li>保存规则（会自动调用 <code>/api/link-cards</code> 生成落地页）。</li>
|
||
<li>确认表单中出现 <strong>落地页链接</strong>（形如 <code>https://域名/p/xxxx</code>）。</li>
|
||
</ol>
|
||
|
||
<div class="box ok">
|
||
保存成功后，规则内 reply_content 类似：
|
||
<pre>{"type":"card","title":"深度研究入口","desc":"…","url":"https://域名/p/xxx","target_url":"https://业务页","cover_url":"…","image_path":"/api/media/link-cards/…"}</pre>
|
||
</div>
|
||
|
||
<h2>三、联调发送</h2>
|
||
<ol>
|
||
<li>在 <strong>账号管理</strong> 对该抖音号点击 <strong>启动托管</strong>。</li>
|
||
<li>用<strong>另一个抖音号</strong>给该账号发私信：<code>深度研究</code>（或你设的关键字）。</li>
|
||
<li>预期：对方收到一条<strong>带封面、标题、描述的链接卡片</strong>（不是纯文本+链接）。</li>
|
||
<li>点击卡片 → 打开落地页 → 自动跳转到 target_url。</li>
|
||
</ol>
|
||
|
||
<h2>四、日志排查</h2>
|
||
<table>
|
||
<tr><th>位置</th><th>看什么</th></tr>
|
||
<tr><td>消息日志</td><td>reply 列应含 <code>[链接卡片] 标题</code>；status 为 sent</td></tr>
|
||
<tr><td>系统诊断日志</td><td>搜索「卡片」「8004」「封面上传」</td></tr>
|
||
<tr><td>后端控制台</td><td><code>Sending to target:</code> 与 <code>Link card send</code></td></tr>
|
||
</table>
|
||
|
||
<h2>五、常见错误</h2>
|
||
<table>
|
||
<tr><th>现象</th><th>处理</th></tr>
|
||
<tr><td>卡片封面上传失败</td><td>重新登录采集 IM 凭证；确认 session 有效</td></tr>
|
||
<tr><td>缺少卡片跳转链接</td><td>配置 KEFU_PUBLIC_BASE_URL 后重新保存规则</td></tr>
|
||
<tr><td>status_code 8004 / raw_check_code 1</td><td>封面 CDN 未就绪；等待 2～5 秒后重试（系统会自动重试一次）</td></tr>
|
||
<tr><td>收到的是文本不是卡片</td><td>检查 reply_content 中 <code>"type":"card"</code> 是否存在</td></tr>
|
||
<tr><td>落地页 404</td><td>确认后端 <code>/p/{slug}</code> 路由可访问且 slug 已入库</td></tr>
|
||
</table>
|
||
|
||
<div class="box warn">
|
||
<strong>注意：</strong>两个均为本系统托管的账号互发消息时，会自动跳过回复以防风控循环。联调请使用外部测试号。
|
||
</div>
|
||
|
||
<h2>六、手动验证 API（可选）</h2>
|
||
<p>登录后台后，在浏览器开发者工具 Network 中确认：</p>
|
||
<ul>
|
||
<li><code>POST /api/link-cards/upload-image</code> — 封面上传</li>
|
||
<li><code>POST /api/link-cards</code> — 创建落地页，返回 page_url</li>
|
||
<li><code>GET /p/{slug}</code> — 落地页可打开并跳转</li>
|
||
</ul>
|
||
</body>
|
||
</html>
|