FE: module product — sản phẩm, biến thể, thuộc tính #

Phần chung (khởi tạo client, lỗi, danh sách, ngôn ngữ) ở tài liệu FE của Core: docs/fe/common.md (bản đọc: xforge-documentation, ADR-0102 của xforge-core). Sửa file này CÙNG PR khi đổi hành vi FE thấy được của module.

Mô hình #

sản phẩm (code, status, brand, category, đơn vị gốc, ảnh, bản dịch, version)
  ├─ đơn vị bán thêm  uoms[]: { uomId, factor }      (vd thùng = 24 lon)
  └─ biến thể         variants[] (≥ 1): sku, barcode, price, compareAtPrice, currency,
                        options[] (một giá trị mỗi thuộc tính: Màu = Đỏ, Size = M),
                        unitPrices[] (giá theo MỌI đơn vị bán, đơn vị gốc trước)
thuộc tính  attributes (Màu, Size…) + values (Đỏ, Xanh… có thể có màu swatch #RRGGBB)

• Sản phẩm không có lựa chọn = MỘT biến thể options: []. Mọi biến thể của một sản phẩm dùng CÙNG bộ thuộc tính, mỗi tổ hợp một lần.
• status: draft (soạn) → active (bán) → archived (ngừng). Lên active cần ít nhất một bản dịch VÀ một biến thể đang bật (409 product_not_publishable).
• unitPrices[].source: base (giá của biến thể), explicit (đặt tay cho đơn vị đó), converted (= price × factor). Tiền là chuỗi.
• Field dịch được (name, shortDescription, description, slug, metaTitle, metaDescription): phần chung §3.3.

CMS / admin (XforgeClient) #

Menu: key product.products (quyền product.read).

• Khoá phiên bản: mọi lần sửa sản phẩm HOẶC biến thể gửi version của sản phẩm đã đọc. Người khác lưu trước → 409 version_conflict (details.currentVersion): tải lại, cho người dùng so rồi lưu lại. Mỗi thao tác biến thể trả LẠI cả sản phẩm (có version mới) — dùng nó cho lần sửa kế.
• Danh sách: lọc status, featured, brand_id, category_id (in_category = danh mục + mọi danh mục con), base_uom_id; q tìm mã và mọi tên đã dịch.
• translations, imageFileIds, uoms gửi = thay cả bộ. Bỏ một đơn vị bán thêm = bỏ luôn giá đặt tay theo đơn vị đó của các biến thể.
• listProductVariantOptions mặc định KHÔNG lọc trạng thái — chỉ lấy hàng bán được: query: { status: "active", active: "true" }. optionsLabel (vd Đỏ / M) để hiện trong picker.
• Ảnh: tải qua module files rồi gửi imageFileIds (thứ tự = thứ tự hiện).
• Xoá sản phẩm / biến thể có thể bị module khác chặn khi còn tồn kho / đơn mở (409 mã của module đó — hiện error.message).

Xuất / nhập file (dataset product.products) #

Màn hình chung của Core (docs/fe/cms.md §7, listDatasets, exportDataset, importDataset…). Xuất cần product.read. Nhập cần product.update; dòng tạo SẢN PHẨM mới cần thêm product.create (không có → forbidden ở đúng dòng).

Mỗi dòng = một biến thể, khoá là SKU; các dòng cùng productCode là một sản phẩm. Nhập lại cùng file không nhân đôi: dòng không đổi tính skipped, sản phẩm không tăng version.

• Sản phẩm mới cần name + baseUomCode (product_import_missing_fields).
• Cột sản phẩm: chỉ cần điền ở một dòng; đã điền nhiều dòng thì phải giống nhau.
• Ô trống = giữ nguyên (sản phẩm mới: giá trị mặc định). Vì vậy file KHÔNG xoá được giá trị (bỏ thương hiệu, xoá mã vạch…) và không xoá biến thể / sản phẩm: dùng form.
• File xuất ghi bản dịch của ngôn ngữ MẶC ĐỊNH; bản dịch ngôn ngữ khác giữ nguyên. Sửa tên không đổi slug đã có.
• Tiền là ô chữ, đúng định dạng tiền của loại tiền: 150000 hoặc 150000.0000 được; 150.000 của tiền VND bị từ chối (dấu chấm ngăn nghìn gõ nhầm). Khi nhập số lẻ trong Excel, để ô dạng Text (Excel có thể lưu 19.99 thành 19.989999999999998, dòng đó bị từ chối).
• Không có trong file, sửa ở form: ảnh, description (mô tả dài, quá sức một ô file), đơn vị bán thêm + giá theo đơn vị, nhóm thuế (module tax). Nhập KHÔNG đụng các phần này. File có cột khác danh sách trên (store_id, imageFileIds…) bị từ chối unknown_column.
• SKU của sản phẩm trong thùng rác → product_sku_exists: khôi phục sản phẩm trước.
• dryRun=true chỉ kiểm định dạng ô. Mã thương hiệu sai, SKU trùng, thiếu quyền tạo… chỉ lộ khi nhập thật; dòng lỗi đầu tiên huỷ cả file.

Lỗi nhập nằm trong errors[] (HTTP vẫn 200, applied: false): line, code, message. Hiện message: câu đã dịch, đã có sẵn mã / cột cụ thể (item không có details).

Storefront (StorefrontClient) #

Không cần đăng nhập. Chỉ sản phẩm active, có bản dịch và ít nhất một biến thể đang bật; trả kèm các biến thể đang bật.

• listPublicProducts({ query }) — trang danh mục / tìm kiếm (≤ 50 / trang; không có mô tả dài / SEO). Lọc featured, brand_id, category_id, in_category; q tìm; sắp sort_order / code / created_at.
• getPublicProductBySlug({ params: { slug } }) — trang sản phẩm, có description, metaTitle, metaDescription cho SEO. Slug của ngôn ngữ nào cũng khớp (ngôn ngữ request trước).
• Chọn biến thể: dựng bộ chọn từ variants[].options (attributeInfo → nhóm, valueInfo → lựa chọn, có swatch). Hiện price / compareAtPrice của biến thể đã chọn; bán theo đơn vị khác (thùng…) dùng unitPrices. Giá cuối (khuyến mãi, mã giảm) chỉ có ở giỏ (module cart).
• Ảnh: images[].fileInfo.id → <img src="/api/v1/storefront/products/images/{fileId}"> trên tên miền của store (route công khai, chỉ ảnh raster của sản phẩm đang bán, cache 5 phút, ETag). Dev không có tên miền store (chỉ x-store): tải bằng getPublicProductImage rồi tạo object URL.
• brandInfo / categoryInfo = null khi thương hiệu / danh mục đang ẩn khỏi storefront — đừng dựng link tới chúng.

Lỗi cần xử lý #