Backend Implementation Plan — Medusa (default, no core modification)

Mục tiêu

Khởi tạo Medusa backend chạy bằng cấu hình mặc định (không fork/sửa source Medusa), expose Store API cho storefront Next.js và Admin API cho quản trị viên.

1. Prerequisites

Node.js 20.x (đã có: v20.16.0)
PostgreSQL (dev: local hoặc Docker container)
Redis (dev: local hoặc Docker container; dùng cho event bus, cache, workflow engine)
Git (repo riêng biệt với frontend)

2. Scaffold dự án

Chạy npx create-medusa-app@latest (hoặc medusa new) trong thư mục backend/
Chọn: khởi tạo với PostgreSQL, không cần seed data mẫu mặc định của Medusa nếu không cần (sẽ seed data riêng của brand)
Kết quả: Medusa server + Admin dashboard (React, đi kèm sẵn, không cần build riêng)

3. Cấu hình môi trường (`.env`)

DATABASE_URL — kết nối PostgreSQL
REDIS_URL — kết nối Redis
STORE_CORS, ADMIN_CORS, AUTH_CORS — whitelist origin của frontend (Next.js dev: http://localhost:3000, prod: domain thật)
JWT_SECRET, COOKIE_SECRET

4. Cấu hình thương mại cơ bản (qua Admin, không cần code)

Tạo Region (ví dụ: Việt Nam — currency VND) và Sales Channel
Cấu hình Shipping Option cơ bản (giao hàng nội địa)
Cấu hình Payment Provider (bắt đầu với manual/COD cho MVP, hoặc Stripe nếu cần online payment ngay)
Tạo tài khoản Admin user đầu tiên

5. Product data model — sử dụng default, không custom module

Theo quyết định đã thảo luận: không cần sửa core Medusa cho yêu cầu custom size đo (vòng eo, vai, ngực...):

Field nào cần nhập cho từng sản phẩm → lưu trong product.metadata.measurement_fields (JSON, sửa trực tiếp qua Admin có sẵn)
Giá trị khách nhập → lưu trong line_item.metadata khi add-to-cart (API POST /store/carts/{id}/line-items đã hỗ trợ sẵn tham số metadata)
Không cần custom module ở giai đoạn MVP. Cân nhắc custom module + Admin UI widget riêng ở giai đoạn sau nếu cần UI đẹp hơn hoặc query có cấu trúc theo số đo.

6. Tạo dữ liệu sản phẩm mẫu

Ít nhất 1-2 category, vài product với variant chuẩn (màu/size cố định) + 1 product minh họa dùng measurement_fields custom

7. Kiểm thử API

Verify Admin API (/admin/*) hoạt động qua Admin dashboard
Verify Store API (/store/*) trả đúng product/region/cart bằng publishable API key
Verify luồng: tạo cart → add line item với metadata custom size → checkout → order lưu đúng metadata

8. Git & Deploy target (ghi chú, chưa thực hiện)

Repo riêng biệt (backend/ là git repo độc lập, không chung với frontend/)
Deploy: Railway hoặc Render (Node service) + Supabase/Neon (PostgreSQL managed) + Redis managed (Upstash hoặc addon của platform)

Không nằm trong scope MVP này

Custom Medusa module cho measurement fields có cấu trúc riêng
Multi-currency / multi-region đầy đủ (chỉ 1 region VN cho MVP)
Payment gateway ngoài manual/Stripe cơ bản

3.2 KiB Raw Blame History