구축·운영

Production readiness

차트는 작은 API mismatch도 빈 대시보드나 잘못된 의사결정으로 이어집니다. 배포 전 레이아웃, 접근성, 데이터, 성능, release smoke를 한 번에 닫습니다.

reopt design업데이트 2026년 6월 26일

1. 릴리즈 게이트

opt-charts 변경은 package test만으로 끝내지 않습니다. 문서 route, catalog route, 소비자 앱 install smoke가 함께 통과해야 실제 배포에 충분합니다.

Gate	필수 증거	잡는 리스크
Layout	height, minHeight, aspect 중 하나가 명시되고 모바일에서 overflow가 없습니다.	ResponsiveContainer 높이 0, card 내부 차트 collapse, tooltip clipped
Accessibility	aria-label 또는 aria-describedby가 있고 chart summary가 데이터 의미를 설명합니다.	스크린 리더에서 그래픽만 노출, 수치 변화 설명 누락
Data	dataKey와 series가 API 응답 필드와 일치하고 empty/error/loading이 패널 레벨에 있습니다.	undefined series, 빈 차트, formatter 단위 불일치
Performance	대량 포인트는 샘플링/집계하고 animation은 운영 대시보드 성격에 맞게 꺼집니다.	hydration 이후 긴 frame, dashboard 탭 전환 지연
Release	package typecheck/test/build, web docs tests, install smoke가 같은 커밋에서 통과합니다.	workspace에서는 되지만 소비자 앱 install에서 export 누락

2. 컴포넌트별 체크

LineChart / AreaChart

dot은 기본 false입니다. 포인트가 많으면 그대로 두고, 주요 이벤트만 annotation이나 별도 label로 표시합니다.

BarChart

vertical layout에서는 XAxis가 number, YAxis가 category로 바뀝니다. 긴 category label은 외부 표나 tooltip로 보완합니다.

PieChart

showLabels는 기본 false입니다. segment가 많으면 legend와 tooltip 중심으로 두고, 상위 5개 외에는 Other로 집계합니다.

FunnelChart

data.length가 0이면 null입니다. 카드 높이를 유지해야 하는 화면은 부모에서 empty state를 렌더링합니다.

RetentionHeatmap

값은 0-100 기준으로 color interpolation됩니다. 비율이 아닌 값을 넣는 경우 valueFormatter와 colorScale을 함께 바꿉니다.

ReportWidget

metric/gauge 외 차트는 동적 import 후 loadingChart를 보여줍니다. report canvas에서는 skeleton 높이를 고정합니다.

3. 성능 기준

Recharts 기반 차트는 포인트 수, series 수, animation, tooltip payload에 민감합니다. 운영 대시보드에서는 API 단계에서 집계하고, 실시간 갱신 화면은 `animate=`를 기본으로 둡니다. ReportWidget처럼 builder canvas에서 다수 위젯을 렌더링하는 경우 chart type별 lazy loading과 고정 높이를 유지합니다.

4. 브라우저 확인

문서 페이지는 navigation, pager, TOC, SEO source path까지 같이 검증합니다. catalog는 실제 chart render와 tooltip/legend 상호작용을 확인하는 smoke surface입니다.

bash

# local docs 확인
bun run --filter @reopt/web dev

# 확인 경로
http://localhost:5001/docs/opt-charts
http://localhost:5001/docs/opt-charts/getting-started
http://localhost:5001/docs/opt-charts/data-model
http://localhost:5001/explore/opt-charts

5. 릴리즈 명령

패키지 변경, 문서 변경, publish 준비가 같이 들어간 PR에서는 아래 명령을 기본 gate로 둡니다. GitHub Packages publish는 버전 bump와 registry 대상이 승인된 뒤에만 실행합니다.

bash

bun run --filter @reopt-ai/opt-charts typecheck
bun run --filter @reopt-ai/opt-charts test
bun run --filter @reopt-ai/opt-charts build
bun run --filter @reopt/web typecheck
bun run --filter @reopt/web test -- 'app/[locale]/docs/__tests__'

workspace 경로가 아닌 tarball 설치 검증이 필요한 릴리즈라면 fresh consumer smoke까지 추가합니다.

bash

bun run --filter @reopt-ai/opt-charts build
node scripts/validate-private-publish.mjs

TMP_DIR=$(mktemp -d)
npm create vite@latest "$TMP_DIR/opt-charts-smoke" -- --template react-ts
cd "$TMP_DIR/opt-charts-smoke"
npm install
npm install /path/to/reopt-design/packages/opt-charts/reopt-ai-opt-charts-*.tgz
npm run build

1. 릴리즈 게이트

opt-charts 변경은 package test만으로 끝내지 않습니다. 문서 route, catalog route, 소비자 앱 install smoke가 함께 통과해야 실제 배포에 충분합니다.

Gate	필수 증거	잡는 리스크
Layout	height, minHeight, aspect 중 하나가 명시되고 모바일에서 overflow가 없습니다.	ResponsiveContainer 높이 0, card 내부 차트 collapse, tooltip clipped
Accessibility	aria-label 또는 aria-describedby가 있고 chart summary가 데이터 의미를 설명합니다.	스크린 리더에서 그래픽만 노출, 수치 변화 설명 누락
Data	dataKey와 series가 API 응답 필드와 일치하고 empty/error/loading이 패널 레벨에 있습니다.	undefined series, 빈 차트, formatter 단위 불일치
Performance	대량 포인트는 샘플링/집계하고 animation은 운영 대시보드 성격에 맞게 꺼집니다.	hydration 이후 긴 frame, dashboard 탭 전환 지연
Release	package typecheck/test/build, web docs tests, install smoke가 같은 커밋에서 통과합니다.	workspace에서는 되지만 소비자 앱 install에서 export 누락

2. 컴포넌트별 체크

LineChart / AreaChart

dot은 기본 false입니다. 포인트가 많으면 그대로 두고, 주요 이벤트만 annotation이나 별도 label로 표시합니다.

BarChart

vertical layout에서는 XAxis가 number, YAxis가 category로 바뀝니다. 긴 category label은 외부 표나 tooltip로 보완합니다.

PieChart

showLabels는 기본 false입니다. segment가 많으면 legend와 tooltip 중심으로 두고, 상위 5개 외에는 Other로 집계합니다.

FunnelChart

data.length가 0이면 null입니다. 카드 높이를 유지해야 하는 화면은 부모에서 empty state를 렌더링합니다.

RetentionHeatmap

값은 0-100 기준으로 color interpolation됩니다. 비율이 아닌 값을 넣는 경우 valueFormatter와 colorScale을 함께 바꿉니다.

ReportWidget

metric/gauge 외 차트는 동적 import 후 loadingChart를 보여줍니다. report canvas에서는 skeleton 높이를 고정합니다.

3. 성능 기준

4. 브라우저 확인

문서 페이지는 navigation, pager, TOC, SEO source path까지 같이 검증합니다. catalog는 실제 chart render와 tooltip/legend 상호작용을 확인하는 smoke surface입니다.

bash

# local docs 확인
bun run --filter @reopt/web dev

# 확인 경로
http://localhost:5001/docs/opt-charts
http://localhost:5001/docs/opt-charts/getting-started
http://localhost:5001/docs/opt-charts/data-model
http://localhost:5001/explore/opt-charts

5. 릴리즈 명령

bash

bun run --filter @reopt-ai/opt-charts typecheck
bun run --filter @reopt-ai/opt-charts test
bun run --filter @reopt-ai/opt-charts build
bun run --filter @reopt/web typecheck
bun run --filter @reopt/web test -- 'app/[locale]/docs/__tests__'

workspace 경로가 아닌 tarball 설치 검증이 필요한 릴리즈라면 fresh consumer smoke까지 추가합니다.

bash

bun run --filter @reopt-ai/opt-charts build
node scripts/validate-private-publish.mjs

TMP_DIR=$(mktemp -d)
npm create vite@latest "$TMP_DIR/opt-charts-smoke" -- --template react-ts
cd "$TMP_DIR/opt-charts-smoke"
npm install
npm install /path/to/reopt-design/packages/opt-charts/reopt-ai-opt-charts-*.tgz
npm run build