- name
- energy-app-middle-integration
- description
- Use when integrating with the energy-app-middle BFF service - covers REST API endpoints, gRPC client setup, authentication headers, multi-tenancy, and downstream service dependencies for the changyuanfeilun energy platform.
energy-app-middle Integration Guide
Overview
energy-app-middle is a BFF + API aggregation layer for the distributed energy management platform. It exposes REST APIs to three client types (Owner / Provider / Platform) and orchestrates calls to IoT Core, IoT PaaS, IAM, algorithm services, and time-series databases.
Quick Reference
| Client Type | Base Path | Audience |
|---|
| Owner API | /api/owner/* | Energy asset owners |
| Provider API | /api/provider/* | Service providers |
| Platform API | /platform-api/* | Platform admins |
| gRPC Server | port 9090 | Internal services |
| Management | port 38081 | Actuator / metrics |
1. Key REST Endpoints
Owner API (/api/owner/)
| Method | Path | Description |
|---|
| GET | /api/owner/der/control_record/{resourceId} | DER control records (paginated) |
| GET/POST | /api/owner/der/control_automation/{resourceId} | DER automation settings |
| POST | /api/owner/der/control_automation/{resourceId}/switch | Toggle automation on/off |
| POST | /api/owner/der/control_automation/{resourceId}/device | Device automation properties |
| GET/POST | /api/owner/project/price/{projectId} | Electricity pricing |
| GET | /api/owner/project/statistics/* | Project electricity statistics |
| GET | /api/owner/project/trend/* | Project trend charts |
| GET/POST | /api/owner/der/plan_prompt/* | DER plan prompts |
Provider API (/api/provider/)
| Method | Path | Description |
|---|
| GET | /api/provider/der/{resourceId}/billing_type | Billing type (TOU/Market) |
| GET/POST | /api/provider/der/{resourceId}/market_price_config | Market price configs |
Platform API (/platform-api/)
| Method | Path | Description |
|---|
| GET | /platform-api/market/config?marketCode={code} | Market metric configurations |
| POST | /platform-api/data | Query market metric data |
2. Authentication & Headers
Token validation is delegated to IAM via gRPC. All requests must carry:
| Header | Description |
|---|
X-ACCESS-TOKEN | JWT token (validated by IAM) |
X-App | App code |
X-Tenant | Tenant code |
X-UID | User UID (set by gateway) |
X-PUID | Parent UID (for sub-accounts) |
All data is tenant-scoped — tenantCode is extracted from request context and applied to every query.
3. gRPC Integration (Internal Services)
Dependency
<dependency>
<groupId>com.feilun</groupId>
<artifactId>energy-app-middle-grpc-interface</artifactId>
</dependency>
Client Configuration
grpc:
client:
energy-app-middle:
address: dns:///energy-app-middle.${K8S_POD_NS}.svc.cluster.local:9090
negotiationType: PLAINTEXT
enableKeepAlive: true
4. Downstream Dependencies
| Service | Protocol | Purpose |
|---|
iam | gRPC | Token validation, authorization |
iot-core | gRPC | Device management & queries |
iot-paas | gRPC | Device grouping, batch tasks |
basic | gRPC | Infrastructure services |
algorithm-der-power-forecast | HTTP | PV power forecasting |
algorithm-dispatch | HTTP | DR dispatch planning |
algorithm-bess-opt | HTTP | Battery storage optimization |
algorithm-bid | HTTP | VPP spot bidding |
| MySQL | JDBC | Transactional data |
| TDEngine | JDBC | Time-series device metrics |
| RisingWave | JDBC | Real-time metric aggregation |
| Apache Pulsar | Messaging | Device events, market data |
| PowerJob | HTTP | Distributed job scheduling |
5. Key DTOs
DerAutomationSettingsReq:
dailyMaxImport/Export, dailyMinimalImport/Export (Double)
maximumExportPower/ImportPower (Double)
opportunityImportPrice/ExportPrice (Double)
DerControlRecordRes:
resourceId, controlCode, status
startTime, endTime, controlDate
controlCurve (JSON array of power points)
MarketMetricDataReq:
marketCode (AEMO_REGIONS: NSW1/QLD1/VIC1/SA1/TAS1)
metrics (List<String>), targetId, startTime, endTime
6. Environment Variables
| Variable | Purpose |
|---|
K8S_POD_NS | Kubernetes namespace (used in gRPC addresses) |
BIZ_NAME | Business code (energy-app-middle) |
SPRING_PROFILES_ACTIVE | Profile (localdev / prod) |
k8s.all.mysql.host/port | MySQL connection |
k8s.eam.mysql.database | MySQL database name |
k8s.all.tdengine.host | TDEngine host |
k8s.all.risingwave.host/port | RisingWave connection |
k8s.all.pulsar.service-url | Pulsar broker URL |
k8s.all.powerjob.worker.server-address | PowerJob server |
7. Common Mistakes
| Mistake | Fix |
|---|
Missing X-Tenant header | Required for all requests — tenant isolation is enforced |
Calling gRPC without X-UID/X-PUID | IoT PaaS interceptor requires both headers |
| Querying metrics without time range | TDEngine/RisingWave queries require startTime + endTime |
Wrong marketCode | AEMO regions: NSW1, QLD1, VIC1, SA1, TAS1 only |
