9.7 KiB
订单日报系统 API 接口文档
一、全局配置接口
1.1 获取求和数据采集字段配置
接口地址: GET /api/global-config/sum-data-fields
请求参数: 无
返回示例:
{
"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列表 |
请求示例:
{
"sum_data_fields": ["sharp_electricity", "peak_electricity", "flat_electricity", "valley_electricity"]
}
返回示例:
{
"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/手动编辑） |
返回示例:
{
"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 | 否 | 结束日期 |
返回示例:
{
"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 | 否 | 数据来源 |
返回示例:
{
"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 | 是 | 文件名 |