# 历史记录 (History Records) API

历史记录 API 用于管理通话记录和对话历史。

## 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `/api/v1/history` |
| 认证方式 | Bearer Token (预留) |

---

## 数据模型

### CallRecord

```typescript
interface CallRecord {
  id: string;                 // 通话记录ID
  user_id: number;            // 所属用户ID
  assistant_id?: string;      // 关联助手ID
  source: string;             // 来源: "debug" | "external"
  status: string;            // 状态: "connected" | "missed" | "failed"
  started_at: string;        // 开始时间 ISO8601
  ended_at?: string;         // 结束时间 ISO8601
  duration_seconds?: int;    // 通话时长(秒)
  summary?: string;          // 通话摘要
  cost?: number;             // 费用
  metadata?: object;         // 元数据
  created_at: string;        // 创建时间
}
```

### TranscriptSegment

```typescript
interface TranscriptSegment {
  turn_index: int;       // 对话轮次
  speaker: string;       // 说话者: "human" | "ai"
  content: string;      // 转写内容
  confidence?: float;    // 置信度 0-1
  start_ms: int;        // 开始时间(毫秒)
  end_ms: int;          // 结束时间(毫秒)
  duration_ms?: int;    // 持续时间(毫秒)
  audio_url?: string;   // 音频URL
  emotion?: string;      // 情绪标签
}
```

### InteractionDetail

```typescript
interface InteractionDetail {
  role: "user" | "assistant";  // 角色
  content: string;              // 文本内容或转写文本
  audio_url?: string;           // 音频URL
  image_urls?: string[];       // 图片URL列表(视频场景)
  timestamp: string;            // 时间戳
}
```

---

## API 端点

### 1. 获取通话记录列表

```http
GET /api/v1/history
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| assistant_id | string | 否 | 过滤助手ID |
| status | string | 否 | 过滤状态: "connected" \| "missed" \| "failed" |
| source | string | 否 | 过滤来源: "debug" \| "external" |
| start_date | string | 否 | 开始日期 ISO8601 |
| end_date | string | 否 | 结束日期 ISO8601 |
| page | int | 否 | 页码，默认 1 |
| limit | int | 否 | 每页数量，默认 20 |

**Response:**

```json
{
  "total": 150,
  "page": 1,
  "limit": 20,
  "list": [
    {
      "id": "call_001",
      "user_id": 1,
      "assistant_id": "abc12345",
      "source": "debug",
      "status": "connected",
      "started_at": "2024-01-15T14:30:00Z",
      "ended_at": "2024-01-15T14:33:00Z",
      "duration_seconds": 180,
      "summary": "用户咨询产品A的售后服务",
      "cost": 0.05,
      "created_at": "2024-01-15T14:30:00Z"
    },
    {
      "id": "call_002",
      "user_id": 1,
      "assistant_id": "abc12345",
      "source": "external",
      "status": "missed",
      "started_at": "2024-01-15T14:00:00Z",
      "duration_seconds": 0,
      "created_at": "2024-01-15T14:00:00Z"
    }
  ]
}
```

---

### 2. 获取通话详情

```http
GET /api/v1/history/{call_id}
```

**Response:**

```json
{
  "id": "call_001",
  "user_id": 1,
  "assistant_id": "abc12345",
  "source": "debug",
  "status": "connected",
  "started_at": "2024-01-15T14:30:00Z",
  "ended_at": "2024-01-15T14:33:00Z",
  "duration_seconds": 180,
  "summary": "用户咨询产品A的售后服务",
  "cost": 0.05,
  "metadata": {
    "browser": "Chrome",
    "os": "Windows"
  },
  "transcripts": [
    {
      "turn_index": 0,
      "speaker": "human",
      "content": "您好，我想咨询一下产品A的售后服务",
      "confidence": 0.98,
      "start_ms": 0,
      "end_ms": 3500,
      "duration_ms": 3500,
      "audio_url": "https://storage.example.com/audio/call_001/turn_0.mp3"
    },
    {
      "turn_index": 1,
      "speaker": "ai",
      "content": "您好！产品A享有7天无理由退货和一年质保服务。请问您遇到了什么问题？",
      "confidence": 0.95,
      "start_ms": 4000,
      "end_ms": 12000,
      "duration_ms": 8000,
      "audio_url": "https://storage.example.com/audio/call_001/turn_1.mp3"
    },
    {
      "turn_index": 2,
      "speaker": "human",
      "content": "我发现产品A有一个功能坏了",
      "confidence": 0.92,
      "start_ms": 13000,
      "end_ms": 18000,
      "duration_ms": 5000,
      "audio_url": "https://storage.example.com/audio/call_001/turn_2.mp3"
    }
  ]
}
```

---

### 3. 创建通话记录

```http
POST /api/v1/history
```

**Request Body:**

```json
{
  "user_id": 1,
  "assistant_id": "abc12345",
  "source": "debug"
}
```

**Response:**

```json
{
  "id": "call_new001",
  "user_id": 1,
  "assistant_id": "abc12345",
  "source": "debug",
  "status": "connected",
  "started_at": "2024-01-15T15:00:00Z",
  "created_at": "2024-01-15T15:00:00Z"
}
```

---

### 4. 更新通话记录

```http
PUT /api/v1/history/{call_id}
```

**Request Body:**

```json
{
  "status": "connected",
  "summary": "用户咨询产品A的售后服务，已引导用户提交工单",
  "duration_seconds": 180,
  "ended_at": "2024-01-15T14:33:00Z"
}
```

---

### 5. 删除通话记录

```http
DELETE /api/v1/history/{call_id}
```

---

### 6. 添加转写片段

```http
POST /api/v1/history/{call_id}/transcripts
```

**Request Body:**

```json
{
  "turn_index": 3,
  "speaker": "ai",
  "content": "好的，我已经为您创建了工单，编号 #12345，请保持电话畅通，我们的客服人员会在24小时内联系您。",
  "confidence": 0.96,
  "start_ms": 20000,
  "end_ms": 28000,
  "duration_ms": 8000,
  "emotion": "neutral"
}
```

**Response:**

```json
{
  "id": 100,
  "turn_index": 3,
  "speaker": "ai",
  "content": "好的，我已经为您创建了工单...",
  "confidence": 0.96,
  "start_ms": 20000,
  "end_ms": 28000,
  "duration_ms": 8000,
  "audio_url": "https://storage.example.com/audio/call_001/turn_3.mp3",
  "emotion": "neutral"
}
```

---

### 7. 获取音频

```http
GET /api/v1/history/{call_id}/audio/{turn_index}
```

**Response:** 重定向到音频文件 URL

---

### 8. 搜索通话记录

```http
GET /api/v1/history/search
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| q | string | 是 | 搜索关键词 |
| page | int | 否 | 页码 |
| limit | int | 否 | 每页数量 |

**Response:**

```json
{
  "total": 5,
  "page": 1,
  "limit": 20,
  "list": [
    {
      "id": "call_001",
      "started_at": "2024-01-15T14:30:00Z",
      "matched_content": "用户咨询产品A的售后服务"
    }
  ]
}
```

---

### 9. 获取统计信息

```http
GET /api/v1/history/stats
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| assistant_id | string | 否 | 助手ID |

**Response:**

```json
{
  "total_calls": 150,
  "connected_calls": 135,
  "missed_calls": 15,
  "failed_calls": 0,
  "avg_duration_seconds": 180,
  "total_cost": 7.50,
  "by_status": {
    "connected": 135,
    "missed": 15,
    "failed": 0
  },
  "by_source": {
    "debug": 100,
    "external": 50
  },
  "daily_trend": [
    {
      "date": "2024-01-15",
      "calls": 20,
      "connected": 18,
      "avg_duration": 175
    }
  ]
}
```

---

## 推荐的 Schema 定义

```python
# ============ Call Record ============
class CallRecordSource(str, Enum):
    DEBUG = "debug"
    EXTERNAL = "external"

class CallRecordStatus(str, Enum):
    CONNECTED = "connected"
    MISSED = "missed"
    FAILED = "failed"

class CallRecordBase(BaseModel):
    assistant_id: Optional[str] = None
    source: str = "debug"

class CallRecordCreate(CallRecordBase):
    pass

class CallRecordUpdate(BaseModel):
    status: Optional[str] = None
    summary: Optional[str] = None
    duration_seconds: Optional[int] = None
    ended_at: Optional[str] = None
    cost: Optional[float] = None
    metadata: Optional[dict] = None

class TranscriptSegment(BaseModel):
    turn_index: int
    speaker: str  # "human" | "ai"
    content: str
    confidence: Optional[float] = None
    start_ms: int
    end_ms: int
    duration_ms: Optional[int] = None
    emotion: Optional[str] = None

class CallRecordOut(BaseModel):
    id: str
    user_id: int
    assistant_id: Optional[str] = None
    source: str
    status: str
    started_at: str
    ended_at: Optional[str] = None
    duration_seconds: Optional[int] = None
    summary: Optional[str] = None
    cost: float = 0.0
    metadata: dict = {}
    created_at: datetime
    transcripts: List[TranscriptSegment] = []

    class Config:
        from_attributes = True

class TranscriptCreate(BaseModel):
    turn_index: int
    speaker: str
    content: str
    confidence: Optional[float] = None
    start_ms: int
    end_ms: int
    duration_ms: Optional[int] = None
    emotion: Optional[str] = None

class TranscriptOut(TranscriptCreate):
    id: int
    audio_url: Optional[str] = None

    class Config:
        from_attributes = True

class HistoryStats(BaseModel):
    total_calls: int
    connected_calls: int
    missed_calls: int
    failed_calls: int
    avg_duration_seconds: float
    total_cost: float
    by_status: dict
    by_source: dict
    daily_trend: List[dict]
```

---

## Web 端对应接口映射

| Web Type | API Endpoint |
|----------|--------------|
| CallLog (list) | `GET /api/v1/history` |
| CallLog (detail) | `GET /api/v1/history/{id}` |
| InteractionDetail | `GET /api/v1/history/{id}` (transcripts 字段) |