Ecommerce Module

Mục đích

ecommerce là cụm domain vận hành lớn nhất của Diva. Đây không phải một feature đơn lẻ mà là tập hợp nhiều subdomain cùng nằm dưới một route tree:

• bán hàng dịch vụ, mỹ phẩm, thẻ trả trước,
• thanh toán, công nợ, commission, hoàn tiền,
• lịch hẹn, tour, project task,
• sản phẩm, kho, phiếu nhập/xuất/chuyển/kiểm,
• voucher, campaign, quỹ, approval requests và một số nhánh ops/governance đi kèm.

Điểm quan trọng nhất: cùng nằm trong module FE ecommerce, nhưng ownership kỹ thuật thực tế bị tách mạnh giữa ecommerce-api, wallet-api, settings, projects, hrm, crm và nhiều nguồn dữ liệu Hasura.

Quy mô

• 135 FE pages
• 338+ tables/views liên quan
• Route tree phức tạp nhất repo
• Event handler lớn nhất: invoice_insert_update.go

Actors & Permissions

Role	Quyền chính	Scope
Staff	Tạo/xem order, tạo appointment, thao tác runtime nghiệp vụ	Self + branch
Manager	Duyệt một số request, xem dữ liệu chi nhánh, xử lý refund/ops theo branch	Branch
Admin / IT / BOD	Toàn quyền route sâu, config, import/export, approval nhiều cấp	System

Feature Groups

Group	Mô tả	Docs
Orders & Payments	Service order, product order, prepaid order, invoice, commission, refund, negative payment	orders.md · orders.technical.md
Services & Appointments	Service config boundary, order item service, appointment, tour, project task, reminder	services.md · services.technical.md
Products & Inventory	Product master, warehouse, stock ledger, import/export, transfer, check sheet, internal order	inventory.md · inventory.technical.md
Promotions & Requests	Prepaid, voucher campaign, withdraw/refund, fund management, negative payment, mounted vs dormant routes	requests.md · requests.technical.md

Đặc điểm kiến trúc

• service được cấu hình ở settings, nhưng runtime bán hàng/lịch hẹn/tour chạy ở ecommerce.
• Tồn kho không đọc trực tiếp từ một bảng snapshot đơn giản; product_supplying là ledger movement, còn product_sku_stock / product_lot_no_stock là read model.
• Payment flow không đồng nhất giữa các loại order:
  • service/prepaid ưu tiên backend action createInvoiceTransaction,
  • product order vẫn còn nhánh insert invoice trực tiếp ở FE.
• refund/withdraw đi qua wallet.transaction_request, còn negative payment đi qua hrm.request_working_schedule.
• promotion có code, GraphQL và permission mapping, nhưng route mount trong module.ts đang bị comment.

Liên kết Modules

• wallet — transaction_request, refund, commission payout, wallet revenue.
• settings — service config, commission setting, prepaid/affiliate policies, app settings.
• projects — project_task, project_task_assignee, tour money.
• user — customer, consultant, staff, branch, department.
• crm — appointment/ticket touchpoints, reminder follow-up.
• notification — noti order, noti refund, reminder appointment, voucher activation.
• report — dashboard doanh số, công nợ, voucher, prepaid, quỹ.
• salary + timekeeping + hrm — tour money, doctor commission, negative payment approval.

Backend Services

Service	Vai trò
ecommerce-api	Action + event chính cho order, invoice, inventory, appointment, voucher
wallet-api	Refund, transaction request lifecycle, rollback commission, wallet revenue
controller (Hasura)	GraphQL metadata, actions, event triggers, cron trigger
export-api	Export file/report/invoice
notification-api / notification-v2-api	Reminder, voucher/order/refund notifications

Databases

DB	Vai trò
ecommerce	order, order_item, invoice, appointment, product, inventory_*, voucher_*, fund, promotion
wallet	transaction, transaction_request, transaction_request_user, wallet revenue/refund
project	project_task, project_task_assignee, workflow tour
hrm	request_working_schedule cho negative payment / doctor commission touchpoint
notification	template và một phần side effect gửi thông báo

Deep Dives

• refund-withdraw — đào sâu refund order, withdraw, refund commission, negative payment và approval chain
• inventory-operations — đào sâu stock movement engine, snapshot vs ledger và approval/adjustment flows

Ghi chú coverage

• Bộ doc hiện tại đã đủ để tra cứu theo 4 domain lớn của ecommerce.
• Một số nhánh governance/ops như device requests, violation record, league/fund ancillary screens vẫn mới ở mức overview trong các doc domain liên quan, chưa tách thành feature doc riêng.