docs: 移动蓝绿部署指南到 troubleshooting 目录

2026-07-05 17:03:36 +08:00
parent ab90db3d3d
commit ca7c6d937a
91 changed files with 4841 additions and 406 deletions
@@ -1,11 +1,13 @@
 # 企微智能IT支持服务台 — 产品需求文档 (PRD)

-> **文档版本**: v1.5
+> **文档版本**: v1.6
 > **创建日期**: 2025-07-11
 > **最近更新**: 2026-07-04
 > **产品经理**: 许清楚 (Xu) · 宋献
 > **状态**: 阶段一开发完成，待端到端验证
 > **说明**: 本文档已合并原 `PRD-v53-incremental.md` 内容（v5.3 坐席工作台增量需求）。v1.0 更新：新增管理后台远景规划（§17）、系统生态与集成规划（§18）、阶段细化与并行推进策略（§19）；明确管理后台为第三端产品；确立 AI 混合策略（流程图+AI+标注+迭代）；将阶段一细化为 1A/1B/1C 子阶段；新增零基础人员原则。v1.1 更新：新增邀请功能设计（§20），将邀请功能纳入M1 MVP（1A子阶段），新增P0-09~P0-11和P1-14~P1-16需求。v1.2 更新：整合 `PRD-增量-人工按钮与术语统一.md` 内容为新章节§10 术语与图标规范。v1.3 更新：新增 §4.5 指标体系详细设计；修复 §16 v5.3 内部章节编号；将 v5.3 项目信息移至 §1.1。v1.4 更新（2026-07-04）：**产品经理视角重构**——新增 §1 产品愿景与目标、§1.5 用户画像、§1.6 非目标章节；补充竞品分析至产品定义章节。
+v1.6 更新（2026-07-05）：坐席端登录流程优化——智能检测企微客户端登录状态，已登录则提供企微快捷登录+浏览器登录+账号密码OTP三种方式；未登录则默认企微扫码登录+账号密码OTP兜底。
+
 v1.5 更新（2026-07-04）：登录逻辑调整——用户端强制企微内嵌，坐席/管理端浏览器直接打开（无需经过企微工作台），支持账号密码+OTP认证。

 > **章节编号说明**: 主文档章节编号为 2-20（§1 在附录中），附录内使用独立编号体系（附录A §1-10、附录B §1-2、附录C §1-6）。后续新增章节应按顺序递增。
@@ -614,45 +616,70 @@ v1.5 更新（2026-07-04）：登录逻辑调整——用户端强制企微内

 #### 4.4.4 各端登录方式

-> **更新日期**: 2026-07-04 | **设计目标**: 用户安全入口可控，坐席/管理员独立访问
+> **更新日期**: 2026-07-05 | **设计目标**: 用户安全入口可控，坐席/管理员独立访问

 | 端 | 访问方式 | 登录方式 | 说明 |
 |----|----------|----------|------|
 | **用户端 (H5)** | 企微工作台 → 应用内嵌打开 | OAuth2 静默授权 | 强制内嵌，保证安全、入口统一、用户粘性 |
-| **坐席端** | 浏览器直接打开 | 账号密码+OTP | **无需经过企微**，灵活办公，支持多设备 |
+| **坐席端** | 浏览器直接打开 | 智能检测+三种登录方式 | 企微快捷登录/浏览器扫码/账号密码+OTP |
 | **管理后台** | 浏览器直接打开 | 账号密码+OTP | **无需经过企微**，安全可控 |

-#### 4.4.5 坐席/管理员登录流程
+#### 4.4.5 坐席登录流程（v1.6 优化）

-> **更新日期**: 2026-07-04 | **核心变更**: 坐席/管理员无需经过企微工作台
+> **更新日期**: 2026-07-05 | **核心变更**: 智能检测企微登录状态，提供三种登录方式

 ```
-坐席访问 /itagent/（管理员访问 /itadmin/）
+坐席访问 /itagent/
    ↓
-浏览器打开登录页
+检测企微客户端登录状态（企微 JS-SDK）
    ↓
-┌─────────────────────────┐
-│ 登录方式选择             │
-│                         │
-│ [🔐 账号密码+OTP登录]  │ ← 主要方式
-│                         │
-│ [🐛 企微扫码登录]      │ ← 备选方式（如有企微环境）
-└─────────────────────────┘
+┌──────────────────────────────────────────────────────┐
+│ 场景一：检测到企微已登录                               │
+│ ┌────────────────────────────────────────────────┐  │
+│ │ 选择登录方式                                    │  │
+│ │                                                │  │
+│ │ [① 在企业微信桌面端打开] → wecom:// 协议       │  │
+│ │                                                │  │
+│ │ [② 继续在浏览器登录]    → 企微扫码+验证码      │  │
+│ │                                                │  │
+│ │ [③ 账号密码+OTP]      → 传统表单登录          │  │
+│ └────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────┘
    ↓
-输入用户名 + 密码 + OTP验证码
+┌──────────────────────────────────────────────────────┐
+│ 场景二：未检测到企微登录                              │
+│ ┌────────────────────────────────────────────────┐  │
+│ │ 默认登录页（企微扫码 + 账号密码OTP）            │  │
+│ │                                                │  │
+│ │  ┌─────────────────┐   ┌─────────────────┐    │  │
+│ │  │  企微扫码登录   │   │ 账号密码+OTP   │    │  │
+│ │  │  (二维码)       │   │                 │    │  │
+│ │  └─────────────────┘   └─────────────────┘    │  │
+│ └────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────┘
    ↓
 验证成功 → 发放Token → 进入工作台
 ```

-#### 4.4.6 企微扫码登录（备选）
+#### 4.4.6 登录方式详细说明
+
+| 登录方式 | 适用场景 | 技术实现 | 用户操作 |
+|----------|---------|---------|---------|
+| **① 企微快捷登录** | 企微客户端已登录 | JS-SDK `wx.agentConfig` 获取用户身份 → 后端校验坐席角色 | 点击"在企业微信桌面端打开"自动跳转 |
+| **② 浏览器企微扫码** | 企微客户端未登录但有企微App | 显示企微OAuth二维码 → 用户扫码授权 | 微信/企微扫码 → 授权 → 自动登录 |
+| **③ 账号密码+OTP** | 无企微环境或二维码失效 | 传统表单 + TOTP验证码 | 输入账号密码+OTP → 登录 |
+
+#### 4.4.7 企微客户端检测

 | 检测方式 | 代码 | 说明 |
 |----------|------|------|
 | **企微内嵌检测** | `navigator.userAgent.includes('wxwork')` | 检测UA是否包含wxwork |
-| **企微内打开** | 调用企微JSAPI `wx.openDefaultBrowser()` 或跳转企微应用URL | 在企微客户端中打开 |
-| **浏览器登录** | 常规表单登录 + OTP输入框 | 账号密码+OTP验证 |
+| **企微 JS-SDK** | `wx.agentConfig()` | 获取当前企微用户身份（需企业微信JS-SDK引入） |
+| **企微协议跳转** | `wecom://` | 唤起企微客户端打开指定页面 |

-> **注意**：用户端（`/itdesk/`）强制企微内嵌，非企微环境访问跳转拦截页。
+> **注意**：
+> - 用户端（`/itdesk/`）强制企微内嵌，非企微环境访问跳转拦截页
+> - 坐席端智能检测为增强体验，检测失败时回退到默认登录页

 #### 4.4.7 技术实现

@@ -2454,8 +2481,8 @@ class TroubleshootingTemplate(Base):
 |------|------|------|
 | `docs/重构方案-复杂场景技术方案.md` | 非线性跳转/多意图等技术方案 | 规划中 |
 | `docs/PRD-增量-人工按钮与术语统一.md` | "人工"按钮与术语规范 | 待实施 |
-| `docs/ARCHITECTURE.md` | 现有系统技术架构 | 维护中 |
-| `docs/小组任务书/任务执行状态看板.md` | 项目任务状态管理 | 维护中 |
+| `docs/03-技术架构/00-系统架构设计文档-v1.3.md` | 现有系统技术架构 | 维护中 |
+| `docs/10-项目管理/05-项目状态看板/01-项目状态看板.md` | 项目任务状态管理 | 维护中 |
 | `docs/archive/` | 已归档的重构方案文档 | 已归档 |

 ---