395 lines
9.7 KiB
Markdown
395 lines
9.7 KiB
Markdown
# 订单日报系统 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 | 是 | 文件名 | |