wecom_it_smart_desk/docs/01-产品文档/04-坐席工作台/PRD-REQ-坐席-001-截图拍照-v1.0.md

坐席端截图 + 拍照功能 PRD

子系统: 04-坐席工作台 模块: 截图拍照

项目信息

项	内容
语言	中文
技术栈	Vue3 + Element Plus + Tailwind CSS
项目名称	agent_screenshot_camera
前端目录	D:\资料\03-项目开发\wecom_it_smart_desk\frontend-agent
涉及组件	ReplyBox.vue / ScreenshotEditor.vue / ScreenCapture.vue（改造）+ 新增 CameraCapture.vue

原始需求复述

IT智能服务台坐席端（PC Web 应用）需要增加截图和相机拍照功能。客服在处理工单时经常需要截取屏幕内容或拍照来辅助沟通。截图需支持全屏/窗口/标签页选择（含跨屏），截图时屏幕变暗出现矩形选框 + 工具栏（马赛克、文字标注、箭头、撤销），样式参考微信/企微截图工具。拍照需用 getUserMedia + <video> 实现内嵌摄像头预览，支持重拍。截图和拍照结果均插入到聊天输入区作为图片消息等待发送（非立即发送）。

---

产品定义

产品目标

1. 提升沟通效率：客服无需切换到外部截图工具或手机拍照，直接在工作台内完成截图/拍照→编辑→发送的全流程，减少上下文切换。
2. 保证信息准确性：通过截图标注（马赛克打码、箭头指引、文字说明）和实时拍照，让客服能够精准传递屏幕画面和实物状况，减少口头描述的歧义。
3. 统一图片消息发送体验：截图和拍照结果统一进入输入区待发送队列，客服可在发送前预览、补充文字说明或删除，与现有粘贴图片/文件上传的交互保持一致。

用户故事

1. 作为客服坐席，我想直接在工作台点击截图按钮截取屏幕画面，这样我就能把用户报障的屏幕现象快速发给用户确认，而不需要切换到微信截图或系统截图工具。

2. 作为客服坐席，我想在截图时用马赛克遮挡敏感信息（如密码、个人信息），这样在发送截图时不会泄露用户隐私。

3. 作为客服坐席，我想在截图选区内用箭头和文字标注重点位置，这样用户能快速理解我指的具体是哪里。

4. 作为客服坐席，我想通过摄像头拍照来记录实物设备状态（如硬件故障、线缆连接），这样比文字描述更直观。

5. 作为客服坐席，我想截图/拍照后的图片先进入输入区等我自己确认后再发送，这样我能在发送前检查标注是否正确、是否打码到位。

---

技术规范

现有代码分析

通过对 frontend-agent/src/components/chat/ 目录的代码审查，发现以下现状：

组件	现状	差距
ReplyBox.vue	工具栏有表情、文件、邀请、快速回复按钮；已有 handleScreenshot()（用 html2canvas）和 handleScreenCapture()（用 getDisplayMedia，但未接入任何按钮）	缺少截图/拍照入口按钮；截图结果直接上传发送而非插入输入区
ScreenshotEditor.vue	裁剪 + 编辑两步模式，工具有画笔/高亮/矩形/箭头/文字，支持撤销/重做	缺少马赛克工具
ScreenCapture.vue	全屏遮罩框选模式，工具有画笔/矩形/箭头/文字	缺少马赛克工具；结果直接发送
upload.ts	文件上传 API，支持重试，返回 { url, filename, file_size, msg_type }	可复用
拍照功能	完全不存在	需新建 CameraCapture.vue 组件

关键发现：ReplyBox.vue 中已有 handleScreenCapture() 方法调用了 navigator.mediaDevices.getDisplayMedia()，但该方法未绑定到任何 UI 按钮。当前截图按钮实际走的是 handleScreenshot() → html2canvas（仅能截取当前页面 DOM，无法截取其他窗口/屏幕）。

需求池

P0 — 必须实现（Must Have）

编号	需求	验收标准
P0-1	截图入口按钮：在 ReplyBox.vue 工具栏新增截图按钮（图标裁剪刀或相机图标），与表情、文件等按钮并列	点击后触发 getDisplayMedia() 屏幕选择流程
P0-2	getDisplayMedia 屏幕捕获：调用 navigator.mediaDevices.getDisplayMedia() 获取屏幕流，捕获一帧画面传入截图编辑器	浏览器弹出屏幕/窗口/标签页选择器；支持选择跨屏显示器；用户取消时静默退出不报错
P0-3	截图选区编辑：全屏遮罩 + 矩形选框拖拽，选区内可编辑，选区外半透明遮罩（对标微信截图）	屏幕变暗；拖拽出现选框；选框可拖动调整大小；8 个方向手柄
P0-4	马赛克工具：截图编辑工具栏新增马赛克工具，拖拽涂抹区域进行像素化打码	选择马赛克工具后在选区内拖拽，拖过区域被马赛克覆盖；支持撤销
P0-5	文字标注工具：点击选区内位置弹出文本输入，输入后渲染为画布上的文字标注	点击出现输入框（非 prompt()，用内联 input）；回车确认渲染到 canvas
P0-6	箭头工具：拖拽绘制带箭头的线段	起点到终点绘制箭头；箭头头部自动计算角度
P0-7	撤销功能：工具栏撤销按钮，逐步撤销编辑操作	每次操作入栈，撤销弹栈；撤销到空时禁用按钮
P0-8	截图结果插入输入区：截图确认后，图片以缩略图形式显示在输入框上方（textarea 之上），作为待发送图片，不自动发送	输入区上方出现图片缩略图 + 删除按钮；可继续输入文字；点击发送时图片和文字一起发送
P0-9	拍照入口按钮：在 ReplyBox.vue 工具栏新增拍照按钮（摄像头图标）	点击后弹出摄像头预览弹窗
P0-10	getUserMedia 摄像头预览：用 navigator.mediaDevices.getUserMedia({ video: true }) 获取摄像头流，渲染到 <video> 元素实时预览	弹窗内嵌视频预览；自动选择前置摄像头；摄像头不可用时显示错误提示
P0-11	拍照捕获：点击拍照按钮，从 <video> 当前帧 capture 到 canvas，转为图片	拍照后预览切换为静态图片；显示"重拍"和"确认"按钮
P0-12	重拍功能：拍照后点击"重拍"返回实时预览状态	重拍后清除上一张照片，恢复 <video> 实时预览
P0-13	拍照结果插入输入区：拍照确认后，图片以缩略图形式显示在输入框上方，作为待发送图片	与 P0-8 行为一致
P0-14	待发送图片发送流程：发送消息时，如果有待发送图片，先上传图片再发送图片消息（msg_type: 'image'），如有文字则额外发送文字消息	图片上传复用 uploadFile() API；发送成功后清空待发送图片和文字
P0-15	待发送图片删除：输入区待发送图片缩略图上有删除按钮，点击移除	点击 × 后缩略图消失，不影响文字内容

P1 — 应该实现（Should Have）

编号	需求	验收标准
P1-1	多张待发送图片：输入区可同时插入多张待发送图片（如先截一张再拍一张）	支持多张缩略图横向排列；发送时按顺序上传发送；可单独删除某一张
P1-2	颜色选择：截图编辑工具栏提供颜色选择（红/黄/蓝/绿/黑等常用色）	点击颜色切换标注颜色；当前选中颜色高亮
P1-3	矩形框工具：拖拽绘制矩形边框（用于圈选区域）	与微信截图矩形工具一致
P1-4	截图保存到本地：截图编辑器提供"保存"按钮，将截图下载到本地	下载为 PNG 文件，文件名 screenshot-{timestamp}.png
P1-5	摄像头切换：如果有多个摄像头，支持切换前后摄像头	弹窗内显示切换按钮；切换后预览更新
P1-6	ESC 退出：截图模式和拍照弹窗均支持 ESC 键退出	按 ESC 等同于取消
P1-7	截图选区尺寸显示：拖拽选区时实时显示选区宽×高像素值	选区右下角或工具栏旁显示 W×H 像素值

P2 — 优先级较低（Nice to Have）

编号	需求	验收标准
P2-1	画笔自由绘制：截图编辑器提供自由画笔工具	拖拽绘制自由曲线；线宽可调
P2-2	高亮工具：半透明黄色高亮笔	拖拽覆盖区域呈半透明高亮
P2-3	快捷键截图：支持 Ctrl+Shift+A 快捷键触发截图	全局快捷键，焦点不在输入框也能触发
P2-4	拍照镜像翻转：前置摄像头预览水平镜像（符合自拍习惯），但保存的图片不镜像	预览镜像、输出正向
P2-5	截图延时捕获：支持 3 秒延时截图（用于捕获鼠标悬停菜单等动态画面）	选择延时后倒计时 3-2-1 再捕获

---

UI 设计要点

1. 工具栏布局（ReplyBox.vue）

现有工具栏顺序：表情 | 文件 | 分隔线 | 邀请 | 快速回复

改造后：截图 | 拍照 | 分隔线 | 表情 | 文件 | 分隔线 | 邀请 | 快速回复

• 截图按钮放在最左侧（最高频使用），图标用裁剪刀 SVG 或 ✂️
• 拍照按钮紧跟截图按钮，图标用摄像头 SVG 或 📷
• 与现有按钮样式保持一致（.tb-btn 类，32×28px，hover 高亮 + tooltip）

2. 截图模式（全屏覆盖层）

• 触发：点击截图按钮 → 浏览器弹出 getDisplayMedia 选择器（选屏幕/窗口/标签页）
• 选区：选中后屏幕变暗（rgba(0,0,0,0.5) 遮罩），鼠标变为十字光标
• 拖拽框选：按住鼠标拖拽出现矩形选框（绿色边框 #07C160，对标微信），选区内画面清晰，选区外半透明
• 8 方向手柄：选框四角 + 四边中点各一个手柄，可拖拽调整大小
• 工具栏：选区下方居中浮动工具栏，从左到右：
  • 工具组：马赛克 | 文字 | 箭头 | 矩形（P1）
  • 颜色组：🔴 🟡 🔵 🟢 ⚫（P1）
  • 操作组：撤销 | 保存(P1) | 取消 | 确认✓
• 尺寸提示：选区右下角实时显示 宽×高 像素值（P1）
• ESC 退出：按 ESC 取消截图

3. 拍照弹窗（CameraCapture.vue）

• 弹出方式：Element Plus el-dialog 居中弹窗，宽度约 640px
• 预览区：<video> 元素填满弹窗主体，自适应摄像头分辨率
• 控制区：弹窗底部居中放置拍照按钮（圆形大按钮，图标 📷）
• 拍照后状态：
  • <video> 隐藏，显示 <canvas> 或 <img> 静态画面
  • 底部按钮变为：重拍 （左）| 确认 （右，绿色主按钮）
• 错误状态：摄像头不可用时显示"无法访问摄像头，请检查权限设置"提示 + 关闭按钮
• 关闭：右上角 ✕ 或 ESC 关闭弹窗，停止摄像头流

4. 待发送图片预览区（输入框上方）

• 位置：在 ReplyBox.vue 的 textarea 上方、工具栏下方，新增一个待发送图片预览条
• 布局：横向排列缩略图，每张缩略图约 80×80px，圆角，右上角有 × 删除按钮
• 样式：浅色背景容器，与现有引用回复预览条（.reply-preview）风格一致
• 多张图片：横向排列，超出宽度时可横向滚动
• 交互：
  • 鼠标悬停缩略图可放大预览（可选 P2）
  • 点击 × 删除该张待发送图片
  • 发送后清空所有待发送图片

5. 视觉风格

• 主色调：与现有坐席端一致，使用 CSS 变量 var(--accent)、var(--bg-secondary) 等
• 截图选框颜色：#07C160（微信绿，与现有 ScreenCapture.vue 一致）
• 工具栏：白色背景 + 阴影，与现有 ScreenshotEditor.vue 工具栏风格一致
• 弹窗：Element Plus 默认主题，圆角 8px

---

待确认问题

编号	问题	影响范围	建议
Q1	企微内嵌浏览器兼容性：getDisplayMedia() 和 getUserMedia() 在企微内置浏览器中是否可用？现有代码注释提到"Screen Capture API 在企微桌面端被限制，不稳定"。	截图功能核心可行性	建议在企微环境下做一次可用性测试；如不可用，保留 html2canvas 作为 fallback（仅能截当前页面）
Q2	HTTPS 要求：getDisplayMedia() 和 getUserMedia() 要求 HTTPS 环境（或 localhost）。坐席端部署是否为 HTTPS？	截图 + 拍照功能可行性	确认生产环境域名是否为 HTTPS；如非 HTTPS 则两个功能都无法使用
Q3	待发送图片与文字的组合发送：用户在输入区有待发送图片 + 文字时，发送方式是：(a) 先发图片消息再发文字消息（两条消息）？还是 (b) 合并为一条富文本消息？	消息发送逻辑	建议方案 (a)：先发图片再发文字，与现有粘贴图片行为一致。后端如支持图文混排消息可改为 (b)
Q4	截图工具栏工具优先级：需求明确提到"马赛克、文字标注、箭头、撤销"四个工具。是否也需要矩形框工具（P1）和高亮/画笔（P2）？	编辑器功能范围	建议 P0 只做需求明确的 4 个工具，矩形框放入 P1
Q5	摄像头权限提示：首次使用拍照功能时浏览器会请求摄像头权限。是否需要自定义权限引导提示？	用户体验	建议在调用 getUserMedia 前先显示一个简短提示"即将请求摄像头权限，请在弹窗中允许"
Q6	InputBox.vue 是否同步改造：代码库中存在 InputBox.vue（旧版输入组件）和 ReplyBox.vue（当前使用）。是否需要同步改造 InputBox.vue？	改造范围	建议只改 ReplyBox.vue，InputBox.vue 如已废弃则不动
Q7	截图后的编辑器复用：现有 ScreenshotEditor.vue（裁剪+编辑两步）和 ScreenCapture.vue（全屏框选+编辑）两个组件功能重叠。新截图功能基于哪个改造？	架构设计	建议基于 ScreenCapture.vue 改造（全屏遮罩框选更符合微信截图体验），废弃或保留 ScreenshotEditor.vue 供 html2canvas fallback 使用

---

附录：现有代码关键路径

frontend-agent/src/
├── components/chat/
│   ├── ReplyBox.vue          ← 主输入组件（改造：加按钮 + 待发送图片区）
│   ├── InputBox.vue           ← 旧版输入组件（待确认是否改造）
│   ├── ScreenshotEditor.vue   ← 截图编辑器（改造：加马赛克工具）
│   ├── ScreenCapture.vue      ← 全屏框选截图（改造：接入 getDisplayMedia + 加马赛克）
│   └── CameraCapture.vue      ← 新建：摄像头拍照组件
├── api/
│   ├── upload.ts              ← 文件上传 API（复用）
│   └── message.ts             ← 消息发送 API（复用）
└── stores/
    └── conversation.ts        ← 会话状态管理（可能需扩展：待发送图片队列）