docs(kpi): trend charts state per-bucket-total semantics for rate metrics (plan R2-04 T7)

src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Shared/KpiTrendChart.razor.cs

@@ -51,6 +51,14 @@ public partial class KpiTrendChart
     /// The series to plot, assumed ordered ascending by
     /// <see cref="KpiSeriesPoint.BucketStartUtc"/>. <c>null</c> or empty renders
     /// the unavailable placeholder rather than an empty chart.
+    /// <para>
+    /// The per-point value's meaning depends on the metric's
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiMetricAggregationCatalog"/>
+    /// classification: a Rate-classified series carries <b>per-bucket totals</b> (the
+    /// bucketer sums each bucket's deltas), while a Gauge series carries
+    /// last-value-per-bucket readings. The chart is agnostic to which — it plots the
+    /// supplied values verbatim (arch-review 04 round 2, R3).
+    /// </para>
     /// </summary>
     [Parameter] public IReadOnlyList<KpiSeriesPoint>? Points { get; set; }
 
@@ -58,7 +66,10 @@ public partial class KpiTrendChart
     /// <c>data-test</c> slug. Required-ish; defaults to "Trend" if blank.</summary>
     [Parameter] public string Title { get; set; } = "Trend";
 
-    /// <summary>Optional unit suffix appended to value labels (e.g. "s").</summary>
+    /// <summary>Optional unit suffix appended to value labels (e.g. "s"). For a
+    /// Rate-classified metric the supplied text must state the per-bucket-total
+    /// semantics (e.g. "delivered/bucket"), not a per-minute/per-interval reading,
+    /// so the label matches the summed values in <see cref="Points"/> (R3).</summary>
     [Parameter] public string? Unit { get; set; }
 
     /// <summary>