qcast-front/docs/superpowers/plans/2026-06-24-roof-shape-pattern-catalog.md

지붕형상 패턴 카탈로그 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: PDF 분석→지붕형상 자동 매칭의 선행 단계로, 지붕형상 설정 팝업의 8개 패턴을 매칭 가능한 시그니처로 정의한 카탈로그 상수 모듈을 추가한다.

Architecture: 의존성 없는 순수 데이터 모듈 1개(src/common/roofShapePattern.js)를 신규 생성한다. 각 패턴 = {shapeNum, key, nameKey, type, ridge, flows, direction?, autoMatchable, note}. 매칭 키는 type + ridge + flows(집합)이며 flows 집합만으로 8패턴이 상호 유일하게 식별된다. 변 역할 적용(처마/케라바 실제 그리기) 로직은 기존 useRoofShapeSetting에 그대로 두고, 이 모듈은 매칭 룩업 테이블 역할만 한다.

Tech Stack: JavaScript (ESM export const), Next.js 14. 신규 의존성 없음.

설계 근거 스펙: docs/superpowers/specs/2026-06-24-roof-shape-pattern-catalog-design.md

Global Constraints

• Prettier: 싱글쿼트, 세미콜론 없음, tabWidth 2, printWidth 150, trailingComma all (.prettierrc).
• 테스트 러너 없음: package.json에 test runner 미연동. 검증은 scratchpad의 node 불변식 하니스로 수행한다(별도 테스트 프레임워크 도입 금지).
• eslint 주의: eslint 미설치 시 next lint가 셋업을 요구할 수 있음 — 임시 설치하더라도 커밋 금지·원복. (메모리: eslint-build-skips-lint)
• Path alias: @/* → ./src/*. 단, 이 모듈은 import가 없다.
• 로깅/alert 금지 규칙 해당 없음(순수 데이터 모듈).
• 모듈 형태: export const ESM. package.json에 "type":"module" 없음 → 소스 .js는 CommonJS 취급되므로, 검증 시 .mjs로 복사해 import 한다(소스에 import가 없어 그대로 동작).
• 범위 경계: 매칭 함수(matchRoofShapePattern)·PDF 분석 확장은 이번 작업 제외. 카탈로그 데이터 + 경량 접근자만.

---

Task 1: 지붕형상 패턴 카탈로그 모듈 생성

Files:

• Create: src/common/roofShapePattern.js
• Verify(scratchpad, 비커밋): <SCRATCH>/check-roofShapePattern.mjs, <SCRATCH>/roofShapePattern.mjs

<SCRATCH> = /private/tmp/claude-501/-Users-devgrr-dev-interplug-hanasys-qcast-front/15fa1013-fdbe-447b-aa10-6e3008bd6339/scratchpad

Interfaces:

• Consumes: 없음(순수 데이터).

• Produces (다음 매칭 작업이 import):

  • ROOF_FLOW = { TOP:'top', BOTTOM:'bottom', LEFT:'left', RIGHT:'right' }
  • ROOF_SHAPE_TYPE = { HIP:'hip', GABLE:'gable', SHED:'shed', MANUAL:'manual' }
  • ROOF_RIDGE = { HIP:'hip', HORIZONTAL:'horizontal', VERTICAL:'vertical', SHED:'shed', NONE:'none' }
  • ROOF_SHAPE_PATTERNS: Array<{ shapeNum:number, key:string, nameKey:string, type:string, ridge:string, flows:string[], direction?:'west'|'east'|'south'|'north', autoMatchable:boolean, note?:string }> (8개)
  • getRoofShapePatternByShapeNum(shapeNum:number) => pattern | null

• Step 1: 검증 하니스 작성 (failing test)

<SCRATCH>/check-roofShapePattern.mjs 생성:

import {
  ROOF_SHAPE_PATTERNS,
  ROOF_FLOW,
  ROOF_SHAPE_TYPE,
  ROOF_RIDGE,
  getRoofShapePatternByShapeNum,
} from './roofShapePattern.mjs'

const fail = (msg) => {
  console.error('FAIL:', msg)
  process.exit(1)
}

// 1. 정확히 8개
if (ROOF_SHAPE_PATTERNS.length !== 8) fail(`expected 8 patterns, got ${ROOF_SHAPE_PATTERNS.length}`)

// 2. shapeNum 이 정확히 {1..8}
const nums = ROOF_SHAPE_PATTERNS.map((p) => p.shapeNum).sort((a, b) => a - b)
if (JSON.stringify(nums) !== JSON.stringify([1, 2, 3, 4, 5, 6, 7, 8])) fail(`shapeNum set mismatch: ${nums}`)

// 3. flows 집합 distinct (정렬 후 JSON 유일) — 매칭 핵심 불변식
const flowKeys = ROOF_SHAPE_PATTERNS.map((p) => JSON.stringify([...p.flows].sort()))
if (new Set(flowKeys).size !== 8) fail('flows signatures are not mutually distinct')

// 4. autoMatchable === false 는 오직 shapeNum 4
const nonMatch = ROOF_SHAPE_PATTERNS.filter((p) => !p.autoMatchable).map((p) => p.shapeNum)
if (JSON.stringify(nonMatch) !== JSON.stringify([4])) fail(`autoMatchable=false should be only [4], got ${nonMatch}`)

// 5. nameKey 비어있지 않음 / shed(type=SHED)만 direction 보유
for (const p of ROOF_SHAPE_PATTERNS) {
  if (typeof p.nameKey !== 'string' || !p.nameKey) fail(`empty nameKey at shapeNum ${p.shapeNum}`)
  const isShed = p.type === ROOF_SHAPE_TYPE.SHED
  if (isShed && !p.direction) fail(`shed shapeNum ${p.shapeNum} missing direction`)
  if (!isShed && p.direction) fail(`non-shed shapeNum ${p.shapeNum} has direction`)
}

// 6. flows 값이 ROOF_FLOW 어휘에 속함 / ridge·type 이 상수 어휘에 속함
const FLOW_VALUES = Object.values(ROOF_FLOW)
const TYPE_VALUES = Object.values(ROOF_SHAPE_TYPE)
const RIDGE_VALUES = Object.values(ROOF_RIDGE)
for (const p of ROOF_SHAPE_PATTERNS) {
  if (!TYPE_VALUES.includes(p.type)) fail(`bad type at shapeNum ${p.shapeNum}: ${p.type}`)
  if (!RIDGE_VALUES.includes(p.ridge)) fail(`bad ridge at shapeNum ${p.shapeNum}: ${p.ridge}`)
  for (const f of p.flows) if (!FLOW_VALUES.includes(f)) fail(`bad flow at shapeNum ${p.shapeNum}: ${f}`)
}

// 7. 접근자
if (getRoofShapePatternByShapeNum(1)?.key !== 'ridge') fail('accessor(1) wrong')
if (getRoofShapePatternByShapeNum(99) !== null) fail('accessor(99) should be null')

console.log('OK: all roofShapePattern invariants hold')

• Step 2: 실패 확인 (red)

Run:

SCRATCH=/private/tmp/claude-501/-Users-devgrr-dev-interplug-hanasys-qcast-front/15fa1013-fdbe-447b-aa10-6e3008bd6339/scratchpad
node "$SCRATCH/check-roofShapePattern.mjs"

Expected: FAIL — Cannot find module '.../roofShapePattern.mjs' (소스 모듈이 아직 없음).

• Step 3: 카탈로그 모듈 작성 (minimal implementation)

src/common/roofShapePattern.js 생성:

// 지붕형상 설정 팝업(RoofShapeSetting)의 8개 패턴 카탈로그.
// PDF 분석→지붕형상 자동 매칭의 룩업 테이블. 매칭 키: type + ridge + flows(집합).
// 설계 근거: docs/superpowers/specs/2026-06-24-roof-shape-pattern-catalog-design.md

// 화면축 흐름방향 (방위적용 前 — 지붕형상 설정 시점에는 실제 방위가 없다)
export const ROOF_FLOW = { TOP: 'top', BOTTOM: 'bottom', LEFT: 'left', RIGHT: 'right' }

// 지붕 유형
export const ROOF_SHAPE_TYPE = { HIP: 'hip', GABLE: 'gable', SHED: 'shed', MANUAL: 'manual' }

// 용마루 방향
export const ROOF_RIDGE = { HIP: 'hip', HORIZONTAL: 'horizontal', VERTICAL: 'vertical', SHED: 'shed', NONE: 'none' }

// shapeNum = useRoofShapeSetting.shapeMenu 의 id 이자 자동 클릭 대상(setShapeNum 값).
// flows 집합만으로 8패턴이 상호 유일하게 식별된다.
// 5~8 화면축↔버튼 매핑은 useRoofShapeSetting case 4~8 에서 전사(정규 winding: outerLines[0].direction==='bottom').
export const ROOF_SHAPE_PATTERNS = [
  {
    shapeNum: 1,
    key: 'ridge',
    nameKey: 'modal.roof.shape.setting.ridge',
    type: ROOF_SHAPE_TYPE.HIP,
    ridge: ROOF_RIDGE.HIP,
    flows: [ROOF_FLOW.TOP, ROOF_FLOW.BOTTOM, ROOF_FLOW.LEFT, ROOF_FLOW.RIGHT],
    autoMatchable: true,
    note: '寄棟 — 전 변 처마, 사방 흐름',
  },
  {
    shapeNum: 2,
    key: 'patternA',
    nameKey: 'modal.roof.shape.setting.patten.a',
    type: ROOF_SHAPE_TYPE.GABLE,
    ridge: ROOF_RIDGE.HORIZONTAL,
    flows: [ROOF_FLOW.TOP, ROOF_FLOW.BOTTOM],
    autoMatchable: true,
    note: '切妻 — 상하 처마/좌우 케라바, 가로 용마루',
  },
  {
    shapeNum: 3,
    key: 'patternB',
    nameKey: 'modal.roof.shape.setting.patten.b',
    type: ROOF_SHAPE_TYPE.GABLE,
    ridge: ROOF_RIDGE.VERTICAL,
    flows: [ROOF_FLOW.LEFT, ROOF_FLOW.RIGHT],
    autoMatchable: true,
    note: '切妻 — 좌우 처마/상하 케라바, 세로 용마루',
  },
  {
    shapeNum: 5,
    key: 'west',
    nameKey: 'commons.west',
    type: ROOF_SHAPE_TYPE.SHED,
    ridge: ROOF_RIDGE.SHED,
    flows: [ROOF_FLOW.BOTTOM],
    direction: 'west',
    autoMatchable: true,
    note: '片流れ — 처마/흐름 bottom, 케라바 좌우',
  },
  {
    shapeNum: 6,
    key: 'east',
    nameKey: 'commons.east',
    type: ROOF_SHAPE_TYPE.SHED,
    ridge: ROOF_RIDGE.SHED,
    flows: [ROOF_FLOW.TOP],
    direction: 'east',
    autoMatchable: true,
    note: '片流れ — 처마/흐름 top, 케라바 좌우',
  },
  {
    shapeNum: 7,
    key: 'south',
    nameKey: 'commons.south',
    type: ROOF_SHAPE_TYPE.SHED,
    ridge: ROOF_RIDGE.SHED,
    flows: [ROOF_FLOW.RIGHT],
    direction: 'south',
    autoMatchable: true,
    note: '片流れ — 처마/흐름 right, 케라바 상하',
  },
  {
    shapeNum: 8,
    key: 'north',
    nameKey: 'commons.north',
    type: ROOF_SHAPE_TYPE.SHED,
    ridge: ROOF_RIDGE.SHED,
    flows: [ROOF_FLOW.LEFT],
    direction: 'north',
    autoMatchable: true,
    note: '片流れ — 처마/흐름 left, 케라바 상하',
  },
  {
    // 변별로 설정 — 자동매칭 비대상(폴백). 깨끗한 매칭 실패 시 후보로만 표시.
    shapeNum: 4,
    key: 'side',
    nameKey: 'modal.roof.shape.setting.side',
    type: ROOF_SHAPE_TYPE.MANUAL,
    ridge: ROOF_RIDGE.NONE,
    flows: [],
    autoMatchable: false,
    note: '변별로 설정 — 자동매칭 비대상(폴백)',
  },
]

// shapeNum 으로 카탈로그 항목 조회. 없으면 null.
export const getRoofShapePatternByShapeNum = (shapeNum) => ROOF_SHAPE_PATTERNS.find((pattern) => pattern.shapeNum === shapeNum) || null

• Step 4: 통과 확인 (green)

Run:

SCRATCH=/private/tmp/claude-501/-Users-devgrr-dev-interplug-hanasys-qcast-front/15fa1013-fdbe-447b-aa10-6e3008bd6339/scratchpad
cp src/common/roofShapePattern.js "$SCRATCH/roofShapePattern.mjs"
node "$SCRATCH/check-roofShapePattern.mjs"

Expected: OK: all roofShapePattern invariants hold

• Step 5: lint / build 검증 (sub-agent)

서브에이전트로 lint·build 검증을 수행한다(프로젝트 컨벤션). lint는 best-effort(eslint 미설치 시 셋업 요구하면 임시 설치 금지·Prettier 규칙 수기 준수로 대체), build는 회귀 가드.

yarn lint   # eslint 미설치 시 셋업 프롬프트면 중단·미설치 유지

Expected: 신규 파일에 대한 에러 0. (이 모듈은 아직 어디서도 import 되지 않아 build 트리쉐이킹 대상이지만, 컨벤션상 yarn build 통과도 확인.)

• Step 6: 커밋

git add src/common/roofShapePattern.js
git commit -m "feat(roof-shape): 지붕형상 패턴 카탈로그 상수 모듈 추가

[작업내용] :
- ROOF_SHAPE_PATTERNS(8) + ROOF_FLOW/ROOF_SHAPE_TYPE/ROOF_RIDGE 상수
- 매칭 키 type+ridge+flows, flows 집합만으로 8패턴 유일 식별
- getRoofShapePatternByShapeNum 접근자
- 매칭 함수·PDF 분석 확장은 다음 작업으로 분리

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"

(scratchpad 검증 파일은 리포 밖이라 커밋 대상 아님.)

---

Self-Review

1. Spec coverage:

• §3 데이터 모듈 스키마 → Task 1 Step 3 ✅
• §4 8패턴 카탈로그 내용 → Task 1 Step 3 (8항목, shapeNum/flows/direction 정합) ✅
• §4 경량 접근자 getRoofShapePatternByShapeNum → Step 3 ✅
• §6 distinct 불변식 검증 → Step 1·4 하니스(불변식 3) ✅
• §6 lint+build → Step 5 ✅
• §5 매칭 함수 미구현(계약만) → 본 플랜에서 의도적으로 제외(범위 경계) ✅
• §2 5~8 화면축↔버튼 매핑 → Step 3 데이터 + 모듈 주석에 반영 ✅

2. Placeholder scan: TBD/TODO/“적절히 처리” 없음. 모든 코드 step에 실제 코드 포함. ✅

3. Type consistency: ROOF_SHAPE_PATTERNS 항목 형태(shapeNum/key/nameKey/type/ridge/flows/direction?/autoMatchable/note)가 Interfaces·Step 3·하니스 검증에서 동일. 접근자명 getRoofShapePatternByShapeNum 일관. flows 값은 ROOF_FLOW 어휘로 통일. ✅