qcast-front/.claude/memory/feedback_debug_labels_local_only.md

name	description	type
디버그 라벨은 QPolygon 인라인 + local 전용	debugLabels 는 별도 util 파일 없이 QPolygon.js 안에 인라인. NEXT_PUBLIC_RUN_MODE==='local' 에서만 동작.	feedback

핵심 규칙 (2개):

1. 가드: 캔버스 라벨은 항상 process.env.NEXT_PUBLIC_RUN_MODE === 'local' 에서만 그려져야 한다. 'local.dev', 'development', 'production' 에서 라벨 보이면 안 됨.

2. 별도 util 파일 만들지 말 것. 사용자 명시: "util 에 debug 파일 자체가 없다.. 라벨은 다른 qline 이런곳에 올려라". 라벨 코드는 호출처(src/components/fabric/QPolygon.js) 안에 인라인 함수(__attachDebugLabels, __classifyLineForLabel, __isDebugLabelsEnabled) 로 둔다.

Why:

• 사용자 명시 반복: "local 일때만 실행, dev/prd 에 사용되면 안 된다."
• src/util/debugLabels.js (+ stub, + next.config alias) 구조를 만들었더니 사용자가 "util 에 debug 파일 자체가 없다" 고 거부. 별도 파일 = 관리 부담 + dev/prd 동기화 이슈.
• 인라인 두면 외부 의존 0, 가드는 빌드 타임 dead-code 제거 가능 (Next.js 가 NEXT_PUBLIC_* 를 리터럴 치환).
• 캔버스에 노란 배경 라벨(B-7, SK-3 등) 이 운영 환경에서 보이면 사용자/고객 혼란.
• local.dev 는 "로컬에서 dev API 붙이는" 모드라 이름은 local 이지만 OFF 대상.

How to apply:

• 가드 함수 __isDebugLabelsEnabled() 의 비교 문자열 변경/완화 금지. === 등호 유지.
• 라벨 관련 새 헬퍼 함수가 필요해도 src/util/ 등 외부에 새 파일 만들지 말 것. QPolygon.js (또는 사용자가 지정한 기존 파일) 안에 인라인.
• 다른 디버그 시각화 추가 시에도 같은 인라인 + 가드 패턴 재사용.
• ENV 정의: .env.localhost=local / .env.local.dev=local.dev / .env.development=development / .env.production=production.

현재 상태 (2026-04-27, 최종):

• src/util/debugLabels.js 삭제, src/util/debugLabels.stub.js 삭제, next.config.mjs alias 설정 원복.
• 모든 라벨 코드는 src/components/fabric/QPolygon.js 상단 (line 1180) 에 인라인:
  • DEBUG_LABEL_NAME 상수
  • __isDebugLabelsEnabled() env 가드
  • __classifyLineForLabel(obj) prefix 분류
  • __attachDebugLabels(canvas, parentId) 부착
• 호출은 drawHelpLine 끝 (~line 600): __attachDebugLabels(this.canvas, this.id)
• dev/prd 빌드: 가드가 false → fabric.Text 생성/추가 없음. 외부 파일 의존 없으므로 빌드 안전.