+ )
+}
+```
+
+## 작동 원리
+
+### Controlled/Uncontrolled 자동 전환
+
+```typescript
+const [state, setState] = useState(false);
+
+// checked prop이 있으면 Controlled, 없으면 Uncontrolled
+const currentValue = checked ?? state;
+
+onClick={() => {
+ const next = !currentValue;
+ setState(next); // 내부 상태 업데이트
+ onChange?.(next); // 외부 콜백 호출 (있다면)
+}}
+```
+
+**핵심 로직**:
+- `checked ?? state`: checked가 있으면 사용, 없으면 내부 state 사용
+- 항상 내부 state와 onChange 모두 실행
+- Props 유무에 관계없이 일관된 동작 보장
+
+### 검증 통합 (InputOfModal)
+
+```typescript
+// InputOfModal.tsx의 검증 로직
+rules={{
+ validate: (value) => {
+ if (!field.required) return true;
+
+ // Checkbox 타입 검증
+ if (field.type === 'checkbox' && !value) {
+ return `${field.label}에 동의해주세요.`;
+ }
+
+ return true;
+ }
+}}
+```
+
+`required: true`일 때 체크하지 않으면 에러 메시지가 표시됩니다.
+
+## 스타일링
+
+### 기본 스타일
+
+```tsx
+
+```
+
+- **Flexbox**: 아이콘과 텍스트를 수평 정렬
+- **gap-2**: 적절한 간격 유지
+- **cursor-pointer**: 클릭 가능 표시
+- **select-none**: 텍스트 선택 방지
+- **font-material-symbols**: Google Material Symbols 폰트 적용
+- **fontVariationSettings**: FILL 속성으로 채워진/빈 상태 표현
+- **icon-checkbox**: 체크박스 아이콘 전용 스타일 (tailwind.config.ts에 정의)
+
+### 커스텀 스타일 적용
+
+컴포넌트를 감싸서 스타일을 확장할 수 있습니다.
+
+```tsx
+
+
+
+```
+
+## 모범 사례
+
+### ✅ 권장사항
+
+```tsx
+// 1. 명확한 레이블 사용
+
+
+// 2. 필수 항목은 required 명시
+{
+ type: 'checkbox',
+ label: '필수 동의 사항',
+ required: true
+}
+
+// 3. Controlled 모드에서 초기값 설정
+const [checked, setChecked] = useState(false)
+
+
+// 4. Form에서는 Controller 사용
+ (
+
+ )}
+/>
+```
+
+### ❌ 비권장사항
+
+```tsx
+// 1. checked만 주고 onChange 없음 (동작 안 함)
+ // ❌
+
+// 2. 모호한 레이블
+ // ❌ 무엇에 대한 동의?
+
+// 3. 중복 상태 관리
+const [state1, setState1] = useState(false)
+const [state2, setState2] = useState(false)
+ { setState1(v); setState2(v); }} // ❌ 복잡함
+/>
+```
+
+## 타입 정의
+
+```typescript
+interface CheckboxProps {
+ /**
+ * 체크 상태 (Controlled 모드)
+ * - 제공하면 Controlled 모드로 작동
+ * - 생략하면 Uncontrolled 모드로 작동
+ */
+ checked?: boolean;
+
+ /**
+ * 상태 변경 콜백
+ * @param checked - 새로운 체크 상태
+ */
+ onChange?: (checked: boolean) => void;
+
+ /**
+ * 표시할 레이블 텍스트
+ * @default '체크박스'
+ */
+ label?: string;
+}
+```
+
+## FormFieldConfig 타입
+
+```typescript
+interface CheckboxFieldConfig extends BaseFieldConfig {
+ type: 'checkbox';
+ label: string;
+ name: string;
+ required?: boolean; // 필수 체크 여부
+}
+```
+
+## 관련 컴포넌트
+
+- **InputOfModal**: Checkbox를 포함한 Form 생성기
+- **InputListProvider**: 다중 입력 관리 (배열 타입)
+- **SkillTag**: 태그 형태의 다중 입력
+
+## 문제 해결
+
+### Q: Uncontrolled 모드에서 초기값 설정하기
+
+**A**: 컴포넌트 내부의 `useState(false)`를 수정하거나, Controlled 모드로 전환하세요.
+
+```tsx
+// 방법 1: 내부 수정 (권장 안 함)
+const [state, setState] = useState(initialValue);
+
+// 방법 2: Controlled 모드 사용 (권장)
+const [checked, setChecked] = useState(true); // 초기값 true
+
+```
+
+### Q: React Hook Form에서 defaultValue 적용하기
+
+**A**: useForm의 `defaultValues`에 설정하세요.
+
+```tsx
+const { control } = useForm({
+ defaultValues: {
+ agreed: true, // 체크된 상태로 시작
+ }
+})
+```
+
+### Q: 여러 Checkbox의 전체 선택/해제 구현
+
+**A**: 상위 컴포넌트에서 상태 배열로 관리하세요.
+
+```tsx
+const [checks, setChecks] = useState([false, false, false]);
+const allChecked = checks.every(Boolean);
+
+const toggleAll = () => {
+ setChecks(checks.map(() => !allChecked));
+};
+
+return (
+ <>
+
+ {checks.map((checked, i) => (
+ {
+ const next = [...checks];
+ next[i] = v;
+ setChecks(next);
+ }}
+ />
+ ))}
+
+)
+```
+
+## 버전 히스토리
+
+### v1.0.0 (2025-01-08)
+- ✨ Controlled/Uncontrolled 모드 자동 지원
+- ✨ `checked ?? state` 패턴으로 단순화
+- ✨ InputOfModal required 검증 통합
+- 🎨 Google Material Symbols 적용
+- 📝 완전한 타입 정의
+
+## 라이선스
+
+이 컴포넌트는 프로젝트의 내부 컴포넌트입니다.
diff --git a/docs/FormConfig-GraphQL-Architecture.md b/docs/FormConfig-GraphQL-Architecture.md
new file mode 100644
index 00000000..077086cc
--- /dev/null
+++ b/docs/FormConfig-GraphQL-Architecture.md
@@ -0,0 +1,897 @@
+# FormConfig 기반 GraphQL 통합 아키텍처 설계 문서
+
+## 목차
+1. [설계 철학](#설계-철학)
+2. [아키텍처 개요](#아키텍처-개요)
+3. [핵심 컴포넌트](#핵심-컴포넌트)
+4. [데이터 흐름](#데이터-흐름)
+5. [사용자 정의 쿼리 작성](#사용자-정의-쿼리-작성)
+6. [타입 시스템](#타입-시스템)
+7. [확장성](#확장성)
+
+---
+
+## 설계 철학
+
+### 1. 사용자가 쿼리를 작성하고, 시스템은 매핑만 수행
+
+**문제점**: 초기 설계에서는 `FormConfig`의 `columnInfo`를 기반으로 GraphQL 쿼리를 자동 생성하려 했습니다.
+- 테이블 구조 추측 (ID 컬럼명, 관계 추론 등)
+- 프라이머리 키가 단일인지 다중인지 불확실
+- `profile_link`처럼 ID가 없는 테이블 처리 복잡
+- 특정 테이블에 종속된 로직 발생
+
+**해결책**: 사용자가 GraphQL 쿼리를 직접 작성하도록 변경
+```typescript
+export const profileConfig: FormConfig = {
+ graphql: {
+ read: `query GetProfile($owner: String!) { ... }`,
+ insert: `mutation InsertProfile($objects: [...]) { ... }`,
+ update: `mutation UpdateProfile($set: ...) { ... }`,
+ },
+ fields: [...]
+};
+```
+
+**장점**:
+- ✅ 완전한 범용성 - 어떤 테이블 구조든 지원
+- ✅ 타입 안전성 - `database.types.ts`에 의존
+- ✅ 명시적 - 쿼리가 무엇을 요청하는지 명확
+- ✅ 유연성 - 복잡한 JOIN, 필터링, 정렬 등 자유롭게 작성
+
+---
+
+## 아키텍처 개요
+
+### 레이어 구조
+
+```
+┌─────────────────────────────────────┐
+│ React Component (Account.tsx) │ ← 사용자 인터페이스
+└────────────┬────────────────────────┘
+ │ useFormConfigData Hook
+ ↓
+┌─────────────────────────────────────┐
+│ useFormConfigData Hook │ ← 상태 관리
+│ - initialValues │
+│ - isLoading, isSaving, error │
+│ - loadData(), saveData() │
+└────────────┬────────────────────────┘
+ │
+ ↓
+┌─────────────────────────────────────┐
+│ GraphQLDataService │ ← 비즈니스 로직
+│ - loadData() │ (쿼리 실행 + 매핑)
+│ - saveData() │
+└────────────┬────────────────────────┘
+ │
+ ├──────────────┬──────────────┐
+ ↓ ↓ ↓
+ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
+ │ QueryBuilder │ │ GraphQL │ │ Data │
+ │ │ │ Client │ │ Transformer │
+ │ - read 쿼리 │ │ - execute │ │ - toForm │
+ │ - insert │ │ - auth │ │ - toGraphQL │
+ │ - update │ │ │ │ │
+ └──────────────┘ └─────────────┘ └──────────────┘
+ │ │ │
+ └──────────────┴──────────────┘
+ ↓
+ ┌────────────────────────────┐
+ │ Supabase GraphQL API │
+ └────────────────────────────┘
+```
+
+### 단일 진실 공급원 (Single Source of Truth)
+
+**FormConfig**가 모든 것의 중심:
+1. **UI 렌더링** - `fields` → `InputOfModal` 컴포넌트
+2. **GraphQL 쿼리** - `graphql.read/insert/update`
+3. **데이터 매핑** - `columnInfo` → Form ↔ GraphQL 변환
+
+---
+
+## 핵심 컴포넌트
+
+### 1. FormConfig 타입 정의
+
+**위치**: `src/app/components/modal/inputs/types/inputTypes.ts`
+
+```typescript
+export interface FormConfig {
+ fields: FormFieldConfig[];
+
+ // 사용자 정의 GraphQL 쿼리 (필수)
+ graphql: {
+ read: string; // 데이터 조회
+ insert: string; // 데이터 삽입
+ update: string; // 데이터 업데이트
+ };
+}
+```
+
+**설계 이유**:
+- `graphql` 필드를 **필수**로 만들어 명시성 확보
+- 각 엔티티(profile, team, project)마다 고유한 쿼리 작성
+- 시스템은 쿼리 내용을 추측하지 않음
+
+### 2. GraphQL Client
+
+**위치**: `src/utils/graphQL/client.ts`
+
+```typescript
+export class SupabaseGraphQLClient {
+ private async execute(query: string, variables?: Record) {
+ // 1. Supabase 세션 토큰 가져오기
+ const { data: { session } } = await this.supabase.auth.getSession();
+
+ // 2. GraphQL 요청
+ const response = await fetch(this.graphqlEndpoint, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${session.access_token}`,
+ apikey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
+ },
+ body: JSON.stringify({ query, variables }),
+ });
+
+ // 3. 에러 처리
+ const result = await response.json();
+ if (result.errors) throw new Error(result.errors[0].message);
+
+ return result;
+ }
+}
+```
+
+**핵심 로직**:
+- Supabase 인증 토큰 자동 주입
+- GraphQL 표준 형식으로 요청
+- 에러를 TypeScript Error로 변환
+
+### 3. Query Builder
+
+**위치**: `src/utils/graphQL/queryBuilder.ts`
+
+```typescript
+// 단순히 FormConfig의 쿼리를 반환
+export function buildReadQuery(formConfig: FormConfig): string {
+ return formConfig.graphql.read;
+}
+
+export function buildInsertMutation(formConfig: FormConfig): string {
+ return formConfig.graphql.insert;
+}
+
+export function buildUpdateMutation(formConfig: FormConfig): string {
+ return formConfig.graphql.update;
+}
+```
+
+**설계 결정**:
+- 초기: 복잡한 쿼리 자동 생성 로직 (300+ 줄)
+- 최종: 단순 반환 함수 (30줄)
+- **이유**: 사용자가 쿼리를 작성하므로 추측 로직 불필요
+
+### 4. Data Transformer
+
+**위치**: `src/utils/graphQL/dataTransformer.ts`
+
+#### GraphQL → Form 데이터 변환
+
+```typescript
+export function graphqlToFormData(
+ graphqlData: any,
+ formConfig: FormConfig
+): Record {
+ const formData = {};
+
+ formConfig.fields.forEach((field) => {
+ const { table, column } = field.columnInfo;
+
+ if (field.type === 'inputList') {
+ // GraphQL의 nested 데이터 → InputList 형식
+ const relationData = graphqlData[`${table}Collection`]?.edges || [];
+ formData[field.fieldName] = relationData.map(edge =>
+ field.inputConfig.inputs.map(input => ({
+ value: edge.node[input.name]
+ }))
+ );
+ }
+
+ if (field.type === 'skillTag') {
+ // GraphQL의 skill_id → 스킬 이름 배열
+ const skills = graphqlData[`${table}Collection`]?.edges || [];
+ formData[field.fieldName] = skills.map(edge => edge.node.skill_name);
+ }
+ });
+
+ return formData;
+}
+```
+
+#### Form 데이터 → GraphQL Variables 변환
+
+```typescript
+export function formDataToGraphQL(
+ formData: Record,
+ formConfig: FormConfig
+): Record {
+ const variables = {};
+
+ formConfig.fields.forEach((field) => {
+ if (field.type === 'inputList') {
+ // InputList → GraphQL mutation objects
+ const items = formData[field.fieldName] as MultiInputItem[][];
+ variables[field.fieldName] = items.map(item => {
+ const obj = {};
+ item.forEach((input, idx) => {
+ obj[field.inputConfig.inputs[idx].name] = input.value;
+ });
+ return obj;
+ });
+ }
+ });
+
+ return variables;
+}
+```
+
+**매핑 규칙**:
+| Form Field Type | GraphQL Type | 변환 로직 |
+|-----------------|--------------|-----------|
+| `inputList` (onlyOne: true) | 단일 스칼라 값 | `[[{value: "foo"}]]` → `"foo"` |
+| `inputList` (onlyOne: false) | 배열 | `[[{value: "a"}], [{value: "b"}]]` → `["a", "b"]` |
+| `skillTag` | 배열 | `["React", "Node"]` → `[{skill_name: "React"}, ...]` |
+| `picture` | 파일 URL | `File` → 스토리지 업로드 → `"url"` |
+| `checkbox` | boolean | `true` → `true` |
+
+### 5. GraphQLDataService
+
+**위치**: `src/services/client/core/graphqlDataService.ts`
+
+```typescript
+export class GraphQLDataService {
+ async loadData(
+ formConfig: FormConfig,
+ variables?: Record
+ ) {
+ // 1. 사용자 정의 쿼리 가져오기
+ const query = buildReadQuery(formConfig);
+
+ // 2. 쿼리 실행
+ const response = await executeQuery(query, variables);
+
+ // 3. GraphQL 응답 → Form 데이터 매핑
+ return graphqlToFormData(response, formConfig);
+ }
+
+ async saveData(
+ formConfig: FormConfig,
+ formData: Record,
+ variables?: Record,
+ isUpdate: boolean = false
+ ) {
+ // 1. Form 데이터 → GraphQL variables 변환
+ const graphqlVariables = formDataToGraphQL(formData, formConfig);
+
+ // 2. 사용자 정의 mutation 실행
+ const mutation = isUpdate
+ ? buildUpdateMutation(formConfig)
+ : buildInsertMutation(formConfig);
+
+ const response = await executeMutation(mutation, {
+ ...graphqlVariables,
+ ...variables
+ });
+
+ return { success: true, data: response };
+ }
+}
+```
+
+**핵심 책임**:
+- ✅ 쿼리 실행 조율
+- ✅ 데이터 변환 호출
+- ❌ 쿼리 생성 (사용자가 함)
+- ❌ 테이블 특화 로직 (없음)
+
+### 6. useFormConfigData Hook
+
+**위치**: `src/utils/hook/useFormConfigData.ts`
+
+```typescript
+export function useFormConfigData(
+ formConfig: FormConfig,
+ variables?: Record, // GraphQL variables
+ options?: {
+ autoLoad?: boolean;
+ isUpdate?: boolean;
+ }
+) {
+ const [initialValues, setInitialValues] = useState({});
+ const [isLoading, setIsLoading] = useState(false);
+ const [error, setError] = useState(null);
+
+ const loadData = useCallback(async () => {
+ setIsLoading(true);
+ const data = await dataService.loadData(formConfig, variables);
+ setInitialValues(data);
+ setIsLoading(false);
+ }, [formConfig, variables]);
+
+ const saveData = useCallback(async (formData) => {
+ return await dataService.saveData(
+ formConfig,
+ formData,
+ variables,
+ options?.isUpdate
+ );
+ }, [formConfig, variables, options?.isUpdate]);
+
+ return { initialValues, isLoading, error, saveData, loadData };
+}
+```
+
+**상태 관리**:
+- `initialValues` - React Hook Form에 전달할 초기값
+- `isLoading` - 로딩 스피너 표시용
+- `error` - 에러 메시지 표시용
+- `saveData` - 폼 제출 핸들러
+
+---
+
+## 데이터 흐름
+
+### 조회 (Read) 플로우
+
+```
+1. Component 렌더링
+ ↓
+2. useFormConfigData(profileConfig, { owner: userId })
+ ↓
+3. loadData() 자동 호출
+ ↓
+4. GraphQLDataService.loadData()
+ ├─ buildReadQuery(profileConfig) → SQL 쿼리 문자열
+ ├─ executeQuery(query, { owner: userId })
+ │ └─ POST /graphql/v1 with auth token
+ └─ graphqlToFormData(response, profileConfig)
+ └─ FormConfig.fields 순회하며 매핑
+ ↓
+5. setInitialValues(mappedData)
+ ↓
+6. InputOfModal에 initialValues 전달
+ ↓
+7. 사용자에게 폼 표시
+```
+
+### 저장 (Save) 플로우
+
+```
+1. 사용자가 폼 제출
+ ↓
+2. handleSubmit(formData)
+ ↓
+3. saveData(formData)
+ ↓
+4. GraphQLDataService.saveData()
+ ├─ formDataToGraphQL(formData, profileConfig)
+ │ └─ FormConfig.fields 기반 변환
+ ├─ buildInsertMutation(profileConfig) or buildUpdateMutation()
+ ├─ executeMutation(mutation, variables)
+ │ └─ POST /graphql/v1 with auth token
+ └─ return { success: true }
+ ↓
+5. 성공 시 모달 닫기 / 실패 시 에러 표시
+```
+
+---
+
+## 사용자 정의 쿼리 작성
+
+### 1. Read Query 예시
+
+```graphql
+query GetProfile($owner: String!) {
+ profileCollection(
+ filter: {
+ owner: { eq: $owner },
+ is_team: { eq: false }
+ }
+ ) {
+ edges {
+ node {
+ profile_id
+ profile_name
+ profile_image
+ description
+
+ # 관계 테이블 (One-to-Many)
+ profile_linkCollection {
+ edges {
+ node {
+ link
+ alt
+ }
+ }
+ }
+
+ # 중간 테이블 (Many-to-Many)
+ profile_skillsCollection {
+ edges {
+ node {
+ skill_id
+ skills {
+ skill_name
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+**주의사항**:
+- Supabase GraphQL은 `Collection` suffix 사용
+- 관계는 `edges { node { } }` 구조
+- 필터는 `{ eq, neq, gt, lt, in, ... }` 연산자
+
+### 2. Insert Mutation 예시
+
+```graphql
+mutation InsertProfile($objects: [profileInsertInput!]!) {
+ insertIntoprofileCollection(objects: $objects) {
+ affectedCount
+ records {
+ profile_id
+ profile_name
+ }
+ }
+}
+```
+
+**Variables 형식**:
+```json
+{
+ "objects": [
+ {
+ "profile_name": "홍길동",
+ "description": "개발자",
+ "owner": "user-123",
+ "is_team": false
+ }
+ ]
+}
+```
+
+### 3. Update Mutation 예시
+
+```graphql
+mutation UpdateProfile(
+ $set: profileUpdateInput!,
+ $filter: profileFilter!
+) {
+ updateprofileCollection(set: $set, filter: $filter) {
+ affectedCount
+ records {
+ profile_id
+ }
+ }
+}
+```
+
+**Variables 형식**:
+```json
+{
+ "set": {
+ "profile_name": "홍길동",
+ "description": "시니어 개발자"
+ },
+ "filter": {
+ "profile_id": { "eq": "profile-123" }
+ }
+}
+```
+
+---
+
+## 타입 시스템
+
+### Supabase 타입 활용
+
+```typescript
+import { Database } from '@/utils/supabase/database.types';
+
+// 테이블 Row 타입
+type Profile = Database['public']['Tables']['profile']['Row'];
+
+// Insert DTO
+type ProfileInsert = Database['public']['Tables']['profile']['Insert'];
+
+// Update DTO
+type ProfileUpdate = Database['public']['Tables']['profile']['Update'];
+
+// 사용 예시
+const profile: Profile = {
+ profile_id: 'xxx',
+ profile_name: '홍길동',
+ owner: 'user-123',
+ is_team: false,
+ // ... database.types.ts에 정의된 모든 필드
+};
+```
+
+### ColumnInfo와 매핑
+
+```typescript
+{
+ fieldName: 'profile_full_name',
+ columnInfo: {
+ table: 'profile', // Database['public']['Tables']['profile']
+ column: 'profile_name' // keyof Profile
+ }
+}
+```
+
+---
+
+## 확장성
+
+### 1. 새로운 엔티티 추가
+
+**예시: Team Config**
+
+```typescript
+// src/services/config/teamConfig.ts
+export const teamConfig: FormConfig = {
+ graphql: {
+ read: `
+ query GetTeam($team_id: String!) {
+ profileCollection(
+ filter: { profile_id: { eq: $team_id }, is_team: { eq: true } }
+ ) {
+ edges {
+ node {
+ profile_id
+ profile_name
+ profile_image
+ team_membersCollection {
+ edges {
+ node {
+ user_id
+ role
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ `,
+ insert: `mutation InsertTeam(...) { ... }`,
+ update: `mutation UpdateTeam(...) { ... }`,
+ },
+ fields: [
+ {
+ fieldName: 'team_name',
+ label: '팀 이름',
+ type: 'inputList',
+ columnInfo: { table: 'profile', column: 'profile_name' },
+ inputConfig: { ... }
+ },
+ // ...
+ ]
+};
+```
+
+**사용**:
+```typescript
+const { initialValues, saveData } = useFormConfigData(
+ teamConfig,
+ { team_id: 'team-123' }
+);
+```
+
+### 2. 복잡한 쿼리 패턴
+
+#### 페이지네이션
+```graphql
+query GetProfiles($first: Int!, $after: Cursor) {
+ profileCollection(first: $first, after: $after) {
+ edges {
+ node { ... }
+ cursor
+ }
+ pageInfo {
+ hasNextPage
+ endCursor
+ }
+ }
+}
+```
+
+#### 정렬
+```graphql
+query GetProfiles($orderBy: [profileOrderBy!]) {
+ profileCollection(orderBy: $orderBy) {
+ edges {
+ node { ... }
+ }
+ }
+}
+```
+
+#### 검색
+```graphql
+query SearchProfiles($search: String!) {
+ profileCollection(
+ filter: {
+ profile_name: { ilike: $search }
+ }
+ ) {
+ edges {
+ node { ... }
+ }
+ }
+}
+```
+
+### 3. 에러 처리 확장
+
+```typescript
+// Custom error handler
+class GraphQLError extends Error {
+ constructor(
+ message: string,
+ public code: string,
+ public extensions?: Record
+ ) {
+ super(message);
+ }
+}
+
+// 사용
+try {
+ await saveData(formData);
+} catch (error) {
+ if (error instanceof GraphQLError) {
+ if (error.code === 'UNIQUE_VIOLATION') {
+ alert('이미 존재하는 프로필 이름입니다.');
+ }
+ }
+}
+```
+
+---
+
+## 설계 결정 및 트레이드오프
+
+### ✅ 채택한 결정
+
+| 결정 | 이유 |
+|------|------|
+| 사용자가 쿼리 작성 | 완전한 범용성, 명시성, 유연성 |
+| FormConfig = 단일 진실 공급원 | UI + 데이터 + 쿼리를 한 곳에서 관리 |
+| React Hook으로 캡슐화 | 상태 관리 단순화, 재사용성 |
+| 데이터 변환 레이어 분리 | GraphQL ↔ Form 형식 변환 로직 격리 |
+
+### ❌ 거부한 결정
+
+| 거부한 설계 | 이유 |
+|-------------|------|
+| 자동 쿼리 생성 | 테이블 구조 추측 불가능, 복잡도 증가 |
+| 테이블 특화 서비스 | 범용성 저하, 유지보수 어려움 |
+| `column: '*'` 지원 | GraphQL은 필드를 명시해야 함 |
+| ORM 패턴 | GraphQL과 맞지 않음, Over-engineering |
+
+---
+
+## 성능 고려사항
+
+### 1. N+1 문제 방지
+
+**나쁜 예**:
+```graphql
+query {
+ profileCollection {
+ edges {
+ node {
+ profile_id
+ # N+1: 각 profile마다 별도 요청
+ }
+ }
+ }
+}
+
+# 별도로
+profileLinkCollection(filter: { profile_id: ... })
+```
+
+**좋은 예**:
+```graphql
+query {
+ profileCollection {
+ edges {
+ node {
+ profile_id
+ # 한 번에 가져오기
+ profile_linkCollection {
+ edges {
+ node {
+ link
+ alt
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+### 2. 필드 선택 최소화
+
+```graphql
+# ❌ 불필요한 데이터 가져오기
+query {
+ profileCollection {
+ edges {
+ node {
+ # 100개 필드 전부
+ }
+ }
+ }
+}
+
+# ✅ 필요한 것만
+query {
+ profileCollection {
+ edges {
+ node {
+ profile_id
+ profile_name
+ # 화면에 표시할 것만
+ }
+ }
+ }
+}
+```
+
+### 3. 캐싱 전략
+
+```typescript
+// React Query 연동 예시
+import { useQuery } from '@tanstack/react-query';
+
+function useProfile(userId: string) {
+ return useQuery({
+ queryKey: ['profile', userId],
+ queryFn: () => dataService.loadData(profileConfig, { owner: userId }),
+ staleTime: 5 * 60 * 1000, // 5분
+ });
+}
+```
+
+---
+
+## 보안 고려사항
+
+### 1. Row Level Security (RLS)
+
+Supabase RLS 정책이 GraphQL에도 적용됩니다:
+
+```sql
+-- 자신의 프로필만 조회 가능
+CREATE POLICY "Users can view own profile"
+ON profile FOR SELECT
+USING (auth.uid() = owner);
+
+-- 자신의 프로필만 수정 가능
+CREATE POLICY "Users can update own profile"
+ON profile FOR UPDATE
+USING (auth.uid() = owner);
+```
+
+### 2. Input Validation
+
+```typescript
+// GraphQL variables 검증
+function validateProfileInput(data: any) {
+ if (!data.profile_name || data.profile_name.length > 100) {
+ throw new Error('Invalid profile name');
+ }
+
+ if (data.description && data.description.length > 1000) {
+ throw new Error('Description too long');
+ }
+}
+```
+
+---
+
+## 마이그레이션 가이드
+
+### 기존 코드 → 새로운 시스템
+
+**Before**:
+```typescript
+// 복잡한 변환 로직
+const profileData = await getProfileWithDetails(userId);
+const initialValues = transformDataToInitialValues(profileData, profileConfig);
+
+// 복잡한 저장 로직
+const saveData = transformFormDataToSaveFormat(formData, profileConfig, userId);
+await saveProfileData(saveData, userId);
+```
+
+**After**:
+```typescript
+// 간단한 Hook 사용
+const { initialValues, saveData } = useFormConfigData(
+ profileConfig,
+ { owner: userId }
+);
+
+// 저장
+await saveData(formData);
+```
+
+**단계**:
+1. `FormConfig`에 `graphql` 필드 추가
+2. GraphQL 쿼리 작성 (Supabase Studio의 GraphiQL 활용)
+3. 기존 API 호출 코드를 `useFormConfigData`로 교체
+4. 테스트 후 기존 코드 제거
+
+---
+
+## 문제 해결
+
+### GraphQL API 404 오류
+
+**증상**: `ERR_FAILED` 또는 404 응답
+
+**해결책**:
+1. Supabase 프로젝트 설정에서 GraphQL API 활성화
+2. 엔드포인트 확인: `https://.supabase.co/graphql/v1`
+3. `NEXT_PUBLIC_SUPABASE_URL`에 trailing slash 없는지 확인
+
+### 데이터 매핑 오류
+
+**증상**: Form에 데이터가 표시되지 않음
+
+**해결책**:
+1. 콘솔에서 GraphQL 응답 구조 확인
+2. `graphqlToFormData`의 매핑 로직 확인
+3. `columnInfo`의 `table`, `column` 값이 올바른지 확인
+
+### 인증 오류
+
+**증상**: "No active session found"
+
+**해결책**:
+1. Supabase 로그인 상태 확인
+2. `supabase.auth.getSession()` 호출 확인
+3. 토큰 만료 여부 확인
+
+---
+
+## 요약
+
+이 시스템의 핵심은 **"사용자가 쿼리를 작성하고, 시스템은 실행과 매핑만 수행"**하는 것입니다.
+
+**시스템이 하는 일**:
+- ✅ GraphQL 쿼리 실행
+- ✅ 인증 토큰 주입
+- ✅ GraphQL ↔ Form 데이터 매핑
+- ✅ 에러 처리
+- ✅ 로딩 상태 관리
+
+**시스템이 하지 않는 일**:
+- ❌ 쿼리 자동 생성
+- ❌ 테이블 구조 추측
+- ❌ 특정 엔티티에 종속된 로직
+
+이를 통해 **완전한 범용성**과 **명시적인 코드**를 달성했습니다.
diff --git a/docs/FormConfig-GraphQL-Integration.md b/docs/FormConfig-GraphQL-Integration.md
new file mode 100644
index 00000000..5b370fa3
--- /dev/null
+++ b/docs/FormConfig-GraphQL-Integration.md
@@ -0,0 +1,421 @@
+# FormConfig와 GraphQL 쿼리 생성기 연동 가이드
+
+## 개요
+
+FormConfig는 폼 필드의 설정을 정의하는 구조체입니다. 이 가이드는 FormConfig에 ColumnInfo를 추가하여 자동으로 GraphQL 쿼리를 생성하는 방법을 설명합니다.
+
+## FormConfig 구조
+
+### 기본 구조
+
+```typescript
+interface FormConfig {
+ fields: FormFieldConfig[];
+}
+
+interface BaseFieldConfig {
+ label: string;
+ required?: boolean;
+ fieldName: string;
+ columnInfo?: ColumnInfo; // GraphQL 쿼리 생성을 위한 컬럼 정보
+}
+```
+
+### ColumnInfo 추가
+
+각 필드에 `columnInfo` 속성을 추가하여 데이터베이스 테이블과 컬럼 정보를 지정할 수 있습니다:
+
+```typescript
+interface ColumnInfo {
+ table: string; // 테이블명
+ column: string; // 컬럼명
+}
+```
+
+## 필드 타입별 설정
+
+### 1. InputList 필드
+
+```typescript
+{
+ fieldName: 'profiles.full_name',
+ label: '이름',
+ type: 'inputList',
+ required: true,
+ columnInfo: { table: 'profile', column: 'profile_name' },
+ inputConfig: {
+ onlyOne: true,
+ inputs: [
+ {
+ name: 'name',
+ type: 'text',
+ placeholder: '이름을 입력하세요',
+ required: true
+ }
+ ]
+ }
+}
+```
+
+### 2. Picture 필드
+
+```typescript
+{
+ fieldName: 'profiles.avatar_url',
+ label: '프로필 이미지',
+ type: 'picture',
+ required: false,
+ columnInfo: { table: 'profile', column: 'profile_image' },
+ aspectRatio: '1:1'
+}
+```
+
+### 3. SkillTag 필드
+
+```typescript
+{
+ fieldName: 'profile_skills',
+ label: '기술 스택',
+ type: 'skillTag',
+ required: false,
+ columnInfo: { table: 'profile_skills', column: 'skill_id' }
+}
+```
+
+### 4. Checkbox 필드
+
+```typescript
+{
+ fieldName: 'profile.is_team',
+ label: '팀 여부',
+ type: 'checkbox',
+ columnInfo: { table: 'profile', column: 'is_team' },
+ checkboxLabel: '팀 프로필입니다'
+}
+```
+
+## 실제 사용 예시
+
+### 프로필 폼 설정
+
+```typescript
+import { FormConfig } from '@/app/components/modal/inputs/types/inputTypes';
+
+export const profileFormConfig: FormConfig = {
+ fields: [
+ {
+ fieldName: 'profiles.full_name',
+ label: '이름',
+ type: 'inputList',
+ required: true,
+ columnInfo: { table: 'profile', column: 'profile_name' },
+ inputConfig: {
+ onlyOne: true,
+ inputs: [
+ {
+ name: 'name',
+ type: 'text',
+ placeholder: '이름을 입력하세요',
+ required: true
+ }
+ ]
+ }
+ },
+ {
+ fieldName: 'profiles.student_number',
+ label: '학번',
+ type: 'inputList',
+ required: true,
+ columnInfo: { table: 'student', column: 'student_number' },
+ inputConfig: {
+ onlyOne: true,
+ inputs: [
+ {
+ name: 'number',
+ type: 'text',
+ placeholder: '학번을 입력하세요',
+ required: true
+ }
+ ]
+ }
+ },
+ {
+ fieldName: 'profiles.avatar_url',
+ label: '프로필 이미지',
+ type: 'picture',
+ required: false,
+ columnInfo: { table: 'profile', column: 'profile_image' },
+ aspectRatio: '1:1'
+ },
+ {
+ fieldName: 'profiles.bio',
+ label: '자기소개',
+ type: 'inputList',
+ required: false,
+ columnInfo: { table: 'profile', column: 'description' },
+ inputConfig: {
+ onlyOne: true,
+ inputs: [
+ {
+ name: 'description',
+ type: 'text',
+ placeholder: '자기소개를 입력하세요',
+ required: false
+ }
+ ]
+ }
+ }
+ ]
+};
+```
+
+## GraphQL 쿼리 생성
+
+### 1. 기본 사용법
+
+```typescript
+import { getColumnInfoArray } from '@/utils/graphQL/form-config-utils';
+import { generateGraphQLQuery } from '@/utils/graphQL/generateGraphQLQuery';
+
+// FormConfig에서 ColumnInfo 추출
+const columnInfoArray = getColumnInfoArray(profileFormConfig);
+
+// GraphQL 쿼리 생성
+const query = generateGraphQLQuery(columnInfoArray);
+console.log(query);
+```
+
+**생성되는 쿼리:**
+```graphql
+{
+ profile {
+ profile_name
+ profile_image
+ description
+ }
+ student {
+ student_number
+ }
+}
+```
+
+### 2. 고급 사용법
+
+#### 특정 필드만 포함
+
+```typescript
+import { getColumnInfoByFieldName } from '@/utils/graphQL/form-config-utils';
+
+// 특정 필드의 ColumnInfo만 가져오기
+const nameColumnInfo = getColumnInfoByFieldName(profileFormConfig, 'profiles.full_name');
+const avatarColumnInfo = getColumnInfoByFieldName(profileFormConfig, 'profiles.avatar_url');
+
+// 선택된 필드들로만 쿼리 생성
+const selectedColumns = [nameColumnInfo, avatarColumnInfo].filter(Boolean);
+const query = generateGraphQLQuery(selectedColumns);
+```
+
+#### 동적 필드 선택
+
+```typescript
+function createQueryForFields(formConfig: FormConfig, fieldNames: string[]) {
+ const columnInfoArray = fieldNames
+ .map(fieldName => getColumnInfoByFieldName(formConfig, fieldName))
+ .filter(Boolean);
+
+ return generateGraphQLQuery(columnInfoArray);
+}
+
+// 사용 예시
+const query = createQueryForFields(profileFormConfig, [
+ 'profiles.full_name',
+ 'profiles.avatar_url'
+]);
+```
+
+## 유틸리티 함수들
+
+### extractColumnInfoFromFormConfig
+
+FormConfig에서 모든 필드의 ColumnInfo를 추출하여 매칭 객체를 생성합니다.
+
+```typescript
+import { extractColumnInfoFromFormConfig } from '@/utils/graphQL/form-config-utils';
+
+const columnInfoMap = extractColumnInfoFromFormConfig(profileFormConfig);
+console.log(columnInfoMap);
+// {
+// "profiles.full_name": { table: 'profile', column: 'profile_name' },
+// "profiles.student_number": { table: 'student', column: 'student_number' },
+// "profiles.avatar_url": { table: 'profile', column: 'profile_image' },
+// "profiles.bio": { table: 'profile', column: 'description' }
+// }
+```
+
+### getColumnInfoArray
+
+FormConfig에서 ColumnInfo 배열을 추출합니다.
+
+```typescript
+import { getColumnInfoArray } from '@/utils/graphQL/form-config-utils';
+
+const columnInfoArray = getColumnInfoArray(profileFormConfig);
+console.log(columnInfoArray);
+// [
+// { table: 'profile', column: 'profile_name' },
+// { table: 'student', column: 'student_number' },
+// { table: 'profile', column: 'profile_image' },
+// { table: 'profile', column: 'description' }
+// ]
+```
+
+### getColumnInfoByFieldName
+
+특정 필드명에 해당하는 ColumnInfo를 가져옵니다.
+
+```typescript
+import { getColumnInfoByFieldName } from '@/utils/graphQL/form-config-utils';
+
+const nameColumnInfo = getColumnInfoByFieldName(profileFormConfig, 'profiles.full_name');
+console.log(nameColumnInfo); // { table: 'profile', column: 'profile_name' }
+```
+
+## 자동 fallback 처리
+
+ColumnInfo가 명시적으로 설정되지 않은 경우, `fieldName`에서 자동으로 추출합니다:
+
+```typescript
+// columnInfo가 없는 경우
+{
+ fieldName: 'profiles.email', // "profiles.email"에서 자동 추출
+ label: '이메일',
+ type: 'inputList'
+ // columnInfo가 없으면 fieldName에서 추출: { table: 'profiles', column: 'email' }
+}
+```
+
+## 모범 사례
+
+### 1. 명시적 ColumnInfo 사용
+
+가능한 한 명시적으로 `columnInfo`를 설정하는 것을 권장합니다:
+
+```typescript
+// 좋은 예시
+{
+ fieldName: 'profiles.full_name',
+ columnInfo: { table: 'profile', column: 'profile_name' } // 명시적 설정
+}
+
+// 피해야 할 예시
+{
+ fieldName: 'profiles.full_name' // fieldName에 의존
+}
+```
+
+### 2. 일관된 네이밍
+
+테이블명과 컬럼명을 일관되게 사용합니다:
+
+```typescript
+// 일관된 네이밍
+columnInfo: { table: 'profile', column: 'profile_name' }
+columnInfo: { table: 'profile', column: 'profile_image' }
+columnInfo: { table: 'profile', column: 'profile_description' }
+```
+
+### 3. 관계 고려
+
+테이블 간의 관계를 고려하여 적절한 테이블을 지정합니다:
+
+```typescript
+// 프로필 정보
+columnInfo: { table: 'profile', column: 'profile_name' }
+
+// 학생 정보 (프로필과 별도 테이블)
+columnInfo: { table: 'student', column: 'student_number' }
+
+// 프로젝트 정보 (프로필과 관계)
+columnInfo: { table: 'projects', column: 'project_name' }
+```
+
+## 테스트
+
+### 테스트 실행
+
+```bash
+# FormConfig 연동 테스트
+npx tsx src/utils/graphQL/form-config-utils.test.ts
+```
+
+### 테스트 예시
+
+```typescript
+// 테스트용 FormConfig
+const testFormConfig: FormConfig = {
+ fields: [
+ {
+ fieldName: 'test.field1',
+ label: '테스트 필드 1',
+ type: 'inputList',
+ columnInfo: { table: 'test_table', column: 'test_column1' },
+ inputConfig: { /* ... */ }
+ }
+ ]
+};
+
+// 테스트 실행
+const columnInfoArray = getColumnInfoArray(testFormConfig);
+const query = generateGraphQLQuery(columnInfoArray);
+console.log(query);
+```
+
+## 문제 해결
+
+### 자주 발생하는 문제
+
+1. **ColumnInfo가 추출되지 않는 경우**
+ - FormConfig의 각 필드에 `columnInfo` 속성이 올바르게 설정되었는지 확인
+ - `fieldName`이 "테이블명.컬럼명" 형식인지 확인
+
+2. **테이블 관계가 인식되지 않는 경우**
+ - `generateGraphQLQuery.ts`의 `extractTableRelationships` 함수에 해당 관계가 정의되어 있는지 확인
+
+3. **TypeScript 오류**
+ - `BaseFieldConfig` 인터페이스에 `columnInfo?: ColumnInfo` 속성이 추가되었는지 확인
+
+## 확장 가능성
+
+### 새로운 필드 타입 추가
+
+새로운 필드 타입을 추가할 때도 동일한 방식으로 `columnInfo`를 설정할 수 있습니다:
+
+```typescript
+interface NewFieldConfig extends BaseFieldConfig {
+ type: 'newFieldType';
+ // ... 기타 속성들
+ // columnInfo는 BaseFieldConfig에서 상속됨
+}
+```
+
+### 동적 FormConfig 생성
+
+런타임에 FormConfig를 동적으로 생성하여 쿼리를 생성할 수도 있습니다:
+
+```typescript
+function createDynamicFormConfig(fields: Array<{fieldName: string, table: string, column: string}>) {
+ const formConfig: FormConfig = {
+ fields: fields.map(field => ({
+ fieldName: field.fieldName,
+ label: field.fieldName,
+ type: 'inputList',
+ columnInfo: { table: field.table, column: field.column },
+ inputConfig: { /* 기본 설정 */ }
+ }))
+ };
+
+ return formConfig;
+}
+```
+
+이 가이드를 통해 FormConfig와 GraphQL 쿼리 생성기를 효과적으로 연동할 수 있습니다.
diff --git a/docs/GlobalModal.md b/docs/GlobalModal.md
new file mode 100644
index 00000000..906e4471
--- /dev/null
+++ b/docs/GlobalModal.md
@@ -0,0 +1,194 @@
+# 전역 모달 시스템 사용 가이드
+
+## 개요
+Context API를 사용한 전역 모달 관리 시스템입니다. 애플리케이션 어디서든 모달을 쉽게 열고 닫을 수 있습니다.
+
+## 설치 완료된 항목
+- ✅ `ModalContext.tsx` - Context 및 Provider
+- ✅ `Modal.tsx` - 모달 UI 컴포넌트
+- ✅ `modal.css` - 모달 스타일
+- ✅ `layout.tsx` - ModalProvider 및 Modal 컴포넌트 통합
+
+## 사용 방법
+
+### 1. 기본 사용법
+
+```tsx
+'use client';
+
+import { useModal } from '@/app/components/modal';
+
+export default function MyComponent() {
+ const { openModal } = useModal();
+
+ const handleOpenModal = () => {
+ openModal(
+