MEDUSA DOCUMENT
MEDUSA DOCUMENT
Tài liệu Medusa mô tả toàn bộ hệ thống theo sidebar Admin live: Medusa Core, Extensions, mobile app, media, promotion, payment và checklist BA.
1. Sơ đồ
2.1 Sơ đồ tổng quan hệ thống
Medusa AdminAdmin/BA/Ops cấu hình dữ liệu
→
Medusa BackendAPI + business rule + xử lý dữ liệu
←
Flutter Mobile AppKhách xem menu, đặt hàng, thanh toán
↓
PostgreSQLLưu dữ liệu chính
Cloudflare R2Lưu ảnh/media
PayOS / VNPayCổng thanh toán
iPOS / FABiĐồng bộ menu/order
Mailgun / SESEmail giao dịch
2.2 Sơ đồ luồng dữ liệu mobile
1. Admin cấu hìnhMedia, menu, branch, promotion, sales policy
→
2. Backend lưuDatabase + metadata + modules
→
3. Store APImobile-bootstrap, mobile-menu, mobile-media
↓
4. Mobile hiển thịHome, Menu, Store, Media
→
5. Khách thao tácChọn sản phẩm + modifier
→
6. Cart/FulfilmentDelivery hoặc Pickup
↓
7. PromotionAuto promotion / voucher
→
8. PaymentPayOS hoặc VNPay
→
9. AuditOrders + Payment Audit + Logs
2.3 Sơ đồ nhóm Admin theo sidebar live
Admin SidebarToàn bộ menu quản trị
Medusa Core
Orders
Drafts
Products
Product Attributes
Stores
Inventory
Customers
Promotions
Price Lists
Extensions
Discount Rules
Promotion Catalog
24H Settings
Logs
Menus
3. Mô tả từng mục Admin
| Mục | Trong mục có gì | Tác dụng | Ảnh hưởng |
|---|---|---|---|
| Orders | Danh sách đơn, chi tiết đơn, khách hàng, sản phẩm, modifier, tổng tiền, payment status, fulfilment status | Theo dõi và xử lý đơn hàng sau khi khách đặt | Đơn mobile phải đúng sản phẩm, giá, promotion, payment và trạng thái |
| Drafts | Đơn nháp, khách hàng, item, giá tạm tính | Giữ đơn chưa hoàn tất hoặc admin tạo đơn | Draft chưa hoàn tất không được tính như đơn thật |
| Products | Tên, ảnh, mô tả, giá, variant, category/collection, status | Nguồn dữ liệu sản phẩm để bán | Product active hiển thị đúng; inactive không hiển thị sai; giá/ảnh/tên đúng trên app |
| Product Attributes | Nhóm thuộc tính và giá trị thuộc tính sản phẩm | Gắn đặc điểm cho sản phẩm để lọc hoặc áp promotion | Promotion/filter theo attribute áp dụng đúng sản phẩm |
| Stores | Store, sales channel, location, region hoặc cấu hình store core | Quản lý nơi bán/kênh bán theo Medusa core | Không lẫn core store với branch/cửa hàng hiển thị trên mobile |
| Inventory | SKU, số lượng tồn, location tồn kho, trạng thái khả dụng | Quản lý còn hàng/hết hàng | Nếu bật kiểm tồn, sản phẩm hết hàng phải bị chặn hoặc hiển thị đúng |
| Customers | Danh sách khách, email, phone, lịch sử đơn, metadata | Quản lý tài khoản khách hàng | Login OTP/email/google gắn đúng customer; đơn hàng gắn đúng khách |
| Promotions | Campaign, rule, code, budget, status của Medusa core | Quản lý khuyến mãi mặc định của Medusa | Cần phân biệt với Promotion Engine custom, tránh nhầm rule |
| Price Lists | Bảng giá theo sản phẩm/variant, kênh bán, nhóm khách hoặc điều kiện | Thiết lập giá khác nhau theo kịch bản bán hàng | Giá mobile đúng theo channel, fulfilment và customer group nếu có |
| Discount Rules | Rule giảm giá, điều kiện áp dụng, trạng thái | Cấu hình giảm giá theo extension/custom | Không xung đột với Promotion Engine custom, giảm đúng điều kiện |
| Promotion Catalog | Branches, mobile menus, product attributes, product modifiers, membership tiers, loyalty | Dữ liệu nền cho mobile và promotion | Inactive không hiển thị/sử dụng sai; branch/tier/attribute áp rule đúng |
| 24H Settings | Mobile settings, media settings, R2 settings, promotion, sales, sync | Cấu hình trực tiếp app và hệ thống 24H | Sau lưu, mobile/store API đọc đúng dữ liệu mới |
| Logs | Customer logs, payment logs, system logs | Debug lỗi khách hàng, thanh toán và backend | Log đủ message/status/error/payload cần thiết |
| Menus | Menu list, menu detail, section detail, item detail | Quản lý cấu trúc menu custom | Section/item đúng thứ tự, inactive không hiển thị, item điều hướng đúng |
4.1 Nội dung các mục Extension quan trọng
| Mục cha | Mục con | Trong mục có gì | Tác dụng | Ảnh hưởng |
|---|---|---|---|---|
| Promotion Catalog | Branches | Cửa hàng, địa chỉ, tọa độ, giờ mở cửa | Nguồn cửa hàng cho pickup/delivery/promotion | Mobile chọn cửa hàng, tính km, áp promotion theo branch |
| Promotion Catalog | Mobile Menus | Menu, section, item | Cấu hình menu đồ uống mobile | Mobile hiển thị menu theo cấu trúc này |
| Promotion Catalog | Product Attributes | Thuộc tính/giá trị sản phẩm | Điều kiện lọc/promotion | Promotion áp dụng đúng nhóm sản phẩm |
| Promotion Catalog | Product Modifiers | Nhóm topping/option | Cấu hình câu hỏi khi chọn sản phẩm | Product detail và cart total |
| Promotion Catalog | Membership Tiers | Hạng thành viên | Phân nhóm khách theo tier | Promotion/quyền lợi theo hạng |
| Promotion Catalog | Loyalty | Tài khoản điểm, ledger điểm | Theo dõi điểm khách hàng | Màn tài khoản/ưu đãi khách hàng |
| 24H Settings | Mobile Settings | Splash, popup, hero, feed, logo, menu banner, price, access, app release, contact/legal | Cấu hình trực tiếp mobile app | Giao diện và hành vi mobile |
| 24H Settings | Media Settings | Asset ảnh, placement, status, order, schedule, target URL | Quản lý media tập trung | Ảnh hiển thị trong app |
| 24H Settings | Cloudflare R2 Settings | Account, bucket, CDN URL, access key, secret key, env/status | Cấu hình nơi lưu ảnh | Upload ảnh thành công/thất bại |
| 24H Settings | Sales Settings | Login rule web/mobile, guest fields | Quy định khách phải login khi nào | Guest/login flow |
| 24H Settings | Sync Settings | Cấu hình đồng bộ | Điều khiển sync hệ thống ngoài | iPOS/FABi/menu/order |
| Logs | Customer logs | Sự kiện/liên quan khách hàng | Debug login/account/order | Hỗ trợ truy lỗi khách |
| Logs | Payment logs | Log thanh toán PayOS/VNPay | Debug payment/callback/webhook | Hỗ trợ truy lỗi thanh toán |
| Logs | System logs | Log hệ thống | Theo dõi lỗi backend/tích hợp | Hỗ trợ vận hành |
4. Phân hệ Mobile Settings / Media
Cách hiểu bảng Media: Kích cỡ đề xuất là chuẩn để đội design xuất ảnh. Ảnh hiện tại trong Media là kích cỡ thật của ảnh đang có trên Admin/CDN. Nếu ảnh hiện tại khác tỉ lệ khuyến nghị thì vẫn có thể hiển thị, nhưng có rủi ro bị crop, lệch hoặc mất chữ/CTA.
| Media | Dùng ở đâu | Tỉ lệ khuyến nghị | Kích cỡ đề xuất | Ảnh hiện tại trong Media | Đánh giá | Rủi ro/Ghi chú design |
|---|---|---|---|---|---|---|
| Splash | Mở app | 9:16 | 1080 x 1920 | 1126 x 2437 | Gần đúng tỉ lệ 9:16 | Ảnh full màn hình, nội dung chính không đặt sát mép. |
| Home popup | Popup trang chủ | 3:4 | 1080 x 1440 | 706 x 913 | Chưa đạt tỉ lệ 3:4 | Ảnh hiện tại thiếu chiều cao so với chuẩn; cần export lại theo 1080 x 1440, 900 x 1200 hoặc 750 x 1000. Tránh đặt chữ/CTA sát mép. |
| Home hero | Banner trang chủ | Xấp xỉ 144:65 | 1440 x 650 | 16 ảnh, đa số 1080 x 1135; một số 1080 x 1134 | Chưa khớp chuẩn banner ngang | Ảnh hiện tại là ảnh dọc/cao hơn chuẩn banner ngang, dễ bị crop mạnh nếu khung hiển thị dạng banner. Đội design cần xác nhận lại khung app thật trước khi xuất lại. |
| Home feed | Card promo | 2:1 | 1200 x 600 | 6 ảnh 991 x 403/404; 1 ảnh wide 1080 x 164 | Chưa đồng bộ tỉ lệ | 6 ảnh đầu gần 2.45:1, ảnh wide rất mỏng. Cần chốt lại một tỉ lệ dùng chung để tránh card cao thấp không đều. |
| Brand logo | Logo/badge | 1:1 hoặc file trong suốt | Logo vuông/transparent | 143 x 142 | Gần đúng 1:1 | Ưu tiên PNG/WebP nền trong suốt; tránh logo bị mờ, lệch hoặc dư nền. |
| Menu banner | Banner menu đồ uống | 16:7 | 1600 x 700 hoặc 1280 x 560 | Chưa có asset trong bộ backfill | Thiếu dữ liệu | Banner ngang trong menu; giữ nội dung chính ở vùng an toàn để tránh crop/lệch UI. |
Rule upload hiện tại: output WebP, quality 0.82, cạnh dài tối đa 1440px, dung lượng tối đa 2 MB, lưu Cloudflare R2.
Số đo "Ảnh hiện tại trong Media" ở bảng trên được scan từ bộ ảnh nguồn dùng trong script backfill Media local. API live đang trả 400 khi gọi từ môi trường này, nên nếu Admin live đã thay ảnh thủ công sau backfill thì cần mở Media Settings để đối chiếu lại URL/kích cỡ thực tế.
6. Phân hệ Product Modifier
| Entity | Ý nghĩa |
|---|---|
| ProductModifierGroup | Nhóm topping/câu hỏi |
| ProductModifierOption | Lựa chọn trong nhóm |
| ProductModifierGroupOption | Liên kết group-option |
| ProductModifierProductGroup | Liên kết product-group |
Checklist: min/max selection đúng, option bắt buộc không được bỏ qua, giá pickup/delivery đúng, tổng tiền cập nhật đúng.
7. Phân hệ Branch / Store
| Nội dung | Mô tả |
|---|---|
| Dùng cho | Chọn cửa hàng pickup, tìm cửa hàng gần bạn, promotion theo branch |
| Dữ liệu | Tên, địa chỉ, phone, giờ mở cửa, latitude, longitude, image |
| Checklist | Danh sách đúng, tìm kiếm đúng, km hợp lý, reload có trạng thái tải, chi tiết cửa hàng đúng |
8. Phân hệ Promotion
| Phần | Mô tả |
|---|---|
| Promotion Catalog | Dữ liệu nền: branch, tier, loyalty, attribute |
| Promotion Engine | Tạo rule khuyến mãi/voucher |
| Voucher | Mã giảm giá có usage limit/status |
| Rule types | cart_adjustment, product_adjustment, buy_x_get_x, buy_x_get_y, bundle_fixed_price, free_gift, free_shipping |
9. Phân hệ Auth / Account
| Luồng | API |
|---|---|
| OTP phone | /store/auth/otp/send, /verify |
| Email login/register | /store/auth/email/login, /register |
| Google OAuth | /store/auth/google/config, /callback |
| Refresh/logout | /store/auth/session/refresh, /logout |
| Change email/phone | /store/account/email/change, /phone/change |
10. Phân hệ Cart / Payment / Logs
| Nhóm | BA cần kiểm tra |
|---|---|
| Cart | Sản phẩm, modifier, quantity, total |
| Fulfilment | Delivery/pickup, store/address |
| Promotion | Auto promotion, voucher |
| Payment | PayOS, VNPay, callback, status |
| Audit | Amount, status, error, payload |
| Logs | Customer/payment/system log |
11. Rủi ro + Checklist
| ID | Rủi ro | Ảnh hưởng |
|---|---|---|
| R-01 | Media sai tỉ lệ | App crop mất chữ/hình |
| R-02 | Rule login web/mobile bị lẫn | Guest/login sai luồng |
| R-03 | Promotion thiếu branch/fulfilment/tier | Áp dụng sai |
| R-04 | Modifier min/max sai | Không add cart hoặc tính tiền sai |
| R-05 | Payment callback lỗi | Đơn hàng sai trạng thái |
| R-06 | iPOS sync ghi đè dữ liệu | Menu/product sai |
| Nhóm | Checklist test toàn hệ thống |
|---|---|
| Mobile media | Splash, popup, hero, feed, logo, menu banner |
| Menu | Section, item, product detail, inactive |
| Store | Pickup list, nearest, favorite, detail, reload |
| Auth | Phone OTP, email, Google, logout, token refresh |
| Sales policy | Guest/login rule web/mobile |
| Cart | Modifier, quantity, total, fulfilment |
| Promotion | Auto promotion, voucher, branch/tier/time limit |
| Payment | PayOS, VNPay, callback, status, audit |
| Account | Profile, orders, loyalty, email/phone change |
| Admin | CRUD, validation, status, schedule, logs |