|
|
@@ -1,5636 +0,0 @@
|
|
|
-# 虚拟电厂平台接口文档
|
|
|
-
|
|
|
-| 项目 | 内容 |
|
|
|
-|------|------|
|
|
|
-| 文档名称 | 虚拟电厂平台接口文档 |
|
|
|
-| 文档版本 | V1.0.3 |
|
|
|
-| 编制依据 | 《API设计文档0304.md》《虚拟电厂平台详细设计文档 V1.0》《虚拟电厂平台数据库设计文档 V1.1》 |
|
|
|
-| 参考规范 | DLT 1867—2024、《虚拟电厂运管管理平台与虚拟电厂信息交互规范》（2025-12-17） |
|
|
|
-| 编制日期 | 2026-06-23 |
|
|
|
-| 更新日期 | 2026-07-04 |
|
|
|
-| 文档状态 | 已对齐 service-vpp 运管平台联调实现（V1.0.3，新增邀约管理接口） |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 目录
|
|
|
-
|
|
|
-- [1. 概述](#1-概述)
|
|
|
- - [1.4 数据存储与接口映射](#14-数据存储与接口映射)
|
|
|
-- [2. 内部 REST API（Web/移动端）](#2-内部-rest-apiweb移动端)
|
|
|
- - [2.1 通用规范](#21-通用规范)
|
|
|
- - [2.1.7 通用审计与租户字段](#217-通用审计与租户字段)
|
|
|
- - [2.2 认证授权](#22-认证授权)
|
|
|
- - [2.3 首页与看板](#23-首页与看板)
|
|
|
- - [2.4 客户管理](#24-客户管理)
|
|
|
- - [2.5 合同管理](#25-合同管理)
|
|
|
- - [2.6 资源管理](#26-资源管理)
|
|
|
- - [2.6.6 可调能力评估](#266-可调能力评估)
|
|
|
- - [2.7 运行监控](#27-运行监控)
|
|
|
- - [2.8 告警管理](#28-告警管理)
|
|
|
- - [2.9 需求响应](#29-需求响应)
|
|
|
- - [2.10 结算管理](#210-结算管理)
|
|
|
- - [2.11 信息报送](#211-信息报送)
|
|
|
- - [2.12 统计报表与数据分析](#212-统计报表与数据分析)
|
|
|
- - [2.13 系统管理](#213-系统管理)
|
|
|
- - [2.14 移动端专用](#214-移动端专用)
|
|
|
- - [2.15 运管平台主动对接（Web 管理）](#215-运管平台主动对接web-管理)
|
|
|
-- [3. 运管平台对接 API（UN/DN）](#3-运管平台对接-apiundn)
|
|
|
- - [3.1 交互概述](#31-交互概述)
|
|
|
- - [3.2 安全机制](#32-安全机制)
|
|
|
- - [3.3 通用服务](#33-通用服务)
|
|
|
- - [3.4 注册服务](#34-注册服务)
|
|
|
- - [3.5 询问服务（Poll）](#35-询问服务poll)
|
|
|
- - [3.6 报告服务](#36-报告服务)
|
|
|
- - [3.7 事件与参与服务](#37-事件与参与服务)
|
|
|
- - [3.8 信息对象服务（车网互动）](#38-信息对象服务车网互动)
|
|
|
- - [3.9 UN 侧错误码](#39-un-侧错误码)
|
|
|
- - [3.10 平台实现与配置（service-vpp）](#310-平台实现与配置service-vpp)
|
|
|
-- [4. 外部监管报送接口](#4-外部监管报送接口)
|
|
|
-- [5. 附录](#5-附录)
|
|
|
- - [5.4 内部 API 与数据表映射](#54-内部-api-与数据表映射节选)
|
|
|
- - [5.6 UN 联调 JSON 样例](#56-un-联调-json-样例)
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 1. 概述
|
|
|
-
|
|
|
-### 1.1 接口体系
|
|
|
-
|
|
|
-本平台接口分为三类：
|
|
|
-
|
|
|
-| 类型 | 调用方向 | 协议 | 用途 |
|
|
|
-|------|----------|------|------|
|
|
|
-| 内部 REST API | 前端/移动端 → 平台后端 | HTTPS + JSON + JWT | 业务管理、监控、运营 |
|
|
|
-| 运管平台 API（DN） | UN ↔ DN | HTTPS + JSON + 国密 SM2/SM3 | 注册、数据上报、需求响应 |
|
|
|
-| 监管报送 API | 平台 → 外部机构 | HTTPS/文件 | 信息报送 |
|
|
|
-
|
|
|
-### 1.2 环境地址
|
|
|
-
|
|
|
-| 环境 | 平台地址（示例） | 内部 API 前缀 | 运管平台 DN 地址（示例） |
|
|
|
-|------|------------------|---------------|--------------------------|
|
|
|
-| 开发 | `http://192.168.10.151` | `/prod-api/service-vpp` | `http://{内网IP}:{PORT}` |
|
|
|
-| 测试 | `https://test.example.com` | `/prod-api/service-vpp` | 联调时向 UN 提供公网 IP+端口 |
|
|
|
-| 生产 | `https://vpp.example.com` | `/prod-api/service-vpp` | 联调时向 UN 提供公网 IP+端口 |
|
|
|
-
|
|
|
-### 1.3 路径与版本策略
|
|
|
-
|
|
|
-与《API设计文档0304.md》保持一致，内部 REST API 采用 **网关 + 服务模块** 路径格式：
|
|
|
-
|
|
|
-| 层级 | 格式 | 示例 |
|
|
|
-|------|------|------|
|
|
|
-| 网关前缀 | `/prod-api` | 统一 API 网关入口 |
|
|
|
-| 服务模块 | `/service-vpp` | 虚拟电厂微服务标识 |
|
|
|
-| 业务路径 | `/{module}/{resource}[/{id}][/action]` | `/alarm/rule`、`/customer/access` |
|
|
|
-
|
|
|
-**完整示例**：`GET /prod-api/service-vpp/customer?current=1&size=10`
|
|
|
-
|
|
|
-- 运管平台（UN/DN）接口路径不变：服务名即路径，如 `/TokenRequest`、`/Poll`
|
|
|
-- 内部 API 破坏性变更通过新增服务版本（如 `service-vpp-v2`）或网关路由版本控制
|
|
|
-
|
|
|
-### 1.4 数据存储与接口映射
|
|
|
-
|
|
|
-内部 REST API 路径格式见 §1.3；持久化按《虚拟电厂平台数据库设计文档 V1.0》落库：
|
|
|
-
|
|
|
-| 接口模块 | 主要数据表 | 说明 |
|
|
|
-|----------|------------|------|
|
|
|
-| 认证/用户/角色/菜单 | `sys_user`、`sys_role`、`sys_menu`、`sys_user_role`、`sys_role_menu` | 沿用 usky-cloud `sys_*` |
|
|
|
-| 系统配置/字典/操作日志 | `sys_config`、`sys_dict_type`、`sys_dict_data`、`sys_oper_log` | 配置键建议 `vpp.` 前缀 |
|
|
|
-| 告警规则 | `rule_engine`、`rule_engine_device`、`rule_engine_condition`、`rule_engine_cron` | 沿用 usky-cloud `rule_*` |
|
|
|
-| 告警记录/统计/通知 | `base_alarm`、`base_alarm_type`、`base_alarm_notice`、`base_alarm_statistic` | 沿用 usky-cloud `base_*` |
|
|
|
-| 设备状态/远程控制 | `dmp_device`、`dmp_device_status`、`dmp_device_command` + `vpp_device_control_log` | 物联网命令写 `dmp_*`，业务摘要写 `vpp_*` |
|
|
|
-| 可调能力评估 | `vpp_site`、`vpp_resource_point`、`vpp_device`、`vpp_dr_*` + TDengine `device_metrics` | `/capability-eval`；曲线经 `service-tsdb` 查询 |
|
|
|
-| 电子档案 | `vpp_file_archive` | VPP 专属；`bizType` + `bizId` 关联合同/客户等 |
|
|
|
-| 需求响应/运管 UN | `vpp_dr_*`、`vpp_registration` | VPP 专属；邀约台账 `vpp_dr_invitation`；UN 报文 `account` ↔ `vpp_customer.account_no` |
|
|
|
-
|
|
|
-> 接口 JSON 字段采用 **camelCase**；落库字段为 **snake_case**，由服务端映射。租户隔离统一使用 `tenantId`（对应各表 `tenant_id`）。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 2. 内部 REST API（Web/移动端）
|
|
|
-
|
|
|
-### 2.1 通用规范
|
|
|
-
|
|
|
-> 本节与《API设计文档0304.md》「通用规范」对齐。
|
|
|
-
|
|
|
-#### 2.1.1 请求头
|
|
|
-
|
|
|
-```
|
|
|
-Content-Type: application/json
|
|
|
-Authorization: Bearer {token}
|
|
|
-```
|
|
|
-
|
|
|
-| Header | 必填 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| `Authorization` | 是（登录接口除外） | `Bearer {token}` |
|
|
|
-| `Content-Type` | 是 | `application/json`（上传接口为 `multipart/form-data`） |
|
|
|
-| `X-Tenant-Id` | 否 | 租户 ID；多租户场景下可由 Token 解析，显式传参时优先 |
|
|
|
-
|
|
|
-#### 2.1.2 统一响应格式
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": {},
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| status | string | 接口调用状态：`SUCCESS` / `FAIL` |
|
|
|
-| code | int | 业务状态码 |
|
|
|
-| msg | string | 提示信息 |
|
|
|
-| data | object | 业务数据 |
|
|
|
-| exception | string/null | 异常信息，正常为 null |
|
|
|
-
|
|
|
-#### 2.1.3 响应状态码
|
|
|
-
|
|
|
-| code | 说明 |
|
|
|
-|------|------|
|
|
|
-| 200 | 成功 |
|
|
|
-| 400 | 请求参数错误 |
|
|
|
-| 401 | 未授权，请先登录 |
|
|
|
-| 403 | 无权限访问 |
|
|
|
-| 404 | 资源不存在 |
|
|
|
-| 500 | 服务器内部错误 |
|
|
|
-
|
|
|
-**业务错误码（节选）**：
|
|
|
-
|
|
|
-| code | 说明 |
|
|
|
-|------|------|
|
|
|
-| 1001 | 用户名或密码错误 |
|
|
|
-| 1002 | 账号已被禁用 |
|
|
|
-| 2001 | 客户/资源/设备不存在 |
|
|
|
-| 2002 | 设备已离线 |
|
|
|
-| 3001 | 合同状态不允许当前操作 |
|
|
|
-| 4001 | 告警记录不存在 |
|
|
|
-| 5001 | 系统配置错误 |
|
|
|
-
|
|
|
-#### 2.1.4 分页规范
|
|
|
-
|
|
|
-**请求参数**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| current | int | 否 | 页码，默认 1 |
|
|
|
-| size | int | 否 | 每页数量，默认 10，最大 100 |
|
|
|
-| sortField | string | 否 | 排序字段，如 `create_time` |
|
|
|
-| sortOrder | string | 否 | `asc` / `desc`，默认 `desc` |
|
|
|
-
|
|
|
-**响应 data 结构**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "records": [],
|
|
|
- "total": 100,
|
|
|
- "current": 1,
|
|
|
- "size": 10,
|
|
|
- "totalPages": 10
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| records | array | 当前页数据列表 |
|
|
|
-| total | int | 总记录数 |
|
|
|
-| current | int | 当前页码 |
|
|
|
-| size | int | 每页记录数 |
|
|
|
-| totalPages | int | 总页数 |
|
|
|
-
|
|
|
-#### 2.1.5 时间格式
|
|
|
-
|
|
|
-所有时间字段统一使用 ISO 8601 格式：`YYYY-MM-DDTHH:mm:ss`
|
|
|
-
|
|
|
-示例：`2026-06-23T10:15:00`
|
|
|
-
|
|
|
-#### 2.1.6 接口描述约定
|
|
|
-
|
|
|
-各业务接口采用统一描述要素（与 0304 文档一致）：
|
|
|
-
|
|
|
-| 要素 | 说明 |
|
|
|
-|------|------|
|
|
|
-| **接口地址** | `METHOD /prod-api/service-vpp/...` |
|
|
|
-| **功能描述** | 接口业务用途 |
|
|
|
-| **请求参数** | Query / Body 字段表或 JSON 示例 |
|
|
|
-| **响应示例** | 含 `status`/`code`/`msg`/`data` 的完整 JSON |
|
|
|
-| **字段说明** | 关键字段与数据表映射（如有） |
|
|
|
-
|
|
|
-#### 2.1.7 通用审计与租户字段
|
|
|
-
|
|
|
-VPP 业务实体（`vpp_*` 表）在列表/详情响应中可能包含以下公共字段：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| tenantId | int | 租户 ID，多租户隔离 | tenant_id |
|
|
|
-| createTime | string | 创建时间（ISO 8601） | create_time |
|
|
|
-| updateTime | string | 更新时间（ISO 8601） | update_time |
|
|
|
-| createdBy | string | 创建人账号（≤30 字符） | created_by |
|
|
|
-| updatedBy | string | 更新人账号 | updated_by |
|
|
|
-| deleteFlag | int | 删除标识：0 未删除 / 1 已删除 | delete_flag |
|
|
|
-| deletedAt | string/null | 软删除时间，未删除时为 null | deleted_at |
|
|
|
-
|
|
|
-> 列表查询默认过滤 `deleteFlag=0`；软删除接口设置 `deleteFlag=1` 并写入 `deletedAt`。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.2 认证授权
|
|
|
-
|
|
|
-#### 2.2.1 用户登录
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/auth/login`
|
|
|
-
|
|
|
-**功能描述**：用户登录，返回 Token 与权限信息。
|
|
|
-
|
|
|
-**权限**：公开
|
|
|
-
|
|
|
-**请求体**（映射 `sys_user`）：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| username | string | 是 | 用户账号（sys_user.user_name） |
|
|
|
-| password | string | 是 | 登录密码 |
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "username": "operator01",
|
|
|
- "password": "******"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**（对应 `sys_user` + `sys_role`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "登录成功",
|
|
|
- "data": {
|
|
|
- "token": "eyJhbGciOiJIUzI1NiJ9...",
|
|
|
- "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
|
|
|
- "expiresIn": 7200,
|
|
|
- "user": {
|
|
|
- "userId": 1001,
|
|
|
- "userName": "operator01",
|
|
|
- "nickName": "张三",
|
|
|
- "phonenumber": "13800138000",
|
|
|
- "deptId": 101,
|
|
|
- "tenantId": 1,
|
|
|
- "status": "0",
|
|
|
- "roles": [
|
|
|
- { "roleId": 10, "roleName": "运营人员", "roleKey": "vpp:operator" }
|
|
|
- ],
|
|
|
- "permissions": ["dashboard:view", "alarm:manage"]
|
|
|
- }
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> `permissions` 由 `sys_role_menu` 关联的 `sys_menu.perms` 聚合得到。
|
|
|
-
|
|
|
-#### 2.2.2 刷新 Token
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/auth/refresh`
|
|
|
-
|
|
|
-**功能描述**：使用 refreshToken 换取新的 accessToken。
|
|
|
-
|
|
|
-**权限**：公开（需有效 refreshToken）
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| refreshToken | string | 是 | 登录时返回的刷新令牌 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "refreshToken": "eyJhbGciOiJIUzI1NiJ9..."
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "刷新成功",
|
|
|
- "data": {
|
|
|
- "token": "eyJhbGciOiJIUzI1NiJ9...",
|
|
|
- "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
|
|
|
- "expiresIn": 7200
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.2.3 退出登录
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/auth/logout`
|
|
|
-
|
|
|
-**功能描述**：注销当前会话，使 Token 失效。
|
|
|
-
|
|
|
-**权限**：已登录用户
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "退出成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.2.4 获取当前用户信息
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/auth/me`
|
|
|
-
|
|
|
-**功能描述**：获取当前登录用户详情及权限列表。
|
|
|
-
|
|
|
-**权限**：已登录用户
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**（对应 `sys_user` + `sys_role` + `sys_menu`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": {
|
|
|
- "userId": 1001,
|
|
|
- "userName": "operator01",
|
|
|
- "nickName": "张三",
|
|
|
- "phonenumber": "13800138000",
|
|
|
- "email": "zhangsan@example.com",
|
|
|
- "deptId": 101,
|
|
|
- "tenantId": 1,
|
|
|
- "status": "0",
|
|
|
- "roles": [
|
|
|
- { "roleId": 10, "roleName": "运营人员", "roleKey": "vpp:operator" }
|
|
|
- ],
|
|
|
- "permissions": ["dashboard:view", "alarm:manage", "customer:view"]
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.3 首页与看板
|
|
|
-
|
|
|
-#### 2.3.1 首页核心指标
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dashboard/summary`
|
|
|
-
|
|
|
-**功能描述**：获取首页核心运营指标汇总。
|
|
|
-
|
|
|
-**权限**：`dashboard:view`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data 字段**（聚合 `vpp_energy_summary_daily`、`vpp_device`、`base_alarm`、`vpp_dr_event`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| todayGenKwh | number | 今日发电量 kWh |
|
|
|
-| todayUseKwh | number | 今日用电量 kWh |
|
|
|
-| todayRevenue | number | 今日收益（元） |
|
|
|
-| onlineDeviceCount | int | 在线设备数 |
|
|
|
-| pendingAlarmCount | int | 待处理告警数 |
|
|
|
-| activeDrEventCount | int | 进行中需求响应事件数 |
|
|
|
-
|
|
|
-**响应 data**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "todayGenKwh": 12580.5,
|
|
|
- "todayUseKwh": 9820.3,
|
|
|
- "todayRevenue": 15680.0,
|
|
|
- "onlineDeviceCount": 128,
|
|
|
- "pendingAlarmCount": 5,
|
|
|
- "activeDrEventCount": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.3.2 GIS 资源分布
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dashboard/map`
|
|
|
-
|
|
|
-**功能描述**：获取资源点地理分布及实时状态，用于 GIS 地图展示。
|
|
|
-
|
|
|
-**权限**：`dashboard:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceType | string | 否 | 资源类型：PV/ESS/EVCS/IND_LOAD/COM_BLDG |
|
|
|
-| runStatus | int | 否 | 运行状态：0离线 1在线 2故障 3维护 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_resource_point` + 实时功率）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| resourceId | long | 资源点 ID |
|
|
|
-| resourceCode | string | 资源编号 |
|
|
|
-| resourceName | string | 资源名称 |
|
|
|
-| resourceType | string | 资源类型 |
|
|
|
-| longitude | number | 经度 |
|
|
|
-| latitude | number | 纬度 |
|
|
|
-| runStatus | int | 运行状态 |
|
|
|
-| activePowerKw | number | 当前有功功率 kW |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "resourceId": 10001,
|
|
|
- "resourceCode": "RES-001",
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "resourceType": "PV",
|
|
|
- "longitude": 121.544379,
|
|
|
- "latitude": 31.221517,
|
|
|
- "runStatus": 1,
|
|
|
- "activePowerKw": 320.5
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.3.3 实时曲线
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dashboard/curve`
|
|
|
-
|
|
|
-**功能描述**：获取首页实时/历史曲线数据。
|
|
|
-
|
|
|
-**权限**：`dashboard:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| type | string | 是 | 曲线类型：load（负荷）/ pv（发电）/ soc（储能 SOC） |
|
|
|
-| date | string | 否 | 日期，格式 YYYY-MM-DD，默认当天 |
|
|
|
-| resourceId | long | 否 | 资源点 ID，不传则全站汇总 |
|
|
|
-
|
|
|
-**响应 data**（数据来源 TDengine `vpp_device_metrics`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "type": "pv",
|
|
|
- "date": "2026-06-23",
|
|
|
- "points": [
|
|
|
- { "time": "2026-06-23T00:00:00", "value": 0.0 },
|
|
|
- { "time": "2026-06-23T08:00:00", "value": 120.5 },
|
|
|
- { "time": "2026-06-23T12:00:00", "value": 450.8 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| type | string | 曲线类型 |
|
|
|
-| date | string | 查询日期 |
|
|
|
-| points | array | 时序数据点 |
|
|
|
-| points[].time | string | 时间点（ISO 8601） |
|
|
|
-| points[].value | number | 指标值 |
|
|
|
-
|
|
|
-#### 2.3.4 资源概览统计
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/resource/overview`
|
|
|
-
|
|
|
-**功能描述**：按资源类型统计资源点数量、容量及在线率。
|
|
|
-
|
|
|
-**权限**：`resource:view`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data**（聚合 `vpp_resource_point`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "totalCount": 56,
|
|
|
- "totalCapacityKw": 28500.0,
|
|
|
- "onlineRate": 0.92,
|
|
|
- "byType": [
|
|
|
- { "resourceType": "PV", "count": 20, "capacityKw": 12000.0, "onlineCount": 19 },
|
|
|
- { "resourceType": "ESS", "count": 8, "capacityKw": 5000.0, "onlineCount": 7 },
|
|
|
- { "resourceType": "EVCS", "count": 15, "capacityKw": 6500.0, "onlineCount": 14 },
|
|
|
- { "resourceType": "IND_LOAD", "count": 10, "capacityKw": 4000.0, "onlineCount": 9 },
|
|
|
- { "resourceType": "COM_BLDG", "count": 3, "capacityKw": 1000.0, "onlineCount": 3 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.4 客户管理
|
|
|
-
|
|
|
-#### 2.4.1 提交准入申请
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/customer/access`
|
|
|
-
|
|
|
-**功能描述**：提交客户准入申请。
|
|
|
-
|
|
|
-**权限**：`customer:access:create`
|
|
|
-
|
|
|
-**请求体**（映射 `vpp_customer_access`）：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| accountNo | string | 是 | 电力户号 |
|
|
|
-| customerName | string | 是 | 客户名称 |
|
|
|
-| customerType | int | 是 | 1高压 2低压商用 3居民充电桩 4自有资产 |
|
|
|
-| powerCompany | string | 是 | 供电公司简称 |
|
|
|
-| contractCapacity | number | 是 | 用电容量 kVA/kW |
|
|
|
-| businessLicenseUrl | string | 否 | 营业执照附件 URL |
|
|
|
-| creditStatus | int | 否 | 1正常 2关注 3不良 |
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "accountNo": "3100060012345",
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "customerType": 2,
|
|
|
- "powerCompany": "市北",
|
|
|
- "contractCapacity": 500.0,
|
|
|
- "businessLicenseUrl": "https://oss.example.com/license.pdf",
|
|
|
- "creditStatus": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "提交成功",
|
|
|
- "data": {
|
|
|
- "id": 5001,
|
|
|
- "applyNo": "ACC-202606230001",
|
|
|
- "accessStatus": 0,
|
|
|
- "applyAt": "2026-06-23T09:30:00"
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.4.2 准入申请列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/customer/access`
|
|
|
-
|
|
|
-**功能描述**：分页查询准入申请列表。
|
|
|
-
|
|
|
-**权限**：`customer:access:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| accessStatus | int | 否 | 0待审核 1通过 2驳回 |
|
|
|
-| applyAtStart | string | 否 | 申请开始时间 |
|
|
|
-| applyAtEnd | string | 否 | 申请结束时间 |
|
|
|
-| current | int | 否 | 页码，默认 1 |
|
|
|
-| size | int | 否 | 每页数量，默认 10 |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 5001,
|
|
|
- "applyNo": "ACC-202606230001",
|
|
|
- "accountNo": "3100060012345",
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "customerType": 2,
|
|
|
- "powerCompany": "市北",
|
|
|
- "contractCapacity": 500.0,
|
|
|
- "accessStatus": 0,
|
|
|
- "auditOpinion": null,
|
|
|
- "auditAt": null,
|
|
|
- "customerId": null,
|
|
|
- "applyAt": "2026-06-23T09:30:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_customer_access`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 准入申请 ID | id |
|
|
|
-| applyNo | string | 申请编号 | apply_no |
|
|
|
-| accountNo | string | 电力户号 | account_no |
|
|
|
-| customerName | string | 客户名称 | customer_name |
|
|
|
-| customerType | int | 1高压 2低压商用 3居民充电桩 4自有资产 | customer_type |
|
|
|
-| powerCompany | string | 供电公司简称 | power_company |
|
|
|
-| contractCapacity | number | 用电容量 kVA/kW | contract_capacity |
|
|
|
-| accessStatus | int | 0待审核 1通过 2驳回 | access_status |
|
|
|
-| auditOpinion | string/null | 审核意见 | audit_opinion |
|
|
|
-| auditAt | string/null | 审核时间 | audit_at |
|
|
|
-| customerId | long/null | 通过后关联的客户 ID | customer_id |
|
|
|
-| applyAt | string | 申请时间 | apply_at |
|
|
|
-
|
|
|
-#### 2.4.3 准入审核
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/customer/access/{id}/audit`
|
|
|
-
|
|
|
-**功能描述**：审核准入申请；通过时自动创建 `vpp_customer` 记录。
|
|
|
-
|
|
|
-**权限**：`customer:access:audit`
|
|
|
-
|
|
|
-**路径参数**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| id | long | 是 | 准入申请 ID |
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "passed": true,
|
|
|
- "auditOpinion": "资质齐全，准予准入"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| passed | boolean | 是 | true 通过 / false 驳回 |
|
|
|
-| auditOpinion | string | 否 | 审核意见 |
|
|
|
-
|
|
|
-**响应示例**（通过时）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "审核通过",
|
|
|
- "data": {
|
|
|
- "id": 5001,
|
|
|
- "accessStatus": 1,
|
|
|
- "customerId": 1001,
|
|
|
- "auditAt": "2026-06-23T10:00:00"
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.4.4 客户列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/customer`
|
|
|
-
|
|
|
-**功能描述**：分页查询客户档案列表。
|
|
|
-
|
|
|
-**权限**：`customer:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| customerName | string | 否 | 客户名称（模糊） |
|
|
|
-| accountNo | string | 否 | 电力户号 |
|
|
|
-| lifecycleStatus | int | 否 | 1待准入 2已准入 3已签约 4履约中 5待续约 6已续约 7已解约 |
|
|
|
-| customerType | int | 否 | 客户类型 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_customer`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 1001,
|
|
|
- "accountNo": "3100060012345",
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "customerType": 2,
|
|
|
- "powerCompany": "市北",
|
|
|
- "contractCapacity": 500.0,
|
|
|
- "creditStatus": 1,
|
|
|
- "lifecycleStatus": 4,
|
|
|
- "province": "上海市",
|
|
|
- "city": "上海市",
|
|
|
- "district": "浦东新区",
|
|
|
- "createTime": "2026-06-23T10:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_customer`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 客户 ID | id |
|
|
|
-| accountNo | string | 电力户号，全局唯一 | account_no |
|
|
|
-| customerName | string | 客户名称 | customer_name |
|
|
|
-| customerType | int | 客户类型 | customer_type |
|
|
|
-| powerCompany | string | 供电公司简称 | power_company |
|
|
|
-| contractCapacity | number | 用电容量 | contract_capacity |
|
|
|
-| creditStatus | int | 1正常 2关注 3不良 | credit_status |
|
|
|
-| lifecycleStatus | int | 生命周期状态（见 §2.4.4 查询参数） | lifecycle_status |
|
|
|
-| province | string | 省 | province |
|
|
|
-| city | string | 市 | city |
|
|
|
-| district | string | 区 | district |
|
|
|
-| createTime | string | 创建时间 | create_time |
|
|
|
-
|
|
|
-#### 2.4.5 客户详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/customer/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取客户详情，含联系人、合同数、资源点数及需求响应能力。
|
|
|
-
|
|
|
-**权限**：`customer:view`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 1001,
|
|
|
- "accountNo": "3100060012345",
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "customerType": 2,
|
|
|
- "powerCompany": "市北",
|
|
|
- "contractCapacity": 500.0,
|
|
|
- "creditStatus": 1,
|
|
|
- "lifecycleStatus": 4,
|
|
|
- "drNotifyMinutes": 30,
|
|
|
- "drUpCapacityKw": 200.0,
|
|
|
- "drDownCapacityKw": 300.0,
|
|
|
- "province": "上海市",
|
|
|
- "city": "上海市",
|
|
|
- "district": "浦东新区",
|
|
|
- "address": "张江路100号",
|
|
|
- "businessLicenseUrl": "https://oss.example.com/license.pdf",
|
|
|
- "remark": null,
|
|
|
- "contacts": [
|
|
|
- {
|
|
|
- "id": 2001,
|
|
|
- "contactName": "李四",
|
|
|
- "contactPhone": "13800138000",
|
|
|
- "contactEmail": "lisi@example.com",
|
|
|
- "isPrimary": 1,
|
|
|
- "position": "电气负责人"
|
|
|
- }
|
|
|
- ],
|
|
|
- "contractCount": 2,
|
|
|
- "resourceCount": 3,
|
|
|
- "createTime": "2026-06-23T10:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**（在列表字段基础上扩展）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| drNotifyMinutes | int | 需求响应提前通知分钟数，默认 30 | dr_notify_minutes |
|
|
|
-| drUpCapacityKw | number | 登记上调能力 kW | dr_up_capacity_kw |
|
|
|
-| drDownCapacityKw | number | 登记下调能力 kW | dr_down_capacity_kw |
|
|
|
-| address | string | 详细地址 | address |
|
|
|
-| businessLicenseUrl | string | 营业执照附件 URL | business_license_url |
|
|
|
-| remark | string/null | 备注 | remark |
|
|
|
-| contacts | array | 联系人列表，元素见 §2.4.7 | vpp_customer_contact |
|
|
|
-| contractCount | int | 关联合同数（聚合） | — |
|
|
|
-| resourceCount | int | 关联资源点数（聚合） | — |
|
|
|
-
|
|
|
-#### 2.4.6 更新客户
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/customer/{id}`
|
|
|
-
|
|
|
-**功能描述**：更新客户档案信息。
|
|
|
-
|
|
|
-**权限**：`customer:edit`
|
|
|
-
|
|
|
-**请求体**（字段均可选，映射 `vpp_customer`）：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| customerName | string | 否 | 客户名称 | customer_name |
|
|
|
-| creditStatus | int | 否 | 1正常 2关注 3不良 | credit_status |
|
|
|
-| lifecycleStatus | int | 否 | 生命周期状态 | lifecycle_status |
|
|
|
-| drNotifyMinutes | int | 否 | 提前通知分钟数 | dr_notify_minutes |
|
|
|
-| drUpCapacityKw | number | 否 | 上调能力 kW | dr_up_capacity_kw |
|
|
|
-| drDownCapacityKw | number | 否 | 下调能力 kW | dr_down_capacity_kw |
|
|
|
-| province | string | 否 | 省 | province |
|
|
|
-| city | string | 否 | 市 | city |
|
|
|
-| district | string | 否 | 区 | district |
|
|
|
-| address | string | 否 | 详细地址 | address |
|
|
|
-| remark | string | 否 | 备注 | remark |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "creditStatus": 1,
|
|
|
- "lifecycleStatus": 4,
|
|
|
- "drNotifyMinutes": 30,
|
|
|
- "drUpCapacityKw": 200.0,
|
|
|
- "drDownCapacityKw": 300.0,
|
|
|
- "province": "上海市",
|
|
|
- "city": "上海市",
|
|
|
- "district": "浦东新区",
|
|
|
- "address": "张江路100号",
|
|
|
- "remark": "重点客户"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "更新成功",
|
|
|
- "data": { "id": 1001 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.4.7 客户联系人管理
|
|
|
-
|
|
|
-**数据表**：`vpp_customer_contact`
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/customer/{id}/contact` | 联系人列表 |
|
|
|
-| POST | `/prod-api/service-vpp/customer/{id}/contact` | 新增联系人 |
|
|
|
-| PUT | `/prod-api/service-vpp/customer/{id}/contact/{contactId}` | 更新联系人 |
|
|
|
-| DELETE | `/prod-api/service-vpp/customer/{id}/contact/{contactId}` | 删除联系人 |
|
|
|
-
|
|
|
-**新增/更新请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| contactName | string | 是 | 联系人姓名 |
|
|
|
-| contactPhone | string | 是 | 联系电话 |
|
|
|
-| contactEmail | string | 否 | 邮箱 |
|
|
|
-| isPrimary | int | 是 | 是否主联系人：0否 1是 |
|
|
|
-| position | string | 否 | 职务 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "contactName": "李四",
|
|
|
- "contactPhone": "13800138000",
|
|
|
- "contactEmail": "lisi@example.com",
|
|
|
- "isPrimary": 1,
|
|
|
- "position": "电气负责人"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**列表响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-[
|
|
|
- {
|
|
|
- "id": 2001,
|
|
|
- "customerId": 1001,
|
|
|
- "contactName": "李四",
|
|
|
- "contactPhone": "13800138000",
|
|
|
- "contactEmail": "lisi@example.com",
|
|
|
- "isPrimary": 1,
|
|
|
- "position": "电气负责人"
|
|
|
- }
|
|
|
-]
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.5 合同管理
|
|
|
-
|
|
|
-#### 2.5.1 合同模板列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/contract/template`
|
|
|
-
|
|
|
-**功能描述**：查询合同模板列表。
|
|
|
-
|
|
|
-**权限**：`contract:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| contractType | int | 否 | 1购售电 2需求响应合作 3聚合代理 4服务代理 5居民充电桩 6自有资产 |
|
|
|
-| isEnabled | int | 否 | 是否启用：0否 1是 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_contract_template`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 10,
|
|
|
- "templateCode": "DR_COOP_V1",
|
|
|
- "templateName": "需求响应合作协议模板",
|
|
|
- "contractType": 2,
|
|
|
- "version": "1.0",
|
|
|
- "fileUrl": "https://oss.example.com/template/dr_coop.docx",
|
|
|
- "variablesJson": { "customerName": "客户名称", "shareRatio": "分成比例" },
|
|
|
- "isEnabled": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_contract_template`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 模板 ID | id |
|
|
|
-| templateCode | string | 模板编码 | template_code |
|
|
|
-| templateName | string | 模板名称 | template_name |
|
|
|
-| contractType | int | 合同类型 | contract_type |
|
|
|
-| version | string | 版本号 | version |
|
|
|
-| fileUrl | string | 模板文件 URL | file_url |
|
|
|
-| variablesJson | object | 模板变量占位符定义 | variables_json |
|
|
|
-| isEnabled | int | 0禁用 1启用 | is_enabled |
|
|
|
-
|
|
|
-#### 2.5.2 创建合同
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/contract`
|
|
|
-
|
|
|
-**功能描述**：创建合同草稿。
|
|
|
-
|
|
|
-**权限**：`contract:create`
|
|
|
-
|
|
|
-**数据表**：`vpp_contract`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "customerId": 1001,
|
|
|
- "templateId": 10,
|
|
|
- "contractType": 2,
|
|
|
- "contractName": "需求响应合作协议",
|
|
|
- "signDate": "2026-01-15",
|
|
|
- "effectiveDate": "2026-01-15",
|
|
|
- "expireDate": "2026-12-31",
|
|
|
- "shareRatio": 70.0,
|
|
|
- "priceJson": {},
|
|
|
- "fileUrl": "https://oss.example.com/contract.pdf"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| customerId | long | 是 | 客户 ID |
|
|
|
-| templateId | long | 否 | 模板 ID |
|
|
|
-| contractType | int | 是 | 合同类型 |
|
|
|
-| contractName | string | 是 | 合同名称 |
|
|
|
-| signDate | string | 否 | 签订日期 YYYY-MM-DD |
|
|
|
-| effectiveDate | string | 否 | 生效日期 |
|
|
|
-| expireDate | string | 否 | 到期日期 |
|
|
|
-| shareRatio | number | 否 | 分成比例% |
|
|
|
-| priceJson | object | 否 | 电价条款 JSON |
|
|
|
-| accountInfoJson | object | 否 | 分成账户信息 |
|
|
|
-| fileUrl | string | 否 | 合同文件 URL |
|
|
|
-| remark | string | 否 | 备注 |
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "创建成功",
|
|
|
- "data": {
|
|
|
- "id": 3001,
|
|
|
- "contractNo": "CT-202601150001",
|
|
|
- "contractStatus": 0
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> 合同附件除 `fileUrl` 外，建议通过 `POST /prod-api/service-vpp/archive` 写入 `vpp_file_archive`（`bizType=CONTRACT`，`bizId=合同ID`），便于多附件管理。
|
|
|
-
|
|
|
-#### 2.5.3 合同列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/contract`
|
|
|
-
|
|
|
-**功能描述**：分页查询合同列表。
|
|
|
-
|
|
|
-**权限**：`contract:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| contractNo | string | 否 | 合同编号 |
|
|
|
-| customerName | string | 否 | 客户名称（模糊） |
|
|
|
-| accountNo | string | 否 | 电力户号 |
|
|
|
-| contractStatus | int | 否 | 0草稿 1审核中 2已生效 3已到期 4已终止 |
|
|
|
-| contractType | int | 否 | 合同类型 |
|
|
|
-| signDateStart | string | 否 | 签订日期起 |
|
|
|
-| signDateEnd | string | 否 | 签订日期止 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_contract`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 3001,
|
|
|
- "contractNo": "CT-202601150001",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "contractType": 2,
|
|
|
- "contractName": "需求响应合作协议",
|
|
|
- "contractStatus": 2,
|
|
|
- "signDate": "2026-01-15",
|
|
|
- "effectiveDate": "2026-01-15",
|
|
|
- "expireDate": "2026-12-31",
|
|
|
- "shareRatio": 70.0
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_contract`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 合同 ID | id |
|
|
|
-| contractNo | string | 合同编号 | contract_no |
|
|
|
-| customerId | long | 客户 ID | customer_id |
|
|
|
-| customerName | string | 客户名称（关联） | — |
|
|
|
-| contractType | int | 合同类型 | contract_type |
|
|
|
-| contractName | string | 合同名称 | contract_name |
|
|
|
-| contractStatus | int | 0草稿 1审核中 2已生效 3已到期 4已终止 | contract_status |
|
|
|
-| signDate | string | 签订日期 YYYY-MM-DD | sign_date |
|
|
|
-| effectiveDate | string | 生效日期 | effective_date |
|
|
|
-| expireDate | string | 到期日期 | expire_date |
|
|
|
-| shareRatio | number | 分成比例 % | share_ratio |
|
|
|
-
|
|
|
-#### 2.5.4 合同详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/contract/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取合同详情及审核流水。
|
|
|
-
|
|
|
-**权限**：`contract:view`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 3001,
|
|
|
- "contractNo": "CT-202601150001",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "templateId": 10,
|
|
|
- "contractType": 2,
|
|
|
- "contractName": "需求响应合作协议",
|
|
|
- "contractStatus": 2,
|
|
|
- "signDate": "2026-01-15",
|
|
|
- "effectiveDate": "2026-01-15",
|
|
|
- "expireDate": "2026-12-31",
|
|
|
- "fileUrl": "https://oss.example.com/contract.pdf",
|
|
|
- "shareRatio": 70.0,
|
|
|
- "priceJson": { "peakPrice": 1.2, "valleyPrice": 0.4 },
|
|
|
- "accountInfoJson": { "bankName": "工商银行", "accountNo": "6222****" },
|
|
|
- "remark": null,
|
|
|
- "auditLogs": [
|
|
|
- {
|
|
|
- "action": 1,
|
|
|
- "opinion": "提交审核",
|
|
|
- "operatorName": "张三",
|
|
|
- "operatedAt": "2026-01-10T10:00:00"
|
|
|
- },
|
|
|
- {
|
|
|
- "action": 2,
|
|
|
- "opinion": "审核通过",
|
|
|
- "operatorName": "李四",
|
|
|
- "operatedAt": "2026-01-12T14:00:00"
|
|
|
- }
|
|
|
- ],
|
|
|
- "archives": [
|
|
|
- { "id": 5001, "fileName": "需求响应合作协议.pdf", "fileUrl": "https://oss.example.com/contract.pdf" }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**（在列表字段基础上扩展）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| templateId | long | 模板 ID | template_id |
|
|
|
-| fileUrl | string | 合同文件 URL | file_url |
|
|
|
-| priceJson | object | 电价条款 JSON | price_json |
|
|
|
-| accountInfoJson | object | 分成账户信息 JSON | account_info_json |
|
|
|
-| remark | string/null | 备注 | remark |
|
|
|
-| auditLogs | array | 审核流水 | vpp_contract_audit_log |
|
|
|
-| auditLogs[].action | int | 1提交 2通过 3驳回 4归档 | action |
|
|
|
-| auditLogs[].opinion | string | 审核意见 | opinion |
|
|
|
-| auditLogs[].operatorName | string | 操作人姓名 | created_by |
|
|
|
-| auditLogs[].operatedAt | string | 操作时间 | create_time |
|
|
|
-| archives | array | 电子档案列表 | vpp_file_archive |
|
|
|
-
|
|
|
-#### 2.5.5 提交合同审核
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/contract/{id}/submit`
|
|
|
-
|
|
|
-**功能描述**：将草稿合同提交审核，`contractStatus` 变更为 1。
|
|
|
-
|
|
|
-**权限**：`contract:submit`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "提交成功",
|
|
|
- "data": { "id": 3001, "contractStatus": 1 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.5.6 合同审核
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/contract/{id}/audit`
|
|
|
-
|
|
|
-**功能描述**：审核合同，写入 `vpp_contract_audit_log`。
|
|
|
-
|
|
|
-**权限**：`contract:audit`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| passed | boolean | 是 | true 通过 / false 驳回 |
|
|
|
-| opinion | string | 否 | 审核意见 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "passed": true,
|
|
|
- "opinion": "审核通过"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "审核通过",
|
|
|
- "data": { "id": 3001, "contractStatus": 2 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.5.7 合同归档
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/contract/{id}/archive`
|
|
|
-
|
|
|
-**功能描述**：合同归档，写入审核流水（action=4）。
|
|
|
-
|
|
|
-**权限**：`contract:archive`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "归档成功",
|
|
|
- "data": { "id": 3001 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.6 资源管理
|
|
|
-
|
|
|
-#### 2.6.1 资源点列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/resource`
|
|
|
-
|
|
|
-**功能描述**：分页查询资源点列表。
|
|
|
-
|
|
|
-**权限**：`resource:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceName | string | 否 | 资源名称（模糊） |
|
|
|
-| resourceCode | string | 否 | 资源编号 |
|
|
|
-| resourceType | string | 否 | PV/ESS/EVCS/IND_LOAD/COM_BLDG |
|
|
|
-| district | string | 否 | 区/区域 |
|
|
|
-| runStatus | int | 否 | 0离线 1在线 2故障 3维护 |
|
|
|
-| customerId | long | 否 | 所属客户 ID |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_resource_point`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 2001,
|
|
|
- "resourceCode": "RES-PV-001",
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "resourceType": "PV",
|
|
|
- "capacityKw": 500.0,
|
|
|
- "adjustableKw": 0,
|
|
|
- "district": "浦东新区",
|
|
|
- "runStatus": 1,
|
|
|
- "responsePriority": 5,
|
|
|
- "createTime": "2026-01-20T10:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_resource_point`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 资源点 ID | id |
|
|
|
-| resourceCode | string | 资源编号，全局唯一 | resource_code |
|
|
|
-| resourceName | string | 资源名称 | resource_name |
|
|
|
-| customerId | long | 所属客户 ID | customer_id |
|
|
|
-| customerName | string | 客户名称（关联查询） | — |
|
|
|
-| resourceType | string | PV/ESS/EVCS/IND_LOAD/COM_BLDG | resource_type |
|
|
|
-| capacityKw | number | 装机容量 kW | capacity_kw |
|
|
|
-| adjustableKw | number | 可调容量 kW | adjustable_kw |
|
|
|
-| district | string | 区/区域 | district |
|
|
|
-| runStatus | int | 0离线 1在线 2故障 3维护 | run_status |
|
|
|
-| responsePriority | int | 响应优先级 1-10 | response_priority |
|
|
|
-| createTime | string | 创建时间 | create_time |
|
|
|
-
|
|
|
-#### 2.6.2 资源看板（实时）
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/resource/board`
|
|
|
-
|
|
|
-**功能描述**：获取资源点实时运行看板数据（Redis 缓存 + TDengine）。
|
|
|
-
|
|
|
-**权限**：`resource:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceType | string | 否 | 资源类型 |
|
|
|
-| district | string | 否 | 区/区域 |
|
|
|
-| runStatus | int | 否 | 运行状态 |
|
|
|
-| customerId | long | 否 | 客户 ID |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceCode": "RES-PV-001",
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "resourceType": "PV",
|
|
|
- "runStatus": 1,
|
|
|
- "activePowerKw": 320.5,
|
|
|
- "voltage": 380.0,
|
|
|
- "current": 520.3,
|
|
|
- "soc": null,
|
|
|
- "evChargePowerKw": null,
|
|
|
- "abnormal": false
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| resourceId | long | 资源点 ID |
|
|
|
-| resourceCode | string | 资源编号 |
|
|
|
-| resourceName | string | 资源名称 |
|
|
|
-| resourceType | string | 资源类型 |
|
|
|
-| runStatus | int | 运行状态 |
|
|
|
-| activePowerKw | number | 当前有功功率 kW（实时） |
|
|
|
-| voltage | number | 电压 V |
|
|
|
-| current | number | 电流 A |
|
|
|
-| soc | number/null | 储能 SOC%，非储能资源为 null |
|
|
|
-| evChargePowerKw | number/null | 充电桩充电功率 kW |
|
|
|
-| abnormal | boolean | 是否异常（超阈值/离线超时等） |
|
|
|
-
|
|
|
-#### 2.6.3 新增资源点
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/resource`
|
|
|
-
|
|
|
-**功能描述**：新增资源点及运行参数配置。
|
|
|
-
|
|
|
-**权限**：`resource:create`
|
|
|
-
|
|
|
-**数据表**：`vpp_resource_point` + `vpp_resource_point_config`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| resourceCode | string | 是 | 资源编号 | resource_code |
|
|
|
-| resourceName | string | 是 | 资源名称 | resource_name |
|
|
|
-| customerId | long | 是 | 所属客户 ID | customer_id |
|
|
|
-| resourceType | string | 是 | PV/ESS/EVCS/IND_LOAD/COM_BLDG | resource_type |
|
|
|
-| capacityKw | number | 是 | 装机容量 kW | capacity_kw |
|
|
|
-| adjustableKw | number | 否 | 可调容量 kW | adjustable_kw |
|
|
|
-| province | string | 否 | 省 | province |
|
|
|
-| city | string | 否 | 市 | city |
|
|
|
-| district | string | 否 | 区/区域 | district |
|
|
|
-| address | string | 否 | 地址 | address |
|
|
|
-| longitude | number | 否 | 经度 | longitude |
|
|
|
-| latitude | number | 否 | 纬度 | latitude |
|
|
|
-| ownerName | string | 否 | 业主名称 | owner_name |
|
|
|
-| contactName | string | 否 | 联系人 | contact_name |
|
|
|
-| contactPhone | string | 否 | 联系电话 | contact_phone |
|
|
|
-| responsePriority | int | 否 | 响应优先级 1-10 | response_priority |
|
|
|
-| config | object | 否 | 运行参数配置，见下表 | vpp_resource_point_config |
|
|
|
-| config.collectIntervalSec | int | 否 | 采集间隔（秒） | collect_interval_sec |
|
|
|
-| config.powerUpperLimit | number | 否 | 功率上限 kW | power_upper_limit |
|
|
|
-| config.powerLowerLimit | number | 否 | 功率下限 kW | power_lower_limit |
|
|
|
-| config.socUpperLimit | number | 否 | SOC 上限 % | soc_upper_limit |
|
|
|
-| config.socLowerLimit | number | 否 | SOC 下限 % | soc_lower_limit |
|
|
|
-| config.offlineTimeoutSec | int | 否 | 离线判定超时（秒） | offline_timeout_sec |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "resourceCode": "RES-PV-001",
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "customerId": 1001,
|
|
|
- "resourceType": "PV",
|
|
|
- "capacityKw": 500.0,
|
|
|
- "adjustableKw": 0,
|
|
|
- "province": "上海市",
|
|
|
- "city": "上海市",
|
|
|
- "district": "浦东新区",
|
|
|
- "address": "张江路100号",
|
|
|
- "longitude": 121.544379,
|
|
|
- "latitude": 31.221517,
|
|
|
- "ownerName": "上海某某有限公司",
|
|
|
- "contactName": "李四",
|
|
|
- "contactPhone": "13800138000",
|
|
|
- "responsePriority": 5,
|
|
|
- "config": {
|
|
|
- "collectIntervalSec": 900,
|
|
|
- "powerUpperLimit": 550.0,
|
|
|
- "offlineTimeoutSec": 300
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "创建成功",
|
|
|
- "data": { "id": 2001, "resourceCode": "RES-PV-001" },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.6.4 更新/删除资源点
|
|
|
-
|
|
|
-**GET 资源详情** — `GET /prod-api/service-vpp/resource/{id}`
|
|
|
-
|
|
|
-**响应 data 示例**（`vpp_resource_point` + `vpp_resource_point_config`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 2001,
|
|
|
- "resourceCode": "RES-PV-001",
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "customerId": 1001,
|
|
|
- "resourceType": "PV",
|
|
|
- "capacityKw": 500.0,
|
|
|
- "adjustableKw": 0,
|
|
|
- "province": "上海市",
|
|
|
- "city": "上海市",
|
|
|
- "district": "浦东新区",
|
|
|
- "address": "张江路100号",
|
|
|
- "longitude": 121.544379,
|
|
|
- "latitude": 31.221517,
|
|
|
- "ownerName": "上海某某有限公司",
|
|
|
- "contactName": "李四",
|
|
|
- "contactPhone": "13800138000",
|
|
|
- "runStatus": 1,
|
|
|
- "responsePriority": 5,
|
|
|
- "unResourceId": null,
|
|
|
- "config": {
|
|
|
- "collectIntervalSec": 900,
|
|
|
- "powerUpperLimit": 550.0,
|
|
|
- "powerLowerLimit": null,
|
|
|
- "socUpperLimit": null,
|
|
|
- "socLowerLimit": null,
|
|
|
- "offlineTimeoutSec": 300
|
|
|
- },
|
|
|
- "devices": [
|
|
|
- { "id": 3001, "deviceCode": "DEV-INV-001", "deviceName": "1#逆变器", "commStatus": 1 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**（映射 `vpp_resource_point` + `vpp_resource_point_config`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 资源点 ID | id |
|
|
|
-| resourceCode | string | 资源编号 | resource_code |
|
|
|
-| resourceName | string | 资源名称 | resource_name |
|
|
|
-| customerId | long | 所属客户 ID | customer_id |
|
|
|
-| resourceType | string | 资源类型 | resource_type |
|
|
|
-| capacityKw | number | 装机容量 kW | capacity_kw |
|
|
|
-| adjustableKw | number | 可调容量 kW | adjustable_kw |
|
|
|
-| province/city/district/address | string | 地址信息 | province 等 |
|
|
|
-| longitude/latitude | number | 经纬度 | longitude/latitude |
|
|
|
-| ownerName | string | 业主名称 | owner_name |
|
|
|
-| contactName/contactPhone | string | 联系人信息 | contact_name/phone |
|
|
|
-| runStatus | int | 运行状态 | run_status |
|
|
|
-| responsePriority | int | 响应优先级 | response_priority |
|
|
|
-| unResourceId | string/null | 运管平台分路资源 ID | un_resource_id |
|
|
|
-| config | object | 运行参数配置 | vpp_resource_point_config |
|
|
|
-| devices | array | 关联设备列表，元素见 §2.6.5 | vpp_device |
|
|
|
-
|
|
|
-**PUT 更新资源** — `PUT /prod-api/service-vpp/resource/{id}`
|
|
|
-
|
|
|
-请求体字段同新增，均可选。
|
|
|
-
|
|
|
-**DELETE 软删除** — `DELETE /prod-api/service-vpp/resource/{id}`
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "删除成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.6.5 设备管理
|
|
|
-
|
|
|
-**数据表**：`vpp_device`（关联 `dmp_device`）
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/resource/{resourceId}/device` | 设备列表 |
|
|
|
-| POST | `/prod-api/service-vpp/resource/{resourceId}/device` | 新增设备 |
|
|
|
-| PUT | `/prod-api/service-vpp/device/{id}` | 更新设备 |
|
|
|
-| DELETE | `/prod-api/service-vpp/device/{id}` | 软删除 |
|
|
|
-
|
|
|
-**新增/更新请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| deviceCode | string | 是 | 设备编号（与 dmp_device.device_id 一致） |
|
|
|
-| deviceName | string | 是 | 设备名称 |
|
|
|
-| deviceType | string | 是 | INVERTER/PCS/EVCS/METER/Gateway 等 |
|
|
|
-| manufacturer | string | 否 | 厂商 |
|
|
|
-| model | string | 否 | 型号 |
|
|
|
-| ratedPowerKw | number | 否 | 额定功率 kW |
|
|
|
-| gatewayId | string | 否 | IoT 网关标识 |
|
|
|
-| registerDmp | boolean | 否 | 是否同步注册 dmp_device |
|
|
|
-| remark | string | 否 | 备注 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "deviceCode": "DEV-INV-001",
|
|
|
- "deviceName": "1#逆变器",
|
|
|
- "deviceType": "INVERTER",
|
|
|
- "manufacturer": "华为",
|
|
|
- "model": "SUN2000-50KTL",
|
|
|
- "ratedPowerKw": 50.0,
|
|
|
- "registerDmp": true
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**设备列表响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 3001,
|
|
|
- "deviceCode": "DEV-INV-001",
|
|
|
- "deviceName": "1#逆变器",
|
|
|
- "resourceId": 2001,
|
|
|
- "deviceType": "INVERTER",
|
|
|
- "manufacturer": "华为",
|
|
|
- "model": "SUN2000-50KTL",
|
|
|
- "ratedPowerKw": 50.0,
|
|
|
- "commStatus": 1,
|
|
|
- "runStatus": 1,
|
|
|
- "firmwareVersion": "V100R001",
|
|
|
- "lastOnlineAt": "2026-06-23T10:15:00",
|
|
|
- "dmpDeviceId": "DEV-INV-001",
|
|
|
- "dmpDeviceUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**设备对象关键字段**：
|
|
|
-
|
|
|
-| 字段 | 数据表 | 说明 |
|
|
|
-|------|--------|------|
|
|
|
-| deviceCode | vpp_device.device_code | 业务设备编码 |
|
|
|
-| dmpDeviceId | dmp_device.device_id | 物联网设备 ID（与 deviceCode 通常一致） |
|
|
|
-| dmpDeviceUuid | dmp_device.device_uuid | 物联网 UUID |
|
|
|
-| commStatus | dmp_device_status.device_status | 1 在线 / 2 离线 |
|
|
|
-
|
|
|
-#### 2.6.6 可调能力评估
|
|
|
-
|
|
|
-> **界面映射**：Web「可调能力评估」页（站点筛选、顶部汇总卡片、可调能力曲线、历史响应）。
|
|
|
-> **数据表**：`vpp_site`、`vpp_resource_point`、`vpp_device`、`vpp_dr_participation`、`vpp_dr_event`、`vpp_dr_evaluation`
|
|
|
-> **时序数据**：TDengine `device_metrics`（经 `service-tsdb` Feign 查询，子表 `_{device_uuid}`）
|
|
|
-
|
|
|
-**模块前缀**：`/prod-api/service-vpp/capability-eval`
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/capability-eval/summary` | 顶部汇总统计 |
|
|
|
-| GET | `/prod-api/service-vpp/capability-eval/load-curve` | 可调能力曲线（基线 vs 实际负荷） |
|
|
|
-| GET | `/prod-api/service-vpp/capability-eval/history` | 历史响应记录（分页） |
|
|
|
-
|
|
|
-**站点下拉**：复用 `GET /prod-api/service-vpp/site`（§2.6 站点管理）。
|
|
|
-
|
|
|
-**权限**：`resource:view`
|
|
|
-
|
|
|
-##### 2.6.6.1 顶部汇总统计
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/capability-eval/summary`
|
|
|
-
|
|
|
-**功能描述**：按站点（或全部站点）统计总资源/负荷类/储能类/发电类的户数与装机容量，并返回最大上调、最大下调能力。
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| siteId | long | 否 | 站点 ID；不传则统计全部站点 |
|
|
|
-
|
|
|
-**分类规则**：
|
|
|
-
|
|
|
-| category | 说明 | resource_type 映射 |
|
|
|
-|----------|------|------------------|
|
|
|
-| TOTAL | 总资源 | 全部 |
|
|
|
-| LOAD | 负荷类 | IND_LOAD、COM_BLDG、EVCS |
|
|
|
-| STORAGE | 储能类 | ESS |
|
|
|
-| GENERATION | 发电类 | PV |
|
|
|
-
|
|
|
-**最大上下调能力**：
|
|
|
-
|
|
|
-- 优先汇总 TDengine 最新 `up_capacity_kw` / `down_capacity_kw`（在线设备，`vpp_device.device_uuid` 关联子表）
|
|
|
-- 无时序数据时回退 `vpp_resource_point.max_up_kw` / `min_down_kw`（`is_control=1`）
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "siteId": 1,
|
|
|
- "siteName": "示范站点",
|
|
|
- "total": {
|
|
|
- "category": "TOTAL",
|
|
|
- "categoryLabel": "总资源",
|
|
|
- "customerCount": 3,
|
|
|
- "capacityKw": 5500.0
|
|
|
- },
|
|
|
- "load": {
|
|
|
- "category": "LOAD",
|
|
|
- "categoryLabel": "负荷类",
|
|
|
- "customerCount": 3,
|
|
|
- "capacityKw": 3300.0
|
|
|
- },
|
|
|
- "storage": {
|
|
|
- "category": "STORAGE",
|
|
|
- "categoryLabel": "储能类",
|
|
|
- "customerCount": 1,
|
|
|
- "capacityKw": 1100.0
|
|
|
- },
|
|
|
- "generation": {
|
|
|
- "category": "GENERATION",
|
|
|
- "categoryLabel": "发电类",
|
|
|
- "customerCount": 1,
|
|
|
- "capacityKw": 1100.0
|
|
|
- },
|
|
|
- "maxUpKw": 120.0,
|
|
|
- "maxDownKw": 110.0
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| siteId | long | 站点 ID（全部站点时为 null） |
|
|
|
-| siteName | string | 站点名称；全部站点时为「全部站点」 |
|
|
|
-| total / load / storage / generation | object | 分类统计对象 |
|
|
|
-| *.category | string | TOTAL / LOAD / STORAGE / GENERATION |
|
|
|
-| *.categoryLabel | string | 分类中文名 |
|
|
|
-| *.customerCount | int | 户数（站点关联客户去重） |
|
|
|
-| *.capacityKw | number | 装机容量 kW（`capacity_kw` 汇总） |
|
|
|
-| maxUpKw | number | 最大上调能力 kW |
|
|
|
-| maxDownKw | number | 最大下调能力 kW |
|
|
|
-
|
|
|
-##### 2.6.6.2 可调能力曲线
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/capability-eval/load-curve`
|
|
|
-
|
|
|
-**功能描述**：返回指定日期的负荷曲线，用于「可调能力曲线」Tab。每 10 分钟一个点（`00:00` ~ `23:50`），对比基线负荷与实际负荷。
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| siteId | long | 否 | 站点 ID；不传则聚合全部站点资源 |
|
|
|
-| date | string | 否 | 统计日期 `yyyy-MM-dd`，默认当天 |
|
|
|
-
|
|
|
-**数据来源（dataSource）**：
|
|
|
-
|
|
|
-| 值 | 说明 |
|
|
|
-|----|------|
|
|
|
-| tsdb | 从 TDengine 查询实测有功功率并聚合 |
|
|
|
-| mock | 无 TSDB 数据时使用模拟曲线（联调兜底） |
|
|
|
-
|
|
|
-**TSDB 查询说明**：
|
|
|
-
|
|
|
-- 经 `service-tsdb` 的 `RemoteTsdbProxyService.queryHistoryDeviceData` 批量查询
|
|
|
-- 设备标识：`vpp_device.device_uuid`，子表 `_{device_uuid}`
|
|
|
-- 有功功率指标匹配顺序：`active_power` → `totalActivePower` → `totalactivepower` → `activepowera`
|
|
|
-- **实际负荷**：统计日各 10 分钟桶内多设备功率均值之和
|
|
|
-- **基线负荷**：7 日前同时段功率作为参考基线；若基线无数据则与实际负荷一致
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "siteId": 1,
|
|
|
- "siteName": "示范站点",
|
|
|
- "date": "2026-07-07",
|
|
|
- "dataSource": "tsdb",
|
|
|
- "points": [
|
|
|
- {
|
|
|
- "time": "11:40",
|
|
|
- "baselineLoadKw": 907.57,
|
|
|
- "actualLoadKw": 967.65
|
|
|
- },
|
|
|
- {
|
|
|
- "time": "11:50",
|
|
|
- "baselineLoadKw": 912.30,
|
|
|
- "actualLoadKw": 970.12
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| siteId | long | 站点 ID |
|
|
|
-| siteName | string | 站点名称 |
|
|
|
-| date | string | 统计日期 yyyy-MM-dd |
|
|
|
-| dataSource | string | tsdb / mock |
|
|
|
-| points | array | 曲线数据点 |
|
|
|
-| points[].time | string | 时刻 HH:mm |
|
|
|
-| points[].baselineLoadKw | number | 基线负荷 kW |
|
|
|
-| points[].actualLoadKw | number | 实际负荷 kW |
|
|
|
-
|
|
|
-##### 2.6.6.3 历史响应记录
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/capability-eval/history`
|
|
|
-
|
|
|
-**功能描述**：分页查询站点下资源曾参与的需求响应事件，用于「历史响应」Tab，按事件开始时间倒序。
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| siteId | long | 否 | 站点 ID；不传则查全部站点资源参与记录 |
|
|
|
-| current | int | 否 | 页码，默认 1 |
|
|
|
-| size | int | 否 | 每页数量，默认 10，最大 100 |
|
|
|
-
|
|
|
-**响应 data.records 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "records": [
|
|
|
- {
|
|
|
- "eventId": 1,
|
|
|
- "eventCode": "EVT_20260707_001",
|
|
|
- "eventName": "削峰响应",
|
|
|
- "eventType": 1,
|
|
|
- "eventTypeLabel": "削峰",
|
|
|
- "responseType": 1,
|
|
|
- "responseTypeLabel": "日前",
|
|
|
- "startTime": "2026-07-07T14:00:00",
|
|
|
- "endTime": "2026-07-07T16:00:00",
|
|
|
- "targetCapacityKw": 500.0,
|
|
|
- "actualCapacityKw": 480.0,
|
|
|
- "qualifiedRate": 96.0
|
|
|
- }
|
|
|
- ],
|
|
|
- "total": 1,
|
|
|
- "current": 1,
|
|
|
- "size": 10
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| eventId | long | 事件 ID | vpp_dr_event.id |
|
|
|
-| eventCode | string | 事件编码 | vpp_dr_event.event_id |
|
|
|
-| eventName | string | 事件名称 | vpp_dr_event.event_name |
|
|
|
-| eventType | int | 1削峰 2填谷 | vpp_dr_event.event_type |
|
|
|
-| eventTypeLabel | string | 事件类型中文 | — |
|
|
|
-| responseType | int | 1日前 2日内 3秒级 | vpp_dr_event.response_type |
|
|
|
-| responseTypeLabel | string | 响应类型中文 | — |
|
|
|
-| startTime | string | 响应开始时间 | vpp_dr_event.start_time |
|
|
|
-| endTime | string | 响应结束时间 | vpp_dr_event.end_time |
|
|
|
-| targetCapacityKw | number | 目标/出清容量 kW | cleared_capacity_kw 或 target_capacity_kw |
|
|
|
-| actualCapacityKw | number | 实际响应容量 kW | vpp_dr_evaluation.actual_capacity_kw |
|
|
|
-| qualifiedRate | number | 达标率 % | vpp_dr_evaluation.qualified_rate |
|
|
|
-
|
|
|
-> **与 §2.9.3 的区别**：§2.9.3 为**单个 DR 事件**的能力评估（参与前判断）；本节为**运营看板级**可调能力评估（按站点汇总资源分类、日负荷曲线与历史参与记录）。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.7 运行监控
|
|
|
-
|
|
|
-#### 2.7.1 实时监控数据
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/monitor/realtime`
|
|
|
-
|
|
|
-**功能描述**：获取资源点/设备实时监控数据。
|
|
|
-
|
|
|
-**权限**：`monitor:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceId | long | 否 | 资源点 ID（与 deviceId/customerId 三选一或组合） |
|
|
|
-| deviceId | long | 否 | 设备 ID |
|
|
|
-| customerId | long | 否 | 客户 ID，返回该客户下所有资源实时数据 |
|
|
|
-
|
|
|
-**响应 data**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "resourceId": 2001,
|
|
|
- "devices": [
|
|
|
- {
|
|
|
- "deviceId": 3001,
|
|
|
- "deviceCode": "DEV-INV-001",
|
|
|
- "commStatus": 1,
|
|
|
- "runStatus": 1,
|
|
|
- "activePowerKw": 320.5,
|
|
|
- "voltage": 380.0,
|
|
|
- "current": 520.3,
|
|
|
- "soc": null,
|
|
|
- "lastOnlineAt": "2026-06-23T10:15:00.000+08:00"
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.7.2 历史数据查询
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/monitor/history`
|
|
|
-
|
|
|
-**功能描述**：查询设备/资源历史运行数据（TDengine）。
|
|
|
-
|
|
|
-**权限**：`monitor:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceIds | string | 否 | 资源点 ID，逗号分隔 |
|
|
|
-| deviceIds | string | 否 | 设备 ID，逗号分隔 |
|
|
|
-| metrics | string | 是 | 指标名，逗号分隔，如 activePowerKw,voltage,soc |
|
|
|
-| startTime | string | 是 | 开始时间 ISO 8601 |
|
|
|
-| endTime | string | 是 | 结束时间 ISO 8601 |
|
|
|
-| granularity | string | 否 | 粒度：15m/1h/1d，默认 15m |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "deviceId": 3001,
|
|
|
- "deviceCode": "DEV-INV-001",
|
|
|
- "metric": "activePowerKw",
|
|
|
- "granularity": "15m",
|
|
|
- "points": [
|
|
|
- { "time": "2026-06-23T08:00:00", "value": 120.5 },
|
|
|
- { "time": "2026-06-23T08:15:00", "value": 135.2 },
|
|
|
- { "time": "2026-06-23T08:30:00", "value": 148.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.7.3 设备远程控制
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/device/{id}/control`
|
|
|
-
|
|
|
-**功能描述**：向设备下发远程控制指令。
|
|
|
-
|
|
|
-**权限**：`device:control`
|
|
|
-
|
|
|
-**路径参数**：`id` — 设备 ID（`vpp_device.id`）
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "controlType": "START",
|
|
|
- "params": {
|
|
|
- "targetPowerKw": 100
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**controlType 枚举**：`START`、`STOP`、`CONFIG`、`OTA`
|
|
|
-
|
|
|
-**落库说明**：
|
|
|
-
|
|
|
-- 命令下发记录写入 `dmp_device_command`（`device_uuid`、`command_content`、`command_status` 等）。
|
|
|
-- 业务侧摘要写入 `vpp_device_control_log`，可通过 `dmpCommandId` 关联物联网命令记录。
|
|
|
-- 设备在线状态以 `dmp_device_status` 为准（`device_status`：1 在线、2 离线）。
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "指令已下发",
|
|
|
- "data": {
|
|
|
- "controlLogId": 8001,
|
|
|
- "dmpCommandId": "CMD-20260623001",
|
|
|
- "controlResult": 2
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 响应字段 | 说明 |
|
|
|
-|----------|------|
|
|
|
-| controlLogId | vpp_device_control_log.id |
|
|
|
-| dmpCommandId | dmp_device_command 命令 ID |
|
|
|
-| controlResult | 0失败 1成功 2执行中 |
|
|
|
-
|
|
|
-#### 2.7.4 控制日志
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/device/{id}/controlLog`
|
|
|
-
|
|
|
-**功能描述**：查询设备远程控制历史记录。
|
|
|
-
|
|
|
-**权限**：`device:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| controlType | string | 否 | START/STOP/CONFIG/OTA |
|
|
|
-| controlResult | int | 否 | 0失败 1成功 2执行中 |
|
|
|
-| startTime | string | 否 | 操作开始时间 |
|
|
|
-| endTime | string | 否 | 操作结束时间 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_device_control_log`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 8001,
|
|
|
- "deviceId": 3001,
|
|
|
- "controlType": "START",
|
|
|
- "controlParams": { "targetPowerKw": 100 },
|
|
|
- "controlResult": 1,
|
|
|
- "resultMessage": "执行成功",
|
|
|
- "createdBy": "operator01",
|
|
|
- "createTime": "2026-06-23T10:20:00",
|
|
|
- "dmpCommandId": "CMD-20260623001"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_device_control_log`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 控制日志 ID | id |
|
|
|
-| deviceId | long | 设备 ID | device_id |
|
|
|
-| controlType | string | START/STOP/CONFIG/OTA | control_type |
|
|
|
-| controlParams | object | 控制参数 JSON | control_params |
|
|
|
-| controlResult | int | 0失败 1成功 2执行中 | control_result |
|
|
|
-| resultMessage | string | 执行结果说明 | result_message |
|
|
|
-| createdBy | string | 操作人账号 | created_by |
|
|
|
-| createTime | string | 操作时间 | create_time |
|
|
|
-| dmpCommandId | string | 物联网命令 ID（关联 dmp_device_command） | dmp_command_id |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.8 告警管理
|
|
|
-
|
|
|
-> **数据表**：规则 → `rule_engine*`；告警记录 → `base_alarm`；类型 → `base_alarm_type`；通知 → `base_alarm_notice` / `base_alarm_notice_result`；统计 → `base_alarm_statistic`。
|
|
|
-
|
|
|
-#### 2.8.1 告警规则 CRUD
|
|
|
-
|
|
|
-| 方法 | URL | 说明 | 数据表 |
|
|
|
-|------|-----|------|--------|
|
|
|
-| GET | `/prod-api/service-vpp/alarm/rule` | 规则列表 | `rule_engine` |
|
|
|
-| POST | `/prod-api/service-vpp/alarm/rule` | 新增规则 | `rule_engine` + 关联表 |
|
|
|
-| GET | `/prod-api/service-vpp/alarm/rule/{id}` | 规则详情 | `rule_engine` |
|
|
|
-| PUT | `/prod-api/service-vpp/alarm/rule/{id}` | 更新规则 | `rule_engine` |
|
|
|
-| DELETE | `/prod-api/service-vpp/alarm/rule/{id}` | 删除规则 | `rule_engine` |
|
|
|
-| GET | `/prod-api/service-vpp/alarm/rule/{id}/device` | 规则绑定设备 | `rule_engine_device` |
|
|
|
-| PUT | `/prod-api/service-vpp/alarm/rule/{id}/device` | 更新绑定设备 | `rule_engine_device` |
|
|
|
-| GET | `/prod-api/service-vpp/alarm/rule/{id}/log` | 规则执行日志 | `rule_engine_log` |
|
|
|
-
|
|
|
-**查询参数（列表）**：`name`、`status`（0 停用 / 1 启用）、`tenantId`、`current`、`size`
|
|
|
-
|
|
|
-**创建/更新规则请求体示例**（映射 `rule_engine` + `rule_engine_device`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "name": "功率超限110%",
|
|
|
- "status": 1,
|
|
|
- "descr": "光伏功率超过额定110%触发告警",
|
|
|
- "detail": {
|
|
|
- "metric": "activePowerKw",
|
|
|
- "operator": ">",
|
|
|
- "thresholdRatio": 1.1,
|
|
|
- "action": "alarmEvent",
|
|
|
- "alarmType": "PWR_OVER",
|
|
|
- "alarmGrade": 2
|
|
|
- },
|
|
|
- "devices": [
|
|
|
- {
|
|
|
- "deviceId": "DEV-INV-001",
|
|
|
- "deviceUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
|
- "identifier": "activePower",
|
|
|
- "productId": 100
|
|
|
- }
|
|
|
- ],
|
|
|
- "conditions": [
|
|
|
- {
|
|
|
- "optionalCondition": "AND",
|
|
|
- "expression": "activePowerKw > ratedPower * 1.1",
|
|
|
- "descr": "功率超限",
|
|
|
- "type": 1
|
|
|
- }
|
|
|
- ],
|
|
|
- "cronExpressions": ["0 */5 * * * ?"],
|
|
|
- "tenantId": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 请求字段 | 数据表字段 | 说明 |
|
|
|
-|----------|------------|------|
|
|
|
-| name | rule_engine.name | 规则名称（≤20 字符） |
|
|
|
-| status | rule_engine.status | 0 停用 / 1 启用 |
|
|
|
-| descr | rule_engine.descr | 规则描述 |
|
|
|
-| detail | rule_engine.detail | JSON，含阈值、动作；`action=alarmEvent` 时写入 `base_alarm` |
|
|
|
-| devices[] | rule_engine_device | deviceId 对应 `vpp_device.device_code` |
|
|
|
-| conditions[] | rule_engine_condition | type：1 触发条件 / 2 约束条件 |
|
|
|
-| cronExpressions[] | rule_engine_cron.cron | CRON 表达式 |
|
|
|
-
|
|
|
-**规则详情响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 12,
|
|
|
- "name": "功率超限110%",
|
|
|
- "status": 1,
|
|
|
- "descr": "光伏功率超过额定110%触发告警",
|
|
|
- "detail": { "action": "alarmEvent", "alarmGrade": 2 },
|
|
|
- "devices": [],
|
|
|
- "conditions": [],
|
|
|
- "cronExpressions": ["0 */5 * * * ?"],
|
|
|
- "tenantId": 1,
|
|
|
- "createTime": "2026-06-01T10:00:00.000+08:00",
|
|
|
- "updateTime": "2026-06-20T15:30:00.000+08:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**规则列表响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 12,
|
|
|
- "name": "功率超限110%",
|
|
|
- "status": 1,
|
|
|
- "descr": "光伏功率超过额定110%触发告警",
|
|
|
- "deviceCount": 5,
|
|
|
- "tenantId": 1,
|
|
|
- "createTime": "2026-06-01T10:00:00.000+08:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**更新绑定设备** — `PUT /alarm/rule/{id}/device`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "devices": [
|
|
|
- {
|
|
|
- "deviceId": "DEV-INV-001",
|
|
|
- "deviceUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
|
- "identifier": "activePower",
|
|
|
- "productId": 100
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**规则执行日志** — `GET /alarm/rule/{id}/log`
|
|
|
-
|
|
|
-**查询参数**：`startTime`、`endTime`、`current`、`size`
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `rule_engine_log`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 501,
|
|
|
- "ruleId": 12,
|
|
|
- "executeTime": "2026-06-23T10:15:00.000+08:00",
|
|
|
- "executeResult": 1,
|
|
|
- "executeMessage": "规则命中，已触发 alarmEvent",
|
|
|
- "alarmId": 158001
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.2 告警类型字典
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/alarm/type`
|
|
|
-
|
|
|
-**功能描述**：获取告警类型字典列表。
|
|
|
-
|
|
|
-**权限**：`alarm:view`
|
|
|
-
|
|
|
-**数据表**：`base_alarm_type`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 1,
|
|
|
- "typeCode": "PWR_OVER",
|
|
|
- "typeName": "功率越限",
|
|
|
- "typeAbbrevia": "越限",
|
|
|
- "alarmDesc": "设备运行功率超过设定阈值"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.3 告警列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/alarm`
|
|
|
-
|
|
|
-**功能描述**：分页查询告警记录列表。
|
|
|
-
|
|
|
-**权限**：`alarm:view`
|
|
|
-
|
|
|
-**数据表**：`base_alarm`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| handleStatus | int | 否 | 0未处理 1已处理 |
|
|
|
-| alarmGrade | int | 否 | 告警等级 1-5 |
|
|
|
-| alarmType | string | 否 | 告警类型编码 |
|
|
|
-| deviceId | string | 否 | 设备编号 |
|
|
|
-| alarmObject | string | 否 | 告警对象（模糊） |
|
|
|
-| alarmTimeStart | string | 否 | 告警时间起 |
|
|
|
-| alarmTimeEnd | string | 否 | 告警时间止 |
|
|
|
-| tenantId | long | 否 | 租户 ID |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `base_alarm`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 158001,
|
|
|
- "deviceId": "DEV-INV-001",
|
|
|
- "alarmTime": "2026-06-23T10:15:00.000+08:00",
|
|
|
- "alarmType": "PWR_OVER",
|
|
|
- "alarmObject": "浦东光伏站",
|
|
|
- "alarmData": "550.2",
|
|
|
- "alarmAttribute": "activePowerKw",
|
|
|
- "alarmContent": "功率超限110%",
|
|
|
- "alarmGrade": 2,
|
|
|
- "alarmAddress": "上海市浦东新区张江路100号",
|
|
|
- "handleStatus": 0,
|
|
|
- "handleBy": null,
|
|
|
- "handleTime": null,
|
|
|
- "handleContent": null,
|
|
|
- "alarmFalse": 0,
|
|
|
- "sitePhoto": null,
|
|
|
- "tenantId": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.4 告警处理（确认/派单/处理合一）
|
|
|
-
|
|
|
-`base_alarm` 以 `handle_status`、`handle_by`、`handle_time`、`handle_content` 承载闭环，以下接口为业务语义封装。
|
|
|
-
|
|
|
-##### 2.8.4.1 确认告警
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/alarm/{id}/confirm`
|
|
|
-
|
|
|
-**功能描述**：确认已知晓告警，可选记录操作人到 `sys_oper_log`。
|
|
|
-
|
|
|
-**权限**：`alarm:manage`
|
|
|
-
|
|
|
-**路径参数**：`id` — 告警记录 ID（`base_alarm.id`）
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "确认成功",
|
|
|
- "data": { "id": 158001 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-##### 2.8.4.2 派单
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/alarm/{id}/dispatch`
|
|
|
-
|
|
|
-**功能描述**：指派告警处理人，预填 `handle_by` 信息。
|
|
|
-
|
|
|
-**权限**：`alarm:manage`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| handlerName | string | 是 | 处理人姓名 |
|
|
|
-| handlerPhone | string | 是 | 处理人电话 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "handlerName": "李四",
|
|
|
- "handlerPhone": "13800138000"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "派单成功",
|
|
|
- "data": { "id": 158001, "handleBy": "李四" },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-##### 2.8.4.3 处理告警
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/alarm/{id}/handle`
|
|
|
-
|
|
|
-**功能描述**：完成告警处理闭环，更新 `base_alarm.handle_*` 字段。
|
|
|
-
|
|
|
-**权限**：`alarm:manage`
|
|
|
-
|
|
|
-**落库字段**：`handle_status=1`、`handle_by`、`handle_time`、`handle_content`、`site_photo`
|
|
|
-
|
|
|
-**处理请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "handleContent": "已远程重启设备，恢复正常",
|
|
|
- "handleBy": "张三",
|
|
|
- "handlePhone": "13900139000",
|
|
|
- "sitePhoto": "https://oss.example.com/photo.jpg"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| handleContent | string | 是 | 处理说明 |
|
|
|
-| handleBy | string | 是 | 处理人姓名 |
|
|
|
-| handlePhone | string | 否 | 处理人电话 |
|
|
|
-| sitePhoto | string | 否 | 现场照片 URL |
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "处理完成",
|
|
|
- "data": {
|
|
|
- "id": 158001,
|
|
|
- "handleStatus": 1,
|
|
|
- "handleBy": "张三",
|
|
|
- "handleTime": "2026-06-23T10:30:00.000+08:00"
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.5 误报关闭
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/alarm/{id}/closeFalse`
|
|
|
-
|
|
|
-**功能描述**：将告警标记为误报并关闭。
|
|
|
-
|
|
|
-**权限**：`alarm:manage`
|
|
|
-
|
|
|
-**路径参数**：`id` — 告警记录 ID
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**落库**：`base_alarm.alarm_false = 1`，`handle_status = 1`
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "已关闭",
|
|
|
- "data": { "id": 158001, "alarmFalse": 1, "handleStatus": 1 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.6 告警通知配置
|
|
|
-
|
|
|
-**数据表**：`base_alarm_notice`（配置）、`base_alarm_notice_result`（推送结果）
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/alarm/notice` | 通知配置列表 |
|
|
|
-| POST | `/prod-api/service-vpp/alarm/notice` | 新增通知配置 |
|
|
|
-| PUT | `/prod-api/service-vpp/alarm/notice/{id}` | 更新通知配置 |
|
|
|
-
|
|
|
-**列表查询参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| productCode | string | 否 | 产品编码，VPP 固定为 VPP |
|
|
|
-| typeCode | string | 否 | 告警类型编码 |
|
|
|
-| tenantId | long | 否 | 租户 ID |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**列表响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 101,
|
|
|
- "productCode": "VPP",
|
|
|
- "typeCode": "PWR_OVER",
|
|
|
- "typeName": "功率越限",
|
|
|
- "receiver1": "1001,1002",
|
|
|
- "receiver2": "1003",
|
|
|
- "timeOut1": 30,
|
|
|
- "timeOut2": 60,
|
|
|
- "noticeMethod": "1,2,4",
|
|
|
- "tenantId": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**创建通知配置请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "productCode": "VPP",
|
|
|
- "typeCode": "PWR_OVER",
|
|
|
- "receiver1": "1001,1002",
|
|
|
- "receiver2": "1003",
|
|
|
- "timeOut1": 30,
|
|
|
- "timeOut2": 60,
|
|
|
- "noticeMethod": "1,2,4",
|
|
|
- "tenantId": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| productCode | string | 是 | 产品编码 |
|
|
|
-| typeCode | string | 是 | 告警类型编码 |
|
|
|
-| receiver1 | string | 是 | 一级接收人 userId，逗号分隔 |
|
|
|
-| receiver2 | string | 否 | 二级接收人 |
|
|
|
-| receiver3 | string | 否 | 三级接收人 |
|
|
|
-| timeOut1 | int | 否 | 一级超时升级（分钟） |
|
|
|
-| timeOut2 | int | 否 | 二级超时升级（分钟） |
|
|
|
-| noticeMethod | string | 是 | 通知方式，逗号分隔 |
|
|
|
-| tenantId | long | 否 | 租户 ID |
|
|
|
-
|
|
|
-> `noticeMethod`：1 站内 / 2 微信 / 3 语音 / 4 短信 / 5 邮件（与 `base_alarm_notice_result.notice_type` 一致）。
|
|
|
-
|
|
|
-**创建/更新响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "保存成功",
|
|
|
- "data": { "id": 101 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.8.7 告警统计
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/alarm/statistics`
|
|
|
-
|
|
|
-**功能描述**：按日/月维度统计告警数量。
|
|
|
-
|
|
|
-**权限**：`alarm:view`
|
|
|
-
|
|
|
-**数据表**：`base_alarm_statistic`（汇总）或 `base_alarm`（实时聚合）
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| startDate | string | 是 | 开始日期 YYYY-MM-DD |
|
|
|
-| endDate | string | 是 | 结束日期 YYYY-MM-DD |
|
|
|
-| statisticDimen | int | 否 | 1日 2月，默认 1 |
|
|
|
-| tenantId | long | 否 | 租户 ID |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "alarmNum": 128,
|
|
|
- "pitfallNum": 5,
|
|
|
- "statisticDimen": 1,
|
|
|
- "statisticTime": "2026-06-23T00:00:00.000+08:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.9 需求响应
|
|
|
-
|
|
|
-> **实现说明（service-vpp）**
|
|
|
-> - 运管平台邀约经 `DistributeEventRequest` 入库 `vpp_dr_event`（Poll 主动拉取或 UN 推送 `/DistributeEventRequest`）。
|
|
|
-> - Web 端参与/出清成功后，若 `vpp.un.outbound-enabled=true`，自动向 UN 发送 `CreateOptRequest` / `CreateCqRequest`。
|
|
|
-> - 出清公示确认：Web 调用 `ack-clearing`，或配置 `auto-ack-clearing=true` 在 Poll 入库后自动发送 `CreateEventResponse`。
|
|
|
-> - 参与记录按电力户号 `vpp_customer.account_no` 与 UN 报文 `list[].account` 映射。
|
|
|
-
|
|
|
-#### 2.9.0 事件状态枚举
|
|
|
-
|
|
|
-| eventStatus | 说明 | 典型触发 |
|
|
|
-|-------------|------|----------|
|
|
|
-| 0 | 待参与 | 邀约入库 |
|
|
|
-| 1 | 已申报 | Web 参与 / UN 申报反馈 |
|
|
|
-| 2 | 执行中 | 出清确认 / Web 出清 |
|
|
|
-| 3 | 已结束 | Web 结束事件 |
|
|
|
-| 4 | 已取消 | Web 拒绝 / UN optOut |
|
|
|
-
|
|
|
-#### 2.9.1 事件列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/event`
|
|
|
-
|
|
|
-**功能描述**：分页查询需求响应事件列表。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| eventStatus | int | 否 | 0待参与 1已申报 2执行中 3已结束 4已取消 |
|
|
|
-| responseType | int | 否 | 1日前 2日内 3秒级 |
|
|
|
-| eventType | int | 否 | 1削峰 2填谷 |
|
|
|
-| startTime | string | 否 | 响应开始时间起 |
|
|
|
-| endTime | string | 否 | 响应开始时间止 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_dr_event`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 6001,
|
|
|
- "eventId": "EVE_20260623001",
|
|
|
- "eventName": "夏季削峰需求响应",
|
|
|
- "responseType": 1,
|
|
|
- "eventType": 1,
|
|
|
- "startTime": "2026-06-23T14:00:00",
|
|
|
- "endTime": "2026-06-23T16:00:00",
|
|
|
- "targetCapacityKw": 1500.0,
|
|
|
- "clearedCapacityKw": 1200.0,
|
|
|
- "subsidyPrice": 3.5,
|
|
|
- "eventStatus": 2
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_dr_event`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 本地事件 ID | id |
|
|
|
-| eventId | string | 运管平台事件 ID | event_id |
|
|
|
-| eventName | string | 事件名称 | event_name |
|
|
|
-| responseType | int | 1日前 2日内 3秒级 | response_type |
|
|
|
-| eventType | int | 1削峰 2填谷 | event_type |
|
|
|
-| startTime | string | 响应开始时间 | start_time |
|
|
|
-| endTime | string | 响应结束时间 | end_time |
|
|
|
-| targetCapacityKw | number | 目标容量 kW | target_capacity_kw |
|
|
|
-| clearedCapacityKw | number | 出清容量 kW | cleared_capacity_kw |
|
|
|
-| subsidyPrice | number | 补贴单价（元/kWh 或协议约定单位） | subsidy_price |
|
|
|
-| eventStatus | int | 事件状态，见 §2.9.0 | event_status |
|
|
|
-
|
|
|
-#### 2.9.2 事件详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/event/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取事件详情，含活动期、补贴标准、出清容量及参与资源列表。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 6001,
|
|
|
- "eventId": "EVE_20260623001",
|
|
|
- "eventName": "夏季削峰需求响应",
|
|
|
- "responseType": 1,
|
|
|
- "eventType": 1,
|
|
|
- "startTime": "2026-06-23T14:00:00",
|
|
|
- "endTime": "2026-06-23T16:00:00",
|
|
|
- "targetCapacityKw": 1500.0,
|
|
|
- "clearedCapacityKw": 1200.0,
|
|
|
- "subsidyPrice": 3.5,
|
|
|
- "eventStatus": 2,
|
|
|
- "participations": [
|
|
|
- {
|
|
|
- "id": 7001,
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceName": "工业负荷A",
|
|
|
- "participateStatus": 1,
|
|
|
- "declaredCapacityKw": 500.0,
|
|
|
- "clearedCapacityKw": 450.0,
|
|
|
- "declaredAt": "2026-06-22T16:00:00"
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**（在列表字段基础上扩展）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| participations | array | 参与记录列表 | vpp_dr_participation |
|
|
|
-| participations[].id | long | 参与记录 ID | id |
|
|
|
-| participations[].customerId | long | 客户 ID | customer_id |
|
|
|
-| participations[].customerName | string | 客户名称（关联） | — |
|
|
|
-| participations[].resourceId | long | 资源点 ID | resource_id |
|
|
|
-| participations[].resourceName | string | 资源名称（关联） | — |
|
|
|
-| participations[].participateStatus | int | 0待确认 1已参与 2已拒绝 | participate_status |
|
|
|
-| participations[].declaredCapacityKw | number | 申报容量 kW | declared_capacity_kw |
|
|
|
-| participations[].clearedCapacityKw | number | 出清容量 kW | cleared_capacity_kw |
|
|
|
-| participations[].declaredAt | string | 申报时间 | declared_at |
|
|
|
-
|
|
|
-#### 2.9.2.1 新增事件
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event`
|
|
|
-
|
|
|
-**功能描述**：手工录入需求响应事件（联调/演练场景）；`eventId` 不传时自动生成，初始状态为**待参与(0)**。运管平台同步事件请走 UN `DistributeEventRequest` 入库。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**数据表**：`vpp_dr_event`
|
|
|
-
|
|
|
-**请求体字段说明**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| eventId | string | 否 | 运管平台事件 ID；不传则自动生成 `EVE_yyyyMMddHHmmss_XXXX` | event_id |
|
|
|
-| eventName | string | 否 | 事件名称；不传则使用 eventId | event_name |
|
|
|
-| responseType | int | 是 | 1日前 2日内 3秒级 | response_type |
|
|
|
-| eventType | int | 否 | 1削峰 2填谷 | event_type |
|
|
|
-| startTime | string | 是 | 响应开始时间（ISO 8601） | start_time |
|
|
|
-| endTime | string | 是 | 响应结束时间（ISO 8601） | end_time |
|
|
|
-| targetCapacityKw | number | 是 | 目标容量 kW，须 > 0 | target_capacity_kw |
|
|
|
-| clearedCapacityKw | number | 否 | 出清容量 kW | cleared_capacity_kw |
|
|
|
-| subsidyPrice | number | 否 | 补贴标准 元/kWh | subsidy_price |
|
|
|
-
|
|
|
-**请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "eventName": "夏季削峰需求响应（演练）",
|
|
|
- "responseType": 1,
|
|
|
- "eventType": 1,
|
|
|
- "startTime": "2026-06-23T14:00:00",
|
|
|
- "endTime": "2026-06-23T16:00:00",
|
|
|
- "targetCapacityKw": 1500.0,
|
|
|
- "subsidyPrice": 3.5
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": {
|
|
|
- "id": 6001,
|
|
|
- "eventId": "EVE_20260623140000_A1B2",
|
|
|
- "eventName": "夏季削峰需求响应（演练）",
|
|
|
- "responseType": 1,
|
|
|
- "eventType": 1,
|
|
|
- "startTime": "2026-06-23T14:00:00",
|
|
|
- "endTime": "2026-06-23T16:00:00",
|
|
|
- "targetCapacityKw": 1500.0,
|
|
|
- "subsidyPrice": 3.5,
|
|
|
- "eventStatus": 0
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.2.2 修改事件
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/dr/event/{id}`
|
|
|
-
|
|
|
-**功能描述**：修改手工录入的事件信息。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**路径参数**：`id` — 本地事件 ID（`vpp_dr_event.id`）
|
|
|
-
|
|
|
-**前置条件**：
|
|
|
-
|
|
|
-- `eventStatus=0`（待参与）
|
|
|
-- 无关联参与记录、执行明细、评估报告
|
|
|
-
|
|
|
-**请求体**：字段同 §2.9.2.1（`eventId` 不可修改，传了也忽略）
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.2.3 删除事件
|
|
|
-
|
|
|
-**接口地址**：`DELETE /prod-api/service-vpp/dr/event/{id}`
|
|
|
-
|
|
|
-**功能描述**：软删除需求响应事件（`deleteFlag=1`）。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**路径参数**：`id` — 本地事件 ID
|
|
|
-
|
|
|
-**前置条件**：
|
|
|
-
|
|
|
-- `eventStatus` 为 0（待参与）或 4（已取消）
|
|
|
-- 无关联参与记录、执行明细、评估报告
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.3 能力评估
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/event/{id}/capability`
|
|
|
-
|
|
|
-**功能描述**：评估事件可调能力，聚合客户登记能力及资源实时可用性。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**数据表**：`vpp_customer`（dr_up/down_capacity_kw）+ `vpp_resource_point`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "totalUpCapacityKw": 1500.0,
|
|
|
- "totalDownCapacityKw": 2000.0,
|
|
|
- "avgResponseTimeSec": 120,
|
|
|
- "avgRampSpeedKwMin": 50.0,
|
|
|
- "resources": [
|
|
|
- {
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceName": "工业负荷A",
|
|
|
- "upCapacityKw": 500.0,
|
|
|
- "downCapacityKw": 800.0,
|
|
|
- "responsePriority": 1,
|
|
|
- "available": true
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| totalUpCapacityKw | number | 汇总上调能力 kW |
|
|
|
-| totalDownCapacityKw | number | 汇总下调能力 kW |
|
|
|
-| avgResponseTimeSec | int | 平均响应时间（秒） |
|
|
|
-| avgRampSpeedKwMin | number | 平均爬坡速度 kW/min |
|
|
|
-| resources | array | 分资源能力明细 |
|
|
|
-| resources[].resourceId | long | 资源点 ID |
|
|
|
-| resources[].resourceName | string | 资源名称 |
|
|
|
-| resources[].upCapacityKw | number | 上调能力 kW |
|
|
|
-| resources[].downCapacityKw | number | 下调能力 kW |
|
|
|
-| resources[].responsePriority | int | 响应优先级 |
|
|
|
-| resources[].available | boolean | 当前是否可用（在线且未故障） |
|
|
|
-
|
|
|
-#### 2.9.4 参与/拒绝事件
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event/{id}/participate`
|
|
|
-
|
|
|
-**功能描述**：确认参与或拒绝需求响应事件，写入 `vpp_dr_participation`；**已启用 outbound 时同步 UN `CreateOptRequest`**。
|
|
|
-
|
|
|
-**权限**：`dr:participate`
|
|
|
-
|
|
|
-**路径参数**：`id` — 事件 ID（`vpp_dr_event.id`）
|
|
|
-
|
|
|
-**参与请求参数**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| participate | boolean | 是 | true 参与 / false 拒绝 |
|
|
|
-| strategyId | long | 否 | 响应策略 ID（参与时） |
|
|
|
-| declaredCapacityKw | number | 否 | 申报总容量 kW |
|
|
|
-| resources | array | 否 | 资源分拆列表 |
|
|
|
-| resources[].resourceId | long | 是 | 资源点 ID |
|
|
|
-| resources[].declaredCapacityKw | number | 是 | 申报容量 kW |
|
|
|
-| reason | string | 否 | 拒绝原因（拒绝时必填） |
|
|
|
-
|
|
|
-**请求体（参与）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "participate": true,
|
|
|
- "strategyId": 10,
|
|
|
- "declaredCapacityKw": 1200.0,
|
|
|
- "resources": [
|
|
|
- { "resourceId": 2001, "declaredCapacityKw": 500.0 },
|
|
|
- { "resourceId": 2002, "declaredCapacityKw": 700.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**请求体（拒绝）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "participate": false,
|
|
|
- "reason": "可调容量不足"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "申报成功",
|
|
|
- "data": {
|
|
|
- "eventId": 6001,
|
|
|
- "participateStatus": 1,
|
|
|
- "declaredCapacityKw": 1200.0
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.5 出清分拆申报
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event/{id}/clearing`
|
|
|
-
|
|
|
-**功能描述**：出清后按资源分拆申报容量，写入 `vpp_dr_execution` 并更新事件为执行中；**已启用 outbound 时同步 UN `CreateCqRequest`**。
|
|
|
-
|
|
|
-**权限**：`dr:participate`
|
|
|
-
|
|
|
-**请求体**（更新 `vpp_dr_participation.cleared_capacity_kw`）：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| totalClearedCapacityKw | number | 是 | 出清总容量 kW |
|
|
|
-| resources | array | 是 | 资源分拆列表 |
|
|
|
-| resources[].resourceId | long | 是 | 资源点 ID |
|
|
|
-| resources[].clearedCapacityKw | number | 是 | 分拆出清容量 kW |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "totalClearedCapacityKw": 1200.0,
|
|
|
- "resources": [
|
|
|
- { "resourceId": 2001, "clearedCapacityKw": 450.0 },
|
|
|
- { "resourceId": 2002, "clearedCapacityKw": 750.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "分拆申报成功",
|
|
|
- "data": { "eventId": "EVE_20260623001", "totalClearedCapacityKw": 1200.0 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.6 执行监控
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/event/{id}/monitor`
|
|
|
-
|
|
|
-**功能描述**：实时监控事件执行进度，数据来自 `vpp_dr_execution`。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "eventId": "EVE_20260623001",
|
|
|
- "targetCapacityKw": 1200.0,
|
|
|
- "actualCapacityKw": 1050.0,
|
|
|
- "progressPercent": 87.5,
|
|
|
- "remainingMinutes": 45,
|
|
|
- "resources": [
|
|
|
- {
|
|
|
- "resourceId": 2001,
|
|
|
- "targetKw": 500.0,
|
|
|
- "actualKw": 480.0,
|
|
|
- "executeStatus": 1
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| eventId | string | 运管平台事件 ID |
|
|
|
-| targetCapacityKw | number | 目标/出清容量 kW |
|
|
|
-| actualCapacityKw | number | 当前实际响应容量 kW |
|
|
|
-| progressPercent | number | 执行进度百分比 |
|
|
|
-| remainingMinutes | int | 剩余执行分钟数 |
|
|
|
-| resources | array | 分资源执行明细（`vpp_dr_execution`） |
|
|
|
-| resources[].resourceId | long | 资源点 ID |
|
|
|
-| resources[].targetKw | number | 目标调节量 kW |
|
|
|
-| resources[].actualKw | number | 实际调节量 kW |
|
|
|
-| resources[].executeStatus | int | 0待执行 1执行中 2已完成 3异常 |
|
|
|
-
|
|
|
-#### 2.9.7 手动干预
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event/{id}/intervene`
|
|
|
-
|
|
|
-**功能描述**：执行中手动切换策略或调整执行。
|
|
|
-
|
|
|
-**权限**：`dr:intervene`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| action | string | 是 | ADJUST（切换策略）/ PAUSE（暂停）/ RESUME（恢复） |
|
|
|
-| strategyId | long | 否 | 目标策略 ID（action=ADJUST 时必填） |
|
|
|
-| remark | string | 否 | 干预说明 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "action": "ADJUST",
|
|
|
- "strategyId": 11,
|
|
|
- "remark": "实际响应偏低，切换备用策略"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "干预指令已下发",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.8 确认出清公示
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event/{id}/ack-clearing`
|
|
|
-
|
|
|
-**功能描述**：向 UN 发送 `CreateEventResponse` 确认出清公示，事件状态推进为**执行中(2)**，并初始化 `vpp_dr_execution`（若尚未创建）。
|
|
|
-
|
|
|
-**权限**：`dr:participate`
|
|
|
-
|
|
|
-**前置条件**：`eventStatus=1`（已申报），且已完成出清公示 Poll 入库（`clearedCapacityKw` 有值）
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> 等价 UN 报文见 §3.7.4；也可由 `vpp.un.auto-ack-clearing=true` 在 Poll 收到出清公示后自动触发。
|
|
|
-
|
|
|
-#### 2.9.9 结束事件
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/event/{id}/complete`
|
|
|
-
|
|
|
-**功能描述**：将执行中事件标记为**已结束(3)**，汇总执行明细写入 `vpp_dr_evaluation`（若不存在则创建）。
|
|
|
-
|
|
|
-**权限**：`dr:intervene`
|
|
|
-
|
|
|
-**前置条件**：`eventStatus=2`，且存在执行明细
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.9.10 效果评估报告
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/event/{id}/evaluation`
|
|
|
-
|
|
|
-**功能描述**：获取事件响应效果评估报告。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**响应 data 示例**（映射 `vpp_dr_evaluation`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "eventId": 6001,
|
|
|
- "eventName": "夏季削峰需求响应",
|
|
|
- "targetCapacityKw": 1200.0,
|
|
|
- "actualCapacityKw": 1050.0,
|
|
|
- "responseDurationMin": 120,
|
|
|
- "subsidyAmount": 7350.0,
|
|
|
- "qualifiedRate": 87.5,
|
|
|
- "reportFileUrl": "https://oss.example.com/dr/eval_6001.pdf",
|
|
|
- "evaluatedAt": "2026-06-23T18:00:00",
|
|
|
- "resourceDetails": [
|
|
|
- {
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceName": "工业负荷A",
|
|
|
- "targetKw": 450.0,
|
|
|
- "actualKw": 420.0,
|
|
|
- "qualifiedRate": 93.3
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data 字段说明**（映射 `vpp_dr_evaluation`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| eventId | long | 本地事件 ID | event_id |
|
|
|
-| eventName | string | 事件名称 | — |
|
|
|
-| targetCapacityKw | number | 目标容量 kW | target_capacity_kw |
|
|
|
-| actualCapacityKw | number | 实际响应容量 kW | actual_capacity_kw |
|
|
|
-| responseDurationMin | int | 响应持续分钟数 | response_duration_min |
|
|
|
-| subsidyAmount | number | 补贴金额（元） | subsidy_amount |
|
|
|
-| qualifiedRate | number | 达标率 % | qualified_rate |
|
|
|
-| reportFileUrl | string | 评估报告文件 URL | report_file_url |
|
|
|
-| evaluatedAt | string | 评估时间 | evaluated_at |
|
|
|
-| resourceDetails | array | 分资源评估明细 | — |
|
|
|
-| resourceDetails[].resourceId | long | 资源点 ID | — |
|
|
|
-| resourceDetails[].resourceName | string | 资源名称 | — |
|
|
|
-| resourceDetails[].targetKw | number | 目标 kW | — |
|
|
|
-| resourceDetails[].actualKw | number | 实际 kW | — |
|
|
|
-| resourceDetails[].qualifiedRate | number | 达标率 % | — |
|
|
|
-
|
|
|
-#### 2.9.11 响应策略 CRUD
|
|
|
-
|
|
|
-**数据表**：`vpp_dr_strategy` + `vpp_dr_strategy_resource`
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/dr/strategy` | 策略列表 |
|
|
|
-| POST | `/prod-api/service-vpp/dr/strategy` | 新增策略 |
|
|
|
-| GET | `/prod-api/service-vpp/dr/strategy/{id}` | 策略详情 |
|
|
|
-| PUT | `/prod-api/service-vpp/dr/strategy/{id}` | 更新策略 |
|
|
|
-| DELETE | `/prod-api/service-vpp/dr/strategy/{id}` | 删除策略 |
|
|
|
-
|
|
|
-**列表查询参数**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| strategyName | string | 否 | 策略名称（模糊） | strategy_name |
|
|
|
-| responseType | int | 否 | 适用响应类型：1日前 2日内 3秒级 | response_type |
|
|
|
-| isEnabled | int | 否 | 0禁用 1启用 | is_enabled |
|
|
|
-| current | int | 否 | 页码 | — |
|
|
|
-| size | int | 否 | 每页数量 | — |
|
|
|
-
|
|
|
-**创建/更新请求体字段说明**（映射 `vpp_dr_strategy` + `vpp_dr_strategy_resource`）：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| strategyCode | string | 是 | 策略编码，全局唯一 | strategy_code |
|
|
|
-| strategyName | string | 是 | 策略名称 | strategy_name |
|
|
|
-| responseType | int | 是 | 适用响应类型：1日前 2日内 3秒级 | response_type |
|
|
|
-| adjustStepKw | number | 否 | 调节步长 kW | adjust_step_kw |
|
|
|
-| executeMode | int | 否 | 执行模式：1并行 2串行，默认 1 | execute_mode |
|
|
|
-| strategyConfig | object/string | 否 | 策略扩展配置 JSON；**请求可传 JSON 对象或 JSON 字符串**，服务端统一序列化后落库 | strategy_config |
|
|
|
-| isDefault | int | 否 | 是否默认策略：0否 1是，默认 0 | is_default |
|
|
|
-| isEnabled | int | 否 | 是否启用：0否 1是，默认 1 | is_enabled |
|
|
|
-| resources | array | 否 | 关联资源列表 | vpp_dr_strategy_resource |
|
|
|
-| resources[].resourceId | long | 是 | 资源点 ID | resource_id |
|
|
|
-| resources[].priority | int | 否 | 优先级序号，默认 0 | priority |
|
|
|
-| resources[].maxAdjustKw | number | 否 | 最大调节量 kW | max_adjust_kw |
|
|
|
-
|
|
|
-**创建/更新请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "strategyCode": "DR_PEAK_V1",
|
|
|
- "strategyName": "削峰默认策略",
|
|
|
- "responseType": 1,
|
|
|
- "adjustStepKw": 50.0,
|
|
|
- "executeMode": 1,
|
|
|
- "isDefault": 1,
|
|
|
- "isEnabled": 1,
|
|
|
- "strategyConfig": { "rampMinutes": 5 },
|
|
|
- "resources": [
|
|
|
- { "resourceId": 2001, "priority": 1, "maxAdjustKw": 500.0 },
|
|
|
- { "resourceId": 2002, "priority": 2, "maxAdjustKw": 800.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**策略详情响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 10,
|
|
|
- "strategyCode": "DR_PEAK_V1",
|
|
|
- "strategyName": "削峰默认策略",
|
|
|
- "responseType": 1,
|
|
|
- "adjustStepKw": 50.0,
|
|
|
- "executeMode": 1,
|
|
|
- "strategyConfig": "{\"rampMinutes\":5}",
|
|
|
- "isDefault": 1,
|
|
|
- "isEnabled": 1,
|
|
|
- "resources": [
|
|
|
- { "resourceId": 2001, "resourceName": "工业负荷A", "priority": 1, "maxAdjustKw": 500.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**策略列表/详情响应字段说明**（映射 `vpp_dr_strategy`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 策略 ID | id |
|
|
|
-| strategyCode | string | 策略编码 | strategy_code |
|
|
|
-| strategyName | string | 策略名称 | strategy_name |
|
|
|
-| responseType | int | 适用响应类型 | response_type |
|
|
|
-| adjustStepKw | number | 调节步长 kW | adjust_step_kw |
|
|
|
-| executeMode | int | 1并行 2串行 | execute_mode |
|
|
|
-| strategyConfig | string | 策略扩展配置（JSON 字符串，对应库表 JSON 列；前端需 `JSON.parse` 后使用） | strategy_config |
|
|
|
-| isDefault | int | 是否默认策略 | is_default |
|
|
|
-| isEnabled | int | 是否启用 | is_enabled |
|
|
|
-| resources | array | 关联资源（详情接口返回，含 resourceName） | vpp_dr_strategy_resource |
|
|
|
-| resources[].resourceId | long | 资源点 ID | resource_id |
|
|
|
-| resources[].resourceName | string | 资源名称（关联查询，仅详情） | — |
|
|
|
-| resources[].priority | int | 优先级序号 | priority |
|
|
|
-| resources[].maxAdjustKw | number | 最大调节量 kW | max_adjust_kw |
|
|
|
-| tenantId | int | 租户 ID | tenant_id |
|
|
|
-| createTime | string | 创建时间 | create_time |
|
|
|
-| createdBy | string | 创建人 | created_by |
|
|
|
-
|
|
|
-> **strategyConfig 入参说明**：`POST/PUT /dr/strategy` 请求体中 `strategyConfig` 支持 JSON 对象（推荐）或 JSON 字符串两种格式；响应中为 JSON 字符串。
|
|
|
-
|
|
|
-#### 2.9.12 邀约管理
|
|
|
-
|
|
|
-> **数据表**：`vpp_dr_invitation`（关联 `vpp_dr_event`、`vpp_customer`、`vpp_customer_contact`、`vpp_dr_participation`）
|
|
|
-> **界面映射**：Web「邀约管理」列表与「添加邀约」弹窗。
|
|
|
-> **业务说明**：聚合商向签约企业下发需求响应邀约；同一事件对同一企业仅允许一条有效邀约。客户确认参与后，可关联 `vpp_dr_participation` 并同步 UN `CreateOptRequest`（见 §2.9.4）。
|
|
|
-
|
|
|
-##### 2.9.12.0 枚举
|
|
|
-
|
|
|
-**replyStatus（回复情况）**
|
|
|
-
|
|
|
-| 值 | 说明 | 界面展示 |
|
|
|
-|----|------|----------|
|
|
|
-| 0 | 待回复 | 待回复 |
|
|
|
-| 1 | 参与 | 参与 |
|
|
|
-| 2 | 拒绝 | 拒绝 |
|
|
|
-| 3 | 超时 | 超时未回复 |
|
|
|
-
|
|
|
-**responseStatus（响应状态）**
|
|
|
-
|
|
|
-| 值 | 说明 | 界面展示 |
|
|
|
-|----|------|----------|
|
|
|
-| 0 | 待响应 | 待响应 |
|
|
|
-| 1 | 已申报 | 响应已申报 |
|
|
|
-| 2 | 执行中 | 响应执行中 |
|
|
|
-| 3 | 已结束 | 响应已结束 |
|
|
|
-| 4 | 已取消 | 已取消 |
|
|
|
-
|
|
|
-**smsNotifyStatus（短信通知）**
|
|
|
-
|
|
|
-| 值 | 说明 |
|
|
|
-|----|------|
|
|
|
-| 0 | 未发送 |
|
|
|
-| 1 | 已发送 |
|
|
|
-| 2 | 发送失败 |
|
|
|
-
|
|
|
-**transactionType（交易类型）**
|
|
|
-
|
|
|
-| 值 | 说明 |
|
|
|
-|----|------|
|
|
|
-| 1 | 削峰 |
|
|
|
-| 2 | 填谷 |
|
|
|
-
|
|
|
-##### 2.9.12.1 邀约列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/invitation`
|
|
|
-
|
|
|
-**功能描述**：分页查询企业邀约台账，支持按下发日期、响应类型、企业名称筛选。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| issueDateStart | string | 否 | 下发日期起（yyyy-MM-dd） | issue_time |
|
|
|
-| issueDateEnd | string | 否 | 下发日期止（yyyy-MM-dd） | issue_time |
|
|
|
-| responseType | int | 否 | 1日前 2日内 3秒级 | response_type |
|
|
|
-| customerId | long | 否 | 客户 ID | customer_id |
|
|
|
-| customerName | string | 否 | 企业名称（模糊） | — |
|
|
|
-| drEventId | long | 否 | 本地事件 ID | dr_event_id |
|
|
|
-| replyStatus | int | 否 | 回复情况 | reply_status |
|
|
|
-| responseStatus | int | 否 | 响应状态 | response_status |
|
|
|
-| current | int | 否 | 页码 | — |
|
|
|
-| size | int | 否 | 每页数量 | — |
|
|
|
-
|
|
|
-**响应 data.records 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 1,
|
|
|
- "invitationNo": "INV_20260704120000_A1B2",
|
|
|
- "drEventId": 1,
|
|
|
- "drEventCode": "EVE_20260430001",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "用户站",
|
|
|
- "executeStartDate": "2026-05-01",
|
|
|
- "executeEndDate": "2026-05-01",
|
|
|
- "replyDeadline": "2026-04-28T18:00:00",
|
|
|
- "issueTime": "2026-04-27T10:00:00",
|
|
|
- "transactionType": 1,
|
|
|
- "responseType": 1,
|
|
|
- "demandCapacityKw": 500.0,
|
|
|
- "declaredCapacityKw": 480.0,
|
|
|
- "replyStatus": 1,
|
|
|
- "responseStatus": 1,
|
|
|
- "smsNotifyStatus": 0
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 邀约 ID | id |
|
|
|
-| invitationNo | string | 邀约编号 | invitation_no |
|
|
|
-| drEventId | long | 本地事件 ID | dr_event_id |
|
|
|
-| drEventCode | string | 需求响应编号（关联 `vpp_dr_event.event_id`） | — |
|
|
|
-| customerId | long | 客户 ID | customer_id |
|
|
|
-| customerName | string | 企业名称（关联） | — |
|
|
|
-| executeStartDate | string | 执行开始日期 | execute_start_date |
|
|
|
-| executeEndDate | string | 执行结束日期 | execute_end_date |
|
|
|
-| replyDeadline | string | 邀约回复截止日期 | reply_deadline |
|
|
|
-| issueTime | string | 下发时间 | issue_time |
|
|
|
-| transactionType | int | 交易类型：1削峰 2填谷 | transaction_type |
|
|
|
-| responseType | int | 1日前 2日内 3秒级 | response_type |
|
|
|
-| demandCapacityKw | number | 需求容量 kW | demand_capacity_kw |
|
|
|
-| declaredCapacityKw | number | 已申报容量 kW | declared_capacity_kw |
|
|
|
-| replyStatus | int | 回复情况，见 §2.9.12.0 | reply_status |
|
|
|
-| responseStatus | int | 响应状态，见 §2.9.12.0 | response_status |
|
|
|
-| smsNotifyStatus | int | 短信通知状态 | sms_notify_status |
|
|
|
-
|
|
|
-##### 2.9.12.2 邀约详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/dr/invitation/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取单条邀约详情，含关联事件与客户主联系人信息。
|
|
|
-
|
|
|
-**权限**：`dr:view`
|
|
|
-
|
|
|
-**响应 data**：在列表字段基础上扩展 `remark`、`participationId`、`smsContactId`、`smsContactName`、`smsContactPhone`、`smsNotifyAt` 及 §2.1.7 审计字段。
|
|
|
-
|
|
|
-##### 2.9.12.3 新增邀约
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/invitation`
|
|
|
-
|
|
|
-**功能描述**：向指定企业下发需求响应邀约；`invitationNo` 不传时自动生成 `INV_yyyyMMddHHmmss_XXXX`；`issueTime` 默认当前时间；`transactionType`、`responseType` 未传时从关联事件复制。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**数据表**：`vpp_dr_invitation`
|
|
|
-
|
|
|
-**请求体字段说明**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------|------------|
|
|
|
-| drEventId | long | 是 | 需求响应事件 ID（`vpp_dr_event.id`） | dr_event_id |
|
|
|
-| customerId | long | 是 | 企业客户 ID | customer_id |
|
|
|
-| executeStartDate | string | 是 | 执行开始日期（yyyy-MM-dd） | execute_start_date |
|
|
|
-| executeEndDate | string | 是 | 执行结束日期（yyyy-MM-dd） | execute_end_date |
|
|
|
-| replyDeadline | string | 是 | 邀约回复截止日期（ISO 8601） | reply_deadline |
|
|
|
-| demandCapacityKw | number | 是 | 需求容量 kW，须 > 0 | demand_capacity_kw |
|
|
|
-| declaredCapacityKw | number | 否 | 已申报容量 kW；新建时可预填 0 | declared_capacity_kw |
|
|
|
-| transactionType | int | 否 | 交易类型；默认取事件 `eventType` | transaction_type |
|
|
|
-| responseType | int | 否 | 响应类型；默认取事件 `responseType` | response_type |
|
|
|
-| smsContactId | long | 否 | 短信通知联系人；默认取客户主联系人 | sms_contact_id |
|
|
|
-| remark | string | 否 | 备注 | remark |
|
|
|
-
|
|
|
-**请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "drEventId": 1,
|
|
|
- "customerId": 1001,
|
|
|
- "executeStartDate": "2026-05-01",
|
|
|
- "executeEndDate": "2026-05-01",
|
|
|
- "replyDeadline": "2026-04-28T18:00:00",
|
|
|
- "demandCapacityKw": 500.0,
|
|
|
- "declaredCapacityKw": 0
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**业务规则**：
|
|
|
-
|
|
|
-- 同一 `drEventId` + `customerId` 不可重复创建（`uk_dr_invitation_event_customer`）
|
|
|
-- 初始 `replyStatus=0`（待回复）、`responseStatus=0`（待响应）、`smsNotifyStatus=0`（未发送）
|
|
|
-- `executeStartDate` ≤ `executeEndDate`；`replyDeadline` 应早于执行开始时间
|
|
|
-
|
|
|
-**响应 data**：返回完整邀约对象（含生成的 `id`、`invitationNo`、`issueTime`）。
|
|
|
-
|
|
|
-##### 2.9.12.4 修改邀约
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/dr/invitation/{id}`
|
|
|
-
|
|
|
-**功能描述**：修改待回复状态的邀约信息。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**前置条件**：`replyStatus=0`（待回复）且 `responseStatus=0`（待响应）
|
|
|
-
|
|
|
-**可修改字段**：`executeStartDate`、`executeEndDate`、`replyDeadline`、`demandCapacityKw`、`declaredCapacityKw`、`transactionType`、`responseType`、`smsContactId`、`remark`
|
|
|
-
|
|
|
-##### 2.9.12.5 删除邀约
|
|
|
-
|
|
|
-**接口地址**：`DELETE /prod-api/service-vpp/dr/invitation/{id}`
|
|
|
-
|
|
|
-**功能描述**：软删除邀约记录（`deleteFlag=1`）。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**前置条件**：`replyStatus` 为 0、2 或 3，且 `responseStatus=0`；已关联 `participationId` 的不可删除
|
|
|
-
|
|
|
-##### 2.9.12.6 发送短信通知
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/invitation/{id}/notify-sms`
|
|
|
-
|
|
|
-**功能描述**：向邀约联系人发送阿里云短信；成功后更新 `smsNotifyStatus=1`、`smsNotifyAt`。
|
|
|
-
|
|
|
-**权限**：`dr:manage`
|
|
|
-
|
|
|
-**配置项**（Nacos 共享 + `service-vpp` 本地）：
|
|
|
-
|
|
|
-| 配置键 | 说明 |
|
|
|
-|--------|------|
|
|
|
-| `sms.ali.region-id` | 阿里云区域，如 `cn-hangzhou` |
|
|
|
-| `sms.ali.access-key-id` | AccessKey ID |
|
|
|
-| `sms.ali.access-key-secret` | AccessKey Secret |
|
|
|
-| `vpp.sms.sign-name` | 短信签名 |
|
|
|
-| `vpp.sms.invitation-template-code` | 邀约默认模板 CODE（需在阿里云单独申请，勿与告警模板混用） |
|
|
|
-| `vpp.sms.enabled` | 是否启用，默认 `true` |
|
|
|
-
|
|
|
-**阿里云模板变量**（代码默认构建，须与控制台模板占位符**完全一致**；默认模板 `SMS_465362899`）：
|
|
|
-
|
|
|
-| 变量名 | 说明 | 示例 |
|
|
|
-|--------|------|------|
|
|
|
-| `meet` | 需求响应事件名称 | 夏季削峰需求响应 |
|
|
|
-| `time` | 响应开始时间（无则取回复截止时间） | 2026-07-08 14:00:00 |
|
|
|
-| `room` | 客户名称 | 上海某某有限公司 |
|
|
|
-
|
|
|
-> **注意**：告警模块使用的 `SMS_463791105` 变量为 `deviceName`、`time`、`alarmType`、`alarmContent`，**不能**直接作为邀约模板。若控制台模板变量名不同，请在请求体传入 `templateParam` 覆盖。
|
|
|
-
|
|
|
-**请求体（可选）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| contactId | long | 否 | 覆盖默认联系人；不传则使用 `smsContactId` 或客户主联系人 |
|
|
|
-| templateCode | string | 否 | 覆盖默认模板 CODE；不传则使用 `vpp.sms.invitation-template-code` |
|
|
|
-| templateParam | string | 否 | 覆盖默认模板变量 JSON；须与 `templateCode` 对应模板占位符一致 |
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "短信已发送",
|
|
|
- "data": {
|
|
|
- "smsNotifyStatus": 1,
|
|
|
- "smsNotifyAt": "2026-07-04T17:30:00"
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-##### 2.9.12.7 企业回复邀约
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/dr/invitation/{id}/reply`
|
|
|
-
|
|
|
-**功能描述**：企业确认参与或拒绝邀约；参与时写入/更新 `vpp_dr_participation` 并回写 `participationId`、`declaredCapacityKw`；**已启用 outbound 时同步 UN `CreateOptRequest`**。
|
|
|
-
|
|
|
-**权限**：`dr:participate`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| participate | boolean | 是 | true 参与 / false 拒绝 |
|
|
|
-| declaredCapacityKw | number | 否 | 申报容量 kW（参与时必填） |
|
|
|
-| reason | string | 否 | 拒绝原因（拒绝时必填） |
|
|
|
-
|
|
|
-**状态流转**：
|
|
|
-
|
|
|
-- 参与：`replyStatus=1`，`responseStatus=1`（已申报）
|
|
|
-- 拒绝：`replyStatus=2`，`responseStatus=4`（已取消）
|
|
|
-- 超过 `replyDeadline` 未回复：由定时任务置 `replyStatus=3`
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.10 结算管理
|
|
|
-
|
|
|
-> **数据表**：`vpp_energy_reading_monthly`、`vpp_settlement_bill`、`vpp_settlement_bill_detail`、`vpp_payment_record`
|
|
|
-
|
|
|
-#### 2.10.1 月度电量核算
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/settlement/energyReading`
|
|
|
-
|
|
|
-**功能描述**：查询月度电量核算结果。
|
|
|
-
|
|
|
-**权限**：`settlement:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| customerId | long | 否 | 客户 ID |
|
|
|
-| resourceId | long | 否 | 资源点 ID |
|
|
|
-| settleYear | int | 否 | 结算年 |
|
|
|
-| settleMonth | int | 否 | 结算月 1-12 |
|
|
|
-| calcStatus | int | 否 | 0待核算 1已核算 2异常 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_energy_reading_monthly`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 9001,
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "totalEnergyKwh": 12580.5,
|
|
|
- "peakEnergyKwh": 3200.0,
|
|
|
- "flatEnergyKwh": 4500.0,
|
|
|
- "valleyEnergyKwh": 3800.0,
|
|
|
- "sharpEnergyKwh": 1080.5,
|
|
|
- "genEnergyKwh": 8500.0,
|
|
|
- "calcStatus": 1,
|
|
|
- "calcAt": "2026-06-01T08:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_energy_reading_monthly`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 记录 ID | id |
|
|
|
-| customerId | long | 客户 ID | customer_id |
|
|
|
-| customerName | string | 客户名称（关联） | — |
|
|
|
-| resourceId | long | 资源点 ID | resource_id |
|
|
|
-| resourceName | string | 资源名称（关联） | — |
|
|
|
-| settleYear | int | 结算年 | settle_year |
|
|
|
-| settleMonth | int | 结算月 1-12 | settle_month |
|
|
|
-| totalEnergyKwh | number | 总电量 kWh | total_energy_kwh |
|
|
|
-| peakEnergyKwh | number | 峰段电量 | peak_energy_kwh |
|
|
|
-| flatEnergyKwh | number | 平段电量 | flat_energy_kwh |
|
|
|
-| valleyEnergyKwh | number | 谷段电量 | valley_energy_kwh |
|
|
|
-| sharpEnergyKwh | number | 尖段电量 | sharp_energy_kwh |
|
|
|
-| genEnergyKwh | number | 发电量 kWh | gen_energy_kwh |
|
|
|
-| calcStatus | int | 0待核算 1已核算 2异常 | calc_status |
|
|
|
-| calcAt | string | 核算时间 | calc_at |
|
|
|
-
|
|
|
-#### 2.10.2 触发电量核算
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/settlement/energyReading/calculate`
|
|
|
-
|
|
|
-**功能描述**：触发指定月份电量核算任务。
|
|
|
-
|
|
|
-**权限**：`settlement:calculate`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| settleYear | int | 是 | 结算年 |
|
|
|
-| settleMonth | int | 是 | 结算月 |
|
|
|
-| customerId | long | 否 | 客户 ID，不传则全量核算 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "customerId": 1001
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "核算任务已提交",
|
|
|
- "data": { "taskId": "CALC-202605-001", "customerCount": 1 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.10.3 账单列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/settlement/bill`
|
|
|
-
|
|
|
-**功能描述**：分页查询电费账单列表。
|
|
|
-
|
|
|
-**权限**：`settlement:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| customerId | long | 否 | 客户 ID |
|
|
|
-| paymentStatus | int | 否 | 0未缴 1部分 2已缴 3逾期 |
|
|
|
-| settleYear | int | 否 | 结算年 |
|
|
|
-| settleMonth | int | 否 | 结算月 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_settlement_bill`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 10001,
|
|
|
- "billNo": "BILL-202605-1001",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "totalEnergyKwh": 12580.5,
|
|
|
- "totalAmount": 15680.0,
|
|
|
- "paidAmount": 0,
|
|
|
- "paymentStatus": 0,
|
|
|
- "dueDate": "2026-06-15",
|
|
|
- "generatedAt": "2026-06-01T10:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应 data.records 字段说明**（映射 `vpp_settlement_bill`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 账单 ID | id |
|
|
|
-| billNo | string | 账单编号 | bill_no |
|
|
|
-| customerId | long | 客户 ID | customer_id |
|
|
|
-| customerName | string | 客户名称（关联） | — |
|
|
|
-| settleYear | int | 结算年 | settle_year |
|
|
|
-| settleMonth | int | 结算月 | settle_month |
|
|
|
-| totalEnergyKwh | number | 总电量 kWh | total_energy_kwh |
|
|
|
-| totalAmount | number | 账单总金额（元） | total_amount |
|
|
|
-| paidAmount | number | 已缴金额（元） | paid_amount |
|
|
|
-| paymentStatus | int | 0未缴 1部分 2已缴 3逾期 | payment_status |
|
|
|
-| dueDate | string | 缴费截止日期 | due_date |
|
|
|
-| generatedAt | string | 账单生成时间 | generated_at |
|
|
|
-
|
|
|
-#### 2.10.4 生成账单
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/settlement/bill/generate`
|
|
|
-
|
|
|
-**功能描述**：根据月度电量核算生成电费账单。
|
|
|
-
|
|
|
-**权限**：`settlement:generate`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| settleYear | int | 是 | 结算年 |
|
|
|
-| settleMonth | int | 是 | 结算月 |
|
|
|
-| customerIds | array | 否 | 客户 ID 列表，不传则按已核算客户批量生成 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "customerIds": [1001, 1002]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "账单生成成功",
|
|
|
- "data": { "generatedCount": 2, "billIds": [10001, 10002] },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.10.5 账单详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/settlement/bill/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取账单详情及分时明细。
|
|
|
-
|
|
|
-**权限**：`settlement:view`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 10001,
|
|
|
- "billNo": "BILL-202605-1001",
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "accountNo": "3100060012345",
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "totalEnergyKwh": 12580.5,
|
|
|
- "totalAmount": 15680.0,
|
|
|
- "paidAmount": 0,
|
|
|
- "paymentStatus": 0,
|
|
|
- "dueDate": "2026-06-15",
|
|
|
- "billFileUrl": "https://oss.example.com/bill/10001.pdf",
|
|
|
- "details": [
|
|
|
- { "timePeriod": 1, "timePeriodName": "尖", "energyKwh": 1080.5, "price": 1.5, "amount": 1620.75 },
|
|
|
- { "timePeriod": 2, "timePeriodName": "峰", "energyKwh": 3200.0, "price": 1.2, "amount": 3840.0 },
|
|
|
- { "timePeriod": 3, "timePeriodName": "平", "energyKwh": 4500.0, "price": 0.8, "amount": 3600.0 },
|
|
|
- { "timePeriod": 4, "timePeriodName": "谷", "energyKwh": 3800.0, "price": 0.4, "amount": 1520.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.10.6 账单下载
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/settlement/bill/{id}/download`
|
|
|
-
|
|
|
-**功能描述**：下载账单 PDF 文件。
|
|
|
-
|
|
|
-**权限**：`settlement:view`
|
|
|
-
|
|
|
-**响应**：`Content-Type: application/pdf` 文件流；或返回 `billFileUrl` 重定向。
|
|
|
-
|
|
|
-#### 2.10.7 缴费记录
|
|
|
-
|
|
|
-**GET 缴费记录列表** — `GET /prod-api/service-vpp/settlement/bill/{id}/payment`
|
|
|
-
|
|
|
-**响应 data 示例**（映射 `vpp_payment_record`）：
|
|
|
-
|
|
|
-```json
|
|
|
-[
|
|
|
- {
|
|
|
- "id": 11001,
|
|
|
- "billId": 10001,
|
|
|
- "paymentAmount": 8000.0,
|
|
|
- "paymentMethod": 1,
|
|
|
- "paymentMethodName": "线下转账",
|
|
|
- "paymentDate": "2026-06-10",
|
|
|
- "voucherUrl": "https://oss.example.com/voucher/11001.jpg",
|
|
|
- "remark": "首期付款",
|
|
|
- "createdBy": "operator01",
|
|
|
- "createdByName": "张三",
|
|
|
- "createTime": "2026-06-10T14:00:00"
|
|
|
- }
|
|
|
-]
|
|
|
-```
|
|
|
-
|
|
|
-**缴费记录字段说明**（映射 `vpp_payment_record`）：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 说明 | 数据表字段 |
|
|
|
-|--------|------|------|------------|
|
|
|
-| id | long | 缴费记录 ID | id |
|
|
|
-| billId | long | 账单 ID | bill_id |
|
|
|
-| paymentAmount | number | 缴费金额（元） | payment_amount |
|
|
|
-| paymentMethod | int | 1线下转账 2电费抵扣 3其他 | payment_method |
|
|
|
-| paymentMethodName | string | 缴费方式名称（字典翻译） | — |
|
|
|
-| paymentDate | string | 缴费日期 YYYY-MM-DD | payment_date |
|
|
|
-| voucherUrl | string | 缴费凭证 URL | voucher_url |
|
|
|
-| remark | string | 对账备注 | remark |
|
|
|
-| createdBy | string | 录入人账号 | created_by |
|
|
|
-| createdByName | string | 录入人姓名（关联） | — |
|
|
|
-| createTime | string | 录入时间 | create_time |
|
|
|
-
|
|
|
-**POST 录入线下缴费** — `POST /prod-api/service-vpp/settlement/bill/{id}/payment`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| paymentAmount | number | 是 | 缴费金额 |
|
|
|
-| paymentMethod | int | 是 | 1线下转账 2电费抵扣 3其他 |
|
|
|
-| paymentDate | string | 是 | 缴费日期 YYYY-MM-DD |
|
|
|
-| voucherUrl | string | 否 | 缴费凭证 URL |
|
|
|
-| remark | string | 否 | 对账备注 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "paymentAmount": 8000.0,
|
|
|
- "paymentMethod": 1,
|
|
|
- "paymentDate": "2026-06-10",
|
|
|
- "voucherUrl": "https://oss.example.com/voucher/11001.jpg",
|
|
|
- "remark": "首期付款"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "录入成功",
|
|
|
- "data": {
|
|
|
- "id": 11001,
|
|
|
- "billId": 10001,
|
|
|
- "paidAmount": 8000.0,
|
|
|
- "paymentStatus": 1
|
|
|
- },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.11 信息报送
|
|
|
-
|
|
|
-> **数据表**：`vpp_report_task`、`vpp_report_record`、`vpp_report_data`、`vpp_report_audit_log`
|
|
|
-
|
|
|
-#### 2.11.1 报送任务列表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/report/task`
|
|
|
-
|
|
|
-**功能描述**：分页查询监管报送任务列表。
|
|
|
-
|
|
|
-**权限**：`report:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| taskStatus | int | 否 | 0待填报 1待审核 2报送中 3已完成 4已逾期 |
|
|
|
-| reportOrg | int | 否 | 1交易中心 2能监局 3经信委 4国网上海 |
|
|
|
-| reportCycle | int | 否 | 1月报 2年报 3临时 |
|
|
|
-| deadlineStart | string | 否 | 截止日期起 |
|
|
|
-| deadlineEnd | string | 否 | 截止日期止 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**taskStatus**：0待填报 1待审核 2报送中 3已完成 4已逾期
|
|
|
-
|
|
|
-**响应 data.records 元素**（映射 `vpp_report_task`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 12001,
|
|
|
- "taskNo": "RPT-202605-001",
|
|
|
- "taskName": "2026年5月虚拟电厂运行月报",
|
|
|
- "reportOrg": 1,
|
|
|
- "reportOrgName": "交易中心",
|
|
|
- "reportCycle": 1,
|
|
|
- "reportType": "VPP_MONTHLY",
|
|
|
- "deadline": "2026-06-10T18:00:00",
|
|
|
- "taskStatus": 0,
|
|
|
- "assigneeId": 1001,
|
|
|
- "assigneeName": "张三",
|
|
|
- "remindDays": 3
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.2 报送记录详情
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/report/record/{id}`
|
|
|
-
|
|
|
-**功能描述**：获取报送记录详情及审核流水。
|
|
|
-
|
|
|
-**权限**：`report:view`
|
|
|
-
|
|
|
-**响应 data 示例**（映射 `vpp_report_record` + `vpp_report_audit_log`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 13001,
|
|
|
- "taskId": 12001,
|
|
|
- "taskName": "2026年5月虚拟电厂运行月报",
|
|
|
- "recordNo": "REC-202605-001",
|
|
|
- "reportPeriod": "2026-05",
|
|
|
- "submitMode": 1,
|
|
|
- "recordStatus": 0,
|
|
|
- "reportFileUrl": null,
|
|
|
- "receiptFileUrl": null,
|
|
|
- "retryCount": 0,
|
|
|
- "submittedAt": null,
|
|
|
- "auditLogs": [],
|
|
|
- "formData": null,
|
|
|
- "isDraft": true
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.3 获取预填报数据
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/report/record/{id}/prefill`
|
|
|
-
|
|
|
-**功能描述**：从客户、合同、结算、DR 等模块自动拉取预填报数据。
|
|
|
-
|
|
|
-**权限**：`report:edit`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "reportPeriod": "2026-05",
|
|
|
- "customerCount": 56,
|
|
|
- "totalCapacityKw": 28500.0,
|
|
|
- "totalGenKwh": 1250000.0,
|
|
|
- "totalUseKwh": 980000.0,
|
|
|
- "drEventCount": 3,
|
|
|
- "drTotalSubsidy": 45000.0,
|
|
|
- "formData": {
|
|
|
- "basicInfo": { "vppName": "伍继虚拟电厂", "reportMonth": "2026-05" },
|
|
|
- "resourceStats": { "pvCount": 20, "essCount": 8 },
|
|
|
- "energyData": { "genKwh": 1250000.0, "useKwh": 980000.0 }
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.4 保存填报数据
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/report/record/{id}/data`
|
|
|
-
|
|
|
-**功能描述**：保存或暂存报送填报数据，写入 `vpp_report_data`。
|
|
|
-
|
|
|
-**权限**：`report:edit`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| formData | object | 是 | 填报表单 JSON |
|
|
|
-| isDraft | boolean | 是 | true 草稿 / false 定稿 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "formData": {
|
|
|
- "basicInfo": { "vppName": "伍继虚拟电厂", "reportMonth": "2026-05" },
|
|
|
- "energyData": { "genKwh": 1250000.0, "useKwh": 980000.0 }
|
|
|
- },
|
|
|
- "isDraft": true
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "保存成功",
|
|
|
- "data": { "recordId": 13001, "isDraft": true },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.5 校验填报数据
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/report/record/{id}/validate`
|
|
|
-
|
|
|
-**功能描述**：校验填报数据完整性与逻辑一致性。
|
|
|
-
|
|
|
-**权限**：`report:edit`
|
|
|
-
|
|
|
-**请求参数**：无
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "valid": false,
|
|
|
- "errors": [
|
|
|
- { "field": "energyData.genKwh", "message": "发电量不能为负数" },
|
|
|
- { "field": "resourceStats.pvCount", "message": "光伏数量与系统统计不一致" }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.6 提交审核
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/report/record/{id}/submitAudit`
|
|
|
-
|
|
|
-**功能描述**：提交报送记录进入审核流程，`recordStatus` 变更为 1。
|
|
|
-
|
|
|
-**权限**：`report:submit`
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "提交成功",
|
|
|
- "data": { "recordId": 13001, "recordStatus": 1 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.7 报送审核
|
|
|
-
|
|
|
-**接口地址**：`PUT /prod-api/service-vpp/report/record/{id}/audit`
|
|
|
-
|
|
|
-**功能描述**：审核报送记录，写入 `vpp_report_audit_log`。
|
|
|
-
|
|
|
-**权限**：`report:audit`
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| passed | boolean | 是 | true 通过 / false 驳回 |
|
|
|
-| opinion | string | 否 | 审核意见 |
|
|
|
-| auditLevel | int | 是 | 1填报 2复核 3审批 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "passed": true,
|
|
|
- "opinion": "数据准确",
|
|
|
- "auditLevel": 2
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.8 执行报送
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/report/record/{id}/submit`
|
|
|
-
|
|
|
-**功能描述**：向监管机构执行报送（接口推送或生成文件），失败自动重试（次数由 `vpp.report.retry.max` 配置）。
|
|
|
-
|
|
|
-**权限**：`report:submit`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "recordId": 13001,
|
|
|
- "recordStatus": 3,
|
|
|
- "submitMode": 1,
|
|
|
- "submittedAt": "2026-06-08T10:00:00",
|
|
|
- "reportFileUrl": "https://oss.example.com/report/13001.xlsx",
|
|
|
- "receiptFileUrl": "https://oss.example.com/receipt/13001.pdf"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.11.9 历史报送查询
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/report/history`
|
|
|
-
|
|
|
-**功能描述**：查询历史报送记录。
|
|
|
-
|
|
|
-**权限**：`report:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| reportOrg | int | 否 | 报送机构 |
|
|
|
-| reportPeriod | string | 否 | 报送周期，如 2026-05 |
|
|
|
-| recordStatus | int | 否 | 0草稿 1待审核 2报送中 3成功 4失败 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 13001,
|
|
|
- "recordNo": "REC-202605-001",
|
|
|
- "taskName": "2026年5月虚拟电厂运行月报",
|
|
|
- "reportOrg": 1,
|
|
|
- "reportPeriod": "2026-05",
|
|
|
- "recordStatus": 3,
|
|
|
- "submittedAt": "2026-06-08T10:00:00",
|
|
|
- "receiptFileUrl": "https://oss.example.com/receipt/13001.pdf"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.12 统计报表与数据分析
|
|
|
-
|
|
|
-> **数据来源**：`vpp_energy_summary_daily`、`vpp_energy_reading_monthly`、`vpp_settlement_bill`、`vpp_dr_evaluation`
|
|
|
-
|
|
|
-#### 2.12.1 能源统计报表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/statistics/energy`
|
|
|
-
|
|
|
-**功能描述**：按资源/时间维度统计发用电量。
|
|
|
-
|
|
|
-**权限**：`statistics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceIds | string | 否 | 资源点 ID，逗号分隔 |
|
|
|
-| startDate | string | 是 | 开始日期 YYYY-MM-DD |
|
|
|
-| endDate | string | 是 | 结束日期 YYYY-MM-DD |
|
|
|
-| granularity | string | 否 | day/month，默认 day |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "summary": { "totalGenKwh": 125000.0, "totalUseKwh": 98000.0, "greenRatio": 72.5 },
|
|
|
- "series": [
|
|
|
- { "date": "2026-06-01", "genKwh": 4200.0, "useKwh": 3200.0 },
|
|
|
- { "date": "2026-06-02", "genKwh": 4500.0, "useKwh": 3100.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.2 月度运行报告
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/statistics/monthlyReport`
|
|
|
-
|
|
|
-**功能描述**：生成指定资源点月度运行报告数据。
|
|
|
-
|
|
|
-**权限**：`statistics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| resourceId | long | 否 | 资源点 ID，不传则全站 |
|
|
|
-| year | int | 是 | 年份 |
|
|
|
-| month | int | 是 | 月份 1-12 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "year": 2026,
|
|
|
- "month": 5,
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "genEnergyKwh": 85000.0,
|
|
|
- "useEnergyKwh": 12000.0,
|
|
|
- "maxPowerKw": 480.0,
|
|
|
- "avgPowerKw": 320.5,
|
|
|
- "onlineRate": 0.95,
|
|
|
- "alarmCount": 3,
|
|
|
- "drParticipateCount": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.3 电费结算报表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/statistics/settlementReport`
|
|
|
-
|
|
|
-**功能描述**：电费结算汇总报表。
|
|
|
-
|
|
|
-**权限**：`statistics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| settleYear | int | 是 | 结算年 |
|
|
|
-| settleMonth | int | 否 | 结算月 |
|
|
|
-| customerId | long | 否 | 客户 ID |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "customerCount": 56,
|
|
|
- "totalEnergyKwh": 680000.0,
|
|
|
- "totalAmount": 850000.0,
|
|
|
- "paidAmount": 620000.0,
|
|
|
- "unpaidAmount": 230000.0,
|
|
|
- "overdueCount": 3
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.4 响应结算报表
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/statistics/drSettlement`
|
|
|
-
|
|
|
-**功能描述**：需求响应补贴结算汇总。
|
|
|
-
|
|
|
-**权限**：`statistics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| startDate | string | 是 | 开始日期 |
|
|
|
-| endDate | string | 是 | 结束日期 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "eventCount": 5,
|
|
|
- "totalTargetCapacityKw": 6000.0,
|
|
|
- "totalActualCapacityKw": 5200.0,
|
|
|
- "avgQualifiedRate": 86.7,
|
|
|
- "totalSubsidyAmount": 45000.0,
|
|
|
- "events": [
|
|
|
- {
|
|
|
- "eventId": "EVE_20260623001",
|
|
|
- "eventName": "夏季削峰需求响应",
|
|
|
- "subsidyAmount": 7350.0,
|
|
|
- "qualifiedRate": 87.5
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.5 总能耗统计
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/analytics/energyTotal`
|
|
|
-
|
|
|
-**功能描述**：总能耗/总费用统计，支持多维度视图。
|
|
|
-
|
|
|
-**权限**：`analytics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| view | string | 否 | amount（电量）/ cost（费用），默认 amount |
|
|
|
-| granularity | string | 否 | day/month/year，默认 month |
|
|
|
-| startDate | string | 是 | 开始日期 |
|
|
|
-| endDate | string | 是 | 结束日期 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "view": "amount",
|
|
|
- "granularity": "month",
|
|
|
- "total": 680000.0,
|
|
|
- "unit": "kWh",
|
|
|
- "points": [
|
|
|
- { "period": "2026-01", "value": 620000.0 },
|
|
|
- { "period": "2026-02", "value": 580000.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.6 分时用电分析
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/analytics/timeOfUse`
|
|
|
-
|
|
|
-**功能描述**：按尖峰平谷分析用电结构。
|
|
|
-
|
|
|
-**权限**：`analytics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| customerId | long | 否 | 客户 ID |
|
|
|
-| startDate | string | 是 | 开始日期 |
|
|
|
-| endDate | string | 是 | 结束日期 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "totalEnergyKwh": 12580.5,
|
|
|
- "periods": [
|
|
|
- { "timePeriod": 1, "name": "尖", "energyKwh": 1080.5, "ratio": 0.086 },
|
|
|
- { "timePeriod": 2, "name": "峰", "energyKwh": 3200.0, "ratio": 0.254 },
|
|
|
- { "timePeriod": 3, "name": "平", "energyKwh": 4500.0, "ratio": 0.358 },
|
|
|
- { "timePeriod": 4, "name": "谷", "energyKwh": 3800.0, "ratio": 0.302 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.7 同比/环比分析
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/analytics/trend`
|
|
|
-
|
|
|
-**功能描述**：指标同比/环比趋势分析。
|
|
|
-
|
|
|
-**权限**：`analytics:view`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| metric | string | 是 | 指标：genKwh/useKwh/revenue/subsidy |
|
|
|
-| compareType | string | 是 | yoy（同比）/ mom（环比） |
|
|
|
-| period | string | 是 | 统计周期，如 2026-05 或 2026 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "metric": "genKwh",
|
|
|
- "compareType": "yoy",
|
|
|
- "currentPeriod": "2026-05",
|
|
|
- "currentValue": 1250000.0,
|
|
|
- "compareValue": 1100000.0,
|
|
|
- "changeRate": 0.136,
|
|
|
- "changeDirection": "up"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.12.8 报表导出
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/statistics/{type}/export`
|
|
|
-
|
|
|
-**功能描述**：导出统计报表文件。
|
|
|
-
|
|
|
-**权限**：`statistics:export`
|
|
|
-
|
|
|
-**路径参数**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| type | string | 是 | energy/monthlyReport/settlementReport/drSettlement |
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| format | string | 否 | pdf/xlsx，默认 xlsx |
|
|
|
-| 其他 | — | — | 与对应统计接口查询参数一致 |
|
|
|
-
|
|
|
-**响应**：文件流（`Content-Disposition: attachment`）
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.13 系统管理
|
|
|
-
|
|
|
-> **数据表**：用户/角色/菜单 → `sys_*`；配置 → `sys_config`；字典 → `sys_dict_*`；操作日志 → `sys_oper_log`；电子档案 → `vpp_file_archive`。
|
|
|
-
|
|
|
-#### 2.13.1 用户管理
|
|
|
-
|
|
|
-| 方法 | URL | 说明 | 数据表 |
|
|
|
-|------|-----|------|--------|
|
|
|
-| GET | `/prod-api/service-vpp/system/user` | 用户列表 | `sys_user` |
|
|
|
-| POST | `/prod-api/service-vpp/system/user` | 创建用户 | `sys_user` |
|
|
|
-| GET | `/prod-api/service-vpp/system/user/{userId}` | 用户详情 | `sys_user` |
|
|
|
-| PUT | `/prod-api/service-vpp/system/user/{userId}` | 更新用户 | `sys_user` |
|
|
|
-| DELETE | `/prod-api/service-vpp/system/user/{userId}` | 禁用/删除 | `sys_user`（`del_flag`） |
|
|
|
-| PUT | `/prod-api/service-vpp/system/user/{userId}/role` | 分配角色 | `sys_user_role` |
|
|
|
-| PUT | `/prod-api/service-vpp/system/user/{userId}/resetPassword` | 重置密码 | `sys_user` |
|
|
|
-
|
|
|
-**查询参数（列表）**：`userName`、`nickName`、`phonenumber`、`status`、`deptId`、`tenantId`、`current`、`size`
|
|
|
-
|
|
|
-**创建用户请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "userName": "operator02",
|
|
|
- "nickName": "王五",
|
|
|
- "password": "******",
|
|
|
- "phonenumber": "13800138001",
|
|
|
- "email": "wangwu@example.com",
|
|
|
- "deptId": 101,
|
|
|
- "status": "0",
|
|
|
- "roleIds": [10, 11],
|
|
|
- "tenantId": 1
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**用户列表响应 data.records 元素**（映射 `sys_user`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "userId": 1001,
|
|
|
- "userName": "operator01",
|
|
|
- "nickName": "张三",
|
|
|
- "phonenumber": "13800138000",
|
|
|
- "email": "zhangsan@example.com",
|
|
|
- "deptId": 101,
|
|
|
- "deptName": "运营部",
|
|
|
- "status": "0",
|
|
|
- "tenantId": 1,
|
|
|
- "createTime": "2026-01-01T10:00:00",
|
|
|
- "roles": [{ "roleId": 10, "roleName": "运营人员" }]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**分配角色请求体** — `PUT /system/user/{userId}/role`：
|
|
|
-
|
|
|
-```json
|
|
|
-{ "roleIds": [10, 11] }
|
|
|
-```
|
|
|
-
|
|
|
-**重置密码请求体** — `PUT /system/user/{userId}/resetPassword`：
|
|
|
-
|
|
|
-```json
|
|
|
-{ "password": "NewPass@123" }
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.13.2 角色与菜单权限
|
|
|
-
|
|
|
-| 方法 | URL | 说明 | 数据表 |
|
|
|
-|------|-----|------|--------|
|
|
|
-| GET | `/prod-api/service-vpp/system/role` | 角色列表 | `sys_role` |
|
|
|
-| POST | `/prod-api/service-vpp/system/role` | 创建角色 | `sys_role` |
|
|
|
-| GET | `/prod-api/service-vpp/system/role/{roleId}` | 角色详情 | `sys_role` |
|
|
|
-| PUT | `/prod-api/service-vpp/system/role/{roleId}` | 更新角色 | `sys_role` |
|
|
|
-| DELETE | `/prod-api/service-vpp/system/role/{roleId}` | 删除角色 | `sys_role` |
|
|
|
-| GET | `/prod-api/service-vpp/system/menu` | 菜单树（含按钮权限） | `sys_menu` |
|
|
|
-| GET | `/prod-api/service-vpp/system/role/{roleId}/menu` | 角色已分配菜单 | `sys_role_menu` |
|
|
|
-| PUT | `/prod-api/service-vpp/system/role/{roleId}/menu` | 分配菜单 | `sys_role_menu` |
|
|
|
-
|
|
|
-**分配菜单请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "menuIds": [1001, 1002, 1003]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> 按钮级权限由 `sys_menu.perms` 标识（如 `alarm:manage`），前端按 `menuType`（M 目录 / C 菜单 / F 按钮）渲染。
|
|
|
-
|
|
|
-**角色列表响应 data.records 元素**（映射 `sys_role`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "roleId": 10,
|
|
|
- "roleName": "运营人员",
|
|
|
- "roleKey": "vpp:operator",
|
|
|
- "roleSort": 1,
|
|
|
- "status": "0",
|
|
|
- "remark": "虚拟电厂运营角色",
|
|
|
- "createTime": "2026-01-01T10:00:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**创建/更新角色请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "roleName": "运营人员",
|
|
|
- "roleKey": "vpp:operator",
|
|
|
- "roleSort": 1,
|
|
|
- "status": "0",
|
|
|
- "remark": "虚拟电厂运营角色"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**菜单树响应 data 示例**（映射 `sys_menu`）：
|
|
|
-
|
|
|
-```json
|
|
|
-[
|
|
|
- {
|
|
|
- "menuId": 1000,
|
|
|
- "menuName": "虚拟电厂",
|
|
|
- "parentId": 0,
|
|
|
- "menuType": "M",
|
|
|
- "path": "/vpp",
|
|
|
- "perms": null,
|
|
|
- "children": [
|
|
|
- {
|
|
|
- "menuId": 1001,
|
|
|
- "menuName": "告警管理",
|
|
|
- "parentId": 1000,
|
|
|
- "menuType": "C",
|
|
|
- "path": "alarm",
|
|
|
- "perms": "alarm:view",
|
|
|
- "children": [
|
|
|
- { "menuId": 1002, "menuName": "告警处理", "menuType": "F", "perms": "alarm:manage" }
|
|
|
- ]
|
|
|
- }
|
|
|
- ]
|
|
|
- }
|
|
|
-]
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.13.3 系统配置
|
|
|
-
|
|
|
-| 方法 | URL | 数据表 |
|
|
|
-|------|-----|--------|
|
|
|
-| GET | `/prod-api/service-vpp/system/config` | `sys_config` |
|
|
|
-| GET | `/prod-api/service-vpp/system/config/{configKey}` | `sys_config` |
|
|
|
-| PUT | `/prod-api/service-vpp/system/config/{configKey}` | `sys_config` |
|
|
|
-
|
|
|
-**查询参数**：`configName`、`tenantId`
|
|
|
-
|
|
|
-**更新配置请求体**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "configValue": "900",
|
|
|
- "configName": "默认采集频率秒",
|
|
|
- "remark": "VPP 全局采集间隔"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-VPP 推荐配置键（`config_key`）：
|
|
|
-
|
|
|
-| configKey | 说明 |
|
|
|
-|-----------|------|
|
|
|
-| vpp.collect.interval.default | 默认采集频率（秒） |
|
|
|
-| vpp.data.retention.years | 时序数据保留年数 |
|
|
|
-| vpp.alarm.escalate.minutes | 告警升级间隔（分钟） |
|
|
|
-| vpp.report.retry.max | 报送失败最大重试次数 |
|
|
|
-| vpp.dr.notify.minutes.default | 需求响应默认提前通知（分钟） |
|
|
|
-
|
|
|
-#### 2.13.4 数据字典
|
|
|
-
|
|
|
-| 方法 | URL | 数据表 |
|
|
|
-|------|-----|--------|
|
|
|
-| GET | `/prod-api/service-vpp/system/dict/type` | `sys_dict_type` |
|
|
|
-| GET | `/prod-api/service-vpp/system/dict/data/{dictType}` | `sys_dict_data` |
|
|
|
-
|
|
|
-**字典类型列表响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-[
|
|
|
- {
|
|
|
- "dictId": 1,
|
|
|
- "dictName": "客户类型",
|
|
|
- "dictType": "vpp_customer_type",
|
|
|
- "status": "0",
|
|
|
- "remark": "VPP客户类型枚举"
|
|
|
- }
|
|
|
-]
|
|
|
-```
|
|
|
-
|
|
|
-**字典数据响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-[
|
|
|
- { "dictCode": 1, "dictLabel": "高压", "dictValue": "1", "dictSort": 1, "status": "0" },
|
|
|
- { "dictCode": 2, "dictLabel": "低压商用", "dictValue": "2", "dictSort": 2, "status": "0" },
|
|
|
- { "dictCode": 3, "dictLabel": "居民充电桩", "dictValue": "3", "dictSort": 3, "status": "0" },
|
|
|
- { "dictCode": 4, "dictLabel": "自有资产", "dictValue": "4", "dictSort": 4, "status": "0" }
|
|
|
-]
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.13.5 操作日志
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/system/operLog`
|
|
|
-
|
|
|
-**功能描述**：分页查询系统操作审计日志。
|
|
|
-
|
|
|
-**权限**：`system:operLog:view`
|
|
|
-
|
|
|
-**数据表**：`sys_oper_log`
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| operName | string | 否 | 操作人账号 |
|
|
|
-| title | string | 否 | 模块标题 |
|
|
|
-| businessType | int | 否 | 业务类型 |
|
|
|
-| status | int | 否 | 0正常 1异常 |
|
|
|
-| startTime | string | 否 | 操作时间起 |
|
|
|
-| endTime | string | 否 | 操作时间止 |
|
|
|
-| tenantId | long | 否 | 租户 ID |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "operId": 181001,
|
|
|
- "title": "告警管理",
|
|
|
- "businessType": 2,
|
|
|
- "operName": "operator01",
|
|
|
- "operUrl": "/prod-api/service-vpp/alarm/158001/handle",
|
|
|
- "operIp": "10.0.0.12",
|
|
|
- "status": 0,
|
|
|
- "operTime": "2026-06-23T10:20:00.000+08:00",
|
|
|
- "consumingTime": 125
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.13.6 电子档案
|
|
|
-
|
|
|
-| 方法 | URL | 说明 | 数据表 |
|
|
|
-|------|-----|------|--------|
|
|
|
-| GET | `/prod-api/service-vpp/archive` | 档案列表 | `vpp_file_archive` |
|
|
|
-| POST | `/prod-api/service-vpp/archive` | 上传档案（multipart） | `vpp_file_archive` |
|
|
|
-| GET | `/prod-api/service-vpp/archive/{id}` | 档案详情/预览 | `vpp_file_archive` |
|
|
|
-| GET | `/prod-api/service-vpp/archive/{id}/download` | 下载 | `vpp_file_archive` |
|
|
|
-| DELETE | `/prod-api/service-vpp/archive/{id}` | 软删除 | `vpp_file_archive` |
|
|
|
-
|
|
|
-**查询参数**：`bizType`（CONTRACT / CUSTOMER / RESOURCE 等）、`bizId`、`fileType`、`current`、`size`
|
|
|
-
|
|
|
-**上传表单字段**：
|
|
|
-
|
|
|
-| 字段 | 必填 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| file | 是 | 文件流 |
|
|
|
-| bizType | 是 | 业务类型 |
|
|
|
-| bizId | 是 | 业务主键 ID |
|
|
|
-| remark | 否 | 备注 |
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 5001,
|
|
|
- "fileName": "需求响应合作协议.pdf",
|
|
|
- "fileUrl": "https://oss.example.com/vpp/contract/5001.pdf",
|
|
|
- "fileType": "pdf",
|
|
|
- "fileSize": 2048576,
|
|
|
- "bizType": "CONTRACT",
|
|
|
- "bizId": 3001,
|
|
|
- "createdBy": 1001,
|
|
|
- "createTime": "2026-06-23T09:00:00.000+08:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.14 移动端专用
|
|
|
-
|
|
|
-移动端与 Web 共用 `/prod-api/service-vpp` 接口，以下补充移动端典型场景。
|
|
|
-
|
|
|
-#### 2.14.1 运营端首页
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/mobile/operator/home`
|
|
|
-
|
|
|
-**功能描述**：运营端移动端首页聚合数据。
|
|
|
-
|
|
|
-**权限**：`dashboard:view`
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "summary": {
|
|
|
- "todayGenKwh": 12580.5,
|
|
|
- "onlineDeviceCount": 128,
|
|
|
- "pendingAlarmCount": 5,
|
|
|
- "activeDrEventCount": 1
|
|
|
- },
|
|
|
- "recentAlarms": [
|
|
|
- { "id": 158001, "alarmContent": "功率超限110%", "alarmTime": "2026-06-23T10:15:00", "alarmGrade": 2 }
|
|
|
- ],
|
|
|
- "activeDrEvents": [
|
|
|
- { "id": 6001, "eventName": "夏季削峰需求响应", "startTime": "2026-06-23T14:00:00", "eventStatus": 2 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.14.2 业主端我的资源
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/mobile/owner/resource`
|
|
|
-
|
|
|
-**功能描述**：按当前登录用户关联的 `customerId` 过滤资源列表及实时状态。
|
|
|
-
|
|
|
-**权限**：已登录业主用户
|
|
|
-
|
|
|
-**响应 data 示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "customerId": 1001,
|
|
|
- "customerName": "上海某某有限公司",
|
|
|
- "resources": [
|
|
|
- {
|
|
|
- "resourceId": 2001,
|
|
|
- "resourceName": "浦东光伏站",
|
|
|
- "resourceType": "PV",
|
|
|
- "capacityKw": 500.0,
|
|
|
- "runStatus": 1,
|
|
|
- "activePowerKw": 320.5,
|
|
|
- "todayGenKwh": 1250.0
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.14.3 业主端账单
|
|
|
-
|
|
|
-**接口地址**：`GET /prod-api/service-vpp/mobile/owner/bill`
|
|
|
-
|
|
|
-**功能描述**：业主端查看本人账单列表。
|
|
|
-
|
|
|
-**权限**：已登录业主用户
|
|
|
-
|
|
|
-**请求参数（Query）**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| paymentStatus | int | 否 | 缴费状态 |
|
|
|
-| current | int | 否 | 页码 |
|
|
|
-| size | int | 否 | 每页数量 |
|
|
|
-
|
|
|
-**响应 data.records 元素**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 10001,
|
|
|
- "billNo": "BILL-202605-1001",
|
|
|
- "settleYear": 2026,
|
|
|
- "settleMonth": 5,
|
|
|
- "totalAmount": 15680.0,
|
|
|
- "paidAmount": 0,
|
|
|
- "paymentStatus": 0,
|
|
|
- "dueDate": "2026-06-15"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.14.4 消息通知
|
|
|
-
|
|
|
-| 方法 | URL | 说明 |
|
|
|
-|------|-----|------|
|
|
|
-| GET | `/prod-api/service-vpp/mobile/message` | 消息列表 |
|
|
|
-| PUT | `/prod-api/service-vpp/mobile/message/{id}/read` | 标记已读 |
|
|
|
-
|
|
|
-**消息列表查询参数**：`msgType`（alarm/dr/bill/system）、`isRead`（0/1）、`current`、`size`
|
|
|
-
|
|
|
-**消息列表响应 data.records 元素**（关联 `base_alarm_notice_result` / `sys_notice`）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "id": 14001,
|
|
|
- "msgType": "alarm",
|
|
|
- "title": "功率超限告警",
|
|
|
- "content": "浦东光伏站功率超过额定110%",
|
|
|
- "isRead": 0,
|
|
|
- "bizId": 158001,
|
|
|
- "createTime": "2026-06-23T10:15:00"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**标记已读响应**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "操作成功",
|
|
|
- "data": null,
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 2.14.5 微信订阅消息绑定
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/mobile/wechat/subscribe`
|
|
|
-
|
|
|
-**功能描述**：绑定微信 openId 并订阅消息模板。
|
|
|
-
|
|
|
-**权限**：已登录用户
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 参数名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| code | string | 是 | 微信登录 code |
|
|
|
-| templateIds | array | 是 | 订阅消息模板 ID 列表 |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "code": "wx_login_code_xxx",
|
|
|
- "templateIds": ["TEMPLATE_ALARM_001", "TEMPLATE_DR_001"]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "status": "SUCCESS",
|
|
|
- "code": 200,
|
|
|
- "msg": "绑定成功",
|
|
|
- "data": { "openId": "oXXXX", "subscribedCount": 2 },
|
|
|
- "exception": null
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 2.15 运管平台主动对接（Web 管理）
|
|
|
-
|
|
|
-> 网关前缀：`/prod-api/service-vpp/un`
|
|
|
-> 实现类：`UnIntegrationController` → `VppUnIntegrationService`
|
|
|
-> 用于联调阶段手动触发 Token、注册、Poll；生产环境建议配合 `poll-enabled` 定时任务。
|
|
|
-
|
|
|
-#### 2.15.1 刷新 UN Token
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/un/token/refresh`
|
|
|
-
|
|
|
-**功能描述**：向 UN 发送 `TokenRequest`，刷新本地 Token 缓存（默认 25 分钟有效，UN 侧 JWT 约 30 分钟）。
|
|
|
-
|
|
|
-**权限**：`system:admin` 或联调专用角色（建议）
|
|
|
-
|
|
|
-**前置条件**：`vpp.un.outbound-enabled=true` 且已配置 `vpp.un.base-url`、`vpp.un.dn-id`
|
|
|
-
|
|
|
-**响应 data**：UN `TokenResponse` 原文（含 `token` 字段）
|
|
|
-
|
|
|
-#### 2.15.2 注册 UN
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/un/register`
|
|
|
-
|
|
|
-**功能描述**：向 UN 发送 `CreateRegistrationRequest`，成功后 `registrationID` 写入 `vpp_registration` 及配置缓存。
|
|
|
-
|
|
|
-**响应 data**：UN `CreateRegistrationResponse` 原文
|
|
|
-
|
|
|
-#### 2.15.3 手动 Poll
|
|
|
-
|
|
|
-**接口地址**：`POST /prod-api/service-vpp/un/poll`
|
|
|
-
|
|
|
-**功能描述**：向 UN 发送 `Poll`，解析响应并自动入库/应答：
|
|
|
-
|
|
|
-| Poll 响应 root | 平台动作 |
|
|
|
-|----------------|----------|
|
|
|
-| PollResponse | 无待处理指令 |
|
|
|
-| DistributeEventRequest | 入库 `vpp_dr_event`，同步参与记录 |
|
|
|
-| ReregistrationRequest | 自动重新注册 |
|
|
|
-| CreateReportRequest | 回 `CreateReportResponse` 并按类型上报报告 |
|
|
|
-
|
|
|
-**响应 data**：UN Poll 响应原文
|
|
|
-
|
|
|
-#### 2.15.4 配置项（Nacos / bootstrap.yml）
|
|
|
-
|
|
|
-| 配置键 | 类型 | 默认 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| vpp.un.base-url | string | — | UN 基地址，如 `https://27.115.117.6:32001` |
|
|
|
-| vpp.un.dn-id | string | — | 运营商 ID |
|
|
|
-| vpp.un.dn-name | string | — | 运营商名称（注册报文） |
|
|
|
-| vpp.un.transport-address | string | — | DN 公网回调地址 |
|
|
|
-| vpp.un.outbound-enabled | boolean | false | 启用 DN→UN 主动调用 |
|
|
|
-| vpp.un.poll-enabled | boolean | false | 启用 Poll 定时任务 |
|
|
|
-| vpp.un.poll-interval-sec | int | 10 | Poll 间隔（秒） |
|
|
|
-| vpp.un.crypto-enabled | boolean | false | 启用 SM2/SM3 加解密 |
|
|
|
-| vpp.un.un-public-key | string | — | UN 公钥 Base64 |
|
|
|
-| vpp.un.dn-public-key | string | — | DN 公钥 Base64 |
|
|
|
-| vpp.un.dn-private-key | string | — | DN 私钥 Base64 |
|
|
|
-| vpp.un.price-down-coeff | string | 0.8 | 申报价格下调系数 |
|
|
|
-| vpp.un.token-header | string | Authorization | Token 请求头 |
|
|
|
-| vpp.un.token-prefix | string | Bearer | Token 前缀 |
|
|
|
-| vpp.un.token-ttl-minutes | int | 25 | 本地 Token 缓存分钟数 |
|
|
|
-| vpp.un.auto-ack-clearing | boolean | false | Poll 出清公示后自动 CreateEventResponse |
|
|
|
-| vpp.un.auto-register-on-startup | boolean | false | 启动时自动 Token + 注册 |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 3. 运管平台对接 API（UN/DN）
|
|
|
-
|
|
|
-### 3.1 交互概述
|
|
|
-
|
|
|
-依据 DLT 1867—2024 及《虚拟电厂接口联调须知》，虚拟电厂运营商平台（**DN**）与运管平台（**UN**）通过 REST(HTTP) 交互。
|
|
|
-
|
|
|
-**角色说明**：
|
|
|
-
|
|
|
-- **DN**：本平台，需暴露 HTTP 服务供 UN 调用，同时主动调用 UN
|
|
|
-- **UN**：上海虚拟电厂运管平台
|
|
|
-
|
|
|
-**交互模式**：
|
|
|
-
|
|
|
-| 模式 | 说明 |
|
|
|
-|------|------|
|
|
|
-| 主动推送 | DN 向 UN 发送注册、数据报告 |
|
|
|
-| 被动拉取 | UN 通过 Poll 下发事件、报告请求、重新注册指令 |
|
|
|
-| 轮询 | DN 定时 Poll（建议 ≤30s，注册返回 `pollFreq` 如 PT10S） |
|
|
|
-
|
|
|
-**联调顺序（摘要）**：
|
|
|
-
|
|
|
-1. 获取 Token → 创建注册 → 元数据报告注册
|
|
|
-2. 实时/曲线数据上报
|
|
|
-3. 启动 Poll → 拉取事件 → 参与申报 → 出清分拆 → 确认公示
|
|
|
-4. 负荷预测/可调节能力预测上报
|
|
|
-
|
|
|
-### 3.2 安全机制
|
|
|
-
|
|
|
-| 项目 | 规范 |
|
|
|
-|------|------|
|
|
|
-| 传输 | HTTPS |
|
|
|
-| 请求方式 | POST |
|
|
|
-| 请求体加密 | SM2，使用 **UN 公钥**加密，Base64 编码 |
|
|
|
-| 数字签名 | SM3withSM2，使用 **DN 私钥**签名，Base64 后放入请求头 `X-Sign` |
|
|
|
-| 响应验签 | 从响应头取 `X-Sign`，UN 公钥验签 |
|
|
|
-| 响应解密 | Base64 解码后，DN 私钥 SM2 解密 |
|
|
|
-| Token | JWT，请求头 `Authorization: Bearer {token}`，有效期 **30 分钟** |
|
|
|
-| DN 被动接口 | UN 调用 DN 时：`crypto-enabled=true` 则请求体 SM2 解密 + `X-Sign` 验签；响应体 SM2 加密 + 签名（`VppUnDnCryptoRequestAdvice` / `ResponseAdvice`） |
|
|
|
-
|
|
|
-**密钥**：UN 分配 UN 公钥、DN 公钥、DN 私钥（均 Base64 编码）。联调初期可设 `vpp.un.crypto-enabled=false` 走明文 JSON。
|
|
|
-
|
|
|
-### 3.3 通用服务
|
|
|
-
|
|
|
-#### 3.3.1 获取 Token
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/TokenRequest`
|
|
|
-
|
|
|
-**调用方**：DN → UN
|
|
|
-
|
|
|
-**落库**：无（Token 缓存 Redis）
|
|
|
-
|
|
|
-**请求体（明文结构，实际需 SM2 加密 + SM3withSM2 签名）**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| root | string | 是 | 固定 `TokenRequest` |
|
|
|
-| version | int | 是 | 协议版本，当前为 1 |
|
|
|
-| requestID | string | 是 | UUID，请求唯一标识 |
|
|
|
-| dnID | string | 是 | 虚拟电厂运营商 ID |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "TokenRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "bf992657-d1b1-4634-badd-2be6f1275e4f",
|
|
|
- "dnID": "10010103000002"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应体（TokenResponse）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "TokenResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "bf992657-d1b1-4634-badd-2be6f1275e4f",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 响应字段 | 类型 | 说明 |
|
|
|
-|----------|------|------|
|
|
|
-| root | string | `TokenResponse` |
|
|
|
-| code | int | 200 成功 |
|
|
|
-| description | string | 结果描述 |
|
|
|
-| requestID | string | 与请求一致 |
|
|
|
-| dnID | string | 运营商 ID |
|
|
|
-| token | string | JWT，有效期 30 分钟 |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.4 注册服务
|
|
|
-
|
|
|
-#### 3.4.1 创建注册请求
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/CreateRegistrationRequest`
|
|
|
-
|
|
|
-**功能描述**：首次注册或重新注册，成功后持久化至 `vpp_registration`。
|
|
|
-
|
|
|
-**调用方**：DN → UN
|
|
|
-
|
|
|
-**请求体（CreateRegistrationRequest）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateRegistrationRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "8c03c417-3147-4d33-9d00-1ebbd71b7b09",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "dnName": "上海市自动需求响应平台",
|
|
|
- "registrationID": "208916e4-5b3f-440c-b60c-ffd5b6c37f2a",
|
|
|
- "reportOnly": false,
|
|
|
- "pullMode": true,
|
|
|
- "signature": false,
|
|
|
- "transport": "REST",
|
|
|
- "transportAddress": "http://27.115.117.6:9000"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 字段 | 说明 |
|
|
|
-|------|------|
|
|
|
-| registrationID | 首次注册为空；重新注册必须携带首次返回的 ID |
|
|
|
-| transportAddress | DN 服务公网地址，供 UN 回调 |
|
|
|
-| pullMode | true 表示 UN 通过 Poll 下发指令 |
|
|
|
-
|
|
|
-**响应字段说明**（映射 `vpp_registration`）：
|
|
|
-
|
|
|
-| 响应字段 | 类型 | 说明 | 落库字段 |
|
|
|
-|----------|------|------|----------|
|
|
|
-| registrationID | string | 注册 ID | vpp_registration.registration_id |
|
|
|
-| pollFreq | string | Poll 频率 ISO8601 | — |
|
|
|
-| unID | string | 运管平台 ID | — |
|
|
|
-| code | int | 200 成功 | vpp_registration.reg_status=1 |
|
|
|
-
|
|
|
-**响应体（CreateRegistrationResponse）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateRegistrationResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "8c03c417-3147-4d33-9d00-1ebbd71b7b09",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "unID": "test_un",
|
|
|
- "registrationID": "93eaa056-8553-4eb8-8113-15590cb98224",
|
|
|
- "pollFreq": "PT10S",
|
|
|
- "transport": ["REST"],
|
|
|
- "serviceSpecific": []
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> **重要**：`registrationID` 需持久化至 `vpp_registration` 表，重新注册时必带，否则返回 `WrongRegistrationID`。
|
|
|
-
|
|
|
-#### 3.4.2 DN 侧被动接口（UN 调用 DN）
|
|
|
-
|
|
|
-DN 需实现 HTTP POST 服务端点（`UnDnController`，默认端口 **9906**，路径与服务名一致）。联调时 UN 访问 `{transportAddress}/{服务名}`。
|
|
|
-
|
|
|
-| 服务名 | DN 路径 | 说明 | 实现状态 |
|
|
|
-|--------|---------|------|----------|
|
|
|
-| TokenRequest | `/TokenRequest` | Token 请求（联调回显） | 已实现 |
|
|
|
-| CreateRegistrationRequest | `/CreateRegistrationRequest` | 注册（联调回显） | 已实现 |
|
|
|
-| RegisterReportRequest | `/RegisterReportRequest` | 元数据报告注册回显 | 已实现 |
|
|
|
-| MomentDataReportRequest | `/MomentDataReportRequest` | 实时数据报告回显 | 已实现 |
|
|
|
-| IntervalDataReportRequest | `/IntervalDataReportRequest` | 曲线数据报告回显 | 已实现 |
|
|
|
-| Poll | `/Poll` | UN 询问 DN（联调回显 PollResponse） | 已实现 |
|
|
|
-| **DistributeEventRequest** | `/DistributeEventRequest` | **事件邀约/反馈/出清公示推送** | **已实现，入库 vpp_dr_event** |
|
|
|
-| CreateOptRequest | `/CreateOptRequest` | 参与申报同步 + CreateOptResponse | 已实现 |
|
|
|
-| CreateCqRequest | `/CreateCqRequest` | 分拆出清同步 + CreateCqResponse | 已实现 |
|
|
|
-| CreateEventResponse | `/CreateEventResponse` | 出清公示确认 + 标准响应 | 已实现 |
|
|
|
-
|
|
|
-**被动接口成功响应扩展字段**（便于联调）：
|
|
|
-
|
|
|
-| 字段 | 说明 |
|
|
|
-|------|------|
|
|
|
-| eventID | 运管平台事件 ID |
|
|
|
-| internalId | 本地 `vpp_dr_event.id` |
|
|
|
-| eventStatus | 本地事件状态（0~4） |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.5 询问服务（Poll）
|
|
|
-
|
|
|
-#### 3.5.1 Poll 请求
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/Poll`
|
|
|
-
|
|
|
-**功能描述**：DN 定时轮询 UN，获取待处理指令（事件、报告请求、重新注册等）。
|
|
|
-
|
|
|
-**调用方**：DN → UN
|
|
|
-
|
|
|
-**频率**：注册返回 `pollFreq`，建议 ≤30s
|
|
|
-
|
|
|
-**请求体**：
|
|
|
-
|
|
|
-| 字段名 | 类型 | 必填 | 说明 |
|
|
|
-|--------|------|------|------|
|
|
|
-| root | string | 是 | 固定 `Poll` |
|
|
|
-| version | int | 是 | 协议版本 |
|
|
|
-| requestID | string | 是 | UUID |
|
|
|
-| dnID | string | 是 | 运营商 ID |
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "Poll",
|
|
|
- "version": 1,
|
|
|
- "requestID": "bf992657-d1b1-4634-badd-2be6f1275e4f",
|
|
|
- "dnID": "10010103000002"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**无指令时响应（PollResponse）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "PollResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "bf992657-d1b1-4634-badd-2be6f1275e4f",
|
|
|
- "dnID": "10010103000002"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 3.5.2 Poll 可返回的指令类型
|
|
|
-
|
|
|
-| 响应 root | 说明 | DN 后续动作（service-vpp 自动/手动） |
|
|
|
-|-----------|------|--------------------------------------|
|
|
|
-| PollResponse | 无待处理指令 | 无 |
|
|
|
-| ReregistrationRequest | 重新注册 | `VppUnIntegrationService.register()` |
|
|
|
-| DistributeEventRequest | 事件邀约/申报反馈/分拆通知/出清公示 | `VppDrEventIngestService.ingestDistributeEvent` |
|
|
|
-| CreateReportRequest | 拉取数据报告 | `VppUnReportService.handleCreateReportRequest` |
|
|
|
-
|
|
|
-**定时 Poll**：`vpp.un.poll-enabled=true` 时，`VppUnPollScheduler` 按 `poll-interval-sec` 执行（默认 10s）。
|
|
|
-
|
|
|
-**Token 失效重试**：HTTP 客户端检测 `TokenExpiredException` 等消息后自动刷新 Token 并重试一次。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.6 报告服务
|
|
|
-
|
|
|
-#### 3.6.0 CreateReportRequest 应答流程（Poll 触发）
|
|
|
-
|
|
|
-UN 通过 Poll 返回 `CreateReportRequest` 后，DN 按以下顺序处理（`VppUnReportServiceImpl`）：
|
|
|
-
|
|
|
-1. `POST {UN_BASE}/CreateReportResponse` — 确认收到报告请求
|
|
|
-2. 按 `reportRequestID` 上报对应报告：
|
|
|
-
|
|
|
-| reportRequestID | 后续上报接口 | 数据来源（当前实现） |
|
|
|
-|---------------|--------------|----------------------|
|
|
|
-| MetaDataReport | RegisterReportRequest | `vpp_resource_point`（unResourceId / resourceCode） |
|
|
|
-| IntervalDataReport | IntervalDataReportRequest | 在线资源点 adjustableKw（占位，待接 TDengine 96 点） |
|
|
|
-| MomentDataReport | MomentDataReportRequest | 同上 |
|
|
|
-
|
|
|
-> 完整 96 点曲线、能力预测等需后续对接 TDengine 与预测服务。
|
|
|
-
|
|
|
-#### 3.6.1 元数据报告注册
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/RegisterReportRequest`
|
|
|
-
|
|
|
-**功能描述**：向 UN 注册可上报的数据维度与量测点定义。
|
|
|
-
|
|
|
-**调用方**：DN → UN
|
|
|
-
|
|
|
-**落库**：`vpp_registration.meta_report_id`
|
|
|
-
|
|
|
-**请求体（摘要）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "RegisterReportRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "53dc702a-e400-4b06-bb06-335ea876171b",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "reportRequestID": "MetaDataReport",
|
|
|
- "report": [
|
|
|
- {
|
|
|
- "createdDateTime": "2019-11-30 12:00:00",
|
|
|
- "reportDescription": {
|
|
|
- "rID": 0,
|
|
|
- "metric": { "metricName": "AP", "multiplier": "k", "symbol": "W" },
|
|
|
- "reportDataSource": { "resourceID": ["10010103000002"] },
|
|
|
- "readingType": "Direct_Read",
|
|
|
- "samplingRate": { "minPeriod": "PT15M", "maxPeriod": "PT15M" }
|
|
|
- }
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**数据维度**：虚拟电厂运营商、聚合用户（户号）、分路可调节资源。
|
|
|
-
|
|
|
-**主要量测点（MetricName）**：
|
|
|
-
|
|
|
-| 量测点 | 单位 | 说明 |
|
|
|
-|--------|------|------|
|
|
|
-| AP | kW | 有功功率 |
|
|
|
-| AP_E | kWh | 用电量 |
|
|
|
-| AP_PE | kWh | 发电量 |
|
|
|
-| 实时上调/下调能力 | kW | 仅运营商维度 |
|
|
|
-| 实时响应时间 | s | 仅运营商维度 |
|
|
|
-| 实时爬坡速度 | kW/min | 仅运营商维度 |
|
|
|
-| 日前申报上调/下调能力 | kW | 预测数据 |
|
|
|
-
|
|
|
-**响应体（RegisterReportResponse）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "RegisterReportResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "53dc702a-e400-4b06-bb06-335ea876171b",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "reportRequestID": "MetaDataReport"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**上报日志**：每次调用写入 `vpp_report_log`（`report_type=RegisterReport`）。
|
|
|
-
|
|
|
-#### 3.6.2 实时数据报告（MomentDataReportRequest）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/MomentDataReportRequest`
|
|
|
-
|
|
|
-**功能描述**：上报 15 分钟级实时运行数据及能力数据。
|
|
|
-
|
|
|
-**数据来源**：TDengine `device_metrics` 聚合
|
|
|
-
|
|
|
-**落库**：`vpp_report_log`（`report_type=MomentData`）
|
|
|
-
|
|
|
-| 项目 | 规格 |
|
|
|
-|------|------|
|
|
|
-| 密度 | 15 分钟 |
|
|
|
-| 频率 | 每 15 分钟，24 小时不间断 |
|
|
|
-| 延迟 | ≤ 30 分钟 |
|
|
|
-| 时标含义 | 00:15:00 代表 00:00:00~00:15:00 的平均/累加 |
|
|
|
-
|
|
|
-**请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "MomentDataReportRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "a4af721e-6a52-4191-af84-71b778d48d6f",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "reportRequestID": "MomentDataReport",
|
|
|
- "createdDateTime": "2026-06-23 10:15:00",
|
|
|
- "report": [
|
|
|
- {
|
|
|
- "resourceID": "10010103000002",
|
|
|
- "metricName": "AP",
|
|
|
- "value": 1250.5,
|
|
|
- "multiplier": "k",
|
|
|
- "symbol": "W"
|
|
|
- },
|
|
|
- {
|
|
|
- "resourceID": "RES-PV-001",
|
|
|
- "metricName": "AP",
|
|
|
- "value": 320.5,
|
|
|
- "multiplier": "k",
|
|
|
- "symbol": "W"
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**能力数据**：须提前 30 分钟上报（如 9:00 上报 9:30 的能力）。
|
|
|
-
|
|
|
-#### 3.6.3 曲线数据报告（IntervalDataReportRequest）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/IntervalDataReportRequest`
|
|
|
-
|
|
|
-**功能描述**：上报上一日 96 点有功功率曲线及日前申报能力。
|
|
|
-
|
|
|
-**数据来源**：TDengine 日聚合 + `vpp_energy_summary_daily`
|
|
|
-
|
|
|
-**落库**：`vpp_report_log`（`report_type=IntervalData`）
|
|
|
-
|
|
|
-| 项目 | 规格 |
|
|
|
-|------|------|
|
|
|
-| 频率 | 每日一次 |
|
|
|
-| 截止 | 次日 06:00 前 |
|
|
|
-| 数据点 | 96 点/日（15 分钟间隔，00:15~次日 00:00） |
|
|
|
-| 内容 | 上日有功功率 96 点 + 日前申报能力等 |
|
|
|
-
|
|
|
-**请求体示例（节选）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "IntervalDataReportRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "b5bf832f-7b63-5202-bg95-82c889e59g7g",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "reportRequestID": "IntervalDataReport",
|
|
|
- "createdDateTime": "2026-06-24 05:30:00",
|
|
|
- "report": [
|
|
|
- {
|
|
|
- "resourceID": "10010103000002",
|
|
|
- "metricName": "AP",
|
|
|
- "intervals": [
|
|
|
- { "time": "2026-06-23 00:15:00", "value": 980.0 },
|
|
|
- { "time": "2026-06-23 00:30:00", "value": 965.5 }
|
|
|
- ]
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 3.6.4 可调节能力负荷预测（RegulateForecastReportRequest）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/RegulateForecastReportRequest`
|
|
|
-
|
|
|
-**功能描述**：上报次日可调节能力负荷预测数据。
|
|
|
-
|
|
|
-**调用方**：DN → UN
|
|
|
-
|
|
|
-**数据来源**：`vpp_customer`（dr_up/down_capacity_kw）+ 资源预测算法
|
|
|
-
|
|
|
-**落库**：`vpp_report_log`（`report_type=RegulateForecast`）
|
|
|
-
|
|
|
-**报送要求**：每日 6:00 前完成次日数据报送；须包含 96 点预测数据。
|
|
|
-
|
|
|
-**请求体示例（节选）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "RegulateForecastReportRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "c6cg943g-8c74-6313-ch06-93d990f60h8h",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "forecastDate": "2026-06-24",
|
|
|
- "upCapacityKw": [
|
|
|
- { "time": "2026-06-24 00:15:00", "value": 1500.0 }
|
|
|
- ],
|
|
|
- "downCapacityKw": [
|
|
|
- { "time": "2026-06-24 00:15:00", "value": 2000.0 }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "RegulateForecastReportResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "c6cg943g-8c74-6313-ch06-93d990f60h8h",
|
|
|
- "dnID": "10010103000002"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-#### 3.6.5 数据报告统一响应（DataReportResponse）
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "DataReportResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "a4af721e-6a52-4191-af84-71b778d48d6f",
|
|
|
- "dnID": "10010103000002"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.7 事件与参与服务
|
|
|
-
|
|
|
-#### 3.7.1 事件下发（DistributeEventRequest）
|
|
|
-
|
|
|
-通过 **Poll 返回** 或 **UN 推送** `POST {DN}/DistributeEventRequest` 到达 DN，解析后写入 `vpp_dr_event`（`raw_payload` 存原文）。
|
|
|
-
|
|
|
-**Event 结构（联调 JSON 20251127）**：
|
|
|
-
|
|
|
-| 节点 | 说明 |
|
|
|
-|------|------|
|
|
|
-| events[].descriptor | eventID、notification、control、filing、lastFiling、deadline 等 |
|
|
|
-| events[].activePeriod[] | dtstart、dtend（活动期，可多段） |
|
|
|
-| events[].signals.signal[] | ENERGY_PRICE → subsidyPrice；DEMAND_CHARGE → targetCapacityKw |
|
|
|
-| events[].target.resources[] | 户号申报/出清明细（account + values[].value） |
|
|
|
-
|
|
|
-**descriptor 关键字段映射（入库）**：
|
|
|
-
|
|
|
-| UN 字段 | 本地字段 | 映射规则 |
|
|
|
-|---------|----------|----------|
|
|
|
-| notification | responseType | mediumterm→1 日前，days→2 日内，near→3 秒级 |
|
|
|
-| control | eventType | peakClipping→1 削峰，fillValley→2 填谷 |
|
|
|
-| DEMAND_CHARGE signal | targetCapacityKw | 取 irregular.values[0].value |
|
|
|
-| ENERGY_PRICE signal | subsidyPrice | 取 irregular.values[0].value |
|
|
|
-| filing/lastFiling/resources | eventStatus 阶段 | 见 `VppUnEventPhase` |
|
|
|
-
|
|
|
-**业务阶段识别（VppUnEventPhase）**：
|
|
|
-
|
|
|
-| 阶段 | 条件 | 本地状态 |
|
|
|
-|------|------|----------|
|
|
|
-| INVITATION | filing=true，resources 空 | 0 待参与 |
|
|
|
-| DECLARE_FEEDBACK | filing=true，resources 有申报量 | 1 已申报 |
|
|
|
-| SPLIT_NOTICE | filing=false，lastFiling=true | 1 已申报 |
|
|
|
-| CLEARING_PUBLICITY | resources 含出清量 | 1 已申报（待 ack-clearing） |
|
|
|
-
|
|
|
-**Poll/推送示例（节选，完整样例见 §5.6）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "DistributeEventRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "a18b7934-43fe-4cae-bafc-5d185dd21e34",
|
|
|
- "dnID": "10010103000052",
|
|
|
- "events": [
|
|
|
- {
|
|
|
- "descriptor": {
|
|
|
- "eventID": "YY#1100_10010103000052",
|
|
|
- "control": "peakClipping",
|
|
|
- "notification": "mediumterm",
|
|
|
- "filing": true,
|
|
|
- "deadline": "2025-11-28 12:59:00"
|
|
|
- },
|
|
|
- "activePeriod": [
|
|
|
- { "dtstart": "2025-11-28T13:00:00", "dtend": "2025-11-28T18:00:00" }
|
|
|
- ],
|
|
|
- "signals": {
|
|
|
- "signal": [
|
|
|
- {
|
|
|
- "signalName": "ENERGY_PRICE",
|
|
|
- "intervals": { "irregular": { "values": [{ "value": 6 }] } }
|
|
|
- },
|
|
|
- {
|
|
|
- "signalName": "DEMAND_CHARGE",
|
|
|
- "intervals": { "irregular": { "values": [{ "value": 400 }] } }
|
|
|
- }
|
|
|
- ]
|
|
|
- },
|
|
|
- "target": { "resources": [] }
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**参与记录同步**：`target.resources[]` 或 `CreateOptRequest.list[]` 中 `account` 匹配 `vpp_customer.account_no`，写入 `vpp_dr_participation`。
|
|
|
-
|
|
|
-#### 3.7.2 创建参与请求（CreateOptRequest）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/CreateOptRequest`
|
|
|
-
|
|
|
-**功能描述**：向 UN 申报参与（optIn）或拒绝（optOut）。
|
|
|
-
|
|
|
-**触发方式**：
|
|
|
-
|
|
|
-- Web：`POST /dr/event/{id}/participate`（outbound 启用时自动上报）
|
|
|
-- 联调：UN 推送至 DN `/CreateOptRequest`（本地同步 + 回显 CreateOptResponse）
|
|
|
-
|
|
|
-**参与请求体（optIn，官方格式）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateOptRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "111",
|
|
|
- "dnID": "10010103000052",
|
|
|
- "eventID": "YY#1100_10010103000052",
|
|
|
- "optType": "optIn",
|
|
|
- "createdDateTime": "2025-11-27 13:34:00",
|
|
|
- "priceDownCoeff": "0.8",
|
|
|
- "list": [
|
|
|
- { "load": "10000", "account": "3101330499683", "needzk": "是" },
|
|
|
- { "load": "90000", "account": "3100149000967", "needzk": "否" }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-| 字段 | 说明 |
|
|
|
-|------|------|
|
|
|
-| optType | optIn 参与 / optOut 拒绝 |
|
|
|
-| list[].account | 电力户号（对应 vpp_customer.account_no） |
|
|
|
-| list[].load | 申报容量 kW（字符串） |
|
|
|
-| list[].needzk | 是否需要直控：是/否 |
|
|
|
-| priceDownCoeff | 价格下调系数，默认 0.8 |
|
|
|
-
|
|
|
-**拒绝请求体（optOut）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateOptRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "111",
|
|
|
- "dnID": "10010103000052",
|
|
|
- "eventID": "YY#1100_10010103000052",
|
|
|
- "optType": "optOut"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应（CreateOptResponse）**：回显请求字段 + `code=200`。
|
|
|
-
|
|
|
-#### 3.7.3 分拆出清申报（CreateCqRequest）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/CreateCqRequest`
|
|
|
-
|
|
|
-**功能描述**：末位运营商按户号分拆出清量；结构与 CreateOptRequest 一致，地址改为 `/CreateCqRequest`。
|
|
|
-
|
|
|
-**触发方式**：Web `POST /dr/event/{id}/clearing`（outbound 启用时自动上报）
|
|
|
-
|
|
|
-**请求体示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateCqRequest",
|
|
|
- "version": 1,
|
|
|
- "requestID": "111",
|
|
|
- "dnID": "10010103000052",
|
|
|
- "eventID": "YY#1100_10010103000052",
|
|
|
- "optType": "optIn",
|
|
|
- "createdDateTime": "2025-11-27 13:34:00",
|
|
|
- "priceDownCoeff": "0.8",
|
|
|
- "list": [
|
|
|
- { "load": "10000", "account": "3101330499683" },
|
|
|
- { "load": "90000", "account": "3100149000967" }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-> 削峰出清量为负数、填谷为正数（UN 侧约定）；本地 Web 出清使用正值 kW，上报 UN 前按户号汇总。
|
|
|
-
|
|
|
-#### 3.7.4 确认出清公示（CreateEventResponse）
|
|
|
-
|
|
|
-**接口地址**：`POST {UN_BASE}/CreateEventResponse`
|
|
|
-
|
|
|
-**功能描述**：收到 UN 出清公示（Poll 返回 DistributeEventRequest / CLEARING_PUBLICITY）后确认。
|
|
|
-
|
|
|
-**触发方式**：
|
|
|
-
|
|
|
-- Web：`POST /dr/event/{id}/ack-clearing`
|
|
|
-- 配置：`vpp.un.auto-ack-clearing=true`
|
|
|
-
|
|
|
-**请求体（官方格式）**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "root": "CreateEventResponse",
|
|
|
- "version": 1,
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "a42bb01d-2395-4038-a95c-7691a9273fc4",
|
|
|
- "dnID": "10010103000002",
|
|
|
- "eventResponses": [
|
|
|
- {
|
|
|
- "optType": "optIn",
|
|
|
- "code": 200,
|
|
|
- "description": "ok",
|
|
|
- "requestID": "9ab66db1-8fd4-4b03-8fd0-c97005a7e33f",
|
|
|
- "qualifiedEventID": {
|
|
|
- "eventID": "YY#1100_10010103000052",
|
|
|
- "modificationNumber": 0
|
|
|
- }
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**本地效果**：`vpp_dr_event.eventStatus=2`，初始化 `vpp_dr_execution`。
|
|
|
-
|
|
|
-#### 3.7.5 需求响应交互时序
|
|
|
-
|
|
|
-```mermaid
|
|
|
-sequenceDiagram
|
|
|
- participant Web as Web/移动端
|
|
|
- participant DN as 虚拟电厂平台(DN)
|
|
|
- participant UN as 运管平台(UN)
|
|
|
-
|
|
|
- DN->>UN: TokenRequest
|
|
|
- DN->>UN: CreateRegistrationRequest
|
|
|
- loop poll-interval-sec
|
|
|
- DN->>UN: Poll
|
|
|
- UN-->>DN: DistributeEventRequest(邀约)
|
|
|
- end
|
|
|
- Web->>DN: POST /dr/event/{id}/participate
|
|
|
- DN->>UN: CreateOptRequest(optIn)
|
|
|
- UN-->>DN: Poll → DistributeEventRequest(申报反馈)
|
|
|
- UN-->>DN: Poll → DistributeEventRequest(分拆通知)
|
|
|
- Web->>DN: POST /dr/event/{id}/clearing
|
|
|
- DN->>UN: CreateCqRequest
|
|
|
- UN-->>DN: Poll → DistributeEventRequest(出清公示)
|
|
|
- Web->>DN: POST /dr/event/{id}/ack-clearing
|
|
|
- DN->>UN: CreateEventResponse
|
|
|
- Web->>DN: POST /dr/event/{id}/complete
|
|
|
- Web->>DN: GET /dr/event/{id}/evaluation
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.8 信息对象服务（车网互动）
|
|
|
-
|
|
|
-> 车网互动相关接口为车网项目个性化能力，一般 VPP 运营商可不开发。
|
|
|
-
|
|
|
-| 方向 | 说明 |
|
|
|
-|------|------|
|
|
|
-| UN → DN | Poll 返回 ObjectMessage（启停充放电、功率调节） |
|
|
|
-| DN → UN | ObjectMessageResponse（接收确认） |
|
|
|
-| DN → UN | ObjectMessage（执行结果通知） |
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.9 UN 侧错误码
|
|
|
-
|
|
|
-| code | description | 处理建议 |
|
|
|
-|------|-------------|----------|
|
|
|
-| 200 | ok | 正常 |
|
|
|
-| 400 | WrongRoot | 检查接口名称 |
|
|
|
-| 400 | UnregisteredDn | 重新 CreateRegistrationRequest |
|
|
|
-| 400 | DnNotExist | 检查 dnID |
|
|
|
-| 400 | WrongRegistrationID | 检查 registrationID |
|
|
|
-| 400 | EventNotExist | 事件不存在 |
|
|
|
-| 400 | LoadForecastDataNot96Points | 补全 96 点预测数据 |
|
|
|
-| 400 | JsonWrong | 检查 JSON 格式 |
|
|
|
-| 500 | NoToken | 先获取 Token |
|
|
|
-| 500 | JWTDecodeException | Token 解码失败 |
|
|
|
-| 500 | TokenExpiredException | Token 过期，重新获取 |
|
|
|
-| 500 | JWTVerificationException | Token 无效 |
|
|
|
-
|
|
|
-**Token 异常响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "timestamp": "2021-11-12T08:29:14.038+0000",
|
|
|
- "status": 500,
|
|
|
- "error": "Internal Server Error",
|
|
|
- "message": "JWTVerificationException",
|
|
|
- "path": "/QueryRegistrationRequest"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-### 3.10 平台实现与配置（service-vpp）
|
|
|
-
|
|
|
-#### 3.10.1 代码模块映射
|
|
|
-
|
|
|
-| 能力 | 主要类 | 说明 |
|
|
|
-|------|--------|------|
|
|
|
-| DN 被动接口 | `UnDnController` / `VppUnDnServiceImpl` | UN 调用 DN |
|
|
|
-| DN 主动客户端 | `VppUnHttpExecutor` / `VppUnClient` | DN 调用 UN |
|
|
|
-| Token 缓存 | `VppUnTokenHolder` | 自动刷新、失败重试 |
|
|
|
-| 国密 | `VppUnCryptoService` + `VppUnDnCrypto*Advice` | SM2/SM3withSM2 |
|
|
|
-| 事件入库 | `VppDrEventIngestServiceImpl` / `VppUnEventParser` | DistributeEventRequest 解析 |
|
|
|
-| 参与同步 | `VppUnDrSyncServiceImpl` | account → vpp_dr_participation |
|
|
|
-| 执行初始化 | `VppDrExecutionBootstrapServiceImpl` | ack 后创建 execution |
|
|
|
-| Poll 调度 | `VppUnPollScheduler` | 定时 Poll |
|
|
|
-| 报告应答 | `VppUnReportServiceImpl` | CreateReportRequest 链路 |
|
|
|
-| Web 联调 | `UnIntegrationController` | /un/token、/register、/poll |
|
|
|
-| 报文构造 | `VppUnMessageBuilder` | 标准 JSON 报文 |
|
|
|
-| 启动注册 | `VppUnBootstrapRunner` | auto-register-on-startup |
|
|
|
-
|
|
|
-#### 3.10.2 服务端口与路径
|
|
|
-
|
|
|
-| 类型 | 地址示例 |
|
|
|
-|------|----------|
|
|
|
-| 内部 Web API | `http://{host}:9906` 经网关 `/prod-api/service-vpp/...` |
|
|
|
-| DN 被动 UN 接口 | `http://{公网IP}:9906/TokenRequest` 等（无网关前缀） |
|
|
|
-| UN 主动调用目标 | `vpp.un.base-url` + `/Poll`、`/CreateOptRequest` 等 |
|
|
|
-
|
|
|
-#### 3.10.3 联调检查清单
|
|
|
-
|
|
|
-1. 配置 `vpp.un.dn-id`、`transport-address`、密钥（或 crypto-enabled=false）
|
|
|
-2. `POST /un/token/refresh` → 获取 Token
|
|
|
-3. `POST /un/register` → 保存 registrationID
|
|
|
-4. `vpp.un.poll-enabled=true` 或手动 `POST /un/poll` → 事件入库
|
|
|
-5. Web 参与/出清/确认 → 验证 UN 侧收到 Opt/Cq/EventResponse
|
|
|
-6. 客户档案 `account_no` 与 UN 户号一致
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 4. 外部监管报送接口
|
|
|
-
|
|
|
-采用适配器模式，由报送服务统一调度，各机构独立实现。内部任务与记录对应 `vpp_report_task`、`vpp_report_record`、`vpp_report_data`。
|
|
|
-
|
|
|
-| 机构 | 适配器 | 对接方式 | reportOrg 枚举 | 说明 |
|
|
|
-|------|--------|----------|----------------|------|
|
|
|
-| 上海电力交易中心 | `TradeCenterReportAdapter` | REST API / 文件上传 | 1 | 按交易中心规范 |
|
|
|
-| 华东能监局 | `EnergyBureauReportAdapter` | 文件报送 | 2 | 生成标准格式文件 |
|
|
|
-| 上海市经信委 | `EconomyInfoReportAdapter` | REST API | 3 | 按月/年/临时 |
|
|
|
-| 国网上海电力 | `StateGridReportAdapter` | REST API | 4 | 运行与响应数据 |
|
|
|
-
|
|
|
-**报送重试策略**：失败后自动重试，次数由 `sys_config.vpp.report.retry.max` 控制（默认 3 次），间隔 1min / 5min / 15min（指数退避）。
|
|
|
-
|
|
|
-**内部触发接口**：`POST /prod-api/service-vpp/report/record/{id}/submit`（见 2.11.8）
|
|
|
-
|
|
|
-### 4.1 交易中心 REST 报送（示例）
|
|
|
-
|
|
|
-**接口地址**：`POST {TRADE_CENTER_BASE}/vpp/report/submit`（由适配器封装）
|
|
|
-
|
|
|
-**功能描述**：向上海电力交易中心推送月度运行数据。
|
|
|
-
|
|
|
-**触发方式**：内部 `TradeCenterReportAdapter` 调用
|
|
|
-
|
|
|
-**请求体**（由 `vpp_report_data.form_data` 转换）：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "reportPeriod": "2026-05",
|
|
|
- "vppName": "伍继虚拟电厂",
|
|
|
- "totalCapacityKw": 28500.0,
|
|
|
- "totalGenKwh": 1250000.0,
|
|
|
- "totalUseKwh": 980000.0,
|
|
|
- "drEventCount": 3,
|
|
|
- "drTotalSubsidy": 45000.0,
|
|
|
- "attachments": [
|
|
|
- { "fileName": "运行月报.xlsx", "fileUrl": "https://oss.example.com/report/13001.xlsx" }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**响应示例**：
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "code": 200,
|
|
|
- "message": "报送成功",
|
|
|
- "receiptNo": "TC-202606080001",
|
|
|
- "receiptUrl": "https://trade.example.com/receipt/TC-202606080001.pdf"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**落库**：更新 `vpp_report_record.record_status=3`、`receipt_file_url`、`submitted_at`。
|
|
|
-
|
|
|
-### 4.2 能监局文件报送（示例）
|
|
|
-
|
|
|
-**接口地址**：文件上传至指定 SFTP/OSS 目录（由 `EnergyBureauReportAdapter` 封装）
|
|
|
-
|
|
|
-**请求**：生成符合能监局模板的标准格式文件（xlsx/pdf）
|
|
|
-
|
|
|
-**响应**：文件上传成功回执；`vpp_report_record.receipt_file_url` 存储回执路径
|
|
|
-
|
|
|
-### 4.3 经信委 REST 报送（示例）
|
|
|
-
|
|
|
-**接口地址**：`POST {ECONOMY_BASE}/api/vpp/monthlyReport`
|
|
|
-
|
|
|
-**请求头**：`Authorization: Bearer {机构Token}`
|
|
|
-
|
|
|
-**请求体**：同 4.1，`reportOrg=3`
|
|
|
-
|
|
|
-**响应**：`{ "success": true, "recordId": "EIC-202605-001" }`
|
|
|
-
|
|
|
-### 4.4 国网上海 REST 报送（示例）
|
|
|
-
|
|
|
-**接口地址**：`POST {STATE_GRID_BASE}/vpp/data/upload`
|
|
|
-
|
|
|
-**请求体**：运行数据 + 需求响应执行数据（来源 `vpp_dr_evaluation`、`vpp_energy_summary_daily`）
|
|
|
-
|
|
|
-**响应**：`{ "status": "ACCEPTED", "batchId": "SG-20260608001" }`
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 5. 附录
|
|
|
-
|
|
|
-### 5.1 内部 API 模块索引
|
|
|
-
|
|
|
-| 模块 | 路径前缀 | 主要接口数 |
|
|
|
-|------|----------|------------|
|
|
|
-| 认证 | `/prod-api/service-vpp/auth` | 4 |
|
|
|
-| 首页 | `/prod-api/service-vpp/dashboard` | 4 |
|
|
|
-| 客户 | `/prod-api/service-vpp/customer` | 10+ |
|
|
|
-| 合同 | `/prod-api/service-vpp/contract` | 8+ |
|
|
|
-| 资源 | `/prod-api/service-vpp/resource` | 10+ |
|
|
|
-| 监控 | `/prod-api/service-vpp/monitor` | 4 |
|
|
|
-| 告警 | `/prod-api/service-vpp/alarm` | 15+ |
|
|
|
-| 需求响应 | `/prod-api/service-vpp/dr` | 20+ |
|
|
|
-| 运管联调 | `/prod-api/service-vpp/un` | 3 |
|
|
|
-| 结算 | `/prod-api/service-vpp/settlement` | 8+ |
|
|
|
-| 报送 | `/prod-api/service-vpp/report` | 10+ |
|
|
|
-| 统计 | `/prod-api/service-vpp/statistics` | 6+ |
|
|
|
-| 分析 | `/prod-api/service-vpp/analytics` | 4 |
|
|
|
-| 系统 | `/prod-api/service-vpp/system` | 10+ |
|
|
|
-| 移动端 | `/prod-api/service-vpp/mobile` | 6+ |
|
|
|
-
|
|
|
-### 5.2 运管平台 API 索引
|
|
|
-
|
|
|
-| 服务类型 | 接口 | 方向 | 实现 |
|
|
|
-|----------|------|------|------|
|
|
|
-| 通用 | TokenRequest | DN→UN | 已实现 |
|
|
|
-| 注册 | CreateRegistrationRequest | DN→UN | 已实现 |
|
|
|
-| 询问 | Poll | DN→UN | 已实现（含定时） |
|
|
|
-| 事件 | DistributeEventRequest | UN→DN / Poll | 已实现 |
|
|
|
-| 报告 | CreateReportResponse | DN→UN | 已实现 |
|
|
|
-| 报告 | RegisterReportRequest | DN→UN | 已实现（Poll 触发） |
|
|
|
-| 报告 | MomentDataReportRequest | DN→UN | 已实现（Poll 触发，占位数据） |
|
|
|
-| 报告 | IntervalDataReportRequest | DN→UN | 已实现（Poll 触发，占位数据） |
|
|
|
-| 报告 | RegulateForecastReportRequest | DN→UN | 待完善 |
|
|
|
-| 参与 | CreateOptRequest | DN→UN | 已实现 |
|
|
|
-| 参与 | CreateCqRequest | DN→UN | 已实现 |
|
|
|
-| 事件 | CreateEventResponse | DN→UN | 已实现 |
|
|
|
-| 对象 | ObjectMessage | UN↔DN | 未实现 |
|
|
|
-
|
|
|
-### 5.3 权限码清单（节选）
|
|
|
-
|
|
|
-| 权限码 | 说明 |
|
|
|
-|--------|------|
|
|
|
-| dashboard:view | 首页查看 |
|
|
|
-| customer:access:create | 提交准入 |
|
|
|
-| customer:access:audit | 准入审核 |
|
|
|
-| contract:create | 创建合同 |
|
|
|
-| contract:audit | 合同审核 |
|
|
|
-| resource:manage | 资源管理 |
|
|
|
-| device:control | 设备远程控制 |
|
|
|
-| alarm:manage | 告警管理 |
|
|
|
-| dr:participate | 需求响应参与 |
|
|
|
-| dr:manage | 需求响应管理（含邀约下发） |
|
|
|
-| settlement:manage | 结算管理 |
|
|
|
-| report:submit | 信息报送 |
|
|
|
-| system:admin | 系统管理 |
|
|
|
-
|
|
|
-### 5.4 内部 API 与数据表映射（节选）
|
|
|
-
|
|
|
-| API 路径前缀 | 主要数据表 | 类型 |
|
|
|
-|--------------|------------|------|
|
|
|
-| `/prod-api/service-vpp/auth`、`/prod-api/service-vpp/system/user` | `sys_user`、`sys_user_role` | usky `sys_*` |
|
|
|
-| `/prod-api/service-vpp/system/role`、`/prod-api/service-vpp/system/menu` | `sys_role`、`sys_menu`、`sys_role_menu` | usky `sys_*` |
|
|
|
-| `/prod-api/service-vpp/system/config` | `sys_config` | usky `sys_*` |
|
|
|
-| `/prod-api/service-vpp/system/dict` | `sys_dict_type`、`sys_dict_data` | usky `sys_*` |
|
|
|
-| `/prod-api/service-vpp/system/operLog` | `sys_oper_log` | usky `sys_*` |
|
|
|
-| `/prod-api/service-vpp/alarm/rule` | `rule_engine`、`rule_engine_device`、`rule_engine_condition`、`rule_engine_cron` | usky `rule_*` |
|
|
|
-| `/prod-api/service-vpp/alarm` | `base_alarm`、`base_alarm_type` | usky `base_*` |
|
|
|
-| `/prod-api/service-vpp/alarm/notice` | `base_alarm_notice`、`base_alarm_notice_result` | usky `base_*` |
|
|
|
-| `/prod-api/service-vpp/device/{id}/control` | `dmp_device_command`、`vpp_device_control_log` | usky `dmp_*` + `vpp_*` |
|
|
|
-| `/prod-api/service-vpp/archive` | `vpp_file_archive` | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/resource` | `vpp_resource_point`、`vpp_device`、`vpp_site` | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/capability-eval` | `vpp_site`、`vpp_resource_point`、`vpp_device`、`vpp_dr_participation`、`vpp_dr_event`、`vpp_dr_evaluation` + TDengine `device_metrics` | VPP 专属 + 时序库 |
|
|
|
-| `/prod-api/service-vpp/customer` 等核心业务 | `vpp_customer`、`vpp_contract`、`vpp_resource_point` 等 | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/settlement` | `vpp_energy_reading_monthly`、`vpp_settlement_bill`、`vpp_payment_record` | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/report` | `vpp_report_task`、`vpp_report_record`、`vpp_report_data` | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/dr` | `vpp_dr_event`、`vpp_dr_invitation`、`vpp_dr_participation`、`vpp_dr_strategy`、`vpp_dr_execution`、`vpp_dr_evaluation` | VPP 专属 |
|
|
|
-| `/prod-api/service-vpp/un` | 调用 UN，落库同 DR + `vpp_registration` | VPP 专属 |
|
|
|
-| 运管平台 DN 被动路径 | `vpp_dr_event`、`vpp_dr_participation`、`vpp_registration` | VPP 专属 |
|
|
|
-| 运管平台 UN 主动客户端 | `vpp_registration`、`vpp_report_log`（报告日志待完善） | VPP 专属 |
|
|
|
-| 监控/统计时序数据 | TDengine `device_metrics` | 时序库 |
|
|
|
-
|
|
|
-### 5.5 参考文档
|
|
|
-
|
|
|
-1. 《API设计文档0304.md》（通用规范与路径格式）
|
|
|
-2. 《虚拟电厂平台详细设计文档 V1.0》
|
|
|
-3. 《虚拟电厂平台数据库设计文档 V1.0》
|
|
|
-4. 《虚拟电厂接口联调须知》（2025-12-11）
|
|
|
-5. 《虚拟电厂运管管理平台-虚拟电厂接口联调 JSON 报文实例》（2025-11-27）
|
|
|
-6. DLT 1867—2024《电力需求响应信息交互规范》
|
|
|
-
|
|
|
-### 5.6 UN 联调 JSON 样例
|
|
|
-
|
|
|
-工程内置样例（与联调文档 20251127 对齐），路径：
|
|
|
-
|
|
|
-`service-vpp/service-vpp-biz/src/main/resources/un-samples/`
|
|
|
-
|
|
|
-| 文件名 | root | 用途 |
|
|
|
-|--------|------|------|
|
|
|
-| poll-request.json | Poll | DN 主动 Poll |
|
|
|
-| distribute-event-invitation.json | DistributeEventRequest | 邀约入库测试 |
|
|
|
-| create-opt-request.json | CreateOptRequest | 参与申报 |
|
|
|
-| create-cq-request.json | CreateCqRequest | 分拆出清 |
|
|
|
-| create-event-response.json | CreateEventResponse | 出清公示确认 |
|
|
|
-
|
|
|
-**本地被动接口测试示例**：
|
|
|
-
|
|
|
-```http
|
|
|
-POST http://localhost:9906/DistributeEventRequest
|
|
|
-Content-Type: application/json
|
|
|
-
|
|
|
-（Body 使用 distribute-event-invitation.json 内容）
|
|
|
-```
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-**文档结束**
|
