feat(materials): partial consumption, returns to stock & reclassification (#99)

CHANGELOG.md

@@ -8,6 +8,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- **Partial consumption, returns to stock & material reclassification** *([#99](https://github.com/Mes-Open/OpenMes/issues/99))* — the shop floor rarely uses exactly what was issued, so a work order's pulled materials can now be reconciled against reality, every change booked to the stock-movement ledger. **Declare actual (partial) consumption** per material — recording what was really used leaves the over-issued surplus to be handed back. **Return unused quantity to stock** at any point before completion: the return raises on-hand, releases the reservation and restores the picked lots, and — critically — shrinks the allocation so batch completion never returns the same quantity twice. **Reclassify material** either between **classes** (regrade a quantity from one material to another, booking a correlated pair of movements) or by **lot status** (release / quarantine / reject — a rejected lot's remaining quantity is scrapped out of stock). Available on the admin work-order page (a **Materials reconciliation** panel) and over the API (`/api/v1/material-allocations/{id}/consume` & `/return`, `/api/v1/material-reclassifications/class`, `/api/v1/material-lots/{id}/reclassify-status`); reclassification is gated to Supervisor/Admin. A new append-only `material_reclassifications` audit table correlates the movement legs. All quantities/columns are additive — existing consumption at batch completion is unchanged.
 - **Controlled production stops and work-order change requests** *([#182](https://github.com/Mes-Open/OpenMes/issues/182))* — pause a running order, change what it builds under review, and resume on the new configuration **without ever overwriting what the shop floor already did**.
   - **A stop is a record, not just a status.** `POST /api/v1/work-orders/{id}/stop` captures a **typed reason** (`OPERATIONAL`, `MATERIAL_SHORTAGE`, `MACHINE_FAILURE`, `QUALITY_HOLD`, `ENGINEERING_CHANGE`, `OTHER`), who stopped production and when, and a **photograph of the state at that moment**: produced quantity, active/completed batches, in-progress steps, allocated and consumed material, and the configuration version in force. Only **one stop is open at a time**, so downtime totals can't double-count. Supplying a downtime reason also opens a **linked `production_downtimes` record** — a stop and a downtime stay separate concepts (why production stopped vs. how long a resource was idle), linked rather than merged, and closed together on resume. Duration is materialised on resume for reporting and reported as a **running total** while the stop is still open.
   - **A new `CHANGE_HOLD` status.** A stop raised with `requires_change` puts the order on **CHANGE_HOLD** instead of PAUSED — the board distinguishes "back after the break" from "nobody may build this until a change is approved" — and **resume is refused** until an approved change request has actually been **applied**. Plain pause/resume is untouched: an order paused the old way still resumes on an empty request body, with no change request and no stop record.

backend/app/Http/Controllers/Api/V1/MaterialAllocationController.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\RecordConsumptionRequest;
+use App\Http\Requests\Api\V1\ReturnAllocationRequest;
+use App\Models\MaterialAllocation;
+use App\Services\Material\MaterialAllocationService;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * Work-order material reconciliation (#99): declare actual (partial) consumption
+ * and return unused quantity to stock. Both funnel through
+ * MaterialAllocationService so stock, reservation and lot accounting stay in sync.
+ */
+class MaterialAllocationController extends Controller
+{
+    public function __construct(
+        protected MaterialAllocationService $allocations,
+    ) {}
+
+    public function consume(RecordConsumptionRequest $request, MaterialAllocation $allocation): JsonResponse
+    {
+        try {
+            $updated = $this->allocations->recordConsumption(
+                $allocation,
+                (float) $request->validated('consumed_qty'),
+                (float) ($request->validated('scrap_qty') ?? 0),
+                $request->validated('notes'),
+            );
+
+            return response()->json([
+                'message' => 'Consumption recorded',
+                'data' => $updated,
+            ]);
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+                'errors' => ['consumed_qty' => [$e->getMessage()]],
+            ], 422);
+        }
+    }
+
+    public function return(ReturnAllocationRequest $request, MaterialAllocation $allocation): JsonResponse
+    {
+        try {
+            $updated = $this->allocations->returnQuantity(
+                $allocation,
+                (float) $request->validated('qty'),
+                $request->user(),
+                $request->validated('reason'),
+            );
+
+            return response()->json([
+                'message' => 'Material returned to stock',
+                'data' => $updated,
+            ]);
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+                'errors' => ['qty' => [$e->getMessage()]],
+            ], 422);
+        }
+    }
+}

backend/app/Http/Controllers/Api/V1/MaterialReclassificationController.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\ReclassifyClassRequest;
+use App\Http\Requests\Api\V1\ReclassifyLotStatusRequest;
+use App\Models\Material;
+use App\Models\MaterialLot;
+use App\Services\Material\MaterialReclassificationService;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * Material reclassification (#99): regrade a quantity between material classes,
+ * or change a lot's status. Route-gated to Supervisor|Admin.
+ */
+class MaterialReclassificationController extends Controller
+{
+    public function __construct(
+        protected MaterialReclassificationService $reclassifications,
+    ) {}
+
+    public function class(ReclassifyClassRequest $request): JsonResponse
+    {
+        try {
+            $source = Material::findOrFail($request->validated('source_material_id'));
+            $target = Material::findOrFail($request->validated('target_material_id'));
+            $lot = $request->validated('source_lot_id')
+                ? MaterialLot::findOrFail($request->validated('source_lot_id'))
+                : null;
+
+            $record = $this->reclassifications->reclassifyClass(
+                $source,
+                $target,
+                (float) $request->validated('qty'),
+                $request->user(),
+                $lot,
+                $request->validated('reason'),
+            );
+
+            return response()->json([
+                'message' => 'Material reclassified',
+                'data' => $record,
+            ]);
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+                'errors' => ['qty' => [$e->getMessage()]],
+            ], 422);
+        }
+    }
+
+    public function status(ReclassifyLotStatusRequest $request, MaterialLot $materialLot): JsonResponse
+    {
+        try {
+            $record = $this->reclassifications->reclassifyStatus(
+                $materialLot,
+                $request->validated('to_status'),
+                $request->user(),
+                $request->validated('reason'),
+            );
+
+            return response()->json([
+                'message' => 'Lot status changed',
+                'data' => $record,
+            ]);
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+                'errors' => ['to_status' => [$e->getMessage()]],
+            ], 422);
+        }
+    }
+}

backend/app/Http/Controllers/Web/Admin/WorkOrderManagementController.php

@@ -3,15 +3,23 @@
 namespace App\Http\Controllers\Web\Admin;
 
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\ReclassifyClassRequest;
+use App\Http\Requests\Api\V1\RecordConsumptionRequest;
+use App\Http\Requests\Api\V1\ReturnAllocationRequest;
 use App\Http\Requests\Web\Admin\StoreWorkOrderRequest;
 use App\Http\Requests\Web\Admin\UpdateWorkOrderRequest;
 use App\Http\Requests\WorkOrder\ResumeWorkOrderRequest;
 use App\Models\Customer;
 use App\Models\Line;
+use App\Models\Material;
+use App\Models\MaterialAllocation;
+use App\Models\MaterialLot;
 use App\Models\ProcessTemplate;
 use App\Models\ProductType;
 use App\Models\WorkOrder;
 use App\Services\CustomFieldService;
+use App\Services\Material\MaterialAllocationService;
+use App\Services\Material\MaterialReclassificationService;
 use App\Services\WorkOrder\WorkOrderService;
 use App\Services\WorkOrder\WorkOrderStopService;
 use Illuminate\Http\Request;
@@ -155,6 +163,27 @@ public function show(WorkOrder $workOrder, CustomFieldService $customFields)
             'is_blocking' => (bool) ($i->issueType?->is_blocking ?? false),
         ])->values();
 
+        // Materials reconciliation (#99): the allocations pulled for this order, so
+        // the page can offer record-consumption / return / reclassify per material.
+        $workOrder->load(['allocations.material', 'allocations.lotPicks.lot']);
+        $allocations = $workOrder->allocations->map(fn ($a) => [
+            'id' => $a->id,
+            'material_id' => $a->material_id,
+            'material_code' => $a->material?->code,
+            'material_name' => $a->material?->name,
+            'unit_of_measure' => $a->material?->unit_of_measure,
+            'status' => $a->status,
+            'allocated_qty' => (float) $a->allocated_qty,
+            'consumed_qty' => (float) $a->consumed_qty,
+            'scrap_qty' => (float) $a->scrap_qty,
+            'returned_qty' => (float) $a->returned_qty,
+            'lots' => $a->lotPicks->map(fn ($p) => [
+                'lot_id' => $p->material_lot_id,
+                'lot_number' => $p->lot?->lot_number,
+                'picked_qty' => (float) $p->picked_qty,
+            ])->values(),
+        ])->values();
+
         // Change control (#182): the stop history with durations, and every change
         // request raised against this order.
         $stops = $workOrder->stops()->with(['stoppedBy:id,name', 'resumedBy:id,name'])->get()
@@ -188,6 +217,8 @@ public function show(WorkOrder $workOrder, CustomFieldService $customFields)
                 'created_at' => $cr->created_at?->toISOString(),
             ])->values();
 
+        $canReclassify = (bool) request()->user()?->hasAnyRole(['Supervisor', 'Admin']);
+
         $openStop = $workOrder->openStop();
         // An order held for a change may only resume once one has been applied — the
         // page needs to know which, so Resume can carry it.
@@ -235,11 +266,93 @@ public function show(WorkOrder $workOrder, CustomFieldService $customFields)
                 'product_type_name' => $workOrder->productType?->name,
                 'batches' => $batches,
                 'issues' => $issues,
+                'allocations' => $allocations,
             ],
+            'canReclassify' => $canReclassify,
+            'materials' => $canReclassify
+                ? Material::where('is_active', true)->orderBy('code')->get(['id', 'code', 'name'])
+                : [],
             'customFields' => $customFields->clientConfig('work_order'),
         ]);
     }
 
+    /**
+     * Materials reconciliation (#99): declare actual consumption, return unused
+     * material to stock, and reclassify a quantity to another class. Each
+     * allocation must belong to this work order.
+     */
+    public function recordConsumption(RecordConsumptionRequest $request, WorkOrder $workOrder, MaterialAllocation $allocation, MaterialAllocationService $allocations)
+    {
+        $this->assertAllocationBelongs($workOrder, $allocation);
+
+        try {
+            $allocations->recordConsumption(
+                $allocation,
+                (float) $request->validated('consumed_qty'),
+                (float) ($request->validated('scrap_qty') ?? 0),
+                $request->validated('notes'),
+            );
+
+            return back()->with('success', __('Consumption recorded'));
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function returnAllocation(ReturnAllocationRequest $request, WorkOrder $workOrder, MaterialAllocation $allocation, MaterialAllocationService $allocations)
+    {
+        $this->assertAllocationBelongs($workOrder, $allocation);
+
+        try {
+            $allocations->returnQuantity(
+                $allocation,
+                (float) $request->validated('qty'),
+                $request->user(),
+                $request->validated('reason'),
+            );
+
+            return back()->with('success', __('Material returned to stock'));
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function reclassify(ReclassifyClassRequest $request, WorkOrder $workOrder, MaterialReclassificationService $reclassifications)
+    {
+        try {
+            $source = Material::findOrFail($request->validated('source_material_id'));
+
+            // The panel always reclassifies one of this order's pulled materials —
+            // enforce that so the nested route is a real scope, not decoration.
+            if (! $workOrder->allocations()->where('material_id', $source->id)->exists()) {
+                abort(404);
+            }
+
+            $target = Material::findOrFail($request->validated('target_material_id'));
+            $lot = $request->validated('source_lot_id') ? MaterialLot::findOrFail($request->validated('source_lot_id')) : null;
+
+            $reclassifications->reclassifyClass(
+                $source,
+                $target,
+                (float) $request->validated('qty'),
+                $request->user(),
+                $lot,
+                $request->validated('reason'),
+            );
+
+            return back()->with('success', __('Material reclassified'));
+        } catch (\DomainException|\InvalidArgumentException $e) {
+            return back()->with('error', $e->getMessage());
+        }
+    }
+
+    private function assertAllocationBelongs(WorkOrder $workOrder, MaterialAllocation $allocation): void
+    {
+        if ($allocation->batch?->work_order_id !== $workOrder->id) {
+            abort(404);
+        }
+    }
+
     public function edit(WorkOrder $workOrder, CustomFieldService $customFields)
     {
         return Inertia::render('admin/work-orders/Edit', [

backend/app/Http/Requests/Api/V1/ReclassifyClassRequest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Http\Requests\Api\V1;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * Reclassify a quantity of material from one class (material) to another (#99).
+ * The route is gated to Supervisor|Admin; this request owns shape validation.
+ */
+class ReclassifyClassRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'source_material_id' => ['required', 'integer', 'exists:materials,id'],
+            'target_material_id' => ['required', 'integer', 'different:source_material_id', 'exists:materials,id'],
+            'qty' => ['required', 'numeric', 'gt:0'],
+            'source_lot_id' => ['nullable', 'integer', 'exists:material_lots,id'],
+            'reason' => ['nullable', 'string', 'max:255'],
+        ];
+    }
+}

backend/app/Http/Requests/Api/V1/ReclassifyLotStatusRequest.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Http\Requests\Api\V1;
+
+use App\Models\MaterialLot;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * Change a material lot's status (#99) — released / quarantine / rejected. The
+ * route is gated to Supervisor|Admin. A reason is required when quarantining or
+ * rejecting, so the disposition is explainable in the audit trail.
+ */
+class ReclassifyLotStatusRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'to_status' => ['required', Rule::in([
+                MaterialLot::STATUS_RELEASED,
+                MaterialLot::STATUS_QUARANTINE,
+                MaterialLot::STATUS_REJECTED,
+            ])],
+            'reason' => [
+                'nullable',
+                'string',
+                'max:255',
+                Rule::requiredIf(fn () => in_array($this->input('to_status'), [
+                    MaterialLot::STATUS_QUARANTINE,
+                    MaterialLot::STATUS_REJECTED,
+                ], true)),
+            ],
+        ];
+    }
+}