Files
kefu/GROUP_IDENTITY.md
T
2026-11-16 09:28:25 +08:00

11 KiB

集团账号登录企微客服

本接入针对 admin-web + wechat_rpa/admin_api.py 企微客服管理端,与 im/backend 社交平台、桌面 terminal=7 认证分别独立。

已有有效 zyt 后台账号可从集团工作台一键进入客服。首次默认分配“集团基础用户”角色,该角色初始化时没有业务权限;客服管理员使用原本地账号在“系统管理 → 用户管理”分配角色,在“角色权限”勾选具体能力。再次集团登录保留管理员分配的角色和本地停用状态,不按同名账号合并,不继承医院 root。密码仍由 zyt 验证,绑定账号不能使用或设置客服本地密码。

网页登录使用同一个账号密码表单:输入zyt账号密码或客服本地账号密码,点击“登录”直接进入客服,不跳转集团后台。本地凭据验证成功时沿用本地账号和角色;否则通过服务器配置的ZYT API实时验密。无医院菜单权限的有效zyt账号也可使用。

直接登录仅需客服API配置ZYT_GROUP_API_URL。中央端点POST /adminapi/group/kefu/login调用原项目无会话验密POST /adminapi/identity.session/verify,不创建或注销zyt网页会话,不依赖集团前端运行。密码仅用于本次验证,不在客服保存为本地密码、放入URL或返回给浏览器;密码仍由zyt管理。

同名账号不会合并:有效本地凭据优先;只有zyt凭据匹配时,按提供方和稳定GID创建/查找独立绑定账号,首次默认分配“集团基础用户”,其初始授权为空,实际权限使用管理员保存的当前配置。原客服管理员在用户管理分配本地业务角色,再次直接登录保持该角色与本地停用状态。不能在客服重置绑定账号的zyt密码。

管理端标准API前缀为/api/v2,构建产物应设置VITE_GLOB_API_URL=/api/v2,可以由8766服务直接托管;开发代理及本机5666预览同时兼容旧/api与标准前缀。如果通过其他地址访问,集团登录会先进入已配置的客服回调地址,再发起登录,避免不同域或端口丢失登录事务。回调仍严格固定,不接受任意跳转。

本地管理员在用户列表“来源/原账号”找到集团用户,选择业务角色即可;“集团基础用户”初始化时无业务权限,持有 role:write 的管理员可编辑其名称、菜单和操作权限;角色编码保持不变,内置角色不能删除。保存对当前和后续使用此角色的账号统一生效,服务重启保留配置,包括清空后的授权。后端每请求使用新权限,已登录前端在页面可见时每3秒同步菜单和按钮,切回窗口立即同步。仅有角色读取权限的角色管理员也能进入角色页;分配用户角色仍需用户管理权限,不因登录成功自动授予管理能力。

集团管理员可查看这里分配的角色和有效权限、同步动态新增的权限目录,并直接编辑已绑定用户的客服授权。客服API配置ZYT_GROUP_METADATA_KEY_FILE,集团配置IAM_KEFU_METADATA_API_URL及IAM_KEFU_METADATA_KEY_FILE,两个文件内容为同一份32字节随机密钥的64位hex表示。文件须放在非公开目录、限制服务用户读取,勿写入浏览器、URL或仓库。Docker需要额外挂载该文件,配置值是容器内只读路径;只有api服务需要它。该密钥同时用于专用授权管理协议,必须仅提供给受信任的集团服务。

元数据接口POST /api/v2/group/access-snapshot只接受专用HMAC请求并签名响应,不接受普通客服用户token代替机器认证,也不能登录或改授权。按稳定GID关联,查询不会创建账号或认领同名本地账号。集团用户页“客服授权”展示当前角色、启停和有效权限,打开期间每30秒刷新;集团菜单管理的客服公司目录自动拉取,也可点击“同步客服权限”。自定义权限增改删会反映到集团管理目录,删除采用软停用并保留既有引用,恢复沿用原节点。不会把客服权限并入集团/医院授权,也不会自动给集团角色加权限。

客服 API 配置以下公开地址,缺少任一项时关闭集团登录:

ZYT_GROUP_BASE_URL=https://<集团前端域名>
ZYT_GROUP_API_URL=https://<集团API域名>/adminapi
KEFU_PUBLIC_BASE_URL=https://<客服前端域名>

同时在集团配置 IAM_KEFU_BASE_URL=<已登记客服地址>、IAM_KEFU_COMPANY_CODE=<实际客服公司编码>以启用该客户端。上面的前端/回调配置仅为保留集团工作台旧单点入口所需;客服主登录框直接验密只依赖API地址。旧回调仍严格为/auth/group-login。默认要求HTTPS,回环本地开发可用HTTP。Docker compose已透传配置,不能把密钥或密码放进这些地址。

保留现有公网HTTP客服地址时,两端必须显式登记同一来源,端口也是来源的一部分。客服API示例:

ZYT_GROUP_BASE_URL=https://x.zhenyangtang.com.cn
ZYT_GROUP_API_URL=https://x.zhenyangtang.com.cn/adminapi
KEFU_PUBLIC_BASE_URL=http://im.zhenyangtang.cn:8369
ZYT_GROUP_ALLOWED_HTTP_ORIGINS=http://im.zhenyangtang.cn:8369

集团端同步设置IAM_KEFU_BASE_URL=http://im.zhenyangtang.cn:8369及IAM_KEFU_ALLOWED_HTTP_ORIGINS=http://im.zhenyangtang.cn:8369。登记项仅接受完整HTTP来源,可逗号分隔;不接受通配符、路径、用户名、密码、查询或片段。更换主机或有效端口须重新登记,回调固定为http://im.zhenyangtang.cn:8369/auth/group-login。该例外仅允许已登记客服前端及回调;集团前端和集团API仍要求HTTPS(回环开发除外)。客服公开配置仅返回由登记结果计算的http_callback_allowed布尔值。HTTP浏览器使用安全随机数及现有hash-wasm计算PKCE S256,不降级为明文挑战。

集团菜单目录仅控制集团入口显示,客服业务菜单和按钮由客服本地角色决定。集团账号首次登录默认基础角色;管理员可编辑基础角色权限,内置角色不可删除。客服 SSO 会话最长 8 小时;本地停用和权限调整每请求生效。当前无跨系统全局注销,集团改密/退出会阻止新的 SSO,但不会声称立即撤销所有已签发客服会话。

集团管理员也可在集团“用户管理 → 客服授权 → 编辑客服授权”中直接分配客服角色,或勾选仅该用户的权限。独立权限通过专属客服角色保存,不修改共享角色或其他用户;实际授权仍存于客服。保存提交后,既有客服会话下一次请求即按新权限执行。2026-11-04起前台页面每3秒同步菜单、按钮和路由,切回窗口或恢复可见立即同步;当前页面失权后返回账号页,不注销登录,仍有权页面及其草稿保留。前端升级首次加载新版本需要刷新一次,后续授权变化无需整页刷新。未绑定用户须先用ZYT账号登录客服,不能按同名本地账号认领。

此管理使用独立的/api/v2/group/access-options、/api/v2/group/access-update端点,沿用服务密钥但绑定实际端点签名,持久化防重放并校验旧版本。普通客服token不能调用。集团仅允许显式集团管理员,并在每次操作核对来源用户/GID/应用归属;两端审计。原access-snapshot仍只读。联调协议见集团integration/kefu-group-authorization-contract.md。

新增回归:wechat_rpa/test_group_sso.py 与 admin-web/apps/web-antd/tests/group-sso.test.mjs。后端测试需要在合成配置及隔离临时目录运行,勿初始化或重置真实账号库。集团侧跨项目联合测试见 C:/zyt/identity-admin/tests/kefu-joint-flow.test.mjs。

知识中心的数据权限

在“角色权限 → 知识中心 → 知识加工与检索”勾选“数据权限:仅本人账号的知识”(knowledge:scope:own),按登录 ZYT 账号对应的可信客户端 tenant 收窄范围,包含管理员或其他账号代为清洗的知识。未勾选沿用原有范围;该项不单独授予查看、编辑或审核动作,管理员保留全部功能和全量数据范围。

服务端登记 ZYT_KNOWLEDGE_ACCOUNT_BRIDGE,格式为 {"group_api_url":"https://group.example.invalid/adminapi","desktop_api_url":"https://zyt.example.invalid","namespace":"admin"}。部署者必须先核实两端确为同一原 ZYT 实例。当前 Group API、桌面登录实际 API、provider、gid、source_admin_id 和 active 客户端须一致;仅按 admin:N 命名空间匹配,不按姓名、账号文本或裸数字匹配。来源缺失或不符、零匹配、客户端停用均为空范围。桌面持久化登录地址优先,配置为空才使用 ZYT_API_BASE_URL。

知识、数量、详情、审核、管理检索、导出和任务控制按当前账号范围校验,不再要求记录由当前操作者发起,也不回填历史。原有客户端范围再取交集,零显式分配沿用原兼容规则,但仍只能匹配本人账号;不修改全局归档授权。审核任务本体仍为创建者私有,混合账号父批次不能越权控制。

知识页主选择器、审核和整理弹窗使用服务端 knowledge_scope,空集合不回退全量。角色或账号集合改变会清理旧详情、勾选、预览与在途响应,无需退出重登。清洗执行时逐 HTTP 及落库校验、进度保留、队列公平调度和原始任务审计链继续保留。原客服对已发布知识的正常使用不变。

知识审核操作

单条审核使用明确的操作按钮确认;编辑后先保存草稿,再以服务端返回的版本号审核。有审核和发布权限时可“审核并发布”。合并操作使用严格布尔确认,索引完成后重新校验当前权限、账号范围、草稿版本、适用条件、来源和有效期;审核及发布记录在同一事务提交。外部索引失败或最终校验失败,不保留中间已审核状态。

勾选批量只需核对一次汇总,详情按需展开。详情最多并发 4 条、操作最多并发 3 条;停止后等待已发出的请求结束,失败不会自动重试。固定所选版本,版本变化时拒绝处理。

全量任务自动预览;具备全量审核、单条审核、发布及来源读取权限时,默认“一键审核并发布”。确认范围和数量后由持久化 Worker 逐条处理,关闭弹窗或离开页面不影响任务。审核、发布、目标结果及任务计数在同一事务提交,外部索引不持有写锁。暂停、取消、权限或范围变化会在提交前再次校验;并发 Worker 和重启不得重复发布或累计进度。旧的仅审核任务继续进入待发布。

本次在弹窗中发起的审核发布任务全部成功后,自动关闭审核弹窗并刷新知识列表;部分失败、待补充、暂停或取消时保留结果。查看历史已完成任务不会触发自动关闭。保留原有数据范围及角色权限,不因简化界面而新增授权。