# Release Notes v0.7.1

> 📅 发布日期:2026-06-23 | 类型:🔐 安全 + ✨ 功能 | 紧急度:🟡 重要
> 🔄 补充:2026-06-24 hotfix #116/#118/#119/#120 已部署(详见文末"补充 hotfix"小节)

## 🎯 本版本重点

1. **修复扫码登录 iOS NSURLErrorCannotFindHost** — 企微 App 用户扫码不再报错
2. **完整 MFA + RBAC 权限体系** — 5 角色细粒度权限 + 高危操作二次认证
3. **H5 员工端企微 OAuth 登录** — 员工不再需要输账号密码
4. **🆕 扫码登录去掉手机 confirm 步骤** — 企微 App 无确认 UI,扫码成功 = 直接登录

## 🔐 安全修复

### #109 P0:扫码登录 NSURLError 修复

**问题**:用户企微 App 访问 `https://itsupport.servyou.com.cn/itportal/`,扫描二维码后跳转报 `NSURLErrorCannotFindHost`(iOS WebView DNS 解析失败)

**根因**:`backend/app/config.py` 新字段 `qrcode_oauth_callback` 用了 pydantic 默认行为,**不剥环境变量前缀**
- 字段名:`qrcode_oauth_callback`
- pydantic-settings 期望 env:`QRCODE_OAUTH_CALLBACK`
- 实际 env:`WECOM_QRCODE_CALLBACK`(带前缀,匹配不上)
- 结果:`settings.qrcode_oauth_callback = ""`,qrcode_service 走兜底返回**相对路径** `/api/auth_qrcode/scan`
- iOS WebView 拼接相对路径失败 → DNS 解析错误

**修复**:
```python
from pydantic import Field

class Settings(BaseSettings):
    qrcode_oauth_callback: str = Field(
        default="",
        validation_alias="WECOM_QRCODE_CALLBACK",
    )
```

**部署**:docker commit + restart + 验证,详见 [[phase1-progress#109-hotfix-二轮修复]]

### RBAC 5 角色 × 4 资源 × 4 操作 × 3 范围

- **5 角色**:super_admin / admin / agent / user / guest
- **4 资源**:user / conversation / config / audit_log
- **4 操作**:read / create / update / delete
- **3 范围**:all / department / self

### 高危路由白名单 + 中间件

5 类高危操作需 OTP 二次认证:
- `role_change`(角色变更)
- `config_change`(配置变更)
- `data_export`(数据导出)
- `account_disable`(账户禁用)
- `account_create_reset`(账户创建/重置)

## ✨ 新功能

### 后端扫码登录(端点 4 个)

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/auth_qrcode/create` | POST | 生成二维码(含 PNG base64) |
| `/api/auth_qrcode/poll/{ticket}` | POST | 扫码端轮询 |
| `/api/auth_qrcode/scan` | POST | 企微回调 |
| `/api/auth_qrcode/confirm` | POST | 用户确认登录 |

### 后端 MFA + pyotp(端点 5 个)

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/mfa/status` | GET | 查询绑定状态 |
| `/api/mfa/bind/start` | POST | 开始绑定(返回 secret + QR) |
| `/api/mfa/bind/confirm` | POST | 确认绑定 |
| `/api/mfa/verify` | POST | 验证 OTP |
| `/api/mfa/disable` | POST | 禁用 MFA |

### 前端 MFA UI

- `MfaBind.vue` — 绑定弹窗
- `useHighRiskOtp.ts` composable — 高危操作 OTP 弹窗
- `Login.vue` / `TopBar.vue` — 集成 MFA 状态显示
- 路由 + store 全链路集成

### H5 员工端 OAuth 登录

- 部署路径:`https://itsupport.servyou.com.cn/itdesk/`
- 自动 OAuth 静默授权(`snsapi_base`)
- 会话列表 + 消息收发
- 已完成 E2E 验证(#104)

## 🛠️ 部署要点

### 必备环境变量

```bash
# /opt/wecom-it-desk/.env
WECOM_QRCODE_CALLBACK=https://itsupport.servyou.com.cn/api/auth_qrcode/scan
WECOM_SSO_ENABLED=true
WECOM_SSO_CALLBACK_BASE=https://itsupport.servyou.com.cn
```

### 部署清单

- [x] Backend commit `78f60c6`(v0.7.1-dev)
- [x] docker 镜像 `wecom-it-desk-backend:latest` 已 commit 新 config
- [x] 容器已重启 + /api/ready 200
- [x] H5 dist 已部署到 `/opt/wecom-it-desk/nginx/html/itdesk/`
- [x] nginx 已 reload
- [x] /api/auth_qrcode/create 返回绝对 URL
- [ ] Gitea push(等用户重授权 token)
- [ ] 企微 App 实际扫码验证

## ⚠️ 已知问题

1. **Gitea push 阻塞**:`workbuddy-claude` token 2026-06-15 被吊销,需去 Gitea Web 重授权
2. **#108 still pending**:v0.7.1-dev 78f60c6 未推到 origin
3. **/api/admin/ IP 白名单**仍是 0.0.0.0/0(临时方案),v1.0 前必须收窄

## 📚 相关文档

- [[H5-DEPLOY-RUNBOOK-v0.7.1]] — H5 部署 runbook
- [[DEPLOY-LOGIN-MIGRATION-v0.7.0]] — 旧版扫码登录
- [[E2E-CHECKLIST-v0.7.0]] — 端到端验收
- [[NGINX-DOMAIN-ROUTING]] — nginx 域名分发
- [[USER-GUIDE-QRCODE-MFA]] — 用户手册
- [[phase1-progress]] — 进展跟踪

## 📊 改动统计

- **代码**:22 文件 / +4705 行
- **测试**:78 passed + 4 xfail + 33 pre-existing failures(已分类)
- **文档**:5 新增 / 3 更新
- **Agent**:4 并行 worktree 合并

---

## 🔄 补充 hotfix(2026-06-24 部署)

### #116 P0 + #118 P0:扫码端点 405 + ticket≠state

**问题**:
- 坐席扫码登录报 `405 Method Not Allowed`
- 企微 OAuth 回调走 GET(`?code=xxx&state=<ticket>`),旧代码只支持 POST
- 即使改双方法,`Optional[str] = None` 没 `Query()` 装饰器,FastAPI 当 body 参数处理
- 函数参数叫 `ticket`,企微用 `state`,参数名不匹配

**修复**:`backend/app/api/auth_qrcode.py` scan 端点
```python
@router.api_route("/scan", methods=["GET", "POST"], response_model=None)
async def scan_qrcode(
    body: Optional[QrcodeScanRequest] = None,
    ticket: Optional[str] = Query(None, description="兼容旧参数名"),
    state: Optional[str] = Query(None, description="企微 OAuth state 标准参数名"),
    code: Optional[str] = Query(None, description="企微 OAuth 授权码"),
    redis_client = Depends(dep_redis),
):
    if body is not None:
        final_ticket, final_code = body.ticket, body.code
    else:
        final_ticket = state or ticket  # 优先 state(企微标准),回退 ticket
        final_code = code
```

**部署**:`deploy-staging/hotfix-116-qrcode-scan-get/` — webcli v7 一键,20/20 pytest 过

### #119:webcli v7 全自动部署链路

复用 jumpserver Playwright + Luna webcli + OTP 自动,实现 18-31KB 命令脚本单次输入,2-3 分钟跑完。

### #120 P0:扫码成功 = 自动登录(去掉 confirm)

**问题**:企微 App 端没有"确认登录" UI,旧 confirm 步骤在生产永远走不通(用户报告"扫码成功后,手机端没有出现确认登录按钮")

**用户决策**:方案 A — 扫码成功 = 自动登录(推荐),2026-06-24 拍板

**修复**:`backend/app/services/qrcode_service.py` `process_scan` 默认 `auto_confirm=True`
- 扫码成功直接写 `qrcode:confirm:{ticket}`(含 token)
- 前端 poll 立即拿到 status=confirmed + token
- 跳过手机 confirm 步骤
- 默认 roles=["user"],admin/agent 走 portal 端角色选择

**测试**:20/20 pytest 过(`test_scan_then_poll_returns_confirmed` + `test_scan_auto_confirm_writes_confirm_key` 等)

**部署**:`deploy-staging/hotfix-120-qrcode-auto-confirm/` — webcli v7 一键,容器内 `/api/ready` 200 OK

**残留**:外部域名 `https://itsupport.servyou.com.cn/api/ready` 不通(nginx `/api/` upstream 配错 + 8000 端口未暴露),**等 #48 修复**。容器内 backend 完全健康。