ADORSYS-GIS / ADORSYS-GIS/converse-frontends
[Story]: Dev fixtures mirror the schema, not the client
- Ngôn ngữ chính
- TypeScript
- Star
- 0
- Fork
- 0
- Merge trung bình
- 1 giờ 49 phút
- Pull request đã merge (30 ngày)
- 253
Mô tả
## Story Statement
As a console developer running the app locally against wiremock,
I want the dev fixtures to mirror the backend schema instead of the client's own assumptions,
so that a bug like a wrong status literal or a missing pagination total fails in dev the same way
it would fail in production, instead of passing because the fixture was authored to agree with it.
## Real Intent
Every data-integrity defect catalogued in Epic 1 — the `pending` vs `pending_review` status
mismatch, decided rows appearing inside a pending list, a missing `listBillingPlans` stub masking
the hardcoded `'standard'` billing plan bug, list responses with no `total` so pagination is never
exercised — passed local development because `wiremock/mappings/*.json` was written from the
console's own (incorrect) expectations, not from `packages/authz-rpc/schema/authz.cstack`. On top
of that, the backend has been CBOR-only since #256 while wiremock answers plain JSON, so even a
correct fixture is never actually decoded through the real client codec path. This story exists so
"tested against wiremock" starts meaning something again.
## Background and Context
Current wiremock stubs (`wiremock/mappings/console-budget.json:20,41`) hardcode
`"status": "pending"` — the real schema value is `pending_review`
(`packages/authz-rpc/schema/authz.cstack:1085,1105`) — which is precisely the literal that let the
Epic 1 refill-queue bug ship undetected. The stubs also still answer for ops the schema has since
retired: `addAccountMember`/`removeAccountMember` (superseded per
`packages/authz-rpc/schema/authz.cstack:609-611`) and `model.Account.update`/`delete` (now denied
unconditionally at the RBAC layer, `authz.cstack:165-181`).
Separately, `apps/console/README.md:402-406` documents that WireMock dev mode cannot exercise a real
data fetch end to end: the backend has spoken CBOR-only since #256, wiremock returns plain JSON, and
the console's `@cratestack/cbor` codec cannot decode it — so no console screen has ever actually been
exercised against fixture data through the real client path in dev.
## 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/apps/console/README.md
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/wiremock/mappings/console-budget.json
- https://github.com/ADORSYS-GIS/converse-frontends/issues/277
## Acceptance Criteria
### Functional
- [ ] Given every wiremock stub used by a console screen, when its shape and enum values are
compared against `authz.cstack`, then they match (status values, response shapes, presence of
`total` for paged lists).
- [ ] Given the Epic 1 defects (wrong status literal, decided-inside-pending, missing billing-plan
stub, missing pagination total), when they are reproduced against the rewritten fixtures, then
each one fails the way it would fail against the real backend.
- [ ] Given the CBOR-vs-JSON gap, when a developer reads the dev-harness documentation, then either
the fixtures now speak CBOR, or there is an explicit, current statement of exactly what dev
does and does not prove.
### Negative / Edge Cases
- [ ] Given a retired op (`addAccountMember`, `removeAccountMember`, `model.Account.update/delete`),
when the fixtures are rewritten, then no stub remains for it.
- [ ] Given a `listBillingPlans` stub, when the API-keys creation flow (Epic 2, Story 2.1) is
exercised in dev, then it can resolve real plan ids instead of failing for lack of a stub.
### Non-Functional
- [ ] Documentation: the CBOR-vs-JSON decision (whichever is chosen) is recorded in
`apps/console/README.md`, not left as a stale TODO.
## Out of Scope
- Standing up a real CBOR-speaking mock server if the decision is "document the limitation instead"
(that is an explicit alternative the ticket allows).
- Fixing the Epic 1 defects themselves — this story only ensures the harness would have caught them.
## Dependencies and Blockers
Depends on the Epic 1 fixes landing separately (or being reproducible against the rewritten
fixtures) to validate the "would have failed" acceptance criterion. No blockers from other epics.
## Assumptions
- `authz.cstack` is the single source of truth for stub shapes going forward — any future op change
updates the schema first, fixtures second.
- The CBOR-vs-JSON call is a deliberate trade-off between engineering cost (build/maintain a
CBOR-encoding stub layer) and coverage honesty (documenting the gap) — not a default answer.
## Implementation Notes
Suggested approach: audit every `wiremock/mappings/*.json` stub against the schema, one procedure at
a time, updating status/enum values, adding `total` to paged responses, adding a `listBillingPlans`
stub, and removing retired-op stubs. For the CBOR ticket, evaluate whether a hand-authored
CBOR-encoding stub layer is proportionate versus documenting the gap explicitly in the README (the
developer may reasonably conclude documentation is the safer, simpler option for now).
## Test Expectations
Manual/regression verification: reproduce each named Epic 1 defect against the rewritten fixtures
and confirm it now fails visibly. For the CBOR ticket, no new automated test is required if the
outcome is documentation — but the README statement itself should be reviewed as the deliverable.
## Verification evidence
To be filled in by the implementing engineer at PR time: which Epic 1 defects were reproduced
against the new fixtures and their (failing) result, and the final CBOR-vs-JSON decision with a link
to where it's documented.
## 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.
Hướng dẫn đóng góp
Hướng nghiên cứu
Start by reading wiremock/mappings/console-budget.json alongside packages/authz-rpc/schema/authz.cstack, then review apps/console/README.md and the linked Epic 1 issue. Audit the console mappings against the schema, reproduce the named Epic 1 defects manually, and record the final CBOR-vs-JSON decision in the README. Done means retired operations are absent and required shapes, enums, pagination totals, and billing-plan coverage are verified.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- typescript
- Lĩnh vực
- backend-api-design, documentation, testing, tooling
- Loại issue
- Tính năng
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 52/100