# templates_v2 스키마 초안 (C.2-a)

C.1 감사에서 드러난 갭 3가지를 해소하기 위한 스키마 확장 초안.

- `_COMPAT` 커버리지 26% → 필드 기반 자동 파생으로 100%
- `structure_intent` 어휘 얕음 (10개, 6 고아) → controlled vocab 확장
- `alternative_patterns` 필드 부재 → 명시적 대안 관계 추가

---

## 1. 새 필드: `content_affinity` (12개 enum)

**역할**: layout 이 선호하는 **콘텐츠 성격** — V3 의 의미 구분 핵심 신호.

| # | 값 | 의미 | 예시 MDX / Figma |
|---|---|---|---|
| 1 | `concept_definition` | 용어/개념 정의 | "BIM이란", "DX란" · Frame 18 |
| 2 | `concept_comparison` | 2+ 개념의 차이점 비교 | "BIM vs DX" · Frame 18 |
| 3 | `goal_axes` | 목표의 핵심 축 나열 (N개) | "DX의 궁극적 목표" · Frame 12 |
| 4 | `persona_benefit` | 주체별 혜택/역할 | "발주자/설계자/시공자 기대효과" · Frame 14 |
| 5 | `process_steps` | 순서 있는 단계 (1→2→3) | "1단계 계획 → 2단계 설계" |
| 6 | `before_after_change` | 전/후 상태 전환 | "AS-IS → TO-BE" · Frame 29 |
| 7 | `capability_requirements` | 요구 역량/조건 나열 | "필수조건", "S/W 필요" · Frame 13, 20 |
| 8 | `comparative_matrix` | N개 × M축 비교표 | 관점별 대비표 · Frame 18 (rows 형식) |
| 9 | `stakeholder_roles` | 이해당사자별 역할 | "정부/민간/학계" |
| 10 | `policy_requirements` | 정책/제도 틀 | "정부주도 BIM 도입" · Frame 27 |
| 11 | `tool_ecosystem` | 도구/SW 생태계 | "Revit, Navisworks 등" |
| 12 | `interrelation` | N개 요소의 상호관계 (순환/벤다이어그램) | "용어간 상호관계" · Frame 1, 12 |

**복수 태깅 허용**: Frame 18 = `[concept_comparison, comparative_matrix]` 처럼 primary + secondary.

### 1-1. 경계 정의 (경계가 붙는 값들)

- **`stakeholder_roles`** vs **`persona_benefit`**
  - `stakeholder_roles` = 주체별 **역할/책임/관계** (누가 무엇을 하는가 — 정부 주도 / 민간 수행 / 학계 연구)
  - `persona_benefit` = 주체별 **기대효과/혜택** (발주자가 얻는 것 / 설계자가 얻는 것)
  - 같은 주체 나열이라도 "**역할 정의**" 면 roles, "**얻는 효과**" 면 benefit
- **`policy_requirements`** vs **`capability_requirements`**
  - `policy_requirements` = 정책/제도/거버넌스 **틀** (정부 BIM 도입 정책, 법적 프레임)
  - `capability_requirements` = 기술/도구/역량 **요건** (S/W 필수, 인력 필요)
  - 이름이 좁게 읽힐 수 있으나 `requirements_constraints` 같은 넓은 이름은 `capability_requirements` 와 겹칠 위험이 있어 분리 유지

---

## 2. 확장: `structure_intent` (10 → 9 통제 어휘)

**역할**: layout 이 **시각적으로 전달하려는 의도** — content_affinity 와 직교 축.

기존 10개는 자유 서술이라 고아 다수. **9개 통제 어휘** 로 압축 + 확장.

| 값 | 의미 | 기존 매핑 |
|---|---|---|
| `binary_compare` | 2개 항목 대비 | concept_comparison 일부 |
| `multi_parallel` | N개 항목 병렬 나열 | requirement_list, requirement_or_pillar |
| `hierarchy` | 상위-하위 관계 | (신규) |
| `sequence` | 순서 있는 흐름 | transformation_story 일부 |
| `state_transition` | **전/후 상태 전환** (AS-IS ↔ TO-BE, Process 혁신) | (신규 — 사용자 피드백 반영) |
| `cycle_interrelation` | 순환 / 상호관계 | (신규 — 고아였던 곳 흡수) |
| `matrix_coverage` | 다차원 커버리지 | multi_attribute_comparison, category_comparison |
| `persona_mapping` | 주체별 매핑 | persona_benefit, industry_comparison |
| `singleton_emphasis` | 단일 강조 | problem_diagnosis 일부 |

**`state_transition` 별도 축 필요성**: content_affinity 의 `before_after_change` 는 "콘텐츠가 전/후 변화를 다룬다" 는 의미. `state_transition` 은 "**레이아웃이 그 변화를 시각적으로 대비 표현** 한다" 는 의도. 둘은 직교 — `before_after_change` 콘텐츠를 `multi_parallel` 레이아웃에 담을 수도, `state_transition` 레이아웃에 담을 수도 있음.

---

## 3. 신규 필드: `alternative_patterns`

**역할**: 이 layout 이 담지 못하는 경우 **의미적 대안 layout** 을 명시. `_COMPAT` 의 빈 공간을 메움.

```yaml
alternative_patterns:
  - pattern: cycle-3way
    reason: "3개 요소를 순환/상호관계로 표현할 때"
    confidence: 0.8
  - pattern: circular-nodes
    reason: "N개 요소를 radial 로 배치"
    confidence: 0.6
```

**출처 혼합 전략** (사용자 지시대로):
- (a) 기존 `_COMPAT` 중 confidence ≥ 0.7 인 관계 흡수
- (b) V3 실패 케이스에서 드러난 관계 수동 추가 (`cycle-3way` ↔ `3col-parallel` 등)
- (c) 최종적으로 `family + layout + content_affinity + structure_intent` 유사도로 **자동 파생 가능**하게 설계

---

## 4. 자동 layout 호환도 파생 공식

수작업 `_COMPAT` 대신:

```
layout_compat_v2(a, b) =
    0.25 × family_match(a.family, b.family)               # exact match = 1, else 0
  + 0.20 × axis_match(a.axis, b.axis)
  + 0.20 × relation_type_match(a.relation_type, b.relation_type)
  + 0.15 × cardinality_overlap(a.cardinality, b.cardinality)
  + 0.20 × jaccard(a.alternative_patterns, b.layout)      # 명시된 대안에 있으면 +
```

→ 330 쌍 전부 자동 계산 가능. `_COMPAT` 수작업 테이블 폐기.

**V3 매칭 공식** (2차 신호 반영):
```
v3_score = 0.40 × layout_compat_v2
         + 0.35 × jaccard(mdx.content_affinity, frame.content_affinity)
         + 0.25 × jaccard(mdx.structure_intent, frame.structure_intent)
```

---

## 5. 완성된 templates_v2 엔트리 예시 (5개 우선 검토 대상)

### Frame 18 (1171281195) — BIM과 DX의 이해

```yaml
visual_pattern:
  family: table
  layout: compare-rows
  axis: vertical
  relation_type: compare
  cardinality: { ideal: 2, min: 2, max: 2 }
content_affinity:
  - concept_comparison        # primary
  - comparative_matrix        # rows 로 다축 비교
structure_intent:
  - binary_compare            # primary
  - matrix_coverage           # secondary
alternative_patterns:
  - { pattern: table-2col, reason: "같은 2개 비교를 컬럼 방식으로", confidence: 0.9 }
  - { pattern: compare-2col, reason: "2열 병렬 비교", confidence: 0.8 }
```

### Frame 12 (cycle-3way) — 건설산업의 목표 (BIM의 목적) ⚠ V3 실패 핵심

```yaml
visual_pattern:
  family: diagram
  layout: cycle-3way
  axis: radial
  relation_type: parallel
  cardinality: { ideal: 3, min: 3, max: 3 }
content_affinity:
  - goal_axes                 # primary — 건설산업 3대 목표
  - interrelation             # secondary — 3요소 순환 구조
structure_intent:
  - cycle_interrelation       # primary
  - multi_parallel            # secondary — 3개 병렬로도 볼 수 있음
alternative_patterns:
  - { pattern: 3col-parallel, reason: "3개 목표를 평면 나열로", confidence: 0.7 }
  - { pattern: circular-nodes, reason: "radial 배치 대안", confidence: 0.6 }
```

### Frame 20 (3col-cards) — 디지털 전환(DX)은 S/W가 필수다

```yaml
visual_pattern:
  family: card
  layout: 3col-cards
  axis: horizontal
  relation_type: parallel
  cardinality: { ideal: 3, min: 3, max: 3 }
content_affinity:
  - capability_requirements   # primary — S/W 등 필수 역량
  - tool_ecosystem            # secondary (도구 언급)
structure_intent:
  - multi_parallel            # primary
alternative_patterns:
  - { pattern: 3col-parallel, reason: "카드 없이 텍스트만", confidence: 0.8 }
  - { pattern: cards-4, reason: "4개로 확장", confidence: 0.5 }
```

**중요**: Frame 12 와 Frame 20 은 둘 다 `3col-parallel` 과 관계가 있으나 — Frame 12 = `goal_axes`, Frame 20 = `capability_requirements`. **content_affinity 가 다름** → V3 v2 가 MDX "DX 의 궁극적 목표"(goal_axes) 를 받으면 Frame 12 를 우선할 수 있음.

### Frame 29 (compare-2banner-top-2col-bottom) — 과정(Process)의 혁신

```yaml
visual_pattern:
  family: diagram
  layout: compare-2banner-top-2col-bottom
  axis: vertical
  relation_type: compare
  cardinality: { ideal: 2, min: 2, max: 2 }
content_affinity:
  - before_after_change       # primary — Process 혁신 (전/후)
  - concept_comparison        # secondary
structure_intent:
  - state_transition          # primary — AS-IS → TO-BE 대비 (사용자 피드백 반영)
  - binary_compare            # secondary
alternative_patterns:
  - { pattern: compare-2col, reason: "단순 2열 비교로", confidence: 0.8 }
  - { pattern: 2col-paired, reason: "짝지은 2열", confidence: 0.7 }
```

### Frame 3 (list-numbered) — 국외

```yaml
visual_pattern:
  family: list
  layout: list-numbered
  axis: vertical
  relation_type: sequence
  cardinality: { ideal: 4, min: 3, max: 8 }
content_affinity:
  - policy_requirements       # primary — 국외 정책 사례
  - stakeholder_roles         # secondary
structure_intent:
  - sequence                  # primary
  - multi_parallel            # secondary
alternative_patterns:
  - { pattern: list-stacked, reason: "번호 없는 리스트로", confidence: 0.9 }
  - { pattern: bullet-cards, reason: "항목을 카드로", confidence: 0.6 }
```

### Frame 11 (3-category) — 시공단계 BIM 모델과 정보 활용 구분

```yaml
visual_pattern:
  family: card
  layout: 3-category
  axis: horizontal
  relation_type: parallel
  cardinality: { ideal: 3, min: 3, max: 3 }
content_affinity:
  - concept_definition        # primary — 3가지 개념 구분
  - concept_comparison        # secondary
structure_intent:
  - multi_parallel            # primary
  - matrix_coverage           # secondary
alternative_patterns:
  - { pattern: 3col-parallel, reason: "카테고리 없이 병렬", confidence: 0.8 }
  - { pattern: persona-3col, reason: "주체별 매핑으로", confidence: 0.5 }
```

---

## 6. V3 실패 케이스가 어떻게 해결되는가 (02-1 시뮬레이션)

### MDX 02-1 "1. DX의 궁극적 목표" (가상 라벨)
```yaml
mdx_layout: 3col-parallel
content_affinity: [goal_axes]          # 3대 목표
structure_intent: [multi_parallel]
```

### 현재 V3 (_COMPAT 기반)
- Frame 20 `3col-cards` compat 0.9 → **1위**
- Frame 12 `cycle-3way` compat **0.15 fallback** → 낮은 순위

### V3 v2 (새 스키마)

Frame 12 점수:
```
layout_compat_v2: 
  family_match(3col-parallel, cycle-3way) → diagram vs diagram* → 0
  axis_match(?, radial) → 0
  relation_type_match(parallel, parallel) → 1 * 0.20 = 0.20
  cardinality_overlap(3, 3) → 1 * 0.15 = 0.15
  jaccard(alt_patterns, 3col-parallel): Frame 12 has 3col-parallel as alt (conf 0.7) → 0.20 * 0.7 = 0.14
  total ≈ 0.49

content_affinity: jaccard([goal_axes], [goal_axes, interrelation]) = 1/2 = 0.5
structure_intent: jaccard([multi_parallel], [cycle_interrelation, multi_parallel]) = 1/2 = 0.5

v3_score = 0.40 × 0.49 + 0.35 × 0.5 + 0.25 × 0.5 = 0.196 + 0.175 + 0.125 = 0.496
```

Frame 20 점수:
```
layout_compat_v2:
  family_match(3col-parallel, 3col-cards) → ?/card → 0
  relation_type_match(parallel, parallel) → 1 * 0.20 = 0.20
  cardinality_overlap(3, 3) → 1 * 0.15 = 0.15
  alt_patterns match (Frame 20 has 3col-parallel as alt conf 0.8): 0.20 * 0.8 = 0.16
  total ≈ 0.51

content_affinity: jaccard([goal_axes], [capability_requirements, tool_ecosystem]) = 0/3 = 0
structure_intent: jaccard([multi_parallel], [multi_parallel]) = 1

v3_score = 0.40 × 0.51 + 0.35 × 0 + 0.25 × 1 = 0.204 + 0 + 0.25 = 0.454
```

**결과**: Frame 12 (0.496) > Frame 20 (0.454) → V3 v2 가 올바른 1위 선택.

핵심: `content_affinity` jaccard 에서 Frame 12 (`goal_axes` 공유) 가 Frame 20 (공유 없음) 을 앞섬.

---

## 7. C.2-b 실행 계획 (AI 초안 생성 + 사용자 검토)

### 단계
1. AI 배치 스크립트 (`pipeline_12_generate_templates_v2.py`) — 32 프레임에 새 필드 생성
   - 입력: 기존 analysis.md + structure_ontology.yaml
   - 출력: `structure_ontology_v2.yaml` (draft) + 프레임별 신뢰도
2. 사용자 검토 우선순위 (사용자 지정):
   - **1순위**: Frame 12, 20, 29, 3, 11 (Holdout 실패 핵심)
   - **2순위**: 3col / cycle / table / process 계열
   - **3순위**: 나머지 일괄
3. 승인된 `structure_ontology_v2.yaml` 고정 → V3 매칭 로직 v2 재구현

---

## 8. 변경 이력

- **v2-draft-01** (초안): content_affinity 12개, structure_intent 8개, 가중치 0.40/0.35/0.25
- **v2-draft-02** (사용자 피드백 반영, 현재):
  1. content_affinity 12개 **유지** — `stakeholder_roles` ↔ `persona_benefit` / `policy_requirements` ↔ `capability_requirements` 경계 정의 §1-1 추가
  2. structure_intent **9개 로 확장** — `state_transition` 추가 (AS-IS ↔ TO-BE 용 별도 축)
  3. 가중치 0.40/0.35/0.25 **유지**. 추후 0.35/0.40/0.25 실험 여지 (content_affinity 비중 상향)
  4. Frame 29 예시 업데이트 — `state_transition` primary

## 9. 남은 결정 / C.2-b 로 진행 조건

C.2-b (AI 배치 라벨링) 진입 조건 **모두 충족**:
- [x] content_affinity enum 확정 (12개)
- [x] structure_intent enum 확정 (9개)
- [x] alternative_patterns 스키마 확정 (혼합 전략)
- [x] V3 매칭 공식 초기 가중치 확정 (0.40/0.35/0.25)
- [x] 우선 검토 프레임 5개 확정 (12, 20, 29, 3, 11)

→ C.2-b (32 프레임 AI 일괄 라벨링 초안 생성) 진행 가능.