Optimizer: expose forecasted highest/lowest battery SOC

[andig]

Summary

Extracts the predicted highest and lowest battery SOC from the optimizer forecast so the energy-flow widget can show the next peak/trough even when the battery is not forecasted to reach a full/empty boundary.

Details

• Replaces BatteryForecast.Full / Empty timestamps with Highest / Lowest points carrying SOC %, time and a Limit flag.
• Limit is set when the aggregated SOC reaches the configured SMax (full) or SMin (empty) exactly.
• Aggregation considers home batteries only (SCapacity > 0); vehicles are ignored.
• Removes the now-redundant batteryForecastFullAndEmptySlots helper.
• Frontend renders the lowest point in the discharge entry and the highest point in the charge entry. Format is {soc} {time} for non-limit points and full/empty {time} when the boundary is reached.
• New i18n key main.energyflow.batteryForecastSoc for the percentage format.

Fixes #29004

Test plan

• go test ./core/...
• npm test (vitest)
• vue-tsc --noEmit
• Manual UI check via Storybook (BatteryForecastSocExtremes story)

[sourcery-ai]

Hey - I've found 3 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="core/site_optimizer.go" line_range="312-316" />
<code_context>
+		return &types.BatteryForecastPoint{Soc: p.soc, Time: ts, Limit: p.limit}
 	}

+	res := types.BatteryForecast{
+		Highest: point(high),
+		Lowest:  point(low),
+	}
+	if res.Highest == nil && res.Lowest == nil {
+		return nil
+	}
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Avoid calling time.Now() multiple times when computing forecast timestamps to prevent subtle boundary inconsistencies.

In `addBatteryForecastTotals`, `now` is computed once, but `point` still calls `time.Now()` via `ts.After(time.Now())`. This can make borderline slots non-deterministic due to tiny differences between the two timestamps. Capture a single `now := time.Now()` (or `cutoff := time.Now()`) once and reuse it for both rounding and the `After` check to ensure consistent boundary behavior.

Suggested implementation:

```golang
		ts := now.Add(time.Duration(p.slot) * tariff.SlotDuration)
		if !ts.After(now) {
			return nil
		}
		return &types.BatteryForecastPoint{Soc: p.soc, Time: ts, Limit: p.limit}
	}

```

This change assumes that a single `now := time.Now()` is already computed earlier in `addBatteryForecastTotals` and reused for the slot rounding. If that is not yet the case, introduce a `now := time.Now()` (or `cutoff := time.Now()`) once at the start of the function and use that same variable both where `now` is used for computing `ts` and in this `After` check.
</issue_to_address>

### Comment 2
<location path="assets/js/components/Energyflow/Energyflow.vue" line_range="690-693" />
<code_context>
-		fmtForecast(
-			forecast: { full?: string | null; empty?: string | null } | undefined,
-			full: boolean
+		fmtForecastPoint(
+			point: { soc: number; time: string; limit?: boolean } | undefined,
+			high: boolean
 		): string | undefined {
-			const isoString = full ? forecast?.full : forecast?.empty;
-			if (!isoString) return undefined;
</code_context>
<issue_to_address>
**suggestion:** Reuse the shared BatteryForecastPoint type instead of an ad-hoc inline shape for better type safety.

The `fmtForecastPoint` param is currently typed as `{ soc: number; time: string; limit?: boolean } | undefined`. Since `BatteryForecastPoint` is already defined in `assets/js/types/evcc.ts`, update this signature to use `BatteryForecastPoint | undefined` to avoid duplicating the shape and reduce drift if the shared type changes (fields or nullability).

Suggested implementation:

```
import type { BatteryForecastPoint } from "@/types/evcc";

export default {

```

```
		fmtForecastPoint(
			point: BatteryForecastPoint | undefined,
			high: boolean
		): string | undefined {

```

1. If your project does not use the `@` alias for `assets/js`, adjust the import path to match existing imports in this file, e.g.:
   - `import type { BatteryForecastPoint } from "../types/evcc";` or
   - `import type { BatteryForecastPoint } from "../../types/evcc";`
2. Ensure `BatteryForecastPoint` in `assets/js/types/evcc.ts` is exported as a TypeScript type/interface and matches the `{ soc: number; time: string; limit?: boolean }` shape currently used by `fmtForecastPoint`.
</issue_to_address>

### Comment 3
<location path="core/site_optimizer.go" line_range="328" />
<code_context>
+	limit bool    // true when SMax (highest) or SMin (lowest) boundary reached
+}
+
+// batteryForecastSocExtremes returns the highest and lowest aggregate SOC
+// points across home batteries (SCapacity > 0) over the forecast horizon.
+// The Limit flag indicates whether the SOC reached the configured SMax (for
</code_context>
<issue_to_address>
**issue (complexity):** Consider splitting the SOC aggregation and extreme-selection logic into smaller helpers and making the limit-selection rules explicit to simplify understanding and testing.

You can keep the new behavior but reduce complexity by separating aggregation from selection and by making the “limit” semantics explicit.

### 1. Split `batteryForecastSocExtremes` responsibilities

Right now it:
- aggregates capacities,
- builds the aggregate SOC over time,
- decides full/empty with tolerance, and
- tracks high/low with subtle limit semantics in a single loop.

You can make this easier to follow and test by extracting the aggregation and selection into helpers:

```go
func aggregateSocSeries(req []optimizer.BatteryConfig, resp []optimizer.BatteryResult) (
	socSeries []float64, fullReached, emptyReached []bool,
) {
	var totalCapacity, totalSMax, totalSMin float32
	for _, b := range req {
		if b.SCapacity > 0 {
			totalCapacity += b.SCapacity
			totalSMax += b.SMax
			totalSMin += b.SMin
		}
	}
	if totalCapacity == 0 || len(resp) == 0 {
		return nil, nil, nil
	}

	tolerance := 0.01 * totalCapacity
	slotCount := len(resp[0].StateOfCharge)

	socSeries = make([]float64, slotCount)
	fullReached = make([]bool, slotCount)
	emptyReached = make([]bool, slotCount)

	for i := 0; i < slotCount; i++ {
		var sum float32
		for batIdx := range req {
			if req[batIdx].SCapacity > 0 {
				sum += resp[batIdx].StateOfCharge[i]
			}
		}
		socSeries[i] = float64(sum/totalCapacity) * 100
		fullReached[i] = totalSMax > 0 && sum >= totalSMax-tolerance
		emptyReached[i] = sum <= totalSMin+tolerance
	}

	return socSeries, fullReached, emptyReached
}

func selectExtremes(socSeries []float64, fullReached, emptyReached []bool) (
	high, low *batteryForecastSlot,
) {
	for i, soc := range socSeries {
		fr, er := fullReached[i], emptyReached[i]

		// first slot at SMax wins for highest
		if high == nil || (!high.limit && (fr || soc > high.soc)) {
			high = &batteryForecastSlot{slot: i, soc: soc, limit: fr}
		}
		// first slot at SMin wins for lowest
		if low == nil || (!low.limit && (er || soc < low.soc)) {
			low = &batteryForecastSlot{slot: i, soc: soc, limit: er}
		}
	}
	return
}

func batteryForecastSocExtremes(req []optimizer.BatteryConfig, resp []optimizer.BatteryResult) (high, low *batteryForecastSlot) {
	socSeries, fullReached, emptyReached := aggregateSocSeries(req, resp)
	if socSeries == nil {
		return nil, nil
	}
	return selectExtremes(socSeries, fullReached, emptyReached)
}
```

This preserves the behavior (including the 1% tolerance and “first at limit wins”) but separates:
- “what is the SOC/time series and limit flags?” from
- “given a series and flags, how do we pick high/low?”.

Both parts can then be unit-tested independently.

### 2. Make the selection logic self-documenting

You can further clarify the domain rules by centralizing the “first boundary wins” policy in small helpers, reducing mental parsing of `||`/`&&`:

```go
func betterHigh(current *batteryForecastSlot, soc float64, reachedLimit bool) bool {
	if current == nil {
		return true
	}
	if current.limit {
		// once at limit, never override
		return false
	}
	// prefer boundary over non-boundary, otherwise higher SOC
	if reachedLimit && !current.limit {
		return true
	}
	return soc > current.soc
}

func betterLow(current *batteryForecastSlot, soc float64, reachedLimit bool) bool {
	if current == nil {
		return true
	}
	if current.limit {
		return false
	}
	if reachedLimit && !current.limit {
		return true
	}
	return soc < current.soc
}

// then in selectExtremes:
if betterHigh(high, soc, fr) {
	high = &batteryForecastSlot{slot: i, soc: soc, limit: fr}
}
if betterLow(low, soc, er) {
	low = &batteryForecastSlot{slot: i, soc: soc, limit: er}
}
```

This keeps the same semantics but makes the intent (“once at limit, don’t override; prefer limit over non-limit; otherwise use max/min”) explicit and easy to review.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[andig]

@copilot fix #29564 (comment)

[naltatis]

Das funktioniert so noch nicht. Die 39% wirken wie eine Random-Information. Da fehlt noch Kontext.

Wir zeigen hier ja das nächste erwartete Maximum an. Ich probier mal in folgende Richtung:

Vorhersage: Voll ab Do. 12:44
Vorhersage: Leer ab Do. 21:30
Nächstes Hoch: Do. 13:00 (48%)
Nächstes Tief: Do. 5:00 (12%)

[naltatis]

Now showing as "next low" and "next high" if the extremes are not reached.

[andig]

Lets check is this is really next low or forecasted low, i.e. the absolute low even after next? Which one would be prefer- I'd say the latter?

[naltatis]

Which one would be prefer- I'd say the latter?

I'd say "the next" since our forecast horizon is subject to change and if we are picking longer horizons this info gets less meaningful/actionable for the users. The next one is clear and in line with our solar forecast communication. We could evolve this to showing "the next peaks" later.