Q.CAST Front

Q.CELLS 일본 시장 대상 태양광 패널 레이아웃 설계 · 견적 · 관리 프론트엔드. Next.js 14 App Router 기반.

자세한 작업 규약 · 비명시적 패턴 · gotcha 는 CLAUDE.md 와 docs/ PDF 들을 참조한다.

Stack

• Framework: Next.js 14.2.28 (App Router, reactStrictMode: false)
• Language: JavaScript + TypeScript (allowJs: true, strict: false)
• Canvas: Fabric.js 5.5.2 (커스텀 확장 — src/components/fabric/, src/util/fabric-extensions.js)
• State: Recoil 0.7.7 (도메인별 atom — src/store/)
• Session/Auth: iron-session 8 (쿠키 기반)
• Data fetching: axios 1.7 + SWR 2.3
• i18n: next-international (ja / ko — src/locales/)
• UI: react-responsive-modal, react-select, react-datepicker, ag-grid-react, sweetalert2, react-icons, framer-motion, tailwindcss + sass
• PDF/이미지: jimp, sharp, convertapi
• DB 클라이언트: mssql (서버 사이드), sqlite/sqlite3 (로컬 캐시)
• AWS: @aws-sdk/client-s3
• Geo: @turf/turf, mathjs, big.js
• Path alias: @/* → ./src/*

Getting Started

yarn install
yarn dev           # .env.localhost 사용, http://localhost:3000

.env.localhost 가 워크트리에 있어야 한다(실제 시크릿 포함). 새 머신에서는 팀에서 받아 배치할 것.

HTTPS 가 필요하면 ./certificates/key.pem, cert.pem 을 준비한 뒤 yarn serve (HTTP 3000 + HTTPS 3001).

Scripts

모든 스크립트는 env-cmd 로 .env.<mode> 를 주입한다. 테스트 러너는 별도로 wiring 되어 있지 않다.

Script	설명
yarn dev	로컬 개발 (.env.localhost)
yarn dev:log	dev + stdout 을 dev.log 로 미러링
yarn dev:local-api	API 를 http://localhost:8080 으로 고정
yarn local:dev	.env.local.dev 모드 (로컬에서 dev 서버 환경 흉내)
yarn build	프로덕션 빌드 (.env.production)
yarn build:dev	dev 빌드 (.env.development)
yarn build:local.dev	local.dev 빌드
yarn start:cluster1	next start -p 5000 (PM2 prd1)
yarn start:cluster2	next start -p 5001 (PM2 prd2)
yarn start:dev	next start -p 5010 (PM2 dev)
yarn serve	server.js — HTTP 3000 + HTTPS 3001 (certificates 필요)
yarn lint	next lint — 완료 전 필수

Environment Variables

각 모드별 .env.<mode> 파일에 정의. 키 목록(전체 값은 절대 공개 채널에 노출 금지):

Key	용도
NEXT_PUBLIC_RUN_MODE	src/config/config.export.js 가 어떤 config 를 로드할지 결정 (local / local.dev / development / production)
NEXT_PUBLIC_API_SERVER_PATH	백엔드 API base URL
NEXT_PUBLIC_HOST_URL	프론트엔드 호스트 (자기 자신)
NEXT_PUBLIC_API_HOST_URL	API 호스트
SESSION_SECRET	iron-session 쿠키 서명 키 — 32 byte 이상 필수
NEXT_PUBLIC_CONVERTER_DWG_API_URL	DWG → SVG 변환 서비스
NEXT_PUBLIC_CONVERTER_DXF_API_URL	DXF → SVG 변환 서비스
NEXT_PUBLIC_Q_ORDER_AUTO_LOGIN_URL	Q-Order autoLogin 진입점
NEXT_PUBLIC_Q_MUSUBI_AUTO_LOGIN_URL	Q-Musubi autoLogin 진입점
NEXT_PUBLIC_AWS_S3_BASE_URL	S3 정적 자산 base URL
NEXT_PUBLIC_ENABLE_LOGGING	true 일 때만 src/util/logger.js 와 debugCapture.js 가 실제로 출력
AWS_REGION, AMPLIFY_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_PROFILE	S3 업로드 (서버 전용 — .env.localhost 등에만)

.env.* 자체는 git 추적 대상이고 시크릿을 포함한다. 머신별 오버라이드는 .env.*.local (gitignore 됨) 에 둘 것.

Routes (App Router)

src/app/
  api/                  # Next.js Route Handlers (S3, debug, 이미지 등)
  community/            # 커뮤니티
  floor-plan/           # 도면 캔버스 — 본 앱의 핵심
    estimate/           # 견적 화면
    simulator/          # 시뮬레이터
    page.jsx            # 도면 에디터 진입점
  join/                 # 회원가입
  login/                # 로그인
  management/           # 관리자
    image/              # 이미지 관리
    stuff/              # 자재/제품 관리
  layout.js             # 루트 레이아웃 — 세션 체크 후 비로그인 시 /login 으로 리다이렉트
  page.js               # 홈

세션이 없는 상태로 /login 외 경로 접근 시 루트 레이아웃이 강제 리다이렉트한다. src/middleware.js 는 x-pathname 헤더를 주입해 루트 레이아웃이 현재 경로에 따라 분기할 수 있게 한다.

Source Layout

src/
  app/                  # App Router 라우트 + 글로벌 Provider 들
  common/               # 공용 유틸 / 모듈
  components/           # 도메인별 UI 컴포넌트
    fabric/             # QLine, QPolygon — Fabric.js 확장 클래스
    floor-plan/         # 캔버스 툴 모달 (roofShape, placementShape, panelBatch …)
    estimate/, management/, simulator/, ui/, …
  config/               # 모드별 런타임 config (config.export.js 가 분기)
  hooks/                # 도메인별 hook (roofcover, surface, module, object, option …)
  lib/                  # 세션, 캔버스 저장/복원, 파일/이미지 액션
  locales/              # ja.json, ko.json
  middleware.js         # x-pathname 주입
  models/               # 도메인 모델
  store/                # Recoil atom (canvas, roof, estimate, modal, menu, setting …)
  styles/               # sass entry (includePaths)
  util/                 # logger, debugCapture, fabric-extensions, canvas-util …

Deployment (PM2)

*.ecosystem.config.js + startscript*.js 조합으로 실행. startscript 가 child_process.exec 로 yarn 스크립트를 호출한다.

File	용도	Port
ecosystem.config.js	프로덕션 클러스터 (instances: 2)	—
prd1.ecosystem.config.js	프로덕션 #1 (fork)	5000
prd2.ecosystem.config.js	프로덕션 #2 (fork)	5001
dev.ecosystem.config.js	dev 서버	5010
dev.local.ecosystem.config.js	local.dev 모드 dev 서버	—

Conventions

상세 사항은 CLAUDE.md 와 docs/Qcast coding convention.pdf, docs/Qcast development guilde.pdf 참조. 핵심만 옮기면:

• Prettier: single quote, no semicolons, tabWidth 2, printWidth 150, trailingComma all. 완료 전 yarn lint.
• No raw alert() — useSwal / useMessage + sweetalert2 만 사용. docs/메세지 처리 가이드.pdf.
• Path alias @/... 우선, ../../.. 체인 지양.
• 로깅 — console.log 직접 사용 금지. src/util/logger.js 사용 (NEXT_PUBLIC_ENABLE_LOGGING=true 일 때만 출력).
• Commit message — .gitmessage.txt 형식 ([일감번호] : [제목]) 또는 최근 브랜치 스타일 [2204] <제목> — <상세>. Prefix 만 영문, 본문은 한국어.
• i18n — UI 텍스트는 src/locales/{ja,ko}.json 에 키 추가 후 useI18n 으로 접근.

Documentation

File	내용
CLAUDE.md	에이전트(Claude / Codex) 작업 규약 + 비명시적 패턴 · gotcha
docs/Canvas Status.md	캔버스 기능 상태 · 타겟별 컨텍스트 메뉴 인벤토리
docs/Qcast coding convention.pdf	전체 코딩 컨벤션
docs/Qcast development guilde.pdf	개발 가이드
docs/메세지 처리 가이드.pdf	모달 / 알럿 메시지 규칙
docs/git commit message Convention.pdf	커밋 메시지 컨벤션
docs/Nextjs 14 컴포넌트에 대해서….pdf	App Router 서버/클라이언트 컴포넌트 노트
docs/dictionary.txt	도메인 용어집 (지붕 / 패널 용어 JP/KR)
docs/diagrams/	아키텍처 다이어그램
.agents/skills/{next-best-practices,vercel-react-best-practices}/	Next/React 패턴 결정 시 우선 참조 (총 95개 룰 .md)

Troubleshooting

• 빌드 시 Module not found: fs / canvas — next.config.mjs 의 webpack externals 에 추가. node-only deps 는 클라이언트 번들에서 제외해야 한다.
• 세션이 즉시 풀림 — SESSION_SECRET 이 32 byte 미만이면 iron-session 이 거부한다. .env.<mode> 확인.
• 플랜 로드 시 InvalidStateError — src/lib/canvas.js / src/util/canvas-util.js 의 3-layer guard (entry/cache/save) 와 SizeSetting 의 0-area guard 로 차단된다. 가드 약화 금지 — 손상된 플랜은 정상 데이터로 교체할 것.
• App Router 캐시로 인한 stale plan/estimate — next.config.mjs 의 experimental.staleTimes 가 의도적으로 모두 0. 다시 켜지 말 것.
• HTTPS dev 실패 — ./certificates/key.pem, cert.pem 부재. gitignore 대상이라 팀에서 받아 배치해야 한다.
• dev 서버에서만 한글/일본어 폰트 깨짐 — next/font 캐시 문제일 가능성. .next/ 삭제 후 재시작.