渠道配置页怎么做才不别扭:多平台动态表单、状态回显与一键预填
前五篇都在讲 BizBuddy 的后端和运维,这篇讲界面上容易被忽略、但很影响口碑的一块:渠道接入的管理页。
一张表单装四个平台,本身就不合理
渠道管理页要同时应付钉钉、企业微信、飞书、GitHub,它们的字段差异还不小:
| 平台 | 要填什么 |
|---|---|
| 钉钉 | AppKey、AppSecret、RobotCode(没有回调地址) |
| 企业微信 | CorpID、Secret、AgentId、Token、EncodingAESKey、回调地址 |
| 飞书 | App ID、App Secret、Encrypt Key、Verification Token、回调地址,而且形态二选一 |
| GitHub | Webhook Secret、Personal Token、Bot 登录名、回调地址 |
要是一张表把所有字段全铺出来,用户面前就会堆着一大堆跟他所选平台无关的输入框。这是最典型的坏体验。
字段跟着平台变,别全铺出来
同一张表单,随"平台类型"切换字段集合。能复用的列尽量复用——比如"应用标识"这一栏,钉钉填 AppKey、飞书填 App ID,共用同一列,表结构就不用膨胀。
三条规则:
不显示就是不存在。 钉钉页面上根本不出现"回调地址"和"接入形态"(它恒为长连接),而不是显示了但标灰。标灰的字段只会让人困惑"是不是我该填点什么"。
必填项跟着平台换。 切平台的时候校验规则同步换:钉钉不校验 Encrypt Key,企微必须填 EncodingAESKey。
多形态平台的字段要做联动。 这条单独说。
把"选型知识"放进界面
飞书支持 Webhook 和长连接二选一,这个选择会连带影响几件事:
| 选了长连接以后 | 界面要做什么 |
|---|---|
| Encrypt Key / Verification Token | 隐藏。长连接建连即鉴权、报文明文,用不上 |
| 回调地址 | 隐藏。应用主动外连,不需要 |
| 校验规则 | 不再强制上面两项 |
| 提示文案 | 写清楚"无需公网 IP 与回调地址;后台事件订阅须选『长连接』" |
这段提示文案的价值比看起来大。它同时回答了"为什么不用填回调地址"和"后台该怎么配",用户不用去翻文档。
同理,长连接形态下"API 基址"的说明也要换口径,从"OpenAPI 基址"改成"长连接 domain,留空用官方默认地址"。不换的话,总有人以为填个内网地址就行。
让"连没连上"看得见
长连接是应用主动连出去的,它连没连上,页面上原本看不出来——一直要到发现机器人不回话才知道。所以连接状态必须回显到列表:
| 状态 | 意思 |
|---|---|
| 未启动 | 渠道停用,或者还没装配 |
| 运行中 | 连接已建立、握手成功 |
| 启动失败 | 凭据错、出网受限、后台没选长连接模式……要带原因 |
一条原则:失败要给原因,别只给一个红叉。 我们的做法是把启动异常的信息登记下来,列表上点开就能看。
另外列的显示也得跟着形态走:回调地址列和连接状态列,只对长连接形态(含恒长连接的钉钉)显示,其他平台不 display,免得列表里多出一列空白。
把运维的脏活做成产品功能
最典型的是"外部身份映射"这件事。管理员最头疼的不是怎么填,是该填什么——外部标识既不是手机号也不是昵称,只能去翻后端日志。
后来我们把它做成了渠道列表行内的一个图标:
渠道列表 · 操作列
[修改] [按手机号查标识] [删除]
↓
弹窗:输手机号 → 查询
↓
命中:显示标识 + 复制 + 「预填到外部身份映射」三个地方是刻意设计的。
一键预填,但平台账号还是要管理员自己选。 查出标识之后,直接切到"外部身份映射"页签并预填渠道和标识——但"绑到哪个平台账号"必须人工决定。那是权限决策,不能被自动化。
只对支持的平台显示。 企业微信(需要通讯录同步的独立 secret)和 GitHub(没有手机号概念)不支持这个查询,界面上直接不给图标。能力边界如实暴露,好过"点了报错"。
敏感数据处理。 查询接口不记操作日志(手机号属于个人敏感信息),日志里手机号脱敏,写成 138****0000。
顺带说个小事:列宽
加了操作图标之后,操作列放不下了。我们把列宽从 130 调到 170。这种事不改,界面上会出现按钮换行、图标被挤掉,用户看到的第一反应就是"你们这页面做得挺糙"。
类似的还有:新增列之后要看看列表会不会出横向滚动条,表单加字段之后要看看小屏下会不会挤成一团。这些细节就是"做完功能"和"做完体验"之间的差距。
最后:界面是把架构翻译给使用者的地方
对着看一下:
| 后端的概念 | 界面上应该长成 |
|---|---|
| 接入形态(webhook / ws) | 一个单选,联动隐藏字段,外加一句明确的提示 |
| 长连接生命周期 | 一个"连接状态"列,失败要带原因 |
| 身份映射的安全规则 | 一句清楚的拒绝提示,并指明去哪儿绑 |
| 平台能力边界 | 按钮不出现,而不是出现但点不了 |
| 敏感信息 | 不回显明文,日志脱敏 |
后端负责把"能不能"做出来,界面负责把"该不该、怎么做"说清楚。渠道接入这类功能,配置项多、平台差异大、出错原因又隐蔽,界面做得怎么样,直接决定交付时你会被问多少问题。
系列目录
- 篇一 渠道网关设计:为什么需要它,两种形态怎么选
- 篇二 钉钉 Stream + 飞书长连接:实现、官方约束和坑
- 篇三 从选型到上线:建表、后台配置、检查表、报错对照
- 篇四 四道关:幂等、限流防自环、身份映射、会话映射
- 篇五 排障实录:钉钉与飞书从环境、权限到图片消息的完整记录
- 篇六 配置页设计:把架构翻译成界面
关于 BizBuddy
BizBuddy 是一个全量开源的企业级智能体平台(MIT License):开源中后台底座(Spring Boot 4.1.1 / JDK 21)做底座,AgentScope Java Harness 做智能体内核,纯 Java 全栈、不含 Python,权限、审计、配额、多渠道接入等能力全部随仓库开源。渠道接入的核心类在 core/channel 包。
欢迎 Star、Issue 与共建。