huhao/ylt_diy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c5fcda3511976f1d641867eac959718453a28011
ylt_diy/docs/API文档.md

395 lines
9.7 KiB
Markdown
Raw Normal View History

制作开发文档，添加充电卡备注到日报中
2026-07-29 10:02:32 +08:00
# 订单日报系统 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 | 是 | 文件名 |
Reference in New Issue Copy Permalink