Skill: effort02/energy-app-middle-integration (version 1.0.0)

--- 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 ```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 ``` 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 |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)