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 downst...

Security Scan

The SKILL.md content matches an internal integration guide, but it references many internal endpoints, environment variables, and auth headers while the skill manifest declares no required credentials or install steps — that mismatch is concerning and worth clarifying before installing.

Purpose & Capability

The name/description and the SKILL.md align: this is an integration guide for the energy-app-middle BFF and enumerates REST/gRPC endpoints, headers, DTOs and downstream services. However the manifest declares no required env vars or credentials while the documentation explicitly references many sensitive environment variables (K8S_POD_NS, DB/TDEngine/RisingWave hosts, Pulsar URL, PowerJob server, and JWT/X-ACCESS-TOKEN usage). The absence of declared requirements is an incoherence: either this is purely read-only documentation (fine) or it expects runtime access to infrastructure (not declared).

Instruction Scope

The SKILL.md is instruction-only and stays on-topic: it documents endpoints, headers to include, DTOs, and common mistakes. It does not instruct the agent to read local files, alter other skills, or send data to unexpected external endpoints. However it assumes the agent will have network access to internal cluster DNS names and that callers will present JWTs and tenant headers — i.e., it assumes access to sensitive runtime context (tokens, internal network).

Install Mechanism

There is no install spec and no code files; this is instruction-only. That minimizes install-time risk (nothing downloaded or written).

Credentials

The document references many environment variables, database and message-broker endpoints, and an authentication token header, yet the registry metadata declares no required env vars or primary credential. This is disproportionate / inconsistent: if the skill expects to be used against real services it should declare which credentials and env vars it needs. If it is only documentation, the references are informational — but an agent invoking this skill autonomously could be prompted to use/require secrets not declared here.

Persistence & Privilege

The skill is not force-installed (always:false), has no install steps, and does not request persistent system modifications. Autonomous invocation is allowed by default but is not combined with other privilege escalation indicators in the manifest.

What to consider before installing

This is mainly a documentation-only integration guide for an internal BFF — useful if you or your agent are operating inside the same cluster/network. Before installing: 1) Confirm the skill's source and maintainer (there's no homepage). 2) Ask the author to declare which environment variables/credentials (if any) are required — right now the SKILL.md references many sensitive endpoints but the manifest declares none. 3) Do not supply JWTs, DB credentials, or internal network access to the agent unless you trust the skill and run it in the appropriate internal environment. 4) If you expect the skill to be used only as read-only documentation, prefer to keep it as a manual reference rather than enabling autonomous invocation. 5) If you need to install it into a production-capable agent, require the author to provide provenance (repo/homepage), and to update the manifest to explicitly list required env vars and the exact scope of network access.

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