Close the fleet gap on the Data Quality dashboard, and record why the reports are unbounded

README.md

@@ -209,6 +209,38 @@ produces a report that runs cleanly and reports the wrong number.
 **Fleet fuel comes from the energy use record.** `VehicleAssetEmssnSrc` has no fuel field —
 fuel, consumption and distance all live on `VehicleAssetEnrgyUse`.
 
+## Scope: the reports read the whole object, deliberately
+
+Fifteen of the 21 reports carry no filter, and all 21 leave the standard date filter
+unbounded. That is a decision, not an oversight, and it is worth understanding before you
+deploy into an org with years of history.
+
+**Why unbounded.** The date column available on these objects is `CreatedDate` — when
+somebody typed the record in. The business axis is `ReportingYear`, and the two do not
+agree: a footprint *for* 2024 is routinely entered in 2026, during the disclosure cycle.
+Bounding on `CreatedDate` would therefore drop records that belong in the answer. It would
+make the reports faster and wrong, which is the worse of the two failures for anything
+feeding a disclosure.
+
+**What it costs.** Each of these reports reads every record in scope on every run. On a
+dev org or a first year of data that is invisible. On an org with several years of
+footprint and energy-use records it is the first thing that will get slow, and the
+dashboard-fed reports pay it on every refresh.
+
+**What to do about it, when you get there.** Add a `ReportingYear` filter — it is on every
+report type here, and it is the axis the reports already group by. Which years to keep is
+a question about your disclosure obligations rather than about Salesforce, which is why
+this repository does not choose for you.
+
+Two related shapes, also deliberate:
+
+- **The six tabular reports have no row limit.** They are worklists and lookup lists —
+  *Footprint Data Entry*, *Asset Names and Locations* — meant to be worked all the way
+  through. A row limit on a worklist hides the rows somebody still has to fill in.
+- **The summary reports show details.** The same reports are read two ways: as a chart on a
+  dashboard, and as a list of the specific assets to go and fix. Turning details off would
+  make the chart marginally cheaper and the worklist useless.
+
 ## Also in this repo
 
 - [`sample-data/`](sample-data/) — six UTF-8 CSVs with deliberate gaps and orphans, so the

docs/building-your-own.md

@@ -174,3 +174,55 @@ that pattern. The lesson is the same one as the report type joins: the platform'
 objects use plain API names in places where its older objects use legacy keys, and only a
 deploy tells you which you've got.
 
+
+## Retrieving overwrites what the source deliberately leaves out
+
+`sf project retrieve start` does not give you back what you deployed. It gives you the
+org's rendering of it, and for dashboards that includes two elements this package
+deliberately does not carry:
+
+```xml
+<owner>someone@example.com</owner>
+<runningUser>someone@example.com</runningUser>
+```
+
+Salesforce stamps both on every dashboard, whatever the source said, and it does so even
+for a `LoggedInUser` dashboard where the running user is not used to decide what anyone
+sees. Commit them and you have broken the package for everybody else: that username does
+not exist in their org, so the deploy fails on a user it cannot resolve. You have also put
+your own email address into a public repository, twice per dashboard.
+
+The committed dashboards here carry `<dashboardType>LoggedInUser</dashboardType>` and no
+owner or running user. That omission is the portable form, and it is load-bearing.
+
+**So: never commit a dashboard retrieve without checking.**
+
+```bash
+sf project retrieve start --manifest manifest/package.xml --target-org <alias>
+grep -rn "owner\|runningUser" force-app/main/default/dashboards/
+```
+
+Anything printed has to come out before you commit. If the rest of the retrieve is
+cosmetic — and it usually is — the honest move is to throw the whole thing away and keep
+the hand-authored source:
+
+```bash
+git checkout -- force-app
+```
+
+### What else comes back, and why none of it is worth keeping
+
+The same round trip adds a few dozen lines of defaults across the reports:
+`<params><name>co</name><value>1</value></params>`, `<showGrandTotal>`, `<showSubTotals>`.
+They change nothing — a deploy from the source without them succeeds — and they make a
+report definition longer without making its intent clearer.
+
+The dashboards also come back with two properties *rewritten* rather than added:
+`<expandOthers>` flips to `false` and `<showTotal>` is dropped altogether. Neither applies
+to a Bar component; Salesforce is normalising settings that were never doing anything.
+That is worth knowing when you write a new component — those two do nothing on a bar chart
+— but it is not worth taking a two-hundred-line reformat to find out.
+
+The general rule, and it is the same one as everywhere else in this document: a deploy
+tells you whether the source is *sufficient*. A retrieve tells you what the org chose to
+store, which is a different question, and a noisier answer.

force-app/main/default/dashboards/NZC_Dashboards/NZC_Data_Quality.dashboard-meta.xml

@@ -128,6 +128,44 @@
             <title>Orphaned Energy Uses by Fuel</title>
             <useReportChart>false</useReportChart>
         </components>
+        <components>
+            <autoselectColumnsFromReport>true</autoselectColumnsFromReport>
+            <chartAxisRange>Auto</chartAxisRange>
+            <componentType>Bar</componentType>
+            <displayUnits>Auto</displayUnits>
+            <drillEnabled>false</drillEnabled>
+            <drillToDetailEnabled>false</drillToDetailEnabled>
+            <enableHover>true</enableHover>
+            <expandOthers>true</expandOthers>
+            <header>Orphans</header>
+            <legendPosition>Bottom</legendPosition>
+            <report>NZC_Reports/Orphaned_Fleet_Footprints</report>
+            <showPercentage>false</showPercentage>
+            <showTotal>false</showTotal>
+            <showValues>true</showValues>
+            <sortBy>RowValueDescending</sortBy>
+            <title>Orphaned Fleet Footprints</title>
+            <useReportChart>false</useReportChart>
+        </components>
+        <components>
+            <autoselectColumnsFromReport>true</autoselectColumnsFromReport>
+            <chartAxisRange>Auto</chartAxisRange>
+            <componentType>Bar</componentType>
+            <displayUnits>Auto</displayUnits>
+            <drillEnabled>false</drillEnabled>
+            <drillToDetailEnabled>false</drillToDetailEnabled>
+            <enableHover>true</enableHover>
+            <expandOthers>true</expandOthers>
+            <header>Orphans</header>
+            <legendPosition>Bottom</legendPosition>
+            <report>NZC_Reports/Orphaned_Vehicle_Energy_Uses</report>
+            <showPercentage>false</showPercentage>
+            <showTotal>false</showTotal>
+            <showValues>true</showValues>
+            <sortBy>RowValueDescending</sortBy>
+            <title>Orphaned Vehicle Energy Uses</title>
+            <useReportChart>false</useReportChart>
+        </components>
     </rightSection>
     <textColor>#000000</textColor>
     <title>NZC Data Quality</title>