FPSMS-frontend/src/app/(main)/report/GRN_REPORT_BACKEND_SPEC.md

# GRN Report – Backend API Spec

The frontend **GRN/入倉明細報告** report calls the following endpoint. The backend must implement it to return JSON (not PDF).

## Endpoint

- **Method:** `GET`
- **Path:** `/report/grn-report`
- **Query parameters (all optional):**
  - `receiptDateStart` – date (e.g. `yyyy-MM-dd`), filter receipt date from
  - `receiptDateEnd` – date (e.g. `yyyy-MM-dd`), filter receipt date to
  - `itemCode` – string, filter by item code (partial match if desired)

## Response

- **Content-Type:** `application/json`
- **Body:** Either an array of row objects, or an object with a `rows` array:

```json
{
  "rows": [
    {
      "poCode": "PO-2025-001",
      "deliveryNoteNo": "DN-12345",
      "receiptDate": "2025-03-15",
      "itemCode": "MAT-001",
      "itemName": "Raw Material A",
      "acceptedQty": 100,
      "receivedQty": 100,
      "demandQty": 120,
      "uom": "KG",
      "purchaseUomDesc": "Kilogram",
      "stockUomDesc": "KG",
      "productLotNo": "LOT-001",
      "expiryDate": "2026-03-01",
      "supplierCode": "P06",
      "supplier": "Supplier Name",
      "status": "completed",
      "grnCode": "PPP004GRN26030298",
      "grnId": 7854617
    }
  ]
}
```

Or a direct array:

```json
[
  { "poCode": "PO-2025-001", "deliveryNoteNo": "DN-12345", ... }
]
```

## Suggested backend implementation

- Use data that “generates the GRN” (Goods Received Note): e.g. **stock-in lines** (or equivalent) linked to **PO** and **delivery note**.
- Filter by:
  - `receiptDate` (or equivalent) between `receiptDateStart` and `receiptDateEnd` when provided.
  - `itemCode` when provided.
- Return one row per GRN line with at least: **PO/delivery note no.**, **itemCode**, **itemName**, **qty** (e.g. `acceptedQty`), **uom**, and optionally receipt date, lot, expiry, supplier, status.

Frontend builds the Excel from this JSON. Columns include: PO No., Delivery Note No., Receipt Date, Item Code, Item Name, Qty, Demand Qty, UOM, Supplier Lot No. 供應商批次, Expiry Date, Supplier Code, Supplier, 入倉狀態, **GRN Code** (`m18_goods_receipt_note_log.grn_code`), **GRN Id** (`m18_record_id`).

## Frontend Excel styling (shared standard)

Header colours, number formats (`#,##0.00` for amounts), and column alignment are defined in:

**[`../chart/_components/EXCEL_EXPORT_STANDARD.md`](../chart/_components/EXCEL_EXPORT_STANDARD.md)**

Use that document when adding or changing Excel exports so formatting stays consistent.