안아수달 — 프론트엔드
아이 발달이 걱정될 때, 검증된 공공 자료로 확인해볼 영역을 찾아주고 가까운 발달재활 기관을 추천하는 서비스.
이 저장소는 화면(웹)이고, API 는 anasudal_BE 에 있습니다.
Next.js 16 (App Router) · TypeScript · Tailwind CSS v4 · Pretendard
시작하기
cp .env.example .env.local # 아래 "환경 변수" 참고
npm install
npm run dev # http://localhost:3000
| 명령 | 설명 |
|---|
npm run dev | 개발 서버 |
npm run build | 프로덕션 빌드 (타입 검사 포함) |
npm run lint | ESLint |
npx tsc --noEmit | 타입 검사만 |
환경 변수
| 이름 | 필수 | 설명 |
|---|
NEXT_PUBLIC_API_BASE | O | 백엔드 주소. 뒤의 /v1 은 클라이언트가 붙인다. 예: http://localhost:8000 |
NEXT_PUBLIC_KAKAO_MAP_KEY | X | 카카오 지도 JavaScript 키 (REST 키와 다름). 없으면 기관 상세의 지도 자리에 카카오맵 링크만 나온다. developers.kakao.com 에서 발급하고 플랫폼 > Web 에 접속 도메인(http://localhost:3000, 배포 도메인)을 등록해야 지도가 그려진다 |
화면
| 경로 | 화면 | 내용 |
|---|
/ | 채팅 메인 | 수달 인사 · 입력창 · 추천 질문 칩 3개(서버가 호출마다 회전) |
/chat?s=<세션> | 대화 | 질문 → SSE 스트리밍 답변 → 👍👎 → 기관 추천 3곳 + 둘러보기 배너 |
/browse | 둘러보기 | 지역 설정 · 기관명/치료영역 검색 · 무한 스크롤(가상화) |
/institutions/[사업자번호] | 기관 상세 | 지도 · 주소 · 전화 · 운영시간 · 영역별 공시 단가 · 홈페이지 |
/design | 디자인 시스템 문서 | 팔레트 · 의미 토큰 · 타이포 · 컴포넌트 전체. 피그마 시트 대조용 |
로그인이 없습니다. 세션 id 만 localStorage 에 두고, 대화 내용은 탭을 닫으면 사라지는 sessionStorage 에만
잠시 보관합니다(기관 상세를 보고 돌아왔을 때 대화가 비지 않게). 서버에는 대화 원문을 저장하지 않습니다.
디자인 시스템
값은 src/app/globals.css 의 @theme 한 곳에만 있습니다. 컴포넌트는 토큰 유틸리티만 쓰고 임의값(text-[20px])은 쓰지 않습니다.
브레이크포인트 — 768px 하나뿐
미만은 모바일, 이상은 PC(태블릿 포함). Tailwind 기본 sm/lg/xl/2xl 은 @theme 에서 지워서 쓰려고 해도 생성되지 않습니다.
반응형은 전부 md: 입니다. 타이포도 이 경계에서 모바일 값 ↔ 데스크톱 값으로 바뀝니다.
색
팔레트 900→50 은 bg-green-600 처럼, 의미 토큰은 이름 그대로 씁니다.
| 토큰 | 값 | 클래스 예 |
|---|
| primary | #295E56 | bg-primary text-primary |
| text/strong · body · muted · placeholder | #1B2A27 #40534F #5A6B67 #9AA8A5 | text-strong text-body text-muted text-placeholder |
| line/default · subtle | #D8DDD6 #EFEFE9 | border-line border-line-subtle |
| action/press · soft · disabled | #204A44 #DEEBE7 #E9E8E0 | active:bg-press bg-soft bg-disabled |
| surface/card · base · sunken | #FFFFFF #F3F2EC #E9E8E0 | bg-card bg-base bg-sunken |
success · warning · danger (+ -bg) | #24634A #B26200 #9E382E | text-danger bg-danger-bg |
타이포 9종
<Text variant="title-m"> 이 태그와 색까지 맞춰주고, 클래스로는 t-title-m 처럼 씁니다. 폰트는 전부 Pretendard Variable 자체 호스팅(next/font/local).
| 변형 | 굵기 · 자간 | 모바일 | PC | 쓰는 곳 |
|---|
| display | 700 · -2.5% | 34/44 | 52/66 | 온보딩 완료 대제목 |
| title-l | 700 · -2% | 26/36 | 36/48 | 화면 제목 |
| title-m | 600 · -2% | 21/30 | 26/38 | 섹션 헤딩, 채팅 메인 인사 |
| title-s | 600 · -1.5% | 18/26 | 20/30 | 카드 제목, 세그먼트 라벨 |
| body-l | 400 | 17/29 | 18/32 | 설명 문단, AI 답변 본문 |
| body-m | 400 | 16/26 | 16/28 | 기본 본문 (최소 본문 크기) |
| caption | 500 | 14/22 | 14/24 | 주석, 보조정보 |
| label | 700 · +1% | 12/18 | 12/18 | 스테퍼, 오버라인 |
| numeric-xl | 700 | 40/44 | 56/60 | 통계 숫자 |
컴포넌트
src/components/ui — Text Button(primary/soft/outline/ghost/danger × sm/md/lg) Chip·Tag Card(card/soft/sunken)·Divider
Input·Textarea·Field Badge·Notice Segmented(세그먼트 버튼 메뉴) ChatInput(채팅 입력창).
/design 에서 전부 상태별로 볼 수 있습니다. 창 폭을 768px 경계로 옮기면 타이포가 바뀌는 것도 확인됩니다.
구조
src/
app/ 화면 (App Router) — page.tsx 는 조립만, 내용은 components 로
components/
ui/ 디자인 시스템 컴포넌트 (화면 로직 없음)
layout/ 상단 바·푸터
chat/ 채팅 메인·대화·답변·추천
browse/ 둘러보기 (지역 필터·검색·가상 목록)
institution/ 기관 카드·상세 조각·카카오 지도
lib/
api/ 백엔드 클라이언트 (client·types·stream)
session.ts 세션 id 보관, 대화 임시 보관
format.ts 표시용 포맷 (시·도 약칭, 가격, 치료영역 표기)
cn.ts 클래스 합치기
design/tokens.ts CSS 와 같은 토큰 값 (JS 에서 필요할 때만)
API 클라이언트
백엔드는 모든 응답을 봉투로 감쌉니다. 클라이언트가 이를 벗기고 실패는 ApiError 로 던집니다.
성공 { "success": true, "data": ... }
실패 { "success": false, "error": { "code": "SESSION_NOT_FOUND", "message": "...", "details": ... } }
import { api, askStream, humanize } from "@/lib/api";
const s = await api.session.create();
// 답변은 SSE 스트리밍 — delta 로 글자가 차오르고, done 의 text(볼드 포함)로 교체한다
await askStream(s.session_id, "30개월인데 두 단어 문장을 못 만들어요", {
onMeta: (m) => setStatus(`근거 ${m.evidence_count}건`),
onDelta: (t) => setText((prev) => prev + t),
onDone: (res) => setAnswer(res),
onError: (e) => setError(humanize(e)),
}, abort.signal);
intent 로 다음 화면이 갈립니다. answer 답변 · pick_region 지역 먼저 물어보기 · recommend 바로 추천 ·
need_context 아이 설명 요청 · diagnosis 진단 요구 거절 · out_of_scope 범위 밖.
타입은 src/lib/api/types.ts 에 백엔드 스키마와 1:1 로 있습니다.
코드 규칙
any 금지. tsconfig 는 strict + noUncheckedIndexedAccess, ESLint 는 @typescript-eslint/no-explicit-any: error.
타입이 없는 외부 SDK(카카오 지도)는 쓰는 부분만 좁혀서 선언합니다 — components/institution/KakaoMap.tsx 참고.- 임의값 금지. 색·타이포·간격은 토큰 클래스로. 피그마 치수는 스케일로 환산합니다(예: 106px =
min-w-26.5).
- 반응형은
md: 만. 다른 접두사는 생성되지 않습니다.
- 둘러보기 목록은 창 스크롤 가상화(
@tanstack/react-virtual)라 2,866곳이어도 DOM 에는 10~20장만 있습니다.
배포 (Vercel)
프로젝트 루트를 이 저장소로 두고 환경 변수 NEXT_PUBLIC_API_BASE, NEXT_PUBLIC_KAKAO_MAP_KEY 를 설정합니다.
백엔드가 HTTP 주소면 브라우저가 mixed content 로 막으므로 API 게이트웨이에 HTTPS 를 먼저 붙여야 합니다.
백엔드의 CORS_ORIGINS 에 Vercel 도메인을 추가하세요.
