9.2 KiB
Generated Next.js Repository Rules
- This frontend application was generated by
@kri/create-next-app. - Keep the generated Next.js routing, server/client boundary, authentication, environment, state, query, and application-shell conventions unless an approved task changes them.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not create new TypeScript type or interface names ending in
DtoorDTO. - Consume shared frontend behavior from
@kri/commonand the KRI UI Registry instead of copying provider implementations into this repository. AGENTS.mdandCLAUDE.mdare central-harness generated outputs. Never edit them directly; update.agent/profile.ymlor.agent/project.mdand recompose.- Run
npm run typecheckandnpm run buildafter relevant source or configuration changes.
Survey Dashboard Data Schema (source: public/tmp-doc/테이블 스키마.xlsx)
Use these backend table/column names as the source of truth for frontend type, variable, and component naming (e.g. TanStack Query keys, DTO-free response types, prop names) so terminology stays consistent between frontend and backend.
t_wave(분기/회차):wave_cd(PK, 예:2601= 2026년 1분기),year,wave,label(예: "1분기 재생에너지"),is_open.wave_cd인코딩: 연도 뒤 2자리 + 분기 2자리(zero-padded), 예: 2026년 1분기 →2601.
t_wave_info(조사 개요 항목, "조사 목적" 등):wave_info_idx(PK),wave_cd(FK),wave_info_order,wave_info_title,wave_info_content.t_survey(조사 대상군: 일반국민/전문가):wave_cd+survey_cd(PK),survey_order,survey_title(예: "일반국민 전화조사"),survey_alias(예: "일반국민").t_survey_item(조사 개요 세부 항목: 조사대상/조사지역/조사방법/조사기간/표본규모/표본오차):survey_item_idx(PK),wave_cd+survey_cd(FK),survey_item_order,survey_item_title,survey_item_content.t_file(결과보고서/인포그래픽 다운로드):file_idx(PK),wave_cd(FK),file_order,file_title,file_type(예: "PDF"),file_name.t_part(Ⅰ~Ⅳ 대분류):wave_cd+part_cd(PK),part_order,part_title(예: "Ⅰ. 에너지 및 재생에너지 정책").t_part_item(문항, 예: "1 재생에너지 중심의 에너지 전환 정책 평가"):wave_cd+part_cd+part_item_cd(PK),part_item_order,part_item_title,chart_type(예: "bar"),part_item_comment(각주 텍스트).t_part_item_sub(문항 아래 서브 그룹, 예: 3-1의 "확대 이유"/"감소 이유"):wave_cd+part_cd+part_item_cd+part_item_sub_cd(PK),part_item_sub_title.t_part_item_base(응답 모집단 N/보조 문구):part_item_base_idx(PK),wave_cd+part_cd+part_item_cd+survey_cd+part_item_sub_cd(nullable, FK),base_count(예: 1640),base_pre_text/base_post_text(nullable).t_part_item_data(차트 데이터 값): PK 컬럼명이t_part_item_data_idx로 다른 테이블과 달리 테이블명 접두사가 붙어 있음(스키마 내 유일한 예외 — 연동 코드 작성 시 오탈자로 오인하지 말 것).wave_cd+part_cd+part_item_cd+survey_cd+part_item_sub_cd(nullable, FK),part_item_data_order,part_item_data_label(예: "매우 잘하고 있다"),part_item_data_value(decimal(14,10), 예:39.9— 퍼센트 값으로 추정).- 계층 구조:
t_wave→ (t_wave_info|t_survey→t_survey_item|t_file|t_part→t_part_item→ (t_part_item_sub,t_part_item_base,t_part_item_data)). - 복합키 패턴: 대부분 상위 테이블의 코드 컬럼(
wave_cd,part_cd,part_item_cd,survey_cd,part_item_sub_cd)을 그대로 이어받는 자연복합키. 별도 대리키(_idx)는t_wave_info,t_survey_item,t_file,t_part_item_base,t_part_item_data에만 존재.
Backend API Integration (epolicy-dash-back, http://localhost:6107, OpenAPI at /v3/api-docs)
백엔드 연동이 완료되어 위 "프론트엔드 명명과의 정합성" 문제는 해소됨 — 영문 slug 라우팅(survey.data.ts/menu.data.ts)을 전부 제거하고 실제 waveCd/partCd 기반 동적 라우트와 API 응답 데이터로 완전히 교체했다.
- 라우트:
/dashboard/[waveCd](조사 개요),/dashboard/[waveCd]/[partCd](Part 상세, 하위 문항은#item-{partItemCd}앵커). 루트/는GET /waves를 서버에서 조회해 접근 가능한 첫 Wave로 리다이렉트한다. - 헤더 분기탭·좌측 메뉴는 하드코딩 config가 아니라
GET /waves(헤더)와GET /waves/{waveCd}(사이드바,parts[].items[])를 그대로 데이터 소스로 사용한다 (AppMainLayout.tsx). 새 분기/Part/문항이 추가돼도 프론트 코드 변경이 필요 없다. - BFF 프록시 패턴: 브라우저 →
src/app/api/waves/[[...slug]]/route.ts(GET 전용, CUD 없음) →createServerApi()(httpOnly 쿠키의 accessToken을 Bearer로 자동 첨부) → 실제 백엔드.example리소스와 동일한 패턴이며, 신규 리소스 추가 시 이 구조를 그대로 복제하면 된다. userContext/ctx쿼리파라미터: Swagger상 로그인/로그아웃/Wave API에 필수 파라미터로 보이지만, 실제로는 서버가 인증 헤더에서 자동으로 채우는 값이다 (curl로 직접 검증함 — 파라미터 없이 호출해도 정상 동작). 프론트에서 절대 수동으로 구성해 보내면 안 된다(클라이언트가 자기userRole을 조작할 수 있게 되는 보안 문제).- Wave 접근 정책:
GET /waves는accessible플래그와 함께 모든 Wave를 반환한다 — 헤더 탭은accessible=false면disabled처리만 하고 숨기지 않는다. Wave/Part 상세 API는 비공개 접근 시403 WAVE_ACCESS_DENIED를 반환하며,nextApi의 기본 403 핸들러(로그아웃 리다이렉트)를 쓰면 안 되므로skipForbiddenHandler: true를 지정하고 화면에서 직접 에러 메시지를 표시한다 (src/lib/api-error-message.ts). - 파일 다운로드: Wave 상세 응답의
files[].downloadUrl은 백엔드 서버 origin 기준 상대 경로이며 프론트 앱 origin과 다르다.NEXT_PUBLIC_FILE_ORIGIN환경변수(백엔드와 동일 호스트,.env.local/.env.development/.env.production에 정의)와 결합해서 사용한다 (src/lib/file-download.ts). 경로를 직접 조합하지 않는다. - 차트 라이브러리: 프로젝트에 없었으므로 KriUiRegistry(
https://ui-registry.kric.com/r/kri-chart.json)의 echarts 래퍼(kri-chart,KriBarChart등)를 shadcn CLI로 설치했다 (src/components/chart/). 새 의존성(echarts,echarts-for-react)이 추가됐다. - 차트/통계표 데이터 해석:
resultGroups가 렌더링 단위. 통계표는 모든categories/series.values를 그대로 쓰고, 차트는category.chartVisible === true인 인덱스만 category/series를 함께 필터링해서 사용한다 (src/lib/chart-utils.ts의toChartData).categories[i]와 각series[n].values[i]는 항상 같은 인덱스로 정렬되어 있다는 전제. - 에러 응답: RFC 7807(
application/problem+json)이며errorToResponse(@kri/common/http)가 그대로 BFF 응답에 프록시한다. 프론트는detail보다code(예:WAVE_ACCESS_DENIED,WAVE_NOT_FOUND,PART_NOT_FOUND)로 분기하는 걸 우선한다. - 로그인 필터 vs 업무 오류 403 구분: 인증 필터 단계에서 막힌 요청(토큰 없음/무효)은 바디 없는 401/403으로 온다.
WAVE_ACCESS_DENIED같은 업무 오류는 RFC7807code가 있는 정상 JSON 응답이다.code가 없는 401/403은 세션이 실제로 무효하다는 뜻이므로/logout으로 보내야 한다 (src/lib/api-error-message.ts의isSessionInvalid). 반대로 클라이언트가 이미 로그아웃 상태(useAuth()의auth.user가 없음)라면 애초에 API를 호출하지 않고 즉시/logout으로 보낸다 (AppMainLayout.tsx) — 두 체크는 서로 다른 계층(클라이언트가 아는 상태 vs 서버가 판정한 토큰 유효성)이라 둘 다 필요하다.
⚠️ nextApi(브라우저 클라이언트) 필수 수정 사항 — 스캐폴딩 버그
NEXT_PUBLIC_API_BASE=/api(상대 경로)를 createHttpClient에 그대로 넘기면 브라우저의 모든 API 호출이 예외 없이 즉시 실패한다. @kri/common의 createBaseUrl이 내부적으로 new URL(baseUrl)을 base 인자 없이 호출하는데(node_modules/@kri/common/dist/http/http-client.js), 상대 경로만 단독으로 넘기면 브라우저 URL 생성자가 document.baseURI로 자동 보정해주지 않고 TypeError: Failed to construct 'URL': Invalid URL을 던진다. 원래 스캐폴딩(@kri/create-next-app)은 이 버그를 가진 채로 생성되며, example CRUD가 실사용된 적이 없어 지금까지 드러나지 않았었다.
src/lib/http-client.ts에서 브라우저에서는 window.location.origin과 결합해 절대 URL로 변환한 뒤 createHttpClient에 넘기도록 고쳐뒀다 — 이 파일을 재생성하거나 유사 패턴(nextApi 스타일 클라이언트)을 다른 프로젝트에 복제할 때 이 처리를 빠뜨리지 말 것.