6.3 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与标准前缀。如果通过其他地址访问，集团登录会先进入已配置的客服回调地址，再发起登录，避免不同域或端口丢失登录事务。回调仍严格固定，不接受任意跳转。
本地管理员在用户列表“来源/原账号”找到集团用户，选择业务角色即可；“集团基础用户”固定无权限，只读不可扩权。后端每请求使用新权限，已登录前端在页面可见时每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已透传配置，不能把密钥或密码放进这些地址。
集团菜单目录仅控制集团入口显示，客服业务菜单和按钮由客服本地角色决定。集团基础角色固定为空，需给用户分配其他业务角色，而不是给基础角色扩权。客服 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。