InsightAI — AI 데이터 분석·예측 반응형 SaaS MVP
미래에이아이랩(MIRAE AI LAB) 제작 레퍼런스
데이터를 넣으면, 무엇이 변했고 왜 변했고 지금 무엇을 해야 하는지 알려주는 분석 SaaS입니다.
대상은 분석가가 없는 중소기업의 대표·운영·마케팅 담당자입니다.
판단 기준은 "데이터를 보여주는가?"가 아니라 **"대표나 실무자가 다음 행동을 정할 수 있는가?"**입니다.
핵심 흐름 (Golden Path)
- 데이터 올리기 → 진단 — CSV·XLSX를 올리면 바로 분석하지 않고 먼저 보여줍니다.
열 인식(파일의 열 → 인식한 항목 / 사용하지 않는 열) → 분석할 수 있는 것 / 없는 것(그리고 무엇이 더 필요한지) →
기간(빠진 날 수, 처음 열 비교 범위) → 데이터 품질(제목 줄 건너뜀, 없는 날짜, 빈 매출, 완전히 같은 행, 빈 열, 짧은 기간) → 이대로 분석 시작.
- 대시보드 = 경영 브리핑 — 숫자 카드가 아니라 한 문장으로 시작합니다:
매출이 이전 30일보다 20.2% 늘었습니다.
그 아래 ① 가장 큰 변화(증감분을 가장 많이 만든 채널·상품) ② 가능성 높은 원인(그 변화를 방문자 × 전환율 × 객단가로 나눈 결과) ③ 지금 확인할 위험 ④ 추천 다음 행동(각각 근거 수치 포함)이 이어지고, 결론마다 근거 n개 보기로 계산값을 펼쳐 확인합니다.
지표는 카드 줄 대신 추이 차트 머리의 탭으로 들어가 있고, 그 아래 평소와 달랐던 날, 채널별 매출 변화(증감액 막대), 그 밖의 발견, 다음 7일 예측이 이어집니다.
추이 차트에는 평소와 달랐던 날이 점으로 찍혀(떨어진 날 빨강 · 오른 날 초록) 누르면 바로 그날의 조사 화면으로 갑니다.
처음 온 사람에게는 처음이라면 이 순서로 보세요(요약 → 차트의 점 → 보고서) 안내가 한 번만 보입니다.
추천 다음 행동은 할 일 목록입니다 — 왼쪽 동그라미를 눌러 완료로 표시하면(날짜와 함께 이 브라우저에 저장) 브리핑·인사이트 모두에 3개 중 1개 완료로 남습니다.
- 이상치 → 조사 흐름 —
평소와 달랐던 날의 한 행을 누르면 조사 화면(/anomalies?id=…)으로 갑니다.
이상 감지 목록 맨 위 기간 한눈에는 일별 매출 막대에 평소와 달랐던 날을 색으로 칠해(위험 · 주의 · 평소보다 많았던 날) 언제 몰려 있었는지 먼저 보여주고, 색칠된 막대를 누르면 그 조사로 갑니다. 행마다 변화 전후 7일의 작은 추이(변화 구간 강조)와 미확인 표시가 붙습니다.
① 무슨 변화인가(그날 값 vs 평소, 같은 날 함께 움직인 지표, 차트) → ② 언제 시작됐고 지금은?(시작 전 → 그날 → 회복일/진행 중) →
③ 어디서 생겼나(채널·상품별 몫) → ④ 확인할 수 있는 근거(지표별 그날·평소·같은 요일 평소) → ⑤ 지금 할 일(지표 조합으로 본 원인 유형과 확인 순서).
위쪽 고정 막대(2 / 5, 이전·다음, 키보드 ←/→, 휴대폰은 옆으로 밀기)와 맨 아래 확인했어요 · 다음 보기로 받은편지함처럼 차례로 넘기며 확인하고, 마지막 건에서 확인 완료 · 대시보드로 돌아갑니다.
- 드릴다운 — 브리핑·인사이트·질의 답변의 링크는 분석 화면으로 범위를 좁혀 이동하고, 돌아가면(링크·브라우저 뒤로) 원래 범위로 복원됩니다.
분석 화면의 분해 표는 항목마다
흐름(일별 추이) · 이번 기간 · 이전 기간 · 변화 · 비중을 한 줄에 두고, 열 머리를 눌러 정렬합니다(좁은 화면은 이름 · 이번 기간 · 변화만).
예측 화면은 숫자 하나로 끝내지 않습니다 — 이 예측을 얼마나 믿을 수 있나(지난 7일을 가리고 같은 방법으로 예측해 실제와 비교: 7일 합계 오차 · 범위 안에 든 날 수 · 믿을 만함/참고용/크게 빗나감)와 일별 예측 표(날짜 · 요일 · 예측 · 예상 범위, 계산 근거 한 줄)를 함께 보여줍니다.
- 보고서 = 업무 기록 — 그 시점의 결론을
1. 핵심 요약 · 2. 분석 범위 · 3. 주요 발견 · 4. 위험 요소 · 5. 권장 행동 · 6. 생성 시점 순서로 남깁니다. 저장 전 "이 결론이 기록됩니다" 미리보기, 제목 수정, 이 범위로 대시보드 열기, PDF, 삭제 되돌리기.
넓은 화면에서는 오른쪽 목차가 지금 읽는 절을 표시하고, 절마다 건수(발견 · 위험 · 행동)를 붙여 누르면 그 절로 이동합니다.
지난 보고서와 비교 — 같은 데이터·대상으로 앞선 기간을 다룬 보고서가 있으면 지표 변화(기간 길이가 다르면 합계 지표는 하루 평균)와 사라진 위험 / 새로 생긴 위험을 보여주고, 없으면 앞 기간 보고서 만들어 비교로 바로 앞 같은 길이 기간의 보고서를 한 번에 만듭니다.
보고서 목록은 제목·데이터·결론으로 찾고, 최근 저장 순(달별로 묶음) · 위험 많은 순 · 분석 기간 순으로 정렬합니다.
- 데이터 질의 — 일반 대화가 아니라 "지금 열린 데이터"에 묻는 도구입니다. 데이터에 맞춘 질문(
웹사이트 매출은 왜 늘었어?, 10월 3일 웹사이트에 무슨 일이 있었어?)을 추천하고, 답마다 **근거(화면과 같은 계산)**와 이어서 볼 화면을 붙입니다.
가장 최근 답 아래에는 아직 묻지 않은 이어서 물어보기가 붙고, 답은 복사로 질문·답·근거를 한 덩어리로 옮깁니다. 물어본 추천 질문은 체크로 표시되고, /로 질문 칸에 바로 가며, 기록 지우기는 되돌릴 수 있습니다.
예외 상태: 브랜드 404 페이지, 화면 오류 시 다시 시도/데모 데이터 비우고 시작 화면, 손상된 저장 데이터는 읽을 때 걸러냅니다.
저장되는 상태 (localStorage, 키 접두어 insightai.)
| 키 | 내용 |
|---|
activeDataset | 지금 분석 중인 데이터셋 id |
history | 분석 기록 — 분석 시점의 실제 핵심 발견·매출 변화율·주의 이상치 수 |
uploads | 업로드 원본(최근 3개, 용량 초과 시 오래된 것부터 정리 → 복원 불가 기록은 원본 없음으로 표시) |
reports | 저장한 보고서 스냅샷 |
readNotifications | 확인 처리한 이상치 id (사이드바·하단 탭 미확인 배지) |
settings | 기본 분석 기간(7/30/90일) |
guideSeen | 대시보드 '처음이라면' 안내를 닫았는지 |
actionsDone | 완료로 표시한 할 일(데이터셋·제목 → 표시한 시각, 최근 200개) |
설정 → 데모 초기화는 위 키를 모두 지우고 샘플 데이터로 다시 시작합니다.
라우팅
| 경로 | 화면 |
|---|
/ | /dashboard로 리다이렉트 |
/dashboard | 대시보드 — 어느 주소로 처음 들어와도 샘플 데이터가 연결됨 |
/anomalies | 이상 감지 — 등급 탭, 미확인 표시, 모두 확인 처리 / ?id= 조사 화면(&from=으로 돌아갈 화면 기억, 열면 확인 처리) |
/insights | 인사이트 + 실행 제안 |
/analytics | 분석 — 지표 추이 + 채널·상품·고객 유형 분해(?metric= 딥링크) |
/forecast | 예측 — 다음 7일 매출·주문·고객(파일에 있는 지표만) · 지난 7일 검증 · 일별 예측 표 |
/reports | 보고서 목록 / ?id= 상세 |
/data · /ai · /settings | 작업 공간 — 업로드 진단·이 데이터로 하는 분석·기록, 데이터 질의, 설정 |
/more | 모바일 더보기 |
/intro | 서비스 소개 |
/notifications · /explore | 통합된 이전 메뉴 → /anomalies · /analytics로 리다이렉트 |
내비게이션
- 데스크톱 사이드바: 핵심 6개(대시보드·이상 감지·인사이트·분석·예측·보고서) + 작업 공간 3개(데이터·데이터 질의·설정). 아이콘은 단색, 활성 항목만 브랜드 블루. 배지는 미확인 이상치 수 하나만.
- 상단 바: 데이터 전환 메뉴(샘플 3종 · 올린 파일 · 파일 올리기) ·
데모 표기 · 오늘 날짜·요일·시각(분 단위). 페이지 제목과 대표 행동은 본문 PageHeader에 한 번만.
- 범위(기간·채널·상품)는 데이터를 보는 화면의 본문 상단에만 둡니다. 데스크톱은 한 줄 컨트롤, 모바일은
최근 30일 · 전체 채널 한 줄 요약을 누르면 바텀시트에서 한 번에 고르고 적용합니다. 값이 하나뿐인 차원(예: 채널 컬럼이 없는 파일)은 숨깁니다.
초기화(모바일은 요약 옆 파란 점)는 이 데이터의 기본 범위(데이터 길이에 맞춰 고른 기간 · 전체 채널 · 전체 상품)에서 벗어났을 때만 나타납니다. 범위를 바꾸면 대시보드 결과가 짧게 전환되어 새로 계산되었음을 알립니다.
- 키보드: 첫
Tab은 본문으로 건너뛰기, 화면을 옮기면 초점이 새 본문 시작으로 갑니다. 복원 중에는 실제 화면 모양의 뼈대를 보여 줍니다.
- 빠른 이동(
Ctrl/⌘ + K, 상단 바의 빠른 이동 · 모바일은 돋보기): 화면 · 지금 범위의 평소와 달랐던 날 · 저장한 보고서 · 데이터 바꾸기 · 자주 하는 일(보고서 저장, 파일 올리기)을 한 칸에서 찾아 ↑↓ Enter로 이동합니다. 새 메뉴가 아니라 기존 화면·기능으로 가는 지름길입니다.
- 페이지 설명줄은 비교 기준을 한 줄로 보여줍니다:
최근 30일 · 이전 30일과 비교. 대시보드는 대신 데이터 이름과 마지막 데이터 날짜(신선도)를 보여주고, 비교 기준은 브리핑 첫 줄에 둡니다.
- 모바일 하단 탭 5개: 홈 · 이상 감지 · 인사이트 · 보고서 · 더보기.
디자인 방향
InsightAI는 대표·실무자가 매일 여는 B2B 분석 도구라서 화면 대부분은 기능·행동 중심으로, 첫인상을 만드는 소개 화면만 하이브리드(제품 미리보기 중심)로 설계했습니다.
상용 B2B SaaS·회계/BI 도구의 신뢰감을 기준으로, 기존 브랜드(그래파이트 사이드바 · 브랜드 블루 · 따뜻한 회백색 바탕)는 그대로 두고 표현의 정밀도를 높였습니다.
| 화면 | 방향 | 핵심 |
|---|
소개 /intro | 하이브리드 | 한 문장 약속 + 실제 샘플 데이터로 계산한 대시보드 축소판(그림이 아니라 엔진 결과) · 단계별 미리보기(진단 · 채널별 변화 · 조사 타임라인) · 원칙 띠 · 업종별 샘플 카드 |
| 대시보드 | 기능 | 브랜드 톤 머리의 경영 브리핑(한 문장 · 매출 · 흐름선) → 지표 탭 + 추이 → 평소와 달랐던 날 |
| 데이터 | 기능 | 지금 데이터 요약(기간 · 행 수 · 채널 · 상품 · 가능한 분석) → 업로드(오른쪽에 '열에 따라 볼 수 있는 분석' 안내) → 샘플 카드(90일 흐름선 + 이번 기간 결론) |
| 보고서 | 문서 | 가운데 정렬된 종이 문서 — 제목 · 범위 · 저장 시각 · 비교 기준 · 데이터 · 분석 방식 머리, 번호가 붙은 6개 절 |
| 모바일 | 앱 | 하단 탭(활성 탭 알약 표시) · 질의 추천은 한 줄 목록 · 업로드 진단 중에는 하단에 '분석 시작' 고정 |
- 글꼴: Pretendard(OFL)를 자체 호스팅합니다(
public/fonts/pretendard, 쓰인 글자 범위만 나눠 받는 dynamic subset). 시스템 글꼴에 기대지 않아 어느 PC에서나 같은 품질로 보입니다. 제목은 크기에 비례해 자간을 좁힙니다.
- 사용자 표시(사이드바 하단 · 더보기)는 기존 사용자 정보(
BRAND.user)를 보여줄 뿐 새 기능이 아닙니다.
디자인 시스템
모든 값은 app/globals.css의 @theme 토큰입니다.
| 구분 | 토큰 |
|---|
| 색상 | 브랜드 블루 brand #0a62db(글자·버튼) / 로고 블루 #1478ff(차트 선) · 보조 틸 accent #0f9fb3(예측·비교 시리즈 전용) · 뉴트럴(canvas/surface/line/ink/nav) · 상태 positive / warning / negative — 모든 글자 색은 WCAG AA(4.5:1) 이상, E2E에서 axe로 검사 |
| 타입 스케일(360px 기준) | caption 13 · meta 14 · sub 15 · body 16 · lead 17 · card 18 · title 22 · page 26 · kpi 28 · display 40 — 768px 이상에서 title 24 · page 30 · kpi 30 · display 52 · 본문 자간 −0.011em, 제목 −0.022em |
| 모서리 | rounded-control 10 · rounded-card 14 · rounded-panel 20 |
| 그림자 | shadow-subtle · shadow-raised · shadow-overlay · shadow-button(주요 버튼의 얕은 브랜드 그림자) |
| 간격 | 4/8px 리듬(gap 2·3·4·6·8) |
| 한국어 | word-break: keep-all; overflow-wrap: break-word 전역 적용 |
원칙
- 메뉴·지표마다 다른 색을 칠하지 않습니다. 색은 **브랜드(선택·행동)**와 **상태(좋음·주의·위험)**에만 씁니다. 상태는 항상 텍스트 라벨(위험·주의·참고)과 함께 표시합니다.
- 패널 안에 패널을 넣지 않습니다(카드 깊이 1). 목록은 구분선으로 나눕니다.
- 버튼 위계는
lib/ui.ts의 btn.primary / secondary / quiet / danger 네 가지. primary는 화면당 하나.
- 차트 색은
lib/palette.ts — 단일 지표는 브랜드 블루, 이전 기간은 옅은 블루 점선, 예측은 틸, 범주형은 블루 명도 단계 + 뉴트럴.
- 장식용 글로우·카운트업·"AI" 반짝이 아이콘을 쓰지 않습니다. 그라데이션은 브리핑·보고서 머리의 아주 옅은 브랜드 톤 한 가지만 씁니다.
- 작은 흐름선(
components/charts/Sparkline.tsx)은 숫자 옆에서 '흐름'만 요약하며, 의미는 옆의 숫자·문장이 전달합니다(스크린리더에서는 숨김).
정직한 데모 표기 · 계산 규칙
- 상단 바
데모 배지, 분석 오버레이·인사이트·설정에 규칙 기반 분석 엔진임을 표시합니다.
- 이상치 감지 기준을 화면에 공개합니다: 평소 수준(직전 7일 중앙값)과 최근 4주 같은 요일 수준 모두에서 20% 이상(전환율·객단가 15%) 벗어난 날.
- 원인은 항상 추정으로 표기합니다(
가능성 높은 원인(추정), 데이터 패턴으로 본 추정). 계산 방식(매출 = 방문자 × 전환율 × 객단가로 나눈 계산)을 근거 옆에 적습니다.
- 예측은 "최근 추세 기반 추정치"로 표기합니다. 실행 제안에는 지어낸 효과 수치(예: 매출 +4~7%)를 쓰지 않고, 제안을 만든 계산값을
근거로 답니다.
- 고객 유형별 금액은 "고객 수 비율로 나눈 추정치"로 표기하고, 원본에 없는 고객 유형별 전환율은 계산하지 않습니다.
- 업로드 파일은 서버로 전송되지 않고 브라우저에서만 처리됩니다.
- 이전 기간 비교는 같은 길이의 직전 구간이 있을 때만 합니다. 비교할 수 없으면 증감 대신
비교 없음, 브리핑은 기간 안의 흐름(전반 vs 후반)으로 대신합니다. 업로드 파일은 데이터 길이에 맞는 기본 기간(예: 40일치 → 최근 7일 vs 이전 7일)으로 엽니다.
- 파일에 없는 컬럼(주문 수·방문자·고객 수·광고비·채널·상품)은 내부 계산용으로만 추정하고, 그 추정치로 만든 지표·인사이트·예측·표 열·질의 답변은 내지 않습니다. 업로드 진단에서 무엇이 빠지는지 미리 알려줍니다.
- 최소 데이터: 급변 감지 8일, 같은 요일 기준 15일, 예측 14일, 상품 흐름(최근 7일 vs 그 전 3주) 28일 이상. 부족하면 이유를 표시합니다.
- 이상치 정리: 주말처럼 반복되는 요일 패턴과 프로모션이 끝나 평소로 돌아온 날은 알리지 않습니다. 며칠 이어진 변화는 시작일·지속 일수를 가진 한 건으로, 여러 채널이 함께 움직이면
전체 한 건으로 묶습니다. 방문자가 급감해 전환율이 높게 계산된 날은 '전환율 급증'으로 따로 알리지 않습니다. 상승은 참고 등급입니다.
샘플 브릿지 CTA
components/SampleBridgeCTA.tsx 하나로 관리합니다. 핵심 작업 중에는 외부 CTA를 띄우지 않고,
흐름을 다 본 지점에서만 노출합니다: 대시보드 하단, 저장된 보고서 상세 하단, 모바일 더보기, 서비스 소개.
노출 조건은 components/AppFooter.tsx에 있습니다.
| 수정 대상 | 위치 |
|---|
| 링크 주소 (상담·다른 샘플·홈페이지) | lib/brand.ts → BRAND.links |
| CTA 문구 (배지·헤드라인·설명·버튼) | components/SampleBridgeCTA.tsx → CTA_COPY |
| 페이지별 링크 덮어쓰기 | <SampleBridgeCTA consultHref samplesHref homeHref /> props |
브랜딩
- 제작 표기는 화면당 한 번: 데스크톱은 사이드바 하단
미래에이아이랩 제작 샘플, 모바일은 하단 한 줄 크레딧.
- 사용자 표시: 미래에이아이랩 김팀장님(설정·보고서 작성자).
- 로고 자산:
public/brand/(가로형·밝은 버전·심볼), 상수 lib/brand.ts, 컴포넌트 components/MiraeLogo.tsx. 파비콘은 심볼.
실행 · 검사
npm install
cp .env.example .env.local # 선택: 데이터 질의에 LLM을 쓰려면 ANTHROPIC_API_KEY 입력
npm run dev # http://localhost:3000
npm run check # typecheck + lint + 단위 테스트 (커밋 전 기본)
npm run build # 프로덕션 빌드 (Vercel 배포 가능)
npm run test:e2e # 프로덕션 빌드를 띄워 데스크톱·모바일 E2E + 접근성 검사 (build 후 실행)
로컬에 Playwright 브라우저 대신 시스템 Chromium을 쓰려면 PLAYWRIGHT_CHROMIUM_PATH=/path/to/chrome npm run test:e2e.
데모 데이터 스토리 (이커머스)
데모 데이터는 접속한 날을 마지막 날로 하는 최근 90일로 생성됩니다. 이벤트도 마지막 날 기준 상대 위치로 정의되어,
언제 열어도 "최근에 벌어진 일"로 읽힙니다.
- 21~15일 전: 프로모션 —
전체 매출·주문 수 급증(참고) 한 건으로 묶여 감지
- 11일 전: 웹사이트 방문자 급감 —
위험, 조사 화면에서 "방문자(−71%)가 주문(−44%)보다 훨씬 크게 줄었다 → 광고 중단·접속 장애·집계 누락 확인"
- 11~8일 전: 모바일 앱 결제 이탈 —
모바일 앱 전환율 급감(주의, 4일간), "결제·장바구니 단계 확인"
- 6일 전~오늘: 웹사이트 전환율·객단가 개선(참고)
- 최근 4주: 스마트스토어 광고비만 증액 — 브리핑의
지금 확인할 위험: "광고비는 60% 늘었지만 주문은 13% 증가에 그쳤습니다"
- 최근 2주: '비타민 세럼' 판매 가속 — "최근 7일 판매가 평소보다 25% 많습니다 → 재고와 노출 확보"
마케팅·매장 데이터에도 같은 방식의 스토리(디스플레이 유입 급감, SNS 광고비 증액, 홍대점 방문객 급감, 주말 패턴)가 들어 있습니다.
개발자 가이드
구조와 데이터 흐름
demo-data / csv(업로드 + 진단) ← 원본 행(DataRow) — 브라우저 밖으로 나가지 않음
│
▼
analytics-engine 기간 해석 · 집계 · 이전 기간 비교 가능 여부
drivers 요인 분해(방문자×전환율×객단가) · 기여도 · 상품 흐름 · 광고 효율 · 기간 안 흐름
anomaly-engine 평소 수준(7일 중앙값·같은 요일) 대비 탐지 → 묶기(일수·전체/채널) · 비율 착시 제거
investigate 이상치 하나의 조사: 무엇 → 언제 → 어디서 → 근거 → 원인 유형·할 일
insight-generator 계산된 발견(근거·계산 방식 포함) · 발견에서 나온 실행 제안
forecast-engine 추세 → 7일 추정
│
▼
briefing.summarize 헤드라인 → 가장 큰 변화 → 가능성 높은 원인 → 지금 확인할 위험 → 다음 행동
── 대시보드 · 보고서 스냅샷 · 분석 기록 · 데이터 질의 · LLM 요약이 같은 함수를 쓴다
qa 질문 의도 → 같은 계산으로 답 + 근거 + 이어 볼 화면 · 데이터별 추천 질문
dataset-meta / capabilities 추정 필드에 기대는 지표 걸러내기 · 이 데이터로 할 수 있는 분석
│
▼
store (React Context) ←→ persist (localStorage: 검증된 읽기 · 용량 초과 대응)
│
▼
화면 (app/(app)/*) ai/client → /api/ai (선택) → Claude API
- 엔진은 순수 함수입니다. React·브라우저에 의존하지 않아 단위 테스트로 규칙을 고정합니다.
- 화면의 모든 숫자는 한 계산 경로에서 나옵니다. 대시보드 브리핑, 저장 보고서, 분석 기록, 데이터 질의, LLM에 보내는 요약이
summarize를 공유해 서로 어긋나지 않습니다.
- 상태 경계: 범위(기간·채널·상품)는 전역 상태이고, 드릴다운은 출발 화면과 이전 범위를
drill로 기억해 돌아갈 때(링크·브라우저 뒤로) 복원합니다(components/DrillWatcher.tsx).
데이터 질의 (LLM, 선택)
- 브라우저는
/api/ai만 호출하고 키는 서버(ANTHROPIC_API_KEY)에만 둡니다. 모델은 AI_MODEL(기본 claude-opus-5-5).
- 원본 행이 아니라 화면과 같은 계산으로 만든 요약(
lib/ai/context.ts, 12KB 이하 — 브리핑 결론 포함)만 보내고, 시스템 프롬프트로 "요약 안의 숫자만 근거로, 화면의 결론과 같은 방향으로, 일반론 없이, 없는 값은 모른다고" 답하게 합니다. 질문은 <question> 태그로 분리해 지시 주입을 막습니다.
- 요청·응답 형식은
lib/ai/contract.ts 한곳에서 정의하고 서버·클라이언트가 같은 검증을 씁니다(질문 300자, 요약 크기 제한).
- 키 없음·거절(
refusal)·호출 실패·20초 초과 시 규칙 기반 엔진으로 넘어갑니다. LLM이 답해도 근거와 이어 볼 화면은 항상 규칙 기반 계산에서 만들고, 답마다 출처(AI가 쓴 문장 / 규칙 기반 계산)를 표시합니다.
- 인스턴스 단위 호출 제한(IP당 분당 20회). 여러 인스턴스에서 공유하려면 외부 저장소로 옮깁니다.
테스트
| 종류 | 위치 | 다루는 것 |
|---|
| 단위 (Vitest, 155개) | tests/unit | 요인 분해(몫의 합 100%)·기여도·상품 흐름(프로모션 주 무시)·광고 효율, 이상치(요일 패턴·프로모션 종료 무시, 기간 묶기, 진행 중, 전체/채널 묶기, 비율 착시), 조사(원인 유형·회복일·상품 몫·할 일), 브리핑(변화·원인·위험 우선순위), 보고서 스냅샷, 인사이트에 일반론·지어낸 효과 없음, 데이터 질의(브리핑과 같은 결론·추천 질문은 모두 답 가능), CSV 진단(제목 줄·없는 날짜·빈 매출·중복·빈 열·빠진 날), 기본 범위 판단(초기화 표시), 분해 표(이전 기간·변화·비중·일별 흐름, 비교 불가 시 비움), 이상치 추이 구간, 예측 검증(일정한 흐름은 오차 ≈0 · 급증은 '크게 빗나감' · 21일 미만은 검증 안 함), 보고서 비교(앞선 보고서 고르기 · 하루 평균 맞춤 · 위험 사라짐/새로 생김 · 앞 기간 계산), 조사(이/가·으로/로), 저장소·AI 라우트 |
| E2E (Playwright) | tests/e2e | 데스크톱·모바일 각각: 브리핑으로 시작, 이상치 → 조사 흐름, 드릴 후 범위 복원, 90일 비교 불가, 보고서(업무 기록 6단) 저장·새로고침·이름 변경·삭제 되돌리기, 업로드 진단(정상·문제 섞인 파일·열이 적은 파일·오류 4종), 업로드 → 분석 → 이상치 조사 → 보고서 저장 한 번에, 차트 점 → 조사, 조사 이전·다음 넘기기(키보드 포함), 보고서 목차 이동, 처음 안내 닫기 유지, 짧은 파일의 초기화 표시, 건너뛰기 링크·화면 이동 초점, 기간 한눈에 → 조사, 분해 표 정렬·좁히기, 예측 검증·일별 표, 할 일 완료 유지·취소, 이어서 물어보기·기록 되돌리기, 앞 기간 보고서 비교·목록 찾기, 빠른 이동(열기·찾기·Enter·Esc 초점 복귀), 조사 화면 옆으로 밀기(모바일), 404·리다이렉트·손상된 저장 데이터 |
| 품질 (axe + 레이아웃) | tests/e2e/quality.spec.ts | 11개 화면 + 조사 화면 + 보고서 문서 + 빠른 이동(열린 상태) × 2개 뷰포트에서 WCAG 2.1 AA 심각·치명 위반 0건, 가로 넘침 0 |
테스트 데이터는 tests/unit/fixtures.ts의 결정적 생성기로 만들어, 각 테스트가 의도한 변화(특정 날·채널 급감 등)만 담습니다.
CI
.github/workflows/ci.yml — 푸시·PR마다 typecheck → lint → 단위 테스트 → 빌드, 이어서 E2E(데스크톱·모바일·접근성). 실패 시 Playwright trace를 아티팩트로 남깁니다.
설계상 선택
- 규칙 기반이 기본: 같은 데이터면 언제나 같은 결과가 나오고 설명 가능해야 하므로, 판단(탐지·요인·제안)은 규칙으로 하고 LLM은 "질문에 자연어로 답하기"에만 씁니다.
- 결론마다 근거: 브리핑·인사이트·제안·질의 답변은 모두 "결론 → 계산값(근거) → 계산 방식"을 갖습니다. 근거를 댈 수 없는 문장(예: "마케팅을 강화하세요")은 만들지 않고, 단위 테스트로 막습니다.
- 평소 수준은 중앙값과 같은 요일로: 평균·전일 대비는 프로모션·주말에 흔들려 거짓 경보가 많습니다. 두 기준 모두에서 벗어나야 알립니다.
- 원인 분해는 로그 분해: 매출 변화(ln R₁/R₀)를 방문자·전환율·객단가의 로그 변화로 나누면 몫의 합이 정확히 100%가 됩니다.
- 추정치는 숨긴다: 업로드 파일에 없는 컬럼은 계산 편의상 추정으로 채우지만, 그 값에 기대는 지표·인사이트·표 열·질의 답변은 내보내지 않습니다.
- 비교는 같은 길이일 때만: 이전 구간이 모자라면 증감 대신 "비교 없음" — 가짜 +100%를 만들지 않습니다.
- 보안 헤더:
nosniff, Referrer-Policy, Permissions-Policy, 틀(iframe) 허용은 자기 자신과 miraeailab.com으로 제한.
데이터 구조 (Supabase)
supabase/schema.sql에 users / datasets / dataset_rows / analyses / insights / anomalies / forecasts / reports / ai_queries
스키마가 정의되어 있습니다. 데모 모드에서는 브라우저 localStorage로 동작합니다.
디렉터리
app/(app)/ dashboard, anomalies, insights, analytics, forecast, reports, data, ai, settings, more
app/intro/ 서비스 소개
components/ BriefingPanel, MetricTabs, ContributionBars, AnomalyList, InvestigationView, InsightList, UploadPanel, SampleCard,
landing/ (소개 화면의 제품 미리보기),
PageHeader, Panel, FilterToolbar, ScopeSheet, DatasetSwitcher, Select, Sidebar, TopBar, MobileNav,
DateLine, DateRangePicker, DataTable, AnalysisOverlay, ToastStack, EmptyState, PageSkeleton,
AppFooter, SampleBridgeCTA, MiraeLogo, Logo, charts/ (RevenueTrend, Investigation, Forecast)
lib/ analytics-engine, drivers, anomaly-engine, investigate, insight-generator, forecast-engine, ← 순수 계산
briefing, report, qa, capabilities, dataset-meta,
csv, demo-data, format, persist, store, drill, nav, ui, use-popover, palette, brand, notifications,
ai/ (contract · context · client)
app/api/ai/ LLM 프록시 라우트
tests/ unit/ (Vitest) · e2e/ (Playwright + axe)
public/ brand/ 로고 · sample/insightai-sample.csv 업로드 예시 · fonts/pretendard (OFL, LICENSE.txt 포함)
supabase/ schema.sql
