# Orders-Note — Implementation Tasks

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

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

## Prerequisites

- [ ] `Order` model with `notes` in `$fillable` (`['notes','debt_amount']`) so `fill()` can set it and cannot set anything else. 🟢 (`app/Models/Order.php:11`)
- [ ] Admin route group `['web','admin']`; `/orders/{order}/note` registered **before** `resource('/orders')` with name `orders.update_note`. 🟢 (`routes/web.php:74-75`)
- [ ] `web` middleware providing CSRF + `_method` spoofing so a `Form::open(method PUT)` reaches this route. 🟢
- [ ] `admin_toastr` helper available for the success flash. 🟢

## Tasks

> Each task references the legacy file the behaviour was extracted from.

- [ ] T-01, Register `PUT /orders/{order}/note` → `OrderController@updateNote` in the admin group with name `orders.update_note`, **before** the `/orders` resource.
  - Legacy origin: `routes/web.php:74`
  - Done when: `PUT /orders/{id}/note` resolves to `updateNote()` for an authenticated admin; anonymous → `302` to `auth/login`.
  - Confidence: 🟢

- [ ] T-02, Implement `updateNote($request, $id)`: validate `notes` (`nullable|string`), `Order::findOrFail($id)`, `fill($valided)`, `save()`.
  - Legacy origin: `OrderController.php:344-351`
  - Done when: a valid request persists `orders.notes` and only that column changes.
  - Confidence: 🟢

- [ ] T-03, On success: flash `admin_toastr(__('Cập nhật thành công'))` and `redirect()->back()`.
  - Legacy origin: `OrderController.php:351-353`
  - Done when: a successful save returns a redirect back with the success toastr visible on the referring page.
  - Confidence: 🟢

- [ ] T-04, On save failure: `back()->withInput()->withErrors('Cập nhật thất bại')`.
  - Legacy origin: `OrderController.php:355`
  - Done when: a failed save returns a redirect back carrying old input and the error message.
  - Confidence: 🟡 (branch effectively unreachable — `Order` defines no halting `saving` event)

- [ ] T-05, Wire the inline note editor forms on the two reader screens to this route (`Form::open(['route'=>['orders.update_note','#id#'],'method'=>'PUT'])`, `#id#` swapped for the order id client-side).
  - Legacy origin: `resources/views/pages/customer-statis.blade.php:183`, `resources/views/pages/customer-orders.blade.php:121`
  - Done when: editing a note from the statistics and purchase-history screens posts to this endpoint and returns to the same screen.
  - Confidence: 🟢

- [ ] T-06, (Improvement, not in legacy) Add observability — log/metric on the note-write path (including the failure branch).
  - Legacy origin: `OrderController.php:342-356` (absence)
  - Done when: each note update emits a structured log or metric.
  - Confidence: 🔴

- [x] T-07, Confirm whether note edits should be gated by order status/editability.
  - Legacy origin: `OrderController.php:342-356` (absence of a guard)
  - Done when: the business confirms notes are free metadata (no guard) or a guard is specified and implemented.
  - Confidence: 🟢 — ✅ Confirmed intentional 2026-09-25 (`questions.md#question-14`): notes are free metadata, no guard needed.

## Test Tasks

- [ ] TT-01, Happy path: `PUT /orders/{id}/note` with a string note updates `orders.notes` and redirects back with a success toastr (see `requirements.md`, Acceptance Criteria).
- [ ] TT-02, Clear: an empty `notes` value clears the annotation without a validation error.
- [ ] TT-03, Validation: a non-string `notes` value fails `nullable|string` and redirects back with errors.
- [ ] TT-04, Unknown id: `PUT /orders/{unknown}/note` returns `404` (`findOrFail`).
- [ ] TT-05, Only-`notes` mutation: submitting extra fields (e.g. `total`, `status`) leaves them unchanged (mass-assignment bounded by `$fillable`).
- [ ] TT-06, Auth: anonymous request → `302` to `auth/login`.

## Data Migration Tasks (if applicable)

- None. Writes only the existing `orders.notes` column; introduces no schema. 🟢 (`data-dictionary.md` orders schema)

## Suggested Order

1. T-01 → T-02 (route + controller action).
2. T-03 → T-04 (success/failure responses).
3. T-05 (view wiring).
4. T-06 → T-07 (observability, status-guard decision) as improvements.

## Pending Gaps (🔴)

- **No observability (T-06):** the note-write path emits no signal, including on failure.