Product Variants

Đào sâu tính năng. Định danh dịch vụ và bề mặt async nằm trong Tổng quan Commerce và API Events.

Một ProductVariant đại diện cho một cấu hình bán được cụ thể của sản phẩm (ví dụ kích cỡ, màu sắc). Mỗi variant có ProductInfo riêng, identifier (SKU, barcode), dữ liệu pricing tùy chọn, và MetaLinks (hình ảnh).

Tổng quan

Thuộc tính	Giá trị
Thực thể	ProductVariant, ProductInfo, ProductIdentifier, MetaLink
Base path	/product-variants (live spec: /v1/api/commerce/doc/openapi.json)
Type cấu trúc	ProductVariant.type — xem Domain Model §4.1
Pricing	catalog lưu dữ liệu pricing; tính toán nằm trong @nx/pricing

Mô hình thực thể

Xem Domain Model §3.2. Bảng trường được duy trì ở đó.

REST Endpoints

Tham khảo đầy đủ: OpenAPI trực tiếp tại /v1/api/commerce/doc/openapi.json. Route tùy biến:

Method	Path	Mục đích
POST	/product-variants/aggregate	Tạo variant + info + identifiers + MetaLinks
PATCH	/product-variants/{id}/aggregate	Cập nhật variant + info + identifiers một cách atomic

Phân giải identifier

GET /product-variants/{id} phân giải bằng:

1. Khớp ID trực tiếp
2. Khớp trường slug

ProductVariantService

File: src/services/product-variant.service.ts

Methods

Method	Mục đích
findByIdentifier({ identifier, filter?, transaction? })	Phân giải theo ID hoặc slug
createAggregate({ data, transaction? })	Tạo variant + info + identifiers + MetaLinks
updateByIdProductVariantAggregate({ id, data, transaction? })	Cập nhật variant + info + identifiers

Request createAggregate()

{
  // các trường ProductVariantInsertSchema
  productId: string;
  status?: string;

  // riêng cho aggregate
  info: ProductInfoInsertSchema;          // bắt buộc — { name: { en, vi }, description: { en, vi } }
  pricing?: PricingSchema;                // tùy chọn — pricing cấp variant
  metaLinks?: MetaLinkUpdateSchema[];     // tùy chọn — hình ảnh/asset (upsert theo ID)
  barcode?: string;                       // tùy chọn — tạo ProductIdentifier (scheme: BARCODE)
  sku?: string;                           // tùy chọn — tạo ProductIdentifier (scheme: SKU)
}

Nó làm gì:

1. Tạo hàng ProductVariant với metadata { merchantId, categoryId } từ Product cha
2. Tạo ProductInfo cho variant
3. Tạo ProductIdentifier với scheme SYSTEM (tự sinh)
4. Nếu sku được cung cấp: tạo ProductIdentifier với scheme SKU
5. Nếu barcode được cung cấp: tạo ProductIdentifier với scheme BARCODE
6. Upsert các bản ghi MetaLink nếu được cung cấp

Request updateByIdProductVariantAggregate()

{
  // các trường ProductVariantUpdateSchema (partial)
  info?: ProductInfoInsertSchema;     // cập nhật partial
  pricing?: PricingSchema;
  barcode?: string;                   // upsert identifier BARCODE
  sku?: string;                       // upsert identifier SKU
}

Sự kiện

Kênh	Tín hiệu	Khi nào	Consumer
CDC (Debezium)	public.ProductVariant	khi ghi hàng	Inventory (seed InventoryItem cho type STOCKABLE_SET), Pricing (init fare từ dữ liệu pricing), Search (index)

Commerce không emit cấp ứng dụng các topic Kafka product-variant.created/.updated — enqueue Kafka cập nhật variant (_enqueueProductVariantUpdated) đã bị comment out trong product-variant.service.ts. Lan truyền được điều khiển bởi CDC. Xem API Events.

Xóa

Được xử lý bởi DeletionPolicyService.deleteProductVariantById():

Điều kiện	Hành vi
Variant có lịch sử bán (orders)	HTTP 400 — archive thay vì xóa
Variant cuối cùng của product + canDeleteLastVariant=false	HTTP 409
Ngược lại	Đã xóa

Không có generateCombinations(), cartesianProduct(), hay endpoint sinh variant tự động. Variant được tạo từng cái một qua endpoint aggregate.

Trang liên quan

Trang	Mô tả
Tổng quan Commerce	Định danh dịch vụ + catalog
Domain Model	Bảng trường Variant + ProductVariantTypes
Products	Quản lý product cha
Pricing trong Commerce	Luồng dữ liệu pricing variant
ADR-0003	Mô hình bộ phân biệt variant type