Energy App Middle Integration

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

xml

<dependency>
    <groupId>com.feilun</groupId>
    <artifactId>energy-app-middle-grpc-interface</artifactId>
</dependency>

Client Configuration

yaml

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

text

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