# 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