Give every API field one name across JSON and CSV

[misaugstad]

resolves #4320

#4320 was that overallStats derived its CSV keys from Title-Case display labels while its JSON
used explicit snake_case, so the two drifted. Fixing only those three field names would have left
the mechanism that produced the drift in place, and the same mechanism had already produced drift
on nearly every other endpoint. So this replaces the mechanism.

What changed

Each model now declares one ordered field list (app/models/api/ApiFields.scala), and its JSON
keys, CSV header, and CSV cells are all derived from it. A field cannot be named one thing in one
format and something else in the other, because there is only one place to name it.

The two endpoints whose response is a single object rather than a list of records (overallStats,
aggregateStats) build their vertical CSV by flattening their own JSON, keying each row by its
dotted path — labels.CurbRamp.count in the CSV is exactly what you would read as
labels.CurbRamp.count from the JSON.

Net 830 insertions, 1124 deletions: each field used to be written three times (JSON key, header
entry, row cell), and in one case four.

Bugs this surfaced

• outputCSV never separated the header from the first row. Every streaming header string had
  to smuggle in a trailing \n to compensate. userStats used that same string with println,
  so its CSV has been emitting a blank line after the header.
• aggregateStatsByDay wrote its field order a fourth time, as an interpolated string in
  StatsApiController.
• labels.count, labels.count_with_severity and total_validations serialized as floats
  (183427.0) because they were built with .toDouble; the docs promised integers.
• The labelClusters CSV docs sample was missing the intersection_id column.

Breaking changes (v3 preview surface, plus /adminapi cvMetadata)

Field names:

Endpoint	Was	Now
accessScore*	n_curb_ramp, score_curb_ramp, n_curb_ramp_sev1, tag_adj_curb_ramp	cluster_counts.CurbRamp, sub_scores.CurbRamp, severity_counts.CurbRamp.1, tag_adjustments.CurbRamp
accessScoreRegions	avg_n_curb_ramp	avg_cluster_counts.CurbRamp
userStats	53 Title-Case columns	snake_case, with stats_by_label_type.CurbRamp.labels
userStats JSON	curb_ramp, marked_crosswalk, cant_see_sidewalk, pedestrian_signal	CurbRamp, Crosswalk, Occlusion, Signal
/adminapi/labels/cvMetadata	Label ID,Panorama ID,…	label_id,pano_id,…
overallStats	average_label_timestamp, km_explored_without_overlap, total_label_count, curb_ramp_severity_sd	labels.avg_label_timestamp, km_explored_no_overlap, labels.count, labels.CurbRamp.severity_stddev
overallStats ai_stats	ai_yes_human_concurs	ai_yes_maj_vote_concurs
aggregateStats	number_of_cities, number_of_countries, number_of_languages	num_cities, num_countries, num_languages
aggregateStats	curb_ramp_labels, no_sidewalk_labels_validated_disagree	by_label_type.CurbRamp.labels, by_label_type.NoSidewalk.labels_validated_disagree

userStats keys stats_by_label_type by the canonical names from /v3/api/labelTypes — it was the
one endpoint whose label types couldn't be joined against the others. The ai_stats leaves say
maj_vote because the key one level up already names whose majority vote it is, and human there
is a specific sibling (every non-AI validator), so admin_majority_vote.ai_yes_human_concurs read
as a contradiction.

Values:

• A missing value is an empty cell, not NA (this matched most v3 models already).
• rawLabels CSV time_created becomes an ISO-8601 string. Its JSON already used one; only the CSV cell was epoch
  millis, so unifying the two picks the JSON's format. Anyone parsing that column as a number will need to change.
  (The docs claimed epoch millis for both formats, which was already wrong; fixed here.)
• aggregateStats no longer carries "status": "OK". It sat inside the stats object rather than wrapping a named
  data key, so flattening put a protocol field at the top of a metric,value table. Its one reader checked it
  immediately before validating that six named fields are numbers, which is the stronger check.
• Optional fields are written as explicit nulls rather than dropped, so a response's key set doesn't
  vary with the data — which is also what keeps it aligned with the CSV's fixed columns.
• String arrays render as real JSON (["narrow","steep"], not [narrow,steep], which no parser
  could read).
• overallStats CSV gains the metric,value header row it was missing; aggregateStats had one.

sidewalk-panorama-tools reads /adminapi/labels/cvMetadata, so it has a heads-up at
ProjectSidewalk/sidewalk-panorama-tools#123. Its CSV reader already expects snake_case, so this
moves toward what it wants; its JSON path is unaffected.

Not included

GeoPackage still builds these column names its own way (n_curb_ramp, and street_id where JSON
and CSV say street_edge_id). That needs its own change — dotted names may not be usable as SQLite
column names, and its attribute writes are positionally coupled to the type spec. Filed as #5273.

Testing

Full backend suite (1424), JS suite (1789), HTMLHint over all api-docs views, locale and asset-path
checks, scalafmt, and a warning-clean compile under -Xfatal-warnings.

One unrelated failure on this branch and on the base: RouteBuilderControllerSpec's soft-deleted
route case, which is the known dev-DB route-accumulation flake (790 routes accumulated locally).
This branch touches no route-builder code.

The api-docs CSV samples were regenerated from the real csvHeader values rather than written by
hand.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LYLhKjbUkFnnpiPrCdHvE9