@restnfeel/agentc-starter-kit/docs/api-reference.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# 📖 AgentC CMS API Reference

## 목차

- [컴포넌트 API](#컴포넌트-api)
- [관리자 API](#관리자-api)
- [서버 API](#서버-api)
- [유틸리티 API](#유틸리티-api)

---

## 🧩 컴포넌트 API

### HeroSection

메인 페이지 상단의 히어로 섹션 컴포넌트

```typescript
interface HeroSectionProps {
  title: string;
  subtitle?: string;
  description?: string;
  backgroundImage?: string;
  backgroundVideo?: string;
  overlay?: boolean;
  ctaButton?: {
    text: string;
    link: string;
    variant?: "primary" | "secondary" | "outline";
    size?: "sm" | "md" | "lg";
  };
  secondaryButton?: {
    text: string;
    link: string;
    variant?: "primary" | "secondary" | "outline";
  };
  features?: string[];
  alignment?: "left" | "center" | "right";
  animation?: boolean;
  className?: string;
}
```

**사용 예제:**

```tsx
<HeroSection
  title="혁신적인 솔루션"
  subtitle="비즈니스를 성장시키는"
  description="최고의 기술로 고객의 성공을 이끌어갑니다"
  backgroundImage="/hero-bg.jpg"
  ctaButton={{
    text: "무료 체험",
    link: "/trial",
    variant: "primary",
  }}
  secondaryButton={{
    text: "더 알아보기",
    link: "/about",
  }}
  features={["24/7 고객지원", "99.9% 업타임", "무료 마이그레이션"]}
  alignment="center"
  animation={true}
/>
```

### AboutSection

회사 소개 및 브랜드 스토리 섹션

```typescript
interface AboutSectionProps {
  title: string;
  description: string;
  content?: string;
  image?: string;
  imagePosition?: "left" | "right" | "top" | "bottom";
  stats?: Array<{
    label: string;
    value: string | number;
    icon?: string;
  }>;
  timeline?: Array<{
    year: string;
    title: string;
    description: string;
  }>;
  team?: Array<{
    name: string;
    position: string;
    image: string;
    bio?: string;
  }>;
  layout?: "default" | "timeline" | "stats" | "team";
}
```

### FeaturesSection

제품 특징 및 기능 소개 섹션

```typescript
interface FeaturesSectionProps {
  title: string;
  description?: string;
  features: Array<{
    icon?: string;
    title: string;
    description: string;
    link?: string;
    image?: string;
  }>;
  layout?: "grid" | "list" | "cards" | "alternating";
  columns?: 2 | 3 | 4;
  showIcons?: boolean;
  showImages?: boolean;
  animation?: boolean;
}
```

### GallerySection

이미지/비디오 갤러리 섹션

```typescript
interface GallerySectionProps {
  title?: string;
  description?: string;
  images: Array<{
    src: string;
    alt: string;
    title?: string;
    description?: string;
    category?: string;
  }>;
  layout?: "grid" | "masonry" | "carousel" | "lightbox";
  columns?: 2 | 3 | 4 | 5;
  aspectRatio?: "square" | "16:9" | "4:3" | "auto";
  showThumbnails?: boolean;
  autoplay?: boolean;
  lightbox?: boolean;
  filters?: string[];
}
```

### ContactSection

연락처 및 문의 폼 섹션

```typescript
interface ContactSectionProps {
  title: string;
  description?: string;
  fields: Array<{
    type: "text" | "email" | "tel" | "textarea" | "select";
    name: string;
    label: string;
    placeholder?: string;
    required?: boolean;
    options?: string[]; // select 타입용
  }>;
  onSubmit: (data: Record<string, any>) => void;
  contactInfo?: {
    address?: string;
    phone?: string;
    email?: string;
    hours?: string;
    socialLinks?: Array<{
      platform: string;
      url: string;
      icon: string;
    }>;
  };
  showMap?: boolean;
  mapCenter?: [number, number]; // [lat, lng]
}
```

### TestimonialSection

고객 후기 섹션

```typescript
interface TestimonialSectionProps {
  title: string;
  description?: string;
  testimonials: Array<{
    content: string;
    author: string;
    position?: string;
    company?: string;
    avatar?: string;
    rating?: number;
  }>;
  layout?: "carousel" | "grid" | "single";
  showRatings?: boolean;
  autoplay?: boolean;
  showAvatars?: boolean;
}
```

### PricingSection

가격표 섹션

```typescript
interface PricingSectionProps {
  title: string;
  description?: string;
  plans: Array<{
    name: string;
    price: string | number;
    period?: string;
    description?: string;
    features: string[];
    highlighted?: boolean;
    buttonText?: string;
    buttonLink?: string;
  }>;
  currency?: string;
  showFreePlan?: boolean;
  showEnterprise?: boolean;
  comparisonTable?: boolean;
}
```

---

## ⚙️ 관리자 API

### AdminDashboard

관리자 대시보드 메인 컴포넌트

```typescript
interface AdminDashboardProps {
  user: {
    name: string;
    role: string;
    avatar?: string;
    permissions?: string[];
  };
  stats: {
    pages: number;
    components: number;
    media: number;
    users: number;
    [key: string]: number;
  };
  quickActions?: Array<{
    label: string;
    action: string;
    icon: string;
    href?: string;
  }>;
  recentActivity?: Array<{
    type: string;
    message: string;
    timestamp: Date;
    user?: string;
  }>;
  customWidgets?: React.ReactNode[];
}
```

### PageEditor

페이지 편집기 컴포넌트

```typescript
interface PageEditorProps {
  pageId?: string;
  initialData?: PageData;
  onSave: (pageData: PageData) => Promise<void>;
  onPublish?: (pageData: PageData) => Promise<void>;
  onPreview?: (pageData: PageData) => void;
  componentLibrary: {
    categories: string[];
    search: boolean;
    dragAndDrop: boolean;
    customComponents?: ComponentDefinition[];
  };
  preview: {
    enabled: boolean;
    responsive: boolean;
    realtime: boolean;
    devices?: ("desktop" | "tablet" | "mobile")[];
  };
  autosave?: boolean;
  versionControl?: boolean;
  collaboration?: boolean;
}

interface PageData {
  id?: string;
  title: string;
  slug: string;
  status: "draft" | "published" | "archived";
  sections: SectionData[];
  metadata: {
    description?: string;
    keywords?: string[];
    ogImage?: string;
  };
  settings: {
    layout?: string;
    theme?: string;
    customCSS?: string;
  };
}
```

### ComponentLibraryManager

컴포넌트 라이브러리 관리자

```typescript
interface ComponentLibraryManagerProps {
  components: ComponentDefinition[];
  onComponentSelect?: (component: ComponentDefinition) => void;
  onComponentEdit?: (component: ComponentDefinition) => void;
  onComponentDelete?: (componentId: string) => void;
  filters: {
    category: boolean;
    search: boolean;
    tags: boolean;
    favorites?: boolean;
  };
  allowCustomComponents?: boolean;
  importExport?: boolean;
}

interface ComponentDefinition {
  id: string;
  type: string;
  category: string;
  metadata: {
    title: string;
    description: string;
    tags: string[];
    icon: string;
    thumbnail?: string;
  };
  props: Record<string, any>;
  schema?: JSONSchema;
  customizable?: boolean;
}
```

### MediaManager

미디어 관리자 컴포넌트

```typescript
interface MediaManagerProps {
  onSelect?: (media: MediaFile[]) => void;
  multiSelect?: boolean;
  allowedTypes?: string[];
  maxFileSize?: number;
  showUpload?: boolean;
  showFolders?: boolean;
  showSearch?: boolean;
  showFilters?: boolean;
  view?: "grid" | "list";
  sortBy?: "name" | "date" | "size" | "type";
  folder?: string;
}

interface MediaFile {
  id: string;
  name: string;
  type: string;
  size: number;
  url: string;
  thumbnailUrl?: string;
  folder?: string;
  metadata: {
    width?: number;
    height?: number;
    duration?: number;
    uploadedAt: Date;
    uploadedBy: string;
  };
  tags?: string[];
}
```

---

## 🔌 서버 API

### createCMSApiRoutes

CMS API 라우트 생성 함수

```typescript
function createCMSApiRoutes(config: CMSConfig): {
  GET: (request: Request) => Promise<Response>;
  POST: (request: Request) => Promise<Response>;
  PUT: (request: Request) => Promise<Response>;
  DELETE: (request: Request) => Promise<Response>;
};

interface CMSConfig {
  database: {
    type: "postgresql" | "mysql" | "sqlite";
    connection: string;
    poolSize?: number;
  };
  auth: {
    enabled: boolean;
    provider: "nextauth" | "custom";
    roles?: string[];
    permissions?: Record<string, string[]>;
  };
  media: {
    storage: "local" | "s3" | "cloudinary" | "custom";
    maxSize: string;
    allowedTypes: string[];
    thumbnails?: boolean;
    optimization?: {
      quality: number;
      formats: string[];
      sizes: number[];
    };
  };
  cache?: {
    enabled: boolean;
    ttl: number;
    provider: "memory" | "redis";
  };
  rateLimit?: {
    windowMs: number;
    max: number;
  };
}
```

### mediaUploadHandler

미디어 업로드 핸들러

```typescript
function mediaUploadHandler(
  config: MediaUploadConfig
): (request: Request) => Promise<Response>;

interface MediaUploadConfig {
  destination: string;
  generateThumbnails?: boolean;
  imageOptimization?: {
    quality: number;
    formats: string[];
    sizes: number[];
  };
  videoProcessing?: {
    formats: string[];
    quality: string;
    thumbnailTime?: number;
  };
  validation?: {
    maxSize: number;
    allowedTypes: string[];
    dimensions?: {
      minWidth?: number;
      minHeight?: number;
      maxWidth?: number;
      maxHeight?: number;
    };
  };
  onSuccess?: (fileInfo: FileInfo) => void;
  onError?: (error: Error) => void;
}
```

### contentValidator

콘텐츠 검증 함수

```typescript
function contentValidator(
  data: any,
  options: ValidationOptions
): ValidationResult;

interface ValidationOptions {
  schema: "page" | "component" | "media" | JSONSchema;
  strict?: boolean;
  sanitize?: boolean;
  allowHtml?: boolean;
  maxLength?: number;
}

interface ValidationResult {
  isValid: boolean;
  errors?: ValidationError[];
  data?: any; // sanitized data
}
```

---

## 🛠️ 유틸리티 API

### createTheme

테마 생성 함수

```typescript
function createTheme(config: ThemeConfig): Theme;

interface ThemeConfig {
  colors: {
    primary: string;
    secondary: string;
    accent?: string;
    background: string;
    surface?: string;
    text: string;
    textSecondary?: string;
    error?: string;
    warning?: string;
    success?: string;
  };
  fonts: {
    heading: string;
    body: string;
    mono?: string;
  };
  spacing: Record<string, string>;
  breakpoints: Record<string, string>;
  borderRadius?: Record<string, string>;
  shadows?: Record<string, string>;
}
```

### createI18n

다국어 지원 설정

```typescript
function createI18n(config: I18nConfig): I18nInstance;

interface I18nConfig {
  defaultLocale: string;
  locales: string[];
  fallbackLocale?: string;
  loadPath: string;
  detection?: {
    order: ("path" | "cookie" | "header")[];
    caches: ("cookie" | "localStorage")[];
  };
  interpolation?: {
    escapeValue: boolean;
  };
}
```

### createSEOManager

SEO 관리자 생성

```typescript
function createSEOManager(config: SEOConfig): SEOManager;

interface SEOConfig {
  defaultMeta: {
    title: string;
    description: string;
    keywords?: string[];
    openGraph?: {
      siteName: string;
      type: string;
      image?: string;
      url?: string;
    };
    twitter?: {
      card: string;
      site?: string;
      creator?: string;
    };
  };
  autoGenerate: {
    sitemap: boolean;
    robots: boolean;
    schema: boolean;
  };
  tracking?: {
    googleAnalytics?: string;
    googleTagManager?: string;
    facebookPixel?: string;
  };
}
```

### createAnalytics

분석 도구 설정

```typescript
function createAnalytics(config: AnalyticsConfig): AnalyticsInstance;

interface AnalyticsConfig {
  providers: {
    googleAnalytics?: string;
    mixpanel?: string;
    amplitude?: string;
    custom?: {
      endpoint: string;
      events: string[];
    };
  };
  privacy: {
    cookieConsent: boolean;
    anonymizeIP: boolean;
    respectDNT: boolean;
  };
  events?: {
    pageview: boolean;
    clicks: boolean;
    forms: boolean;
    scroll: boolean;
    custom?: string[];
  };
}
```

---

## 📝 이벤트 핸들러

### 페이지 이벤트

```typescript
interface PageEvents {
  onPageLoad?: (pageData: PageData) => void;
  onPageSave?: (pageData: PageData) => Promise<void>;
  onPagePublish?: (pageData: PageData) => Promise<void>;
  onPageDelete?: (pageId: string) => Promise<void>;
  onSectionAdd?: (sectionData: SectionData) => void;
  onSectionUpdate?: (sectionData: SectionData) => void;
  onSectionDelete?: (sectionId: string) => void;
}
```

### 미디어 이벤트

```typescript
interface MediaEvents {
  onUploadStart?: (files: File[]) => void;
  onUploadProgress?: (progress: number) => void;
  onUploadComplete?: (files: MediaFile[]) => void;
  onUploadError?: (error: Error) => void;
  onMediaSelect?: (media: MediaFile[]) => void;
  onMediaDelete?: (mediaId: string) => Promise<void>;
}
```

### 사용자 이벤트

```typescript
interface UserEvents {
  onLogin?: (user: User) => void;
  onLogout?: () => void;
  onPermissionChange?: (user: User, permissions: string[]) => void;
  onUserCreate?: (user: User) => Promise<void>;
  onUserUpdate?: (user: User) => Promise<void>;
  onUserDelete?: (userId: string) => Promise<void>;
}
```

---

**💡 이 API 레퍼런스를 참고하여 AI가 모든 기능을 정확하게 구현할 수 있습니다!**