wecom_it_smart_desk/docs/01-产品文档/01-认证与登录/PRD-REQ-认证-统一认证与登录-v1.1.md

# PRD-REQ-认证-统一认证与登录

> **版本**: v1.1 | **日期**: 2026-08-05 | **状态**: 预研整合（物理归档集 / Pre-research Consolidation — Physical Archive）
> **作者**: 宋献（产品） | **审核**: —
> **关联原型**: `原型-REQ-认证-001-扫码登录-v1.0.html`、`原型-REQ-认证-002-账号绑定-v1.0.html`
> **关联文档**: 技术方案 `../02-技术文档/技术方案-REQ-认证-统一认证与登录-v1.0.md` ｜ 测试用例 `../03-测试文档/03-功能测试用例/TC-REQ-认证-统一认证与登录-v1.0.md`
> **关联规范**: `00-产品开发流程与文档管理规范.md`

---

## 1. 文档目的与范围

### 1.1 背景

`docs/01-产品文档/01-认证与登录/` 目录下长期仅有原型图（`原型-REQ-认证-001-扫码登录`、`原型-REQ-认证-002-账号绑定`），**缺少对应的产品需求文档（PRD）**。与此同时，认证与登录相关的设计、实现、测试、部署内容散落在多个目录：

- 运维文档：`06-OTP二次验证实现.md`、`07-扫码登录OTP部署指南-v0.7.0.md`、`USER-GUIDE-QRCODE-MFA.md`、`OTP绑定-测试报告-20260708.md`
- 测试文档：`TC-REQ-认证-统一认证与登录-v1.0.md`（原名 `登录功能测试用例-20260706.md`，2026-08-05 按规范重命名）
- 技术架构：`05-架构图/admin-login-sequence.mermaid`、系统架构设计文档
- 任务说明书：`任务说明书-76-零信任VPN卡片免登录修复.md` 等

本 PRD 将上述散落内容**剥离、整合**为认证与登录模块的**产品级单一真源（Single Source of Truth）**。

### 1.2 整合方式说明（重要 · v1.1 修订）

本 PRD v1.0 采用「引用式整合」（源文档保留原目录、仅链接）。**v1.1 按用户决策 Q5 改为「物理归档集」**：

1. 认证模块**缺失的技术方案**已物理补齐于 `docs/02-技术文档/技术方案-REQ-认证-统一认证与登录-v1.0.md`；
2. 运维文档（06/07/USER-GUIDE）与测试文档（OTP绑定-测试报告）**原本即处于规范目录**（`04-运维文档/部署运维/`、`03-测试文档/`），未跨目录搬运，仅补充交叉引用以形成三件套闭环；
3. 本 PRD 现以「指向规范目录三件套」的归档集形式存在，不再以"引用式"双栖。

### 1.3 本次范围

- ✅ 整合现有认证与登录能力现状
- ✅ 固化「认证强度分级」决策（2026-08-05 锁定）
- ✅ 将「坐席端一键免登录（REQ-认证-003）」列为**后续待实现功能需求（需求预研）**
- ⚠️ 「管理端一键免登录（REQ-认证-004）」**明确不立项**（决策 Q3，仅保留设计边界，见 §5.2）
- ❌ 本次**不进入开发**（用户明确：维持现状，仅做需求预研）

---

## 2. 现状：认证与登录能力全景

当前系统提供三种登录/身份核验通道，并按角色施加不同强度的认证。

### 2.1 扫码登录（REQ-认证-001，已上线 v0.7.0）

| 项 | 内容 |
|---|---|
| 方式 | 坐席端/管理端/门户登录页展示企微二维码，用户用**手机企微客户端扫码**确认 |
| 后端 | `/api/auth_qrcode/*`（v0.7.0 新增 4 个端点） |
| 前端 | `frontend-agent/src/views/Login.vue`、`frontend-admin/src/views/Login.vue` 重写扫码 UI |
| 安全属性 | **双信道分离**（认证设备=手机 ≠ 操作设备=PC）+ **人工主动扫码** = 弱 2FA / 带外确认（out-of-band） |
| 参考 | `07-扫码登录OTP部署指南-v0.7.0.md`、`原型-REQ-认证-001-扫码登录-v1.0.html` |

### 2.2 账号绑定（REQ-认证-002，已上线）

| 项 | 内容 |
|---|---|
| 方式 | 坐席首次通过企微身份登录后，将其企微 `userid` 与系统 `agent` 账号建立绑定关系 |
| 作用 | 绑定是后续「一键免登录」「角色校验」「OTP 启用」的前置条件 |
| 参考 | `原型-REQ-认证-002-账号绑定-v1.0.html` |

### 2.3 OTP / MFA 二次验证（已上线 v0.7.0）⚠️ 重要澄清

> **澄清点**：用户在本次需求中提及"管理后台增加 OTP 列入后续待实现"。经核查文档，**管理端 OTP 已于 v0.7.0 实现，且为 admin 登录的常驻第二因子**，并非待建功能。本 PRD 据此修正理解：未来「管理端一键免登录」若立项，应**复用并强制前置既有 OTP**，而非从零建设 OTP。

| 项 | 内容 |
|---|---|
| 机制 | TOTP（pyotp / Google Authenticator），SMS（蜂鸟）作为备用通道 |
| 数据模型 | `users.mfa_secret`、`users.mfa_enabled`、`users.mfa_bound_at`、`users.mfa_last_verified_at` |
| 后端接口 | `/api/auth/otp-*`（6 个端点）、`/api/auth/otp-admin-reset/{employee_id}`、`/api/admin/high-risk/*`（高危操作 OTP 守卫 `require_high_risk_otp`） |
| 登录流程 | admin 角色且 `mfa_enabled=1` 时，登录返回 `require_otp: True`，前端显示 OTP 输入框，验证通过才签发 token |
| 坐席端 | OTP 为**可选**（绑定后启用）；admin 为**强制** |
| 错误码 | 1006/1007/1008/1009/1010（OTP 相关） |
| 参考 | `06-OTP二次验证实现.md`、`07-扫码登录OTP部署指南-v0.7.0.md`、`TC-REQ-认证-统一认证与登录-v1.0.md` |

### 2.4 企微 JS-SDK 免登录（已有构建块 `jsdk-login`）

| 项 | 内容 |
|---|---|
| 接口 | `/api/auth_wecom/jsdk-login` |
| 行为 | 传入企微 `userid` → 后端查角色 → 直接返回 token（agent / admin / user） |
| 现状 | 已在测试用例中覆盖（JSDK-01~05），是「一键免登录」后端的**现成半截**——缺前端在登录页主动拿 userid 的环节 |
| 参考 | `TC-REQ-认证-统一认证与登录-v1.0.md` §3.1 |

### 2.5 管理端登录基础流程

`admin-login-sequence.mermaid` 描述了 admin 基础登录序列：`/api/agents/login`（user_id + name）→ DB 查 role → Redis 存 token → 前端校验 `role==="admin"` → 存 `admin_token` → 跳转 `/admin/dashboard`。**注意**：该 mermaid 为 OTP 启用前的基础序列，实际生产流已叠加 §2.3 的 OTP 步骤。

---

## 3. 认证强度分级规范（2026-08-05 锁定）

以「**风险敞口**」而非「**功能对称**」分配认证强度，为后续需求与实现提供强制约束。

| 通道 | 安全属性 | 适用端 | 约束 |
|---|---|---|---|
| **扫码登录** | 双信道分离 + 人工扫码 = 弱 2FA / 带外确认 | 坐席端、管理端、门户 | 基准通道，始终保留 |
| **一键免登录**（agentConfig） | 单信道单设备，坍缩为单因子，**失去应用层带外确认** | **仅坐席端** | 仅限 PC 端、仅对**已绑定用户**开放；token 有效期应短于 8h |
| **管理端登录** | 高风险面（系统配置/权限/全局数据） | **管理端** | **不直接套用一键免登录**；OTP 为常驻强制第二因子 |
| **管理端一键免登录**（未来） | 单因子 + OTP 前置 | 管理端（未来，**不立项**） | 若立项，OTP **必须作为前置强制第二因子**同步落地 |

**精确表述**：一键免登录并非"无认证"——企微企业身份本身有平台级保障（手机绑定 + 企业账号 + 可见范围）。风险增量 = **应用层失去带外确认这一额外屏障**，而非归零。写技术方案时应避免被误解为"一键等于裸奔"。

---

## 4. 痛点与机会

| 痛点 | 影响对象 | 现状成本 |
|---|---|---|
| 坐席/管理员为高频用户，每日多次登录均需手机扫码（5–10 秒 + 找手机） | 坐席端、管理端日常使用者 | 操作摩擦累积，体验下降 |
| 已绑定用户在自己常用的企微客户端内登录，仍需跨设备扫码，存在"本可一步却两步"的冗余 | 已绑定坐席 | 体验与效率损失 |
| 管理端因风险高，长期只能扫码 + OTP 双步，暂无快捷通道（符合安全分级，但属已知权衡） | 管理员 | 安全优先，体验次之（可接受） |

**机会**：在不降低管理端安全水位的前提下，为**坐席端已绑定用户**提供合规的一键免登录，显著降低高频操作摩擦。

---

## 5. 后续待实现功能需求（需求预研 / Pending）

### 5.1 REQ-认证-003：坐席端一键免登录

**问题陈述**：已绑定的坐席在常用企微客户端（PC/Mac）内打开登录页时，仍需跨设备扫码，存在冗余操作摩擦。

**用户故事**
- 作为**已绑定坐席**，当我在自己常用的 PC 企微客户端内打开坐席端登录页时，我希望看到「一键登录」按钮，以便无需找手机扫码即可进入工作台。
- 作为**未绑定/新设备坐席**，我希望系统自动回落到扫码登录，以免误放行。
- 作为**安全负责人**，我希望一键登录仅在已绑定且单设备未显异常时可用，以便控制单设备被控的风险。

**需求分级（MoSCoW）**
- **Must（P0）**：
  - 登录页检测 `isWecomEnv()`（UA 含 `wxwork`）后，调用 `wx.config` + `wx.agentConfig`（`with_agent_config=true`）获取当前企微 `userid`
  - 后端新增 `POST /api/auth/check-wecom-bind?userid=xxx` 校验该 userid 是否已绑定坐席角色
  - 校验通过 → 显示「一键登录」按钮 → 复用 `jsdk-login` 签发 token → 进入工作台
  - 校验不通过 / agentConfig 失败 → **静默回落扫码**，不影响存量用户
- **Should（P1）**：仅对**已绑定用户**开放；token 有效期短于现有 8h（建议 2–4h + refresh）
- **Could（P2）**：同设备「常用设备」绑定，异地/新设备强制扫码；loading 态与防双击
- **Won't（本次）**：手机端企微一键登录（agentConfig 在手机端受限，暂缓评估）

**设计预研（基于既有可行性调研）**
- 前端断点：在 `Login.vue` 的 `isWecomEnv()` 分支内补齐 `wx.agentConfig` 调用链（复用 `wecom_jsapi.py` 的 `with_agent_config` 签名）
- 后端断点：新增 `check-wecom-bind` 接口，复用现有 `jsdk-login` 的 userid→token 签发
- **禁止使用 `window.wecom_userid` 全局变量**（历史 `EmergencyDispatcher.vue:113` bug 教训），userid 必须来自标准 SDK 调用
- H5 端无需改动（员工本就在企微内运行）

**验收标准（预研占位）**
- Given 坐席已绑定且处于 PC 企微内 → When 打开登录页 → Then 显示「一键登录」并可一键进入工作台
- Given 坐席未绑定或不在企微内 → When 打开登录页 → Then 仅显示扫码
- Given agentConfig 调用异常 → When 打开登录页 → Then 自动回落扫码，无报错阻塞

**风险**
- 单设备被控 → 攻击者可无手机配合新发起会话。**缓解**：仅已绑定用户 + 短时效 token + 设备绑定（P2）

### 5.2 REQ-认证-004：管理端一键免登录 + OTP 前置强制 — ⚠️ 不立项（设计预留）

**决策（2026-08-05，Q3）**：管理端一键免登录**不立项**。按 §3 认证强度分级，管理端风险敞口（系统配置/权限/全局数据）远大于坐席端，**不直接套用一键免登录**。本条目仅作为「未来若业务确需时的设计边界预留」，不作为待开发需求。

**设计预留（仅供未来参考，不进入排期）**
- 若未来立项，必须复用 REQ-认证-003 的企微身份探测逻辑 + 将既有 OTP（`/api/auth/otp-*`）作为**前置强制第二因子**。
- 新增部分仅为「企微身份一键探测 + 复用既有 OTP 作该通道前置网关」，**非从零建设 OTP**（OTP 基础设施已存在且为 admin 常驻强制因子）。
- 验收与风险同 v1.0 §5.2（保留作未来参考）。

---

## 6. 非目标（Non-goals）

1. **本次不开发**：仅 REQ-认证-003 做预研；REQ-认证-004 **不立项**，不排期、不写技术方案与任务说明书。
2. **不改变现有扫码登录**：扫码作为基准通道始终保留，一键免登录仅为增量可选。
3. **不降低管理端安全水位**：管理端不获得"无 OTP 的快捷登录"（已明确不立项）。
4. **不建设新 OTP 体系**：复用既有 `/api/auth/otp-*`，不重复造轮子。
5. **不涉及 H5 端登录改造**：H5 本就在企微内，无此场景。
6. **不做手机端一键登录**：agentConfig 在手机端受限，本轮暂缓。

---

## 7. 成功指标（未来上线后测量）

| 指标 | 定义 | 目标（建议） |
|---|---|---|
| 一键登录采纳率 | 已绑定坐席中使用一键登录的占比 | > 60%（上线 30 日内） |
| 扫码登录依赖下降 | 坐席端扫码次数占比下降 | 显著下降，不强制 |
| 一键登录端到端耗时 | 点击到进入工作台 | < 2s |
| 安全事件 | 单设备被控导致的未授权登录 | 0（配合短时效 + 设备绑定） |
| 管理端 OTP 触发率 | 管理端登录中 OTP 校验占比 | 100%（保持现行基线，REQ-004 不立项不影响） |

---

## 8. 开放问题 / 待决策

| # | 问题 | 提议方 | 状态 |
|---|---|---|---|
| Q1 | 一键登录 token 有效期上限取多少？（建议 2–4h） | 产品 + 安全 | 待决策 |
| Q2 | 是否引入「常用设备」绑定（P2）？ | 产品 | 待决策 |
| Q3 | 管理端一键登录是否立项？ | 管理层 | ✅ **已决策：不立项**（2026-08-05） |
| Q4 | agentConfig 在企微 PC 端的可用性是否已用生产账号验证？ | 技术 | 待验证（预研阶段） |
| Q5 | 源文档是否需要物理搬迁或维持引用式整合？ | 产品 | ✅ **已决策：物理归档集**（2026-08-05，见 §1.2） |

---

## 9. 参考文档索引

| 文档 | 路径 | 用途 |
|---|---|---|
| 认证模块技术方案 | `02-技术文档/技术方案-REQ-认证-统一认证与登录-v1.0.md` | 技术设计单一真源 |
| OTP 二次验证实现 | `04-运维文档/部署运维/06-OTP二次验证实现.md` | OTP 机制与接口（端点命名待对齐） |
| 扫码登录 + OTP 部署指南 | `04-运维文档/部署运维/07-扫码登录OTP部署指南-v0.7.0.md` | 扫码/OTP 部署与现状 |
| 扫码登录 MFA 用户手册 | `04-运维文档/部署运维/USER-GUIDE-QRCODE-MFA.md` | 用户侧说明 |
| OTP 绑定测试报告 | `03-测试文档/04-版本测试报告/OTP绑定-测试报告-20260708.md` | OTP 验证 |
| 登录功能测试用例 | `03-测试文档/03-功能测试用例/TC-REQ-认证-统一认证与登录-v1.0.md` | 登录/MFA 用例（含 REQ-003 预研） |
| 管理端登录序列图 | `02-技术文档/技术架构/05-架构图/admin-login-sequence.mermaid` | admin 基础登录流 |
| 零信任 VPN 卡片免登录 | `07-项目管理/任务说明书/任务说明书-76-零信任VPN卡片免登录修复.md` | 关联"免登录"上下文 |
| 扫码登录原型 | `01-产品文档/01-认证与登录/原型-REQ-认证-001-扫码登录-v1.0.html` | REQ-认证-001 原型 |
| 账号绑定原型 | `01-产品文档/01-认证与登录/原型-REQ-认证-002-账号绑定-v1.0.html` | REQ-认证-002 原型 |

---

## 10. 修订历史

| 版本 | 日期 | 变更内容 | 修改人 |
|---|---|---|---|
| v1.0 | 2026-08-05 | 初始整合版：梳理现状（扫码/绑定/OTP/jsdk-login）、固化认证强度分级、将坐席端与管理端一键免登录列为预研待实现需求 | 宋献 |
| v1.1 | 2026-08-05 | 决策落地：Q3 管理端一键不立项（§5.2 降级为设计预留）；Q5 物理归档集（§1.2）；新增技术方案 v1.0 索引；测试文档重命名 TC-REQ-认证-统一认证与登录-v1.0；修正 OTP 绑定测试报告路径；§8 开放问题状态更新 | 宋献 / Duckula |