2nd/10_Wiki/Topics/Frontend/전자상거래 플랫폼 (E-commerce Platforms).md

---
id: wiki-2026-0508-전자상거래-플랫폼-e-commerce-platforms
title: 전자상거래 플랫폼 (E-commerce Platforms)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [E-commerce, Shopping platforms, Online retail]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [ecommerce, frontend, shopify, nextjs, headless]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: Next.js / Shopify Hydrogen
---

# 전자상거래 플랫폼 (E-commerce Platforms)

## 매 한 줄
> **"매 product catalog + cart + checkout + payment 의 합성 system"**. 2026 매 headless commerce (Shopify Hydrogen, Commerce.js, Medusa) 가 dominant — 매 frontend 와 backend 의 decoupling 으로 매 brand experience freedom + 매 perf 우월. 매 monolithic platform (Magento, WooCommerce) 의 점진 displacement.

## 매 핵심

### 매 platform 분류
- **SaaS hosted**: Shopify, BigCommerce — 매 zero ops, 매 customization 제약.
- **Self-hosted monolith**: Magento (Adobe Commerce), WooCommerce — 매 full control, 매 ops 부담.
- **Headless / composable**: Shopify Hydrogen, Medusa, Commercetools, Saleor — 매 frontend freedom + 매 microservice backend.
- **Marketplace**: Amazon, eBay, Coupang — 매 multi-seller plumbing.

### 매 핵심 모듈
- **Catalog**: 매 product, variant, collection, search/facet.
- **Cart**: 매 session-based (anonymous) + persistent (logged-in).
- **Checkout**: 매 address, shipping, tax calc, payment.
- **Order management (OMS)**: 매 fulfillment, returns, refund.
- **Payment**: Stripe, PayPal, Toss (KR), 매 PG aggregator.

### 매 응용
1. D2C 매 brand store (Hydrogen + Shopify).
2. Headless 매 multi-channel (web + mobile + kiosk).
3. B2B 매 catalog + quote + PO workflow.

## 💻 패턴

### Shopify Hydrogen — 매 product page (RSC)
```typescript
// app/products/[handle]/page.tsx
import { storefront } from '@/lib/shopify';

export default async function ProductPage({ params }) {
  const { product } = await storefront.query(`
    query Product($handle: String!) {
      product(handle: $handle) {
        id title descriptionHtml
        images(first: 5) { edges { node { url altText } } }
        variants(first: 10) {
          edges { node { id title price { amount currencyCode } } }
        }
      }
    }
  `, { variables: { handle: params.handle } });

  return <ProductDetails product={product} />;
}
```

### Cart state — 매 Zustand + localStorage
```typescript
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface CartState {
  items: { variantId: string; qty: number }[];
  add: (variantId: string, qty: number) => void;
  remove: (variantId: string) => void;
  clear: () => void;
}

export const useCart = create<CartState>()(
  persist(
    (set) => ({
      items: [],
      add: (variantId, qty) =>
        set((s) => {
          const existing = s.items.find((i) => i.variantId === variantId);
          if (existing) {
            return {
              items: s.items.map((i) =>
                i.variantId === variantId ? { ...i, qty: i.qty + qty } : i
              ),
            };
          }
          return { items: [...s.items, { variantId, qty }] };
        }),
      remove: (variantId) =>
        set((s) => ({ items: s.items.filter((i) => i.variantId !== variantId) })),
      clear: () => set({ items: [] }),
    }),
    { name: 'cart' }
  )
);
```

### Stripe Checkout — 매 server action
```typescript
'use server';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function createCheckout(items: CartItem[]) {
  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: items.map((i) => ({
      price_data: {
        currency: 'usd',
        product_data: { name: i.title },
        unit_amount: i.price * 100,
      },
      quantity: i.qty,
    })),
    success_url: `${process.env.URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.URL}/cart`,
  });
  return session.url!;
}
```

### Search — 매 Algolia / Typesense facet
```typescript
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, Hits, RefinementList, SearchBox }
  from 'react-instantsearch';

const client = algoliasearch('APP_ID', 'SEARCH_KEY');

export function ProductSearch() {
  return (
    <InstantSearch searchClient={client} indexName="products">
      <SearchBox />
      <RefinementList attribute="brand" />
      <RefinementList attribute="category" />
      <Hits hitComponent={ProductCard} />
    </InstantSearch>
  );
}
```

### Webhook — 매 order processing
```typescript
// app/api/webhooks/shopify/route.ts
import { headers } from 'next/headers';
import crypto from 'crypto';

export async function POST(req: Request) {
  const body = await req.text();
  const hmac = headers().get('x-shopify-hmac-sha256');

  const computed = crypto
    .createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET!)
    .update(body, 'utf8')
    .digest('base64');

  if (computed !== hmac) return new Response('Unauthorized', { status: 401 });

  const order = JSON.parse(body);
  // 매 fulfillment, email, analytics
  await processOrder(order);
  return new Response('ok');
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 startup, 매 빠른 launch | Shopify (hosted) |
| 매 brand-led DTC 매 custom UI | Shopify Hydrogen (headless) |
| 매 enterprise 매 complex catalog | Commercetools / Saleor |
| 매 KR domestic | Cafe24 / NHN Commerce |
| 매 self-host 매 budget | Medusa (Node) / WooCommerce |

**기본값**: 매 Shopify Hydrogen + Next.js 매 modern DTC.

## 🔗 Graph
- 부모: [[Frontend Architecture]] · [[Headless Commerce]]
- 변형: [[Shopify]] · [[Medusa]] · [[Magento]] · [[Commercetools]]
- 응용: [[D2C]] · [[B2B Commerce]] · [[Marketplace]]
- Adjacent: [[Stripe]] · [[Algolia]] · [[CMS]]

## 🤖 LLM 활용
**언제**: 매 product description 생성, 매 review summary, 매 search query rewriting, 매 personalized recommendation.
**언제 X**: 매 payment processing (deterministic 의 X), 매 inventory mgmt.

## ❌ 안티패턴
- **monolith lock-in**: 매 Magento 매 customization → 매 upgrade 지옥.
- **client-side cart on PDP**: 매 SEO loss — server-rendered cart count 도 필요.
- **synchronous webhook**: 매 5초 timeout — queue 로 offload.

## 🧪 검증 / 중복
- Verified (Shopify Hydrogen, Stripe, Medusa docs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — e-commerce platforms, headless, Shopify/Stripe/Algolia 패턴 정리 |