ADORSYS-GIS / ADORSYS-GIS/converse-frontends
[Story]: The client stops hardcoding server-owned catalogs
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Merge medio
- 1h 49m
- PR unite (30g)
- 253
Descrizione
## Story Statement
As a console user filtering usage by model or by dimension,
I want the Overview filters to offer the models and group-by dimensions the backend actually
supports,
so that I can filter by a real model instead of a single fake "All models" option, and so a
group-by choice maps onto a dimension the usage backend understands instead of a client-invented
one.
## Real Intent
The console currently guesses at two catalogs the server owns outright: the model list and the
usage `group-by` dimension enum. Both guesses were made because the procedures/enums that should
back them either weren't called yet (`listModelCatalog`, zero call sites) or were approximated with
a smaller, wrong set (`project | model` vs. the real `UsageGroupBy` enum). This story exists so the
Overview screen's filters reflect reality instead of a placeholder shipped before the contract was
read, and so a misconfigured budget backend is diagnosable instead of indistinguishable from an
outage.
## Background and Context
`MODEL_OPTIONS` in `apps/console/src/containers/use-overview-screen.ts:67` is a single hardcoded
`{ value: 'all', label: 'All models' }` entry. `listModelCatalog` exists in the schema
(`packages/authz-rpc/schema/authz.cstack:598`) with zero call sites anywhere in the console.
`OVERVIEW_GROUP_BYS` in `apps/console/src/client/url-state.ts:105` is `['project', 'model']`. The
usage backend's `UsageGroupBy` enum (`openapi/usage.backend.yaml:114`) is
`account_id | project_id | api_key_id | user_id | user_name | model | metric_name | signal_type` —
`project` is not `project_id`, so the URL param as it stands cannot address a real backend
dimension for the project case.
Separately, `budgetUrl` falls back silently to `backendUrl` when unset
(`apps/console/src/server/env.ts:173`), and the proxy always appends `/budget/rpc/…`
(`apps/console/src/server/proxy-target.ts:45-48`), so a genuinely missing budget backend config
produces the same 404 as a real outage — the `/admin` screen shows "Could not load the refill
queue." either way, with no way for an operator to tell configuration from incident.
## Source of truth (links)
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/packages/authz-rpc/schema/authz.cstack
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/openapi/usage.backend.yaml
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/docs/adr/0009-nextjs-console-replacement.md
- https://github.com/ADORSYS-GIS/converse-frontends/issues/277
## Acceptance Criteria
### Functional
- [ ] Given the Overview model filter, when it renders, then it lists real models from
`listModelCatalog`, not a single hardcoded `all` entry.
- [ ] Given a `group-by` URL param, when the user selects a group-by dimension, then the value sent
to the usage backend is a real `UsageGroupBy` member (via a mapping layer, or a deliberate
URL-contract change recorded per ADR 0011).
- [ ] Given a deployment where `budgetUrl` is not configured, when `/admin` fails to load the refill
queue, then the failure is reported as a misconfiguration, distinguishable from a real outage.
### Negative / Edge Cases
- [ ] Given `listModelCatalog` returns an empty list, then the model filter degrades to a clear
"no models available" state, not a silent empty dropdown.
- [ ] Given an old bookmarked URL with `groupBy=project`, then it is either mapped correctly or
redirected/handled per the ADR 0011 decision — it does not silently 400 against the backend.
### Non-Functional
- [ ] Observability: a budget-misconfiguration failure is distinguishable in logs/error surface from
a genuine upstream 5xx/timeout.
## Out of Scope
- Building the usage dashboards that would consume the model/group-by filters (Epic 4).
- Backend changes to `listModelCatalog` or `UsageGroupBy` (Epic 6, cross-team).
## Dependencies and Blockers
Depends on nothing outside this repo. Blocks Epic 4's usage-dashboard work insofar as those
dashboards will want a real model filter.
## Assumptions
- `listModelCatalog`'s existing shape is sufficient to populate a selector without further backend
work.
- The choice between a `group-by` mapping layer and a URL-contract change is a product/ADR decision
to be made and recorded at ticket time, not assumed here.
## Implementation Notes
Suggested approach: fetch `listModelCatalog` alongside the other Overview screen data and derive
`MODEL_OPTIONS` from the response; for `group-by`, prefer a thin mapping layer
(`project` → `project_id`) over a URL-contract break unless ADR 0011's "param names are product
surface" stance argues otherwise — the developer should challenge this if a contract change proves
simpler. For the budget-misconfiguration ticket, distinguish "unset" from "set" at config-read time
in `env.ts` rather than trying to infer it from the proxy's response shape.
## Test Expectations
Unit tests for the model-catalog fetch/derivation and the group-by mapping layer; a regression test
pinning the misconfigured-vs-outage distinction (e.g. asserting the error surfaced when `budgetUrl`
is unset differs from a mocked 5xx/timeout).
## Verification evidence
To be filled in by the implementing engineer at PR time: test run output, manual verification notes
against a real or mocked backend, and confirmation that no `MODEL_OPTIONS`/`group-by` literal
remains hardcoded.
## Human accountable owner
@stephane-segning
## AI Usage Declaration
Ticket decomposition
## Human verification completed
- [ ] I checked the story against the source of truth
- [ ] I confirmed the acceptance criteria
- [ ] I reviewed the implementation approach
- [ ] I verified generated code manually
- [ ] I verified generated tests manually
- [ ] I removed or corrected unsupported AI claims
- [ ] I am the accountable owner and accept responsibility for this story.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.