FE: module order — đơn hàng (ADR-0073) #

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.

Đơn tạo ra từ chốt giỏ ở storefront (module checkout, channel: "web") hoặc do nhân viên tạo ở CMS (createOrder, channel: "admin", xem "Tạo đơn").

Hai trục trạng thái #

status:         placed ──confirm──► confirmed ──fulfill──► fulfilled ──complete──► completed
                  │                     │
                  └──────cancel─────────┴──► cancelled

paymentStatus:  unpaid → paid → partially_refunded / refunded

• status = vòng đời giao hàng, nhân viên chuyển (hoặc tự chuyển, xem dưới). Chuyển sai bước → 409 order_invalid_transition (details: { from, to }).
• paymentStatus = trục TIỀN, chỉ server đổi (module payments khi tiền về, module refund khi hoàn) — FE không đặt được. Giao hàng KHÔNG đòi đã trả (COD).
• Tiền về đủ khi đơn placed → đơn tự confirmed (paidAt có giá trị).
• paymentMethod (chọn lúc đặt, không đổi được): prepaid trả trước qua ý định thanh toán; cod thu khi giao, tiền về khi hãng nộp tiền thu hộ (module shipment). Đơn trước khi có trường này là prepaid.
• Ý định thanh toán hết hạn (mặc định 60 phút) mà đơn prepaid còn placed + unpaid → đơn tự cancelled, nhả kho, khi store bật order.auto_cancel ({ onPaymentExpiry: true }, mặc định). Đơn cod KHÔNG tự huỷ theo ý định: nhân viên xác nhận rồi giao; khi tạo vận đơn, điền sẵn codAmount = grandTotal. Store đặt order.auto_cancel.codUnconfirmedHours (số giờ, mặc định null = không) thì đơn cod còn placed quá số giờ đó tự cancelled (cancelReason: "COD not confirmed"), nhả kho. Việc này chạy mỗi giờ nên đơn có thể bị huỷ trễ tới một giờ.
• Mốc thời gian theo trạng thái: placedAt, confirmedAt, fulfilledAt, completedAt, cancelledAt, paidAt (null = chưa tới).

Tiền là chuỗi (subtotal, discountTotal, taxTotal, shippingTotal, offsetTotal, grandTotal) kèm currency.

CMS / admin (XforgeClient) #

Menu: key order.orders (quyền order.read).

• Danh sách: mới nhất trước; lọc status, payment_status, payment_method, channel, customer_id; q tìm theo số đơn; sắp created_at / updated_at / number. Phân trang theo con trỏ (phần chung §2).
• Nút theo actions: danh sách + chi tiết của nhân viên có actions: ("confirm" | "fulfill" | "complete" | "cancel" | "record_payment")[] — thao tác người gọi làm được lúc này (theo trạng thái + quyền order.manage / order.cancel / order.record_payment, đơn đã trả chưa hoàn đủ không có cancel). Bật / tắt nút theo đó, đừng tự suy từ status. Response storefront không có actions.
• actions không phải lời hứa: server vẫn có thể trả 409 khi bấm, nên luôn xử lý lỗi rồi tải lại đơn. cancel vẫn hiện mà gặp 409 order_paid_cancel khi tiền vừa về ý định nhưng đơn chưa kịp ghi nhận (chỉ biết được sau khi khoá); module khác có thể chặn bằng 409 mã riêng (vd shipment_on_the_way); hai người cùng thao tác → 409 order_invalid_transition.
• Giao: hàng đã giữ rời kho của đơn (warehouseInfo) bằng một phiếu xuất; lô / serial đã xuất ghi vào items[].detail. Lỗi của một dòng mang error.at = "items.<chỉ số>" (thiếu hàng, sai lô…) → tô dòng đó.
• Huỷ: nhả kho, huỷ ý định thanh toán còn chờ. Đơn đã trả (paid) phải hoàn ĐỦ trước (module refund, tới paymentStatus: refunded) — không thì 409 order_paid_cancel. Đơn đã fulfilled không huỷ được. Module khác có thể chặn bằng 409 mã riêng (vd shipment_on_the_way khi vận đơn đang đi) — hiện error.message.
• Chi tiết có thêm customerInfo (khách storefront), items, adjustments (giảm giá / phí từng dòng), shippingAddress, note, cancelReason, createdByInfo / updatedByInfo. Lịch sử thay đổi (ai đổi trạng thái lúc nào): listRecordChanges({ params: { resource: "orders", id } }) (quyền core.view_record_history + order.read).

• SMS báo khách (ADR-0104 của Core): màn cấu hình store sửa order.sms_notify (onPlaced, onConfirmed, onFulfilled, onCancelled; mặc định tắt — tin tính phí) qua PUT /api/v1/core/configs/order.sms_notify. Tin đi tới số khách nhập cho đơn (phone lúc chốt đơn); store cần có tài khoản SMS (core.sms_sender) hoặc dùng của nền tảng.

Tạo đơn #

Màn hình gọi quoteOrder mỗi khi đổi dòng / khách / mã / phí giao để hiện tổng tiền, rồi createOrder khi lưu. quoteOrder không giữ gì và KHÔNG kiểm tồn kho: thiếu hàng chỉ báo lúc createOrder.

• createOrder → { order, paymentCode }, một transaction: báo giá lại, giữ kho ở kho mặc định, tạo ý định thanh toán (order.paymentIntentId). Đơn 0 đồng luôn prepaid, đã paid, paymentCode: null.
• Lỗi của một dòng mang error.at = "lines.<chỉ số>" → tô dòng đó (ngừng bán 409 price_variant_unavailable, sai đơn vị / số lượng 400, thiếu hàng 409 stock_insufficient_available).
• customerId không có, thuộc store khác, đã xoá hay đã gỡ khỏi store đều trả CÙNG 404 order_customer_not_found (error.at = "customerId").
• Bật Idempotency-Key của client để bấm hai lần không thành hai đơn.

Thu tiền đơn prepaid: đơn chờ tiền về qua ý định thanh toán, tiền về đủ thì đơn tự confirmed.

• Đưa khách paymentCode / QR: getPaymentIntent({ params: { id: paymentIntentId } }) (payments.read) → code, transfer (VietQR), momo; hoặc gửi link trang trả tiền của storefront (id + paymentCode).
• MoMo: createPaymentIntentMomoCheckout (payments.write).
• Tiền đã vào tài khoản mà không tự khớp (sai nội dung…): listPaymentTransactions({ query: { status: "unmatched" } }) → matchPaymentTransaction({ params: { id }, body: { intentId: paymentIntentId } }) (payments.reconcile). Khớp giao dịch thiếu tiền thì ý định paid nhưng đơn vẫn unpaid, người xử lý tiếp. IPN MoMo thất lạc: queryPaymentIntentMomo.
• Thu tiền mặt / chuyển khoản / thẻ ngoài cổng: nút "Đã thu tiền" khi actions có record_payment (quyền order.record_payment) → recordOrderPayment({ params: { id }, body: { method, amount, reference } }). method: cash / bank_transfer / card / other. amount phải bằng grandTotal (409 order_payment_amount_mismatch: tải lại đơn); chưa hỗ trợ thu từng phần. Đơn đổi paid + tự confirmed khi job tiền về chạy, thường trong vài giây: đợi realtime order.changed hoặc đọc lại đơn, response có thể còn unpaid. Đơn không hợp lệ → 409 order_payment_not_recordable; ý định đã trả / huỷ → 409 payment_intent_not_payable. Đừng tạo ý định mới bằng createPaymentIntent trỏ vào đơn (đơn chỉ nhận tiền qua ý định của chính nó).
• Ý định hết hạn sau 60 phút: đơn còn placed + unpaid tự huỷ (cấu hình order.auto_cancel). Hẹn trả sau → bấm Xác nhận để giữ đơn; tiền đến sau đó nằm ở hàng chờ, khớp tay như trên.

Đơn cod: không tự huỷ theo ý định; tiền về khi hãng nộp tiền thu hộ (remitShipmentCod, module shipment). Lệnh tạo đơn của nhân viên KHÔNG áp checkout.payment_methods (cấu hình đó là lựa chọn của người mua lúc chốt đơn); database chưa nâng cấp → 409 order_cod_unavailable.

Báo cáo #

Dùng màn báo cáo chung (listReports, runReport, exportReport; form dựng từ params), đều cần order.read.

Định nghĩa doanh thu (một nghĩa cho cả ba báo cáo): đơn có placedAt nằm trong khoảng ngày THEO GIỜ STORE, không tính đơn cancelled, CHƯA trừ hoàn tiền, kể cả đơn chưa thu tiền. Đơn huỷ về sau tự rời báo cáo của ngày đặt; hoàn tiền thì không.

• order.daily_revenue: total = grandTotal (số khách phải trả, gồm phí giao, đã trừ offset là thẻ quà / điểm). subtotal là tiền hàng trước giảm, tax có thể đã nằm trong subtotal (giá đã gồm thuế) nên đừng tự cộng các cột thành total. Dòng tổng ở summary; summary: null khi store có đơn nhiều tiền tệ.
• order.status_summary: CÓ đơn huỷ (dòng status: "cancelled") để đếm; đừng lấy tổng cột total làm doanh thu.
• order.top_products: qty theo ĐƠN VỊ GỐC (unit), revenue = tiền dòng sau giảm giá, gồm thuế, KHÔNG gồm phí giao và chưa trừ offset, nên tổng revenue khác total của order.daily_revenue. Sản phẩm đã vào thùng rác có sku / product null.
• Mỗi tiền tệ một dòng; ô tiền là chuỗi, đừng đổi sang số.

Xuất file #

Tập order.orders CHỈ xuất (listDatasets, exportDataset, startDatasetExport, quyền order.read): một dòng một đơn, sớm nhất trước, có tên / email / điện thoại khách; không có dòng hàng, địa chỉ, ghi chú. Không có file mẫu / nhập.

In + gửi hoá đơn #

Mẫu order.invoice: HOÁ ĐƠN BÁN HÀNG, KHÔNG phải hoá đơn VAT (hoá đơn VAT của cấu hình payments.einvoice). Xem: printDocument({ params: { name, id } }), quyền order.read. Gửi email: emailDocument, quyền order.send_invoice (canEmail ở listPrintables), luôn tới customerEmail của đơn, không nhập được địa chỉ khác; đơn không có email → 409 print_recipient_missing.

Thông báo, realtime, webhook #

• Thông báo order.new khi đặt đơn ở mọi kênh, tới nhân viên có order.manage, kèm Web Push; link: { key: "order.orders", id }. Đến trễ vài giây.
• Realtime order.changed (data: { orderId }, người có order.read): đặt, đổi trạng thái, huỷ, tiền về, cả khi do server tự làm. Nhận rồi đọc lại đơn qua API. Hoàn tiền chưa phát sự kiện này.
• Webhook gửi đi (màn "Tích hợp", listWebhookEvents): data chỉ có orderId, number, status, paymentStatus, currency, grandTotal, không dữ liệu cá nhân.
  • order.placed.
  • order.status_changed: thêm previousStatus, previousPaymentStatus. Phát cả khi chỉ tiền đổi (status = previousStatus). Không phát khi huỷ và khi hoàn tiền.
  • order.cancelled.

Storefront (StorefrontClient) #

Chỉ đơn của CHÍNH khách đang đăng nhập (đơn của người khác → 404 order_not_found); không có kho / người tạo.

• listMyOrders({ query }) — mới nhất trước, lọc status, phân trang theo con trỏ.
• getMyOrder({ params: { id } }) — chi tiết + dòng. Có paymentIntentId + paymentCode: còn unpaid thì hiện nút "Thanh toán" mở trang trả tiền của module payments (getStorefrontPaymentIntent({ params: { id: paymentIntentId }, query: { code: paymentCode } })). paymentCode: null = đơn 0 đồng.
• cancelMyOrder({ params: { id }, body: { reason? } }) — chỉ khi đơn còn placed VÀ chưa trả (409 order_invalid_transition / order_paid_cancel). Hiện nút chỉ trong điều kiện đó.

Lỗi cần xử lý #