Merge branch 'feat/purchase-order'

PurchaseOrder entity: Prisma model+migration, Zod+CRUD (P2003 on both
vendorId/receivedById, receivedAt/receivedById co-nullability
refine), API routes, tests. Verified green by test-runner (127/127
tests, tsc/lint/build clean) before merge.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

CLAUDE.md

@@ -113,10 +113,15 @@ Với mỗi mục tiêu nghiệp vụ stakeholder đưa ra (vd "thêm tracking s
 - Rà lại advisory riêng của `next` (prod dependency, có vài high/moderate — vd SSRF qua WebSocket upgrade, middleware bypass) khi có dịp, tách biệt khỏi đợt retrofit Prisma/Zod này.
 - Test coverage gaps (chưa block gì, chỉ là follow-up): chưa test malformed JSON body, chưa test JSON body không phải object (array/string).
 - `Button` (shadcn) không `forwardRef`, React đang pin 18 — dormant risk, xem note ở "Trạng thái hiện tại".
-- Các entity còn lại: `PurchaseOrder`, `Receipt`, `Assignment` (`AssetItem` xong 2026-07-31, `License` xong 2026-08-02, xem "Trạng thái hiện tại"). `Assignment` là entity tiếp theo nên làm — nối `Employee`+`AssetItem`+`License`, trả lời trực tiếp câu hỏi nghiệp vụ "ai đang giữ máy/license nào" nêu ở `docs/asset-license-management.md`.
+- **`Vendor`/`PurchaseOrder`(gộp `Receipt`)/`Assignment`/`AssetCategoryAttributeDef` (2026-08-02): spec đầy đủ ở `docs/asset-license-management.md`, đã có task list phụ thuộc-đúng do `pm`-pass sequencing (2026-08-02), sẵn sàng giao `feature-implementer` theo đúng thứ tự dưới đây (3 lane độc lập, có thể xen kẽ):**
+  - **Lane A (Vendor → License.vendorId → PurchaseOrder → purchaseOrderId x3)**: (1-4) `Vendor` entity chuẩn 4 commit (model+migration/lib/API/test), không phụ thuộc gì. (5) Retrofit `License.vendor` (string) → `License.vendorId` (FK) — **1 commit gộp** (schema+migration+lib+test), theo đúng tiền lệ retrofit `Request.employeeId` (commit `49d96b7`, không tách lớp như entity mới vì tách ra sẽ để lại state nửa vời không chạy được) — tiện thể fix luôn finding cũ của `code-reviewer`: `createLicense()` chưa theo pattern `{ok,value}|{ok,error}`, giờ **bắt buộc** phải thêm vì `vendorId` là FK mới (cần bắt `P2003`). Phụ thuộc (1). (6-9) `PurchaseOrder` entity chuẩn 4 commit (`vendorId` FK, `receivedBy` FK→`Employee`, Zod `.refine()` cho ràng buộc `receivedAt`/`receivedBy` cùng null hoặc cùng có giá trị, bắt `P2003` cho cả 2 FK, theo đúng pattern `{ok,error}` ngay từ đầu) — phụ thuộc (1) `Vendor` + `Employee` (đã có). (10) `AssetItem.purchaseOrderId` — 1 commit gộp (nullable FK). (11) `License.purchaseOrderId` — 1 commit gộp **riêng** với task (5) dù cùng file, vì trigger phụ thuộc khác nhau (`Vendor` vs `PurchaseOrder`) — gộp chung sẽ vi phạm nguyên tắc 1-commit-1-thay-đổi-nghiệp-vụ. (12) `Request.purchaseOrderId` — 1 commit gộp. (10)(11)(12) đều chỉ phụ thuộc (6), độc lập lẫn nhau, thứ tự giữa 3 task này không quan trọng.
+  - **Lane B (AssetCategory → AssetCategoryAttributeDef + AssetModel → wire dynamic validation → AssetItem.modelId)**: **gap phát hiện khi sequencing** — `AssetCategory`/`AssetModel`/`ConsumableItem` đã có spec từ round BA trước (2026-08-02, xem "Phân loại tài sản" trong doc) nhưng **CHƯA build** (không có trong `prisma/schema.prisma` hiện tại, `AssetItem.model` vẫn là string tự do) — phải làm trước thì `AssetCategoryAttributeDef` mới có ý nghĩa. (13-16) `AssetCategory` entity chuẩn 4 commit (`name`, `valueGroup` enum `high_value`/`low_value`), không phụ thuộc gì. (17-20) `AssetCategoryAttributeDef` entity chuẩn 4 commit (`categoryId` FK, `key`, `label`, `dataType` enum, `required`, `sortOrder`, unique `(categoryId,key)` → bắt `P2002`) — phụ thuộc (13), độc lập với `AssetModel`. (21-24) `AssetModel` entity chuẩn 4 commit (`categoryId` FK + business rule "category phải `valueGroup=high_value`" — cần lookup DB, không phải Zod thuần; `manufacturer`, `name`, `specs` JSONB — ở task này `specs` chỉ validate lỏng là object hợp lệ, CHƯA khớp động theo `AssetCategoryAttributeDef`) — phụ thuộc (13), độc lập với (17-20). (25) Wire dynamic specs validation vào `AssetModel` create/update — **1 commit riêng**, không gộp vào (22), vì đây là logic mới/rủi ro (build Zod schema runtime từ `AssetCategoryAttributeDef`, map `dataType`→`z.string()/number()/boolean()/coerce.date()`, từ chối key lạ, bắt buộc key `required`) — phụ thuộc (18) và (22). (26) Retrofit `AssetItem.model` (string) → `AssetItem.modelId` (FK) — 1 commit gộp, phụ thuộc (21) (không cần đợi (25)).
+  - **Lane C (`Assignment`, độc lập hoàn toàn với Lane A/B — chỉ cần `Employee`+`AssetItem`+`License` đã có sẵn)**: (27) model+migration (`employeeId` FK, `assetItemId`/`licenseId` nullable FK, `assignedAt`, `returnedAt` nullable, `signedAt` nullable). (28) lib validation+CRUD — rủi ro nhất trong cả 4 entity: Zod `.refine()` XOR `assetItemId`/`licenseId`, chặn >1 `Assignment` active/`AssetItem`, transaction tăng/giảm `License.seatsUsed` kèm chặn overbook (`seatsUsed >= seatsTotal`), đồng bộ `AssetItem.status` (assigned/in_stock), helper transfer (đóng cũ+mở mới cùng 1 transaction). (29) API routes — **cần quyết định shape mới**: đây là entity đầu tiên cần thao tác "update" (return/transfer) trong khi codebase hiện tại **mọi entity đều chỉ có POST(create)+GET(list), chưa có route update nào** — đề xuất mặc định `POST /api/assignments` (assign/transfer) + `PATCH /api/assignments/[id]` (return, nhận `{returnedAt}}`), cần xác nhận lại khi giao task cho `pm`/`feature-implementer` vì không có tiền lệ. (30) tests. **(31) Bắt buộc code-reviewer pass riêng cho Assignment (diff 27-30) trước khi coi là xong** — đúng rule ở "Multi-agent dev workflow" (state-mutation-với-invariant, seat-count) — không phải 1 commit, là 1 gate.
+  - **2 câu hỏi mở đã được stakeholder trả lời (2026-08-02, xem "Assignment" trong `docs/asset-license-management.md`) — Lane C hết bị chặn**: (a) `createAssignment()` **chặn** nếu `AssetItem.status` khác `in_stock` (400). (b) Route update dùng `PATCH /api/<entity>/[id]` (áp dụng cho cả `Assignment` và `PurchaseOrder`), không dùng action-based sub-route.
+  - `ConsumableItem` (phần catalog, KHÔNG phải luồng "xin+nhận" — luồng đó vẫn BỊ CHẶN chờ 7 câu hỏi mở, xem doc): độc lập với toàn bộ 3 lane trên (chỉ cần `AssetCategory`), sẵn sàng cho `pm` chia task riêng nếu stakeholder muốn gộp vào cùng đợt — không đưa vào sequencing này vì nằm ngoài phạm vi 4 việc được giao lần này.
 - Các state tiếp theo của Request: Pending Approval → Approved → Ordered → Received → Delivered → Closed, và nhánh Rejected/Cancelled
 - UI (hiện chỉ có placeholder home page)
 - Auth/phân quyền (ai được approve request, ai được xác nhận nhận hàng/bàn giao)
 
 ---
-Cập nhật lần cuối: 2026-08-02 (deploy lên homelab ubi.toanhoang.work, License entity)
+Cập nhật lần cuối: 2026-08-02 (deploy lên homelab ubi.toanhoang.work, License entity, task sequencing cho Vendor/PurchaseOrder/Assignment/AssetCategoryAttributeDef)

docs/asset-license-management.md

@@ -23,14 +23,17 @@ Theo dõi toàn bộ vòng đời tài sản/license: **Request → Approval →
 | Entity | Ý nghĩa |
 |---|---|
 | `Employee` | id, tên, phòng ban, manager |
-| `Vendor` | nhà cung cấp |
+| `Vendor` | id, `name`, `contactEmail`, `contactPhone`, `address`, `taxCode` (nullable — mã số thuế VN), `notes` (nullable) — nhà cung cấp/reseller mua hàng qua, **khác** `AssetModel.manufacturer` (hãng sản xuất/OEM). Xem "Vendor" bên dưới |
-| `AssetItem` | hardware — serial number, model, ngày mua, bảo hành, trạng thái (in stock / assigned / repair / retired) |
+| `AssetItem` | hardware **high-value** (serial hóa bắt buộc) — serial number, model (FK → `AssetModel`, bắt buộc — không còn string tự do), ngày mua, bảo hành, trạng thái (in stock / assigned / repair / retired), `purchaseOrderId` (FK → `PurchaseOrder`, nullable — chiều cung, xem "PurchaseOrder" bên dưới). Category không còn gán trực tiếp trên `AssetItem` — suy ra qua `AssetModel.categoryId`. Xem "Phân loại tài sản" bên dưới |
-| `License` | phần mềm — tên, vendor, tổng seat, seat đã dùng, ngày hết hạn, loại (perpetual/subscription) |
+| `License` | phần mềm — tên, `vendorId` (FK → `Vendor`, retrofit từ string tự do — xem "Vendor" bên dưới), tổng seat, seat đã dùng, ngày hết hạn, loại (perpetual/subscription), `purchaseOrderId` (FK → `PurchaseOrder`, nullable — chiều cung, xem "PurchaseOrder" bên dưới) |
-| `Request` | người yêu cầu, loại (asset/license), lý do, trạng thái |
+| `Request` | người yêu cầu, loại (asset/license), lý do, trạng thái, `purchaseOrderId` (FK → `PurchaseOrder`, nullable — chiều cầu, xem "PurchaseOrder" bên dưới) — **chỉ áp dụng cho asset high-value/license**, không dùng cho consumable (xem "Phân loại tài sản" bên dưới) |
-| `PurchaseOrder` | gộp nhiều Request đã duyệt, vendor, ngày đặt, ngày dự kiến nhận |
+| `PurchaseOrder` | id, `vendorId` (FK → `Vendor`), `orderDate`, `expectedDate`, `receivedAt` (nullable — null nghĩa là chưa nhận), `receivedBy` (FK → `Employee`, nullable, set cùng lúc với `receivedAt`). **Gộp luôn `Receipt`** (không còn là entity riêng — nhận hàng là 1 phần trạng thái của chính PO), all-or-nothing theo cả PO (không nhận từng phần), không track giá/chi phí, không có `status` riêng (suy ra từ Request liên kết). Xem "PurchaseOrder" bên dưới |
-| `Receipt` | nhận hàng — đối chiếu PO, ngày nhận, người nhận |
+| `Assignment` | id, `employeeId` (FK → `Employee`), `assetItemId` (FK → `AssetItem`, nullable) / `licenseId` (FK → `License`, nullable — đúng 1 trong 2, XOR), `assignedAt`, `returnedAt` (nullable — null nghĩa đang giữ), `signedAt` (nullable — chỉ là timestamp đánh dấu đã ký, không upload file). Gán AssetItem (high-value)/License cho 1 Employee cụ thể. **Không áp dụng cho consumable** (consumable track theo tồn kho, không gắn 1 người cụ thể). Xem "Assignment" bên dưới |
-| `Assignment` | gán AssetItem/License cho Employee — ngày giao, ngày trả, biên bản ký nhận |
 | `Request.servicenow_ticket` | field text, nhập tay số ticket ServiceNow liên quan (không tích hợp API ServiceNow ngay — volume thấp, nhập tay đủ dùng; để ngỏ cho auto-sync sau nếu cần) |
+| `AssetCategory` | id, tên (vd "Laptop", "Cáp HDMI"), nhóm giá trị cố định (`high_value` \| `low_value`) — danh mục category cụ thể do IT admin tự định nghĩa, không hardcode. Xem "Phân loại tài sản" bên dưới |
+| `AssetModel` | id, category (FK → `AssetCategory`, bắt buộc, phải thuộc nhóm `high_value`), `manufacturer` (vd "Dell"), `name` (vd "Latitude 5420"), `specs` (JSONB — giá trị thật của các thuộc tính động, xem `AssetCategoryAttributeDef`) — tách riêng 2 field `manufacturer`/`name`, không gộp chung 1 string, để filter/report theo hãng. Nằm giữa `AssetCategory` và `AssetItem` (1 model có nhiều `AssetItem` serial khác nhau). Xem "Phân loại tài sản" bên dưới |
+| `AssetCategoryAttributeDef` | id, `categoryId` (FK → `AssetCategory`), `key` (slug, vd `ram_gb`), `label` (tên hiển thị, vd "RAM (GB)"), `dataType` (enum đóng: `string`/`number`/`boolean`/`date`), `required` (bool), `sortOrder` (int) — định nghĩa thuộc tính riêng theo từng category, giá trị thật nằm ở `AssetModel.specs`. Unique `(categoryId, key)`. Xem "Phân loại tài sản" bên dưới |
+| `ConsumableItem` | phụ kiện **low-value/consumable** — tên, category (bắt buộc, phải thuộc nhóm `low_value`, trỏ thẳng `AssetCategory` — **không** qua `AssetModel`, khái niệm "model" chỉ áp dụng cho asset serial hóa), số lượng tồn kho (`quantityOnHand`). **KHÔNG serial hóa, KHÔNG gắn Assignment cá nhân** — chỉ track theo số lượng. Xem "Phân loại tài sản" bên dưới |
 
 ## Luồng trạng thái Request
 
@@ -40,6 +43,79 @@ Draft → Pending Approval → Approved → Ordered → Received → Delivered
              Rejected / Cancelled
 ```
 
+## Phân loại tài sản: High-value vs Low-value/Consumable (chốt 2026-08-02)
+
+**Quyết định đã chốt với stakeholder:** tài sản được phân nhóm theo **category cố định**, KHÔNG theo ngưỡng giá tiền. Mỗi `AssetCategory` thuộc đúng 1 trong 2 nhóm giá trị (`high_value` hoặc `low_value`), category cụ thể do IT admin tự định nghĩa/mở rộng — danh sách dưới đây chỉ là **ví dụ minh hoạ, không phải danh sách đóng**:
+
+- Nhóm `high_value` → đi qua luồng `AssetItem` hiện có nguyên vẹn (serial hóa bắt buộc, track cá nhân qua `Assignment`, đi qua state machine đầy đủ của `Request`). Ví dụ category: Laptop, Màn hình, Máy in, Điện thoại công ty.
+- Nhóm `low_value` (consumable) → entity mới `ConsumableItem`, **không serial hóa**, chỉ track theo số lượng tồn kho (`quantityOnHand`), **không gắn `Assignment`** cho 1 người cụ thể. Ví dụ category: Cáp (HDMI/USB-C/LAN), Chuột, Bàn phím, Túi đựng laptop, Sạc dự phòng.
+
+**Cập nhật 2026-08-02 (2): thêm phân cấp `AssetModel` giữa `AssetCategory` và `AssetItem`.** Lý do: nhiều model khác nhau trong cùng 1 category (vd category "Laptop" có nhiều model "Dell Latitude 5420", "MacBook Pro 14"...), cần report/thống kê theo model (vd "đang có bao nhiêu Dell Latitude 5420"), tránh lỗi gõ tay khi model là string tự do như trước. Phân cấp: `AssetCategory` ("Laptop") → `AssetModel` ("Dell Latitude 5420") → từng `AssetItem` (1 serial cụ thể thuộc model đó). `AssetModel.manufacturer`/`AssetModel.name` tách riêng (không gộp 1 string) để filter/report riêng theo hãng. Khái niệm "model" chỉ có ý nghĩa cho asset serial hóa (`high_value`) — `ConsumableItem` không có model, vẫn trỏ thẳng `AssetCategory` (`low_value`) như cũ.
+
+**Cập nhật 2026-08-02 (3): thêm `AssetCategoryAttributeDef` — thuộc tính đặc thù theo từng category.** Lý do: từng category có bộ thuộc tính riêng cần track (vd RAM/CPU cho category "Laptop", độ phân giải cho "Màn hình") mà không phải asset high-value nào cũng giống nhau — cần định nghĩa động theo category, không hardcode cột cứng cho từng loại thuộc tính.
+
+- Entity mới `AssetCategoryAttributeDef`: `categoryId` (FK → `AssetCategory`), `key` (slug, vd `ram_gb`), `label` (tên hiển thị, vd "RAM (GB)"), `dataType` (enum đóng: `string`/`number`/`boolean`/`date` — đây là tập giá trị kỹ thuật cố định do dev định nghĩa, **khác** với `AssetCategory` là tập mở IT admin tự mở rộng), `required` (bool), `sortOrder` (int, thứ tự hiển thị trên form). Unique `(categoryId, key)`.
+- Mỗi `AssetCategory` có bộ attribute **riêng, độc lập** — cố tình **không** phải thư viện thuộc tính dùng chung giữa các category. Nếu 2 category cùng muốn 1 thuộc tính kiểu "khối lượng (kg)", mỗi category tự tạo 1 row `AssetCategoryAttributeDef` riêng — trùng tên `key` giữa 2 category là bình thường và được chấp nhận, đây là 2 row không liên quan tới nhau. Lý do: ở quy mô hiện tại (ít category), thiết kế thư viện thuộc tính dùng chung (tách riêng bảng `AttributeDef` + bảng join `CategoryAttribute`) cộng thêm độ phức tạp thật (thêm 1 bảng, UX phải chọn "gắn thuộc tính có sẵn hay tạo mới", sửa 1 def ảnh hưởng dây chuyền nhiều category) để đổi lấy lợi ích (sửa 1 chỗ áp dụng khắp nơi, query cross-category an toàn) mà hiện chưa cần tới — stakeholder đã từ chối rõ ràng thiết kế dùng chung để giữ đơn giản.
+- Giá trị thật nằm ở `AssetModel.specs` (cột JSONB) — **không** nằm trên `AssetItem`, vì đây là thuộc tính theo spec-sheet dùng chung cho mọi serial thuộc cùng 1 model (mọi `AssetItem` "Dell Latitude 5420" đều cùng RAM), không phải dữ liệu riêng theo từng instance. Validate động lúc ghi: app build Zod schema runtime từ các `AssetCategoryAttributeDef` thuộc category của model đó (map `dataType` → `z.string()`/`z.number()`/`z.boolean()`/`z.coerce.date()`), từ chối key lạ chưa được định nghĩa cho category, bắt buộc các key có `required = true` phải có mặt.
+- Known gap chấp nhận được, chưa chặn: nếu admin sửa/xoá 1 `AssetCategoryAttributeDef` sau khi đã có `AssetModel` mang giá trị dưới key đó trong `specs`, giá trị cũ trở thành orphaned/stale — chưa có cơ chế migration/cleanup. Ghi nhận là known gap để xử lý khi có UI quản lý attribute-def thật, không cần giải quyết ngay bây giờ.
+
+**Ràng buộc dữ liệu:**
+- `AssetModel.categoryId` bắt buộc, phải trỏ tới 1 `AssetCategory` có `valueGroup = high_value`.
+- `AssetItem.modelId` bắt buộc, phải trỏ tới 1 `AssetModel` có thật (thay cho field `model` string tự do trước đây — đã đổi, không cần chiến lược backfill vì DB chưa có `AssetItem` thật). `AssetItem` không còn giữ `categoryId` trực tiếp — category được suy ra qua `AssetItem.modelId → AssetModel.categoryId` (tránh 2 nguồn sự thật có thể lệch nhau).
+- `ConsumableItem.categoryId` bắt buộc, phải trỏ tới 1 `AssetCategory` có `valueGroup = low_value` — trỏ thẳng, không qua `AssetModel`.
+- `Request` (state machine đầy đủ) tiếp tục chỉ áp dụng cho `type: asset|license` như hiện tại — **không** mở rộng `RequestType` thêm `consumable`.
+- `AssetCategoryAttributeDef.categoryId` bắt buộc, phải trỏ tới 1 `AssetCategory` có thật. Unique `(categoryId, key)`.
+- `AssetModel.specs` (JSONB) chỉ được chứa các key đã có `AssetCategoryAttributeDef` tương ứng với category của model đó — validate ở tầng Zod (build động lúc runtime), không phải DB CHECK constraint (nhất quán với nguyên tắc "không raw SQL cho app logic" của codebase).
+
+**Luồng riêng cho consumable ("xin + nhận" đơn giản hoá):** stakeholder đã xác nhận muốn 1 luồng gọn hơn state machine đầy đủ của `Request`, nhưng **chưa chốt chi tiết state/approval/xử lý hết hàng** — xem danh sách câu hỏi mở trong spec BA (2026-08-02, lưu ở lịch sử trao đổi/PR liên quan). Không build luồng này (entity `ConsumableRequest` hoặc tương đương) tới khi có câu trả lời — chỉ mới build phần catalog (`AssetCategory`, `ConsumableItem`).
+
+## Vendor (chốt 2026-08-02)
+
+Entity mới, độc lập với `AssetModel`.
+
+- Field: `id`, `name`, `contactEmail`, `contactPhone`, `address`, `taxCode` (nullable — mã số thuế VN), `notes` (nullable).
+- **Phân biệt quan trọng:** `Vendor` (nơi mua hàng — vd nhà phân phối/reseller VN) là khái niệm **khác** `AssetModel.manufacturer` (hãng sản xuất/OEM, vd "Dell") — không phải lúc nào cũng cùng 1 công ty (vd mua laptop Dell qua reseller "FPT Trading", không mua thẳng từ Dell). Quyết định: giữ nguyên `AssetModel.manufacturer` là string tự do như hiện tại (không đổi gì); `Vendor` chỉ dùng cho quan hệ mua sắm (`PurchaseOrder`, `License`).
+- **Retrofit `License.vendor`** (hiện là string tự do) → **`License.vendorId`** (FK → `Vendor`), theo đúng tiền lệ đã có trong codebase (`Request.employeeId` string→FK khi `Employee` ra đời, `AssetItem.model` string→FK khi `AssetModel` ra đời — xem "Trạng thái hiện tại" ở `../CLAUDE.md`). Chưa có `License` thật nào trong DB production nên đây là đổi kiểu cột thuần tuý, **không cần chiến lược backfill** — giống các retrofit trước đó.
+
+**Ràng buộc dữ liệu:**
+- `License.vendorId` bắt buộc, phải trỏ tới 1 `Vendor` có thật (thay cho field `vendor` string tự do trước đây).
+
+## PurchaseOrder (gộp Receipt) (chốt 2026-08-02)
+
+**Quyết định: gộp `Receipt` vào `PurchaseOrder`, không giữ là entity riêng nữa** — nhận hàng chỉ là 1 phần trạng thái của chính PO đó (`receivedAt`/`receivedBy`), không cần 1 bảng riêng để đối chiếu. Row `Receipt` trong bảng Data model ở trên đã được xoá, gộp vào row `PurchaseOrder`.
+
+- Field: `id`, `vendorId` (FK → `Vendor`), `orderDate`, `expectedDate`, `receivedAt` (nullable DateTime — null nghĩa là chưa nhận), `receivedBy` (nullable FK → `Employee`, set cùng lúc với `receivedAt`).
+- Cố tình **không** có field giá/chi phí — stakeholder nói rõ `PurchaseOrder` không cần track tiền, chỉ cần trả lời "asset/license nào thuộc PO nào".
+- Cố tình **không** có field `PurchaseOrder.status` riêng — trạng thái suy ra từ trạng thái của các `Request` liên kết (`Request` đã có state machine `Ordered → Received → Delivered` riêng), tránh 2 nguồn sự thật.
+- **Nhận hàng là all-or-nothing theo từng PO** ("nhận 1 lần đủ cho cả PO") — không hỗ trợ nhận nhiều đợt/từng phần. Đây là đánh đổi đơn giản hoá **có chủ ý**, stakeholder đã biết rõ và chấp nhận có thể cần đổi lại sau (paraphrase: "giờ làm đơn giản vậy trước, sau này cần đổi thì tính tiếp") — ghi lại rõ đây là tradeoff/assumption đã note, không phải bỏ sót khi viết spec.
+- **Traceability** (đúng yêu cầu cốt lõi của stakeholder: "chỉ cần biết asset nằm trong PO nào"): thêm `purchaseOrderId` (nullable FK → `PurchaseOrder`) ở **CẢ BA** chỗ — `AssetItem`, `License`, và `Request`. Ba field này phục vụ mục đích khác nhau, không dư thừa:
+  - `Request.purchaseOrderId` — chiều cầu (demand-side): request nào đã duyệt được gộp vào PO này (đây vốn là mục đích ban đầu đã note trong doc cho `PurchaseOrder`: "gộp nhiều Request đã duyệt").
+  - `AssetItem.purchaseOrderId` và `License.purchaseOrderId` — chiều cung (supply-side): record tồn kho/thực tế nào tới qua PO này. Set lúc intake/tạo mới. Nullable vì không phải `AssetItem`/`License` nào cũng đi qua 1 PO chính thức (vd tồn kho lịch sử nhập trước khi có hệ thống).
+
+**Ràng buộc dữ liệu:**
+- `PurchaseOrder.vendorId` bắt buộc, trỏ tới 1 `Vendor` có thật.
+- `PurchaseOrder.receivedBy` chỉ set cùng lúc với `receivedAt` (cả hai cùng null hoặc cùng có giá trị).
+- `AssetItem.purchaseOrderId`, `License.purchaseOrderId`, `Request.purchaseOrderId` đều nullable, trỏ tới `PurchaseOrder` nếu có.
+- `PurchaseOrder` không có field `status` — suy ra qua `Request` liên kết, không lưu trùng.
+
+## Assignment (chốt 2026-08-02)
+
+- Field: `id`, `employeeId` (FK → `Employee`), `assetItemId` (FK → `AssetItem`, nullable), `licenseId` (FK → `License`, nullable), `assignedAt`, `returnedAt` (nullable — null nghĩa đang giữ), `signedAt` (nullable DateTime — null nghĩa biên bản chưa ký. Cố tình chỉ là 1 timestamp đánh dấu đã ký/chưa, **KHÔNG** phải upload file — stakeholder đã quyết định rõ không cần lưu file scan lúc này, "biên bản ký nhận" chỉ cần đánh dấu đã ký + ngày ký).
+- Đúng 1 trong 2 (`assetItemId`/`licenseId`) phải được set — không cả hai, không cả hai đều rỗng (XOR) — validate ở tầng Zod qua `.refine()`, theo đúng cách codebase đã xử lý validate cross-field (không phải DB CHECK constraint, đúng nguyên tắc "không raw SQL cho app logic" — Prisma schema cũng không diễn tả được constraint XOR này natively).
+- Không phải entity mới, nhưng có các business rule tầng application cần note lại rõ ở đây (đủ quan trọng để phát sinh bug nếu bỏ sót, nhưng là rule app phải tự enforce, không phải bản thân là 1 entity):
+  - 1 `AssetItem` chỉ có tối đa 1 `Assignment` **active** (`returnedAt IS NULL`) tại 1 thời điểm — không thể bị giữ bởi 2 người cùng lúc. Enforce trước khi tạo `Assignment` mới.
+  - Assign 1 `License` phải **tăng** `License.seatsUsed`, và phải **bị từ chối** nếu `seatsUsed >= seatsTotal` (không overbook). Trả lại (set `returnedAt`) **giảm** `seatsUsed`. Toàn bộ phải chạy trong 1 transaction — đây chính là rủi ro seat-count race condition mà `code-reviewer` đã note trước đó cho `License` (xem "Trạng thái hiện tại" ở `../CLAUDE.md`, mục `License`) — `Assignment` là chỗ thực sự implement/exercise seat counting lần đầu tiên.
+  - Chuyển tài sản giữa nhân viên (case đặc biệt đã note ở trên: "Tài sản luân chuyển giữa phòng ban / chi nhánh") = đóng `Assignment` cũ (`returnedAt = now`) + tạo `Assignment` mới, cả hai trong 1 transaction. Không cần entity "Transfer" riêng.
+  - `AssetItem.status` phải đồng bộ theo trạng thái `Assignment`: tạo `Assignment` → status `assigned`; trả lại → status `in_stock`, trừ nhánh RMA/sửa chữa đã note ở "Case đặc biệt cần xử lý" (đó là case riêng, không đi qua path trả-lại-thông-thường này).
+  - **Chốt 2026-08-02 (trả lời 2 câu hỏi mở của `pm`):** (a) `createAssignment()` phải **chặn** nếu `AssetItem.status` hiện tại khác `in_stock` (vd không cho assign 1 item đang `repair`/`retired`) — trả lỗi 400, không chỉ dựa vào điều kiện "chưa có Assignment active nào". (b) Route "update" (trả lại/chuyển giao `Assignment`, nhận hàng `PurchaseOrder`) dùng `PATCH /api/<entity>/[id]` — tiền lệ REST-shape đầu tiên cho update trong codebase, áp dụng thống nhất cho cả `Assignment` và `PurchaseOrder`, không dùng action-based sub-route.
+
+**Ràng buộc dữ liệu:**
+- `Assignment.employeeId` bắt buộc, trỏ tới 1 `Employee` có thật.
+- Đúng 1 trong `assetItemId`/`licenseId` được set (XOR) — validate Zod `.refine()`.
+- Không được có > 1 `Assignment` active cho cùng 1 `AssetItem` tại 1 thời điểm (enforce ở tầng application, không phải DB constraint).
+- Tạo `Assignment` bị chặn nếu `AssetItem.status` khác `in_stock` (400).
+- `License.seatsUsed` tăng/giảm đồng bộ trong 1 transaction khi assign/return; assign bị chặn nếu `seatsUsed >= seatsTotal`.
+
 ## Module tương lai: Rack/Slot management + IoT (chưa build, chỉ note kiến trúc)
 
 Mục tiêu xa hơn: biết chính xác asset nằm ở ô/slot nào trên tủ rack, và hướng dẫn người lấy đúng ô bằng đèn (pick-to-light).
@@ -93,7 +169,8 @@ QR gán asset vào slot (bước 1, thủ công hàng ngày) **không phải IoT
 ## Việc còn dở
 
 - Thiết kế ERD chi tiết + wireframe màn hình
-- Entity còn lại: `PurchaseOrder`, `Receipt`, `Assignment` (`Employee`, `AssetItem` đã xong 2026-07-31; `License` xong 2026-08-02, xem `../CLAUDE.md`)
+- **`Vendor`, `PurchaseOrder` (gộp `Receipt`), `Assignment`, `AssetCategoryAttributeDef` (2026-08-02): đã có spec đầy đủ (BA), sẵn sàng cho `pm` chia task** — xem các mục "Vendor", "PurchaseOrder (gộp Receipt)", "Assignment" và "Cập nhật 2026-08-02 (3)" trong "Phân loại tài sản" ở trên. Bao gồm cả retrofit `License.vendor` (string) → `License.vendorId` (FK → `Vendor`, không cần backfill vì chưa có `License` thật trong DB) và thêm `purchaseOrderId` (nullable FK) vào `AssetItem`/`License`/`Request`. Thứ tự phụ thuộc gợi ý cho `pm`: `Vendor` → retrofit `License.vendorId` → `PurchaseOrder` (+ `purchaseOrderId` trên 3 entity) → `Assignment`; `AssetCategoryAttributeDef` độc lập, có thể làm song song.
+- Consumable (2026-08-02): phần phân loại (`AssetCategory`, `ConsumableItem`) đã có spec đầy đủ (BA), sẵn sàng cho `pm` chia task. Luồng "xin + nhận" (`ConsumableRequest` hoặc tương đương) **BỊ CHẶN** — cần stakeholder trả lời các câu hỏi mở: (1) có cần approval không, ai duyệt; (2) ai được tạo request xin (tự xin cho mình hay xin hộ được); (3) có giới hạn số lượng tối đa/lần xin không; (4) hết hàng thì chặn hẳn / cho "nợ" chờ nhập thêm / fulfill một phần; (5) trừ tồn kho lúc tạo request hay lúc fulfill; (6) restock tồn kho qua luồng nào, ai được làm; (7) có cần ghi nhận người phát hàng/ký nhận không. Không tự đoán — xem chi tiết đầy đủ trong spec BA.
 - Migrate 2 request đang có (`Firefly_License_Request.docx`, `Eric Pelatan.docx`, ở workspace `ubisoft/` ngoài repo này) vào hệ thống mới sau khi có DB
 - (Xa hơn, chưa ưu tiên) Rack/Slot + IoT pick-to-light, cron email cảnh báo license hết hạn, Power BI report views
 - Setup Gitea tự host ở nhà (2026-07-31) — dự định làm remote chính sau này, giữ GitHub làm backup off-site (đây là "sản phẩm dùng cả đời" của user, không nên chỉ có 1 bản duy nhất). Tạm thời vẫn push GitHub như hiện tại, chưa làm gấp.
@@ -103,4 +180,4 @@ QR gán asset vào slot (bước 1, thủ công hàng ngày) **không phải IoT
 - Migrate entity `Request` từ SQLite sang Postgres (2026-07-30) và setup ESLint đều đã **CONFIRMED xong** qua lượt verify độc lập (test-runner riêng, không phải agent vừa code tự chấm) — 6 test pass trên Postgres thật, lint sạch, type-check sạch. Chi tiết trạng thái nằm ở `../CLAUDE.md`, không duplicate ở đây.
 
 ---
-Cập nhật lần cuối: 2026-08-02
+Cập nhật lần cuối: 2026-08-02 (spec `Vendor`, `PurchaseOrder` gộp `Receipt`, `Assignment`, `AssetCategoryAttributeDef` — sẵn sàng cho `pm` chia task)

prisma/migrations/20260802232754_add_vendor/migration.sql

@@ -0,0 +1,13 @@
+-- CreateTable
+CREATE TABLE "vendors" (
+    "id" UUID NOT NULL,
+    "name" TEXT NOT NULL,
+    "contact_email" TEXT NOT NULL,
+    "contact_phone" TEXT NOT NULL,
+    "address" TEXT NOT NULL,
+    "tax_code" TEXT,
+    "notes" TEXT,
+    "created_at" TIMESTAMPTZ(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "vendors_pkey" PRIMARY KEY ("id")
+);

prisma/migrations/20260802234029_retrofit_license_vendor_id/migration.sql

@@ -0,0 +1,13 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `vendor` on the `licenses` table. All the data in the column will be lost.
+  - Added the required column `vendor_id` to the `licenses` table without a default value. This is not possible if the table is not empty.
+
+*/
+-- AlterTable
+ALTER TABLE "licenses" DROP COLUMN "vendor",
+ADD COLUMN     "vendor_id" UUID NOT NULL;
+
+-- AddForeignKey
+ALTER TABLE "licenses" ADD CONSTRAINT "licenses_vendor_id_fkey" FOREIGN KEY ("vendor_id") REFERENCES "vendors"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

prisma/migrations/20260802235729_add_purchase_order/migration.sql

@@ -0,0 +1,18 @@
+-- CreateTable
+CREATE TABLE "purchase_orders" (
+    "id" UUID NOT NULL,
+    "vendor_id" UUID NOT NULL,
+    "order_date" TIMESTAMPTZ(6) NOT NULL,
+    "expected_date" TIMESTAMPTZ(6) NOT NULL,
+    "received_at" TIMESTAMPTZ(6),
+    "received_by" UUID,
+    "created_at" TIMESTAMPTZ(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "purchase_orders_pkey" PRIMARY KEY ("id")
+);
+
+-- AddForeignKey
+ALTER TABLE "purchase_orders" ADD CONSTRAINT "purchase_orders_vendor_id_fkey" FOREIGN KEY ("vendor_id") REFERENCES "vendors"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "purchase_orders" ADD CONSTRAINT "purchase_orders_received_by_fkey" FOREIGN KEY ("received_by") REFERENCES "employees"("id") ON DELETE SET NULL ON UPDATE CASCADE;

prisma/schema.prisma

@@ -51,14 +51,17 @@ model Request {
 // possible future normalization, not built yet. `managerId` is a nullable
 // self-relation: top-level employees (no manager) have `managerId = null`.
 model Employee {
-  id         String     @id @default(uuid()) @db.Uuid
+  id                     String          @id @default(uuid()) @db.Uuid
-  name       String
+  name                   String
-  department String
+  department             String
-  managerId  String?    @map("manager_id") @db.Uuid
+  managerId              String?         @map("manager_id") @db.Uuid
-  manager    Employee?  @relation("EmployeeManager", fields: [managerId], references: [id])
+  manager                Employee?       @relation("EmployeeManager", fields: [managerId], references: [id])
-  reports    Employee[] @relation("EmployeeManager")
+  reports                Employee[]      @relation("EmployeeManager")
-  requests   Request[]
+  requests               Request[]
-  createdAt  DateTime   @default(now()) @map("created_at") @db.Timestamptz(6)
+  // Back-relation for PurchaseOrder.receivedById — an Employee can be the
+  // receiver on multiple POs over time.
+  purchaseOrdersReceived PurchaseOrder[]
+  createdAt              DateTime        @default(now()) @map("created_at") @db.Timestamptz(6)
 
   @@map("employees")
 }
@@ -102,17 +105,20 @@ enum LicenseType {
 
 // Software license inventory — see docs/asset-license-management.md's "Data
 // model (sơ bộ)" table (tên, vendor, tổng seat, seat đã dùng, ngày hết hạn,
-// loại). `vendor` is deliberately a plain String for now, not a separate
+// loại). `vendorId` was a free-text `vendor` String until the "## Vendor
-// Vendor entity — no Vendor entity exists yet, same "plain string for now"
+// (chốt 2026-08-02)" retrofit — same precedent as Request.employeeId
-// precedent as Employee.department. `seatsUsed` is a stored counter
+// (string -> FK once Employee existed). No production `License` data
-// (defaults to 0 at creation), not a computed value — it will only ever be
+// existed at the time of this change, so this was a plain column-type
-// set to 0 here since Assignment (the thing that would consume seats)
+// migration, not a backfill. `seatsUsed` is a stored counter (defaults to 0
-// doesn't exist yet. `expiryDate` is nullable: perpetual licenses never
+// at creation), not a computed value — it will only ever be set to 0 here
-// expire, only subscription licenses usually have one.
+// since Assignment (the thing that would consume seats) doesn't exist yet.
+// `expiryDate` is nullable: perpetual licenses never expire, only
+// subscription licenses usually have one.
 model License {
   id          String      @id @default(uuid()) @db.Uuid
   name        String
-  vendor      String
+  vendorId    String      @map("vendor_id") @db.Uuid
+  vendor      Vendor      @relation(fields: [vendorId], references: [id])
   seatsTotal  Int         @map("seats_total")
   seatsUsed   Int         @default(0) @map("seats_used")
   expiryDate  DateTime?   @map("expiry_date") @db.Date
@@ -122,6 +128,61 @@ model License {
   @@map("licenses")
 }
 
+// Purchasing counterparty — see docs/asset-license-management.md's "## Vendor
+// (chốt 2026-08-02)". Deliberately independent of AssetModel.manufacturer
+// (OEM, e.g. "Dell") — Vendor is the reseller/distributor actually bought
+// from (e.g. "FPT Trading"), a different concept that isn't always the same
+// company. `licenses` is the back-relation from the License.vendor ->
+// License.vendorId retrofit (same doc section). `purchaseOrders` is the
+// back-relation from PurchaseOrder.vendorId (see "## PurchaseOrder (gộp
+// Receipt) (chốt 2026-08-02)"). taxCode/notes are nullable — not every
+// vendor record has a known VN tax code or extra notes at creation time.
+model Vendor {
+  id             String          @id @default(uuid()) @db.Uuid
+  name           String
+  contactEmail   String          @map("contact_email")
+  contactPhone   String          @map("contact_phone")
+  address        String
+  taxCode        String?         @map("tax_code")
+  notes          String?
+  createdAt      DateTime        @default(now()) @map("created_at") @db.Timestamptz(6)
+  licenses       License[]
+  purchaseOrders PurchaseOrder[]
+
+  @@map("vendors")
+}
+
+// Purchasing document — see docs/asset-license-management.md's "##
+// PurchaseOrder (gộp Receipt) (chốt 2026-08-02)". Deliberately absorbs what
+// would otherwise be a separate `Receipt` entity: receiving is just part of
+// this row's own state (`receivedAt`/`receivedBy`), not a separate table to
+// reconcile against. No `status` field — status is inferred from linked
+// `Request`s (Ordered -> Received -> Delivered), not stored here, to avoid
+// two sources of truth. No cost/price fields — stakeholder said explicitly
+// PurchaseOrder doesn't need to track money, only "which asset/license
+// belongs to which PO". Receiving is all-or-nothing per PO (no partial
+// receipt tracking) — a deliberate simplification, see doc for the
+// stakeholder-accepted tradeoff. `receivedAt`/`receivedBy` are both
+// nullable and must be co-null/co-set together (both-null = not yet
+// received) — enforced at the Zod layer (src/lib/purchase-orders.ts), not a
+// DB constraint, same approach as other cross-field invariants in this
+// codebase (e.g. Assignment's assetItemId/licenseId XOR, not built yet).
+// purchaseOrderId back-references on AssetItem/License/Request (traceability,
+// same doc section) are NOT part of this change — out of scope for this task.
+model PurchaseOrder {
+  id           String    @id @default(uuid()) @db.Uuid
+  vendorId     String    @map("vendor_id") @db.Uuid
+  vendor       Vendor    @relation(fields: [vendorId], references: [id])
+  orderDate    DateTime  @map("order_date") @db.Timestamptz(6)
+  expectedDate DateTime  @map("expected_date") @db.Timestamptz(6)
+  receivedAt   DateTime? @map("received_at") @db.Timestamptz(6)
+  receivedById String?   @map("received_by") @db.Uuid
+  receivedBy   Employee? @relation(fields: [receivedById], references: [id])
+  createdAt    DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+
+  @@map("purchase_orders")
+}
+
 // Minimal internal auth accounts — NOT company SSO (deliberately ruled out,
 // see CLAUDE.md / auth decision notes). A handful of trusted IT staff
 // accounts, created by hand via scripts/create-user.ts, no self-registration.

src/app/api/licenses/route.ts

@@ -22,10 +22,10 @@ export async function POST(request: Request): Promise<NextResponse> {
     return NextResponse.json({ error: "Request body must be a JSON object" }, { status: 400 });
   }
 
-  const { name, vendor, seatsTotal, expiryDate, licenseType } = body as Record<string, unknown>;
+  const { name, vendorId, seatsTotal, expiryDate, licenseType } = body as Record<string, unknown>;
   const validation = validateCreateLicenseInput({
     name,
-    vendor,
+    vendorId,
     seatsTotal,
     expiryDate,
     licenseType,
@@ -36,7 +36,10 @@ export async function POST(request: Request): Promise<NextResponse> {
   }
 
   const created = await createLicense(validation.value);
-  return NextResponse.json(created, { status: 201 });
+  if (!created.ok) {
+    return NextResponse.json({ error: created.error }, { status: 400 });
+  }
+  return NextResponse.json(created.value, { status: 201 });
 }
 
 export async function GET(): Promise<NextResponse> {

src/app/api/purchase-orders/route.ts

@@ -0,0 +1,58 @@
+import { NextResponse } from "next/server";
+import { auth } from "@/auth";
+import {
+  createPurchaseOrder,
+  listPurchaseOrders,
+  validateCreatePurchaseOrderInput,
+} from "@/lib/purchase-orders";
+
+// Mirrors src/app/api/licenses/route.ts's pattern — middleware.ts excludes
+// /api from route protection, so this checks the session itself. Flat
+// permission model (CLAUDE.md): only "logged in or not", no role check.
+export async function POST(request: Request): Promise<NextResponse> {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "Request body must be valid JSON" }, { status: 400 });
+  }
+
+  if (typeof body !== "object" || body === null) {
+    return NextResponse.json({ error: "Request body must be a JSON object" }, { status: 400 });
+  }
+
+  const { vendorId, orderDate, expectedDate, receivedAt, receivedById } =
+    body as Record<string, unknown>;
+  const validation = validateCreatePurchaseOrderInput({
+    vendorId,
+    orderDate,
+    expectedDate,
+    receivedAt,
+    receivedById,
+  });
+
+  if (!validation.ok) {
+    return NextResponse.json({ error: validation.error }, { status: 400 });
+  }
+
+  const created = await createPurchaseOrder(validation.value);
+  if (!created.ok) {
+    return NextResponse.json({ error: created.error }, { status: 400 });
+  }
+  return NextResponse.json(created.value, { status: 201 });
+}
+
+export async function GET(): Promise<NextResponse> {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const purchaseOrders = await listPurchaseOrders();
+  return NextResponse.json(purchaseOrders, { status: 200 });
+}

src/app/api/vendors/route.ts

@@ -0,0 +1,52 @@
+import { NextResponse } from "next/server";
+import { auth } from "@/auth";
+import { createVendor, listVendors, validateCreateVendorInput } from "@/lib/vendors";
+
+// Mirrors src/app/api/licenses/route.ts's pattern — middleware.ts excludes
+// /api from route protection, so this checks the session itself. Flat
+// permission model (CLAUDE.md): only "logged in or not", no role check.
+export async function POST(request: Request): Promise<NextResponse> {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "Request body must be valid JSON" }, { status: 400 });
+  }
+
+  if (typeof body !== "object" || body === null) {
+    return NextResponse.json({ error: "Request body must be a JSON object" }, { status: 400 });
+  }
+
+  const { name, contactEmail, contactPhone, address, taxCode, notes } =
+    body as Record<string, unknown>;
+  const validation = validateCreateVendorInput({
+    name,
+    contactEmail,
+    contactPhone,
+    address,
+    taxCode,
+    notes,
+  });
+
+  if (!validation.ok) {
+    return NextResponse.json({ error: validation.error }, { status: 400 });
+  }
+
+  const created = await createVendor(validation.value);
+  return NextResponse.json(created, { status: 201 });
+}
+
+export async function GET(): Promise<NextResponse> {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const vendors = await listVendors();
+  return NextResponse.json(vendors, { status: 200 });
+}

src/lib/licenses.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { Prisma } from "@prisma/client";
 import { prisma } from "./prisma";
 
 export type LicenseType = "perpetual" | "subscription";
@@ -6,7 +7,7 @@ export type LicenseType = "perpetual" | "subscription";
 export interface LicenseRecord {
   id: string;
   name: string;
-  vendor: string;
+  vendor_id: string;
   seats_total: number;
   seats_used: number;
   expiry_date: string | null;
@@ -16,7 +17,7 @@ export interface LicenseRecord {
 
 export interface CreateLicenseInput {
   name: string;
-  vendor: string;
+  vendorId: string;
   seatsTotal: number;
   expiryDate?: Date | null;
   licenseType: LicenseType;
@@ -46,7 +47,14 @@ function dateString(message: string) {
 
 const createLicenseSchema = z.object({
   name: nonEmptyString("name is required and must be a non-empty string"),
-  vendor: nonEmptyString("vendor is required and must be a non-empty string"),
+  // Now a real FK to Vendor (see schema.prisma) — only a UUID *format*
+  // check here — whether it references a real vendor is left to Prisma's
+  // own FK constraint at insert time (see createLicense()'s P2003 handling
+  // below), rather than an extra pre-check query. Mirrors the same pattern
+  // used for Request.employeeId in src/lib/requests.ts.
+  vendorId: z
+    .string({ required_error: "vendorId is required and must be a valid UUID string" })
+    .uuid("vendorId is required and must be a valid UUID string"),
   seatsTotal: z
     .number({ required_error: "seatsTotal is required and must be a positive integer", invalid_type_error: "seatsTotal is required and must be a positive integer" })
     .int({ message: "seatsTotal is required and must be a positive integer" })
@@ -60,17 +68,17 @@ const createLicenseSchema = z.object({
 });
 
 /**
- * Validates raw (untyped) license-creation input. name/vendor must be
+ * Validates raw (untyped) license-creation input. name must be a non-empty
- * non-empty strings, seatsTotal must be a positive integer, expiryDate is
+ * string, vendorId must be a valid UUID string, seatsTotal must be a
- * optional/nullable but must be a valid date string if present, licenseType
+ * positive integer, expiryDate is optional/nullable but must be a valid
- * must be one of the two enum values. seatsUsed is not accepted here — new
+ * date string if present, licenseType must be one of the two enum values.
- * licenses always start at 0 (same pattern as AssetItem always starting
+ * seatsUsed is not accepted here — new licenses always start at 0 (same
- * "in_stock"), seats are only ever consumed via other operations (once
+ * pattern as AssetItem always starting "in_stock"), seats are only ever
- * Assignment exists), not at creation.
+ * consumed via other operations (once Assignment exists), not at creation.
  */
 export function validateCreateLicenseInput(input: {
   name?: unknown;
-  vendor?: unknown;
+  vendorId?: unknown;
   seatsTotal?: unknown;
   expiryDate?: unknown;
   licenseType?: unknown;
@@ -86,7 +94,7 @@ export function validateCreateLicenseInput(input: {
 function toRecord(row: {
   id: string;
   name: string;
-  vendor: string;
+  vendorId: string;
   seatsTotal: number;
   seatsUsed: number;
   expiryDate: Date | null;
@@ -96,7 +104,7 @@ function toRecord(row: {
   return {
     id: row.id,
     name: row.name,
-    vendor: row.vendor,
+    vendor_id: row.vendorId,
     seats_total: row.seatsTotal,
     seats_used: row.seatsUsed,
     expiry_date: row.expiryDate ? row.expiryDate.toISOString() : null,
@@ -105,22 +113,35 @@ function toRecord(row: {
   };
 }
 
+export type CreateLicenseResult =
+  | { ok: true; value: LicenseRecord }
+  | { ok: false; error: string };
+
 /**
- * Creates a License. No unique constraint exists on `name` (unlike
+ * Creates a License. If vendorId doesn't reference an existing Vendor,
- * AssetItem.serialNumber), so unlike createAssetItem() there's no known
+ * Prisma raises a known error (code P2003, FK violation) — caught here and
- * Prisma error code to catch/translate here.
+ * translated into the same `{ok:false,error}` shape as input validation
+ * failures, rather than letting a raw Prisma error leak to the API layer.
+ * Mirrors src/lib/requests.ts's createRequest() pattern for employeeId.
  */
-export async function createLicense(input: CreateLicenseInput): Promise<LicenseRecord> {
+export async function createLicense(input: CreateLicenseInput): Promise<CreateLicenseResult> {
-  const created = await prisma.license.create({
+  try {
-    data: {
+    const created = await prisma.license.create({
-      name: input.name,
+      data: {
-      vendor: input.vendor,
+        name: input.name,
-      seatsTotal: input.seatsTotal,
+        vendorId: input.vendorId,
-      expiryDate: input.expiryDate ?? null,
+        seatsTotal: input.seatsTotal,
-      licenseType: input.licenseType,
+        expiryDate: input.expiryDate ?? null,
-    },
+        licenseType: input.licenseType,
-  });
+      },
-  return toRecord(created);
+    });
+    return { ok: true, value: toRecord(created) };
+  } catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2003") {
+      return { ok: false, error: "vendorId does not reference an existing vendor" };
+    }
+    throw error;
+  }
 }
 
 export async function listLicenses(): Promise<LicenseRecord[]> {

src/lib/purchase-orders.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { Prisma } from "@prisma/client";
+import { prisma } from "./prisma";
+
+export interface PurchaseOrderRecord {
+  id: string;
+  vendor_id: string;
+  order_date: string;
+  expected_date: string;
+  received_at: string | null;
+  received_by: string | null;
+  created_at: string;
+}
+
+export interface CreatePurchaseOrderInput {
+  vendorId: string;
+  orderDate: Date;
+  expectedDate: Date;
+  receivedAt?: Date | null;
+  receivedById?: string | null;
+}
+
+export type ValidationResult =
+  | { ok: true; value: CreatePurchaseOrderInput }
+  | { ok: false; error: string };
+
+// Mirrors src/lib/licenses.ts's dateString helper — accepts any string
+// Date.parse() can handle and transforms it into a Date for Prisma. Used
+// here for orderDate/expectedDate/receivedAt, which are all Timestamptz
+// (not just Date) columns, so datetime strings (not just "2026-07-31") are
+// also accepted.
+function dateString(message: string) {
+  return z
+    .string({ required_error: message, invalid_type_error: message })
+    .refine((value) => !Number.isNaN(Date.parse(value)), { message })
+    .transform((value) => new Date(value));
+}
+
+const createPurchaseOrderSchema = z
+  .object({
+    // FK to Vendor — only a UUID *format* check here, whether it references
+    // a real vendor is left to Prisma's own FK constraint at insert time
+    // (see createPurchaseOrder()'s P2003 handling below). Mirrors
+    // src/lib/licenses.ts's vendorId handling.
+    vendorId: z
+      .string({ required_error: "vendorId is required and must be a valid UUID string" })
+      .uuid("vendorId is required and must be a valid UUID string"),
+    orderDate: dateString("orderDate is required and must be a valid date string"),
+    expectedDate: dateString("expectedDate is required and must be a valid date string"),
+    // Both nullable — null means "not yet received". Co-nullability with
+    // receivedById is enforced by the .refine() below, not here.
+    receivedAt: dateString("receivedAt must be a valid date string").optional().nullable(),
+    receivedById: z
+      .string({ invalid_type_error: "receivedById must be a valid UUID string" })
+      .uuid("receivedById must be a valid UUID string")
+      .optional()
+      .nullable(),
+  })
+  .refine(
+    (value) => {
+      const hasReceivedAt = value.receivedAt !== undefined && value.receivedAt !== null;
+      const hasReceivedById = value.receivedById !== undefined && value.receivedById !== null;
+      return hasReceivedAt === hasReceivedById;
+    },
+    {
+      message: "receivedAt and receivedById must both be set or both be unset",
+      // Attach the error to both fields so it surfaces regardless of which
+      // one the caller looks at first.
+      path: ["receivedAt"],
+    }
+  );
+
+/**
+ * Validates raw (untyped) purchase-order-creation input. vendorId must be a
+ * valid UUID string, orderDate/expectedDate must be valid date strings,
+ * receivedAt/receivedById are optional/nullable but must both be set or
+ * both be unset (co-nullability invariant — receiving a PO always records
+ * both "when" and "who" together). No status field is accepted — PurchaseOrder
+ * deliberately has no stored status (see schema.prisma comment), it's
+ * inferred from linked Requests.
+ */
+export function validateCreatePurchaseOrderInput(input: {
+  vendorId?: unknown;
+  orderDate?: unknown;
+  expectedDate?: unknown;
+  receivedAt?: unknown;
+  receivedById?: unknown;
+}): ValidationResult {
+  const result = createPurchaseOrderSchema.safeParse(input);
+  if (!result.success) {
+    const message = result.error.issues[0]?.message ?? "Invalid input";
+    return { ok: false, error: message };
+  }
+  return { ok: true, value: result.data };
+}
+
+function toRecord(row: {
+  id: string;
+  vendorId: string;
+  orderDate: Date;
+  expectedDate: Date;
+  receivedAt: Date | null;
+  receivedById: string | null;
+  createdAt: Date;
+}): PurchaseOrderRecord {
+  return {
+    id: row.id,
+    vendor_id: row.vendorId,
+    order_date: row.orderDate.toISOString(),
+    expected_date: row.expectedDate.toISOString(),
+    received_at: row.receivedAt ? row.receivedAt.toISOString() : null,
+    received_by: row.receivedById,
+    created_at: row.createdAt.toISOString(),
+  };
+}
+
+export type CreatePurchaseOrderResult =
+  | { ok: true; value: PurchaseOrderRecord }
+  | { ok: false; error: string };
+
+/**
+ * Creates a PurchaseOrder. Two separate FKs can fail here (vendorId ->
+ * Vendor, receivedById -> Employee) — Prisma raises the same error code
+ * (P2003) for either, so the FK constraint name in `error.meta.field_name`
+ * is used to tell them apart and return a targeted message, rather than a
+ * raw Prisma error leaking to the API layer. Mirrors
+ * src/lib/licenses.ts's createLicense() pattern, extended for the
+ * two-FK case.
+ */
+export async function createPurchaseOrder(
+  input: CreatePurchaseOrderInput
+): Promise<CreatePurchaseOrderResult> {
+  try {
+    const created = await prisma.purchaseOrder.create({
+      data: {
+        vendorId: input.vendorId,
+        orderDate: input.orderDate,
+        expectedDate: input.expectedDate,
+        receivedAt: input.receivedAt ?? null,
+        receivedById: input.receivedById ?? null,
+      },
+    });
+    return { ok: true, value: toRecord(created) };
+  } catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2003") {
+      const fieldName = typeof error.meta?.field_name === "string" ? error.meta.field_name : "";
+      if (fieldName.includes("received_by")) {
+        return { ok: false, error: "receivedById does not reference an existing employee" };
+      }
+      return { ok: false, error: "vendorId does not reference an existing vendor" };
+    }
+    throw error;
+  }
+}
+
+export async function listPurchaseOrders(): Promise<PurchaseOrderRecord[]> {
+  const rows = await prisma.purchaseOrder.findMany({
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+  });
+  return rows.map(toRecord);
+}

src/lib/vendors.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { prisma } from "./prisma";
+
+export interface VendorRecord {
+  id: string;
+  name: string;
+  contact_email: string;
+  contact_phone: string;
+  address: string;
+  tax_code: string | null;
+  notes: string | null;
+  created_at: string;
+}
+
+export interface CreateVendorInput {
+  name: string;
+  contactEmail: string;
+  contactPhone: string;
+  address: string;
+  taxCode?: string | null;
+  notes?: string | null;
+}
+
+export type ValidationResult =
+  | { ok: true; value: CreateVendorInput }
+  | { ok: false; error: string };
+
+// Mirrors src/lib/licenses.ts's nonEmptyString helper.
+function nonEmptyString(message: string) {
+  return z.string({ required_error: message, invalid_type_error: message }).refine(
+    (value) => value.trim() !== "",
+    { message }
+  );
+}
+
+const createVendorSchema = z.object({
+  name: nonEmptyString("name is required and must be a non-empty string"),
+  contactEmail: z
+    .string({
+      required_error: "contactEmail is required and must be a valid email",
+      invalid_type_error: "contactEmail is required and must be a valid email",
+    })
+    .email("contactEmail is required and must be a valid email"),
+  contactPhone: nonEmptyString("contactPhone is required and must be a non-empty string"),
+  address: nonEmptyString("address is required and must be a non-empty string"),
+  // Nullable, per docs/asset-license-management.md's "## Vendor" spec — not
+  // every vendor record has a known VN tax code at creation time.
+  taxCode: nonEmptyString("taxCode must be a non-empty string").optional().nullable(),
+  notes: nonEmptyString("notes must be a non-empty string").optional().nullable(),
+});
+
+/**
+ * Validates raw (untyped) vendor-creation input. name/contactPhone/address
+ * must be non-empty strings, contactEmail must be a valid email string,
+ * taxCode/notes are optional/nullable (per the "## Vendor" spec in
+ * docs/asset-license-management.md) but must be non-empty strings if
+ * present.
+ */
+export function validateCreateVendorInput(input: {
+  name?: unknown;
+  contactEmail?: unknown;
+  contactPhone?: unknown;
+  address?: unknown;
+  taxCode?: unknown;
+  notes?: unknown;
+}): ValidationResult {
+  const result = createVendorSchema.safeParse(input);
+  if (!result.success) {
+    const message = result.error.issues[0]?.message ?? "Invalid input";
+    return { ok: false, error: message };
+  }
+  return { ok: true, value: result.data };
+}
+
+function toRecord(row: {
+  id: string;
+  name: string;
+  contactEmail: string;
+  contactPhone: string;
+  address: string;
+  taxCode: string | null;
+  notes: string | null;
+  createdAt: Date;
+}): VendorRecord {
+  return {
+    id: row.id,
+    name: row.name,
+    contact_email: row.contactEmail,
+    contact_phone: row.contactPhone,
+    address: row.address,
+    tax_code: row.taxCode,
+    notes: row.notes,
+    created_at: row.createdAt.toISOString(),
+  };
+}
+
+/**
+ * Creates a Vendor. No unique constraint exists on any field, no FKs
+ * either (see docs/asset-license-management.md's "## Vendor" spec — this
+ * is a standalone entity, same starting shape as Employee/License before
+ * they grew relations) — so unlike createAssetItem()/createEmployee()
+ * there's no known Prisma error code to catch/translate here.
+ */
+export async function createVendor(input: CreateVendorInput): Promise<VendorRecord> {
+  const created = await prisma.vendor.create({
+    data: {
+      name: input.name,
+      contactEmail: input.contactEmail,
+      contactPhone: input.contactPhone,
+      address: input.address,
+      taxCode: input.taxCode ?? null,
+      notes: input.notes ?? null,
+    },
+  });
+  return toRecord(created);
+}
+
+export async function listVendors(): Promise<VendorRecord[]> {
+  const rows = await prisma.vendor.findMany({
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+  });
+  return rows.map(toRecord);
+}

tests/licenses.test.ts

@@ -34,10 +34,27 @@ function postRequest(body: unknown): Request {
   });
 }
 
+// License.vendorId is a real FK to Vendor (see schema.prisma /
+// src/lib/licenses.ts) — tests that need a valid vendorId create a real
+// Vendor row first and use its id, rather than an arbitrary string. Mirrors
+// tests/requests.test.ts's createTestEmployee() helper.
+function createTestVendor(overrides: { name?: string } = {}) {
+  return prisma.vendor.create({
+    data: {
+      name: overrides.name ?? "Test Vendor",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Test Street",
+    },
+  });
+}
+
 beforeEach(async () => {
-  // Each test starts from an empty table so listing/order assertions are
+  // Each test starts from empty tables so listing/order assertions are
-  // deterministic.
+  // deterministic. licenses must be cleared before vendors since
+  // licenses.vendor_id has an FK (ON DELETE RESTRICT) to vendors.
   await prisma.license.deleteMany();
+  await prisma.vendor.deleteMany();
   // Default to a logged-in session — the lib-level tests below don't go
   // through the route at all (so this is a no-op for them), and the
   // route-level tests exercise business logic, not auth gating (that's
@@ -49,7 +66,7 @@ describe("validateCreateLicenseInput", () => {
   it("accepts valid input with an expiryDate", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 10,
       expiryDate: "2027-01-15",
       licenseType: "subscription",
@@ -59,7 +76,7 @@ describe("validateCreateLicenseInput", () => {
     if (result.ok) {
       expect(result.value).toMatchObject({
         name: "Adobe Creative Cloud",
-        vendor: "Adobe",
+        vendorId: "11111111-1111-1111-1111-111111111111",
         seatsTotal: 10,
         licenseType: "subscription",
       });
@@ -70,7 +87,7 @@ describe("validateCreateLicenseInput", () => {
   it("accepts valid input with no expiryDate (perpetual license)", () => {
     const result = validateCreateLicenseInput({
       name: "Windows Server 2022",
-      vendor: "Microsoft",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 5,
       licenseType: "perpetual",
     });
@@ -84,7 +101,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects an empty name", () => {
     const result = validateCreateLicenseInput({
       name: "",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 10,
       licenseType: "subscription",
     });
@@ -95,24 +112,37 @@ describe("validateCreateLicenseInput", () => {
     }
   });
 
-  it("rejects an empty vendor", () => {
+  it("rejects a vendorId that is not a valid UUID", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "",
+      vendorId: "not-a-uuid",
       seatsTotal: 10,
       licenseType: "subscription",
     });
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
-      expect(result.error).toMatch(/vendor/i);
+      expect(result.error).toMatch(/vendorId/i);
+    }
+  });
+
+  it("rejects a missing vendorId", () => {
+    const result = validateCreateLicenseInput({
+      name: "Adobe Creative Cloud",
+      seatsTotal: 10,
+      licenseType: "subscription",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/vendorId/i);
     }
   });
 
   it("rejects a zero seatsTotal", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 0,
       licenseType: "subscription",
     });
@@ -126,7 +156,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects a negative seatsTotal", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: -5,
       licenseType: "subscription",
     });
@@ -140,7 +170,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects a non-integer seatsTotal", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 3.5,
       licenseType: "subscription",
     });
@@ -154,7 +184,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects an invalid expiryDate", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 10,
       expiryDate: "not-a-date",
       licenseType: "subscription",
@@ -169,7 +199,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects an invalid licenseType", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 10,
       licenseType: "trial",
     });
@@ -183,7 +213,7 @@ describe("validateCreateLicenseInput", () => {
   it("rejects a missing licenseType", () => {
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: "11111111-1111-1111-1111-111111111111",
       seatsTotal: 10,
     });
 
@@ -196,9 +226,10 @@ describe("validateCreateLicenseInput", () => {
 
 describe("createLicense", () => {
   it("creates a license with seatsUsed always 0, regardless of client input", async () => {
+    const vendor = await createTestVendor();
     const result = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: vendor.id,
       seatsTotal: 10,
       // @ts-expect-error -- seatsUsed is intentionally not part of
       // CreateLicenseInput; this simulates a client trying to sneak it in.
@@ -209,12 +240,15 @@ describe("createLicense", () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
 
-    const record = await createLicense(result.value);
+    const created = await createLicense(result.value);
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const record = created.value;
 
     expect(record.seats_used).toBe(0);
     expect(record).toMatchObject({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendor_id: vendor.id,
       seats_total: 10,
       license_type: "subscription",
     });
@@ -225,28 +259,55 @@ describe("createLicense", () => {
   });
 
   it("creates a perpetual license with no expiryDate", async () => {
+    const vendor = await createTestVendor();
     const result = validateCreateLicenseInput({
       name: "Windows Server 2022",
-      vendor: "Microsoft",
+      vendorId: vendor.id,
       seatsTotal: 5,
       licenseType: "perpetual",
     });
     expect(result.ok).toBe(true);
     if (!result.ok) return;
 
-    const record = await createLicense(result.value);
+    const created = await createLicense(result.value);
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const record = created.value;
 
     expect(record.expiry_date).toBeNull();
     expect(record.seats_used).toBe(0);
     expect(record.license_type).toBe("perpetual");
   });
+
+  it("returns a clean error when vendorId doesn't reference an existing vendor", async () => {
+    const result = validateCreateLicenseInput({
+      name: "Adobe Creative Cloud",
+      vendorId: "00000000-0000-0000-0000-000000000000",
+      seatsTotal: 10,
+      licenseType: "subscription",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const created = await createLicense(result.value);
+    expect(created.ok).toBe(false);
+    if (created.ok) return;
+    expect(created.error).toMatch(/vendorId/i);
+    expect(created.error).toMatch(/does not reference an existing vendor/i);
+
+    const remaining = await prisma.license.findMany();
+    expect(remaining).toHaveLength(0);
+  });
 });
 
 describe("listLicenses", () => {
   it("lists created licenses, newest first", async () => {
+    const vendor1 = await createTestVendor({ name: "Microsoft VN" });
+    const vendor2 = await createTestVendor({ name: "Adobe VN" });
+
     const first = validateCreateLicenseInput({
       name: "Windows Server 2022",
-      vendor: "Microsoft",
+      vendorId: vendor1.id,
       seatsTotal: 5,
       licenseType: "perpetual",
     });
@@ -258,7 +319,7 @@ describe("listLicenses", () => {
 
     const second = validateCreateLicenseInput({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendorId: vendor2.id,
       seatsTotal: 10,
       licenseType: "subscription",
     });
@@ -269,8 +330,8 @@ describe("listLicenses", () => {
 
     expect(records).toHaveLength(2);
     // newest first
-    expect(records[0]).toMatchObject({ name: "Adobe Creative Cloud", vendor: "Adobe" });
+    expect(records[0]).toMatchObject({ name: "Adobe Creative Cloud", vendor_id: vendor2.id });
-    expect(records[1]).toMatchObject({ name: "Windows Server 2022", vendor: "Microsoft" });
+    expect(records[1]).toMatchObject({ name: "Windows Server 2022", vendor_id: vendor1.id });
   });
 
   it("returns an empty list when there are no licenses", async () => {
@@ -281,10 +342,11 @@ describe("listLicenses", () => {
 
 describe("POST /api/licenses", () => {
   it("creates a license with seatsUsed always 0 on valid input", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
       postRequest({
         name: "Adobe Creative Cloud",
-        vendor: "Adobe",
+        vendorId: vendor.id,
         seatsTotal: 10,
         expiryDate: "2027-01-15",
         licenseType: "subscription",
@@ -296,7 +358,7 @@ describe("POST /api/licenses", () => {
 
     expect(body).toMatchObject({
       name: "Adobe Creative Cloud",
-      vendor: "Adobe",
+      vendor_id: vendor.id,
       seats_total: 10,
       seats_used: 0,
       license_type: "subscription",
@@ -308,10 +370,11 @@ describe("POST /api/licenses", () => {
   });
 
   it("creates a perpetual license with no expiryDate", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
       postRequest({
         name: "Windows Server 2022",
-        vendor: "Microsoft",
+        vendorId: vendor.id,
         seatsTotal: 5,
         licenseType: "perpetual",
       })
@@ -324,8 +387,9 @@ describe("POST /api/licenses", () => {
   });
 
   it("rejects an empty name", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
-      postRequest({ name: "", vendor: "Adobe", seatsTotal: 10, licenseType: "subscription" })
+      postRequest({ name: "", vendorId: vendor.id, seatsTotal: 10, licenseType: "subscription" })
     );
 
     expect(res.status).toBe(400);
@@ -333,19 +397,45 @@ describe("POST /api/licenses", () => {
     expect(body.error).toMatch(/name/i);
   });
 
-  it("rejects an empty vendor", async () => {
+  it("rejects a vendorId that is not a valid UUID", async () => {
     const res = await POST(
-      postRequest({ name: "Adobe Creative Cloud", vendor: "", seatsTotal: 10, licenseType: "subscription" })
+      postRequest({
+        name: "Adobe Creative Cloud",
+        vendorId: "not-a-uuid",
+        seatsTotal: 10,
+        licenseType: "subscription",
+      })
     );
 
     expect(res.status).toBe(400);
     const body = await res.json();
-    expect(body.error).toMatch(/vendor/i);
+    expect(body.error).toMatch(/vendorId/i);
+  });
+
+  it("rejects a vendorId that is a well-formed UUID but doesn't reference an existing vendor", async () => {
+    const res = await POST(
+      postRequest({
+        name: "Adobe Creative Cloud",
+        vendorId: "00000000-0000-0000-0000-000000000000",
+        seatsTotal: 10,
+        licenseType: "subscription",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/vendorId/i);
+    expect(body.error).toMatch(/does not reference an existing vendor/i);
+
+    // And it must not have created anything.
+    const remaining = await prisma.license.findMany();
+    expect(remaining).toHaveLength(0);
   });
 
   it("rejects a zero seatsTotal", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
-      postRequest({ name: "Adobe Creative Cloud", vendor: "Adobe", seatsTotal: 0, licenseType: "subscription" })
+      postRequest({ name: "Adobe Creative Cloud", vendorId: vendor.id, seatsTotal: 0, licenseType: "subscription" })
     );
 
     expect(res.status).toBe(400);
@@ -354,10 +444,11 @@ describe("POST /api/licenses", () => {
   });
 
   it("rejects an invalid expiryDate", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
       postRequest({
         name: "Adobe Creative Cloud",
-        vendor: "Adobe",
+        vendorId: vendor.id,
         seatsTotal: 10,
         expiryDate: "not-a-date",
         licenseType: "subscription",
@@ -370,8 +461,9 @@ describe("POST /api/licenses", () => {
   });
 
   it("rejects an invalid licenseType", async () => {
+    const vendor = await createTestVendor();
     const res = await POST(
-      postRequest({ name: "Adobe Creative Cloud", vendor: "Adobe", seatsTotal: 10, licenseType: "trial" })
+      postRequest({ name: "Adobe Creative Cloud", vendorId: vendor.id, seatsTotal: 10, licenseType: "trial" })
     );
 
     expect(res.status).toBe(400);
@@ -406,13 +498,16 @@ describe("POST /api/licenses", () => {
 
 describe("GET /api/licenses", () => {
   it("lists created licenses, newest first", async () => {
+    const vendor1 = await createTestVendor({ name: "Microsoft VN" });
+    const vendor2 = await createTestVendor({ name: "Adobe VN" });
+
     await POST(
-      postRequest({ name: "Windows Server 2022", vendor: "Microsoft", seatsTotal: 5, licenseType: "perpetual" })
+      postRequest({ name: "Windows Server 2022", vendorId: vendor1.id, seatsTotal: 5, licenseType: "perpetual" })
     );
     // Ensure a distinct created_at ordering even on fast filesystems/clocks.
     await new Promise((resolve) => setTimeout(resolve, 5));
     await POST(
-      postRequest({ name: "Adobe Creative Cloud", vendor: "Adobe", seatsTotal: 10, licenseType: "subscription" })
+      postRequest({ name: "Adobe Creative Cloud", vendorId: vendor2.id, seatsTotal: 10, licenseType: "subscription" })
     );
 
     const res = await GET();
@@ -423,8 +518,8 @@ describe("GET /api/licenses", () => {
     expect(body).toHaveLength(2);
 
     // newest first
-    expect(body[0]).toMatchObject({ name: "Adobe Creative Cloud", vendor: "Adobe" });
+    expect(body[0]).toMatchObject({ name: "Adobe Creative Cloud", vendor_id: vendor2.id });
-    expect(body[1]).toMatchObject({ name: "Windows Server 2022", vendor: "Microsoft" });
+    expect(body[1]).toMatchObject({ name: "Windows Server 2022", vendor_id: vendor1.id });
   });
 
   it("returns an empty list when there are no licenses", async () => {
@@ -440,10 +535,11 @@ describe("auth gating on /api/licenses", () => {
   // session presence, per the flat permission model (no role/permission
   // logic).
   it("POST /api/licenses returns 401 without a session", async () => {
+    const vendor = await createTestVendor();
     mockedAuth.mockResolvedValue(null);
 
     const res = await POST(
-      postRequest({ name: "Adobe Creative Cloud", vendor: "Adobe", seatsTotal: 10, licenseType: "subscription" })
+      postRequest({ name: "Adobe Creative Cloud", vendorId: vendor.id, seatsTotal: 10, licenseType: "subscription" })
     );
 
     expect(res.status).toBe(401);

tests/purchase-orders.test.ts

@@ -0,0 +1,577 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Mock } from "vitest";
+import type { Session } from "next-auth";
+import {
+  createPurchaseOrder,
+  listPurchaseOrders,
+  validateCreatePurchaseOrderInput,
+} from "@/lib/purchase-orders";
+import { prisma } from "@/lib/prisma";
+
+// Note: this file has two layers of coverage, mirroring tests/licenses.test.ts:
+// - lib-level tests below exercise src/lib/purchase-orders.ts directly
+//   (validation, co-nullability refine, FK error handling, list ordering).
+// - route-level tests (further down) exercise
+//   src/app/api/purchase-orders/route.ts over HTTP, including the auth() gate.
+vi.mock("@/auth", () => ({ auth: vi.fn() }));
+
+import { GET, POST } from "@/app/api/purchase-orders/route";
+import { auth } from "@/auth";
+
+const mockedAuth = auth as unknown as Mock<() => Promise<Session | null>>;
+
+const testSession: Session = {
+  user: { id: "test-user-id" },
+  expires: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+};
+
+function postRequest(body: unknown): Request {
+  return new Request("http://localhost/api/purchase-orders", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+// PurchaseOrder.vendorId/receivedById are real FKs to Vendor/Employee (see
+// schema.prisma / src/lib/purchase-orders.ts) — tests that need valid ids
+// create real rows first and use their ids. Mirrors
+// tests/licenses.test.ts's createTestVendor() and tests/requests.test.ts's
+// createTestEmployee() helpers.
+function createTestVendor(overrides: { name?: string } = {}) {
+  return prisma.vendor.create({
+    data: {
+      name: overrides.name ?? "Test Vendor",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Test Street",
+    },
+  });
+}
+
+function createTestEmployee(overrides: { name?: string; department?: string } = {}) {
+  return prisma.employee.create({
+    data: {
+      name: overrides.name ?? "Test Employee",
+      department: overrides.department ?? "IT",
+    },
+  });
+}
+
+beforeEach(async () => {
+  // Each test starts from empty tables so listing/order assertions are
+  // deterministic. purchase_orders must be cleared before vendors/employees
+  // since purchase_orders has FKs (ON DELETE RESTRICT to vendors, ON DELETE
+  // SET NULL to employees) to both.
+  await prisma.purchaseOrder.deleteMany();
+  await prisma.vendor.deleteMany();
+  await prisma.employee.deleteMany();
+  // Default to a logged-in session — the lib-level tests below don't go
+  // through the route at all (so this is a no-op for them), and the
+  // route-level tests exercise business logic, not auth gating (that's
+  // covered by the "auth gating" describe block further down).
+  mockedAuth.mockResolvedValue(testSession);
+});
+
+describe("validateCreatePurchaseOrderInput", () => {
+  it("accepts valid input with no receivedAt/receivedById (not yet received)", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.vendorId).toBe("11111111-1111-1111-1111-111111111111");
+      expect(result.value.orderDate).toBeInstanceOf(Date);
+      expect(result.value.expectedDate).toBeInstanceOf(Date);
+      expect(result.value.receivedAt).toBeUndefined();
+      expect(result.value.receivedById).toBeUndefined();
+    }
+  });
+
+  it("accepts valid input with both receivedAt and receivedById explicitly null (not yet received)", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: null,
+      receivedById: null,
+    });
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts valid input with both receivedAt and receivedById set (received)", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: "2026-08-12",
+      receivedById: "22222222-2222-2222-2222-222222222222",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.receivedAt).toBeInstanceOf(Date);
+      expect(result.value.receivedById).toBe("22222222-2222-2222-2222-222222222222");
+    }
+  });
+
+  it("rejects receivedAt set without receivedById", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: "2026-08-12",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/receivedAt/i);
+      expect(result.error).toMatch(/receivedById/i);
+    }
+  });
+
+  it("rejects receivedById set without receivedAt", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedById: "22222222-2222-2222-2222-222222222222",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/receivedAt/i);
+      expect(result.error).toMatch(/receivedById/i);
+    }
+  });
+
+  it("rejects a missing vendorId", () => {
+    const result = validateCreatePurchaseOrderInput({
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/vendorId/i);
+    }
+  });
+
+  it("rejects a vendorId that is not a valid UUID", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "not-a-uuid",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/vendorId/i);
+    }
+  });
+
+  it("rejects a missing orderDate", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      expectedDate: "2026-08-10",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/orderDate/i);
+    }
+  });
+
+  it("rejects an invalid expectedDate", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "not-a-date",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/expectedDate/i);
+    }
+  });
+
+  it("rejects a receivedById that is not a valid UUID", () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "11111111-1111-1111-1111-111111111111",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: "2026-08-12",
+      receivedById: "not-a-uuid",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/receivedById/i);
+    }
+  });
+});
+
+describe("createPurchaseOrder", () => {
+  it("creates a purchase order that is not yet received", async () => {
+    const vendor = await createTestVendor();
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: vendor.id,
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const created = await createPurchaseOrder(result.value);
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const record = created.value;
+
+    expect(record.vendor_id).toBe(vendor.id);
+    expect(record.received_at).toBeNull();
+    expect(record.received_by).toBeNull();
+    expect(typeof record.id).toBe("string");
+    expect(record.id.length).toBeGreaterThan(0);
+    expect(Number.isNaN(Date.parse(record.order_date))).toBe(false);
+    expect(Number.isNaN(Date.parse(record.expected_date))).toBe(false);
+    expect(Number.isNaN(Date.parse(record.created_at))).toBe(false);
+  });
+
+  it("creates a purchase order that has already been received", async () => {
+    const vendor = await createTestVendor();
+    const employee = await createTestEmployee();
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: vendor.id,
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: "2026-08-12",
+      receivedById: employee.id,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const created = await createPurchaseOrder(result.value);
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const record = created.value;
+
+    expect(record.received_by).toBe(employee.id);
+    expect(Number.isNaN(Date.parse(record.received_at as string))).toBe(false);
+  });
+
+  it("returns a clean error when vendorId doesn't reference an existing vendor", async () => {
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: "00000000-0000-0000-0000-000000000000",
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const created = await createPurchaseOrder(result.value);
+    expect(created.ok).toBe(false);
+    if (created.ok) return;
+    expect(created.error).toMatch(/vendorId/i);
+    expect(created.error).toMatch(/does not reference an existing vendor/i);
+
+    const remaining = await prisma.purchaseOrder.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+
+  it("returns a clean error when receivedById doesn't reference an existing employee", async () => {
+    const vendor = await createTestVendor();
+    const result = validateCreatePurchaseOrderInput({
+      vendorId: vendor.id,
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+      receivedAt: "2026-08-12",
+      receivedById: "00000000-0000-0000-0000-000000000000",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const created = await createPurchaseOrder(result.value);
+    expect(created.ok).toBe(false);
+    if (created.ok) return;
+    expect(created.error).toMatch(/receivedById/i);
+    expect(created.error).toMatch(/does not reference an existing employee/i);
+
+    const remaining = await prisma.purchaseOrder.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+});
+
+describe("listPurchaseOrders", () => {
+  it("lists created purchase orders, newest first", async () => {
+    const vendor1 = await createTestVendor({ name: "Microsoft VN" });
+    const vendor2 = await createTestVendor({ name: "Adobe VN" });
+
+    const first = validateCreatePurchaseOrderInput({
+      vendorId: vendor1.id,
+      orderDate: "2026-08-01",
+      expectedDate: "2026-08-10",
+    });
+    expect(first.ok).toBe(true);
+    if (first.ok) await createPurchaseOrder(first.value);
+
+    // Ensure a distinct created_at ordering even on fast filesystems/clocks.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    const second = validateCreatePurchaseOrderInput({
+      vendorId: vendor2.id,
+      orderDate: "2026-08-02",
+      expectedDate: "2026-08-11",
+    });
+    expect(second.ok).toBe(true);
+    if (second.ok) await createPurchaseOrder(second.value);
+
+    const records = await listPurchaseOrders();
+
+    expect(records).toHaveLength(2);
+    // newest first
+    expect(records[0]).toMatchObject({ vendor_id: vendor2.id });
+    expect(records[1]).toMatchObject({ vendor_id: vendor1.id });
+  });
+
+  it("returns an empty list when there are no purchase orders", async () => {
+    const records = await listPurchaseOrders();
+    expect(records).toEqual([]);
+  });
+});
+
+describe("POST /api/purchase-orders", () => {
+  it("creates a purchase order that is not yet received on valid input", async () => {
+    const vendor = await createTestVendor();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+      })
+    );
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+
+    expect(body).toMatchObject({ vendor_id: vendor.id, received_at: null, received_by: null });
+    expect(typeof body.id).toBe("string");
+    expect(body.id.length).toBeGreaterThan(0);
+    expect(Number.isNaN(Date.parse(body.order_date))).toBe(false);
+    expect(Number.isNaN(Date.parse(body.expected_date))).toBe(false);
+    expect(Number.isNaN(Date.parse(body.created_at))).toBe(false);
+  });
+
+  it("creates a purchase order that has already been received", async () => {
+    const vendor = await createTestVendor();
+    const employee = await createTestEmployee();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+        receivedAt: "2026-08-12",
+        receivedById: employee.id,
+      })
+    );
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.received_by).toBe(employee.id);
+    expect(Number.isNaN(Date.parse(body.received_at))).toBe(false);
+  });
+
+  it("rejects a missing vendorId", async () => {
+    const res = await POST(
+      postRequest({ orderDate: "2026-08-01", expectedDate: "2026-08-10" })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/vendorId/i);
+  });
+
+  it("rejects a vendorId that is a well-formed UUID but doesn't reference an existing vendor", async () => {
+    const res = await POST(
+      postRequest({
+        vendorId: "00000000-0000-0000-0000-000000000000",
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/vendorId/i);
+    expect(body.error).toMatch(/does not reference an existing vendor/i);
+
+    // And it must not have created anything.
+    const remaining = await prisma.purchaseOrder.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+
+  it("rejects a receivedById that is a well-formed UUID but doesn't reference an existing employee", async () => {
+    const vendor = await createTestVendor();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+        receivedAt: "2026-08-12",
+        receivedById: "00000000-0000-0000-0000-000000000000",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/receivedById/i);
+    expect(body.error).toMatch(/does not reference an existing employee/i);
+
+    // And it must not have created anything.
+    const remaining = await prisma.purchaseOrder.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+
+  it("rejects receivedAt set without receivedById", async () => {
+    const vendor = await createTestVendor();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+        receivedAt: "2026-08-12",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/receivedAt/i);
+    expect(body.error).toMatch(/receivedById/i);
+  });
+
+  it("rejects receivedById set without receivedAt", async () => {
+    const vendor = await createTestVendor();
+    const employee = await createTestEmployee();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "2026-08-10",
+        receivedById: employee.id,
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/receivedAt/i);
+    expect(body.error).toMatch(/receivedById/i);
+  });
+
+  it("rejects an invalid expectedDate", async () => {
+    const vendor = await createTestVendor();
+    const res = await POST(
+      postRequest({
+        vendorId: vendor.id,
+        orderDate: "2026-08-01",
+        expectedDate: "not-a-date",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/expectedDate/i);
+  });
+
+  it("rejects an invalid JSON body", async () => {
+    const req = new Request("http://localhost/api/purchase-orders", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "not json",
+    });
+
+    const res = await POST(req);
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/JSON/i);
+  });
+
+  it("rejects a non-object JSON body", async () => {
+    // Note: arrays are `typeof "object"` in JS, so they pass the route's
+    // object check (same behavior as /api/licenses) — use a JSON string
+    // primitive here to actually exercise the "not an object" branch.
+    const res = await POST(postRequest("not an object"));
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/JSON object/i);
+  });
+});
+
+describe("GET /api/purchase-orders", () => {
+  it("lists created purchase orders, newest first", async () => {
+    const vendor1 = await createTestVendor({ name: "Microsoft VN" });
+    const vendor2 = await createTestVendor({ name: "Adobe VN" });
+
+    await POST(
+      postRequest({ vendorId: vendor1.id, orderDate: "2026-08-01", expectedDate: "2026-08-10" })
+    );
+    // Ensure a distinct created_at ordering even on fast filesystems/clocks.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await POST(
+      postRequest({ vendorId: vendor2.id, orderDate: "2026-08-02", expectedDate: "2026-08-11" })
+    );
+
+    const res = await GET();
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toHaveLength(2);
+
+    // newest first
+    expect(body[0]).toMatchObject({ vendor_id: vendor2.id });
+    expect(body[1]).toMatchObject({ vendor_id: vendor1.id });
+  });
+
+  it("returns an empty list when there are no purchase orders", async () => {
+    const res = await GET();
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual([]);
+  });
+});
+
+describe("auth gating on /api/purchase-orders", () => {
+  // Mirrors tests/licenses.test.ts's "auth gating" block — only checks
+  // session presence, per the flat permission model (no role/permission
+  // logic).
+  it("POST /api/purchase-orders returns 401 without a session", async () => {
+    const vendor = await createTestVendor();
+    mockedAuth.mockResolvedValue(null);
+
+    const res = await POST(
+      postRequest({ vendorId: vendor.id, orderDate: "2026-08-01", expectedDate: "2026-08-10" })
+    );
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ error: "Unauthorized" });
+
+    // And it must not have created anything.
+    const remaining = await prisma.purchaseOrder.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+
+  it("GET /api/purchase-orders returns 401 without a session", async () => {
+    mockedAuth.mockResolvedValue(null);
+
+    const res = await GET();
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ error: "Unauthorized" });
+  });
+});

tests/vendors.test.ts

@@ -0,0 +1,476 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Mock } from "vitest";
+import type { Session } from "next-auth";
+import {
+  createVendor,
+  listVendors,
+  validateCreateVendorInput,
+} from "@/lib/vendors";
+import { prisma } from "@/lib/prisma";
+
+// Note: this file has two layers of coverage, mirroring tests/licenses.test.ts:
+// - lib-level tests below exercise src/lib/vendors.ts directly (validation,
+//   nullable taxCode/notes, list ordering).
+// - route-level tests (further down) exercise src/app/api/vendors/route.ts
+//   over HTTP, including the auth() gate — mirrors tests/licenses.test.ts's
+//   @/auth mocking pattern.
+vi.mock("@/auth", () => ({ auth: vi.fn() }));
+
+import { GET, POST } from "@/app/api/vendors/route";
+import { auth } from "@/auth";
+
+const mockedAuth = auth as unknown as Mock<() => Promise<Session | null>>;
+
+const testSession: Session = {
+  user: { id: "test-user-id" },
+  expires: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+};
+
+function postRequest(body: unknown): Request {
+  return new Request("http://localhost/api/vendors", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+beforeEach(async () => {
+  // Each test starts from an empty table so listing/order assertions are
+  // deterministic.
+  await prisma.vendor.deleteMany();
+  // Default to a logged-in session — the lib-level tests below don't go
+  // through the route at all (so this is a no-op for them), and the
+  // route-level tests exercise business logic, not auth gating (that's
+  // covered by the "auth gating" describe block further down).
+  mockedAuth.mockResolvedValue(testSession);
+});
+
+describe("validateCreateVendorInput", () => {
+  it("accepts valid input with taxCode and notes", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      taxCode: "0301234567",
+      notes: "Preferred reseller for Dell laptops",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatchObject({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+        taxCode: "0301234567",
+        notes: "Preferred reseller for Dell laptops",
+      });
+    }
+  });
+
+  it("accepts valid input with no taxCode/notes", () => {
+    const result = validateCreateVendorInput({
+      name: "Synnex FPT",
+      contactEmail: "[email protected]",
+      contactPhone: "0287654321",
+      address: "456 Le Van Viet, Q9, HCMC",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.taxCode).toBeUndefined();
+      expect(result.value.notes).toBeUndefined();
+    }
+  });
+
+  it("rejects an empty name", () => {
+    const result = validateCreateVendorInput({
+      name: "",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/name/i);
+    }
+  });
+
+  it("rejects an invalid contactEmail", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "not-an-email",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/contactEmail/i);
+    }
+  });
+
+  it("rejects a missing contactEmail", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/contactEmail/i);
+    }
+  });
+
+  it("rejects an empty contactPhone", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/contactPhone/i);
+    }
+  });
+
+  it("rejects an empty address", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/address/i);
+    }
+  });
+
+  it("rejects an empty taxCode when provided", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      taxCode: "",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatch(/taxCode/i);
+    }
+  });
+
+  it("accepts a null taxCode/notes explicitly", () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      taxCode: null,
+      notes: null,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.taxCode).toBeNull();
+      expect(result.value.notes).toBeNull();
+    }
+  });
+});
+
+describe("createVendor", () => {
+  it("creates a vendor with taxCode and notes", async () => {
+    const result = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      taxCode: "0301234567",
+      notes: "Preferred reseller for Dell laptops",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const record = await createVendor(result.value);
+
+    expect(record).toMatchObject({
+      name: "FPT Trading",
+      contact_email: "[email protected]",
+      contact_phone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      tax_code: "0301234567",
+      notes: "Preferred reseller for Dell laptops",
+    });
+    expect(typeof record.id).toBe("string");
+    expect(record.id.length).toBeGreaterThan(0);
+    expect(Number.isNaN(Date.parse(record.created_at))).toBe(false);
+  });
+
+  it("creates a vendor with no taxCode/notes (both null)", async () => {
+    const result = validateCreateVendorInput({
+      name: "Synnex FPT",
+      contactEmail: "[email protected]",
+      contactPhone: "0287654321",
+      address: "456 Le Van Viet, Q9, HCMC",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const record = await createVendor(result.value);
+
+    expect(record.tax_code).toBeNull();
+    expect(record.notes).toBeNull();
+  });
+});
+
+describe("listVendors", () => {
+  it("lists created vendors, newest first", async () => {
+    const first = validateCreateVendorInput({
+      name: "Synnex FPT",
+      contactEmail: "[email protected]",
+      contactPhone: "0287654321",
+      address: "456 Le Van Viet, Q9, HCMC",
+    });
+    expect(first.ok).toBe(true);
+    if (first.ok) await createVendor(first.value);
+
+    // Ensure a distinct created_at ordering even on fast filesystems/clocks.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    const second = validateCreateVendorInput({
+      name: "FPT Trading",
+      contactEmail: "[email protected]",
+      contactPhone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+    });
+    expect(second.ok).toBe(true);
+    if (second.ok) await createVendor(second.value);
+
+    const records = await listVendors();
+
+    expect(records).toHaveLength(2);
+    // newest first
+    expect(records[0]).toMatchObject({ name: "FPT Trading" });
+    expect(records[1]).toMatchObject({ name: "Synnex FPT" });
+  });
+
+  it("returns an empty list when there are no vendors", async () => {
+    const records = await listVendors();
+    expect(records).toEqual([]);
+  });
+});
+
+describe("POST /api/vendors", () => {
+  it("creates a vendor on valid input", async () => {
+    const res = await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+        taxCode: "0301234567",
+        notes: "Preferred reseller for Dell laptops",
+      })
+    );
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+
+    expect(body).toMatchObject({
+      name: "FPT Trading",
+      contact_email: "[email protected]",
+      contact_phone: "0281234567",
+      address: "123 Nguyen Van Linh, Q7, HCMC",
+      tax_code: "0301234567",
+      notes: "Preferred reseller for Dell laptops",
+    });
+    expect(typeof body.id).toBe("string");
+    expect(body.id.length).toBeGreaterThan(0);
+    expect(Number.isNaN(Date.parse(body.created_at))).toBe(false);
+  });
+
+  it("creates a vendor with no taxCode/notes", async () => {
+    const res = await POST(
+      postRequest({
+        name: "Synnex FPT",
+        contactEmail: "[email protected]",
+        contactPhone: "0287654321",
+        address: "456 Le Van Viet, Q9, HCMC",
+      })
+    );
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.tax_code).toBeNull();
+    expect(body.notes).toBeNull();
+  });
+
+  it("rejects an empty name", async () => {
+    const res = await POST(
+      postRequest({
+        name: "",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/name/i);
+  });
+
+  it("rejects an invalid contactEmail", async () => {
+    const res = await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "not-an-email",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/contactEmail/i);
+  });
+
+  it("rejects an empty contactPhone", async () => {
+    const res = await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/contactPhone/i);
+  });
+
+  it("rejects an empty address", async () => {
+    const res = await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "",
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/address/i);
+  });
+
+  it("rejects an invalid JSON body", async () => {
+    const req = new Request("http://localhost/api/vendors", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "not json",
+    });
+
+    const res = await POST(req);
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/JSON/i);
+  });
+
+  it("rejects a non-object JSON body", async () => {
+    // Note: arrays are `typeof "object"` in JS, so they pass the route's
+    // object check (same behavior as /api/licenses) — use a JSON string
+    // primitive here to actually exercise the "not an object" branch.
+    const res = await POST(postRequest("not an object"));
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/JSON object/i);
+  });
+});
+
+describe("GET /api/vendors", () => {
+  it("lists created vendors, newest first", async () => {
+    await POST(
+      postRequest({
+        name: "Synnex FPT",
+        contactEmail: "[email protected]",
+        contactPhone: "0287654321",
+        address: "456 Le Van Viet, Q9, HCMC",
+      })
+    );
+    // Ensure a distinct created_at ordering even on fast filesystems/clocks.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+      })
+    );
+
+    const res = await GET();
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toHaveLength(2);
+
+    // newest first
+    expect(body[0]).toMatchObject({ name: "FPT Trading" });
+    expect(body[1]).toMatchObject({ name: "Synnex FPT" });
+  });
+
+  it("returns an empty list when there are no vendors", async () => {
+    const res = await GET();
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual([]);
+  });
+});
+
+describe("auth gating on /api/vendors", () => {
+  // Mirrors tests/licenses.test.ts's "auth gating" block — only checks
+  // session presence, per the flat permission model (no role/permission
+  // logic).
+  it("POST /api/vendors returns 401 without a session", async () => {
+    mockedAuth.mockResolvedValue(null);
+
+    const res = await POST(
+      postRequest({
+        name: "FPT Trading",
+        contactEmail: "[email protected]",
+        contactPhone: "0281234567",
+        address: "123 Nguyen Van Linh, Q7, HCMC",
+      })
+    );
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ error: "Unauthorized" });
+
+    // And it must not have created anything.
+    const remaining = await prisma.vendor.findMany();
+    expect(remaining).toHaveLength(0);
+  });
+
+  it("GET /api/vendors returns 401 without a session", async () => {
+    mockedAuth.mockResolvedValue(null);
+
+    const res = await GET();
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ error: "Unauthorized" });
+  });
+});