simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
facc04aa653d9ac63f310cb2eb33f0e979c6ec39
wecom_it_smart_desk/docs/01-产品文档/01-认证与登录/PRD-REQ-认证-统一认证与登录-v1.1.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

224 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |
Reference in New Issue View Git Blame Copy Permalink