# Orders-Note — Contracts

> Produced by the Reversa **Writer** (phase: generation) · doc_level: `complete`
> Generated on 2026-09-21

**Confidence scale:** 🟢 CONFIRMED · 🟡 INFERRED · 🔴 GAP

External HTTP contract exposed by the `orders-note` unit — the single route `PUT /orders/{order}/note` (`OrderController::updateNote`, route name `orders.update_note`) under the admin group (`['web','admin']`, empty admin prefix), declared **before** `resource('/orders')` and on a distinct path so it is not shadowed by the resource `update` route. It is a server-rendered **form** write (redirect-back / PRG, not JSON), requires an authenticated admin session, and mutates exactly one column (`orders.notes`). 🟢 (`routes/web.php:74`, `OrderController.php:342-356`)

---

## PUT `/orders/{order}/note` — update an order's note 🟢 (`:342-356`)

- **Auth:** required; anonymous → `302 auth/login`. 🟢 (`routes/web.php:24-28`)
- **CSRF:** required (Laravel `web` middleware). The caller submits a form via `Form::open(method PUT)`, which emits the CSRF token and the `_method=PUT` spoof field. 🟢 (`customer-statis.blade.php:183`)
- **Request:**

  | Field | In | Type | Required | Notes |
  |-------|----|------|----------|-------|
  | `order` | path | integer | ✅ | Order id; loaded via `Order::findOrFail` — unknown id → `404`. 🟢 (`:348`) |
  | `notes` | body (form) | string | ❌ | `nullable|string`; empty/absent clears the note. A non-string value fails validation. 🟢 (`:345`) |
  | `_token` | body (form) | string | ✅ | CSRF token (emitted by `Form::open`). 🟢 |
  | `_method` | body (form) | string | ✅ | `PUT` (method spoof for the HTML form). 🟢 |

- **Response — success:** `302` redirect **back** to the referring page, with an `admin_toastr` success flash (`Cập nhật thành công`). No body payload. 🟢 (`:352-353`)
- **Response — validation failure:** redirect back with the Laravel error bag (a non-string `notes`). 🟢 (`:345`)
- **Response — save failure:** `302` redirect back with old input + error `Cập nhật thất bại`. (Effectively unreachable — `Order` defines no halting `saving` event.) 🟡 (`:355`)
- **Status codes:** `302` (success/failure redirect back; → `auth/login` when unauthenticated) · `404` for an unknown id (`findOrFail`) · `419` if the CSRF token is missing/expired. No JSON variant. 🟢 (`:342-356`)
- **Side effect:** sets `orders.notes` only; mass-assignment bounded by `Order::$fillable = ['notes','debt_amount']`, so no other column can be written. 🟢 (`Order.php:11`; `:349`)

---

## Consumed contracts (owned by other units)

`orders-note` reads/writes only the `orders` table through Eloquent; it calls no other unit's HTTP endpoint and no external service. 🟢

| Reads / writes | Owner unit | Purpose |
|----------------|------------|---------|
| `orders.notes` (write), `orders` row (`findOrFail`) | `orders-crud` | the order whose note is edited |

---

## Producer/consumer relationships

| This unit is… | Counterparty | Contract |
|---------------|--------------|----------|
| **Producer** | `customers-statistics` | that screen renders the inline note editor (`Form::open` → `orders.update_note`) and consumes `notes` as its "annotated orders" filter (`whereNotNull('notes')`). 🟢 (`customer-statis.blade.php:183`) |
| **Producer** | `customers-purchase-history` | that screen also renders the inline note editor pointed at this route. 🟢 (`customer-orders.blade.php:121`) |
| **Consumer** | `orders-crud` | reads/writes the `Order` model owned by that unit (the `notes` column, appended `code`/`is_editable`/`debt_locked`). 🟢 |

---

## Cross-cutting contract notes

- **Method surface:** a single `PUT`; no other verbs on `/orders/{order}/note`. 🟢 (`routes/web.php:74`)
- **Content type:** form-encoded request; redirect-back response (`text/html` after the redirect), not JSON. 🟢 (`:353`)
- **Single-column write:** touches only `orders.notes`; no totals/points/debt/status recomputation. 🟢 (`:349`)
- **No status guard:** a note can be edited on any order regardless of status/age (contrast `orders-crud` `update`, which enforces `is_editable`). Confirmed intentional 2026-09-25 (`questions.md#question-14`). 🟢 (`:342-356`)
- **404 via `findOrFail`:** unknown id returns a clean `404`. 🟢 (`:348`)
- **Authorization:** authentication only; any admin may edit any order's note. 🟡 (ADR-0009)
- **No observability:** the note-write path emits no telemetry. 🔴 (`:342-356`, absence)