docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,266 @@
|
||||
---
|
||||
id: wiki-2026-0508-전자상거래-플랫폼
|
||||
title: 전자상거래 플랫폼
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [E-commerce Platform, Shopify, headless commerce, 커머스 플랫폼]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [ecommerce, platform, headless, shopify, checkout]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: typescript
|
||||
framework: shopify-hydrogen-medusa
|
||||
---
|
||||
|
||||
# 전자상거래 플랫폼
|
||||
|
||||
## 매 한 줄
|
||||
> **"매 monolith 의 Shopify vs headless 의 Medusa/Saleor 의 build vs buy spectrum 결정"**. 2026 의 ecommerce 는 SaaS (Shopify, BigCommerce), Composable/MACH (commercetools, Medusa, Saleor), AI-native (agentic shopping, conversational commerce) 3축으로 분기. 매 plat 선택은 catalog scale, custom logic 양, dev resource, 매 international tax 의 4 변수 함수.
|
||||
|
||||
## 매 핵심
|
||||
|
||||
### 매 platform 분류
|
||||
- **SaaS Monolith**: Shopify (Plus), BigCommerce, Wix Commerce.
|
||||
- **Headless / Composable**: Shopify Hydrogen, commercetools, Saleor, Medusa.
|
||||
- **Open-source**: Medusa.js, Saleor, Sylius (PHP), Spree.
|
||||
- **Marketplace**: Mirakl, Marketplacer.
|
||||
- **B2B specialized**: SAP Commerce, Salesforce B2B, Spryker.
|
||||
|
||||
### 매 핵심 component
|
||||
- **Catalog**: product, variant, option, inventory.
|
||||
- **Cart/Checkout**: session, abandoned cart, taxonomy.
|
||||
- **Payment**: PSP integration (Stripe, Adyen, Toss).
|
||||
- **Order/Fulfillment**: state machine, OMS.
|
||||
- **Tax/Shipping**: TaxJar, Avalara, ShipBob.
|
||||
- **Customer/Account**: passwordless, social, subscription.
|
||||
|
||||
### 매 응용
|
||||
1. Shopify Hydrogen 의 storefront 와 headless backend.
|
||||
2. Medusa.js + Next.js 의 fully open-source stack.
|
||||
3. Composable commerce 의 best-of-breed 조합.
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### Shopify Storefront API (GraphQL)
|
||||
```ts
|
||||
// app/lib/shopify.ts
|
||||
import { createStorefrontClient } from "@shopify/hydrogen-react";
|
||||
|
||||
export const client = createStorefrontClient({
|
||||
storeDomain: "your-shop.myshopify.com",
|
||||
storefrontApiVersion: "2025-01",
|
||||
publicStorefrontToken: process.env.PUBLIC_STOREFRONT_TOKEN!,
|
||||
});
|
||||
|
||||
const PRODUCTS_QUERY = `#graphql
|
||||
query Products($first: Int!) {
|
||||
products(first: $first) {
|
||||
nodes {
|
||||
id title handle
|
||||
priceRange { minVariantPrice { amount currencyCode } }
|
||||
featuredImage { url altText }
|
||||
}
|
||||
}
|
||||
}`;
|
||||
|
||||
export async function listProducts(first = 24) {
|
||||
const { data } = await client.query(PRODUCTS_QUERY, { variables: { first } });
|
||||
return data.products.nodes;
|
||||
}
|
||||
```
|
||||
|
||||
### Medusa.js (open-source backend)
|
||||
```ts
|
||||
// medusa-config.ts
|
||||
import { defineConfig } from "@medusajs/framework/utils";
|
||||
|
||||
export default defineConfig({
|
||||
projectConfig: {
|
||||
databaseUrl: process.env.DATABASE_URL,
|
||||
redisUrl: process.env.REDIS_URL,
|
||||
http: {
|
||||
storeCors: process.env.STORE_CORS!,
|
||||
adminCors: process.env.ADMIN_CORS!,
|
||||
authCors: process.env.AUTH_CORS!,
|
||||
jwtSecret: process.env.JWT_SECRET!,
|
||||
cookieSecret: process.env.COOKIE_SECRET!,
|
||||
},
|
||||
},
|
||||
modules: [
|
||||
{ resolve: "@medusajs/medusa/payment-stripe",
|
||||
options: { apiKey: process.env.STRIPE_API_KEY }},
|
||||
{ resolve: "@medusajs/medusa/cache-redis",
|
||||
options: { redisUrl: process.env.REDIS_URL }},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### Cart state (Zustand + persist)
|
||||
```ts
|
||||
import { create } from "zustand";
|
||||
import { persist } from "zustand/middleware";
|
||||
|
||||
type CartItem = { variantId: string; qty: number; priceCents: number };
|
||||
interface CartState {
|
||||
items: CartItem[];
|
||||
add: (i: CartItem) => void;
|
||||
remove: (variantId: string) => void;
|
||||
total: () => number;
|
||||
}
|
||||
|
||||
export const useCart = create<CartState>()(persist(
|
||||
(set, get) => ({
|
||||
items: [],
|
||||
add: (i) => set(s => {
|
||||
const ex = s.items.find(x => x.variantId === i.variantId);
|
||||
return ex
|
||||
? { items: s.items.map(x => x === ex ? { ...x, qty: x.qty + i.qty } : x) }
|
||||
: { items: [...s.items, i] };
|
||||
}),
|
||||
remove: (id) => set(s => ({ items: s.items.filter(x => x.variantId !== id) })),
|
||||
total: () => get().items.reduce((a,b) => a + b.qty * b.priceCents, 0),
|
||||
}),
|
||||
{ name: "cart" }
|
||||
));
|
||||
```
|
||||
|
||||
### Stripe Checkout (server)
|
||||
```ts
|
||||
import Stripe from "stripe";
|
||||
const stripe = new Stripe(process.env.STRIPE_SECRET!);
|
||||
|
||||
export async function createCheckoutSession(items: CartItem[], userId: string) {
|
||||
return await stripe.checkout.sessions.create({
|
||||
mode: "payment",
|
||||
line_items: items.map(i => ({
|
||||
price_data: {
|
||||
currency: "usd",
|
||||
product_data: { name: i.title },
|
||||
unit_amount: i.priceCents,
|
||||
},
|
||||
quantity: i.qty,
|
||||
})),
|
||||
success_url: `${process.env.SITE}/order/success?sid={CHECKOUT_SESSION_ID}`,
|
||||
cancel_url: `${process.env.SITE}/cart`,
|
||||
automatic_tax: { enabled: true },
|
||||
metadata: { userId },
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Webhook idempotency
|
||||
```ts
|
||||
// app/api/webhooks/stripe/route.ts
|
||||
import Stripe from "stripe";
|
||||
import { redis } from "@/lib/redis";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const sig = req.headers.get("stripe-signature")!;
|
||||
const body = await req.text();
|
||||
const event = Stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
|
||||
|
||||
// Idempotency: refuse double-processing
|
||||
const seen = await redis.set(`stripe:evt:${event.id}`, "1", "EX", 60*60*24, "NX");
|
||||
if (!seen) return new Response("dup", { status: 200 });
|
||||
|
||||
if (event.type === "checkout.session.completed") {
|
||||
await fulfillOrder(event.data.object);
|
||||
}
|
||||
return new Response("ok");
|
||||
}
|
||||
```
|
||||
|
||||
### Order state machine (XState)
|
||||
```ts
|
||||
import { createMachine } from "xstate";
|
||||
|
||||
export const orderMachine = createMachine({
|
||||
id: "order",
|
||||
initial: "pending_payment",
|
||||
states: {
|
||||
pending_payment: {
|
||||
on: { PAID: "paid", CANCELLED: "cancelled", EXPIRED: "expired" }
|
||||
},
|
||||
paid: { on: { PACKED: "packed", REFUND: "refunded" } },
|
||||
packed: { on: { SHIPPED: "shipped" } },
|
||||
shipped: { on: { DELIVERED: "delivered", LOST: "investigating" } },
|
||||
delivered: { type: "final" },
|
||||
cancelled: { type: "final" },
|
||||
expired: { type: "final" },
|
||||
refunded: { type: "final" },
|
||||
investigating: { on: { RESOLVED: "delivered", REFUND: "refunded" } },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Inventory reservation
|
||||
```ts
|
||||
// Atomic reserve via Redis Lua
|
||||
const RESERVE_LUA = `
|
||||
local stock = tonumber(redis.call('GET', KEYS[1]))
|
||||
local need = tonumber(ARGV[1])
|
||||
if stock and stock >= need then
|
||||
redis.call('DECRBY', KEYS[1], need)
|
||||
return 1
|
||||
end
|
||||
return 0`;
|
||||
|
||||
await redis.eval(RESERVE_LUA, 1, `stock:${variantId}`, qty);
|
||||
```
|
||||
|
||||
### Tax calc (Stripe Tax / Avalara)
|
||||
```ts
|
||||
const calc = await stripe.tax.calculations.create({
|
||||
currency: "usd",
|
||||
line_items: items.map(i => ({
|
||||
amount: i.priceCents * i.qty,
|
||||
reference: i.variantId,
|
||||
tax_behavior: "exclusive",
|
||||
})),
|
||||
customer_details: {
|
||||
address: { line1, city, state, postal_code, country: "US" },
|
||||
address_source: "shipping",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| <100 SKU, fast launch | Shopify (Basic/Plus) |
|
||||
| custom checkout flow | Hydrogen (Shopify) or Medusa |
|
||||
| 100% control + open-source | Medusa.js |
|
||||
| enterprise, MACH | commercetools |
|
||||
| B2B multi-tenant | Saleor / Spryker |
|
||||
| AI agent shopping | Storefront API + agent layer |
|
||||
|
||||
**기본값**: Shopify Plus + Hydrogen for SMB-mid; Medusa.js for full-control startups.
|
||||
|
||||
## 🔗 Graph
|
||||
- 변형: [[Headless Commerce]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: product description gen, category mapping, support FAQ from KB, conversational search.
|
||||
**언제 X**: payment authorization 의 final approval — deterministic system 만.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **DIY checkout from scratch**: PCI scope blowup.
|
||||
- **Webhook without idempotency**: double-fulfill, double-refund.
|
||||
- **Cart in localStorage only**: lost on multi-device.
|
||||
- **No inventory reservation**: oversell.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Shopify 2025 dev docs, Medusa v2, Stripe Tax docs, MACH alliance).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — ecommerce platform decision matrix + patterns. |
|
||||
Reference in New Issue
Block a user