# 개발 기본설계

## 1. 설계 목표

초기에는 빠르게 배포할 수 있는 단일 웹 애플리케이션으로 시작하되, 콘텐츠와 상담 데이터가 늘어날 때 무리 없이 분리할 수 있게 설계합니다.

## 2. 제안 기술 스택

| 영역 | 제안 | 이유 | 확정 시점 |
|---|---|---|---|
| 웹 | Next.js App Router + TypeScript | SEO, 서버 렌더링, 폼 처리, 배포 생태계 | 구현 시작 전 |
| 스타일 | Tailwind CSS 또는 CSS Modules | 작은 팀의 빠른 UI 반복 | 디자인 시스템 확정 시 |
| 콘텐츠 | 코드 기반 정적 콘텐츠 | 초기 변경 이력과 검수가 단순함 | MVP |
| 상담 저장 | 서버 액션/API + 외부 시트·CRM 또는 DB | 운영 방식에 따라 교체 가능 | 개인정보 검토 후 |
| 검증 | Vitest, Testing Library, Playwright | 단위·컴포넌트·핵심 흐름 분리 | 초기 설정 시 |
| 배포 | Vercel 또는 조직 표준 환경 | Next.js 운영 단순화 | 보안·조달 검토 후 |
| 분석 | 조직 승인 분석 도구 | 퍼널 이벤트 측정 | 개인정보 정책 확정 후 |

기술 이름은 제안이며 확정 사항이 아닙니다. 조직의 보안, 조달, 운영 제약이 우선합니다.

## 3. 시스템 경계

```text
[방문자 브라우저]
       |
       v
[Next.js 웹 애플리케이션]
  |       |          |
  |       |          +--> [분석 서비스]
  |       +-------------> [콘텐츠/이미지]
  +---------------------> [상담 접수 API]
                              |
                              +--> [메일/알림]
                              +--> [운영 시트·CRM 또는 DB]
```

## 4. 개발 폴더 구조

```text
development/
├── README.md
├── apps/
│   └── web/
│       ├── public/
│       │   └── images/
│       └── src/
│           ├── app/              # 라우트, 메타데이터, 서버 엔드포인트
│           ├── components/
│           │   ├── common/       # 버튼, 헤더, 푸터 등 공통 UI
│           │   └── sections/     # 히어로, 사례, FAQ, CTA 등 랜딩 섹션
│           ├── lib/              # 검증, 분석, 외부 연동, 공통 함수
│           └── styles/           # 전역 토큰과 스타일
├── packages/
│   ├── config/                   # 공유 lint, TypeScript, 환경 설정
│   └── ui/
│       └── src/                  # 재사용 가능한 디자인 시스템 요소
└── tests/
    └── e2e/                      # 방문→상담 신청 핵심 흐름
```

하나의 랜딩 사이트만 운영하는 동안에는 `packages/ui`를 억지로 별도 패키지로 배포하지 않습니다. 두 번째 앱이나 실제 재사용 요구가 생길 때 독립 패키지로 승격합니다.

## 5. 화면 구성

| 순서 | 섹션 | 연결 요구사항 | 핵심 역할 |
|---:|---|---|---|
| 1 | Header | PRD-003 | 주요 CTA를 항상 찾을 수 있게 함 |
| 2 | Hero | PRD-001 | 대상, 문제, 제공 가치를 즉시 설명 |
| 3 | Problem / Solution | PRD-001 | 방문자의 상황과 제공 역량을 연결 |
| 4 | Capabilities | PRD-001 | 지원 가능한 SW 분야를 구조화 |
| 5 | Case Studies | PRD-002 | 실제 문제, 실행, 성과를 증명 |
| 6 | Partners / Trust | PRD-002 | 운영 주체와 참여 근거를 제공 |
| 7 | Process | PRD-003 | 상담 이후의 절차와 예상 시간을 설명 |
| 8 | FAQ | PRD-003 | 주요 불확실성과 이탈 요인을 해소 |
| 9 | Contact CTA / Form | PRD-003 | 상담 의도를 수집 |
| 10 | Footer | 정책 | 연락처와 법적 문서 연결 |

## 6. 콘텐츠 모델

```ts
type CaseStudy = {
  id: string;
  title: string;
  industry: string;
  problem: string;
  solution: string;
  outcomes: Array<{ label: string; value: string; evidence?: string }>;
  image: { src: string; alt: string };
  published: boolean;
};

type Inquiry = {
  companyName: string;
  contactName: string;
  email: string;
  phone?: string;
  need: string;
  consent: boolean;
  source?: string;
};
```

실제 저장 전에 입력 길이, 허용 형식, 필수 항목, 보관 기간을 개인정보 담당자와 확정해야 합니다.

## 7. 상담 처리 흐름

1. 클라이언트와 서버에서 입력을 검증합니다.
2. 봇 방지 정책을 적용합니다.
3. 동의 시점과 정책 버전을 함께 기록합니다.
4. 저장 또는 외부 시스템 전달 성공 후에만 완료 화면을 표시합니다.
5. 실패 시 사용자가 입력을 잃지 않도록 복구 가능한 오류를 보여 줍니다.
6. 민감한 입력값은 로그와 분석 이벤트에 남기지 않습니다.

## 8. 분석 이벤트 초안

| 이벤트 | 발생 조건 | 금지 데이터 |
|---|---|---|
| `page_view` | 페이지 유효 조회 | 개인 식별 정보 |
| `section_view` | 핵심 섹션이 화면에 노출 | 자유 입력 내용 |
| `cta_click` | 위치별 주요 CTA 클릭 | 연락처 |
| `form_start` | 첫 폼 상호작용 | 입력값 |
| `form_submit_success` | 서버 접수 성공 | 이름, 이메일, 전화번호 |
| `form_submit_error` | 접수 실패 | 원문 오류나 입력값 |

## 9. 비기능 요구사항

- 모바일 360px부터 데스크톱까지 주요 흐름이 끊기지 않아야 합니다.
- 키보드만으로 탐색하고 폼을 제출할 수 있어야 합니다.
- 이미지에는 의미 있는 대체 텍스트를 제공합니다.
- 목표 성능은 Core Web Vitals의 `good` 범위를 기준으로 잡습니다.
- 비밀 값은 환경 변수로 관리하며 브라우저 번들에 포함하지 않습니다.
- 의존성 오류, 폼 실패, 외부 연동 실패를 관찰할 수 있어야 합니다.
- 개인정보를 로그, URL, 분석 속성에 포함하지 않습니다.

## 10. 테스트 전략

| 층 | 대상 | 예시 |
|---|---|---|
| 정적 검사 | 타입, lint, 형식 | 잘못된 콘텐츠 필드 차단 |
| 단위 테스트 | 검증 및 변환 함수 | 필수 값, 길이, 잘못된 이메일 |
| 컴포넌트 테스트 | 폼과 상호작용 UI | 오류 메시지, 키보드 사용 |
| E2E | 핵심 사용자 흐름 | 방문, CTA, 유효 신청, 실패 복구 |
| 수동 검수 | 반응형·콘텐츠·접근성 | 실제 기기와 주요 브라우저 |

## 11. 환경 구분

- `local`: 개발자 로컬, 테스트 데이터만 사용
- `preview`: 변경 검토, 실제 개인정보 수집 금지
- `production`: 승인된 도메인과 저장소만 사용

환경 변수의 이름과 책임자는 실제 외부 연동 선택 후 `.env.example`에 문서화합니다. 비밀 값 자체는 저장소에 커밋하지 않습니다.

## 12. 기술 결정 기록

| ID | 결정 | 상태 |
|---|---|---|
| ADR-001 | 제품 문서와 실제 소스를 분리한다 | 채택 |
| ADR-002 | MVP는 단일 Next.js 웹 앱으로 시작한다 | 제안 |
| ADR-003 | 초기 콘텐츠는 코드 기반으로 관리한다 | 제안 |
| ADR-004 | 운영 흐름이 검증될 때까지 대규모 CMS를 도입하지 않는다 | 제안 |
| ADR-005 | 개인정보 저장소는 정책 검토 후 선택한다 | 보류 |

## 13. 구현 전 확인 목록

- 브랜드, 카피, 로고와 이미지 사용 권한
- 폼 필드, 동의 문구, 보관 기간
- 상담 저장소와 알림 수신자
- 분석 도구와 쿠키 정책
- 배포 도메인, 보안 헤더, 장애 대응 담당자
- 브라우저 지원 범위와 성능 기준

## 관련 문서

- [기회 정의](../01-product/OPPORTUNITY.md)
- [비즈니스 모델](../02-business/BUSINESS_MODEL.md)
- [개발 작업 안내](../../development/README.md)

