simon/wecom_it_smart_desk

Fork 0

Files

T

Simon 63262292d7 chore: initial baseline with P0-safety .gitignore

2026-06-14 16:51:56 +08:00

37 KiB

Raw Permalink Blame History

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

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

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`	新增	数据库迁移脚本

具体工作:

初始化 frontend-admin/ 项目（Vue 3 + TS + Vite + Element Plus + Pinia + Tailwind CSS）
配置 Vite（base: /itadmin/、API 代理到 localhost:8000）
创建 Axios 实例（使用 admin_token 而非 agent_token）
定义全局 CSS 变量（深色科技风，与 PRD §10.2 对齐）
后端新增 ConfigChangeLog 模型
后端扩展 Agent 模型（新增 role, skill_tags）
后端扩展 QuickReplyTemplate 模型（新增 status, version, submitted_by）
后端新增 admin.py Schema（请求/响应数据结构）
创建 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 筛选逻辑（坐席端可见性）

具体工作:

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

具体工作:

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

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`	新增	通用占位页模板

具体工作:

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

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/ 路由

具体工作:

前后端联调：逐一测试所有 API 端点
深色科技风主题一致性检查（所有页面、组件、对话框）
Element Plus 组件深色样式覆盖（表格、表单、对话框、分页等）
响应式布局调整（窗口缩放、侧边栏折叠）
前端构建 npm run build，确认 dist 产物可用
Nginx 配置更新（新增 /itadmin/ 路由）
种子数据更新（宋献设为 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 和主理人决策对齐。

37 KiB Raw Permalink Blame History Unescape Escape

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

目录

1. 实现方案与框架选型

1.1 核心技术挑战

1.2 技术栈确认

前端（新建 frontend-admin/）

后端（扩展现有 FastAPI）

1.3 架构模式

2. 文件列表及相对路径

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

2.2 后端（扩展现有 backend/）

2.3 文件变更标注

3. 数据模型

3.1 新增模型：ConfigChangeLog

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

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

3.4 类图

4. API 接口设计

4.1 权限校验依赖

4.2 API 端点列表

4.2.1 运营总览仪表盘

4.2.2 功能开关/参数管理

4.2.3 坐席人员管理

4.2.4 外部系统集成配置

4.2.5 快速回复管理

4.2.6 消息分配模式

4.2.7 会话监控

4.2.8 全局搜索

5. 程序调用流程

5.1 管理员登录流程

5.2 配置变更流程

5.3 快速回复审核流程

5.4 坐席管理 CRUD 流程

6. 任务列表

T01: 项目基础设施

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

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

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

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

任务依赖图

7. 依赖包列表

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

7.2 后端新增

8. 共享知识

8.1 API 响应格式

8.2 错误码规范

8.3 认证方式

8.4 前端 Token 键名

8.5 CSS 变量（深色科技风）

8.6 集成配置存储约定

8.7 快速回复状态枚举

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

8.9 技能标签枚举

8.10 日期格式

9. 待明确事项

37 KiB

Raw Permalink Blame History

前端（新建 `frontend-admin/`）

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

2.2 后端（扩展现有 `backend/`）

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