PRD: Vendor

Module	Kho (CORE-06)	PRD ID	PRD-VEN-001
Status	Shipped	Owner	Inventory squad
Date	2026-05-27	Version	v1.0
Packages	@nx/inventory · apps/client	URD	VEN

TL;DR

Cho merchant một nơi để lưu các nhà cung cấp của mình - một danh mục vendor với liên hệ, địa chỉ, đăng ký thuế, và liên kết nguyên vật liệu - được tạo và sửa trong một thao tác aggregate duy nhất từ cả client app lẫn back office. Mọi đơn mua hàng tham chiếu một vendor ở đây, nên mỗi lần nhập tồn đều truy về được một nhà cung cấp có tên, và soft-delete bảo toàn liên kết đó ngay cả sau khi một vendor bị gỡ.

1. Bối cảnh & Vấn đề

Đơn mua hàng cần một nhà cung cấp để tham chiếu, và merchant cần một nơi duy nhất để lưu thông tin liên hệ và thuế của nhà cung cấp. Không có danh mục vendor, một lần nhập tồn không thể truy về một nhà cung cấp có tên, và không có bản ghi cô lập theo merchant về việc một doanh nghiệp mua hàng từ ai, liên hệ thế nào, hay đăng ký thuế của họ ra sao - khiến việc mua hàng, đối soát nhà cung cấp, và báo cáo thuế trở nên không đáng tin.

Package @nx/inventory đã có sẵn entity Vendor, service, và API (kết quả của một lần đổi tên supplier → vendor trước đó), nhưng chưa có bề mặt hướng người dùng để tạo, sửa, hay duyệt vendor. Increment này cung cấp bề mặt đó - các màn hình client và back-office cộng với một đường aggregate create/update - biến Vendor ở backend thành một danh mục nhà cung cấp hoạt động được mà các đơn mua hàng có thể tham chiếu.

2. Mục tiêu & Ngoài phạm vi

Mục tiêu

• Một danh mục vendor cô lập theo từng merchant, ghi nhận tên, thông tin liên hệ (emails, phones), địa chỉ, và đăng ký thuế.
• Màn hình tạo/sửa với một form liên hệ có cấu trúc và một trường điều khoản thanh toán.
• Một danh sách/bảng vendor để duyệt các nhà cung cấp hiện có.
• Aggregate create/update để một vendor và các trường liên quan (gồm liên kết nguyên vật liệu qua một material multi-input) được lưu trong một thao tác.
• Cùng một bề mặt được cung cấp ở cả client app lẫn back office.

Ngoài phạm vi

• Nhận hàng đơn mua hàng và biến động tồn - thuộc về Đơn mua hàng / Mục đơn mua hàng.
• Quyền sở hữu danh mục nguyên vật liệu phía vendor vượt khỏi liên kết multi-select hiển thị trên form.
• Định giá vendor đa tiền tệ hoặc định giá vendor (ngoài phạm vi module theo phần Ngoài phạm vi của URD).

3. Success Metrics

Metric	Mục tiêu / tín hiệu
Khả năng truy vết	100% đơn mua hàng tham chiếu một vendor hiện có (không có lần nhập tồn mồ côi)
Mức độ áp dụng	Merchant duy trì một danh mục vendor thay vì ghi chú nhà cung cấp tạm bợ
Độ đầy đủ dữ liệu	Vendor mang theo chi tiết liên hệ + thuế dùng được cho PO và báo cáo thuế
Toàn vẹn lịch sử	Gỡ một vendor không bao giờ làm hỏng một tham chiếu PO hiện có (soft-delete bảo toàn nó)

4. Personas & Use Cases

Persona	Mục tiêu trong tính năng này
Chủ	Duy trì một danh mục nhà cung cấp với chi tiết liên hệ và thuế
Nhân viên kho	Tra cứu và chọn một vendor khi lập một đơn mua hàng

Core scenarios: tạo một vendor (tên, liên hệ, địa chỉ, thuế) → sửa nó sau bằng một aggregate update gồm liên kết nguyên vật liệu → duyệt danh sách vendor → tham chiếu vendor từ một đơn mua hàng → soft-delete một vendor trong khi bảo toàn các liên kết PO lịch sử.

5. User Stories

• Là một chủ, tôi muốn tạo một vendor với tên, liên hệ, địa chỉ, và đăng ký thuế, để các nhà cung cấp của tôi nằm trong một danh mục cô lập theo merchant.
• Là một chủ, tôi muốn sửa một vendor và các liên kết nguyên vật liệu của nó trong một lần lưu duy nhất, để vendor và các trường liên quan giữ nhất quán.
• Là nhân viên kho, tôi muốn duyệt và tìm danh sách vendor, để chọn đúng nhà cung cấp khi lập một PO.
• Là một chủ, tôi muốn một vendor đã gỡ vẫn giữ nguyên các tham chiếu PO lịch sử, để các lần mua trong quá khứ vẫn audit được.

6. Functional Requirements

#	Requirement	URD ref
FR-1	Chủ có thể tạo vendor trong một merchant; vendor được cô lập theo từng merchant	URD-VEN-001 · URD-VEN-005
FR-2	Vendor ghi nhận tên, thông tin liên hệ (emails, phones), địa chỉ, và một system identifier (VEN_YYYYMMDD_id)	URD-VEN-002
FR-3	Vendor có thể lưu một mã số đăng ký thuế	URD-VEN-003
FR-4	Aggregate create/update lưu vendor và các trường liên quan (liên hệ, điều khoản thanh toán, liên kết nguyên vật liệu) trong một thao tác	URD-VEN-001..002
FR-5	Vendor dùng soft-delete; các tham chiếu PO lịch sử được bảo toàn	URD-VEN-004

Toàn văn requirement và tiêu chí nghiệm thu nằm trong URD Kho. PRD này tham chiếu chúng thay vì lặp lại.

7. Non-Functional Requirements

Area	Requirement
Toàn vẹn dữ liệu	Soft-delete bảo toàn các vendor được đơn mua hàng tham chiếu - một vendor đã gỡ không bao giờ làm mồ côi một dòng PO
Tenancy & authz	Mọi thao tác cô lập theo từng merchant (x-merchant-id); được kiểm soát bởi permission của Kho
Tính nhất quán	Aggregate create/update là transactional - một vendor và các trường liên quan commit cùng nhau hoặc không gì cả
i18n	Nhãn hướng người dùng song ngữ ({ en, vi })

8. UX & Flows

Các màn hình chính (trong apps/client và back office): danh sách/bảng vendor, tạo vendor, sửa vendor - với một form liên hệ có cấu trúc, một trường điều khoản thanh toán, và một material multi-input.

9. Data & Domain

Entity	Vai trò
Vendor	Bản ghi nhà cung cấp - tên, liên hệ (emails/phones), địa chỉ, đăng ký thuế, system identifier, soft-delete
Liên kết nguyên vật liệu	Liên kết một vendor tới các nguyên vật liệu nó cung cấp, ghi nhận qua material multi-input của form

Chỉ ở mức khái niệm - toàn bộ schema và bất biến nằm trong domain model của Kho.

10. Dependencies & Assumptions

Phụ thuộc vào

• Entity/service/API Vendor của @nx/inventory - contract backend hiện có mà bề mặt này tiêu thụ (từ lần refactor supplier → vendor trước đó).
• Nguyên vật liệu (URD-MAT) - cho các liên kết material multi-input trên form vendor.

Giả định

• Ngữ cảnh merchant (x-merchant-id) được thiết lập để vendor được cô lập đúng.
• Đơn mua hàng sẽ tham chiếu vendor từ danh mục này thay vì nhà cung cấp dạng free-text.

11. Risks & Open Questions

Rủi ro / câu hỏi	Giảm thiểu / trạng thái
Xóa một vendor có thể làm mồ côi các tham chiếu PO lịch sử	Soft-delete bảo toàn liên kết; vendor không bao giờ bị hard-delete
Aggregate update lỗi một phần	Update là transactional - vendor và các trường liên quan commit cùng nhau
Phình phạm vi liên kết nguyên vật liệu (catalog vendor sở hữu)	Ngoài phạm vi; chỉ hỗ trợ liên kết multi-select trên form
Định giá vendor đa tiền tệ	Ngoài phạm vi theo phần Ngoài phạm vi của URD; ghi nhận như một ràng buộc cho vendor xuyên biên giới

12. Release Plan & Launch Criteria

Khía cạnh	Kế hoạch
Phase	P1 (nền tảng) - xem catalog tính năng URD
Rollout	Mọi merchant; không feature flag; client app + back office
Migration	Không (entity Vendor backend đã có sẵn từ lần refactor supplier → vendor)
Tiêu chí ra mắt	Tạo→sửa→liệt kê đã kiểm chứng đầu-cuối; aggregate update (gồm liên kết nguyên vật liệu) lưu trong một thao tác duy nhất; soft-delete bảo toàn các tham chiếu PO
Giám sát	Số vendor theo từng merchant, tỉ lệ lỗi create/update, toàn vẹn tham chiếu PO-tới-vendor

13. FAQ

Một đơn mua hàng lấy vendor từ đâu? Từ danh mục này - một PO cần một vendor hiện có, nên nhà cung cấp, liên hệ, và chi tiết thuế được tái sử dụng thay vì nhập lại.

Điều gì xảy ra với PO khi tôi gỡ một vendor? Không gì hỏng cả - vendor dùng soft-delete, nên các tham chiếu PO lịch sử được bảo toàn.

Tôi có thể lưu một vendor và các nguyên vật liệu của nó trong một bước? Có - aggregate create/update commit vendor và các trường liên quan (liên hệ, điều khoản thanh toán, liên kết nguyên vật liệu) trong một thao tác transactional duy nhất.

Danh mục vendor có dùng chung giữa các merchant? Không - vendor được cô lập theo từng merchant.

Cái này có sở hữu danh mục nguyên vật liệu không? Không - chỉ liên kết material multi-select trên form vendor; bản thân danh mục nguyên vật liệu là tính năng Nguyên vật liệu.

References

• URD: Kho - Vendor
• Được dùng bởi: Đơn mua hàng · Mục đơn mua hàng
• Liên quan: Nguyên vật liệu
• Module: Kho - tổng quan + truy vết
• Developer: @nx/inventory · domain model