wecom_it_smart_desk/docs/ARCHITECTURE-admin.md

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

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

---

## 目录

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

```python
# 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（新增字段）

```python
# 在 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（新增字段）

```python
# 在 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 类图

```mermaid
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 权限校验依赖

```python
# 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
- 描述: 获取仪表盘统计数据
- 响应:
```json
{
  "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
- 描述: 获取全部配置项（按功能分组）
- 响应:
```json
{
  "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
- 描述: 更新单个配置项（同时记录变更日志）
- 请求体:
```json
{
  "value": "true"
}
```
- 响应:
```json
{
  "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)
- 响应:
```json
{
  "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)
- 响应:
```json
{
  "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
- 描述: 添加坐席
- 请求体:
```json
{
  "user_id": "WangLi",
  "name": "王丽",
  "role": "agent",
  "skill_tags": ["外设", "安全"],
  "max_load": 5
}
```
- 响应:
```json
{
  "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
- 描述: 编辑坐席（角色/技能标签/负载上限）
- 请求体:
```json
{
  "role": "agent",
  "skill_tags": ["电脑", "网络"],
  "max_load": 8
}
```
- 响应:
```json
{
  "code": 0,
  "data": {
    "id": "uuid",
    "role": "agent",
    "skill_tags": ["电脑", "网络"],
    "max_load": 8
  }
}
```

**DELETE /api/admin/agents/{id}**

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

#### 4.2.4 外部系统集成配置

**GET /api/admin/integrations**

- 权限: admin
- 描述: 获取集成系统列表及配置状态
- 响应:
```json
{
  "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_`）
- 请求体:
```json
{
  "api_url": "https://api.dify.ai/v1",
  "api_key": "app-xxxxx"
}
```
- 响应:
```json
{
  "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` (可选)
- 响应:
```json
{
  "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
- 描述: 审核快速回复模板（通过/驳回）
- 请求体:
```json
{
  "action": "approve",
  "reason": ""
}
```
或:
```json
{
  "action": "reject",
  "reason": "内容需要更具体的操作步骤"
}
```
- 响应:
```json
{
  "code": 0,
  "data": {
    "id": "uuid",
    "status": "approved",
    "version": 2
  }
}
```

#### 4.2.6 消息分配模式

**GET /api/admin/assignment-mode**

- 权限: admin
- 描述: 获取当前分配模式
- 响应:
```json
{
  "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
- 描述: 切换分配模式（阶段一仅允许手动接单）
- 请求体:
```json
{
  "mode": "manual"
}
```

#### 4.2.7 会话监控

**GET /api/admin/monitor/sessions**

- 权限: admin
- 描述: 获取实时会话列表（Demo预览）
- 查询参数: `status` (可选，默认非 resolved)
- 响应:
```json
{
  "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
- 描述: 搜索配置项、坐席、快速回复
- 响应:
```json
{
  "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 管理员登录流程

```mermaid
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 配置变更流程

```mermaid
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 快速回复审核流程

```mermaid
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 流程

```mermaid
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 状态）

---

### 任务依赖图

```mermaid
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`）

```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 遵循统一响应格式：

```json
// 成功
{"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 对齐：

```css
: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 技能标签枚举

```typescript
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 和主理人决策对齐。