Skip to content

docs(seed): clarify passenger-km and round-trip in business travel transport - #605

Merged
mrivas00 merged 2 commits into
mainfrom
docs/mati/business-travel-transport-explanation
Aug 25, 2026
Merged

docs(seed): clarify passenger-km and round-trip in business travel transport#605
mrivas00 merged 2 commits into
mainfrom
docs/mati/business-travel-transport-explanation

Conversation

@mrivas00

@mrivas00 mrivas00 commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • A user reported that the help panel of Viajes de negocios — Traslado left two things unanswered: whether the quantity is one person's kilometres or people × kilometres, and whether a trip counts one leg or both. Neither question was addressed anywhere on the page.
  • The answer is not uniform, which is why the page could not be fixed with a one-liner: the DEFRA 2025 factors seeded for this subcategory use two different bases — air, bus and rail are per passenger-km, while car and taxi are per vehicle-km. The page now states that distinction up front, says both legs of a round trip count, and gives the formula that builds the quantity (km per leg × legs × people × trips, dropping the people term for car/taxi).
  • While verifying the numbers against tools/seed/src/data/base/methodologies.json, the page turned out to contradict the seeded data in several places, so it is now aligned with what the calculator actually offers.

Linked issues

None — reported as direct user feedback.

Type of change

  • feat — new feature
  • fix — bug fix
  • refactor — internal change with no behavioural impact
  • docs — documentation only
  • chore — repository or tooling change
  • infra — infrastructure-as-code change
  • security — security-relevant change (also fill in the security
    checklist below)
  • breaking — backward-incompatible change for country deployers
    (must include a deprecation path or migration note)

What was contradicting the seed

Page said (before) Seed says
Factor table with invented values (0,25 / 0,15 / 0,03 / 0,18 kg CO₂e/km) The 10 real Transporte options with their DEFRA 2025 values (0,1257 / 0,117 / 0,1091 / 0,1038 / 0,0354 / 0,148 / 0,173 …)
Apply a cabin-class multiplier by hand (×1,5 / ×2-3 / ×3-4) Class is part of the option itself (… Economy / … Business), so no manual multiplier — Business is already ~1,5× (short haul) to ~2,9× (medium/long haul)
Flight bands by distance (<500 km / 500-3.700 / >3.700) Bands by duration (Short haul (<3hrs) / Medium haul (3-6hrs) / Long haul (>6hrs))
Unidad: km, moneda local allowedMeasurementUnitsAbbreviations: m, km, mi — no currency unit exists
"Si vas con colegas en el mismo Uber o taxi, divide los km entre los pasajeros" Taxi factor is per vehicle-km, so dividing leads to under-reporting; the vehicle's kilometres are counted once

Country-agnosticism checklist

  • No country-specific logic was hard-coded in the codebase.
  • Country variation is expressed through configuration, seed data
    or system parameters.
  • The change is backward-compatible with existing country
    deployments, or a deprecation path and migration note are
    documented in this PR.

DPG checklist

  • Documentation under docs/ was updated where relevant.
  • No new platform-specific dependency was added without an
    open-source alternative path documented.
  • No new PII handling pattern was introduced without review
    against docs/security/sensitive-data.md and PRIVACY.md.
  • If this PR adds user-facing strings, they are in Spanish (the
    project's user-facing language).

Security checklist

  • N/A — this PR does not touch security-sensitive code.

Mandatory local checks

pnpm format:check   # pass
pnpm lint           # pass (13/13 tasks)
pnpm type-check     # pass (13/13 tasks)
pnpm test           # not run — see reviewer notes
  • All of the above pass locally on my machine.

Screenshots / evidence

The rewritten worked example, recomputed against the seeded factors:

Transporte Quantity Factor Emissions
Avión Long haul Economy (3 people, round trip, 9.500 km/leg) 57.000 km 0,1091 6.219 kg CO₂e
Avión Medium haul Economy (4 trips, 1 person, 2.100 km/leg) 16.800 km 0,1170 1.966 kg CO₂e
Avión Short haul Economy (3 trips, 2 people, 620 km/leg) 7.440 km 0,1257 935 kg CO₂e
Bus (5 people, round trip, 225 km/leg) 2.250 km 0,1038 234 kg CO₂e
Taxi (vehicle kilometres, occupants not multiplied) 600 km 0,1480 89 kg CO₂e
Auto (vehicle kilometres, occupants not multiplied) 800 km 0,1730 138 kg CO₂e

Total ≈ 9.581 kg CO₂e (~9,6 t). The example closes by explaining the two effects that caused the original confusion: the international conference is 65% of the total because of passenger-km (3 people × 2 legs), not because its factor is high — it is in fact the lowest air factor — and shared taxis contribute little precisely because occupants are not multiplied.

Reviewer notes

  • The page is only reflected in the app after reseeding. It is loaded by tools/seed/src/scripts/seedExplanations.ts, so an existing deployment keeps serving the stored copy until explanations are seeded again.
  • pnpm test was not run: the diff is a single seed markdown file with no code path, and no test asserts on explanation content. Happy to run the suite if you would rather have it on the record.
  • Worth a second opinion on two judgement calls: the km-equivalence hint I added for choosing a flight band (short ≈ up to ~2.000 km, medium ≈ 2.000-5.000, long ≈ >5.000 — marked as orientative, since the seeded options are defined by duration), and the RFI note, which now says the platform applies the DEFRA 2025 factor as-is and that any radiative-forcing adjustment belongs in "Factor propio" rather than in the quantity.
  • The ferry bullet is kept in the coverage list even though no ferry option exists in the dimension, so the scope of the subcategory is not silently narrowed.
  • Two red checks are pre-existing and unrelated to this diff (a single markdown file): Audit and Trivy Image Scan (api) both fail on the same transitive dependency, deepmerge-ts 7.1.5 pulled in by @prisma/client → prisma → @prisma/config (CVE-2026-40345 / GHSA-ggr8-5vv4-36mx). Reproduced locally on this branch, and already tracked in fix(deps): force deepmerge-ts to 8.x to patch CVE-2026-40345 #602. Everything else passes, including Seed Unit Tests, Format Check, Lint, Type Check and the full test matrix.

@mrivas00 mrivas00 added priority: high High priority type: docs documentation only area: docs docs/ and root docs labels Aug 19, 2026
@mrivas00
mrivas00 force-pushed the docs/mati/business-travel-transport-explanation branch 3 times, most recently from 16bb1f8 to c0857ea Compare August 25, 2026 19:45
…ansport

User feedback on the business travel — transport subcategory: the help
panel did not say whether to enter one person's kilometres or people ×
kilometres, nor whether a trip counts one leg or both.

The DEFRA 2025 factors seeded for this subcategory use two different
bases: air, bus and rail are per passenger-km, while car and taxi are
per vehicle-km. Make that distinction explicit, state that both legs of
a round trip count, and add the formula that builds the quantity
(km per leg × legs × people × trips).

Also align the page with the seeded data, which it contradicted:
- replace the invented factor table with the 10 real Transporte options
  and their DEFRA 2025 values
- drop the manual cabin-class multiplier (class is part of the option)
- use flight-duration bands (short/medium/long haul) instead of km bands
- remove "moneda local" as a unit (only m, km and mi are allowed)
- rework the worked example to show how each quantity is derived
- fix the rideshare note, which advised splitting vehicle kilometres
  between passengers and so led to under-reporting
…bases

The seed data commit rewrote the "Viajes de negocios - Traslado" markdown,
but a running deployment keeps serving the text it was first seeded with:
seed.ts aborts the whole run when the database already has data (the
country-count gate), so seedExplanations never re-inlines a markdown file
that changed after the initial seed.

Write the current file content onto the row so the (i) panel matches the
repository and a later reseed is a no-op.

Same shape as the guide updates in
20260825140000_add_machinery_catalog_and_otro_values: the row is matched
through the demo country's base methodology, so a country deployment that
maintains its own methodology decides for itself, and the write is guarded
by IS DISTINCT FROM, so re-running the migration touches zero rows. The
later timestamp is deliberate — that migration rewrites this same row with
the previous revision of the guide, so it has to run first.

Guide text only: no factor, captured inventory line or computed total is
touched.

Verified against the seeded local database inside a rolled-back
transaction, replaying both migrations in order: after 20260825140000 the
row still holds the previous revision, the first apply of this one reports
UPDATE 1 and the second UPDATE 0, and the stored guide is byte-identical
to the markdown file (md5 15ee0cb2).
@mrivas00
mrivas00 force-pushed the docs/mati/business-travel-transport-explanation branch from 0ab1511 to ee90dda Compare August 25, 2026 20:46
@mrivas00
mrivas00 merged commit 4a9fb6b into main Aug 25, 2026
24 checks passed
@mrivas00
mrivas00 deleted the docs/mati/business-travel-transport-explanation branch August 25, 2026 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs docs/ and root docs priority: high High priority type: docs documentation only

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants