ADORSYS-GIS / ADORSYS-GIS/converse-frontends

[Story]: Dev fixtures mirror the schema, not the client

Đang mở
#283 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
user-story
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.