feat: OTP首次绑定 + 三端登录修复 + 管理端权限修复 (2026-07-08)

OTP首次绑定:
- 新增统一 OTP 路由 /auth/otp-* (otp.py + router.py)
- 坐席端 OTP 绑定面板 (OtpBindPanel.vue)
- 管理端 OTP 管理列表 (MfaManage.vue)
- agent_login 签发半认证 token 支持首次绑定流程

三端登录修复:
- 坐席/管理端去掉'返回扫码登录'按钮
- 管理端改为二维码始终可见+轮询扫码状态
- 员工端 /itdesk/ 改为 alias 直接服务 H5 (不再301重定向)
- docker-compose 添加 h5 volume 挂载

管理端权限修复:
- 扫码登录改用 get_user_roles() 替代写死 roles=['agent']
- get_user_roles() 增加 agents.role 回退
- 新增 GET /admin/roles/user-roles 端点
- 角色管理页加载用户角色分配数据

文档更新:
- OTP PRD + 系统设计文档
- 故障排查手册 v1.1 (新增6案例)
- nginx 生产基准配置

frontend-agent/src/stores/agent.ts

@@ -83,7 +83,6 @@ export const useAgentStore = defineStore('agent', () => {
 
       // 登录前先清除旧数据，避免切换账号时显示旧用户信息
       localStorage.removeItem(TOKEN_KEY)
-      localStorage.removeItem(PORTAL_TOKEN_KEY)
       localStorage.removeItem(AGENT_USER_ID_KEY)
       token.value = null
       agentUserId.value = null
@@ -91,7 +90,26 @@ export const useAgentStore = defineStore('agent', () => {
 
       const data = await apiLogin(inputUserId, password, otpCode)
 
-      // 检查是否需要 OTP 验证
+      // 检查是否需要 OTP 首次绑定（优先级高于 require_otp）
+      if ('require_otp_bind' in data && data.require_otp_bind) {
+        // 保存半认证 token（BUG-001 修复后新增），供后续 otp-bind/otp-verify 携带鉴权
+        if (data.token) {
+          token.value = data.token
+          agentUserId.value = data.user_id
+          localStorage.setItem(TOKEN_KEY, data.token)
+          localStorage.setItem(AGENT_USER_ID_KEY, data.user_id)
+        }
+        // 不抛异常，返回绑定信息供 Login.vue 展示 OtpBindPanel
+        logging.value = false
+        return {
+          require_otp_bind: true,
+          user_id: data.user_id,
+          name: data.name,
+          role: data.role,
+        }
+      }
+
+      // 检查是否需要 OTP 验证（已绑定用户二次验证）
       if ('require_otp' in data && data.require_otp) {
         // 返回 data，让 Login.vue 处理 require_otp
         logging.value = false