simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ddebbe61a5f1512a66c39cf1cc2f0f0f71826365
wecom_it_smart_desk/docs/ARCHITECTURE-admin.md
T

37 KiB
Raw Blame History

IT智能服务台 — 管理后台架构设计文档

文档版本: v1.0 架构师: 高见远 (Bob) 日期: 2026-07-15 关联文档: docs/PRD-admin.md、docs/ARCHITECTURE.md

目录

  1. 实现方案与框架选型
  2. 文件列表及相对路径
  3. 数据模型
  4. API 接口设计
  5. 程序调用流程
  6. 任务列表
  7. 依赖包列表
  8. 共享知识
  9. 待明确事项

1. 实现方案与框架选型

1.1 核心技术挑战

# 挑战 解决方案
C1 管理后台 RBAC 权限校验 复用坐席端 Redis token 机制，新增 require_admin 依赖函数，校验 Agent.role == 'admin'
C2 配置变更历史追踪 新建 config_change_logs 表，每次 PUT 配置时记录 {key, old, new, who, when}
C3 快速回复审核状态机 QuickReplyTemplate 新增 status/version/submitted_by 字段，状态流转: draft→pending_review→approved/rejected
C4 坐席端快速回复可见性逻辑 坐席端 GET /api/quick-replies 增加状态筛选: 返回 approved + 自己的 pending_review
C5 深色科技风 UI 主题 全局 CSS 变量覆盖 Element Plus 默认样式，使用 Tailwind CSS 辅助布局
C6 前端项目隔离 新建 frontend-admin/ 独立项目，部署路径 /itadmin/，与坐席端 /itagent/ 并列

1.2 技术栈确认

前端（新建 frontend-admin/）

项目 版本 用途
Vue 3 ^3.4.0 UI 框架，Composition API
TypeScript ^5.5.0 类型安全
Vite ^5.3.0 构建工具
Element Plus ^2.7.0 UI 组件库
Pinia ^2.1.0 状态管理
Tailwind CSS ^3.4.0 工具类样式
Vue Router ^4.3.0 路由管理
Axios ^1.7.0 HTTP 客户端
@element-plus/icons-vue ^2.3.0 图标库

后端（扩展现有 FastAPI）

项目 版本 用途
FastAPI 现有 Web 框架
SQLAlchemy 2.0 现有 ORM（async）
Pydantic 现有 数据校验
Alembic 现有 数据库迁移

1.3 架构模式

  • 前端: SPA + 侧边栏导航布局，Pinia 状态管理，Axios 统一拦截
  • 后端: 增量式扩展，新建 admin.py 路由模块 + admin_service.py 服务层
  • 认证: 复用坐席端 Redis token，新增 admin 角色校验中间件

2. 文件列表及相对路径

2.1 前端（frontend-admin/，新建项目）

frontend-admin/
├── index.html                              # HTML 入口
├── package.json                             # 依赖声明
├── tsconfig.json                            # TypeScript 配置
├── tsconfig.node.json                       # Node 端 TS 配置
├── vite.config.ts                           # Vite 配置（base: /itadmin/）
├── tailwind.config.js                       # Tailwind CSS 配置
├── postcss.config.js                        # PostCSS 配置
├── env.d.ts                                 # 环境类型声明
├── src/
│   ├── main.ts                              # Vue 应用入口
│   ├── App.vue                              # 根组件
│   ├── api/
│   │   └── index.ts                         # Axios 实例 + 拦截器（admin_token）
│   ├── api/
│   │   ├── admin.ts                         # 管理后台 API 调用函数
│   ├── router/
│   │   └── index.ts                         # 路由配置（含 admin 守卫）
│   ├── stores/
│   │   ├── admin.ts                         # 管理员状态 Store（登录/权限）
│   │   ├── config.ts                        # 配置项 Store
│   │   ├── agent.ts                         # 坐席管理 Store
│   │   └── quickReply.ts                    # 快速回复管理 Store
│   ├── layouts/
│   │   └── AdminLayout.vue                  # 管理后台布局（侧边栏+面包屑+内容区）
│   ├── views/
│   │   ├── Login.vue                        # 管理员登录页
│   │   ├── Dashboard.vue                    # 运营总览仪表盘
│   │   ├── Configs.vue                       # 功能开关/参数管理
│   │   ├── Agents.vue                        # 坐席人员管理
│   │   ├── Integrations.vue                  # 外部系统集成配置
│   │   ├── QuickReplies.vue                  # 快速回复管理
│   │   ├── AssignmentMode.vue                # 消息分配模式（占位）
│   │   ├── Monitor.vue                       # 会话监控（Demo预览）
│   │   ├── Flowcharts.vue                    # 排查流程图（占位）
│   │   └── Placeholder.vue                   # 通用占位页模板
│   ├── components/
│   │   ├── Sidebar.vue                      # 侧边栏导航组件
│   │   ├── Breadcrumb.vue                   # 面包屑导航组件
│   │   ├── StatCard.vue                     # 统计卡片组件
│   │   ├── ConfigGroup.vue                  # 配置分组卡片组件
│   │   ├── AgentTable.vue                   # 坐席列表表格组件
│   │   ├── IntegrationCard.vue              # 集成系统卡片组件
│   │   ├── QuickReplyCard.vue               # 快速回复卡片组件
│   │   └── SearchBox.vue                    # 全局搜索组件
│   ├── types/
│   │   └── index.ts                         # TypeScript 类型定义
│   └── styles/
│       └── global.css                       # 深色科技风全局样式 + CSS 变量

2.2 后端（扩展现有 backend/）

backend/
├── app/
│   ├── models/
│   │   ├── agent.py                         # 修改：新增 role, skill_tags 字段
│   │   ├── quick_reply_template.py          # 修改：新增 status, version, submitted_by 字段
│   │   ├── config_change_log.py             # 新增：配置变更日志模型
│   │   └── __init__.py                      # 修改：导入新模型
│   ├── schemas/
│   │   ├── agent.py                         # 修改：新增 role, skill_tags 字段到响应
│   │   ├── quick_reply.py                   # 修改：新增 status, version, submitted_by
│   │   └── admin.py                         # 新增：管理后台专用 Schema
│   ├── api/
│   │   ├── admin.py                         # 新增：管理后台路由
│   │   ├── router.py                        # 修改：注册 admin_router
│   │   └── quick_replies.py                 # 修改：增加 status 筛选逻辑
│   └── services/
│       └── admin_service.py                 # 新增：管理后台业务逻辑
├── alembic/
│   └── versions/
│       └── 006_admin_extension.py           # 新增：管理后台数据库迁移

2.3 文件变更标注

标记 含义
新增 全新创建的文件
修改 在现有文件中添加/修改内容

3. 数据模型

3.1 新增模型：ConfigChangeLog

# backend/app/models/config_change_log.py

import uuid
from datetime import datetime

from sqlalchemy import DateTime, String, Text
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class ConfigChangeLog(Base):
    """配置变更日志模型 — 对应 config_change_logs 表。

    记录每次配置项的变更历史，包含变更前后的值、操作人和时间。

    Attributes:
        id: 日志唯一标识（UUID）
        config_key: 变更的配置键
        old_value: 变更前的值
        new_value: 变更后的值
        changed_by: 变更操作人（agent_id）
        changed_at: 变更时间
    """

    __tablename__ = "config_change_logs"

    id: Mapped[str] = mapped_column(
        String(36),
        primary_key=True,
        default=lambda: str(uuid.uuid4()),
    )

    config_key: Mapped[str] = mapped_column(
        String(128),
        nullable=False,
        comment="配置键",
    )

    old_value: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        default="",
        comment="变更前的值",
    )

    new_value: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        default="",
        comment="变更后的值",
    )

    changed_by: Mapped[str] = mapped_column(
        String(36),
        nullable=False,
        comment="变更操作人 agent_id",
    )

    changed_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        default=datetime.now,
        comment="变更时间",
    )

    __table_args__ = (
        Index("idx_ccl_config_key", "config_key"),
        Index("idx_ccl_changed_at", "changed_at"),
    )

    def __repr__(self) -> str:
        return f"<ConfigChangeLog(key={self.config_key}, by={self.changed_by})>"

3.2 扩展模型：Agent（新增字段）

# 在 backend/app/models/agent.py 中新增字段：

role: Mapped[str] = mapped_column(
    String(20),
    nullable=False,
    default="agent",
    comment="角色：admin=组长, agent=坐席",
)

skill_tags: Mapped[list] = mapped_column(
    JSON,
    nullable=False,
    default=list,
    comment="技能标签列表（电脑/软件/外设/网络/安全/资产/其他）",
)

3.3 扩展模型：QuickReplyTemplate（新增字段）

# 在 backend/app/models/quick_reply_template.py 中新增字段：

status: Mapped[str] = mapped_column(
    String(20),
    nullable=False,
    default="approved",
    comment="状态：draft/pending_review/approved/rejected",
)

version: Mapped[int] = mapped_column(
    Integer,
    nullable=False,
    default=1,
    comment="版本号，每次审核通过后 +1",
)

submitted_by: Mapped[str] = mapped_column(
    String(36),
    nullable=True,
    default=None,
    comment="提交人 agent_id",
)

3.4 类图

classDiagram
    class Agent {
        +str id
        +str user_id
        +str name
        +str status
        +str role
        +list skill_tags
        +int current_load
        +int max_load
        +datetime created_at
        +datetime updated_at
    }

    class SystemConfig {
        +str id
        +str config_key
        +str config_value
        +str description
        +datetime updated_at
    }

    class ConfigChangeLog {
        +str id
        +str config_key
        +str old_value
        +str new_value
        +str changed_by
        +datetime changed_at
    }

    class QuickReplyTemplate {
        +str id
        +str category
        +str title
        +str content
        +list variables
        +int sort_order
        +str status
        +int version
        +str submitted_by
        +datetime created_at
        +datetime updated_at
    }

    class Conversation {
        +str id
        +str employee_id
        +str employee_name
        +str status
        +int urgency_score
        +str assigned_agent_id
        +datetime created_at
    }

    ConfigChangeLog --> SystemConfig : tracks changes to
    ConfigChangeLog --> Agent : changed_by
    QuickReplyTemplate --> Agent : submitted_by
    Conversation --> Agent : assigned_agent_id

4. API 接口设计

4.1 权限校验依赖

# backend/app/api/admin.py 中定义

from app.api.agents import get_current_agent

async def require_admin(
    agent: Agent = Depends(get_current_agent),
) -> Agent:
    """管理后台权限校验：仅 role='admin' 可访问。"""
    if agent.role != "admin":
        raise AppException(1004, "无管理权限")
    return agent

4.2 API 端点列表

所有管理后台 API 统一前缀 /api/admin/。

4.2.1 运营总览仪表盘

GET /api/admin/dashboard/overview

  • 权限: admin
  • 描述: 获取仪表盘统计数据
  • 响应:
{
  "code": 0,
  "data": {
    "online_agents": 3,
    "today_conversations": 12,
    "avg_response_time": "—",
    "ai_hit_rate": "—",
    "pending_reviews": 2,
    "system_alerts": [],
    "integrations_health": [
      {"system": "Dify AI", "status": "connected"},
      {"system": "RAGFlow", "status": "partial"}
    ]
  }
}

4.2.2 功能开关/参数管理

GET /api/admin/configs

  • 权限: admin
  • 描述: 获取全部配置项（按功能分组）
  • 响应:
{
  "code": 0,
  "data": {
    "groups": [
      {
        "name": "AI 对话引擎",
        "key_prefix": "ai_",
        "items": [
          {
            "key": "ai_auto_reply",
            "value": "true",
            "description": "AI自动回复开关",
            "value_type": "boolean"
          },
          {
            "key": "intervene_round_threshold",
            "value": "3",
            "description": "AI介入轮次阈值",
            "value_type": "number"
          },
          {
            "key": "hand_raise_keywords",
            "value": "[\"转人工\",\"人工\",\"人工服务\"]",
            "description": "举手关键词列表",
            "value_type": "json_array"
          }
        ]
      },
      {
        "name": "应急模式",
        "key_prefix": "emergency_",
        "items": [
          {
            "key": "emergency_mode",
            "value": "false",
            "description": "应急模式开关",
            "value_type": "boolean"
          }
        ]
      }
    ]
  }
}

PUT /api/admin/configs/{key}

  • 权限: admin
  • 描述: 更新单个配置项（同时记录变更日志）
  • 请求体:
{
  "value": "true"
}
  • 响应:
{
  "code": 0,
  "data": {
    "key": "emergency_mode",
    "old_value": "false",
    "new_value": "true",
    "changed_at": "2026-07-15T10:30:00Z"
  }
}

GET /api/admin/configs/{key}/history

  • 权限: admin
  • 描述: 获取指定配置项的变更历史
  • 查询参数: limit (默认20)
  • 响应:
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "uuid",
        "config_key": "emergency_mode",
        "old_value": "false",
        "new_value": "true",
        "changed_by": "agent_id",
        "changed_by_name": "宋献",
        "changed_at": "2026-07-15T10:30:00Z"
      }
    ]
  }
}

4.2.3 坐席人员管理

GET /api/admin/agents

  • 权限: admin
  • 描述: 获取坐席列表（管理视图，含角色/技能标签）
  • 查询参数: status (可选，筛选 online/offline/busy)
  • 响应:
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "uuid",
        "user_id": "SongXian",
        "name": "宋献",
        "status": "online",
        "role": "admin",
        "skill_tags": ["电脑", "网络", "软件"],
        "current_load": 2,
        "max_load": 5,
        "today_resolved": 8,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-07-15T08:00:00Z"
      }
    ]
  }
}

POST /api/admin/agents

  • 权限: admin
  • 描述: 添加坐席
  • 请求体:
{
  "user_id": "WangLi",
  "name": "王丽",
  "role": "agent",
  "skill_tags": ["外设", "安全"],
  "max_load": 5
}
  • 响应:
{
  "code": 0,
  "data": {
    "id": "uuid",
    "user_id": "WangLi",
    "name": "王丽",
    "role": "agent",
    "skill_tags": ["外设", "安全"],
    "status": "offline",
    "current_load": 0,
    "max_load": 5
  }
}

PUT /api/admin/agents/{id}

  • 权限: admin
  • 描述: 编辑坐席（角色/技能标签/负载上限）
  • 请求体:
{
  "role": "agent",
  "skill_tags": ["电脑", "网络"],
  "max_load": 8
}
  • 响应:
{
  "code": 0,
  "data": {
    "id": "uuid",
    "role": "agent",
    "skill_tags": ["电脑", "网络"],
    "max_load": 8
  }
}

DELETE /api/admin/agents/{id}

  • 权限: admin
  • 描述: 移除坐席
  • 响应:
{
  "code": 0,
  "data": null,
  "message": "坐席已移除"
}

4.2.4 外部系统集成配置

GET /api/admin/integrations

  • 权限: admin
  • 描述: 获取集成系统列表及配置状态
  • 响应:
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "dify",
        "name": "Dify AI",
        "status": "connected",
        "configurable": true,
        "config": {
          "api_url": "https://api.dify.ai/v1",
          "api_key_set": true
        }
      },
      {
        "id": "ragflow",
        "name": "RAGFlow",
        "status": "partial",
        "configurable": true,
        "config": {
          "api_url": "",
          "api_key_set": false
        }
      },
      {
        "id": "data_platform",
        "name": "数据平台",
        "status": "disconnected",
        "configurable": false,
        "config": null
      },
      {
        "id": "beisen",
        "name": "北森 eHR",
        "status": "disconnected",
        "configurable": false,
        "config": null
      },
      {
        "id": "huorong",
        "name": "火绒安全",
        "status": "disconnected",
        "configurable": false,
        "config": null
      },
      {
        "id": "liansoft",
        "name": "联软安全",
        "status": "pending",
        "configurable": false,
        "config": null
      }
    ]
  }
}

PUT /api/admin/integrations/{id}

  • 权限: admin
  • 描述: 更新集成配置（仅 dify/ragflow 可用，配置存 system_configs 表，键前缀 integration_）
  • 请求体:
{
  "api_url": "https://api.dify.ai/v1",
  "api_key": "app-xxxxx"
}
  • 响应:
{
  "code": 0,
  "data": {
    "id": "dify",
    "name": "Dify AI",
    "status": "connected",
    "config": {
      "api_url": "https://api.dify.ai/v1",
      "api_key_set": true
    }
  }
}

4.2.5 快速回复管理

GET /api/admin/quick-replies/pending

  • 权限: admin
  • 描述: 获取待审核模板列表
  • 查询参数: category (可选)
  • 响应:
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "uuid",
        "category": "电脑",
        "title": "密码重置引导",
        "content": "您好{employee_name}...",
        "variables": ["employee_name"],
        "status": "pending_review",
        "version": 1,
        "submitted_by": "agent_id",
        "submitted_by_name": "王丽",
        "sort_order": 0,
        "created_at": "2026-07-14T10:00:00Z",
        "updated_at": "2026-07-14T10:00:00Z"
      }
    ]
  }
}

PUT /api/admin/quick-replies/{id}/review

  • 权限: admin
  • 描述: 审核快速回复模板（通过/驳回）
  • 请求体:
{
  "action": "approve",
  "reason": ""
}

或:

{
  "action": "reject",
  "reason": "内容需要更具体的操作步骤"
}
  • 响应:
{
  "code": 0,
  "data": {
    "id": "uuid",
    "status": "approved",
    "version": 2
  }
}

4.2.6 消息分配模式

GET /api/admin/assignment-mode

  • 权限: admin
  • 描述: 获取当前分配模式
  • 响应:
{
  "code": 0,
  "data": {
    "current_mode": "manual",
    "modes": [
      {"id": "manual", "name": "手动接单", "enabled": true, "locked": false},
      {"id": "round_robin", "name": "轮询分配", "enabled": false, "locked": true, "unlock_at": "阶段二"},
      {"id": "least_active", "name": "最少活跃优先", "enabled": false, "locked": true, "unlock_at": "阶段二"},
      {"id": "weighted", "name": "加权比例分配", "enabled": false, "locked": true, "unlock_at": "阶段三"},
      {"id": "skill_match", "name": "技能匹配分配", "enabled": false, "locked": true, "unlock_at": "阶段三"},
      {"id": "priority_queue", "name": "优先队列", "enabled": false, "locked": true, "unlock_at": "阶段三"}
    ]
  }
}

PUT /api/admin/assignment-mode

  • 权限: admin
  • 描述: 切换分配模式（阶段一仅允许手动接单）
  • 请求体:
{
  "mode": "manual"
}

4.2.7 会话监控

GET /api/admin/monitor/sessions

  • 权限: admin
  • 描述: 获取实时会话列表（Demo预览）
  • 查询参数: status (可选，默认非 resolved)
  • 响应:
{
  "code": 0,
  "data": {
    "stats": {
      "in_progress": 3,
      "queued": 1,
      "resolved_today": 8,
      "alerts": 0
    },
    "items": [
      {
        "id": "uuid",
        "employee_name": "张三",
        "status": "serving",
        "assigned_agent_name": "宋献",
        "urgency_score": 3,
        "created_at": "2026-07-15T09:00:00Z",
        "last_message_summary": "我的电脑无法开机"
      }
    ]
  }
}

4.2.8 全局搜索

GET /api/admin/search?q=关键词

  • 权限: admin
  • 描述: 搜索配置项、坐席、快速回复
  • 响应:
{
  "code": 0,
  "data": {
    "items": [
      {"type": "config", "id": "emergency_mode", "name": "应急模式", "route": "/admin/configs"},
      {"type": "agent", "id": "uuid", "name": "宋献", "route": "/admin/agents"},
      {"type": "quick_reply", "id": "uuid", "name": "密码重置引导", "route": "/admin/quick-replies"}
    ]
  }
}

5. 程序调用流程

5.1 管理员登录流程

sequenceDiagram
    participant U as 管理员(组长)
    participant FE as frontend-admin
    participant API as /api/agents/login
    participant Redis as Redis
    participant DB as PostgreSQL

    U->>FE: 输入 user_id + name 登录
    FE->>API: POST /api/agents/login
    API->>DB: 查询 Agent (user_id)
    DB-->>API: Agent 记录（含 role 字段）
    API->>Redis: 存储 token → user_id 映射
    API-->>FE: {agent_info, token, role: "admin"}
    FE->>FE: 检查 role === "admin"
    FE->>FE: 存储 admin_token 到 localStorage
    FE->>FE: 跳转到 /admin/dashboard

5.2 配置变更流程

sequenceDiagram
    participant U as 管理员
    participant FE as frontend-admin
    participant API as /api/admin/configs/{key}
    participant SVC as admin_service
    participant DB as PostgreSQL

    U->>FE: 切换应急模式开关
    FE->>API: PUT /api/admin/configs/emergency_mode
    API->>API: require_admin 校验权限
    API->>SVC: update_config(key, value, agent_id)
    SVC->>DB: SELECT SystemConfig WHERE key=emergency_mode
    DB-->>SVC: 当前值 "false"
    SVC->>DB: INSERT ConfigChangeLog(old="false", new="true", by=agent_id)
    SVC->>DB: UPDATE SystemConfig SET value="true"
    DB-->>SVC: 更新成功
    SVC-->>API: {key, old_value, new_value, changed_at}
    API-->>FE: 返回变更结果
    FE->>FE: 显示变更成功提示

5.3 快速回复审核流程

sequenceDiagram
    participant A as 坐席(王丽)
    participant AG as /api/quick-replies
    participant U as 管理员(宋献)
    participant ADM as /api/admin/quick-replies
    participant DB as PostgreSQL

    A->>AG: POST /api/quick-replies (创建模板, status=draft)
    A->>AG: PUT /api/quick-replies/{id} (提交审核, status→pending_review)
    AG->>DB: UPDATE QuickReplyTemplate SET status='pending_review', submitted_by='wang_li'

    U->>ADM: GET /api/admin/quick-replies/pending
    ADM->>DB: SELECT WHERE status='pending_review'
    DB-->>ADM: 待审核列表
    ADM-->>U: 显示待审核模板

    U->>ADM: PUT /api/admin/quick-replies/{id}/review (action=approve)
    ADM->>DB: UPDATE SET status='approved', version=version+1
    DB-->>ADM: 更新成功

    A->>AG: GET /api/quick-replies (获取可见模板)
    AG->>DB: SELECT WHERE status='approved' OR (status='pending_review' AND submitted_by=自己)
    DB-->>AG: 全员可见(approved) + 仅自己(pending_review)

5.4 坐席管理 CRUD 流程

sequenceDiagram
    participant U as 管理员
    participant FE as frontend-admin
    participant API as /api/admin/agents
    participant DB as PostgreSQL

    U->>FE: 进入坐席管理页面
    FE->>API: GET /api/admin/agents?status=online
    API->>API: require_admin 校验
    API->>DB: SELECT Agent (含 role, skill_tags)
    DB-->>API: 坐席列表
    API-->>FE: 返回坐席数据

    U->>FE: 编辑坐席（修改技能标签）
    FE->>API: PUT /api/admin/agents/{id}
    API->>API: require_admin 校验
    API->>DB: UPDATE Agent SET skill_tags=['电脑','网络']
    DB-->>API: 更新成功
    API-->>FE: 返回更新后的坐席信息

6. 任务列表

T01: 项目基础设施

任务名称: 项目基础设施 + 数据库迁移 优先级: P0 依赖: 无 涉及文件:

文件 操作 职责
frontend-admin/package.json 新增 前端依赖声明
frontend-admin/vite.config.ts 新增 Vite 构建配置（base: /itadmin/）
frontend-admin/tsconfig.json 新增 TypeScript 配置
frontend-admin/tsconfig.node.json 新增 Node TS 配置
frontend-admin/tailwind.config.js 新增 Tailwind CSS 配置
frontend-admin/postcss.config.js 新增 PostCSS 配置
frontend-admin/index.html 新增 HTML 入口
frontend-admin/env.d.ts 新增 环境类型声明
frontend-admin/src/main.ts 新增 Vue 应用入口
frontend-admin/src/App.vue 新增 根组件
frontend-admin/src/styles/global.css 新增 深色科技风全局样式
frontend-admin/src/api/index.ts 新增 Axios 实例（admin_token）
frontend-admin/src/types/index.ts 新增 TypeScript 类型定义
backend/app/models/config_change_log.py 新增 配置变更日志模型
backend/app/models/agent.py 修改 新增 role, skill_tags 字段
backend/app/models/quick_reply_template.py 修改 新增 status, version, submitted_by 字段
backend/app/models/__init__.py 修改 导入新模型
backend/app/schemas/agent.py 修改 新增 role, skill_tags 到响应
backend/app/schemas/quick_reply.py 修改 新增 status, version, submitted_by
backend/app/schemas/admin.py 新增 管理后台专用 Schema
backend/alembic/versions/006_admin_extension.py 新增 数据库迁移脚本

具体工作:

  1. 初始化 frontend-admin/ 项目（Vue 3 + TS + Vite + Element Plus + Pinia + Tailwind CSS）
  2. 配置 Vite（base: /itadmin/、API 代理到 localhost:8000）
  3. 创建 Axios 实例（使用 admin_token 而非 agent_token）
  4. 定义全局 CSS 变量（深色科技风，与 PRD §10.2 对齐）
  5. 后端新增 ConfigChangeLog 模型
  6. 后端扩展 Agent 模型（新增 role, skill_tags）
  7. 后端扩展 QuickReplyTemplate 模型（新增 status, version, submitted_by）
  8. 后端新增 admin.py Schema（请求/响应数据结构）
  9. 创建 Alembic 迁移脚本 006_admin_extension.py

T02: 后端管理 API + 权限中间件

任务名称: 后端管理 API 路由 + 权限校验 + 业务逻辑 优先级: P0 依赖: T01 涉及文件:

文件 操作 职责
backend/app/api/admin.py 新增 管理后台全部路由（7组 API）
backend/app/services/admin_service.py 新增 管理后台业务逻辑层
backend/app/api/router.py 修改 注册 admin_router
backend/app/api/quick_replies.py 修改 增加 status 筛选逻辑（坐席端可见性）

具体工作:

  1. 实现 require_admin 依赖函数（校验 token + role=admin）
  2. 实现 /api/admin/dashboard/overview — 仪表盘聚合查询
  3. 实现 /api/admin/configs — 配置项分组读取
  4. 实现 /api/admin/configs/{key} PUT — 配置更新 + 变更日志写入
  5. 实现 /api/admin/configs/{key}/history — 配置变更历史查询
  6. 实现 /api/admin/agents CRUD — 坐席管理（含 role/skill_tags 编辑）
  7. 实现 /api/admin/integrations — 集成系统配置（复用 SystemConfig，键前缀 integration_）
  8. 实现 /api/admin/quick-replies/pending + /{id}/review — 审核流程
  9. 实现 /api/admin/assignment-mode — 分配模式读写
  10. 实现 /api/admin/monitor/sessions — 会话监控查询
  11. 实现 /api/admin/search — 全局搜索
  12. 修改坐席端 GET /api/quick-replies 增加 status 筛选（approved + 自己的 pending_review）
  13. 在 router.py 中注册 admin_router

T03: 前端布局框架 + P0 页面

任务名称: 前端布局框架 + P0 核心页面（仪表盘/配置/坐席/集成） 优先级: P0 依赖: T01 涉及文件:

文件 操作 职责
frontend-admin/src/router/index.ts 新增 路由配置（含 admin 守卫）
frontend-admin/src/stores/admin.ts 新增 管理员状态 Store
frontend-admin/src/stores/config.ts 新增 配置项 Store
frontend-admin/src/stores/agent.ts 新增 坐席管理 Store
frontend-admin/src/api/admin.ts 新增 管理后台 API 调用函数
frontend-admin/src/layouts/AdminLayout.vue 新增 管理后台布局
frontend-admin/src/components/Sidebar.vue 新增 侧边栏导航
frontend-admin/src/components/Breadcrumb.vue 新增 面包屑
frontend-admin/src/components/StatCard.vue 新增 统计卡片
frontend-admin/src/components/ConfigGroup.vue 新增 配置分组卡片
frontend-admin/src/components/AgentTable.vue 新增 坐席列表表格
frontend-admin/src/components/IntegrationCard.vue 新增 集成系统卡片
frontend-admin/src/components/SearchBox.vue 新增 全局搜索
frontend-admin/src/views/Login.vue 新增 管理员登录页
frontend-admin/src/views/Dashboard.vue 新增 运营总览仪表盘
frontend-admin/src/views/Configs.vue 新增 功能开关/参数管理
frontend-admin/src/views/Agents.vue 新增 坐席人员管理
frontend-admin/src/views/Integrations.vue 新增 外部系统集成配置

具体工作:

  1. 实现路由配置（全部 10 个路由 + 路由守卫校验 admin 角色）
  2. 实现管理员 Store（登录/登出/权限校验，使用 admin_token）
  3. 实现 AdminLayout（深色侧边栏 + 面包屑 + 内容区）
  4. 实现 Sidebar（导航分组 + 优先级标签 + 灰化占位）
  5. 实现登录页（复用坐席登录 API，检查 role=admin）
  6. 实现仪表盘页面（4 个统计卡片 + 待处理事项 + 系统健康状态）
  7. 实现功能开关页面（6 组配置卡片 + toggle 开关 + JSON 编辑对话框）
  8. 实现坐席管理页面（表格列表 + 状态筛选 + 编辑角色/技能标签对话框）
  9. 实现系统集成页面（6 个系统卡片 + Dify/RAGFlow 配置表单）
  10. 实现全局搜索组件

T04: P1 页面 + 快速回复管理 + 占位页

任务名称: P1 运营管理页面（快速回复/分配模式/会话监控/排查流程图）+ 占位页 优先级: P1 依赖: T03 涉及文件:

文件 操作 职责
frontend-admin/src/stores/quickReply.ts 新增 快速回复管理 Store
frontend-admin/src/components/QuickReplyCard.vue 新增 快速回复卡片组件
frontend-admin/src/views/QuickReplies.vue 新增 快速回复管理页面
frontend-admin/src/views/AssignmentMode.vue 新增 消息分配模式（占位）
frontend-admin/src/views/Monitor.vue 新增 会话监控（Demo预览）
frontend-admin/src/views/Flowcharts.vue 新增 排查流程图（占位）
frontend-admin/src/views/Placeholder.vue 新增 通用占位页模板

具体工作:

  1. 实现快速回复管理页面（卡片列表 + 分类筛选 + 审核操作按钮）
  2. 实现审核流程交互（通过/驳回对话框，驳回需填原因）
  3. 实现分配模式页面（6 个模式卡片，手动接单可选，其余灰化+锁图标）
  4. 实现会话监控页面（统计卡片 + 实时会话表格，标注 Demo 预览）
  5. 实现排查流程图页面（模板列表 + 灰化的导入导出按钮）
  6. 实现通用占位页模板（居中"开发中"提示 + 返回首页按钮）

T05: 集成测试 + 样式打磨 + 部署配置

任务名称: 前后端集成联调 + 深色主题样式打磨 + 部署配置 优先级: P1 依赖: T02, T03, T04 涉及文件:

文件 操作 职责
frontend-admin/src/styles/global.css 修改 深色主题样式微调
frontend-admin/src/layouts/AdminLayout.vue 修改 响应式适配
frontend-admin/src/components/*.vue 修改 组件样式统一
frontend-admin/dist/ 生成 构建产物
Nginx 配置 修改 新增 /itadmin/ 路由

具体工作:

  1. 前后端联调：逐一测试所有 API 端点
  2. 深色科技风主题一致性检查（所有页面、组件、对话框）
  3. Element Plus 组件深色样式覆盖（表格、表单、对话框、分页等）
  4. 响应式布局调整（窗口缩放、侧边栏折叠）
  5. 前端构建 npm run build，确认 dist 产物可用
  6. Nginx 配置更新（新增 /itadmin/ 路由）
  7. 种子数据更新（宋献设为 admin 角色，现有快速回复设为 approved 状态）

任务依赖图

graph TD
    T01[T01: 项目基础设施+DB迁移] --> T02[T02: 后端管理API+权限]
    T01 --> T03[T03: 前端布局+P0页面]
    T03 --> T04[T04: P1页面+快速回复+占位]
    T02 --> T05[T05: 集成测试+样式+部署]
    T04 --> T05

7. 依赖包列表

7.1 前端新增（frontend-admin/package.json）

{
  "dependencies": {
    "vue": "^3.4.0",
    "vue-router": "^4.3.0",
    "pinia": "^2.1.0",
    "element-plus": "^2.7.0",
    "@element-plus/icons-vue": "^2.3.0",
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "typescript": "^5.5.0",
    "vite": "^5.3.0",
    "vue-tsc": "^2.0.0",
    "tailwindcss": "^3.4.0",
    "postcss": "^8.4.0",
    "autoprefixer": "^10.4.0"
  }
}

7.2 后端新增

无新增 pip 依赖。所有后端功能基于现有 FastAPI + SQLAlchemy + Pydantic + Redis 实现。

8. 共享知识

8.1 API 响应格式

所有 API 遵循统一响应格式：

// 成功
{"code": 0, "data": {...}, "message": "success"}

// 失败
{"code": 1004, "data": null, "message": "无管理权限"}

8.2 错误码规范

错误码 含义 使用场景
0 成功 —
1001 参数错误 请求体校验失败
1002 未授权 token 缺失/无效/过期
1003 资源不存在 查询对象不存在
1004 无权限访问 非 admin 角色访问管理 API
1005 服务器内部错误 未预期异常

8.3 认证方式

  • 管理后台前端: 登录成功后将 token 存储到 localStorage 的 admin_token 键
  • 请求头: Authorization: Bearer {token}
  • 后端校验: 复用坐席端 get_current_agent 依赖，新增 require_admin 校验 role == 'admin'
  • Token 存储: Redis agent:token:{token} → user_id，TTL 8 小时

8.4 前端 Token 键名

端 localStorage 键 说明
坐席端 agent_token 坐席工作台
管理后台 admin_token 管理后台（独立键避免冲突）

8.5 CSS 变量（深色科技风）

管理后台使用固定深色主题，CSS 变量与 PRD §10.2 对齐：

:root {
  --bg-primary: #0f172a;
  --bg-secondary: #1e293b;
  --bg-tertiary: #334155;
  --accent: #3b82f6;
  --success: #10b981;
  --warning: #f59e0b;
  --danger: #ef4444;
  --text-primary: #f1f5f9;
  --text-secondary: #94a3b8;
  --text-muted: #64748b;
}

8.6 集成配置存储约定

阶段一复用 SystemConfig 表存储集成系统配置，键命名规则：

键 值示例 说明
integration_dify_api_url https://api.dify.ai/v1 Dify API 地址
integration_dify_api_key app-xxxxx Dify API Key
integration_ragflow_api_url http://ragflow:9380 RAGFlow API 地址
integration_ragflow_api_key ragflow-xxxxx RAGFlow API Key

8.7 快速回复状态枚举

draft → pending_review → approved
                    └→ rejected → (修改后重新提交) → pending_review
  • approved: 全员可见
  • pending_review: 仅提交人 + admin 可见
  • rejected: 仅提交人可见（返回修改后重新提交）
  • draft: 仅提交人可见

8.8 坐席端快速回复可见性规则

坐席端 GET /api/quick-replies 返回条件：

  • status = 'approved'（全员可见）
  • status = 'pending_review' AND submitted_by = 当前坐席ID（自己的待审核）

8.9 技能标签枚举

const SKILL_TAGS = ['电脑', '软件', '外设', '网络', '安全', '资产', '其他'] as const;

8.10 日期格式

所有日期使用 ISO 8601 UTC 格式，如 2026-07-15T10:30:00Z。

9. 待明确事项

# 事项 当前假设 影响范围
1 坐席"今日结单数"统计口径 从 conversations 表统计 assigned_agent_id = agent.id AND status = 'resolved' AND DATE(resolved_at) = TODAY 仪表盘 + 坐席管理
2 集成配置中 API Key 是否加密存储 阶段一明文存储（与现有 SystemConfig 一致），阶段二引入加密 安全性
3 管理后台是否支持移动端适配 阶段一仅支持桌面端，不做移动端响应式 布局
4 应急模式引导文案是否阶段二可配 按主理人决策，阶段一固定文案 功能开关页
5 全局搜索结果排序规则 按类型优先级排序：配置项 > 坐席 > 快速回复，同类型按名称排序 搜索体验

文档结束 — 本架构设计文档覆盖管理后台阶段一 1B 的全部技术方案，与 PRD-admin.md 和主理人决策对齐。

Reference in New Issue View Git Blame Copy Permalink