FE: module price_list — bảng giá #
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.
Chỉ có ở CMS (XforgeClient). Storefront không gọi gì: giá của bảng hiện thẳng
trong giỏ / chốt đơn (lines[].unitPrice, priceSource: "price_list"; giá
catalog mang nguồn khác — base, explicit, converted — nên chỉ so với
"price_list").
Menu: key price_list.price_lists (quyền price_list.read).
Bảng giá #
Bộ route CRUD chuẩn (listPriceLists, getPriceList, createPriceList,
updatePriceList, replacePriceList, deletePriceList, restorePriceList,
listPriceListTrash, listPriceListOptions).
| Field | Ghi chú |
|---|---|
channel | all (mặc định), web, pos, admin — kênh bán áp dụng |
audience | all (mọi người mua, mặc định) hoặc customers (chỉ khách được gán) |
startsAt | endsAt — ISO UTC; null = không giới hạn |
Tiền tệ là tiền tệ của store lúc tạo. Response có itemCount, customerCount.
Giá và khách #
listPriceListItems/setPriceListItems({ body: { items } })— thay TOÀN BỘ dòng giá (≤ 2000). Mỗi dòng:variantId,uomId(null hoặc đơn vị gốc = đơn vị gốc, lưu null; đơn vị khác phải là đơn vị bán của sản phẩm),minQty(theo đơn vị bán, mặc định 1),price(đơn giá theo đơn vị bán, cùng quy ước thuế với giá catalog). Nhiều dòng cùng biến thể + đơn vị = bậc số lượng. Lỗi theo dòng:price_list_variant_not_found/price_list_uom_not_foundvớierror.at = "items.<i>"; trùng dòng → 409price_list_item_duplicate.listPriceListCustomers/setPriceListCustomers({ body: { customerIds } })— thay TOÀN BỘ khách (≤ 2000), dùng khiaudience: customers. Khách không thuộc store → 409price_list_customer_not_foundvớierror.at = "customerIds.<i>".
Xuất / nhập file (dataset price_list.prices) #
Màn hình chung của Core (docs/fe/cms.md §7). Xuất cần price_list.read, nhập
cần price_list.update. Mỗi dòng = một dòng giá; khoá là priceListCode +
sku + uomCode + minQty. Dòng đã có → sửa giá; chưa có → thêm; nhập lại
cùng file không nhân đôi (skipped).
| Cột | Ghi chú |
|---|---|
priceListCode | bắt buộc; bảng giá phải có sẵn, file không tạo bảng giá |
sku | bắt buộc; biến thể của sản phẩm trong store, không trong thùng rác |
uomCode | trống hoặc đơn vị gốc = đơn vị gốc; đơn vị khác phải là đơn vị bán của sản phẩm |
minQty | mặc định 1; 10 và 10.00 là cùng một bậc |
price | bắt buộc, chuỗi ≥ 0, theo định dạng loại tiền của bảng |
currency | tuỳ chọn; có thì phải đúng tiền của bảng (price_list_currency_mismatch) |
productCode | chỉ có ở file xuất, để đọc; nhập bỏ qua |
- KHÔNG xoá: dòng giá vắng khỏi file giữ nguyên. Thay cả bộ / xoá dòng:
setPriceListItems. Thêm tới trần 2000 dòng một bảng →price_list_too_many_items. - Giá VND không có số lẻ:
95000hay95000.0000được,95.000(dấu chấm ngăn nghìn gõ nhầm) →price_list_price_format. Giá lẻ hơn đơn vị của loại tiền chỉ đặt được quasetPriceListItems; dòng đã có mà giá không đổi thì vẫn nhập lại được. Giá là ô chữ trong Excel: nhập số lẻ thì để ô dạng Text. dryRun=truechỉ kiểm định dạng ô; mã sai chỉ lộ khi nhập thật. Dòng lỗi đầu tiên huỷ cả file; lỗi nằm trongerrors[].code+line:price_list_not_found,price_list_variant_not_found,price_list_uom_not_found,price_list_item_duplicate(hai dòng cùng khoá trong file), và các mã ở trên.- Lần nhập ghi lịch sử giá vào lịch sử bảng giá
(
items.<variantId>.<uomId | base>.<minQty>.price).
Giá nào được dùng #
Trong báo giá, mỗi dòng nhận giá THẤP NHẤT giữa giá catalog và giá của mọi bảng đang áp (đúng kênh, tiền tệ, trong thời gian hiệu lực, đúng khách, đủ bậc số lượng). Không có thứ tự ưu tiên giữa các bảng. Giá cao hơn catalog không bao giờ được dùng.