MOB-03 — API client from the OpenAPI contract + mock server workflow
hoco_api generated from openapi.json (models + dio client), regeneration script, Prism mock server for local development, contract version pinned.
| Field | Details |
|---|---|
| Task code | MOB-03 |
| Phase | P0 — Foundations (cadrage, UX/UI, architecture & contract) |
| Product scope | V1 |
| Status | Planned |
| Start | Sun 25 Oct 2026 |
| Due | Mon 26 Oct 2026 |
| Responsible | Imad — Mobile developer (Flutter) |
| Co-responsible | — |
| Effort | 1 person-day(s) planned · 3 from scratch · size S |
| Area · app | Mobile foundation · mobile |
| Depends on | SRV-03, MOB-02 |
| Unblocks | MOB-06, MOB-09, MOB-11 |
| Milestones | — |
Summary
hoco_api generated from openapi.json (models + dio client), regeneration script, Prism mock server for local development, contract version pinned.
Description
The Flutter apps cannot use the oRPC client, so they consume the API through a Dart client generated from the OpenAPI 3.1 document Anis publishes (SRV-03); this keeps mobile and server on one contract and lets Imad build against a mock server before the server exists. Scope: hoco_api generated models (freezed/json_serializable) and dio clients, a one-command regeneration script with the contract version pinned, a Prism mock workflow for the dev flavor, cursor-pagination helpers and a contract-drift check. Repositories per feature are built in the feature tasks. It needs from Anis the published openapi.json with operationIds equal to the op ids, declared error responses and realistic named examples. Every screen task calls these clients; MOB-12 switches from the mock to staging.
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Configure the generator (swagger_parser with freezed + json_serializable and dio clients per tag; openapi-generator dart-dio as fallback) so op ids map to methods such as catalogProductsList and delegateVisitsArrive | Imad |
| 2 | Pin the contract: packages/hoco_api/openapi/openapi.json + CONTRACT_VERSION; tool/api_gen.dart fetches a version, regenerates, runs build_runner and prints added/removed operations | Imad |
| 3 | Forward-compatible decoding: unknown enum values map to an unknown case, unknown fields ignored, nullable price/priceLocked for guests, money as int centimes, ISO dates as UTC DateTime | Imad |
| 4 | Riverpod providers for each generated client (AuthApi, MeApi, CatalogApi, DelegateToursApi, SyncApi…) on the hoco_core dio | Imad |
| 5 | CursorPage<T> { items, nextCursor } and a PagedListNotifier for infinite lists (limit 20, max 100) | Imad |
| 6 | Mock server: melos run mock starts Prism on openapi.json (port 4010, dynamic + named examples); dev flavor targets http://10.0.2.2:4010/v1 | Imad |
| 7 | Smoke tests in CI against Prism for auth.login, me.get, catalog.products.list, delegate.tours.today and sync.batch | Imad |
| 8 | Contract-drift job (oasdiff) comparing the pinned document with staging /openapi.json and failing on breaking changes | Imad |
| 9 | Feedback round on the SRV-03 draft: operationIds, nullable patterns, examples and error schemas that the Dart generator handles | Anis |
Deliverables
- packages/hoco_api/openapi/openapi.json and CONTRACT_VERSION
- packages/hoco_api/lib/src/generated/ (models and clients) and swagger_parser.yaml
- packages/hoco_api/tool/api_gen.dart and melos scripts api:gen and mock
- CI jobs mock-smoke and contract-check
Acceptance criteria
- Regeneration is one command and reproducible (a second run produces no diff); generated code needs no hand edits (NFR-09)
- Both apps' dev flavor sign in, load the catalog and load today's tour against the Prism mock
- A catalog response for a guest with price null, priceLocked true and availability IN_STOCK decodes without error
- An unknown enum value returned by the server does not crash decoding or the UI
- A breaking change in the staging contract fails the contract-check job before it reaches a release
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| NFR-09 | Maintainability: automated tests, CI gates, typed contracts, documentation | V1 |
API surface
| Endpoint group | Operations |
|---|---|
| Authentication & sessions | 10 |
| Me, devices, app config & reference data | 9 |
| Catalog & favorites | 12 |
| Tours & visits | 19 |
Test measures
- CI smoke tests against Prism for five operations
- Unit tests decoding guest and signed-in ProductCard payloads and an error envelope
- oasdiff breaking-change check on every PR touching openapi.json
Risks
- Dart generators mishandle OpenAPI 3.1 constructs (type arrays for nullable, anonymous oneOf) — validate on the SRV-03 draft and agree simple schema patterns with Anis; keep the fallback generator ready
- Prism's random data hides UI edge cases — ask Anis for named examples (guest, pending account, out-of-stock, empty lists)
KPI
- Delivered by Mon 26 Oct 2026 within 1 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
MOB-04 — Flutter design system — tokens, theme, components
hoco_ui: Akram's tokens as ThemeData + ThemeExtensions, typography, the mobile component library and a widget gallery app for design QA.
MOB-05 — Navigation, app shells & system states
go_router with auth guard, bottom-navigation shells for both apps, deep-link routes, splash/version check, offline/maintenance/forced-update/error/empty states.