Travel traveller resolution: -1 / null sentinels — Implementation Plan¶
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Replace the __other_internal__ / __other_external__ string
sentinels for user_institutional_id with "-1" (Internal other) and JSON
null (External other), so every Professional Travel row resolves to a
Headcount name, "Internal other", or "External other" without ever
overwriting a source SCIPER that fails to resolve.
Architecture: No new column, no FK, no synthetic User rows —
user_institutional_id stays a free-text string inside DataEntry.data
(JSONB). Two constants (TRAVELER_OTHER_INTERNAL = "-1",
TRAVELER_OTHER_EXTERNAL = None/null) are defined once per language and
reused everywhere. The existing correlated-subquery resolution in
data_entry_repo.py needs no logic change — it already scopes correctly by
carbon_report_module_id and SQL's NULL = NULL → NULL already makes the
External sentinel safe. The work is: (1) point the ingestion provider and
the create/response DTOs at the new sentinels, (2) migrate the two legacy
string values in existing data, (3) fix two latent bugs in the
already-shipped frontend resolver where a loose == null check would
swallow the new null-as-External-other value into a blank dash.
Tech Stack: FastAPI, SQLModel/SQLAlchemy (async), Pydantic v2, Alembic,
pytest (uv run pytest); Vue 3 + Quasar 2, TypeScript, Playwright
(tests/unit/*.spec.ts run via playwright-ct.config.ts, no vitest).
Spec: 1153-traveler-sentinel-resolution-prd.md
Global Constraints¶
- No
traveller_typecolumn, no syntheticUserrows. (PRD §2, §11) - Never overwrite a source SCIPER that fails to resolve against
Headcount — an unmatched SCIPER (e.g.
"45005") stays"45005"forever; only the two known legacy literals (__other_internal__,__other_external__) are migrated. (PRD §1, §6) "-1"is the one reserved sentinel string. No other negative-looking value carries special meaning. (PRD §7)- External other is JSON
nullwith the key present, never an absent key. (PRD §2, decided in brainstorming 2026-08-14) - Headcount matching stays scoped to
carbon_report_module_id(unit + report year), stricter than the PRD's plainunit_id— do not loosen this. (PRD §3) - Traveler stays Create-only — do not add an update path for
user_institutional_idas part of this plan. (PRD §5, §11) - Backend tests:
cd backend && uv run pytest <path> -q. Frontend unit specs:cd frontend && rtk playwright test -c playwright-ct.config.ts <path>. Frontend type-check (unproxied, per house rule —rtk tscgreen does not guaranteevue-tscpasses):cd frontend && make type-check.
Task 1: Backend — ingestion provider sentinel constants¶
Files:
- Modify:
backend/app/services/data_ingestion/api_providers/professional_travel_api_provider.py:21-25 - Test:
backend/tests/unit/services/data_ingestion/test_professional_travel_api_provider.py
Interfaces:
-
Produces:
TRAVELER_OTHER_INTERNAL: str = "-1",TRAVELER_OTHER_EXTERNAL: None = None, both importable fromapp.services.data_ingestion.api_providers.professional_travel_api_provider.transform_data's existing blank-SCIPER branch (sciper_raw if sciper_raw and str(sciper_raw).strip() else TRAVELER_OTHER_EXTERNAL, line ~112-116) needs no edit — only the constant's value changes. -
Step 1: Add a failing assertion pinning the new sentinel type
In backend/tests/unit/services/data_ingestion/test_professional_travel_api_provider.py, find test_allows_missing_sciper (in TestTransformData) and add a stronger literal assertion after the existing one:
async def test_allows_missing_sciper(self, provider):
# #1153: SCIPER is no longer mandatory — a traveler with no EPFL
# SCIPER still comes through, tagged with the external-traveler
# sentinel the frontend resolves to "Other traveler (external)".
records = [self._make_record(SCIPER="")]
result = await provider.transform_data(records)
assert len(result) == 1
assert result[0]["user_institutional_id"] == TRAVELER_OTHER_EXTERNAL
# Pin the sentinel scheme itself (not just the imported symbol):
# External other is real JSON null, not a string sentinel.
assert result[0]["user_institutional_id"] is None
- Step 2: Run test to verify it fails
Run: cd backend && uv run pytest tests/unit/services/data_ingestion/test_professional_travel_api_provider.py::TestTransformData::test_allows_missing_sciper -v
Expected: FAIL — result[0]["user_institutional_id"] is currently the string "__other_external__", not None.
- Step 3: Update the sentinel constants
In professional_travel_api_provider.py, replace lines 21-25:
# Sentinel ``user_institutional_id`` for a traveler with no EPFL SCIPER
# (#1153). Must match ``TRAVELER_OTHER_EXTERNAL`` in
# frontend/src/constant/module-config/traveler-options.ts, which resolves it
# to the "Other traveler (external)" display label.
TRAVELER_OTHER_EXTERNAL = "__other_external__"
with:
# Sentinel ``user_institutional_id`` values for a traveler not tied to a
# resolvable Headcount identity (#1153, revised to the -1/null scheme —
# see docs/src/implementation-plans/1153-traveler-sentinel-resolution-prd.md).
# Must match the same-named constants in
# frontend/src/constant/module-config/traveler-options.ts.
# - INTERNAL: traveler has a SCIPER but it doesn't resolve against this
# report's Headcount roster. Not assigned by ingestion (a Tableau row
# either has a SCIPER or doesn't) — read-time resolution only, defined
# here for centralized reuse (tests, future create-DTO validation).
# - EXTERNAL: traveler has no SCIPER at all. Ingestion assigns this on a
# blank/None/whitespace SCIPER.
TRAVELER_OTHER_INTERNAL = "-1"
TRAVELER_OTHER_EXTERNAL = None
- Step 4: Run test to verify it passes
Run: cd backend && uv run pytest tests/unit/services/data_ingestion/test_professional_travel_api_provider.py -v
Expected: PASS, all tests in the file (this constant swap doesn't change any other assertion since the other tests import the symbol rather than hardcoding the string).
- Step 5: Pin the literal contract
Add near the top of TestTransformData (or as a standalone test) in the same test file:
def test_sentinel_constants_are_the_agreed_literals():
"""Pins the exact wire values — frontend traveler-options.ts must match."""
assert TRAVELER_OTHER_INTERNAL == "-1"
assert TRAVELER_OTHER_EXTERNAL is None
Add TRAVELER_OTHER_INTERNAL to the existing import line at the top of the test file (it already imports TRAVELER_OTHER_EXTERNAL).
- Step 6: Run the full file and commit
Run: cd backend && uv run pytest tests/unit/services/data_ingestion/test_professional_travel_api_provider.py -v && uv run ruff check app/services/data_ingestion/api_providers/professional_travel_api_provider.py tests/unit/services/data_ingestion/test_professional_travel_api_provider.py
Expected: PASS, ruff clean.
git add backend/app/services/data_ingestion/api_providers/professional_travel_api_provider.py backend/tests/unit/services/data_ingestion/test_professional_travel_api_provider.py
git commit -m "feat(travel-api): switch traveler sentinels to -1/null (#1153)"
Task 2: Backend — nullable user_institutional_id on Create and Response DTOs¶
Files:
- Modify:
backend/app/modules/professional_travel/data_entries.py - Test: Create
backend/tests/unit/modules/test_professional_travel_schemas.py
Interfaces:
- Consumes: nothing from Task 1.
-
Produces:
ProfessionalTravelPlaneHandlerCreate.user_institutional_id: str | None,ProfessionalTravelTrainHandlerCreate.user_institutional_id: str | None,ProfessionalTravelPlaneHandlerResponse.user_institutional_id: str | None,ProfessionalTravelTrainHandlerResponse.user_institutional_id: str | None. Task 3's repo test constructs rows relying on the Response DTO acceptingNone/"-1". -
Step 1: Write the failing test
Create backend/tests/unit/modules/test_professional_travel_schemas.py:
"""Traveler sentinel validation for Professional Travel DTOs (#1153).
user_institutional_id is a free-text SCIPER string inside DataEntry.data —
no FK, no enum. "-1" (Internal other) and null (External other) must
validate on both the Create DTOs (frontend form submission, PR #1153/#2117)
and the Response DTOs (existing rows read back from the DB must not fail
serialization now that External-other rows persist a real null).
"""
import pytest
from pydantic import ValidationError
from app.modules.professional_travel.data_entries import (
ProfessionalTravelPlaneHandlerCreate,
ProfessionalTravelPlaneHandlerResponse,
ProfessionalTravelTrainHandlerCreate,
ProfessionalTravelTrainHandlerResponse,
)
_PLANE_META = {
"data_entry_type_id": 1,
"carbon_report_module_id": 1,
"data": {},
"origin_iata": "GVA",
"destination_iata": "ZRH",
"cabin_class": "economy",
}
_TRAIN_META = {
"data_entry_type_id": 2,
"carbon_report_module_id": 1,
"data": {},
"origin_name": "Lausanne",
"destination_name": "Geneva",
"origin_country_code": "CH",
"destination_country_code": "CH",
"cabin_class": "second",
}
@pytest.mark.parametrize("sciper", ["123456", "-1", None])
def test_plane_create_accepts_sentinel_and_real_sciper(sciper) -> None:
item = ProfessionalTravelPlaneHandlerCreate.model_validate(
{**_PLANE_META, "user_institutional_id": sciper}
)
assert item.user_institutional_id == sciper
@pytest.mark.parametrize("sciper", ["123456", "-1", None])
def test_train_create_accepts_sentinel_and_real_sciper(sciper) -> None:
item = ProfessionalTravelTrainHandlerCreate.model_validate(
{**_TRAIN_META, "user_institutional_id": sciper}
)
assert item.user_institutional_id == sciper
def test_plane_create_still_requires_the_field() -> None:
payload = {k: v for k, v in _PLANE_META.items()}
with pytest.raises(ValidationError):
ProfessionalTravelPlaneHandlerCreate.model_validate(payload)
@pytest.mark.parametrize("sciper", ["123456", "-1", None])
def test_plane_response_accepts_sentinel_and_real_sciper(sciper) -> None:
item = ProfessionalTravelPlaneHandlerResponse.model_validate(
{
"id": 1,
"data_entry_type_id": 1,
"carbon_report_module_id": 1,
"source": None,
"user_institutional_id": sciper,
"origin_iata": "GVA",
"destination_iata": "ZRH",
}
)
assert item.user_institutional_id == sciper
@pytest.mark.parametrize("sciper", ["123456", "-1", None])
def test_train_response_accepts_sentinel_and_real_sciper(sciper) -> None:
item = ProfessionalTravelTrainHandlerResponse.model_validate(
{
"id": 1,
"data_entry_type_id": 2,
"carbon_report_module_id": 1,
"source": None,
"user_institutional_id": sciper,
"origin_name": "Lausanne",
"destination_name": "Geneva",
}
)
assert item.user_institutional_id == sciper
- Step 2: Run tests to verify the sentinel/None cases fail
Run: cd backend && uv run pytest tests/unit/modules/test_professional_travel_schemas.py -v
Expected: the None parametrization of each *_accepts_sentinel_and_real_sciper test FAILS with a pydantic ValidationError (user_institutional_id is currently str, non-optional); the "123456"/"-1" cases and test_plane_create_still_requires_the_field already PASS (they don't need the type change).
- Step 3: Widen the four fields
In backend/app/modules/professional_travel/data_entries.py, change all four occurrences of user_institutional_id: str to user_institutional_id: str | None — in ProfessionalTravelPlaneHandlerResponse, ProfessionalTravelTrainHandlerResponse, ProfessionalTravelPlaneHandlerCreate, ProfessionalTravelTrainHandlerCreate. No other field changes.
- Step 4: Run tests to verify they pass
Run: cd backend && uv run pytest tests/unit/modules/test_professional_travel_schemas.py -v
Expected: PASS, all cases.
- Step 5: Commit
git add backend/app/modules/professional_travel/data_entries.py backend/tests/unit/modules/test_professional_travel_schemas.py
git commit -m "feat(travel): accept null/-1 user_institutional_id on travel DTOs (#1153)"
Task 3: Backend — end-to-end resolution matrix through the repo + safety comment¶
Files:
- Modify:
backend/app/repositories/data_entry_repo.py:870-880(comment only, no logic change) - Test:
backend/tests/unit/repositories/test_data_entry_repo.py
Interfaces:
- Consumes:
TRAVELER_OTHER_INTERNALfrom Task 1 (app.services.data_ingestion.api_providers.professional_travel_api_provider), the widened Response DTOs from Task 2. -
Produces: nothing new — this task only proves the existing
DataEntryRepository.get_submodule_data(carbon_report_module_id: int, data_entry_type_id: int, limit: int, offset: int, sort_by: str, sort_order: str, filter: str | None = None, institutional_id_filter: str | None = None, exclude_planner_snapshots: bool = False) -> SubmoduleResponseround-trips the full matrix without raising and without ever rewriting a stored value. -
Step 1: Write the failing (well: currently-erroring) test
Append to backend/tests/unit/repositories/test_data_entry_repo.py:
from app.models.module_type import ModuleTypeEnum
from app.services.data_ingestion.api_providers.professional_travel_api_provider import (
TRAVELER_OTHER_INTERNAL,
)
# ======================================================================
# Traveler sentinel resolution matrix (#1153, -1/null scheme)
# ======================================================================
def _plane_entry(module_id: int, sciper: str | None) -> DataEntry:
return DataEntry(
carbon_report_module_id=module_id,
data_entry_type_id=DataEntryTypeEnum.plane,
status=DataEntryStatusEnum.PENDING,
data={
"user_institutional_id": sciper,
"origin_iata": "GVA",
"destination_iata": "ZRH",
"cabin_class": "economy",
},
)
def _member_entry(module_id: int, sciper: str | None, name: str) -> DataEntry:
return DataEntry(
carbon_report_module_id=module_id,
data_entry_type_id=DataEntryTypeEnum.member,
status=DataEntryStatusEnum.PENDING,
data={"user_institutional_id": sciper, "name": name, "sius_code": "51", "fte": 1.0},
)
@pytest.mark.asyncio
async def test_traveler_resolution_matrix(db_session: AsyncSession):
"""PRD §4 matrix, driven through the real get_submodule_data query.
Every row must round-trip its stored user_institutional_id unchanged
(never overwritten by the resolver), regardless of whether a Headcount
match exists.
"""
repo = DataEntryRepository(db_session)
module_a = CarbonReportModule(
carbon_report_id=1,
module_type_id=ModuleTypeEnum.professional_travel.value,
status="in_progress",
)
module_b = CarbonReportModule(
carbon_report_id=2,
module_type_id=ModuleTypeEnum.professional_travel.value,
status="in_progress",
)
db_session.add(module_a)
db_session.add(module_b)
await db_session.flush()
# Headcount: "123456" is a member of module_a's report only.
db_session.add(_member_entry(module_a.id, "123456", "Ada Lovelace"))
# A different unit/year's Headcount also has "999999" — must NOT resolve
# to module_a's travel row with the same SCIPER (unit isolation, PRD §4).
db_session.add(_member_entry(module_b.id, "999999", "Wrong Unit Person"))
await db_session.flush()
rows = {
"matched": _plane_entry(module_a.id, "123456"),
"external": _plane_entry(module_a.id, None),
"internal_explicit": _plane_entry(module_a.id, TRAVELER_OTHER_INTERNAL),
"unresolved_source_id": _plane_entry(module_a.id, "45005"),
"wrong_unit_match": _plane_entry(module_a.id, "999999"),
}
for entry in rows.values():
db_session.add(entry)
await db_session.flush()
response = await repo.get_submodule_data(
carbon_report_module_id=module_a.id,
data_entry_type_id=DataEntryTypeEnum.plane.value,
limit=10,
offset=0,
sort_by="id",
sort_order="asc",
)
by_id = {item.id: item for item in response.items}
# Every stored value survives unchanged — resolution never rewrites data.
assert by_id[rows["matched"].id].user_institutional_id == "123456"
assert by_id[rows["external"].id].user_institutional_id is None
assert (
by_id[rows["internal_explicit"].id].user_institutional_id
== TRAVELER_OTHER_INTERNAL
)
assert by_id[rows["unresolved_source_id"].id].user_institutional_id == "45005"
assert by_id[rows["wrong_unit_match"].id].user_institutional_id == "999999"
Add DataEntryStatusEnum to the existing app.models.data_entry import line
at the top of the file if not already imported (it already imports
DataEntry, DataEntryTypeEnum; check before adding to avoid a duplicate
import).
- Step 2: Run test to verify it fails
Run: cd backend && uv run pytest tests/unit/repositories/test_data_entry_repo.py::test_traveler_resolution_matrix -v
Expected: FAILS at construction/validation — by_id[rows["internal_explicit"].id].user_institutional_id raises KeyError or the DTO raises ValidationError for the None row, because Task 2 hasn't landed yet in isolation. If Tasks 1-2 are already merged by the time this runs, this test should already PASS (it's a characterization test proving the existing subquery logic — described in the PRD as needing zero changes — actually holds); in that case skip Step 2's "must fail" expectation and proceed straight to Step 3 (add the comment) since there is no red state left to observe.
- Step 3: Add the safety comment (no logic change)
In backend/app/repositories/data_entry_repo.py, immediately before the existing comment block at line ~871 (# A person can hold multiple headcount roles...), add:
# Both TRAVELER_OTHER_INTERNAL ("-1") and External-other
# (real SQL NULL) rely on this equality never spuriously
# matching a MemberEntry: no real SCIPER is ever "-1", and
# SQL's NULL = NULL evaluates to NULL (not true) — so an
# External-other travel row can never match a Headcount
# member who also has no SCIPER yet (#951 made that
# optional too). See
# docs/src/implementation-plans/1153-traveler-sentinel-resolution-prd.md §5.
- Step 4: Run test to verify it passes
Run: cd backend && uv run pytest tests/unit/repositories/test_data_entry_repo.py -v
Expected: PASS, full file.
- Step 5: Commit
git add backend/app/repositories/data_entry_repo.py backend/tests/unit/repositories/test_data_entry_repo.py
git commit -m "test(travel): pin traveler-sentinel resolution matrix through get_submodule_data (#1153)"
Task 4: Backend — Alembic data migration for legacy sentinel values¶
Files:
- Create:
backend/alembic/versions/<generated>.py
Interfaces:
- Consumes: nothing (pure data migration, independent of Tasks 1-3's Python code).
-
Produces: nothing consumed by later tasks.
-
Step 1: Generate the revision skeleton
Run: cd backend && make db-revision message="migrate legacy traveler sentinels to -1 and null"
This runs uv run alembic revision --autogenerate -m "..." and fills in
down_revision from the current head automatically — do not hand-pick a
revision id. Since this is a data-only change with no model/column diff,
autogenerate should produce empty upgrade()/downgrade() bodies (same as
2026_07_22_1444-2c7f5cf1c9de_migrate_mice_research_facility_type_to_.py,
which is the template for Step 2). If autogenerate emits unrelated noise
(e.g. a stray index), prune it — see feedback_alembic_via_make_db_revision
convention.
- Step 2: Write the migration body
Fill in the generated file's upgrade() and downgrade():
def upgrade() -> None:
"""Rewrite legacy string traveler sentinels to -1 / null (#1153)."""
op.execute(
sa.text(
"""
UPDATE data_entries
SET data = jsonb_set(data::jsonb, '{user_institutional_id}', '"-1"')::json
WHERE data->>'user_institutional_id' = '__other_internal__'
"""
)
)
op.execute(
sa.text(
"""
UPDATE data_entries
SET data = jsonb_set(data::jsonb, '{user_institutional_id}', 'null')::json
WHERE data->>'user_institutional_id' = '__other_external__'
"""
)
)
def downgrade() -> None:
"""Restore the legacy string sentinels — the exact inverse."""
op.execute(
sa.text(
"""
UPDATE data_entries
SET data = jsonb_set(data::jsonb, '{user_institutional_id}', '"__other_internal__"')::json
WHERE data->>'user_institutional_id' = '-1'
"""
)
)
op.execute(
sa.text(
"""
UPDATE data_entries
SET data = jsonb_set(data::jsonb, '{user_institutional_id}', '"__other_external__"')::json
WHERE data->>'user_institutional_id' IS NULL
AND data::jsonb ? 'user_institutional_id'
"""
)
)
Note the downgrade's External-other WHERE clause: data->>'user_institutional_id' IS NULL AND data::jsonb ? 'user_institutional_id' — matches only rows where the key is present with a null value (this migration's own contract), not rows where the key is absent entirely (e.g. non-travel data entries, which have no such key at all and must not be touched). The ::jsonb cast is required: data_entries.data is Postgres json, and the ? (has-key) operator is jsonb-only — found and fixed during Task 4's implementation (2026-08-14), documented here for consistency.
Update the module docstring at the top of the generated file to explain the
"why" (mirror the mice migration's docstring style): this migration exists
because #1153's traveler sentinels moved from ad-hoc strings to
"-1"/null, and this repo's DB persists across deploys (backfills ship
with the code, not "moot after reseed").
- Step 3: Verify upgrade/downgrade apply cleanly
Run: cd backend && uv run alembic upgrade head against your local dev DB
(start one via docker compose up -d db if not already running), then uv
run alembic downgrade -1 to confirm the inverse also applies without error.
Expected: both complete with no errors.
- Step 4: Commit
git add backend/alembic/versions/
git commit -m "feat(db): migrate legacy __other_internal__/__other_external__ sentinels (#1153)"
Task 5: Frontend — traveler-options.ts: new sentinel values, fixed resolver, extracted cell/legend helpers¶
Files:
- Modify:
frontend/src/constant/module-config/traveler-options.ts - Test:
frontend/tests/unit/travel-other-traveler.spec.ts
Interfaces:
- Produces:
TRAVELER_OTHER_INTERNAL: string = '-1'TRAVELER_OTHER_EXTERNAL: null = nullresolveTravelerName(userInstitutionalId: string | null | undefined, memberName: string | undefined, t: (key: string) => string): string— behavior changed:undefined→'-';null→ External label (previously both collapsed to'-').- New:
resolveTravelerCellText(userInstitutionalId: string | null | undefined, headcountMembersMap: Map<string, string>, currentUserInstitutionalId: string | null | undefined, currentUserDisplayName: string, t: (key: string) => string): string— consumed by Task 6 (ModuleTable.vue). -
New:
travelerSentinelMapEntries(t: (key: string) => string): [string, string][]— consumed by Task 7 (ModuleCharts.vue). Returns[TRAVELER_OTHER_INTERNAL, label]and['', label]— the trips-map endpoint coerces anullSCIPER to''server-side (data_entry_repo.py:1363,tid = traveler_id or ""), so the External entry is keyed'', notTRAVELER_OTHER_EXTERNAL. -
Step 1: Write the failing tests
Replace the first test in frontend/tests/unit/travel-other-traveler.spec.ts
('#1153: absent traveler id renders a dash') — it currently asserts null
renders '-', which is the exact bug this task fixes:
test("#1153: no data yet (undefined) renders a dash", () => {
expect(resolveTravelerName(undefined, undefined, t)).toBe("-");
});
test("#1153: explicit null (External other) resolves to the external label, not a dash", () => {
expect(resolveTravelerName(null, undefined, t)).toBe(
TRAVELER_OTHER_EXTERNAL_LABEL_KEY,
);
});
Append new tests for the two extracted helpers at the end of the file:
import {
resolveTravelerCellText,
travelerSentinelMapEntries,
} from "../../src/constant/module-config/traveler-options";
test("#1153: cell text — undefined id (loading) renders a dash", () => {
expect(
resolveTravelerCellText(undefined, new Map(), undefined, "Me", t),
).toBe("-");
});
test("#1153: cell text — external sentinel renders the external label", () => {
expect(resolveTravelerCellText(null, new Map(), undefined, "Me", t)).toBe(
TRAVELER_OTHER_EXTERNAL_LABEL_KEY,
);
});
test("#1153: cell text — internal sentinel renders the internal label", () => {
expect(
resolveTravelerCellText(
TRAVELER_OTHER_INTERNAL,
new Map(),
undefined,
"Me",
t,
),
).toBe(TRAVELER_OTHER_INTERNAL_LABEL_KEY);
});
test("#1153: cell text — matching roster entry wins over the raw SCIPER", () => {
const roster = new Map([["0184", "Ada Lovelace"]]);
expect(resolveTravelerCellText("0184", roster, undefined, "Me", t)).toBe(
"Ada Lovelace",
);
});
test("#1153: cell text — current user shortcut wins when not in the roster map yet", () => {
expect(
resolveTravelerCellText("0184", new Map(), "0184", "Ada Lovelace", t),
).toBe("Ada Lovelace");
});
test("#1153: cell text — unresolved SCIPER falls back to the internal label", () => {
expect(resolveTravelerCellText("999999", new Map(), undefined, "Me", t)).toBe(
TRAVELER_OTHER_INTERNAL_LABEL_KEY,
);
});
test('#1153: trips-map legend keys external under "" (matches the backend leg coercion)', () => {
const entries = travelerSentinelMapEntries(t);
expect(entries).toContainEqual([
TRAVELER_OTHER_INTERNAL,
TRAVELER_OTHER_INTERNAL_LABEL_KEY,
]);
expect(entries).toContainEqual(["", TRAVELER_OTHER_EXTERNAL_LABEL_KEY]);
});
Update the file's top-of-file import list to add
resolveTravelerCellText, travelerSentinelMapEntries (kept as a second
import statement is fine, or merge into the existing one — match the
existing single-import-block style).
- Step 2: Run tests to verify they fail
Run: cd frontend && rtk playwright test -c playwright-ct.config.ts tests/unit/travel-other-traveler.spec.ts
Expected: FAIL — the renamed/new null test fails (resolveTravelerName
still has the loose == null guard), and every resolveTravelerCellText /
travelerSentinelMapEntries test fails (not exported yet).
- Step 3: Fix the resolver and add the two helpers
In frontend/src/constant/module-config/traveler-options.ts, change the
constants (lines 15-16):
export const TRAVELER_OTHER_INTERNAL = "__other_internal__";
export const TRAVELER_OTHER_EXTERNAL = "__other_external__";
to:
export const TRAVELER_OTHER_INTERNAL = "-1";
export const TRAVELER_OTHER_EXTERNAL = null;
Fix resolveTravelerName (the if (userInstitutionalId == null) return '-';
line):
export function resolveTravelerName(
userInstitutionalId: string | null | undefined,
memberName: string | undefined,
t: (key: string) => string,
): string {
// Only "no data yet" renders a dash. Once External other is a real
// `null`, a loose `== null` here would swallow it too — use `===`.
if (userInstitutionalId === undefined) return "-";
if (userInstitutionalId === TRAVELER_OTHER_EXTERNAL) {
return t(TRAVELER_OTHER_EXTERNAL_LABEL_KEY);
}
if (userInstitutionalId === TRAVELER_OTHER_INTERNAL) {
return t(TRAVELER_OTHER_INTERNAL_LABEL_KEY);
}
if (memberName) return memberName;
return t(TRAVELER_OTHER_INTERNAL_LABEL_KEY);
}
Append the two new exported helpers at the end of the file:
/**
* Resolve the traveler_name table-cell text for a Professional Travel row
* (extracted from ModuleTable.vue's renderCell so it's unit-testable
* without mounting the component). Precedence: no data yet → dash; roster
* match → member name; the viewer's own id → their display name (covers
* standard users whose roster map may not include themselves); otherwise
* delegate to resolveTravelerName for the sentinel/unresolved-SCIPER cases.
*/
export function resolveTravelerCellText(
userInstitutionalId: string | null | undefined,
headcountMembersMap: Map<string, string>,
currentUserInstitutionalId: string | null | undefined,
currentUserDisplayName: string,
t: (key: string) => string,
): string {
if (userInstitutionalId === undefined) return "-";
if (userInstitutionalId !== null) {
const member = headcountMembersMap.get(userInstitutionalId);
if (member) return member;
if (userInstitutionalId === currentUserInstitutionalId) {
return currentUserDisplayName;
}
}
return resolveTravelerName(userInstitutionalId, undefined, t);
}
/**
* Legend entries for the trips-map "Other traveler" sentinels
* (ModuleCharts.vue). get_professional_travel_trips_map coerces a null
* SCIPER to "" server-side (`tid = traveler_id or ""`, data_entry_repo.py)
* — that endpoint never sees TRAVELER_OTHER_EXTERNAL's real null, so the
* legend must be keyed to what it actually emits.
*/
export function travelerSentinelMapEntries(
t: (key: string) => string,
): [string, string][] {
return [
[TRAVELER_OTHER_INTERNAL, t(TRAVELER_OTHER_INTERNAL_LABEL_KEY)],
["", t(TRAVELER_OTHER_EXTERNAL_LABEL_KEY)],
];
}
- Step 4: Run tests to verify they pass
Run: cd frontend && rtk playwright test -c playwright-ct.config.ts tests/unit/travel-other-traveler.spec.ts
Expected: PASS, full file.
- Step 5: Commit
git add frontend/src/constant/module-config/traveler-options.ts frontend/tests/unit/travel-other-traveler.spec.ts
git commit -m "fix(travel): -1/null traveler sentinels, fix null-swallowed-to-dash bug (#1153)"
Task 6: Frontend — wire ModuleTable.vue to resolveTravelerCellText¶
Files:
- Modify:
frontend/src/components/organisms/module/ModuleTable.vue:508(import),:1346-1358(renderCell'straveler_namebranch)
Interfaces:
-
Consumes:
resolveTravelerCellTextfrom Task 5. -
Step 1: Replace the import
Change line 508:
import { resolveTravelerName } from "src/constant/module-config/traveler-options";
to:
import { resolveTravelerCellText } from "src/constant/module-config/traveler-options";
(resolveTravelerName was only used at the one call site being replaced below — confirmed via repo-wide grep before this plan was written.)
- Step 2: Replace the
traveler_namebranch
Replace:
if (col.field === "traveler_name") {
const user_institutional_id = row["user_institutional_id"] as
string | undefined;
if (user_institutional_id == null) return "-";
const member = headcountMembersMap.value.get(user_institutional_id);
if (member) return member;
if (user_institutional_id === authStore.user?.institutional_id) {
return authStore.displayName;
}
return resolveTravelerName(user_institutional_id, undefined, $t);
}
with:
if (col.field === "traveler_name") {
const user_institutional_id = row["user_institutional_id"] as
string | null | undefined;
return resolveTravelerCellText(
user_institutional_id,
headcountMembersMap.value,
authStore.user?.institutional_id,
authStore.displayName,
$t,
);
}
- Step 3: Type-check
Run: cd frontend && make type-check
Expected: no new errors (this is a straight behavior-preserving extraction
plus the null widening already covered by Task 5's helper signature).
- Step 4: Commit
git add frontend/src/components/organisms/module/ModuleTable.vue
git commit -m "refactor(travel): wire ModuleTable traveler cell through resolveTravelerCellText (#1153)"
Task 7: Frontend — wire ModuleCharts.vue to travelerSentinelMapEntries¶
Files:
- Modify:
frontend/src/components/organisms/module/ModuleCharts.vue:198-204(imports),:373-380(travelerSentinelLabels)
Interfaces:
-
Consumes:
travelerSentinelMapEntriesfrom Task 5. -
Step 1: Replace the sentinel import
Change:
import {
TRAVELER_OTHER_INTERNAL,
TRAVELER_OTHER_EXTERNAL,
TRAVELER_OTHER_INTERNAL_LABEL_KEY,
TRAVELER_OTHER_EXTERNAL_LABEL_KEY,
} from "src/constant/module-config/traveler-options";
to:
import { travelerSentinelMapEntries } from "src/constant/module-config/traveler-options";
(none of the four removed symbols are used elsewhere in this file — confirmed via grep before this plan was written.)
- Step 2: Replace
travelerSentinelLabels
Delete the local function:
// The two "Other traveler" sentinels (issue #1153) are stored verbatim as the
// traveler SCIPER, so seed their translated labels into every roster map — the
// map renderer would otherwise show the raw `__other_internal__` string.
function travelerSentinelLabels(): [string, string][] {
return [
[TRAVELER_OTHER_INTERNAL, t(TRAVELER_OTHER_INTERNAL_LABEL_KEY)],
[TRAVELER_OTHER_EXTERNAL, t(TRAVELER_OTHER_EXTERNAL_LABEL_KEY)],
];
}
and replace its two call sites in loadTravelerNames (...travelerSentinelLabels() appears twice — the success branch's travelerNames.value = new Map([...travelerSentinelLabels(), ...]) and the catch branch's travelerNames.value = new Map(travelerSentinelLabels());) with travelerSentinelMapEntries(t):
async function loadTravelerNames(unitId: number, year: number | string) {
try {
const members = await getHeadcountMembers(
await moduleStore.resolveCarbonReportId(unitId, year),
);
travelerNames.value = new Map([
...travelerSentinelMapEntries(t),
...members.map((m): [string, string] => [m.institutional_id, m.name]),
]);
} catch (err) {
// Still resolve the sentinels even if the roster fetch fails.
travelerNames.value = new Map(travelerSentinelMapEntries(t));
// Non-fatal: legs simply fall back to showing the raw SCIPER.
console.error("Failed to load headcount members for trips map", err);
}
}
- Step 3: Type-check
Run: cd frontend && make type-check
Expected: no new errors.
- Step 4: Commit
git add frontend/src/components/organisms/module/ModuleCharts.vue
git commit -m "refactor(travel): wire ModuleCharts trips-map legend through travelerSentinelMapEntries (#1153)"
Task 8: Frontend — widen HeadcountMemberSelect.vue's option type¶
Files:
- Modify:
frontend/src/components/organisms/module/HeadcountMemberSelect.vue:70-73
Interfaces:
- Consumes:
TRAVELER_OTHER_EXTERNAL(nownull) from Task 5.
Why this task exists: options (line 99-109) already pushes { value:
TRAVELER_OTHER_EXTERNAL } — once that constant is null (Task 5), this
violates the current SelectOption { value: string } interface. No
behavior change is needed beyond the type — the q-select binds
modelValue: string | null already, and emit-value/map-options pass
the raw value straight through untouched.
- Step 1: Widen the interface
Change:
interface SelectOption {
label: string;
value: string;
}
to:
interface SelectOption {
label: string;
value: string | null;
}
- Step 2: Type-check
Run: cd frontend && make type-check
Expected: PASS — this is a pure type widening with no new logic, so a
Playwright spec would only re-assert what Task 5's resolveTravelerName/
resolveTravelerCellText tests already cover (this component just passes
the sentinel value through unchanged); type-check is the right-sized proof
here.
- Step 3: Commit
git add frontend/src/components/organisms/module/HeadcountMemberSelect.vue
git commit -m "fix(travel): widen HeadcountMemberSelect option type for null sentinel (#1153)"
Task 9: Full verification pass and PR update¶
Files: none (verification only).
- Step 1: Backend full targeted suite
Run:
cd backend && uv run pytest \
tests/unit/services/data_ingestion/test_professional_travel_api_provider.py \
tests/unit/modules/test_professional_travel_schemas.py \
tests/unit/repositories/test_data_entry_repo.py \
tests/integration/modules/professional_travel/test_traveler_dropdown_integration.py \
tests/unit/v1/test_travel_table_visibility.py \
-v
Expected: PASS. Then run cd backend && make lint (ruff + mypy, per the backend Makefile's lint target) and fix anything the sentinel type change surfaces.
- Step 2: Frontend full targeted suite + type-check
Run:
cd frontend && rtk playwright test -c playwright-ct.config.ts tests/unit/travel-other-traveler.spec.ts
cd frontend && make type-check
cd frontend && npx eslint src/constant/module-config/traveler-options.ts src/components/organisms/module/ModuleTable.vue src/components/organisms/module/ModuleCharts.vue src/components/organisms/module/HeadcountMemberSelect.vue
Expected: PASS, no lint errors.
- Step 3: Update PR #2117
This branch (fix/1153-handle-travel-api-external) already has PR #2117
open against dev (per the brainstorming decision to stack this work on
the same branch rather than merge #2117 first). Push the new commits:
cd /Users/guilbert/works/git/github/worktrees/co2-calculator/fix/1153-handle-travel-api-external
git push
Then update the PR body (gh pr edit 2117 --body ...) to describe the full
scope now landed — the missing-value stats and SCIPER-optional ingest from
the original PR, plus the -1/null sentinel scheme, DTO widening,
migration, and frontend fixes from this plan. Link both plan docs:
docs/src/implementation-plans/1153-traveler-sentinel-resolution-prd.md
and docs/src/implementation-plans/1153-traveler-sentinel-resolution-plan.md.
- Step 4: Flip the plan doc status
Update this file's frontmatter status: in-progress → status: delivered
once Steps 1-3 are green and pushed.