# API plan — `<METHOD> /api/v1/<path>`   (audience: `<audience>` · flow: `<flow>`)

> **One file per endpoint**, saved at `docs/project/api/<audience>/<flow>/<endpoint>.md` (folder per audience → flow).
> **Self-contained:** ANY agent (even one that didn't do the analysis) must be able to **build AND document**
> this endpoint from THIS file alone — so consolidate everything relevant here. Produced **after the schema
> GATE, before** the sprint that builds it. Drives `build-api` + `build-tests` + `build-postman-collection`.

## 1) Identity
- **Endpoint:** `<METHOD> /api/v1/<path>`
- **Audience / platform:** `<user | provider | delegate | company | shared>` — `<app / web / both>` (same audience, app+web → this one endpoint serves both).
- **Flow / screen:** `<flow>` — Figma: `<screen name>` — **screen link (رابط كامل، لا node-id خام):** `https://www.figma.com/design/<fileKey>/<name>?node-id=<node بـ `-` لا `:`>&m=dev` (الـ `fileKey` من `brand-identity.md`؛ `254:1955` → `254-1955`) — **action:** `<submit / accept / reject / mark-received / …>`
- **Auth / guard:** `<public | auth:<audience> (guard per audience — default multi-auth) | auth:sanctum — see `build-auth-audience.md`>`
- **Rate limit:** `<none | named limiter (e.g. `throttle:request-code`)>` — sensitive endpoints (auth/OTP/writes) declare one, registered in `AppServiceProvider`.
- **Ownership:** `<none | scope to `auth()->id()` / owning column | Policy>` — anti-IDOR (see `build-auth-audience.md`).
- **Consumer:** `<which app screen / admin>`

## 2) How it works — logic (consolidated FROM the analysis)
> Pull **every** relevant rule about this endpoint out of `docs/project/analysis.md` (and the source PDF/Figma)
> and write it here in full — don't link, **inline it**. The reader should need nothing else.
- Step-by-step behavior: `<...>`
- Business rules / constraints: `<...>`
- **Status/state transitions** this action causes: `<from → to>` (+ the Enum)
- **Multi-step flow?** if this endpoint is **one step of a sequence** (e.g. `verify-current → set-new → verify-new` for a phone/email change), name the step + what precedes/follows it + the OTP type (`OtpType::OLD_*/NEW_*`). List the sibling steps so none is dropped.
- **Side effects (Laravel-first):** events fired / jobs queued / notifications sent: `<...>`
- Edge cases & failure conditions: `<...>`

## 3) Request
- Path / query params: `<name: type — rule>` (+ `?lang=ar|en`)
- Body fields: `<name: type — validation — required?>` (field label → `validation.php` → `attributes`; per-field message override → `custom.<field>.<rule>`)
- Files: `<field: rules (mime/size/array)>` — files are **normal inputs**; the model `FILES` + `BaseFilesTrait` upload them (no `UploadedFile` service param, no manual `$model->save()`).
- **Form Request:** `App\Http\Requests\Api\<Module>\<Name>Request` (extends `BaseApiRequest`) — rules above. **No `messages()`/`attributes()`** in the request; messages + translated field names live in `lang/{ar,en}/validation.php`.
- **Validation correctness — tick each (see `build-api.md` "API correctness"):**
  - [ ] **no client-only rules** (`terms=>accepted`, confirm-password match, …)
  - [ ] enum fields via `Rule::enum(<Enum>::class)` / `Rule::in(<Enum>::values())` — never an `in:...` literal
  - [ ] `unique`/`exists` on SoftDeletes tables are `->whereNull('deleted_at')`-aware
  - [ ] phone = separate `country_code` (`exists:countries,code`) + normalized `phone` (`PhoneNormalizer` in `prepareForValidation`)
  - [ ] messages & field-names in `validation.php` (`attributes` + `custom.<field>.<rule>`), **not** a per-request `messages()`

## 4) Response
- **Success:** `<200/201>` via `respondWithSuccess(msg, data)` — Resource `App\Http\Resources\Api\V1\<Resource>` (fields: `<...>`).
- **List vs detail resource:** index/list → `<Entity>ListResource` with **only the card's fields** (id + `<name, thumbnail, price…>` **from the screen**), **not** the full record (no `created_at`/full relations); show/detail → full `<Entity>Resource`.
- **UI copy (from the design):** the **exact** success/toast + inline-error wording shown on the screen → `<ar / en>` — used as the `api/<file>` message keys; never invent a generic "done successfully".
- **Shape rules** (see `build-api.md` "API correctness"): single resource → **flat `data`** (no `data.user` wrapper); **auth token inside the Resource**; **enums as `{value,label}`** (`GeneralEnumTrait::toValueLabel()`); include **computed/derived fields** the screen needs (`<is_subscribed, …>`).
- **List** → pagination block (`build-api` §5/§6). **Response** message keys (success/business) live in `lang/{ar,en}/api/<file>.php`; **validation** messages live in `validation.php` (§3) — never hardcode either.
- **Errors:** `<422 {message,errors} | 401 | 403 | 404 | 409 …>` with localized messages.

## 5) Postman — the request added to the collection JSON file
> `build-postman-collection` adds this **verbatim** into `docs/postman/<project>.postman_collection.json`
> (the file `START` created). The collection **folder = this flow**. Model shape on `save`'s collection.
- **Folder path:** `<section: Auth | Logic | Settings>` / `<flow>` · **Request name:** `<kebab-route-segment>` (e.g. `create-debt`)
- **URL:** `{{base_url}}<segment>` (+ `?lang=ar`) · **Method:** `<...>`
- **Auth:** per-request Bearer `{{user_token}}` (or none) + an explicit `Authorization` header.
- **Body:** `<formdata / raw json — with REAL Arabic example values>`
- **Test script (if it returns a token/id):** `pm.environment.set(...)` / `pm.collectionVariables.set(...)`.
- **Saved examples (required):** ✅ success · ⚠️ validation (422) · ❌ unauthorized/error — each a real request body + response.
- **Documentation (request description):** purpose · **screen link — الرابط الكامل** (`figma.com/design/<fileKey>/…?node-id=<node بـ `-`>&m=dev`، مبني آليًا؛ **ممنوع** الـ node-id الخام `254:1955` وحده) · **every variable/param explained** · auth · error list.

## 6) Build checklist (for the implementing agent)
- [ ] model/migration ready (build-database) — **reuse/alter existing, never a duplicate table**
- [ ] route + **thin** controller + service (the §2 logic) + Form Request + Resource
- [ ] lang keys ar+en (no hardcoded strings) · Laravel-first side effects wired
- [ ] tests (build-tests): success + validation + auth + envelope + i18n
- [ ] Postman request + examples + docs added (§5)