# PRD - 快速回复规则后台管理

> **需求编号**: REQ-通用-002
> **版本**: v1.2
> **状态**: [已评审]
> **作者**: Simon
> **日期**: 2026-07-27（初版） / 2026-07-28（v1.2 变更）
> **关联文档**:
> - 原型图：`01-产品文档/01-02产品设计/快速回复规则后台管理-原型图.html`
> - 技术方案：`02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md`
> - 任务说明书：`07-项目管理/任务说明书/任务说明书-131-快速回复规则后台管理.md`
> - 测试用例：`03-测试文档/03-功能测试用例/TC-通用-002-快速回复规则后台管理.md`
> - 部署文档：`04-运维文档/快速回复规则后台管理-部署文档-v1.0.md`
> - 整改记录：`04-运维文档/部署运维/00-文档规范化整改记录.md`

---

## 1. 需求描述

### 1.1 背景

当前AI回复的快速规则（打招呼、业务路由、发送名片）全部硬编码在Python代码中，存在以下问题：

- **维护不便**：修改关键词需要改代码、部署
- **无法运营**：运营人员无法自主配置规则
- **灵活性差**：无法快速响应业务变化

### 1.2 目标

建立后台可编辑的快速规则管理系统，将硬编码的规则配置迁移到数据库，支持运营人员在管理后台灵活配置。

同时考虑未来扩展性：系统既要支持**人工快速维护**，也要为**智能体自动优化**（AI Agent 自动分析消息、调整规则）保留接口能力。

### 1.3 范围

| 规则类型 | 当前实现 | 目标 |
|---------|---------|------|
| 打招呼关键词 | `ai_handler.py` 硬编码 | 数据库 + 管理页面 |
| 业务路由关键词 | `routing_service.py` 硬编码 | 数据库 + 管理页面 |
| 路由目标配置 | `routing_service.py` 硬编码 | 数据库 + 管理页面 |

---

## 2. 用户故事

### 2.1 运营人员

| 优先级 | 用户故事 |
|--------|---------|
| P0 | 作为运营人员，我希望在管理后台增删改查打招呼关键词，无需每次修改代码 |
| P0 | 作为运营人员，我希望在管理后台维护业务路由关键词，及时响应业务变化 |
| P1 | 作为运营人员，我希望修改规则后立即生效，无需重启服务 |
| P1 | 作为运营人员，我希望看到规则的启用/禁用状态，快速调整规则 |

### 2.2 开发人员

| 优先级 | 用户故事 |
|--------|---------|
| P0 | 作为开发人员，我希望规则数据存储在数据库，支持多环境配置 |
| P1 | 作为开发人员，我希望规则加载有缓存，减少数据库查询压力 |

---

## 3. 功能需求

### 3.1 数据库设计

新建 `quick_rules` 表：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL | 主键 |
| rule_type | VARCHAR(50) | 规则类型：greeting/routing_prefilter/routing_target |
| category | VARCHAR(50) | 业务分类（行政/人力/财务/法务/物业） |
| keyword | TEXT | 关键词内容 |
| priority | INTEGER | 优先级（越大越优先） |
| response_template | TEXT | 回复模板（可选） |
| is_active | BOOLEAN | 是否启用 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

**rule_type 枚举**:
- `greeting` - 打招呼规则
- `routing_prefilter` - 路由预过滤关键词
- `routing_target` - 路由目标配置

> **注意**: BYOD功能涉及员工岗位校验、资产领取状态查询、补贴历史年限等复杂API，暂不纳入快速规则管理，后续可在智能服务模块中实现。

### 3.2 管理API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/admin/quick-rules` | GET | 列表查询（支持筛选） |
| `/api/admin/quick-rules` | POST | 创建规则 |
| `/api/admin/quick-rules/{id}` | PUT | 更新规则 |
| `/api/admin/quick-rules/{id}` | DELETE | 删除规则 |
| `/api/admin/quick-rules/batch` | POST | 批量导入 |
| `/api/admin/quick-rules/refresh` | POST | 热刷新缓存 |
| `/api/admin/quick-rules/export` | GET | 批量导出（JSON/Excel） |
| `/api/admin/quick-rules/batch-delete` | POST | 批量删除（按ID列表） |
| `/api/admin/quick-rules/agent-update` | POST | 智能体专用更新（带置信度） |
| `/api/admin/quick-rules/audit-log` | GET | 规则修改审计日志 |
| `/api/admin/quick-rules/stats` | GET | 规则统计（命中率、误判率） |

### 3.3 前端管理页面

新建 `/quick-rules` 路由，包含3个子页面：

| 子页面 | 路径 | 功能 |
|--------|------|------|
| 打招呼配置 | `/quick-rules/greeting` | 管理打招呼关键词 |
| 路由关键词 | `/quick-rules/routing` | 管理业务路由关键词 |
| 路由目标 | `/quick-rules/targets` | 管理路由目标（kfid） |

### 3.4 规则加载服务

创建 `QuickRuleService`：
- 启动时加载所有规则到内存缓存
- 提供 `get_greeting_keywords()`、`get_byod_keywords()` 等方法
- 支持热刷新API，修改后刷新缓存

---

## 4. 验收标准

### 4.1 功能验收

| 编号 | 验收条件 | 测试方式 |
|------|---------|---------|
| AC1 | 可以在管理后台新增打招呼关键词 | 页面操作验证 |
| AC2 | 可以在管理后台修改业务路由关键词 | 页面操作验证 |
| AC3 | 管理后台快速回复规则页面不再展示顶部 3 张规则统计卡片，规则计数信息由标签导航上的徽标呈现 | 页面加载后检查标签导航及徽标 |
| AC4 | 修改规则后无需重启即可生效 | 修改后发送消息验证 |
| AC5 | 禁用规则后立即不生效 | 禁用后发送消息验证 |
| AC6 | 规则列表支持分页和搜索 | 页面操作验证 |
| AC7 | 底部统计卡片删除后，路由切换、筛选、批量删除、编辑、启停开关、分页、搜索功能完全保持不变 | 页面回归验证 |

### 4.2 性能验收

| 编号 | 验收条件 | 目标 |
|------|---------|------|
| PC1 | 规则加载时间 | < 100ms（缓存命中） |
| PC2 | 规则查询响应时间 | < 200ms |
| PC3 | 页面加载时间 | < 2s |

### 4.3 兼容性验收

| 编号 | 验收条件 |
|------|---------|
| CC1 | 与现有功能（欢迎与引导、快速回复）无冲突 |
| CC2 | 历史数据（硬编码规则）可迁移到数据库 |

---

## 5. Non-goals

- 不支持正则表达式匹配（仅支持简单关键词）
- 暂不提供规则版本历史回滚
- 暂不提供规则导入/导出功能

---

## 6. 技术约束

- 使用现有数据库PostgreSQL
- 前端使用现有Vue3 + Element Plus技术栈
- 规则匹配保持简单子串匹配
- 需要兼容现有硬编码规则的默认值

---

## 7. 风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 规则迁移可能影响线上服务 | 中 | 渐进式迁移，新旧页面并行 |
| 缓存与数据库不一致 | 中 | 热刷新机制 + 缓存过期策略 |
| 智能体自动修改规则引入风险 | 高 | 置信度阈值 + 人工审核 + 审计日志 |

---

## 8. 扩展规划（v2.0 智能体自动优化）

### 8.1 为什么需要智能体自动优化

随着业务消息量增长，仅靠人工维护规则会出现：
- 规则更新滞后：新业务术语、词汇无法及时识别
- 误判漏判：缺乏闭环反馈机制
- 优化效率低：人工分析大量日志成本高

### 8.2 双重维护模式

| 维度 | 人工快速维护 | 智能体自动优化 |
|------|------------|---------------|
| 触发方式 | 管理后台手动操作 | 定时任务触发 |
| 修改范围 | 单条/批量 | 批量 |
| 审核机制 | 人工审核 | 置信度阈值（>0.8 自动，<0.8 人工） |
| 回滚能力 | 手动 | 自动（命中率下降时回滚） |
| 审计追溯 | updated_at | 审计日志表 |

### 8.3 智能体专用接口

- `POST /api/admin/quick-rules/agent-update` - 智能体提交建议
  - 请求参数附带：置信度、修改原因、建议依据
  - 返回值：是否应用、警告信息
- `GET /api/admin/quick-rules/audit-log` - 审计日志
  - 记录：操作人/agent、修改前后值、置信度、修改时间
- `GET /api/admin/quick-rules/stats` - 规则统计
  - 命中率、误判率、规则有效性分析

### 8.4 批量导入导出

- `POST /api/admin/quick-rules/import` - 支持 JSON/Excel 批量导入
- `GET /api/admin/quick-rules/export` - 支持 JSON/Excel 批量导出
- 用途：备份、跨环境同步、智能体配置同步

### 8.5 期望效果

- 人工运维效率提升 50%
- 规则误判率下降 30%
- 业务响应速度提升（无需开发介入）

---

## 9. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 | 影响范围 |
|------|------|---------|-------|----------|----------|
| 2026-07-27 | v1.0 | 初始版本 | Simon | 快速回复规则后台管理需求建立 | 管理后台及快速规则服务 |
| 2026-07-27 | v1.1 | 新增第8章 扩展规划（智能体自动优化 + 导入导出） | Simon | 补充后续智能化扩展规划 | 产品规划与相关接口设计 |
| 2026-07-28 | v1.2 | 删除快速回复规则管理后台顶部 3 张重复统计卡片，仅保留标签导航；补充关联文档链接 | Simon | 信息冗余 | 管理后台 /quick-rules 页面 |