# EcoData 数据接口文档

## 项目概述

EcoData 是一个基于数据查询系统，提供数据查询。

数据为测试生成数据，仅供测试。

## 基本URL

`http://ecodata.lzgxy.cn`

## 接口列表

### 1. 分页数据查询接口

- **接口地址**：`/query/PaginQuery/`
- **请求方式**：GET
- **认证方式**：密钥验证

#### 请求参数

| 参数名     | 类型    | 必填 | 说明                |
| ---------- | ------- | ---- | ------------------- |
| key        | String  | `是` | 访问密钥            |
| user_id    | String  | 否   | 用户ID              |
| product_id | String  | 否   | 产品ID              |
| start_time | String  | 否   | 开始时间（ISO格式） |
| end_time   | String  | 否   | 结束时间（ISO格式） |
| city       | String  | 否   | 用户所在城市        |
| gender     | String  | 否   | 用户性别            |
| age        | Integer | 否   | 用户年龄            |
| platform   | String  | 否   | 购物平台            |
| offset     | Integer | 否   | 起始索引，默认为0   |
| limit      | Integer | 否   | 返回数量，默认为10  |

#### 请求头

- 需要在URL参数中包含 `key` 参数，用于身份验证

#### 响应示例

```json
{
  "data": [
    {
      "id": 1,
      "user_id": "123456",
      "order_id": "123456000001",
      "user_name": "张三",
      "product_id": "P001",
      "product_name": "商品名称",
      "product_category": "商品分类",
      "unit_price": 99.99,
      "purchase_time": "2023-01-01T10:00:00",
      "quantity": 2,
      "total_amount": 199.98,
      "user_city": "北京",
      "user_gender": "男",
      "user_age": 25,
      "shopping_platform": "淘宝"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 100,
    "has_more": true
  }
}
```

#### 浏览器示例

![image-20260106195505299](./pics/image-20260106195505299.png)

#### 响应参数说明

- `data`：数据列表
  - id：记录ID
  - user_id：用户ID
  - order_id：订单ID
  - user_name：用户名
  - product_id：产品ID
  - product_name：产品名称
  - product_category：产品分类
  - unit_price：单价
  - purchase_time：购买时间
  - quantity：数量
  - total_amount：总金额
  - user_city：用户城市
  - user_gender：用户性别
  - user_age：用户年龄
  - shopping_platform：购物平台
- `pagination`：分页信息
  - offset：起始索引
  - limit：返回数量
  - total：总记录数
  - has_more：是否有更多数据

### 2. 密钥生成接口

- **接口地址**：`/get_signature/`
- **请求方式**：GET

#### 请求参数

| 参数名 | 类型   | 必填 | 说明     |
| ------ | ------ | ---- | -------- |
| id     | String | 是   | 学生学号 |
| name   | String | 是   | 学生姓名 |

#### 响应示例

```json
{
  "name": "张三",
  "student_id": "20210001",
  "ip": "192.168.1.1",
  "request_key": "XXXXXXXXX（访问密钥）"
}
```

#### 浏览器示例

![image-20260106195132490](./pics/image-20260106195132490.png)

#### 响应参数说明

- name：学生姓名
- student_id：学生学号
- ip：当前IP地址
- request_key：生成的请求密钥

## 验证机制

### 密钥验证流程

1. **密钥生成**：
   - 通过 `/get_signature/` 接口获取密钥
   - 密钥有效期为5分钟
   
2. **密钥验证**：
   - 在请求 `/query/PaginQuery/` 时需要在URL参数中添加 `key` 参数

## 异常处理

- `400`: 缺少密钥参数
- `401`: 密钥解析失败或已过期
- `403`: IP地址不匹配
- `404`: 学生信息不存在或未找到