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

15 KiB
Raw Blame History

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