# Albamon 프론트엔드 — 기술 문서

---

## 1. 프로젝트 한 줄 요약

**알바몬(albamon) 모바일 웹**을 위한 **Nx + pnpm 모노레포**입니다. 도메인별로 **Next.js 앱이 여러 개**로 나뉘어 있고, 공통 UI·유틸·API 클라이언트·타입은 `libs/shared`에 둡니다.

---

## 2. 전체 레포 구조

| 구분                  | 경로                                                                | 설명                                                               |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **앱 (Next.js)**      | `apps/services`, `apps/personal`, `apps/business`, `apps/alba-talk` | 서비스별 배포 단위. 각각 독립 `serve` / `build`                    |
| **도메인 라이브러리** | `libs/services`, `libs/personal`, `libs/business`, `libs/alba-talk` | 해당 앱 전용 컴포넌트·템플릿·훅·상수 등                            |
| **공유**              | `libs/shared/*`                                                     | layouts, components, hooks, store, utils, types, **api-client** 등 |
| **도구**              | `tools/*`                                                           | 슬롯 실행, 타입체크, 크로스 import 검사, enum/schema fetch 등      |
| **목 API**            | `apps/mock-api`                                                     | 로컬/테스트용 목 서버                                              |

**빌드·실행**

- 패키지 매니저: **pnpm** (`packageManager` 고정)
- 태스크 러너: **Nx 13** (`@nrwl/next`, `@nrwl/react` 등)
- Personal 로컬: `pnpm personal` → `SERVICE_NAME=personal`로 `nx serve personal` (기본 포트 **4201**, `apps/personal/project.json`)

### 모노레포 구조의 용도

| 목적                          | 설명                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **배포·릴리즈 단위 분리**     | 구직자(`personal`), 공고·검색·이벤트 등 퍼블릭 서비스(`services`), 기업(`business`), 커뮤니티(`alba-talk`)처럼 **제품·URL·트래픽 특성이 다른 영역을 앱 단위로 쪼개** 독립 빌드·배포한다. (`pnpm personal`, `pnpm services` 등) |
| **공통 자산의 단일 유지보수** | 레이아웃, 디자인 시스템에 가까운 컴포넌트, 인증/로깅 유틸, **API 클라이언트·BFF 타입**을 `libs/shared`에 모아 **중복 구현을 줄이고** 변경 시 한곳을 고친다.                                                                    |
| **도메인 소유권과 경계**      | 앱별 전용 코드는 `libs/services`, `libs/personal`, `libs/business`, `libs/alba-talk` 등에 두고, **타 앱 라이브러리 직접 참조를 막는 검사**(예: `tools/cross-imports-checker`)로 결합도를 관리한다.                             |
| **툴링·품질 일원화**          | Nx로 빌드/캐시, ESLint, 타입체크 스크립트를 공통으로 두어 **여러 앱을 같은 규칙**으로 돌린다.                                                                                                                                  |
| **의존성·버전 정합**          | pnpm 워크스페이스로 **루트 `package.json` 기준** 의존성을 맞추고, 앱 간 버전 드리프트를 줄인다.                                                                                                                                |

요약하면, **“한 레포에서 여러 Next 앱을 같이 키우되, 공유는 `shared`로, 도메인 전용은 앱·라이브러리 경계로 나눈다”**는 형태입니다. 마이페이지·이력서 등은 주로 `personal`, 이벤트·일부 퍼블릭 페이지는 `services`, 인재관리(기업)는 `business` 쪽에 가깝게 배치되는 식으로 **업무에 따라 앱이 갈라질 수 있다**는 점도 용도에 포함됩니다.

---

## 3. 공통 기술 스택 (레포 전체)

| 영역                    | 기술                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| 프레임워크              | **Next.js 12**, **React 17**                                                               |
| 언어                    | **TypeScript 4.x**                                                                         |
| 스타일                  | **SCSS** (Nx generator 기본), 일부 **Tailwind 4** (루트 devDependencies)                   |
| 서버 상태 / 데이터 패칭 | **React Query v3** (`QueryClientProvider`, `Hydrate`)                                      |
| 폼·검증                 | **react-hook-form**, **yup**, **zod**                                                      |
| 전역 상태               | **zustand**, 공유 **store** (`libs/shared/store`)                                          |
| HTTP                    | **axios** 기반 API 레이어 (`libs/shared/api-client`)                                       |
| 관측·품질               | **Sentry** (`@sentry/nextjs`), **OpenTelemetry** (웹 SDK), **Datadog RUM**, **web-vitals** |
| 실험·분석               | **Statsig** (클라이언트 부트스트랩 등), **Braze**, GA 연동 유틸                            |
| 기타 UI/기능            | Swiper, Video.js, CKEditor, react-cropper / 이미지 크롭, 지도(Kakao 등), Lottie 등         |

Next 설정상 **Personal**은 `output: 'standalone'`, **basePath: `/personal`**, 이미지 도메인 화이트리스트, 보안 헤더(`X-Frame-Options` 등), 개발 시 CORS 헤더 등이 적용됩니다.

---

## 4. Personal 서비스 상세

### 4.1 역할 (비즈니스 관점)

**구직자(개인 회원)** 중심 영역으로 추정되는 화면군이 모여 있습니다.

- **마이페이지·홈 진입**
- **계정**: 비밀번호·본인인증·탈퇴·프로필/메일·SNS 로그인 등
- **이력서**: 등록/수정(다단계), 간편 이력서, 공개·미리보기, 포트폴리오, 스크랩/추천·리포트, 이력서 제한(카테고리·기업별) 등
- **지원**: 지원하기, 지원 내역(타입별), 면접 제안 등
- **관심 기업**: 폴더·목록·지도·조건, 채용 공고 스크랩
- **구직 활동**: 이슈, 검색 이력 등
- **미디어**: 사진/동영상/크롭/뷰어·프로필 이미지
- **유료 상품**: 이력서 상품·이용 내역
- **개인정보 침해 신고·보상·결과**
- **알바몬 Z 온보딩** (스케줄, 파트, 스킬, 이력서 등 단계)
- **헬스체크·퍼지 캐시** 등 운영용 페이지
- **API 라우트**: 로깅, OTEL 프록시, purge-cache 등

라우트는 `apps/personal/pages/` 아래 **파일 기반 라우팅**으로 구성됩니다.

### 4.2 앱 레이어 (`apps/personal`)

| 파일/영역                           | 역할                                                                                                                                          |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `_app.tsx`                          | React Query, 레이아웃(`DefaultLayout`/`NoneLayout`), 세션·인증 연동, **Statsig**, Sentry, Braze/GA 초기화, 공통 훅(액세스 로깅, 앱 브릿지 등) |
| `_document.tsx`                     | 문서 셸                                                                                                                                       |
| `next.config.js`                    | `basePath`, `assetPrefix`, redirect(예: `/resume` → `/resume-manage`), 이미지·헤더                                                            |
| `Dockerfile` / `sentry.*.config.js` | 배포·에러 수집                                                                                                                                |

인증 예외 경로 예: `notRequiredAuthUrl`에 `/health`, `/purge-cache` 등.

### 4.3 도메인 라이브러리 (`libs/personal`)

Personal 전용 코드는 **다음 모듈로 분리**됩니다 (경로 별칭: `@albamon-mobile-frontend-web/personal/*`).

| 라이브러리                 | 용도                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `libs/personal/components` | UI 컴포넌트 (이력서 스텝, 지원 폼, 계정, 미디어, 상품 카드 등). **Storybook** 타깃 존재 |
| `libs/personal/templates`  | 페이지 단위 조합·레이아웃 템플릿                                                        |
| `libs/personal/hooks`      | 도메인 훅 (예: 이력서 검증, 역량 데이터 변환)                                           |
| `libs/personal/constants`  | 문구·설정 상수                                                                          |
| `libs/personal/utils`      | 이력서 매니저 등 도메인 유틸                                                            |
| `libs/personal/types`      | Personal 타입                                                                           |
| `libs/personal/store`      | 이력서·미디어 뷰어 등 **zustand** 스토어 (`withResumeStore` 등)                         |

### 4.4 API 및 BFF 타입 (`libs/shared`)

Personal은 **다른 앱과 동일하게** 공유 API 클라이언트를 씁니다.

- **클라이언트 코드**: `libs/shared/api-client/personal/`
  - 도메인별로 `*.api.ts`, `*.queries.ts`, `*.mutations.ts` 등 **React Query** 패턴
  - 예: `resume`, `apply`, `favorite`, `mypage`, `account`, `media`, `job-search`, `mailing`, `product`, `leave`, `member` …
- **BFF/응답 타입**: `libs/shared/types/bff/personal/`
  - `resume`, `apply`, `mypage`, `member`, `product`, `events`, `albamonz` 등 스키마 정리

즉, **화면은 `apps/personal` + `libs/personal`**, **통신·계약은 `libs/shared/api-client` + `libs/shared/types`**에 두는 구조입니다.

### 4.5 아키텍처 규칙: 크로스 import 방지

`tools/cross-imports-checker/personal.sh` 기준:

- `apps/personal`, `libs/personal` 소스에서 **`alba-talk` / `business` / `services` 라이브러리 직접 import 금지**
- Personal은 **shared + personal libs + api-client** 조합으로 경계를 유지

경력기술서에는 **「도메인 경계를 스크립트로 강제하는 모노레포」**로 표현 가능합니다.

---

## 5. 담당 도메인

아래는 **업무 영역별**로 옮기기 좋은 문장 예시입니다. 실제 담당 범위·성과에 맞게 숫자·기능명을 구체화하세요. (스택은 공통으로 **Next.js, React, TypeScript, React Query, react-hook-form, zustand** 등을 가정한 표현입니다.)

- **마이페이지**  
  구직자 마이페이지에서 **요약 정보·메뉴 진입·세션/권한에 따른 노출**을 다루며, 공유 레이아웃·스토어와 연동해 **모바일 웹 UX**를 맞추었다.

- **이력서(작성/등록, 수정, 상세 입력)**  
  이력서 **다단계 등록·수정 플로우**와 학력·경력·역량 등 **상세 입력 화면**을 구현하였고, 폼 검증·임시저장·API 연동(React Query 기반)으로 **입력 완결도**를 높이는 데 기여하였다.

- **포트폴리오(등록/관리)**  
  포트폴리오 **등록·수정·목록 관리** UI와 파일/미디어 처리 흐름을 다루며, 이력서 도메인 컴포넌트·템플릿(`libs/personal`)과 API 계층을 연결하였다.

- **지원현황(조회/관리)**  
  지원 내역 **목록·상세·상태별 필터/탭** 등 **조회·관리** 화면을 구현하고, 지원 취소·숨김 등 액션과 서버 상태 동기화를 처리하였다.

- **인재관리(리스트, 상세)**  
  기업 측 **인재(지원자) 리스트·상세** 화면에서 목록 조회, 상세 패널, 검색·정렬 등 **데이터 밀도가 높은 테이블/폼 UI**를 구현·개선하였다. _(구현 위치는 주로 `apps/business`·관련 `libs/business` 등 기업 앱 쪽에 해당하는 경우가 많음.)_

- **이벤트/프로모션 페이지**  
  **이벤트·프로모션 랜딩** 페이지를 기획/디자인에 맞춰 구현하고, 공통 컴포넌트·트래킹(분석·실험 도구) 연동을 반영하였다. _(구현 위치는 주로 `apps/services`의 `pages/events` 등 퍼블릭 서비스 앱 쪽에 해당하는 경우가 많음.)_

**한 줄로 묶을 때 (선택)**  
Nx·pnpm 모노레포 환경에서 **마이페이지·이력서·포트폴리오·지원현황** 등 구직자 도메인과 **인재관리·이벤트 페이지**까지, 앱 경계에 맞춰 화면을 나누어 개발하였다.

---

## 6. 빠른 참고: Personal 페이지 디렉터리 맵 (요약)

```
apps/personal/pages/
├── index, mypage, health, …
├── account/          # 계정·인증·탈퇴·메일 등
├── apply/            # 지원·목록·면접 제안
├── favorite/corp/    # 관심 기업·지도·폴더
├── job-search/       # 구직 활동 관련
├── media/            # 사진·동영상·크롭·뷰어
├── product/          # 이력서 상품 등
├── resume*/          # 이력서 관리·등록·간편·공개·스크랩·제한 등
├── privacy-intrusion/
├── albamon-z/onboarding/
└── api/              # 로깅, OTEL, purge-cache 등
```

---


잡코리아 내에서 알바몬 MSA 로 진행했던 프로젝트입니다.

성 연 철

알바몬 MSA 프로젝트