###  잡코리아 비즈센터 구축 (PC)

**요약**

- 지원자 관리 및 채용 성과 리포트 기능을 구축하고, 복잡한 UI/상태를 구조화해 **유지보수성과 성능을 함께 개선**

**기간**

- 2025.02 ~ 2025.03 (진행중)

**아키텍처/구조**

- **FSD + DDP** 혼합 구조로 UI/도메인/데이터 계층 분리

**기술적 기여(How I improved it)**

- views/features/entities/core-data 계층 분리로 책임 경계 명확화
- Repository + Mapper + Domain Service 패턴으로 API 스키마 변경 영향 최소화
- Selection/Kanban/Table/Actions 컨텍스트 분리 및 동적 import 적용으로 복잡 상태/렌더 비용 최적화
- TanStack Query 기반 캐시 무효화/동기화 전략 설계로 목록-상세 데이터 정합성 개선
- Domain Service에서 API 응답을 UI 전용 모델로 변환하여 재사용성과 유지보수성 확보
- Vitest 기반 훅/도메인 테스트로 회귀 안정성 강화

사용 기술

- **Frontend**: React 18, Next.js, React Query(TanStack Query)
- **스타일링:** jds/theme (사내용 UI 컴포넌트), Tailwind CSS 3, vanilla-extract(병행)
- **모니터링:** Sentry
- **CI/CD**: Jenkins, Argo CD, GitLab 기반 빌드·배포 프로세스
- **Collaboration**: Notion, Slack, JIRA

역할

- 지원자 관리(ATS) 화면 복잡도 제어 (STAR)
    - **Situation / Task**
    - 칸반/테이블 2개 뷰를 동시에 운영하는 지원자 목록 화면에서, 검색·필터·정렬·페이지네이션·상세 모달 등 **상태 조합이 폭증**하여 유지보수와 성능 리스크가 커짐
    - 동일 데이터 소스를 뷰별로 안정적으로 재사용할 수 있도록 화면 상태를 4개의 Context로 분리
        - Selection
        - Kanban
        - Table
        - Actions
    - 액션(모달 닫힘/열림, 스크랩 변경, 단계 이동 등) 이후 목록-상세 정합성을 보장하도록 **TanStack Query invalidate/remove 전략**을 설계
    - 빈 상태(검색 결과 없음, 공고 자체 지원자 없음)와 예외(잘못된 공고 ID)를 분리 처리해 운영 안정성 강화
- 지원자 액션 플로우 고도화
    - 스크랩, 삭제, 면접 제안, 일괄 액션 등 실무 운영 기능을 화면 단에서 일관된 패턴으로 구현
    - 상태 반영 지연을 줄이기 위해 일부 액션은 **낙관적 업데이트 + 쿼리 동기화** 조합으로 처리
    - 상세 조회 시 열람 상태 반영, 재오픈 시 최신 데이터 보장 등
    
- 채용 리포트 도메인 구조화
    - 단일 리포트/비교 리포트를 하나의 모달 체계에서 분기 처리해 UI 재사용성 확보
    - 리포트 섹션별 데이터 변환 로직을 Domain Service로 모아
    - 화면 컴포넌트는 렌더링 역할에 집중하도록 분리
        - 처리 지표:
        - 매체별 조회수/지원자수/전환율
        - 시간대별 성과
        - 지원자 분포(연령/성별/경력/학력/희망연봉)
        - 채용 단계별 퍼널
        - 경쟁력 및 상품 성과 비교
        - 비교 리포트 인사이트 생성 로직을 분리해, 공고 간 상대 성과 해석을 UI에 일관되게 제공
- 데이터 계층 안정화(DDP)
    - Repository -> Mapper -> Domain Service -> Hook/UI 흐름으로 데이터 접근 단일화
    - API 응답 DTO와 화면 모델을 분리해 스키마 변경 시 영향 범위를 축소
    - 결과적으로 기능 추가/변경 시 화면 수정 범위를 줄이고, 회귀 리스크를 낮춤
- 성능/품질 관점 작업
    - 무거운 컴포넌트들(상세/리스트 일부)을 **dynamic import**로 분리해 초기 로딩 부담 완화
    - 훅/도메인 단 테스트(Vitest) 기반으로 핵심 로직 회귀 방지
    - ESLint/Prettier/Typecheck 파이프라인과 함께 코드 일관성 유지

잡코리아내의 기업서비스를 분리 및 리뉴얼

Next.js

React.js

TailwindCSS

TypeScript

잡코리아 비즈센터 구축

# 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 로 진행했던 프로젝트입니다.

Scss

Storybook

Webpack

Jest

알바몬 MSA 프로젝트

# 연철s 포트폴리오 어드민

개인 포트폴리오 웹사이트를 관리하기 위한 관리자 대시보드입니다. Next.js와 VisActor를 활용하여 현대적이고 직관적인 인터페이스를 제공합니다.

## 기능

- 📊 **포트폴리오 관리** - 프로젝트, 기술 스택, 경력 등 포트폴리오 콘텐츠 관리
- 📝 **콘텐츠 에디터** - 마크다운 기반의 풍부한 텍스트 에디터
- 🌗 **다크 모드** - 시스템 환경설정을 지원하는 다크/라이트 모드
- 📱 **반응형 디자인** - 모든 디바이스에서 사용 가능
- 🔒 **인증 시스템** - 관리자 로그인
- 📈 **데이터 시각화** - 포트폴리오 방문자 통계 및 분석

## 기술 스택

- [Next.js 15.0.1](https://nextjs.org/) - React 프레임워크
- [React 19.0.0-rc](https://react.dev/) - UI 라이브러리
- [TypeScript 5.5.4](https://www.typescriptlang.org/) - 타입 안정성
- [Tailwind CSS 3.4.1](https://tailwindcss.com/) - 스타일링
- [VisActor 1.12.10](https://visactor.io/) - 데이터 시각화
- [Supabase 2.49.4](https://supabase.com/) - 백엔드 및 데이터베이스
- [AWS S3 SDK 3.812.0](https://aws.amazon.com/s3/) - 파일 스토리지
- [React Hook Form 7.56.4](https://react-hook-form.com/) - 폼 관리
- [SWR 2.3.3](https://swr.vercel.app/) - 데이터 페칭
- [Jotai 2.10.1](https://jotai.org/) - 상태 관리
- [React Markdown 10.1.0](https://github.com/remarkjs/react-markdown) - 마크다운 렌더링
- [Next Themes 0.3.0](https://github.com/pacocoursey/next-themes) - 테마 관리
- [React Hot Toast 2.5.2](https://react-hot-toast.com/) - 토스트 알림
- [Radix UI 2.1.1](https://www.radix-ui.com/) - 접근성 컴포넌트
- [Lucide React 0.436.0](https://lucide.dev/) - 아이콘
- [Date-fns 3.6.0](https://date-fns.org/) - 날짜 유틸리티

## 시작하기

1. 저장소를 클론합니다

```bash
git clone https://github.com/your-username/portfolio-admin.git
cd portfolio-admin
```

2. 의존성을 설치합니다

```bash
pnpm install
```

3. 환경 변수를 설정합니다

```bash
cp .env.example .env.local
```

4. 개발 서버를 실행합니다

```bash
pnpm dev
```

5. 브라우저에서 [http://localhost:3000](http://localhost:3000)을 열어 확인합니다.

## 프로젝트 구조

```bash
src/
├── app/                    # Next.js 앱 라우터
│   ├── (dashboard)/        # 대시보드 페이지
│   ├── project/            # 프로젝트 관련 페이지
│   │   ├── create/         # 프로젝트 생성
│   │   ├── edit/           # 프로젝트 수정
│   │   ├── preview/        # 프로젝트 미리보기
│   │   └── write/          # 프로젝트 작성
│   ├── ticket/             # 티켓 관련 페이지
│   └── api/                # API 라우트
├── components/             # React 컴포넌트
│   ├── nav/                # 네비게이션 컴포넌트
│   ├── providers/          # Provider 컴포넌트
│   └── ui/                 # UI 컴포넌트
├── config/                 # 설정 파일
├── data/                   # 정적 데이터 및 샘플 데이터
├── hooks/                  # 커스텀 React 훅
├── lib/                    # 유틸리티 함수 및 상태 관리
│   ├── context/            # 컨텍스트 관련
│   ├── file/               # 파일 관련 유틸
│   └── zustand/            # Zustand 상태 관리
├── docs/                   # api type
├── style/                  # 전역 및 커스텀 스타일
└── types/                  # 내부에서 사용하는 type
```

## 주요 기능 상세

### 포트폴리오 관리

- 프로젝트 CRUD 작업
- 마크다운 콘텐츠 미리보기
- 프로젝트 상태 관리
- 프로젝트 이미지 업로드
- 기술 stack 관리
- 프로젝트 순서 정렬 기능

### 콘텐츠 에디터

- 마크다운 지원
- 이미지 업로드
- 코드 하이라이팅
- 실시간 미리보기

### 데이터 시각화

- 방문자 통계
- 페이지별 조회수
- 사용자 행동 분석
- 트래픽 소스 분석

## 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.


포트폴리오를 관리하기 위한 관리자 사이트입니다.

Styled Components

포트폴리오 어드민

# 연철s 포트폴리오 어드민

개인 포트폴리오 웹사이트를 관리하기 위한 관리자 대시보드입니다. Next.js와 VisActor를 활용하여 현대적이고 직관적인 인터페이스를 제공합니다.

## 기능

- 📊 **포트폴리오 관리** - 프로젝트, 기술 스택, 경력 등 포트폴리오 콘텐츠 관리
- 📝 **콘텐츠 에디터** - 마크다운 기반의 풍부한 텍스트 에디터
- 🌗 **다크 모드** - 시스템 환경설정을 지원하는 다크/라이트 모드
- 📱 **반응형 디자인** - 모든 디바이스에서 사용 가능
- 🔒 **인증 시스템** - 관리자 로그인
- 📈 **데이터 시각화** - 포트폴리오 방문자 통계 및 분석

## 기술 스택

- [Next.js 15.0.1](https://nextjs.org/) - React 프레임워크
- [React 19.0.0-rc](https://react.dev/) - UI 라이브러리
- [TypeScript 5.5.4](https://www.typescriptlang.org/) - 타입 안정성
- [Tailwind CSS 3.4.1](https://tailwindcss.com/) - 스타일링
- [VisActor 1.12.10](https://visactor.io/) - 데이터 시각화
- [Supabase 2.49.4](https://supabase.com/) - 백엔드 및 데이터베이스
- [AWS S3 SDK 3.812.0](https://aws.amazon.com/s3/) - 파일 스토리지
- [React Hook Form 7.56.4](https://react-hook-form.com/) - 폼 관리
- [SWR 2.3.3](https://swr.vercel.app/) - 데이터 페칭
- [Jotai 2.10.1](https://jotai.org/) - 상태 관리
- [React Markdown 10.1.0](https://github.com/remarkjs/react-markdown) - 마크다운 렌더링
- [Next Themes 0.3.0](https://github.com/pacocoursey/next-themes) - 테마 관리
- [React Hot Toast 2.5.2](https://react-hot-toast.com/) - 토스트 알림
- [Radix UI 2.1.1](https://www.radix-ui.com/) - 접근성 컴포넌트
- [Lucide React 0.436.0](https://lucide.dev/) - 아이콘
- [Date-fns 3.6.0](https://date-fns.org/) - 날짜 유틸리티

## 시작하기

1. 저장소를 클론합니다

```bash
git clone https://github.com/your-username/portfolio-admin.git
cd portfolio-admin
```

2. 의존성을 설치합니다

```bash
pnpm install
```

3. 환경 변수를 설정합니다

```bash
cp .env.example .env.local
```

4. 개발 서버를 실행합니다

```bash
pnpm dev
```

5. 브라우저에서 [http://localhost:3000](http://localhost:3000)을 열어 확인합니다.

## 프로젝트 구조

```bash
src/
├── app/                    # Next.js 앱 라우터
│   ├── (auth)/            # 인증 관련 페이지
│   ├── (dashboard)/       # 대시보드 페이지
│   └── api/               # API 라우트
├── components/            # React 컴포넌트
│   ├── dashboard/        # 대시보드 컴포넌트
│   ├── editor/          # 에디터 컴포넌트
│   ├── forms/           # 폼 컴포넌트
│   └── ui/              # UI 컴포넌트
├── lib/                  # 유틸리티 함수
├── styles/              # 전역 스타일
└── types/               # TypeScript 타입
```

## 주요 기능 상세

### 포트폴리오 관리

- 프로젝트 CRUD 작업
- 마크다운 콘텐츠 미리보기
- 프로젝트 상태 관리
- 프로젝트 이미지 업로드
- 기술 스택 관리

### 콘텐츠 에디터

- 마크다운 지원
- 이미지 업로드
- 코드 하이라이팅
- 실시간 미리보기

### 데이터 시각화

- 방문자 통계
- 페이지별 조회수
- 사용자 행동 분석
- 트래픽 소스 분석

## 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.


제가 작업헀던 내용을 정리하기 위해 제작한 개인 포트폴리오 사이트입니다.

Node.js

JavaScript

supabase

포트폴리오 프로젝트

# 📈 Stock AI Platform 프로젝트 소개

## 📋 개요

`stock-ai-platform`은 **국내/해외 주식 데이터를 실시간으로 조회하고, AI 기반 분석 및 추천을 제공하는 대시보드형 웹 서비스**입니다.  
KIS Open API를 통해 종목 데이터를 수집하고, Groq LLM으로 뉴스 컨텍스트 기반 인사이트를 생성해 투자 판단에 참고할 수 있는 정보를 제공합니다.

---

## 🛠️ 기술 스택

### Core Technologies

- **Next.js 16.1.6 (App Router)** - 풀스택 웹 애플리케이션 프레임워크
- **React 19.2.3** - UI 컴포넌트 기반 렌더링
- **TypeScript 5.x** - 정적 타입 시스템
- **TanStack Query 5.x** - 서버 상태 캐싱/동기화

### Data & AI

- **KIS Open API** - 국내/해외 종목 시세 및 랭킹 데이터 소스
- **Groq SDK** - 종목 분석 및 추천 생성 LLM 호출
- **SerpAPI / Bing News / Yahoo Finance** - 뉴스 컨텍스트 수집(폴백 체인)
- **Supabase** - KIS 액세스 토큰 저장 및 분산 락 기반 갱신(선택 사용)

### UI & Visualization

- **Tailwind CSS 4** - 유틸리티 기반 스타일링
- **lightweight-charts** - 가격 히스토리 차트 렌더링
- **lucide-react** - 아이콘 시스템

### Testing & Quality

- **Vitest + Testing Library + jsdom** - 단위/컴포넌트 테스트
- **Playwright** - E2E 시나리오 테스트
- **ESLint 9 + eslint-config-next** - 코드 품질 관리

---

## ⚡ 주요 기능

### 1) 국내/해외 주식 대시보드

- 기본 진입 시 `/domestic`으로 리다이렉트
- 탭 기반으로 국내/해외 시장 전환
- 국내 종목은 **거래량/거래대금 기준 TOP 20** 필터 지원
- 종목 선택 시 우측 패널에서 AI 분석 결과 확인

### 2) 통합 종목 검색

- 종목명/티커 기준 `search` 페이지 제공
- 국내/해외 결과를 통합 조회
- 검색 결과에서 바로 AI 분석 실행 가능

### 3) AI 종목 분석 (Streaming)

- `POST /api/stock-analysis`를 통해 분석 결과를 스트리밍 텍스트로 수신
- 가격 히스토리 + 변동률 + 뉴스 컨텍스트를 함께 프롬프트로 전달
- 결과는 `Bullish/Bearish/Neutral`, 핵심 요약, 상승/하락 요인, 리스크 등 구조화된 JSON 포맷 기준으로 생성

### 4) AI 추천 TOP 3

- `POST /api/recommendations`에서 종목 후보군을 정량 점수로 1차 필터링
- 모멘텀/변동률 기반 `quantScore` 상위 후보 + 뉴스 컨텍스트를 결합해 추천 생성
- LLM 실패 시 정량 점수 기반 fallback 추천으로 서비스 연속성 보장
- 대시보드에서 5분 주기로 추천 자동 갱신

### 5) 안정적인 KIS 토큰 관리

- 토큰 발급/갱신 로직을 서비스 레이어로 분리
- Supabase 설정 시 `kis_tokens` 테이블 기반 분산 락으로 동시 갱신 충돌 완화
- Supabase 미설정 환경에서는 메모리 캐시 폴백으로 동작

---

## 🔌 주요 API 엔드포인트

| 엔드포인트 | 메서드 | 설명 |
| --- | --- | --- |
| `/api/stocks` | `GET` | 시장별 종목 리스트 조회 (`market`, `ranking`) |
| `/api/stocks/search` | `GET` | 종목명/티커 검색 (`q` 또는 `query`) |
| `/api/stocks/item` | `GET` | 특정 종목 상세 조회 (`id`) |
| `/api/stock-analysis` | `POST` | 단일 종목 AI 분석 스트리밍 |
| `/api/recommendations` | `POST` | 시장별 AI 추천 종목 반환 |

---

## 🔐 환경 변수

| 키 | 용도 |
| --- | --- |
| `GROQ_API_KEY` | AI 분석/추천 LLM 호출 |
| `SERPAPI_KEY` | 뉴스 컨텍스트 1순위 수집 |
| `BING_NEWS_KEY` | 뉴스 컨텍스트 2순위 수집 |
| `KIS_APP_KEY` | KIS API 인증 |
| `KIS_APP_SECRET` | KIS API 인증 |
| `KIS_BASE_URL` | KIS API Base URL |
| `SUPABASE_URL` | 토큰 저장소(Supabase) 연결 |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase 서버 권한 키 |

---

## 🧪 테스트 및 개발 경험

### 테스트 구성

- API 라우트 테스트: `src/app/api/**/*.test.ts`
- 서비스 레이어 테스트: `src/services/*.test.ts`
- UI/훅 테스트: `src/components/**/*.test.tsx`, `src/hooks/*.test.tsx`
- E2E 테스트: `e2e/stock-flows.spec.ts`

### 실행 스크립트

- `pnpm dev` - 개발 서버 실행
- `pnpm test` - Vitest 실행
- `pnpm coverage` - 커버리지 리포트 생성
- `pnpm e2e` - Playwright E2E 실행

---

## 🎯 프로젝트 가치

- 실시간 주식 데이터와 AI 인사이트를 한 화면에서 제공해 탐색 시간을 단축
- 국내/해외 시장을 통합해 비교 분석 경험을 개선
- 외부 API 실패 상황에서도 fallback 경로를 갖춘 안정적인 사용자 경험 제공


주식 분석 플랫폼

# Dreamweaver-AI 프로젝트 개요

## 프로젝트 소개

Dreamweaver-AI는 사용자가 입력한 키워드(주인공, 친구, 배경, 교훈, 그림 스타일)를 바탕으로 AI가 어린이 그림책 스토리를 생성하고, 선택적으로 삽화를 생성해 책 형태로 보여주는 웹 애플리케이션입니다.

생성된 결과는 공유 링크로 저장하고 다시 열람할 수 있으며, 마지막 공유본은 로컬 스토리지 fallback으로도 확인할 수 있습니다.

## 기술 스택

### Frontend

- `Next.js 15` (App Router)
- `React 19`
- `TypeScript`
- `Tailwind CSS v4` + `globals.css` 커스텀 테마 변수

### Backend/API (Next.js Route Handlers)

- `zod` 기반 요청/응답 검증
- `ReadableStream + SSE` 방식의 스트리밍 응답
- 외부 AI API 연동
  - 스토리 생성/추천: `Groq API`
  - 이미지 생성: `OpenAI Images API`

### Data/Storage

- `Supabase`
  - 공유 스토리 메타/본문 저장 (`storybook_shares`)
  - 삽화 업로드 및 공개 URL 제공 (`storybook-images` storage bucket)
  - 조회수 증가 RPC 사용 (`increment_share_view_count`)

## 핵심 기능

### 1) AI 그림책 생성

- 입력값: 주인공, 친구, 배경, 교훈, 스타일, 삽화 생성 여부
- `/api/generate`에서 스토리 생성 후 SSE로 텍스트를 점진 전송
- 클라이언트는 `story_delta` 이벤트를 받아 타이핑 애니메이션처럼 렌더링
- 삽화 옵션 활성화 시 스토리 생성 후 이미지 생성 단계 진행

### 2) 추천 후 즉시 생성 플로우

- `/api/recommend`에서 AI가 입력 필드를 추천
- 추천값을 폼에 반영한 뒤 바로 생성 API를 호출해 원클릭 생성 UX 제공
- 비정상 응답 대비 fallback 값 내장

### 3) 책 형태 뷰어 UX

- `BookViewer` 컴포넌트에서 표지/본문/뒷표지 구조로 렌더링
- 페이지 넘김 애니메이션(앞/뒤 방향) 제공
- 본문을 문단 단위로 분리하고 페이지 길이에 맞춰 자동 페이징

### 4) 공유/재열람

- 공유 시 해시 기반 ID 생성 후 `/api/share/[id]`에 저장
- 이미지가 data URL이면 Supabase Storage에 업로드 후 공개 URL로 치환
- `/share?id=...`에서 공유본 조회, 조회수 증가 처리
- 서버 조회 실패 시 localStorage fallback으로 복구 시도

### 5) 안정성 및 품질 보강

- 한글 중심 입력/출력 정규화 및 길이 제한
- JSON 파싱 실패 시 보조 추출/복구 로직 제공
- API 키 누락, 외부 API 실패, 이미지 생성 실패 등 예외 처리

## 주요 API 엔드포인트

- `POST /api/generate`: 스토리/삽화 생성 (SSE)
- `POST /api/recommend`: 입력 추천값 생성
- `POST /api/share/[id]`: 공유 데이터 저장
- `GET /api/share/[id]`: 공유 데이터 조회 및 view count 증가

## 실행 스크립트

- `pnpm run dev` : 개발 서버 실행
- `pnpm run build`: 프로덕션 빌드
- `pnpm run start`: 프로덕션 서버 실행
- `pnpm run lint`: 린트 실행

## 환경 변수(요약)

실행 시 아래 계열 변수가 필요합니다.

- Groq: `GROQ_API_KEY`, `GROQ_MODEL`, `GROQ_RECOMMEND_MODEL`
- OpenAI: `OPENAI_API_KEY`, `OPENAI_IMAGE_MODEL`, `OPENAI_IMAGE_SIZE`, `OPENAI_IMAGE_TIMEOUT_MS`
- Supabase: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`

프로젝트 운영 환경에 따라 일부 변수는 선택적으로 사용됩니다.


AI 로 만든 나만의 동화책을 공유해보세요!

Prisma

AI 동화책 만들기

# 🍳 Albamon Deep Link 프로젝트

## 📋 개요

**@albamon/deep-link**는 알바몬 모바일 앱과 웹 간의 원활한 연동을 위하여 제작한 딥링크 관리 시스템입니다.
크로스 플랫폼 환경에서 사용자가 웹에서 앱으로 자연스럽게 이동할 수 있도록 하는 솔루션을 제공합니다.

---

## 🛠️ 기술 스택

### **Core Technologies**

- **React 17.0.2** - UI 컴포넌트 라이브러리
- **TypeScript ~5.4.0** - 정적 타입 시스템
- **Next.js 12.2.2** - React 기반 풀스택 프레임워크
- **Vite 5.1.0** - 빠른 개발 서버 및 빌드 도구

### **Styling & UI**

- **Tailwind CSS 3.4.17** - 유틸리티 퍼스트 CSS 프레임워크
- **PostCSS 8.5.3** - CSS 후처리 도구
- **Autoprefixer 10.4.20** - CSS 벤더 프리픽스 자동 추가

### **Development Tools**

- **ESLint 9.19.0** - 코드 품질 검사
- **Prettier 2.5.1** - 코드 포맷팅
- **Husky 9.1.7** - Git 훅 관리
- **Changesets 2.28.1** - 버전 관리 및 릴리즈

### **Build & Package Management**

- **pnpm** - 패키지 매니저
- **vite-plugin-dts** - TypeScript 선언 파일 생성
- **vite-tsconfig-paths** - TypeScript 경로 별칭 지원

---

## ⚡ 주요 기능


### **패키지 배포 자동화**
- nexus 서버에 vite를 사용한 패키지 자동 배포
- git push 시에 자동으로 패키지를 배포 여부 선택 기능 (CLI)
- 배포 시 changelog 사용으로 버전별로 자동으로 문서 관리

### **데모 컴포넌트 UI 제공**
- 데모 컴포넌트를 패키지에 같이 제공하여 편의성 제공 
- tailwindcss 사용으로 간단한 스타일링 적용


### **앱 설치 여부 감지**

- **visibilitychange** 이벤트 활용
- 타이머 기반 폴백 처리 (기본 3초)
- 스토어 리디렉션 자동화


### **설정 가능한 Props**

| 프로퍼티     | 타입                     | 설명                 |
| ------------ | ------------------------ | -------------------- |
| `query`      | `Record<string, string>` | 딥링크 쿼리 파라미터 |
| `isJobkorea` | `boolean?`               | 잡코리아 환경 여부   |

### **지원하는 쿼리 파라미터**

| 파라미터       | 설명                         | 예시                  |
| -------------- | ---------------------------- | --------------------- |
| `popup_url`    | 팝업 페이지 URL              | `/user-account/login` |
| `gi_no`        | 구인정보 번호                | `12345`               |
| `search_word`  | 검색 키워드                  | `카페알바`            |
| `alarm_config` | 알림 설정                    | `1`                   |
| `marketTimer`  | 스토어 리디렉션 대기시간(ms) | `3000`                |

---

## 📱 지원 환경

### **모바일 환경**

- **iOS**: Safari 14+, 알바몬 앱, 잡코리아 앱
- **Android**: Chrome 90+, 알바몬 앱, 잡코리아 앱

### **데스크톱 환경**

- **Chrome**: 90+
- **Safari**: 14+
- **Firefox**: 88+
- **Edge**: 90+

### **개발 환경**

- **Node.js**: 16+
- **pnpm**: 8+
- **TypeScript**: 5.4+

---

## 🧪 테스트 및 디버깅

### **데모 환경**

- `/demo.json`을 통한 샘플 딥링크 제공
- 실시간 딥링크 테스트 가능
- 플랫폼별 동작 확인

### **성과 및 결과**

- **모바일 사용자 경험 개선**: 웹-앱 간 원활한 이동으로 사용자 이탈률 17% 감소
- **크로스 플랫폼 호환성**: Android/iOS 모든 환경에서 일관된 동작
- **개발 생산성 향상**: 재사용 가능한 컴포넌트로 개발 시간 단축

---


알바몬 딥링크 버전관리 및 공통 사용을 위해서 진행했던 프로젝트입니다.

성 연 철

#TailwindCSS