FE: module gift_card — thẻ quà #

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.

CMS / admin (XforgeClient) #

Menu: key gift_card.gift_cards (quyền gift_card.read). Route CRUD chuẩn, không thùng rác: listGiftCards, getGiftCard, createGiftCard, updateGiftCard, deleteGiftCard, listGiftCardOptions; thêm adjustGiftCard, listGiftCardTransactions, refundOrderToGiftCard và listGiftCardOrderRefundables.

• Mã là tiền của người cầm. Response của createGiftCard có ĐỦ mã một lần: in / gửi cho người mua ngay. Gửi lại cùng Idempotency-Key KHÔNG trả lại mã (409 idempotency_response_withheld, thẻ không phát thêm, response không có id thẻ): tìm thẻ vừa tạo ở listGiftCards (mới nhất trước); chỉ người có quyền gift_card.view_code mới xem lại được ĐỦ mã (getGiftCard) — người chỉ có gift_card.create mất response lần đầu thì phải nhờ người có quyền. Sau đó code bị che (****ABCD, codeMasked: true) trừ khi người dùng có quyền gift_card.view_code.
• Danh sách không tìm theo một phần mã. Tra thẻ khách mang tới: listGiftCards({ query: { code: "<đủ mã>" } }) (không phân biệt hoa / thường, gạch, khoảng trắng).
• adjustGiftCard({ body: { amount, note } }): amount có dấu (dương = nạp, âm = trừ), note bắt buộc. Số dư không được âm → 409 gift_card_insufficient_balance (details.balance).
• deleteGiftCard chỉ xoá thẻ chưa từng dùng; thẻ đã có giao dịch → 409 gift_card_in_use, hãy tắt active.
• listGiftCardTransactions: sổ của thẻ, mới nhất trước, phân trang con trỏ: issue, redeem (trả cho đơn, số âm, kèm orderInfo), release (về lại thẻ khi đơn huỷ hoặc nhân viên hoàn, kèm orderInfo; note là lý do hoàn), adjust. balance là số dư sau giao dịch.

Hoàn phần thẻ của đơn về lại thẻ #

refundOrderToGiftCard hoàn riêng phần đơn đã trả bằng thẻ, nhân viên quyết số tiền. createRefund (module refund) chỉ hoàn tiền mặt / chuyển khoản, hệ thống KHÔNG tự chia một lần hoàn giữa tiền và thẻ. Màn chi tiết đơn:

1. listGiftCardOrderRefundables({ query: { order_id } }) (quyền gift_card.read): mỗi thẻ đã trả cho đơn một dòng giftCardId, giftCardInfo (code luôn che, currency, balance, active), redeemed, released, refundable. Danh sách rỗng = đơn không trả bằng thẻ, ẩn nút. refundable là "0" thì tắt nút (đơn chưa trả xong, đã hoàn hết hoặc đã huỷ).
2. refundOrderToGiftCard({ body: { orderId, giftCardId, amount, reason? } }) (quyền gift_card.adjust). amount làm tròn theo tiền tệ, tối đa refundable. Response là dòng ở bước 1 đã cập nhật, kèm orderId, orderInfo, amount (số vừa hoàn). reason lưu vào note của dòng sổ release.

Đơn huỷ sau đó chỉ trả về thẻ phần còn lại; đơn đã huỷ thì refundable là "0". Hoàn về thẻ KHÔNG đổi status / paymentStatus của đơn. Thẻ đang tắt / hết hạn vẫn nhận lại tiền.

Storefront #

Không có route riêng: khách nhập mã thẻ vào giỏ như mã giảm giá (setMyCartCodes, trang module cart); được nhập nhiều thẻ. Thẻ trả phần còn lại của đơn SAU giảm giá, thuế và phí giao: giỏ và đơn có khoản trong adjustments (source: "gift_card", scope: "offset") và totals.offsetTotal. code của khoản này đã bị che (****ABCD) ở giỏ, báo giá và đơn — mã đủ chỉ còn trong codes của giỏ (của chính khách).

• Giỏ chưa có phí giao, nên số thẻ trả ở giỏ có thể nhỏ hơn lúc chốt đơn (chốt đơn cộng phí giao rồi mới trừ thẻ). Thẻ đủ trả cả đơn thì grandTotal là 0 và đơn không cần thanh toán thêm.
• Thẻ không dùng được → 409 gift_card_not_applicable, details.reason: inactive, expired, no_balance, currency_mismatch; mã không được lưu (hoặc nằm trong rejectedCodes nếu đã lưu trước). Chốt đơn khi đó cũng trả lỗi này — bỏ mã (setMyCartCodes) rồi chốt lại.
• Số dư bị trừ lúc chốt đơn. Đơn huỷ thì phần đã trừ về lại thẻ. Nhân viên hoàn phần thẻ của đơn đã trả bằng thao tác riêng (mục CMS); hoàn tiền (refund) chỉ là tiền mặt / chuyển khoản.