wecom_it_smart_desk/docs/02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md

技术方案 - 快速回复规则后台管理

关联PRD: 01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md 版本: v1.2 日期: 2026-07-27（初版） / 2026-07-28（v1.2 调整） 作者: Simon

---

1. 技术架构设计

1.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                     ITAgent 管理后台                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  /quick-rules          /quick-rules/greeting        │   │
│  │  /quick-rules/contacts /quick-rules/routing         │   │
│  │  /quick-rules/targets                               │   │
│  └─────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP API
┌────────────────────────┴────────────────────────────────────┐
│                     FastAPI 后端                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  QuickRuleService (规则加载 + 缓存)                  │   │
│  │  - get_greeting_keywords()                          │   │
│  │  - get_contact_keywords()                           │   │
│  │  - get_routing_keywords()                           │   │
│  │  - get_routing_targets()                            │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  QuickRuleCRUD API                                  │   │
│  │  - /api/admin/quick-rules (CRUD)                   │   │
│  │  - /api/admin/quick-rules/refresh (热刷新)           │   │
│  └─────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                   PostgreSQL 数据库                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  quick_rules 表                                      │   │
│  │  - id / rule_type / category / keyword / ...        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

1.2 模块设计

模块	职责	文件位置
QuickRule	数据库模型	app/models/quick_rule.py
quick_rules_api	管理API	app/api/admin/quick_rules.py
QuickRuleService	规则加载服务	app/services/quick_rule_service.py

---

2. 数据库设计

2.1 quick_rules 表

CREATE TABLE quick_rules (
    id SERIAL PRIMARY KEY,
    rule_type VARCHAR(50) NOT NULL,
    -- 枚举: greeting, routing_prefilter, routing_target
    category VARCHAR(50),
    -- 业务分类: IT服务, 行政, 人力资源, 财务, 法务, 行政-物业
    keyword TEXT NOT NULL,
    -- 关键词内容 或 名称
    priority INTEGER DEFAULT 0,
    -- 优先级，匹配时按优先级排序
    response_template TEXT,
    -- 回复模板（可选）
    extra_data JSONB,
    -- 扩展字段（用于kfid等配置）
    is_active BOOLEAN DEFAULT TRUE,
    -- 是否启用
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT uk_rule_type_keyword UNIQUE (rule_type, keyword)
);

CREATE INDEX idx_quick_rules_type_active ON quick_rules(rule_type, is_active);
CREATE INDEX idx_quick_rules_category ON quick_rules(category);

2.2 初始数据

-- 打招呼关键词（从 ai_handler.py 迁移）
INSERT INTO quick_rules (rule_type, keyword, priority, is_active) VALUES
('greeting', '你好', 10, true),
('greeting', '您好', 9, true),
('greeting', 'hi', 8, true),
('greeting', 'hello', 7, true),
('greeting', '在吗', 6, true),
('greeting', '在么', 5, true);

-- 路由预过滤关键词（从 routing_service.py 迁移）
INSERT INTO quick_rules (rule_type, category, keyword, priority, is_active) VALUES
('routing_prefilter', 'IT服务', '打印机', 10, true),
('routing_prefilter', 'IT服务', '打印', 9, true),
('routing_prefilter', 'IT服务', '电脑', 8, true),
('routing_prefilter', '行政', '复印机', 7, true),
('routing_prefilter', '人力资源', '考勤', 8, true),
('routing_prefilter', '人力资源', '入职', 7, true),
('routing_prefilter', '财务', '报销', 10, true),
('routing_prefilter', '财务', '发票', 9, true),
('routing_prefilter', '法务', '合同', 10, true);

-- 路由目标配置
INSERT INTO quick_rules (rule_type, category, keyword, extra_data, is_active) VALUES
('routing_target', '行政', '机票酒店前台', '{"service_name": "机票酒店前台", "description": "受理机票、酒店、快递、访客等", "url": "https://work.weixin.qq.com/nl/innerkfid/ikfCtcYBwAAV00zNJGfmuA0aG1c2qCDnQ"}', true),
('routing_target', '人力资源', '人力资源共享服务咨询', '{"service_name": "人力资源共享服务咨询", "description": "工牌/考勤/入离职/社保", "url": "https://work.weixin.qq.com/nl/innerkfid/ikfCtcYBwAAvSRL5i5b_Xia8vCmFc2gRw"}', true);

---

3. API 设计

3.1 管理接口

接口	方法	说明
/api/admin/quick-rules	GET	列表查询（支持 rule_type、category、keyword 筛选）
/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/stats	GET	统计各类型规则数量

3.2 请求/响应示例

GET /api/admin/quick-rules?rule_type=greeting&page=1&size=20

{
  "total": 6,
  "page": 1,
  "size": 20,
  "items": [
    {
      "id": 1,
      "rule_type": "greeting",
      "keyword": "你好",
      "priority": 10,
      "is_active": true,
      "created_at": "2026-07-27T10:00:00Z",
      "updated_at": "2026-07-27T10:00:00Z"
    }
  ]
}

POST /api/admin/quick-rules

{
  "rule_type": "routing_prefilter",
  "category": "IT服务",
  "keyword": "投影仪",
  "priority": 5,
  "is_active": true
}

---

4. 服务设计

4.1 QuickRuleService

class QuickRuleService:
    """规则加载服务 - 单例模式"""

    _cache: dict = {}

    @classmethod
    async def load_all(cls) -> None:
        """启动时加载所有规则到缓存"""
        rules = await db.query(QuickRule).where(QuickRule.is_active == True).all()
        cls._cache = {
            'greeting': [r.keyword for r in rules if r.rule_type == 'greeting'],
            'contact': [r.keyword for r in rules if r.rule_type == 'contact'],
            'routing_prefilter': {r.keyword: r.category for r in rules if r.rule_type == 'routing_prefilter'},
            'routing_target': {r.category: r.extra_data for r in rules if r.rule_type == 'routing_target'},
        }

    @classmethod
    async def refresh(cls) -> None:
        """热刷新缓存"""
        await cls.load_all()

    @classmethod
    def get_greeting_keywords(cls) -> list[str]:
        """获取打招呼关键词列表"""
        return cls._cache.get('greeting', [])

    @classmethod
    def get_contact_keywords(cls) -> list[str]:
        """获取联系人关键词列表"""
        return cls._cache.get('contact', [])

    @classmethod
    def get_routing_keywords(cls) -> dict[str, str]:
        """获取路由预过滤关键词 {keyword: category}"""
        return cls._cache.get('routing_prefilter', {})

    @classmethod
    def get_routing_targets(cls) -> dict[str, dict]:
        """获取路由目标 {category: {service_name, description, url}}"""
        return cls._cache.get('routing_target', {})

---

5. 代码改造计划

5.1 新增文件

文件	说明
app/models/quick_rule.py	QuickRule SQLAlchemy 模型
app/api/admin/quick_rules.py	CRUD API
app/services/quick_rule_service.py	规则加载服务
migrations/versions/xxx_quick_rules.py	Alembic 迁移脚本

5.2 改造文件

文件	改造内容
app/services/ai_handler.py	从 QuickRuleService 加载打招呼关键词
app/api/contacts.py	从 QuickRuleService 加载联系人配置
app/services/routing_service.py	从 QuickRuleService 加载路由配置

5.3 改造示例

改造前 (ai_handler.py):

_GREETING_KEYWORDS = ["你好", "您好", "hi", "hello", "在吗", "在么"]

def check_greeting(text: str) -> bool:
    return any(kw in text for kw in _GREETING_KEYWORDS)

改造后 (ai_handler.py):

from app.services.quick_rule_service import QuickRuleService

def check_greeting(text: str) -> bool:
    keywords = QuickRuleService.get_greeting_keywords()
    return any(kw in text for kw in keywords)

---

6. 前端实现

6.1 路由配置

// router/index.ts
{
  path: '/quick-rules',
  component: Layout,
  children: [
    { path: '', component: () => import('@/views/quick-rules/index.vue') },
    { path: 'greeting', component: () => import('@/views/quick-rules/greeting.vue') },
    { path: 'contacts', component: () => import('@/views/quick-rules/contacts.vue') },
    { path: 'routing', component: () => import('@/views/quick-rules/routing.vue') },
    { path: 'targets', component: () => import('@/views/quick-rules/targets.vue') },
  ]
}

6.2 页面结构

页面	组件
quick-rules/index.vue	规则管理主页（标签导航 + count 徽标 + 筛选区 + 规则表格）
quick-rules/greeting.vue	打招呼关键词管理
quick-rules/contacts.vue	业务联系人管理
quick-rules/routing.vue	路由关键词管理
quick-rules/targets.vue	路由目标配置

6.3 v1.2 UI 调整

移除 src/frontend-admin/src/views/quick-rules/index.vue 顶部 .stats-row 三张统计卡片；标签导航 .tab-bar 保留 count 徽标，作为规则数量的唯一页面展示来源。卡片原有点击行为仅调用 switchTab，标签导航已完整承担相同切换能力，因此删除不影响路由切换、筛选、批量删除、编辑、启停、分页和搜索。后端 getQuickRuleStats 接口保留；quick-rules/audit.vue 的 4 张审计统计卡片不在本次调整范围。

---

7. 部署与运维

7.1 部署顺序

1. 执行数据库迁移脚本（创建 quick_rules 表 + 初始数据）
2. 部署后端代码
3. 部署前端代码
4. 验证功能

7.2 监控指标

指标	说明
quick_rules_query_duration	规则查询耗时
quick_rules_cache_hit_rate	缓存命中率
quick_rules_api_requests	管理API请求数

7.3 回滚方案

• 数据库：保留迁移脚本，可降级表
• 代码：旧页面保留，新页面上线后观察一周再下线旧页面

---

8. 验收检查点

检查点	验证方式
数据库迁移成功	确认 quick_rules 表存在且数据正确
API 可用	curl 测试 CRUD 接口
规则加载正确	调用服务方法验证返回值
前端页面可访问	浏览器访问 /quick-rules
现有功能无影响	发送消息验证打招呼/路由仍正常工作
热刷新生效	修改规则后无需重启即可生效

---

9. v2.0 增量设计 — 智能体自动优化 + 导入导出

9.1 新增 API 端点

接口	方法	说明
/api/admin/quick-rules/import	POST	批量导入（JSON/Excel）
/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	规则统计（命中率、误判率）

9.2 智能体专用更新请求

POST /api/admin/quick-rules/agent-update

{
  "rule_type": "routing_prefilter",
  "category": "IT服务",
  "keyword": "投影仪",
  "priority": 5,
  "confidence": 0.92,
  "reason": "误判率分析：最近30天5条'投影仪'相关消息被误判为闲聊",
  "agent_id": "rule_optimizer_v1",
  "execution_id": "exec_2026-07-27_001"
}

置信度阈值：

• ≥ 0.85：自动应用并记录审计
• 0.5 ~ 0.85：进入待审核队列
• < 0.5：拒绝（不入库）

9.3 批量导入导出

导入格式（JSON）：

{
  "rules": [
    {
      "rule_type": "greeting",
      "keyword": "你好",
      "priority": 10,
      "is_active": true
    }
  ],
  "mode": "skip_duplicates"  // skip_duplicates | overwrite | fail
}

导出格式：支持 JSON 和 Excel 两种格式

9.4 审计日志表

CREATE TABLE quick_rule_audit_log (
    id SERIAL PRIMARY KEY,
    rule_id INTEGER,
    rule_type VARCHAR(50),
    action VARCHAR(20),  -- create/update/delete/batch
    actor_type VARCHAR(20),  -- human/agent
    actor_id VARCHAR(100),  -- agent_id 或 坐席ID
    old_value JSONB,
    new_value JSONB,
    confidence FLOAT,
    reason TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

9.5 规则统计

GET /api/admin/quick-rules/stats

{
  "total_rules": 45,
  "hit_rate": 0.78,
  "false_positive_rate": 0.05,
  "active_rules": 42,
  "by_type": {
    "greeting": 6,
    "routing_prefilter": 25,
    "routing_target": 14
  },
  "top_unkonwn_keywords": ["云盘权限", "VPN", "VPN登录"]
}

9.6 实施步骤

步骤	内容	预估时间
1	批量导入/导出 API	1h
2	批量删除 API	0.5h
3	智能体专用 API（带置信度）	1.5h
4	审计日志表 + 记录逻辑	1.5h
5	规则统计 API	1h
6	前端导入/导出按钮	1h
7	智能体调用脚本示例	0.5h
总计		7h

---

10. 变更记录

日期	版本	变更内容	变更人	变更原因	影响范围
2026-07-27	v1.0	初始版本	Simon	快速回复规则后台管理技术设计建立	后端、数据库及管理后台
2026-07-27	v1.1	新增第9章 v2.0 增量设计（智能体自动优化 + 导入导出）	Simon	补充智能体扩展设计	API、审计及导入导出
2026-07-28	v1.2	移除 index.vue 顶部 .stats-row 三张重复统计卡片，保留 .tab-bar 的 count 徽标；统计接口与审计页卡片保持不变	Simon	页面信息冗余	管理后台 /quick-rules 页面