51 lines
3.2 KiB
Markdown
51 lines
3.2 KiB
Markdown
# 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
|