# 订单日报系统 API 接口文档

## 一、全局配置接口

### 1.1 获取求和数据采集字段配置

**接口地址**: `GET /api/global-config/sum-data-fields`

**请求参数**: 无

**返回示例**:

```json
{
    "success": true,
    "data": ["sharp_electricity", "peak_electricity", "flat_electricity", "valley_electricity"]
}
```

**字段说明**:

| 字段Key | 显示名称 | 说明 |
|---------|----------|------|
| sharp_electricity | 尖时电量(kWh) | 尖时段充电电量 |
| peak_electricity | 峰时电量(kWh) | 峰时段充电电量 |
| flat_electricity | 平时电量(kWh) | 平时段充电电量 |
| valley_electricity | 谷时电量(kWh) | 谷时段充电电量 |
| charge_elecfee_amount | 实收电费(元) | 实际收取的电费金额 |
| charge_servicefee_amount | 实收服务费(元) | 实际收取的服务费金额 |
| charge_amount | 实收总金额(元) | 实际收取的总金额（电费+服务费） |
| charge_frequency | 充电次数 | 充电订单次数 |
| custom_service_fee | 自定义服务费(元) | 按自定义单价计算的服务费 |
| custom_total_amount | 自定义实收总金额(元) | 实收电费+自定义服务费 |

### 1.2 保存求和数据采集字段配置

**接口地址**: `POST /api/global-config/sum-data-fields`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sum_data_fields | Array | 是 | 选中的采集字段Key列表 |

**请求示例**:

```json
{
    "sum_data_fields": ["sharp_electricity", "peak_electricity", "flat_electricity", "valley_electricity"]
}
```

**返回示例**:

```json
{
    "success": true,
    "message": "配置保存成功"
}
```

## 二、求和数据接口

### 2.1 查询求和数据列表

**接口地址**: `GET /api/sum-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | Integer | 否 | 页码（不传则返回全部数据） |
| page_size | Integer | 否 | 每页大小，默认20 |
| start_date | String | 否 | 开始日期（格式：YYYY-MM-DD） |
| end_date | String | 否 | 结束日期（格式：YYYY-MM-DD） |
| config_id | Integer | 否 | 配置ID |
| config_name | String | 否 | 配置名称（模糊搜索） |
| sum_field_key | String | 否 | 求和字段键名 |
| data_source | String | 否 | 数据来源（auto/手动编辑） |

**返回示例**:

```json
{
    "success": true,
    "data": {
        "list": [...],
        "total": 100,
        "page": 1,
        "page_size": 20
    }
}
```

### 2.2 从历史记录采集求和数据

**接口地址**: `POST /api/sum-data/collect`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| history_id | Integer | 否 | 历史记录ID（不传则采集所有） |
| start_date | String | 否 | 开始日期 |
| end_date | String | 否 | 结束日期 |

**返回示例**:

```json
{
    "success": true,
    "message": "采集完成，共采集 50 条求和数据，跳过 0 条无求和数据的记录"
}
```

### 2.3 批量添加求和数据

**接口地址**: `POST /api/sum-data/batch-add`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| report_date | String | 是 | 报表日期（YYYY-MM-DD） |
| config_name | String | 是 | 配置名称 |
| split_type | String | 是 | 拆分方式（company_id/user_id/station_id） |
| split_value | String | 是 | 拆分值 |
| split_name | String | 否 | 拆分显示名称 |
| total_orders | Integer | 否 | 订单数 |
| remark | String | 否 | 备注/修改原因 |
| fields | Array | 是 | 求和字段数据列表 |

**fields数组结构**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sum_field_key | String | 是 | 字段键名 |
| sum_field_name | String | 是 | 字段显示名称 |
| sum_value | Float | 是 | 求和值 |

### 2.4 更新求和数据

**接口地址**: `PUT /api/sum-data/<id>`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sum_value | Float | 是 | 更新后的求和值 |
| remark | String | 否 | 修改原因/备注 |

### 2.5 删除求和数据

**接口地址**: `DELETE /api/sum-data/<id>`

**请求参数**: 无

### 2.6 批量删除求和数据

**接口地址**: `POST /api/sum-data/batch-delete`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Array | 是 | 要删除的记录ID列表 |

### 2.7 导出求和数据

**接口地址**: `GET /api/sum-data/export`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| start_date | String | 否 | 开始日期 |
| end_date | String | 否 | 结束日期 |
| keyword | String | 否 | 配置名称关键字 |
| data_source | String | 否 | 数据来源 |

**返回示例**:

```json
{
    "success": true,
    "total": 100,
    "file_path": "/public/reports/求和数据导出_20260728.xlsx",
    "filename": "求和数据导出_20260728.xlsx"
}
```

## 三、配置管理接口

### 3.1 创建配置

**接口地址**: `POST /api/config`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| config_name | String | 是 | 配置名称 |
| split_type | String | 是 | 拆分方式 |
| split_value | String | 是 | 拆分值（逗号分隔） |
| split_name | String | 否 | 拆分显示名称 |
| selected_fields | Array | 是 | 选择的字段列表 |
| sum_fields | Array | 否 | 求和字段列表 |
| time_periods | Object | 否 | 分时段电量配置 |
| merge_telecom | Boolean | 否 | 是否合并特来电数据 |
| telecom_vehicle_no | String | 否 | 特来电车量自编号 |
| field_custom_names | Object | 否 | 字段自定义表头名称 |
| show_monthly_total | Boolean | 否 | 是否显示月度总计 |
| custom_service_fee_price | Float | 否 | 自定义服务费单价(元/kWh) |
| custom_service_fee_name | String | 否 | 自定义服务费表头名称 |
| show_custom_service_fee | Boolean | 否 | 是否显示自定义服务费列 |
| show_total_amount | Boolean | 否 | 是否显示实收总金额列 |
| total_amount_name | String | 否 | 实收总金额表头名称 |

### 3.2 查询配置列表

**接口地址**: `GET /api/config`

**请求参数**: 无

### 3.3 查询单个配置

**接口地址**: `GET /api/config/<id>`

**请求参数**: 无

### 3.4 更新配置

**接口地址**: `PUT /api/config/<id>`

**请求参数**: 同创建配置

### 3.5 删除配置

**接口地址**: `DELETE /api/config/<id>`

**请求参数**: 无

### 3.6 复制配置

**接口地址**: `POST /api/config/<id>/copy`

**请求参数**: 无

### 3.7 启用/禁用配置

**接口地址**: `POST /api/config/<id>/toggle`

**请求参数**: 无

### 3.8 配置排序

**接口地址**: `POST /api/config/<id>/move`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| direction | String | 是 | 移动方向（up/down） |

## 四、认证接口

### 4.1 登录

**接口地址**: `POST /api/auth/login`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |

### 4.2 获取用户信息

**接口地址**: `GET /api/auth/info`

**请求参数**: 无

### 4.3 修改密码

**接口地址**: `POST /api/auth/change-password`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| old_password | String | 是 | 旧密码 |
| new_password | String | 是 | 新密码 |
| confirm_password | String | 是 | 确认新密码 |

## 五、实体管理接口

### 5.1 查询企业列表

**接口地址**: `GET /api/entities/company`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | Integer | 否 | 页码 |
| page_size | Integer | 否 | 每页大小 |
| keyword | String | 否 | 搜索关键字 |

### 5.2 查询用户列表

**接口地址**: `GET /api/entities/user`

**请求参数**: 同企业列表

### 5.3 查询场站列表

**接口地址**: `GET /api/entities/station`

**请求参数**: 同企业列表

### 5.4 按ID批量查询实体

**接口地址**: `POST /api/entities/by_ids`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | String | 是 | 实体类型（company/user/station） |
| ids | Array | 是 | 实体ID列表 |

## 六、字段列表接口

### 6.1 获取字段列表

**接口地址**: `GET /api/fields`

**请求参数**: 无

## 七、日报生成接口

### 7.1 生成日报

**接口地址**: `POST /api/report/generate`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| config_id | Integer | 是 | 配置ID |
| report_date | String | 否 | 报表日期（默认昨天） |

### 7.2 查询历史记录

**接口地址**: `GET /api/report/history`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | Integer | 否 | 页码 |
| page_size | Integer | 否 | 每页大小 |
| start_date | String | 否 | 开始日期 |
| end_date | String | 否 | 结束日期 |
| config_name | String | 否 | 配置名称 |
| status | Integer | 否 | 状态（0失败/1成功） |

### 7.3 删除历史记录

**接口地址**: `DELETE /api/report/history/<id>`

**请求参数**: 无

### 7.4 批量删除历史记录

**接口地址**: `POST /api/report/history/batch-delete`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Array | 是 | 记录ID列表 |

## 八、文件下载接口

### 8.1 下载报表文件

**接口地址**: `GET /api/download/report/<file_name>`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file_name | String | 是 | 文件名 |