# Procurement Engine 2.0: Release Notes & QA Testing Guide

**Branch**: `add-seat-layout-docs` → `main`  
**Module**: Procurement & Inventory Allocation Engine (`/procurement-engine`)  
**Target Audience**: QA Engineers, Testers, Frontend/Backend Developers, Release Managers  
**Date**: October 2026  

---

## 1. Executive Summary

This release delivers an end-to-end overhaul of the **Bhagirath ERP Procurement Engine**. The system transitions from a monolithic, unrouted single component into an enterprise-grade, multi-page routed procurement suite compliant with the Audi ERP Procurement Engine Specification.

### Key Milestones Achieved:
1. **Modular Multi-Page UI Architecture**: Decomposed into 8 dedicated subpages under `/procurement-engine/*` with persistent sub-navigation (`PendingCheckPage`, `BulkCheckPage`, `SingleCheckPage`, `ShortageHoldsPage`, `OpenRequestsPage`, `ConfirmedListPage`, `ConfirmedBomDetailsPage`, `BackflushListPage`).
2. **Deterministic Multi-Store Inventory Allocation (BUG-02 Fix)**: Inventory reservation now locks and exhausts all storage locations/bins in FIFO/descending order rather than locking only the first inventory record.
3. **Collapsible Chassis Breakdown & Full Space Utilization**: In Bulk Check, multi-chassis allocations are presented in full-width collapsible rows (`colSpan={10}`) beneath each Raw Material (RM), with clear badges for Body Type, Customer Segment, and individual chassis quantities.
4. **Global Shortage Sorting & Dynamic Category Tabs**: RMs with stock shortages are sorted to the top globally across all categories, and filtering is organized cleanly by BOM categories (`All Parts`, `Base BOM`, `Special Features`, `Ad-hoc`).
5. **Robust Eager Loading**: Chassis records cleanly load related dealer orders, dealer accounts, feature masters, and options without detached session or N+1 query exceptions.
6. **Zero Conflict Clean Merge**: All changes are self-contained, validated against `main`, and pass both Python AST syntax validation and Vite production bundle builds.

---

## 2. Inventory of Files Pushed to `main`

The following files constitute this release:

### A. Backend Core & Database
| File Path | Nature of Change | Conflict Risk |
|---|---|---|
| `backend/app/models/yard_models.py` | Added `model = relationship("VehicleModelMaster", lazy="select")` to `ChassisMaster` | **None** (Clean property addition) |
| `backend/app/models/dealer_models.py` | Added `dealer_order_vehicles` relationship to `VehicleModelMaster` | **None** (Clean property addition) |
| `backend/app/models/procurement_models.py` | Added `category` column to `ChassisBomSnapshot` and table metadata | **None** (Self-contained) |
| `backend/app/modules/procurement/bulk_engine_routes.py` | Standardized eager-loading using explicit model classes (`DealerOrder.dealer`, etc.) | **None** (Isolated to procurement) |
| `backend/app/modules/procurement/bulk_engine_service.py` | Enhanced bulk multi-chassis simulation, reservation, PR auto-generation, and chassis grouping | **None** (Self-contained) |
| `backend/app/modules/procurement/engine_routes.py` | Added chassis details, category fields, station filtering, and hold management routes | **None** (Self-contained) |
| `backend/app/modules/procurement/engine_service.py` | Implemented multi-row inventory locking (BUG-02), chassis BOM grouping, and snapshot categorization | **None** (Self-contained) |

### B. Alembic Migrations
| File Path | Description | Conflict Risk |
|---|---|---|
| `backend/migrations/versions/2dc76e3c9a58_restore_missing_procurement_tables.py` | Safe DDL recreation (`IF NOT EXISTS`) for `rm_purchase_request` & `rm_purchase_request_detail` | **None** (Linear migration) |
| `backend/migrations/versions/2e7a33888d03_procurement_snapshot_category_and_.py` | Adds `category` column and unique constraint `uq_chassis_bom_snapshot(chassis_id, rm_id)` | **None** (Linear migration) |

### C. Frontend Navigation & Pages
| File Path | Nature of Change | Conflict Risk |
|---|---|---|
| `frontend/src/App.jsx` | Configured routes for `/procurement-engine/*` modular subpages | **None** (Replaced single route with subroute tree) |
| `frontend/src/api/procurement.js` | Added API methods for single/bulk simulations, confirmations, holds, and BOM snapshots | **None** (Self-contained) |
| `frontend/src/pages/procurement/ProcurementEngine.jsx` | Removed monolithic legacy file in favor of modular directory | **None** (Clean replacement) |
| `frontend/src/pages/procurement/engine/EngineLayout.jsx` | Sub-navigation bar with active badges, hold counts, and unified header | **None** (New file) |
| `frontend/src/pages/procurement/engine/PendingCheckPage.jsx` | Pending grid with dealer name, order date, and expandable features | **None** (New file) |
| `frontend/src/pages/procurement/engine/BulkCheckPage.jsx` | Multi-chassis simulation matrix with category tabs, global shortage sorting, and collapsible chassis rows | **None** (New file) |
| `frontend/src/pages/procurement/engine/SingleCheckPage.jsx` | Single-chassis BOM check, inline quantity editing, custom part addition | **None** (New file) |
| `frontend/src/pages/procurement/engine/ShortageHoldsPage.jsx` | Hold registry with shortage badges, PR links, and Re-Run / Check Stock actions | **None** (New file) |
| `frontend/src/pages/procurement/engine/OpenRequestsPage.jsx` | Open Purchase Requests tracking with filter tabs and item breakdowns | **None** (New file) |
| `frontend/src/pages/procurement/engine/ConfirmedListPage.jsx` | Released/confirmed chassis registry with direct links to confirmed BOMs | **None** (New file) |
| `frontend/src/pages/procurement/engine/ConfirmedBomDetailsPage.jsx` | Immutable audit view of confirmed BOM with station tabs and reservation status | **None** (New file) |
| `frontend/src/pages/procurement/engine/BackflushListPage.jsx` | In-production chassis backflush tracking filtered by station completion | **None** (New file) |

### D. Configuration & Documentation
| File Path | Description |
|---|---|
| `.gitignore` | Ignores local database dumps, seed artifacts, and scratch test scripts |
| `docs/PROCUREMENT_ENGINE_RELEASE_NOTES.md` | Comprehensive QA testing guide and release notes (this document) |

---

## 3. Conflict Analysis & Merge Safety

1. **Direct Merge Tree Verification**: Tested via `git merge-tree origin/main HEAD`. Zero conflict markers (`<<<<<<<`) were produced.
2. **Branch Lineage**: The current branch `add-seat-layout-docs` diverged cleanly from `main`. All changes in `origin/main` are pull-request merges originating from our branch history.
3. **No Overwrite of Unrelated Modules**: Changes are strictly confined to `procurement`, `yard_models.py`, `dealer_models.py`, and `frontend/src/pages/procurement/`. Sales, Maintenance, QA, and Admin modules remain untouched.

---

## 4. Prerequisites for Other Developers

When other developers pull this branch from `main`, they must execute the following 2 steps:

### Step 1: Run Database Migrations
Run Alembic migrations to apply the missing procurement tables and snapshot schema updates:
```bash
cd backend
# With virtual environment activated:
alembic upgrade head
```
*Expected Output*: Applies revisions `2dc76e3c9a58` and `2e7a33888d03` without errors.

### Step 2: Verify Frontend Dependencies
```bash
cd frontend
npm install
npm run dev
```
```

---

## 5. QA Testing Guide & Test Scenarios

Testers should execute the following test suites to validate system functionality:

### Test Suite 1: Single Chassis Check & Reservation (`/procurement-engine/single/:chassisId`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Pending Check** &rarr; Click **"Check Stock"** on any chassis.
- **Verification Checklist**:
  1. **BOM Itemization**: Base BOM items and special feature items appear with RM Code, RM Name, Station Name, Unit of Measure, Current Available Stock, and Required Qty.
  2. **Shortage Detection**: If `Required Qty > Available Stock`, the row displays a red badge with the shortage amount.
  3. **Editable Quantities**: Change a required quantity in the input box. Ensure the total shortage updates immediately.
  4. **Add Part**: Click **"+ Add Part"**, enter RM ID, Category, and Qty. Verify it appends to the table.
  5. **Confirm Reservation**:
     - *If Stock Available*: Status transitions to `CONFIRMED`. Chassis moves to Confirmed list.
     - *If Shortage Exists*: System places chassis on `SHORTAGE_HOLD`, generates a Purchase Request (`PR-...`), and redirects to Shortage Holds.

### Test Suite 2: Bulk Check & Multi-Chassis Allocation (`/procurement-engine/bulk`)
- **Navigation**: In **Pending Check**, select 2 or more chassis checkboxes &rarr; Click **"Check Stock (N)"**.
- **Verification Checklist**:
  1. **Category Tabs**: Verify the four tabs at top: `All Parts`, `Base BOM`, `Special Features`, `Ad-hoc`.
  2. **Global Shortage Prioritization**: Items with shortages appear at the top of the table regardless of tab.
  3. **Collapsible Chassis Breakdown**:
     - Under each RM row, click **"Show Chassis (N)"** / arrow toggle.
     - Verify a full-width row expands spanning all 10 columns.
     - Verify chips show: Chassis Number, Body Type, Segment, and Required Qty for that chassis.
     - Verify toggling closes the row smoothly.
  4. **Table Column Fit**: Verify RM Name wraps naturally and all columns (including Shortage and Pending PO) remain visible without excessive horizontal scrolling.
  5. **Bulk Confirmation**: Click **"Confirm & Reserve"**. Verify all selected chassis are processed atomically.

### Test Suite 3: Pending Check Grid (`/procurement-engine/pending`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Pending Check**.
- **Verification Checklist**:
  1. **Chassis Information**: Displays Chassis No, Model Name, Dealer Name, and Order Date.
  2. **Feature Drawer/Expander**: Click the chevron on a chassis row to expand custom features and options chosen on the dealer order.
  3. **Batch Selection**: Select All checkbox selects all chassis. Selection counter reflects accurately.

### Test Suite 4: Shortage Holds Management (`/procurement-engine/holds`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Shortage Holds**.
- **Verification Checklist**:
  1. **Hold Badge**: Holds tab in header displays active count badge in orange.
  2. **Hold Details**: Grid shows Chassis No, Model, Shortage RMs, Reason, and Associated Purchase Request Number.
  3. **Check Stock / Re-Run**: Click **"Check Stock"** to re-simulate against newly received GRN inventory.

### Test Suite 5: Open Purchase Requests (`/procurement-engine/requests`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Open Requests**.
- **Verification Checklist**:
  1. Displays all auto-indented PRs generated by the Procurement Engine.
  2. View PR Number (`PR-BULK-...`), Vendor, Request Date, and affected chassis UUIDs.
  3. Expand PR row to verify specific raw materials and shortage quantities indented.

### Test Suite 6: Confirmed BOM Details (`/procurement-engine/confirmed/:chassisId`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Confirmed List** &rarr; Click **"View BOM"**.
- **Verification Checklist**:
  1. Displays immutable snapshot of reserved parts.
  2. Station tabs allow filtering by Assembly Line stations in numerical sequence.
  3. Total reserved quantities match production requirements.

### Test Suite 7: Backflush Review (`/procurement-engine/backflush`)
- **Navigation**: Go to **Purchasing > Procurement Engine > Backflush Review**.
- **Verification Checklist**:
  1. Displays chassis currently progressing on the shop floor (`IN_PRODUCTION`).
  2. Shows current active station, completed stations, and consumed raw materials.

---

## 6. Technical Architecture & Endpoints Reference

### API Endpoints
| HTTP Method | Route | Description |
|---|---|---|
| `GET` | `/api/procurement/bulk-engine/pending-chassis` | Fetches pending chassis with dealer, order date, and features eager-loaded |
| `POST` | `/api/procurement/bulk-engine/simulate` | Simulates multi-chassis inventory allocation and detects shortages |
| `POST` | `/api/procurement/bulk-engine/run` | Executes atomic reservation and creates auto-indented Purchase Requests |
| `GET` | `/api/procurement/engine/single-simulate/:chassis_id` | Simulates single chassis BOM against aggregated inventory |
| `POST` | `/api/procurement/engine/single-confirm/:chassis_id` | Confirms single chassis reservation with multi-row store locking |
| `GET` | `/api/procurement/engine/chassis-bom/:chassis_id` | Fetches confirmed snapshot BOM grouped by station and category |
| `GET` | `/api/procurement/engine/shortage-holds` | Lists chassis currently held due to stock shortages |
| `GET` | `/api/procurement/engine/open-requests` | Lists open purchase requests generated by engine indents |
| `GET` | `/api/procurement/engine/confirmed-chassis` | Lists confirmed chassis released to production |
| `GET` | `/api/procurement/engine/backflush-candidates` | Lists in-production chassis for backflush material consumption |

---

## 7. Sign-off Checklist for Merge

- [x] All test/debug/diagnostic scripts and local seed dumps excluded from git commits.
- [x] Python backend files compiled with 0 syntax errors.
- [x] Frontend production build compiled with 0 errors via Vite.
- [x] `git merge-tree` verified 0 merge conflicts against `origin/main`.