---
feature: <Feature name, e.g. Instant Booking>
slug: <kebab-case file name from PROJECT_BRAIN registry>
surface: <client | …a Flutter surface from config/docs.php>
consumer: flutter
version: 1.0.0
status: <in-progress | ready | deprecated>
brd_version: "<BRD version in force>"
brd_ids: [<CUST-012>]
business_rules: [<BR-12>, <BR-14>]
decisions: [<D1>, <DEC-01>, <TD-05>]
schema_tables: [<orders>, <order_items>]
screens: [<customer--booking--03-*>]   # patterns from the PROJECT_BRAIN Screens column (docs/app_screens/)
related_docs: [<../admin/orders.md>]
last_updated: <YYYY-MM-DD>
---

# <Feature name> — Flutter Integration Guide (<surface>)

> **Base URL:** `{HOST}/api/v1/<surface>` · Shared rules (headers, envelope,
> errors, pagination, Dio setup): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Quick reference

<!-- Read-this-first summary (≤ ~40 lines, budget docs.budgets.quick_reference_bytes).
     get-integration-brief / docs:brief return this section on its own, so it must be
     enough to start coding. One line per item; details live in the numbered sections. -->

| | |
|---|---|
| Version | 1.0.0 (YYYY-MM-DD) — latest change: <one line>; app action: <None / what to change> |
| Status | <ready> · BRD <IDs> · decisions <D1, DEC-xx> |
| Auth | <Bearer token of this surface · guest allowed?> |

**Endpoints**

| Method | Path | Route name | Purpose |
|--------|------|------------|---------|
| `GET` | `/<path>` | `<surface>.<group>.index` | <one line> |

**Statuses:** `<value>` (<meaning>) · `<value>` (<meaning>) — full table §4.
**Error codes:** `<ERROR_CODE>` (<when>) · `<ERROR_CODE>` (<when>).
**Open decisions:** <DEC-xx: one line> or None.

---

## 1. Business summary

<Two to four plain sentences: what the user can do, why, and the key rules that
change what the app shows. Written for a mobile developer, not a lawyer.>

## 2. User flow and screens

<Map each screen to the endpoint that feeds it and the actions on it.>

| Step | Screen / widget | Endpoint | Notes (states, empty, loading, errors) |
|------|-----------------|----------|-----------------------------------------|
| 1 | <ServiceDetailsScreen> | `GET /services/{id}` | <Required options must be chosen before "Continue"> |
| 2 | <ProviderListScreen> | `GET /services/{id}/providers` | <Featured providers first; empty state when none cover the address> |

```
<Optional ASCII flow, e.g.>
Service details ──► Providers ──► Summary ──► [Instant alert] ──► Payment ──► Confirmed
                                     └──► (scheduled) Request sent ──► Provider accepts ──► Payment
```

## 3. Endpoints

<Repeat this block per endpoint.>

### 3.x <Action name>

`<METHOD> /api/v1/<surface>/<path>`

| | |
|---|---|
| Auth | <Bearer token · approved account required? · guest allowed?> |
| Extra headers | <Idempotency-Key required? X-Country?> |
| Rate limit | <if any> |

**Path / query parameters**

| Name | In | Type | Required | Rules | Description |
|------|----|------|----------|-------|-------------|
| `id` | path | uuid (string) | yes | exists | <…> |

**Request body** (`application/json` or `multipart/form-data`)

| Field | Type | Required | Validation (mirror on the client) | Description |
|-------|------|----------|-----------------------------------|-------------|
| `address_id` | uuid (string) | yes | must belong to the user, inside a service area | <…> |

```json
{ "address_id": "0198a1c4-7b52-7c3e-9d0f-3f6a2b1c8e55", "options": ["0198a1c5-…", "0198a1c6-…"] }
```

**Success — `200`**

```json
<Real response copied from a feature test or Postman run>
```

**Response fields**

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| `status` | EnumValue | no | See §4 |
| `can_cancel` | bool | no | Show the cancel button only when `true` |

**Errors**

| HTTP | `error_code` | When | What the app should do |
|------|--------------|------|------------------------|
| 422 | — | Validation failed | Show `message` |
| 422 | `BUSINESS_RULE_VIOLATED` | <BR-xx violated, e.g. address outside service area> | <Ask user to change address> |
| 409 | `INVALID_STATE_TRANSITION` | <…> | <Refresh the order> |

## 4. Statuses and enums

| Enum | `value` | Meaning | Allowed actions (`can_*` flags true) |
|------|---------|---------|--------------------------------------|
| order_status | `confirmed` | Paid and confirmed | `can_cancel`, `can_chat` |

## Data model

| Table | Read / write | Notes |
|-------------------------|--------------|-------|
| `<orders>` | read + write | <status values exposed, snapshots taken> |

## 5. Dart models

```dart
class <Entity> {
  final String id; // the public id exactly as the API returns it
  final EnumValue status;
  final String totalAmount;   // money string, parse with parseMoney()
  final DateTime? scheduledAt;
  final bool canCancel;

  <Entity>.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        status = EnumValue.fromJson(j['status'] as Map<String, dynamic>),
        totalAmount = j['total_amount'] as String,
        scheduledAt = parseDate(j['scheduled_at']),
        canCancel = j['can_cancel'] as bool;
}
```

## 6. Business rules enforced by the backend

| Rule | What the backend does | What the user sees |
|------|-----------------------|--------------------|
| BR-xx | <…> | <message / disabled button> |

## 7. Notifications and real-time events

| Push `type` | Sent when | Payload `data` keys | App action on tap |
|-------------|-----------|---------------------|-------------------|
| `<order_confirmed>` | <…> | `order_id` | Open order details |

## 8. Localization and UI notes

- <Labels that come from the API vs. static app strings>
- <RTL considerations, number/currency formatting, date display>

## 9. Integration checklist

- [ ] Models created and parsing verified against the real responses above
- [ ] Every error code in §3 handled
- [ ] Buttons driven by `can_*` flags
- [ ] Empty, loading, and error states built for each screen
- [ ] Push `type`s from §7 routed
- [ ] Tested in `ar` (RTL) and `en`

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-<ID> | <acceptance scenario from the BRD> | <…> |

## 11. Open decisions and known limitations

| ID | Impact on this feature | Current behavior |
|----|------------------------|------------------|
| DEC-xx | <…> | <working assumption from docs/DECISIONS.md> |

---

## Version history

<!-- Keep the newest 5 rows here. Older rows and their changelog entries move to
     docs/<surface>/_history/<slug>.md (link it below) — agents rarely need them. -->

Newest first. Never edit an old row.

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.0 | YYYY-MM-DD | Initial | First release of the feature. | Integrate as described above. |

## Changelog

<!-- Copy this block for every new version, newest on top. -->

### 1.0.0 — YYYY-MM-DD
- **Added:** <endpoints / fields / statuses>
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** —
- **Breaking:** No
- **Endpoints affected:** `<METHOD /path>`
- **App action required:** <exact steps for the Flutter developer, or "None">
- **BRD / decisions:** <IDs this version implements or depends on>