ylt_diy/docs/API文档.md

订单日报系统 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	是	文件名