接口契约

本文定义前后端之间的稳定契约。前端所有请求经网关转发，按服务前缀路由：/vpp-event/** 进入事件服务，/vpp-dispatch/** 进入调度服务；网关去掉一级前缀后到达控制器。

统一请求上下文

Authorization: Bearer <access-token>

成功响应包含 code、msg、data；分页接口统一返回 total 与 rows。业务失败返回明确错误信息（如“事件已进入响应中，不接受新申报”），前端按 code 判断，不依赖具体文案。

能力	方法	语义
桩分页	`GET /resource/list`	按场站/参与状态/设备状态筛选
场站下拉	`GET /resource/station-list`	台账表单选项
资源统计	`GET /resource/stats`	桩数、容量与参与汇总
7 日功率	`GET /resource/power7d`	桩级近 7 日功率曲线
负荷曲线	`GET /resource/load-curve`	当日分钟级负荷
场站排名	`GET /resource/station-rank`	场站容量/贡献排名
运营商事件占比	`GET /resource/operator-event-pie/{eventId}`	事件内运营商参与分布
新增/修改/删除	`POST/PUT/DELETE /resource`	桩台账维护
批量启停	`PUT /resource/batchStatus`	批量启用/停用参与
导出	`POST /resource/export`	台账导出

能力	方法	语义
首页指标	`GET /home/metrics`	削峰/填谷/额定容量指标卡、环比与设备在线统计
容量趋势	`GET /home/capacityTrend`	当日可调容量削峰/填谷曲线与今日最大值

能力	方法	语义
分配分页	`GET /dispatch/list`	按事件/场站/状态筛选
全部分配	`GET /dispatch/listAll`	汇总用
生成分配	`POST /dispatch/allocate/{eventId}`	按可调容量生成桩级目标
确认分配	`PUT /dispatch/confirm`	待确认 → 已确认
下发	`PUT /dispatch/send/{ids}`	已确认 → 已下发
删除	`DELETE /dispatch/{ids}`	分配记录维护
运营商分配视图	`GET /dispatch/operatorList`	按运营商维度查看
按运营商生成	`POST /dispatch/allocateByOperator/{eventId}`	运营商维度分配
运营商确认	`PUT /dispatch/confirmOperator`	两级确认的第二级

能力	方法	语义
执行记录	`GET /execute/list`	目标/实际功率记录
偏差查询	`GET /execute/deviation`	按事件/阈值/场站/桩号过滤超差记录
事件桩清单	`GET /execute/piles/{eventId}`	参与执行的桩列表
模拟回放	`GET /execute/simulate/{eventId}`	重演执行曲线
新增/修改/删除	`POST/PUT/DELETE /execute`	记录维护

能力	方法	语义
评估分页	`GET /assess/list`	按事件/场站筛选
全部评估	`GET /assess/listAll`	汇总用
生成评估	`POST /assess/generate/{eventId}?qualRate=80`	按合格线生成场站级评估
删除	`DELETE /assess/{ids}`	评估记录维护

能力	方法	语义
结算分页	`GET /settlement/list`	按事件/场站/状态筛选
全部结算	`GET /settlement/listAll`	汇总用
生成结算	`POST /settlement/generate/{eventId}?unitPrice=4`	按单价生成结算单
确认结算	`PUT /settlement/confirm/{ids}`	记录确认时间
打款登记	`PUT /settlement/pay/{ids}`	记录打款时间并置已结算
我的收益	`GET /settlement/my-summary`、`GET /settlement/my-summary-total`	场站视角收益汇总
首页经营	`GET /settlement/homeStats`、`homeEventRows`、`flowStats`、`shareStats`	结算总额、事件结算进展、收益走势、分成统计
导出	`POST /settlement/export`	结算导出
删除	`DELETE /settlement/{ids}`	结算记录维护

接口层强制执行业务状态机，前端不需要重复实现：

申报：事件进入响应中后，新增申报被拒绝
分配：未确认不能下发；下发后进入执行监测
结算：未经评估生成结算时电量来源缺失，应先评估

接口契约体现的是平台的聚合开放能力：前端管理页、大屏和后续第三方系统围绕同一套事件与资源语义协同。