simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

Browse Source
This commit is contained in:
Simon
2026-07-07 21:52:11 +08:00
parent 242c1967ff
commit fab75760e0
203 changed files with 21504 additions and 3345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-产品需求/02-产品需求文档PRD-v1.2-20260704.md
+772 -306
View File
File diff suppressed because it is too large Load Diff
docs/02-产品需求/04-增量PRD-三端认证重构.md
+167
View File
@@ -0,0 +1,167 @@
# 增量 PRD — 三端认证重构（合并唯一认证方式 + 响应契约统一）
> **文档版本**: v1.0（增量）
> **创建日期**: 2026-07-06
> **产品经理**: 许清楚 (Xu)
> **状态**: 待架构师系统方案设计 / 任务分解
> **关联文档**:
> - `docs/02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` §4.5
> - `docs/11-历史归档/PRD-admin-v1.0-archived-20260703.md` §4.4
> - 架构文档 §6.7 `/api/agents/otp-*`（**本增量 PRD 裁定作废**）
> - `backend/app/utils/response.py`（统一信封 `success_response` / `error_response`）
---
## 0. 文档目标
1. **合并唯一认证方式**：将 PRD v1.2 §4.5 与 管理端 PRD v1.0 的认证章节合并为**唯一、无矛盾的认证规范**，消除两文档之间及文档内部的历史矛盾（统一入口残留、免密分支、登录方式数量、OTP 接口路径、员工端是否含密/OTP、管理端网络约束等）。
2. **收口响应契约统一（方案 A）**：将三端 Axios 拦截器与后端统一信封**收口为同一契约**，消除 H5 返回 envelope、agent/admin 返回 AxiosResponse 的不一致。
3. 本增量 PRD 与 §4.5 是**取代关系**：凡本文件与 v1.2 §4.5 / 管理端 PRD v1.0 认证章节冲突处，**一律以本文件为准**；相关旧条款视为作废。
---
## 1. 矛盾消解对照表（核心：证明"唯一认证方式"）
| # | 矛盾点 | 旧文档表述（冲突来源） | 本增量 PRD 裁定（唯一方式） |
|---|--------|------------------------|------------------------------|
| C1 | 统一入口 `/itportal/` | v1.2 §4.5.2「/itportal/ 已配置未使用，保留接口」；§4.5.7「Portal 前端 /api/portal/* 保留接口」 | **彻底移除** `/itportal/` 入口与 `/api/portal/*`；三端独立入口 `/itdesk/` `/itagent/` `/itadmin/`（决策1） |
| C2 | 管理端「免密直接进入」分支 | v1.2 §4.5.2 管理后台「企微已登录且有管理员角色 → 免密直接进入」；§4.5.4 场景一「免密直接进入」；§4.5.5「企微免密登录(wx.agentConfig)」 | **全部移除**免密分支与企微 JS-SDK 免密登录（决策4） |
| C3 | 登录方式数量 | v1.2 §4.5.3/§4.5.4「智能检测 + 三种登录方式（含免密）」 | 坐席/管理端**仅两种并列**：①企微扫码登录 ②账号密码+OTP（决策3） |
| C4 | OTP 接口路径 | v1.2 §4.5.7 `/api/mfa/*`、§4.5.10 `/api/mfa/bind/start`、`/api/mfa/verify`；架构 §6.7 `/api/agents/otp-*` | **统一为** `/api/auth/otp-bind` `/otp-verify` `/otp-unbind` `/otp-status`；旧路径全部作废（决策5） |
| C5 | 员工端是否含密码/OTP | v1.2 §4.5.3 仅「OAuth2 静默授权」，未禁止密码/OTP、未明确禁止企微外打开 | 员工端**无密码、无 OTP**；仅企微工作台内嵌(snsapi_base)打开；禁止企微外打开（非 wxwork UA 跳拦截页）；Token 经 `?token=` 传入并镜像本地（决策2） |
| C6 | 管理端网络约束 | v1.2 与管理端 PRD v1.0 均未规定 IP 白名单/内网/VPN | **新增** 管理端仅限内网/VPN + IP 白名单：`117.147.35.138`、`218.75.34.87`、`10.240.0.0`（内网/VPN 网段）（决策6） |
| C7 | 响应拦截器不一致 | H5 成功返回 `response.data`（envelope）；agent/admin 成功返回 `response`（AxiosResponse），调用方取 `.data.data` | 三端**统一方案 A**：成功返回内层 `data`，失败抛 `{code, message}`（决策7） |
| C8 | `portal_token` 遗留 | agent 拦截器 `handleAuthExpired` 仍清理 `portal_token` | 随 C1 清理所有 `portal_token` 引用（保留 `agent_token`） |
---
## 2. 用户故事
| ID | 角色 | 用户故事 | 优先级 |
|----|------|----------|--------|
| US-EMP-1 | 普通员工 (user) | 作为普通员工，我希望在企微工作台点击应用即**直接进入** IT 服务台（无需账号密码、无 OTP），以便快速提交 IT 问题并查看进度 | P0 |
| US-EMP-2 | 普通员工 (user) | 作为普通员工，我希望在**非企微环境**打开链接时被拦截提示，避免认证异常或信息泄露 | P0 |
| US-AGT-1 | IT 坐席 (agent) | 作为 IT 坐席，我希望在浏览器打开坐席工作台时，能用**企微扫码**或**账号密码+OTP** 登录（两种方式任选），以便在任何环境进入工作台 | P0 |
| US-AGT-2 | IT 坐席 (agent) | 作为 IT 坐席，我希望 **OTP 输入框在账号密码验证通过后才出现**，避免提前暴露与误填 | P0 |
| US-ADM-1 | 管理员 (admin) | 作为管理员（组长），我希望管理后台仅能从**内网/VPN 且 IP 在白名单**内打开，并支持扫码/账号密码+OTP 登录，确保安全 | P0 |
| US-ADM-2 | 管理员 (admin) | 作为管理员，我希望管理后台与坐席端使用**相同的认证与 Token 机制**，降低维护与排查成本 | P0 |
| US-DEV-1 | 开发者 | 作为开发者，我希望本地/测试环境**跳过** UA 校验、IP 白名单与真实企微 OAuth，员工端可走 dev/mock 登录，以便不依赖企微即可联调 | P0 |
---
## 3. 需求池
> 标注规则：**AUTH-** = 认证类；**CTRT-** = 响应契约类。
> 优先级：P0=Must / P1=Should / P2=Nice-to-have。
### 3.1 认证类（AUTH）
#### P0
| ID | 需求 | 说明 / 验收标准 |
|----|------|-----------------|
| AUTH-P0-1 | 三端独立入口确立 | 入口：`/itdesk/`（H5，企微内嵌）、`/itagent/`（浏览器）、`/itadmin/`（浏览器）。**移除** `/itportal/` 入口与 `/api/portal/*` 保留接口（含前端 portal 工程与 `portal_token` 清理，见 C1/C8）。 |
| AUTH-P0-2 | 员工端唯一认证 | OAuth2 静默授权（snsapi_base）→ 直进工作台；**无密码、无 OTP**；Token 经 URL `?token=` 传入并镜像 `localStorage`(`h5_token`)；**非 wxwork UA 跳拦截页**（仅生产启用，见 AUTH-P0-7）。 |
| AUTH-P0-3 | 坐席/管理端两方式并列 | 同源认证，浏览器直开，**仅两种并列**：①企微扫码登录 ②账号密码+OTP。**移除**「企微已登录且具角色→免密直接进入」分支（C2/C3）。 |
| AUTH-P0-4 | OTP 输入框渲染时机 | OTP 输入框**默认隐藏**，仅「账号密码验证通过」后才渲染（前端修正，含原型修正，见 §4）。 |
| AUTH-P0-5 | OTP 接口统一 | 统一为 `/api/auth/otp-bind` / `otp-verify` / `otp-unbind` / `otp-status`；**作废** `/api/mfa/*` 与 `/api/agents/otp-*`（C4）。语义：bind=首次绑定返回 secret/二维码；verify=校验/登录；unbind=解绑；status=查询绑定状态。 |
| AUTH-P0-6 | 管理端 IP 白名单 | 管理端仅允许 内网/VPN + IP 白名单：`117.147.35.138`、`218.75.34.87`、`10.240.0.0`（内网/VPN 网段）。非白名单 IP 拒绝访问（HTTP 403 / 拦截页）。仅生产启用（见 AUTH-P0-7）。 |
| AUTH-P0-7 | env-gating（环境门控） | UA 校验、IP 白名单、真实企微 OAuth **三者仅生产环境启用**；本地/测试环境跳过（详见 §5）。 |
| AUTH-P0-8 | 员工端本地 dev/mock 登录 | 本地/测试（ENV=dev 且未配 CorpId）走 dev/mock：复用 `backend/app/api/dev_auth.py` 的 `/api/dev/login` 签发测试 employee token（`login_source="dev"`）；H5 复用 `VITE_WECOM_CORP_ID` 为空时的 Mock 登录页分支。 |
| AUTH-P0-9 | Token 机制统一 | 三端统一 Bearer Token：员工端经 `?token=` 传入+本地镜像；坐席/管理端存 `localStorage`（`agent_token` / `admin_token`）。请求头统一 `Authorization: Bearer <token>`。清理 `portal_token` 遗留引用。 |
#### P1
| ID | 需求 | 说明 / 验收标准 |
|----|------|-----------------|
| AUTH-P1-1 | OTP 本地测试支持 | 坐席/管理端本地可直测：OTP 用标准 TOTP；本地显示 secret 或提供 dev 端点返回当前 TOTP 码。IP 白名单本地关闭。 |
| AUTH-P1-2 | 真实 OAuth 验证环境 | 真实企微 OAuth 端到端验证**仅在正式/Staging**（`itsupport.servyou.com.cn`，已配企微可信域名）进行，本地不依赖。 |
| AUTH-P1-3 | 首次绑定 OTP 引导 | 首次登录引导绑定 OTP（bind→展示 secret/二维码→verify 闭环）；后续登录走 verify。 |
#### P2
| ID | 需求 | 说明 / 验收标准 |
|----|------|-----------------|
| AUTH-P2-1 | 跨主体（互联企业）认证扩展 | 后续阶段支持跨主体员工：复用扫码/OTP 路径，不引入新认证方式。 |
### 3.2 响应契约类（CTRT）
#### P0
| ID | 需求 | 说明 / 验收标准 |
|----|------|-----------------|
| CTRT-P0-1 | 三端拦截器统一（方案 A） | 三端 Axios **响应拦截器**统一为：成功返回**内层 `data`**（`res.data`），失败抛出**标准化错误对象 `{code, message}`**。消除 H5 返回 envelope vs agent/admin 返回 AxiosResponse 的不一致（C7）。各端 401/1002 重授权逻辑保留（见 CTRT-P0-3）。 |
| CTRT-P0-2 | 三端调用点改造 | 三端现有 API 封装需适配：H5 原取 `response.data`（envelope）→ 改为直接消费内层 `data`；agent/admin 原取 `response.data.data` → 改为直接消费内层 `data`（拦截器已解包）。全量回归三端 API 调用点。 |
#### P1
| ID | 需求 | 说明 / 验收标准 |
|----|------|-----------------|
| CTRT-P1-1 | 后端信封审计 | 审查全部路由，确认均经 `success_response` / `error_response` 或全局 `AppException` 处理器（`response.py`），无裸 `dict` 直返 / 漏用信封的接口；发现漏网接口整改为统一信封。 |
| CTRT-P1-2 | 请求拦截器统一 | 三端请求拦截器统一注入 `Authorization: Bearer <token>`（已部分一致，统一键名与降级逻辑；清理 `X-Employee-Id` 明文头遗留）。 |
#### 401 / 未授权 处理约定（各端保留，统一上报形态）
| 端 | 触发 | 处理（保留既有逻辑） | 上报形态 |
|----|------|----------------------|----------|
| H5 | biz1002 / http401 / UA 拦截 | 清除 `h5_token`；生产→重走 OAuth2 重定向（带防循环计数）；Mock→跳 `/itdesk/login` | 抛 `{code:1002, message:"未授权"}` |
| Agent | biz1002 / http401 | 先静默刷新（`/api/auth/refresh`）；失败则清除 `agent_token` 并跳 `/login` | 抛 `{code, message}` |
| Admin | biz1002 / http401 | 清除 `admin_token` 并跳 `/login` | 抛 `{code, message}` |
---
## 4. UI 设计稿说明
> 原型图目录：`docs/04-原型设计/prototypes-原型图/`
| 端 | 引用原型 | 说明 |
|----|----------|------|
| 坐席 | `agent-login-v1.html` | 登录页（企微扫码 / 账号密码+OTP 两方式并列） |
| 管理 | `admin-login-v1.html` | 管理后台登录页（与坐席同构，叠加 IP 白名单约束） |
| 员工 | `h5-user-wecom-style-v2-mobile.html` | 企微工作台内嵌 H5 样式（无独立登录页；非企微打开跳拦截页） |
### ⚠️ 重点修正（必须落到前端实现）
1. **OTP 输入框默认隐藏**：`agent-login-v1.html` 与 `admin-login-v1.html` 中，OTP 输入行**初始不渲染**（或 `display:none`）；仅在「账号密码验证通过」后由前端动态渲染/启用。原型原稿若存在常显 OTP 框，需按此修正。
2. **两方式并列、无免密入口**：登录页仅保留「企微扫码登录」「账号密码+OTP」两个入口；**移除**原稿中「企微免密登录」按钮与「智能检测后免密进入」分支（对应 C2/C3）。
3. **员工端无登录表单**：`h5-user-wecom-style-v2-mobile.html` 不含账号密码/OTP 表单；非 wxwork UA 打开时展示拦截提示页（非登录页）。
4. **管理端网络提示**：`admin-login-v1.html` 在 IP 非白名单/非内网时展示「无访问权限」拦截页（由后端 403 驱动）。
---
## 5. 测试策略
### 5.1 本地环境处理（env-gating）
snsapi_base 的 `redirect_uri` 必须是企微后台配置的可信域名（`itsupport.servyou.com.cn`），本地 `localhost` 无法回调；且「禁止企微外打开」的 UA 校验在非 wxwork 浏览器会拦截。处理方案：
| 控制项 | 生产（production / itsupport.servyou.com.cn） | 本地 / 测试（dev / 未配 CorpId） |
|--------|-----------------------------------------------|----------------------------------|
| UA 校验（非 wxwork 跳拦截页） | **启用** | 跳过 |
| IP 白名单（管理端） | **启用** | 关闭 |
| 真实企微 OAuth | **启用** | 跳过（走 dev/mock） |
### 5.2 各端验证路径
- **员工端（本地）**：`VITE_WECOM_CORP_ID` 为空 → H5 走 Mock 登录页；调用 `/api/dev/login?role=user` 签发测试 employee token（`login_source="dev"`），模拟 `?token=` 入参并镜像 `h5_token`，断言工作台加载。
- **员工端（真实 OAuth）**：仅正式/Staging 验证 snsapi_base 静默授权 → `?token=` 传入 → 直进工作台；非 wxwork UA 验证跳拦截页。
- **坐席/管理端（本地）**：浏览器直开；OTP 用标准 TOTP（本地显示 secret 或 dev 端点返回当前码）；IP 白名单本地关闭；验证两方式并列与 OTP 输入框延迟渲染。
- **管理端（生产）**：仅限内网/VPN + 白名单 IP；非白名单 403。
### 5.3 自动化测试断言（针对 dev/mock，不依赖真实企微）
1. dev/mock 登录返回 `code:0` 且 `data.token` 为合法 Bearer Token。
2. 携带 `?token=` / `Authorization: Bearer` 后，工作台/管理页可加载（API 返回内层 `data`）。
3. 注入失效 Token → 触发 401/1002 → 按端重授权（员工重 OAuth/Mock 登录页；坐席刷新后跳 /login；管理跳 /login）。
4. 拦截器统一契约：成功返回内层 `data`；失败 `catch` 到 `{code, message}`（三端一致）。
5. OTP 接口：bind 返回 secret、verify 通过/失败分支、status 查询、unbind 闭环。
---
## 6. 待确认问题
**无。** 所有认证方式、网络约束、OTP 接口、响应契约与本地测试策略均依据已确认决策（决策1–7）与现行代码（`response.py`、三端 `api/index.ts`、`dev_auth.py`）落定，无需进一步确认。
---
> **文档结束** — 本增量 PRD 取代 PRD v1.2 §4.5 与管理端 PRD v1.0 认证章节中的相关条款，作为三端认证重构与响应契约统一的唯一权威来源，供架构师做系统方案设计与任务分解。
docs/02-产品需求/04-技术方案-消息推送策略优化与超时提醒.md
-227
View File
@@ -1,227 +0,0 @@
# 技术方案：消息推送策略优化与超时提醒
> **需求来源**：2026-07-05 产品讨论
> **版本**：v1.0
> **状态**：待开发
---
## 一、需求概述
### 1.1 业务背景
当前坐席回复用户消息时，会同时走两个通道：
1. **WebSocket** → 推送到 H5 页面
2. **企微应用消息** → 推送到"IT支持服务"应用的消息列表
这导致两种场景混在一起：
- 场景A：员工找坐席（一对一私密对话）→ 期望只走 H5
- 场景B：IT支持组群发通知 → 期望走企微消息
### 1.2 产品需求
| 需求 | 描述 |
|------|------|
| R1 | 正常对话：坐席回复仅推送到 H5 页面（WebSocket） |
| R2 | 坐席回复后员工 3 分钟（可配置）未回复，发送企微提醒消息 |
| R3 | 提醒消息只发 1 次 |
| R4 | 10 分钟后自动标记会话为"待关闭"状态 |
| R5 | 提醒文案固定（见 1.3） |
### 1.3 提醒文案
```
IT服务提醒：您有新的消息未查看，咨询将在10分钟后标记为待关闭，请尽快点击处理 👉 https://itsupport.servyou.com.cn/itdesk/
```
---
## 二、技术方案
### 2.1 架构设计
```
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ 坐席发送 │────▶│ WebSocket │────▶│ H5页面 │
│ 消息 │ │ (仅推送H5) │ │ (实时可见) │
└─────────────┘ └──────────────┘ └─────────────────┘
│
▼ (触发条件)
┌─────────────────────────────────────────┐
│ 后台定时任务 (每30秒) │
│ • 检查超时未回复会话 │
│ • 发送企微提醒消息 │
│ • 标记会话状态 │
└─────────────────────────────────────────┘
```
### 2.2 数据库改动
#### 2.2.1 conversations 表新增字段
```sql
ALTER TABLE conversations
ADD COLUMN IF NOT EXISTS last_agent_reply_at TIMESTAMP DEFAULT NULL,
ADD COLUMN IF NOT EXISTS reminder_sent BOOLEAN DEFAULT FALSE,
ADD COLUMN IF NOT EXISTS reminder_sent_at TIMESTAMP DEFAULT NULL,
ADD COLUMN IF NOT EXISTS pending_close_at TIMESTAMP DEFAULT NULL;
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `last_agent_reply_at` | TIMESTAMP | 坐席最后回复时间 |
| `reminder_sent` | BOOLEAN | 是否已发送提醒 |
| `reminder_sent_at` | TIMESTAMP | 提醒发送时间 |
| `pending_close_at` | TIMESTAMP | 待关闭时间（最后回复+10分钟） |
#### 2.2.2 配置表（可选）
在系统配置表中添加：
| key | default | 说明 |
|-----|---------|------|
| `reminder.timeout_minutes` | 3 | 未回复超时时间（分钟） |
| `reminder.close_minutes` | 10 | 自动待关闭时间（分钟） |
| `reminder.enabled` | true | 是否启用提醒功能 |
### 2.3 后端改动
#### 2.3.1 消息发送逻辑修改
**文件**：`backend/app/api/messages.py`
```python
# 坐席发送消息时
async def send_message(...):
# 1. 仅通过 WebSocket 推送到 H5（不再调用企微 API）
await manager.send_to_employee(conversation.employee_id, ws_event)
# 2. 更新会话的最后坐席回复时间
conversation.last_agent_reply_at = datetime.now()
conversation.reminder_sent = False # 重置提醒标记
conversation.pending_close_at = datetime.now() + timedelta(minutes=10)
```
#### 2.3.2 新增定时任务
**文件**：`backend/app/tasks/reminder_task.py`（新建）
```python
# 每 30 秒执行一次
@scheduler.scheduled_job('interval', seconds=30)
async def check_unreplied_sessions():
"""检查超时未回复的会话，发送提醒"""
# 1. 查找需要处理的会话
sessions = await db.execute(select(Conversation).where(
Conversation.status == 'active',
Conversation.last_agent_reply_at.isnot(None),
Conversation.reminder_sent == False,
Conversation.last_agent_reply_at < (datetime.now() - timedelta(minutes=3))
))
for session in sessions:
# 2. 发送企微提醒消息
await send_reminder_message(session)
# 3. 标记已发送
session.reminder_sent = True
session.reminder_sent_at = datetime.now()
# 4. 处理待关闭会话
pending = await db.execute(select(Conversation).where(
Conversation.status == 'active',
Conversation.pending_close_at < datetime.now()
))
for session in pending:
session.status = 'pending_close' # 待关闭状态
await db.commit()
```
#### 2.3.3 提醒消息发送函数
**文件**：`backend/app/services/reminder_service.py`（新建）
```python
async def send_reminder_message(conversation: Conversation):
"""发送超时提醒企微消息"""
message = "IT服务提醒：您有新的消息未查看，咨询将在10分钟后标记为待关闭，请尽快点击处理 👉 https://itsupport.servyou.com.cn/itdesk/"
redis_client = settings.create_redis_client()
wecom_service = WecomService(redis_client)
try:
await wecom_service.send_text_message(
conversation.employee_id,
message
)
finally:
await wecom_service.close()
await redis_client.close()
```
### 2.4 前端改动
#### 2.4.1 坐席端（无需改动）
当前坐席发送消息功能保持不变，后端会自动处理推送逻辑。
#### 2.4.2 H5 端（无需改动）
WebSocket 接收消息逻辑保持不变。
### 2.5 部署配置
#### 2.5.1 后端定时任务启动
在 `backend/app/main.py` 中注册定时任务：
```python
from apscheduler.schedulers.asyncio import AsyncIOScheduler
scheduler = AsyncIOScheduler()
scheduler.add_job(check_unreplied_sessions, 'interval', seconds=30)
scheduler.start()
```
---
## 三、任务分解
| # | 任务 | 文件 | 预估工时 |
|---|------|------|---------|
| 1 | 数据库迁移 | conversations 表新增字段 | 0.5h |
| 2 | 消息发送逻辑修改 | `backend/app/api/messages.py` | 0.5h |
| 3 | 新建提醒服务 | `backend/app/services/reminder_service.py` | 1h |
| 4 | 新建定时任务 | `backend/app/tasks/reminder_task.py` | 1h |
| 5 | 定时任务注册 | `backend/app/main.py` | 0.5h |
| 6 | 部署测试 | - | 1h |
**总计**：约 4.5 小时
---
## 四、风险与注意事项
1. **定时任务并发**：多实例部署时需确保任务不重复执行（建议加分布式锁）
2. **历史数据**：已存在的会话不受影响，新逻辑仅对新增会话生效
3. **配置灵活性**：当前为固定值，后续可扩展为可配置
---
## 五、相关文件清单
| 文件 | 操作 |
|------|------|
| `backend/app/api/messages.py` | 修改 |
| `backend/app/services/reminder_service.py` | 新建 |
| `backend/app/tasks/reminder_task.py` | 新建 |
| `backend/app/main.py` | 修改 |
| `docs/02-产品需求/04-技术方案-消息推送策略优化与超时提醒.md` | 新建 |
---
*最后更新：2026-07-05 15:40*
docs/02-产品需求/product-产品/v0.7.2-backlog-candidate-2026-06-24.md → docs/02-产品需求/v0.7.2-backlog-candidate-2026-06-24.md
+51 -11
View File
@@ -1,15 +1,17 @@
---
name: v0.7.2-backlog-candidate-2026-07-04
description: v0.7.1 开发中，基于文档优化专项后的最新状态更新
name: v0.7.2-backlog-candidate-2026-07-05
description: v0.7.1 已发布，蓝绿部署已完成，最新状态更新
metadata:
type: project
last_updated: 2026-07-04
last_updated: 2026-07-05
---
# v0.7.2 backlog 候选(2026-07-04 更新)
# v0.7.2 backlog 候选(2026-07-05 更新)
> **更新说明 (2026-07-04)**:
> - v0.7.1 正在开发中（企微SSO、RBAC权限）
> **更新说明 (2026-07-05)**:
> - v0.7.1 已发布 ✅（企微SSO、RBAC权限、消息互通）
> - 蓝绿部署已完成（Blue/Green 环境切换）
> - Gitea 服务已恢复 (v1.26.2)
> - 完成文档优化专项（用户手册创建、KPI指标补充、技术约束更新）
> - 补充阶段四/五的KPI指标定义
> - 新增需求：待办事项集成企微审批工单（#74）
@@ -27,32 +29,44 @@ metadata:
- 阻塞:**需网络组确认真实代理 IP 段**(WAF/堡垒机/CDN 出口 IP)
- 不能 Claude 单方面定,需用户提交工单
- 估时:1h(改 nginx + reload + 验证)
- 状态:待网络组确认
- **任务说明书**: `docs/10-任务说明/P1-01-IP白名单收窄.md`
2. **#74 [P1] 待办事项集成企微审批工单**
- 将企微审批工单同步到坐席待办事项
- 需企微审批应用 API 权限
- 估时:2-3天
- 状态:需企微API权限
- **任务说明书**: `docs/10-任务说明/P1-06-待办集成企微审批.md`
3. **#75 [P1] 头像同步功能完善**
- 员工端/坐席端头像显示优化
- 当前仅首次登录同步，需改为每次登录强制更新
- 需处理头像URL过期问题
- 估时:1-2天
- 状态:待开发
- **任务说明书**: `docs/10-任务说明/P1-02-头像同步功能完善.md`
3. **#73 [P1] 修后端文件未真正覆盖**
4. **#73 [P1] 修后端文件未真正覆盖**
- `yes | cp -f` 路径,部署时偶尔没生效
- 根因:`deploy-staging/` bind mount + RO 双重坑(见 [[bind-mount-deleted-inode-pitfall]])
- 估时:2h(改 deploy 脚本用 rsync --checksum)
- 状态:待开发
- **任务说明书**: `docs/10-任务说明/P1-03-修后端文件覆盖.md`
3. **#86 [P1] 排查流程图零依赖部分 review + 文档化**
5. **#86 [P1] 排查流程图零依赖部分 review + 文档化**
- 把 Mermaid 流程图从代码里剥离成可读文档
- 不阻塞生产,可顺手做
- 估时:3h
- 状态:待开发
- **任务说明书**: `docs/10-任务说明/P1-04-排查流程图文档化.md`
4. **#92 [P1] 修 v0.7.1-dev 引入的 pytest 失败(0 引入,33 pre-existing)**
6. **#92 [P1] 修 v0.7.1-dev 引入的 pytest 失败(0 引入,33 pre-existing)**
- 实际还有 64 个 pre-existing 失败(conftest 卡死环境问题)
- v0.7.1-dev 引入 0 个
- 估时:4h(可能是 conftest.py SQLite StaticPool 性能 + Windows + utf-8 + asyncio loop 顺序问题)
- 状态:待开发
- **任务说明书**: `docs/10-任务说明/P1-05-pytest失败修复.md`
### P2(可放 v0.7.3+ 或 v1.0)
@@ -104,19 +118,45 @@ metadata:
- #48 IP 白名单收窄(前提:网络组确认)
- #73 修后端文件覆盖
- #92/9 pytest 性能 + 33 失败修复
- 头像同步功能完善(#75)
**可选(顺手)**:
- #86 排查流程图文档化
- #10 看板刷新
- 待办事项集成企微审批工单(#74)
**暂缓(等用户/外部)**:
- #108 Gitea push
- #31 docker registry
- #43 HTTPS 证书
- #53 企微验证
> **已完成**:
> - ✅ #108 Gitea push - 已恢复服务 (v1.7.2)
> - ✅ 蓝绿部署架构 - 已实施完成
## Why
v0.7.1 已 release,P0 全清;剩余都是 P1/P2,用户应有选择权决定下一版本范围。
v0.7.1 已 release ✅,P0 全清;剩余都是 P1/P2,用户应有选择权决定下一版本范围。
## 🔄 已完成工作 (2026-07-05)
### v0.7.1 Release
- ✅ 企微 SSO 登录
- ✅ RBAC 权限体系
- ✅ 用户/坐席消息互通
- ✅ 管理后台功能完善
### 部署架构
- ✅ 蓝绿部署架构（Blue/Green 环境切换）
- ✅ Nginx upstream 动态切换
- ✅ 部署脚本 `switch-blue-green.sh`
### 基础设施
- ✅ Gitea 服务恢复 (v1.26.2)
- ✅ PostgreSQL/Redis 正常运行
### 文档整理
- ✅ 部署运维文档合并（01-部署指南、02-故障排查、03-版本记录）
- ✅ 蓝绿部署指南
## How to apply
下次用户问"接下来做什么"或"v0.7.2 规划",直接给这份清单让用户选。
docs/02-产品需求/功能详细规格说明书-P1P2功能.md
+649
View File
@@ -0,0 +1,649 @@
# IT智能服务台 - P1/P2功能详细规格说明书
> **文档版本**: v1.0
> **创建日期**: 2026-07-06
> **产品经理**: 宋献
> **状态**: 待技术可行性确认
> **对应需求**: 用户提供的P1/P2功能需求清单
---
## 目录
1. [概述与需求矩阵](#1-概述与需求矩阵)
2. [P1功能详细规格](#2-p1功能详细规格)
- 2.1 摇人按钮
- 2.2 满意度评价
- 2.3 排队系统
- 2.4 快速回复
- 2.5 知识库(基础)
3. [P2功能详细规格](#3-p2功能详细规格)
- 3.1 AI Wingman
- 3.2 会话标注
- 3.3 自动摘要
- 3.4 数据看板
- 3.5 知识库自动迭代
4. [技术可行性研究](#4-技术可行性研究)
5. [项目任务分解](#5-项目任务分解)
6. [风险与依赖](#6-风险与依赖)
---
## 1. 概述与需求矩阵
### 1.1 需求来源
本规格说明书基于用户提供的功能需求清单，结合现有PRD文档中的阶段规划进行编写。
### 1.2 需求矩阵
| 优先级 | 功能 | 阶段 | 现有需求ID | 依赖关系 |
|--------|------|------|------------|----------|
| P1 | 摇人按钮 | 阶段2 | P1-11 | 阶段1完成 |
| P1 | 满意度评价 | 阶段2 | 新增 | 阶段1完成 |
| P1 | 排队系统 | 阶段2 | P2-03 | 阶段1完成 |
| P1 | 快速回复 | 阶段2 | P1-09 | 阶段1完成 |
| P1 | 知识库(基础) | 阶段2 | 新增 | 阶段1完成 |
| P2 | AI Wingman | 阶段3 | P2-08 | P1知识库完成 |
| P2 | 会话标注 | 阶段3 | P2-04 | 阶段2完成 |
| P2 | 自动摘要 | 阶段3 | 新增 | P2-08依赖 |
| P2 | 数据看板 | 阶段4 | 新增 | 阶段3完成 |
| P2 | 知识库自动迭代 | 阶段4 | P2-05 | P2-04完成 |
---
## 2. P1功能详细规格
### 2.1 摇人按钮
> **需求ID**: P1-11（已存在于需求池）
> **阶段**: 阶段2
> **原型参考**: 第9章摇人功能设计
#### 2.1.1 功能描述
在H5端用户输入框左侧提供一键呼叫IT坐席的入口，用户点击后立即触发转人工流程。
#### 2.1.2 用户故事
```
作为 普通员工
我希望 点击"摇人"按钮一键呼叫IT坐席
以便 当AI无法解决我的问题时，可以快速获得人工帮助
```
#### 2.1.3 功能规格
| 要素 | 规格 |
|------|------|
| 入口位置 | H5输入框左侧，紧邻输入框 |
| 触发条件 | 点击按钮即触发，无需其他前置条件 |
| 触发后行为 | 1. 按钮变为"呼叫中..."状态；2. 发送转人工请求到后端；3. 分配空闲坐席；4. 建立会话连接 |
| 按钮样式 | 橙色渐变铃铛图标（参考企微风格），带脉冲动画吸引注意 |
| 兜底逻辑 | 无空闲坐席时进入排队，显示排队位置和预计等待时间 |
| 关闭方式 | 按钮右上角X，或会话建立后自动消失 |
#### 2.1.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 前端 | H5输入组件LeftArea添加摇人按钮组件 |
| 后端 | 新增 `/api/conversation/transfer-to-agent` 接口 |
| 状态管理 | Pinia新增 `transferring` 状态 |
| 消息协议 | WebSocket通知坐席有新会话 |
#### 2.1.5 验收标准
- [ ] 按钮在输入框左侧正确显示
- [ ] 点击后立即触发转人工流程
- [ ] 无空闲坐席时正确进入排队
- [ ] 会话建立后按钮消失
- [ ] 样式符合企微风格（橙色渐变）
---
### 2.2 满意度评价
> **需求ID**: 新增
> **阶段**: 阶段2
#### 2.2.1 功能描述
在会话结束后，邀请员工对本次服务进行满意度评价，用于持续优化服务质量。
#### 2.2.2 用户故事
```
作为 普通员工
我希望 在会话结束后对我的问题解决情况进行评价
以便 让IT团队了解服务满意度，帮助改进服务质量
```
#### 2.2.3 功能规格
| 要素 | 规格 |
|------|------|
| 触发时机 | 坐席点击"结单"按钮后，自动推送评价邀请 |
| 评价方式 | 5星好评 + 表情选择（😀满意/😐一般/😞不满意） |
| 评价内容 | 星级（必选）、表情（必选）、文字反馈（可选，限200字） |
| 展示时机 | 会话结束后3秒自动弹出，或H5返回首页时弹出 |
| 评价激励 | 评价后可参与抽奖（可选配置） |
| 数据存储 | 评价记录关联会话ID，存储到数据库 |
#### 2.2.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 前端 | 新增评价弹窗组件，集成到H5会话流程 |
| 后端 | 新增 `/api/conversation/{id}/evaluate` 接口 |
| 数据模型 | 新增 `ConversationEvaluation` 表 |
| 消息推送 | 企微应用消息推送评价邀请 |
#### 2.2.5 验收标准
- [ ] 会话结束后正确弹出评价邀请
- [ ] 5星评价和表情选择功能正常
- [ ] 评价数据正确存储
- [ ] 坐席可以在后台查看评价统计
---
### 2.3 排队系统
> **需求ID**: P2-03（已存在于需求池）
> **阶段**: 阶段2
#### 2.3.1 功能描述
当多个员工同时请求人工服务时，按请求顺序进行排队，并显示预计等待时间。
#### 2.3.2 用户故事
```
作为 普通员工
我希望 当所有坐席忙碌时能看到排队位置和预计等待时间
以便 合理安排等待时间，决定是否继续等待或稍后再试
```
#### 2.3.3 功能规格
| 要素 | 规格 |
|------|------|
| 触发条件 | 全部坐席忙碌（无空闲状态） |
| 排队展示 | 当前位置、前面等待人数、预计等待时间（基于平均处理时长计算） |
| 等待提示 | 每30秒更新排队状态，展示"正在为您转接，请稍候..." |
| 超时处理 | 排队超过10分钟提示"当前等待时间较长，是否继续等待？" |
| 取消排队 | 用户可主动取消排队，取消后释放排队位置 |
| 队列管理 | 按进入时间FIFO分配，VIP用户可插队（可选） |
#### 2.3.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 队列存储 | Redis List或数据库 `QueueItem` 表 |
| 实时推送 | WebSocket推送排队状态更新 |
| 分配算法 | 轮询+权重（VIP优先），基于坐席负载均衡 |
| 等待时间计算 | 移动平均算法，基于历史处理时长 |
#### 2.3.5 验收标准
- [ ] 坐席忙碌时自动进入排队
- [ ] 正确显示排队位置和预计等待时间
- [ ] 用户可主动取消排队
- [ ] 坐席空闲时正确分配
- [ ] 排队超时正确处理
---
### 2.4 快速回复
> **需求ID**: P1-09（部分存在于需求池）
> **阶段**: 阶段2
#### 2.4.1 功能描述
为坐席提供常用语管理功能，支持快捷搜索和插入，显著提升回复效率。
#### 2.4.2 用户故事
```
作为 IT坐席
我希望 快速找到并使用常用回复语
以便 减少重复输入，快速响应员工问题
```
#### 2.4.3 功能规格
| 要素 | 规格 |
|------|------|
| 入口位置 | 坐席工作台右栏AI助手面板 |
| 分类管理 | 支持多级分类（如：网络问题/软件问题/硬件问题） |
| 模板字段 | 标题、分类、关键词（支持多标签）、内容、适用场景 |
| 搜索方式 | 全文搜索 + 关键词标签匹配 |
| 使用方式 | 点击模板插入到输入框，支持Ctrl+数字快捷使用 |
| 权限管理 | 管理员创建/编辑，普通坐席只能使用 |
| 审核流程 | 新模板需管理员审核通过后生效（可选配置） |
#### 2.4.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 数据模型 | 复用现有 `QuickReplyTemplate` 表，扩展字段 |
| 前端 | 坐席工作台右栏新增快速回复Tab |
| 后端 | 优化搜索接口，支持全文检索 |
| 权限控制 | RBAC角色权限 |
#### 2.4.5 验收标准
- [ ] 快速回复面板正确显示
- [ ] 支持多级分类和搜索
- [ ] 点击模板正确插入到输入框
- [ ] 管理员可创建/编辑模板
- [ ] 搜索结果准确
---
### 2.5 知识库(基础)
> **需求ID**: 新增
> **阶段**: 阶段2
#### 2.5.1 功能描述
构建基础FAQ知识库，支持手动维护和检索，为AI和坐席提供知识支撑。
#### 2.5.2 用户故事
```
作为 IT坐席
我希望 在知识库中快速搜索问题答案
以便 为员工提供准确的解决方案
```
#### 2.5.3 功能规格
| 要素 | 规格 |
|------|------|
| 知识类型 | FAQ（问答对）、文档链接、操作步骤 |
| 维护方式 | 管理员手动新增/编辑/删除 |
| 分类体系 | 多级分类（按问题类型/部门/系统） |
| 标签管理 | 支持多标签，便于检索 |
| 搜索方式 | 关键词搜索 + 语义匹配（基于RAGFlow） |
| 展示形式 | 标题 + 摘要 + 详情 + 相关推荐 |
| 命中统计 | 记录每条知识的查看/使用次数 |
#### 2.5.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 数据模型 | 新增 `KnowledgeBase` 表 |
| 检索引擎 | 集成RAGFlow API进行语义检索 |
| 管理后台 | 新增知识库管理模块 |
| 访问控制 | 读：全员可访问；写：仅管理员 |
#### 2.5.5 验收标准
- [ ] 知识库管理后台可用
- [ ] 支持FAQ增删改查
- [ ] 搜索功能正常
- [ ] RAGFlow集成检索可用
- [ ] 命中统计正确记录
---
## 3. P2功能详细规格
### 3.1 AI Wingman
> **需求ID**: P2-08（部分存在于需求池）
> **阶段**: 阶段3
> **参考**: 现有第15章AI Wingman设计
#### 3.1.1 功能描述
AI驱动的坐席智能辅助系统，为坐席提供实时建议回复、相关知识推荐和操作指引。
#### 3.1.2 用户故事
```
作为 IT坐席
我希望 AI根据对话上下文自动建议回复内容
以便 减少思考时间，快速给出专业答案
```
#### 3.1.3 功能规格
| 要素 | 规格 |
|------|------|
| 建议生成 | 基于当前对话上下文，生成1-3条回复建议 |
| 生成时机 | 用户发送消息后实时生成 |
| 采纳方式 | 点击建议自动填入输入框，支持Ctrl+1/2/3快捷采纳 |
| 知识推荐 | 根据对话内容推荐相关知识库条目 |
| 步骤生成 | 针对常见问题生成排查步骤（结构化） |
| 风险提示 | 识别潜在风险并提醒坐席（如涉及敏感操作） |
| 反馈机制 | 坐席可标记建议"有用/无用"，用于模型优化 |
#### 3.1.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| AI服务 | 调用Dify Agent + 千问模型 |
| 上下文管理 | 会话窗口内消息摘要 |
| 知识检索 | RAGFlow API |
| 反馈存储 | 标注数据用于模型微调 |
#### 3.1.5 验收标准
- [ ] 对话过程中实时生成建议回复
- [ ] 知识推荐准确相关
- [ ] 风险提示有效
- [ ] 采纳率≥30%
---
### 3.2 会话标注
> **需求ID**: P2-04（已存在于需求池）
> **阶段**: 阶段3
#### 3.2.1 功能描述
坐席在工作过程中标注AI回复的准确性，形成数据闭环用于持续优化AI能力。
#### 3.2.2 用户故事
```
作为 IT坐席
我希望 对AI给出的回复进行正确/错误标注
以便 团队了解AI能力边界，持续改进服务质量
```
#### 3.2.3 功能规格
| 要素 | 规格 |
|------|------|
| 标注位置 | AI回复消息下方，"👍正确/👎错误"快捷按钮 |
| 错误类型 | 标记错误时需选择原因：信息不全/过时/不准确/其他 |
| 补充说明 | 可选填写错误详情（限100字） |
| 标注统计 | 坐席个人和团队维度统计准确率 |
| 关联动作 | 标注错误后可选择"提交知识库优化" |
#### 3.2.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 数据模型 | 新增 `MessageAnnotation` 表 |
| 标注接口 | `/api/messages/{id}/annotate` |
| 统计面板 | 管理后台新增标注统计视图 |
#### 3.2.5 验收标准
- [ ] AI回复下方显示标注按钮
- [ ] 标注操作正常存储
- [ ] 统计数据准确
- [ ] 错误反馈可关联知识库优化
---
### 3.3 自动摘要
> **需求ID**: 新增
> **阶段**: 阶段3
#### 3.3.1 功能描述
会话结束后，AI自动生成会话摘要，记录问题描述、解决方案和后续行动项。
#### 3.3.2 用户故事
```
作为 IT坐席
我希望 会话结束后自动生成摘要
以便 快速回顾会话内容，后续跟进有据可查
```
#### 3.3.3 功能规格
| 要素 | 规格 |
|------|------|
| 生成时机 | 坐席点击"结单"后自动生成 |
| 摘要内容 | 问题描述、解决步骤、涉及系统、后续行动项 |
| 存储位置 | 会话详情页"摘要"Tab |
| 人工修改 | 坐席可编辑补充摘要内容 |
| 模板化 | 支持按问题类型生成结构化摘要 |
#### 3.3.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| AI服务 | 调用Dify工作流生成摘要 |
| 存储 | `Conversation.summary` 字段 |
| 触发 | 结单API调用时异步生成 |
#### 3.3.5 验收标准
- [ ] 结单后自动生成摘要
- [ ] 摘要内容准确完整
- [ ] 坐席可编辑摘要
- [ ] 摘要可查看和导出
---
### 3.4 数据看板
> **需求ID**: 新增
> **阶段**: 阶段4
#### 3.4.1 功能描述
为IT管理者提供数据统计看板，支持服务质量分析和决策优化。
#### 3.4.2 用户故事
```
作为 IT主管
我希望 查看团队的服务数据统计
以便 了解服务质量，优化团队配置
```
#### 3.4.3 功能规格
| 维度 | 指标 |
|------|------|
| 整体概览 | 今日会话量、平均响应时长、解决率、满意度 |
| 坐席绩效 | 个人处理量、响应时长、解决率、满意度排名 |
| 问题分布 | 按类型/部门/时段分布热力图 |
| AI效果 | AI解决率、采纳率、误判率 |
| 趋势分析 | 周/月/季度趋势曲线 |
#### 3.4.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 数据聚合 | SQL统计 + Redis缓存 |
| 图表展示 | ECharts可视化 |
| 导出功能 | Excel/PDF导出 |
#### 3.4.5 验收标准
- [ ] 看板正确显示各项指标
- [ ] 数据更新及时（准实时）
- [ ] 支持时间范围筛选
- [ ] 数据导出功能正常
---
### 3.5 知识库自动迭代
> **需求ID**: P2-05（已存在于需求池）
> **阶段**: 阶段4
#### 3.5.1 功能描述
基于会话标注数据，AI自动分析知识库缺口，生成优化建议并执行更新。
#### 3.5.2 用户故事
```
作为 IT主管
我希望 AI能自动发现知识库盲区并生成更新建议
以便 知识库持续迭代，避免重复问题
```
#### 3.5.3 功能规格
| 要素 | 规格 |
|------|------|
| 分析维度 | 错误标注高频问题、未命中知识库的会话、AI不确定回复 |
| 生成建议 | 自动生成FAQ草稿、标记过时内容 |
| 审核流程 | AI生成内容需管理员审核后生效 |
| 推送机制 | 通过企微消息推送审核通知给管理员 |
| 效果追踪 | 更新后跟踪该知识点的解决率提升 |
#### 3.5.4 技术实现
| 组件 | 实现方式 |
|------|----------|
| 分析服务 | 定时任务 + 千问分析 |
| 知识更新 | RAGFlow API批量操作 |
| 通知服务 | 企微应用消息推送 |
| 效果追踪 | A/B测试对比 |
#### 3.5.5 验收标准
- [ ] 定时分析标注数据
- [ ] 生成优化建议准确
- [ ] 审核流程完整
- [ ] 更新后效果可追踪
---
## 4. 技术可行性研究
### 4.1 技术栈匹配
| 功能 | 技术要求 | 现有技术栈 | 可行性 |
|------|----------|-----------|--------|
| 摇人按钮 | WebSocket实时通信 | 已有WS通道 | ✅ 完全可行 |
| 满意度评价 | 数据存储+消息推送 | PostgreSQL+企微消息API | ✅ 完全可行 |
| 排队系统 | Redis队列管理 | Redis已部署 | ✅ 完全可行 |
| 快速回复 | 全文搜索 | 可用LIKE/全文索引 | ✅ 完全可行 |
| 知识库 | RAGFlow集成 | RAGFlow已部署 | ✅ 完全可行 |
| AI Wingman | Dify Agent | Dify已部署 | ✅ 完全可行 |
| 会话标注 | 数据模型 | 新增表即可 | ✅ 完全可行 |
| 自动摘要 | Dify工作流 | Dify已部署 | ✅ 完全可行 |
| 数据看板 | 数据聚合+可视化 | ECharts | ✅ 完全可行 |
| 知识库自动迭代 | 定时任务+AI分析 | 现有架构扩展 | ✅ 可行（需资源） |
### 4.2 风险评估
| 功能 | 主要风险 | 风险等级 | 缓解措施 |
|------|----------|----------|----------|
| 排队系统 | 高并发性能 | 中 | Redis集群 + 限流 |
| AI Wingman | 响应延迟 | 中 | 异步生成 + 缓存 |
| 数据看板 | 查询性能 | 低 | 预计算 + 缓存 |
| 知识库自动迭代 | AI生成质量 | 中 | 人工审核把关 |
### 4.3 依赖关系
```
阶段1完成
↓
P1功能（阶段2）
├── 摇人按钮 ←─────────────┐
├── 满意度评价 ←─────────┤
├── 排队系统 ←───────────┤
├── 快速回复 ←──────────┤
└── 知识库 ←────────────┘
↓
P2功能（阶段3-4）
├── AI Wingman ← 知识库完成
├── 会话标注 ← 阶段2完成
├── 自动摘要 ← AI Wingman依赖
├── 数据看板 ← 阶段3完成
└── 知识库自动迭代 ← 会话标注完成
```
---
## 5. 项目任务分解
### 5.1 阶段2任务（P1功能）
| 任务ID | 任务名称 | 预估工时 | 负责人 | 依赖 |
|--------|----------|----------|--------|------|
| T2-01 | 摇人按钮前端开发 | 2d | 前端 | 无 |
| T2-02 | 摇人按钮后端接口 | 2d | 后端 | 无 |
| T2-03 | 满意度评价前端 | 2d | 前端 | 无 |
| T2-04 | 满意度评价后端 | 2d | 后端 | 无 |
| T2-05 | 排队系统后端 | 3d | 后端 | 无 |
| T2-06 | 排队系统前端 | 2d | 前端 | T2-05 |
| T2-07 | 快速回复管理后台 | 3d | 前端+后端 | 无 |
| T2-08 | 快速回复坐席端 | 2d | 前端 | T2-07 |
| T2-09 | 知识库基础管理 | 4d | 前端+后端 | RAGFlow |
| T2-10 | 阶段2集成测试 | 3d | QA | T2-01~09 |
**阶段2预估总工时**: 25人日
### 5.2 阶段3任务（P2功能-上半）
| 任务ID | 任务名称 | 预估工时 | 负责人 | 依赖 |
|--------|----------|----------|--------|------|
| T3-01 | AI Wingman后端集成 | 5d | 后端 | Dify |
| T3-02 | AI Wingman前端 | 3d | 前端 | T3-01 |
| T3-03 | 会话标注功能 | 3d | 前端+后端 | 无 |
| T3-04 | 自动摘要功能 | 4d | 后端 | Dify |
| T3-05 | 阶段3集成测试 | 3d | QA | T3-01~04 |
**阶段3上半预估总工时**: 18人日
### 5.3 阶段4任务（P2功能-下半）
| 任务ID | 任务名称 | 预估工时 | 负责人 | 依赖 |
|--------|----------|----------|--------|------|
| T4-01 | 数据看板后端统计 | 4d | 后端 | 数据积累 |
| T4-02 | 数据看吧前端 | 3d | 前端 | T4-01 |
| T4-03 | 知识库自动迭代分析 | 4d | 后端 | 会话标注数据 |
| T4-04 | 知识库自动迭代执行 | 3d | 后端 | T4-03 |
| T4-05 | 阶段4集成测试 | 3d | QA | T4-01~04 |
**阶段4预估总工时**: 17人日
---
## 6. 风险与依赖
### 6.1 外部依赖
| 依赖项 | 用途 | 状态 |
|--------|------|------|
| 企微消息API | 消息推送、通知 | ✅ 已集成 |
| RAGFlow | 知识库语义检索 | ✅ 已部署 |
| Dify | AI服务编排 | ✅ 已部署 |
| 千问模型 | AI生成能力 | ✅ 已部署 |
### 6.2 内部依赖
- 阶段1MVP必须先完成
- 知识库是AI Wingman的前提
- 会话标注是知识库自动迭代的前提
### 6.3 风险预案
| 风险场景 | 应对方案 |
|----------|----------|
| AI服务不可用 | 降级到纯人工模式，显示友好提示 |
| 高并发排队 | 限流 + 排队超时引导 |
| 知识库检索无结果 | 兜底到人工回复 |
---
## 附录：版本历史
| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2026-07-06 | 初始版本 |
---
*文档结束*
docs/02-产品需求/待开发功能任务清单.md
+121
View File
@@ -0,0 +1,121 @@
# 待开发功能任务清单
> 生成日期: 2026-07-05
> 状态: 待开发
---
## 一、M1 阶段待开发功能（本地可实现）
### P1 系列
| ID | 功能 | 状态 | 优先级 |
|----|------|------|--------|
| P1-20 | 邀请功能-历史消息共享 | 待开发 | P1 |
| P1-21 | 邀请功能-部门批量邀请 | 待开发 | P1 |
| P1-22 | 邀请功能-系统消息广播 | 待开发 | P1 |
| P1-23 | 文件上传 | 待开发 | P1 |
### 已实现（M1）
| ID | 功能 | 状态 |
|----|------|------|
| P1-01 | 会话标记系统 | ✅ 已实现 |
| P1-02 | 会话列表排序 | ✅ 已实现 |
| P1-03 | VIP标记自动匹配 | ✅ 已实现 |
| P1-04 | 举手标记 | ✅ 已实现 |
| P1-05 | 需介入标记 | ✅ 已实现 |
| P1-06 | 情绪标记（规则版） | ✅ 已实现 |
| P1-07 | 紧急度评分 | ✅ 已实现 |
| P1-08 | 置顶/代办 | ✅ 已实现 |
| P1-09 | 坐席端AI助手面板 | ✅ 已实现 |
| P1-10 | 用户端H5双栏 | ✅ 已实现 |
| P1-11 | 摇人按钮 | ✅ 已实现 |
| P1-12 | 趣味话术体系 | ✅ 已实现 |
| P1-13 | 用户端AI助手面板 | ✅ 已实现 |
| P1-14 | AI草稿回复 | ✅ 已实现（需AI接入） |
| P1-15 | 会话自动摘要 | ✅ 已实现（需AI接入） |
| P1-16 | 自动标签 | ✅ 已实现（需AI接入） |
| P1-17 | AI建议采纳追踪 | ✅ 已实现 |
---
## 二、M2 阶段功能（需要 AI 接入）
### 待开发（需要 Dify/RAGFlow）
| ID | 功能 | 依赖服务 |
|----|------|----------|
| P2-01 | AI前置筛选 | Dify |
| P2-02 | 转人工触发配置 | 配置中心 |
| P2-03 | 排队系统 | 后端 |
| P2-04 | 对话日志标注 | 后端 |
| P2-05 | AI知识库自动迭代 | Dify + RAGFlow |
| P2-06 | 情绪标记（模型版） | Dify |
| P2-07 | 跨企业共享 | 企微API |
| P2-08 | AI建议回复动态生成 | Dify |
| P2-09 | 操作步骤AI动态生成 | Dify |
| P2-10 | 风险提示AI动态判断 | Dify |
| P2-11 | 知识推荐 | RAGFlow |
| P2-12 | SOP流程导航 | 后端 |
| P2-13 | 相似工单推荐 | 后端 |
| P2-14 | 客户画像 | 后端 |
| P2-15 | 情绪识别预警 | Dify |
| P2-16 | 安抚话术推荐 | Dify |
| P2-17 | 语气润色 | Dify |
| P2-18 | 正向激励 | 后端 |
| P2-19 | 坐席疲劳检测 | 后端 |
---
## 三、M3 阶段功能
全部依赖 AI 接入，暂无条件开发。
---
## 四、本次开发任务
### 任务1：邀请功能-历史消息共享（P1-20）
**需求**：
- 邀请时可选择共享历史消息模式（全部/最近10条/不共享）
- 默认最近10条
- 被邀请人可查看共享的历史消息
**技术方案**：
- 后端：新增字段 `history_share_mode` 到 conversations 表
- API：修改 `/invite` 接口支持历史消息参数
- 前端：InviteDialog 增加历史消息选项
### 任务2：邀请功能-部门批量邀请（P1-21）
**需求**：
- 可按部门批量邀请
- 勾选部门=邀请全部门成员
- 部门节点勾选后自动展开子成员，支持取消个别成员
**技术方案**：
- 后端：新增 `/api/departments` 通讯录API
- 前端：InviteDialog 增加部门选择器组件
### 任务3：邀请功能-系统消息广播（P1-22）
**需求**：
- 邀请成功/加入/退出时在会话中广播系统消息
- 所有参与者看到 "XX邀请XX加入会话" "XX已加入会话"
**技术方案**：
- 后端：在 invite/join/leave 操作时插入系统消息
- 前端：MessageList 渲染系统消息类型
### 任务4：文件上传（P1-23）
**需求**：
- 坐席/员工可发送文件附件（PDF/Word/Excel/压缩包等）
- 文件可上传、存储、下载
- 大小限制可配置（默认20MB）
**技术方案**：
- 后端：已有上传API，需完善文件类型校验
- 前端：InputBox 增加文件上传按钮