---
feature: <Feature name, e.g. Instant Booking>
slug: <kebab-case file name from PROJECT_BRAIN registry>
surface: <client | provider | delivery>
consumer: flutter
version: 1.0.0
status: <in-progress | ready | deprecated>
brd_version: "1.3"
brd_ids: [<CUST-012>, <CUST-014>]
business_rules: [<BR-12>, <BR-14>]
decisions: [<DEC-01>]
schema_tables: [<orders>, <order_items>, <payments>]
screens: [<customer--booking--03-*>]   # patterns from the PROJECT_BRAIN Screens column
related_docs: [<../provider/orders.md>, <../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)

## Version history

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 below. |

## 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>

---

## 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 (`db-schema.sql`) | Read / write | Notes |
|-------------------------|--------------|-------|
| `<orders>` | read + write | <status values exposed, snapshots taken> |

## 5. Dart models

```dart
class <Entity> {
  final String id; // uuid (TD-19), never an int
  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> | <from BRD Project Guide §14> | <…> |

## 11. Open decisions and known limitations

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