# 上传记录查询接口 API 文档

## 快速开始

系统现在支持查询用户的文件上传记录，所有接口都需要认证。

## 接口列表

### 1. 查询上传记录（支持分页和筛选）

```
GET /api/upload/records
```

**功能**: 查询用户的上传记录，支持分页、按数据集筛选、按文件名搜索

**认证**: 需要在请求头中携带 Token
```
Authorization: Bearer <your_token>
```

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | int | 否 | 1 | 页码（从1开始） |
| page_size | int | 否 | 10 | 每页数量（最大100） |
| user_id | string | 否 | - | 用户ID（仅管理员可用） |
| dataset_id | string | 否 | - | 数据集ID筛选 |
| file_name | string | 否 | - | 文件名模糊搜索 |

**响应格式**:
```json
{
  "code": 200,
  "message": "查询成功，共 25 条记录",
  "total": 25,
  "page": 1,
  "page_size": 10,
  "records": [
    {
      "id": 1,
      "user_id": "user_123",
      "user_name": "张三",
      "file_id": "abc123",
      "file_name": "example.pdf",
      "file_size": 10485760,
      "file_md5": "d41d8cd98f00b204e9800998ecf8427e",
      "file_path": "/uploads/dataset_001/example.pdf",
      "dataset_id": "dataset_001",
      "total_chunks": 10,
      "upload_status": "completed",
      "upload_started_at": "2024-01-01T10:00:00",
      "upload_completed_at": "2024-01-01T10:05:00",
      "created_at": "2024-01-01T10:05:00"
    }
  ]
}
```

**使用示例**:
```bash
# 基本查询（第一页，10条）
curl -H "Authorization: Bearer your_token" \
  "http://localhost:8000/api/upload/records"

# 分页查询（第2页，每页20条）
curl -H "Authorization: Bearer your_token" \
  "http://localhost:8000/api/upload/records?page=2&page_size=20"

# 按数据集查询
curl -H "Authorization: Bearer your_token" \
  "http://localhost:8000/api/upload/records?dataset_id=dataset_001"

# 搜索文件名
curl -H "Authorization: Bearer your_token" \
  "http://localhost:8000/api/upload/records?file_name=report"
```

---

### 2. 获取上传统计信息

```
GET /api/upload/records/stats
```

**功能**: 获取当前用户的上传统计信息（总文件数、总大小、今日上传等）

**认证**: 需要在请求头中携带 Token
```
Authorization: Bearer <your_token>
```

**响应格式**:
```json
{
  "code": 200,
  "message": "统计信息获取成功",
  "data": {
    "total_files": 125,
    "total_size": 5368709120,
    "total_size_gb": 5.0,
    "today_files": 10,
    "today_size": 419430400,
    "today_size_gb": 0.39
  }
}
```

**使用示例**:
```bash
curl -H "Authorization: Bearer your_token" \
  "http://localhost:8000/api/upload/records/stats"
```

---

## 前端集成示例

### React 示例

```jsx
import React, { useState, useEffect } from 'react';

function UploadRecords() {
  const [records, setRecords] = useState([]);
  const [stats, setStats] = useState(null);
  const [page, setPage] = useState(1);
  const [total, setTotal] = useState(0);
  const token = 'your_token'; // 从登录状态获取

  // 获取上传记录
  const fetchRecords = async (page) => {
    const response = await fetch(
      `http://localhost:8000/api/upload/records?page=${page}&page_size=10`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    const data = await response.json();
    setRecords(data.records);
    setTotal(data.total);
  };

  // 获取统计信息
  const fetchStats = async () => {
    const response = await fetch(
      'http://localhost:8000/api/upload/records/stats',
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    const data = await response.json();
    setStats(data.data);
  };

  useEffect(() => {
    fetchRecords(page);
    fetchStats();
  }, [page]);

  return (
    <div>
      <h2>上传统计</h2>
      {stats && (
        <div>
          <p>总文件数: {stats.total_files}</p>
          <p>总大小: {stats.total_size_gb} GB</p>
          <p>今日上传: {stats.today_files} 个文件</p>
        </div>
      )}

      <h2>上传记录</h2>
      <table>
        <thead>
          <tr>
            <th>文件名</th>
            <th>大小</th>
            <th>上传时间</th>
            <th>状态</th>
          </tr>
        </thead>
        <tbody>
          {records.map(record => (
            <tr key={record.id}>
              <td>{record.file_name}</td>
              <td>{(record.file_size / 1024 / 1024).toFixed(2)} MB</td>
              <td>{new Date(record.upload_completed_at).toLocaleString()}</td>
              <td>{record.upload_status}</td>
            </tr>
          ))}
        </tbody>
      </table>

      <div>
        <button onClick={() => setPage(p => Math.max(1, p - 1))}>上一页</button>
        <span>第 {page} 页，共 {Math.ceil(total / 10)} 页</span>
        <button onClick={() => setPage(p => p + 1)}>下一页</button>
      </div>
    </div>
  );
}

export default UploadRecords;
```

### Vue 3 示例

```vue
<template>
  <div>
    <h2>上传统计</h2>
    <div v-if="stats">
      <p>总文件数: {{ stats.total_files }}</p>
      <p>总大小: {{ stats.total_size_gb }} GB</p>
      <p>今日上传: {{ stats.today_files }} 个文件</p>
    </div>

    <h2>上传记录</h2>
    <table>
      <thead>
        <tr>
          <th>文件名</th>
          <th>大小</th>
          <th>上传时间</th>
          <th>状态</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="record in records" :key="record.id">
          <td>{{ record.file_name }}</td>
          <td>{{ (record.file_size / 1024 / 1024).toFixed(2) }} MB</td>
          <td>{{ formatDate(record.upload_completed_at) }}</td>
          <td>{{ record.upload_status }}</td>
        </tr>
      </tbody>
    </table>

    <div>
      <button @click="prevPage">上一页</button>
      <span>第 {{ page }} 页，共 {{ totalPages }} 页</span>
      <button @click="nextPage">下一页</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, computed } from 'vue';

const records = ref([]);
const stats = ref(null);
const page = ref(1);
const total = ref(0);
const pageSize = 10;
const token = 'your_token'; // 从登录状态获取

const totalPages = computed(() => Math.ceil(total.value / pageSize));

const fetchRecords = async (pageNum) => {
  const response = await fetch(
    `http://localhost:8000/api/upload/records?page=${pageNum}&page_size=${pageSize}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  const data = await response.json();
  records.value = data.records;
  total.value = data.total;
};

const fetchStats = async () => {
  const response = await fetch(
    'http://localhost:8000/api/upload/records/stats',
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  const data = await response.json();
  stats.value = data.data;
};

const prevPage = () => {
  if (page.value > 1) {
    page.value--;
    fetchRecords(page.value);
  }
};

const nextPage = () => {
  if (page.value < totalPages.value) {
    page.value++;
    fetchRecords(page.value);
  }
};

const formatDate = (dateStr) => {
  return new Date(dateStr).toLocaleString('zh-CN');
};

onMounted(() => {
  fetchRecords(page.value);
  fetchStats();
});
</script>
```

---

## 权限说明

- **普通用户**: 只能查询自己的上传记录
- **管理员 (admin)**: 可以查询任何用户的上传记录

---

## 注意事项

1. 所有接口都需要认证，请在请求头中携带有效的 Token
2. 分页查询建议设置合理的 `page_size`，避免一次加载过多数据
3. 时间字段采用 ISO 8601 格式（如：`2024-01-01T10:00:00`）
4. 文件大小单位为字节，前端显示时需要自行转换为 KB/MB/GB
5. 统计信息建议前端进行适当缓存，避免频繁请求

---

## 错误处理

所有接口在发生错误时返回：

```json
{
  "code": 500,
  "message": "错误信息描述",
  "total": 0,
  "page": 1,
  "page_size": 10,
  "records": []
}
```

常见错误码：
- `401`: Token无效或过期
- `403`: 权限不足
- `500`: 服务器内部错误

