diff --git a/docs/architecture/IMP-04-FRAME-SUITABILITY-MATRIX.md b/docs/architecture/IMP-04-FRAME-SUITABILITY-MATRIX.md new file mode 100644 index 0000000..bfb1038 --- /dev/null +++ b/docs/architecture/IMP-04-FRAME-SUITABILITY-MATRIX.md @@ -0,0 +1,227 @@ +# IMP-04 Frame Suitability Matrix (32 frames) + +> Phase Z runtime catalog 확장 (IMP-04) 의 per-frame 진단 + Phase Z mapping +> proposal. Codex #15337 + #15340 의 추천 *32-frame schema suitability matrix* +> 답. impl 전 prerequisite 자료. +> +> **본 matrix scope** : Phase Z runtime catalog (executable projection) 으로의 +> mapping. *matching schema canonical decision* (Codex #15340 의 architectural +> question) 은 별 axis (IMP-05+) 이양 — 본 doc 에 포함 X. +> +> Source-of-truth : +> - V4 evidence : `tests/matching/v4_full32_result.yaml` (32 unique template_ids, +> 320 judgments) +> - per-frame analysis : `figma_to_html_agent/blocks/{frame_id}/analysis.md` +> - per-frame visual : `figma_to_html_agent/blocks/{frame_id}/{index.html,flat.md,assets/}` +> +> Generated : 2026-05-13 / scope-lock = Gitea #4 round 6 (32 frame all-in, +> remaining 28). + +--- + +## §1. 요약 통계 + +| axis | count | +|---|---| +| V4 32 unique templates | 32 | +| Active (이미 Phase Z 등록) | 4 | +| Remaining (본 issue 작업 대상) | 28 | +| `analysis.md` 보유 | 32/32 | +| `texts.md` 보유 | 32/32 | +| `index.html` 보유 (visual base) | 20/32 — **12 missing** | +| `flat.md` 보유 | 21/32 — 11 missing | +| `assets/` 디렉토리 보유 | 20/32 | + +**Decision 분류** (본 matrix 결과) : + +- **ACTIVE** (4) — 이미 Phase Z catalog 활성 +- **reusable-now** (16) — `index.html` 보유 → Track A visual activation 가능 +- **visual-pending** (12) — `index.html` 부재 → Track B (별도 처리 필요) + +**Family 분포** : + +| family | count | examples | +|---|---|---| +| cards | 12 | persona-3col, cards-3-category, paired-rows-2x2, quadrant-4, ... | +| table | 5 | table-2col, table-3col, compare-rows, ... | +| compare | 4 | 2col-paired-list, central-split-synthesis, banner-top-2col-bottom, cards-3-compare | +| diagram | 5 | cycle-3way-intersection, quadrilateral-relations, radial-diagram-5, ... | +| list | 3 | list-numbered-4, list-stacked-vertical, 3-column | +| map | 1 | full-page-map-banner | +| composite | 1 | central-5-goals | +| compare (별 grouping) | rest | + +**Cardinality 분포** (ideal) : + +| ideal | count | comment | +|---|---|---| +| 2 | 5 | compare-2-way (table-2col, banner-top-2col-bottom, etc.) | +| 3 | 11 | cards-3col, cards-3-category, list-3-column, persona-3col, ... | +| 4 | 8 | quadrant-4, paired-rows-2x2, cards-4-grid, ... | +| 5 | 3 | radial-5, central-5-goals, list-stacked-5 | +| 6 | 1 | circular-nodes-6 | +| 1 | 1 | full-page-map-banner | + +--- + +## §2. ACTIVE 4 frames (이미 Phase Z 등록) + +| template_id | frame_id | fn | family / layout | builder | partial | +|---|---|---|---|---|---| +| `three_parallel_requirements` | 1171281190 | 13 | list / 3-column | `items_with_role` + `pillar_item` | `f13b` (157 lines) | +| `process_product_two_way` | 1171281210 | 29 | compare / banner-top-2col-bottom | `process_product_pair` | `f29b` (294 lines) | +| `bim_issues_quadrant_four` | 1171281193 | 16 | cards / quadrant-4 | `quadrant_flat_slots` + `quadrant_item` | `f16b` (223 lines) | +| `three_persona_benefits` | 1171281191 | 14 | cards / persona-3col | `items_with_role` + `quadrant_item` | `f14b` (110 lines, **refinement 필요** — index.html base 안 씀) | + +--- + +## §3. Remaining 28 frames — Phase Z mapping matrix + +각 frame 의 : +- **figma_to_html 자원 status** (`A`=analysis.md, `T`=texts.md, `I`=index.html, `F`=flat.md, `S`=assets/) — `-` = 부재 +- **V4 신호** (use_as_is/light_edit/restructure/reject) +- **Phase Z mapping proposal** (source_shape, builder) +- **decision** (reusable-now / visual-pending) + +### §3.1 reusable-now (16 frames — `index.html` 보유) + +| template_id | fid | fn | family / layout | card (ideal) | slots | V4 (UAI/LE/RS/RJ) | proposed source_shape | proposed builder | decision | +|---|---|---|---|---|---|---|---|---|---| +| `app_sw_package_vs_solution` | 1171281203 | 23 | table / table-2col | 2 | 4 | 0/0/1/9 | top_bullets | new (compare_table_2col) | reusable-now | +| `bigroom_system_components` | 1171281178 | 7 | compare / 2col-paired-list | 2 | 5 | 0/0/0/10 | top_bullets | `process_product_pair` (재사용?) or new | reusable-now | +| `bim_adoption_central_split` | 1171281208 | 27 | compare / central-split-synthesis | 2 | 5 | 0/0/2/8 | top_bullets | new (split-synthesis) | reusable-now | +| `bim_current_problems_paired` | 1171281194 | 17 | cards / paired-rows-2x2 | 4 | 9 | 0/0/1/9 | top_bullets | `quadrant_flat_slots` 변형 or new | reusable-now | +| `bim_dx_comparison_table` | 1171281195 | 18 | table / compare-rows | 2 | 4 | **1**/0/0/9 | top_bullets | new (compare_table_2col) | reusable-now | +| `construction_bim_three_usage` | 1171281182 | 11 | cards / cards-3-category | 3 | 7 | **1**/0/1/8 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now | +| `construction_goals_three_circle_intersection` | 1171281189 | 12 | diagram / cycle-3way-intersection | 3 | 5 | **1**/**1**/1/7 | top_bullets | new (cycle-intersect-3) | reusable-now | +| `dx_sw_necessity_three_perspectives` | 1171281198 | 20 | cards / cards-3-header | 3 | 7 | 0/**2**/1/7 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now | +| `engn_sw_three_types` | 1171281204 | 24 | table / table-3col | 3 | 5 | 0/**1**/0/9 | h3_subsections | new (compare_table_3col) | reusable-now | +| `info_management_what_how_when` | 1171281179 | 8 | cards / 3-section-framework | 3 | 7 | 0/0/0/10 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now | +| `model_specialized_engn_sw` | 1171281202 | 22 | diagram / split-panel-numbered | 3-4 | 5 | 0/0/1/9 | top_bullets | new (split-panel) | reusable-now | +| `overseas_bim_numbered_list` | 1171281174 | 3 | list / list-numbered-4 | 4 | 5 | 0/0/0/10 | top_bullets | `items_with_role` 변형 (numbered) | reusable-now | +| `pre_construction_model_info_stacked` | 1171281180 | 9 | list / list-stacked-vertical | 5 (min 4 max 6) | 3 | 0/0/0/10 | top_bullets | `items_with_role` (재사용, flexible card) | reusable-now | +| `solution_engn_split_diagram` | 1171281201 | 21 | diagram / split-panel-diagram | 4 (min 3 max 5) | 4 | 0/0/3/7 | top_bullets | new (split-panel) | reusable-now | +| `sw_development_cycle_six_nodes` | 1171281172 | 1 | diagram / circular-nodes-6 | 6 | 7 | 0/0/0/10 | top_bullets | new (circular-6) | reusable-now | +| `sw_reality_three_emphasis` | 1171281209 | 28 | cards / title-plus-3-emphasis | 3 | 7 | 0/0/0/10 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now | + +### §3.2 visual-pending (12 frames — `index.html` 부재) + +| template_id | fid | fn | family / layout | card (ideal) | slots | V4 (UAI/LE/RS/RJ) | resource status | decision | +|---|---|---|---|---|---|---|---|---| +| `commercial_sw_four_categories` | 1171281205 | 25 | cards / left-categories-right-logos | 4 | 6 | 0/0/0/10 | A T - - - | visual-pending | +| `compensation_complaint_map` | 1171281177 | 6 | map / full-page-map-banner | 1 | 2 | 0/0/0/10 | A T - - - | visual-pending | +| `compensation_complaint_side_card` | 1171281176 | 5 | cards / side-card-with-list | 3 (min 3 max 5) | 4 | 0/0/0/10 | A T - - - | visual-pending | +| `design_method_distortion_three_col` | 1171281197 | 19 | compare / cards-3-compare | 3 | 7 | 0/0/0/10 | A T - - - | visual-pending | +| `domestic_bim_actor_relations` | 1171281175 | 4 | diagram / quadrilateral-relations | 4 | 6 | 0/0/1/9 | A T - - - | visual-pending | +| `engn_sw_development_domain_knowledge` | 1171281173 | 2 | cards / bullet-cards-4-plus-center | 4 | 7 | 0/0/0/10 | A T - - - | visual-pending | +| `field_effectiveness_five_elements` | 1171281181 | 10 | diagram / radial-diagram-5 | 5 | 6 | 0/0/0/10 | A T - - - | visual-pending | +| `industry_characteristics_three_col` | 1171281212 | 31 | table / table-3col | 3 | 5 | 0/0/0/10 | A T - - - | visual-pending | +| `industry_current_status_three_col` | 1171281211 | 30 | table / table-3col | 3 | 5 | 0/0/0/10 | A T - - - | visual-pending | +| `policy_achievement_five_goals` | 1171281213 | 32 | composite / central-5-goals | 5 | 9 | 0/0/0/10 | A T - - - | visual-pending | +| `policy_goals_plus_execution_requirements` | 1171281192 | 15 | cards / policy-4card-plus-list | 4 | 10 | 0/0/0/10 | A T - - - | visual-pending | +| `sw_dependency_four_problems` | 1171281206 | 26 | cards / cards-4-grid | 4 | 9 | 0/**1**/1/8 | A T - F - | visual-pending (index 부재, flat 있음) | + +--- + +## §4. Track 분리 (matrix 기반) + +### Track A — Visual activation (16 reusable-now + 1 active refinement) + +priority 진행 순서 (자체 추천 — V4 신호 ↑ 순서) : + +1. **`three_persona_benefits` refinement** (active 1, V4 use_as_is=1) — index.html base 재작성 +2. `dx_sw_necessity_three_perspectives` (LE=2 가장 높음, persona builder 재사용 가능) +3. `construction_goals_three_circle_intersection` (UAI=1+LE=1+RS=1, V4 신호 강함, 단 새 builder 필요 — cycle-intersect) +4. `construction_bim_three_usage` (UAI=1, persona builder 재사용) +5. `bim_dx_comparison_table` (UAI=1, 새 builder — compare_table_2col) +6. 잔여 11 reusable-now (V4 신호 0 — 단순 catalog 확보 목적, 진행 순서 임의) + +### Track B — visual-pending 12 frames + +option (a/b/c) 결정 필요 (user 확인) : + +- **(a)** figma_to_html agent 재실행 → 별 issue (IMP-04b "visual extraction") +- **(b)** analysis.md + texts.md 만으로 minimal CSS partial 작성 (시각 디테일 손실 인정) +- **(c)** 본 issue scope 외 — IMP-04b 로 분리, 본 issue 는 16 frame 만 활성 + +자체 추천 = **(c)** — 본 issue 는 *visual base 있는 frame* 만 활성. 12 missing 은 별 axis. scope 명확 + 진행 속도 ↑. + +### Track C — Matching schema canonical decision (Codex #15340) + +본 matrix scope 외. IMP-05 또는 별 architectural axis 로 이양. 본 doc 에 권장 사항 surface 만 : + +- figma_to_html / matching metadata = canonical matching knowledge source +- Phase Z frame_contracts + partial builders = runtime executable projection +- bridge/mapping layer = explicit conversion + +--- + +## §5. Builder 재사용 vs 새 builder 분석 + +### §5.1 기존 4 builder + +- `items_with_role` (F13) — array of items with `role_order` mapping. `pillar_item` parser uses sub-sections. +- `process_product_pair` (F29) — 2 named columns with sections, `column_with_transform` + `column_plain` parsers. +- `quadrant_flat_slots` (F16) — flat keyed positional slots (`quadrant_N_label` / `quadrant_N_body`). +- `quadrant_item` parser — `{label, body:[{text,indent}]}` flat list. + +### §5.2 재사용 가능 (Track A 안 builder 재사용 candidates) + +| pattern | example frames | builder | parser | +|---|---|---|---| +| 3 cards parallel (단순 label + body) | persona, dx_sw_necessity, construction_bim_usage, info_mgmt, sw_reality | `items_with_role` | `quadrant_item` (재사용) | +| 4 quadrant flat | bim_current_problems (4 grid), sw_dependency (4 grid — visual-pending) | `quadrant_flat_slots` 변형 (4-card grid) | `quadrant_item` (재사용) | +| numbered list (1..N) | overseas_bim, pre_construction_model_info | `items_with_role` (no role) | `pillar_item` 또는 new | + +### §5.3 새 builder 필요 + +| pattern | example frames | proposed builder | +|---|---|---| +| 2-col compare table | app_sw_package_vs_solution, bim_dx_comparison_table | `compare_table_2col` | +| 3-col compare table | engn_sw_three_types (+ visual-pending: industry_*) | `compare_table_3col` | +| cycle/circle diagram | construction_goals_three_circle_intersection | `cycle_intersect_3` | +| split-panel diagram | model_specialized_engn_sw, solution_engn_split | `split_panel` | +| circular nodes | sw_development_cycle_six_nodes | `circular_nodes_n` | +| paired 2x2 | bim_current_problems_paired | `paired_rows_2x2` | +| central split synthesis | bim_adoption_central_split | `central_split_synthesis` | + +→ **새 builder 7+ 필요** (Track A 안). 일부 generic 화 가능성 — *implementation 시 구체화*. + +--- + +## §6. min_height_px derivation method + +기존 catalog : F13=230, F29=345, F16 = (no visual_hints — default zone size 사용?) + +본 matrix 의 frame 별 `min_height_px` 추정 method : + +- `figma_to_html_agent/blocks/{frame_id}/flat.md` 의 *frame 원본 height* × Phase Z slide-body scale = derived min height +- 예 : persona frame_id 1171281191 = 1927 px × (1280/2601) = 1927 × 0.49213 = 949 px (그러나 Phase Z slide-body 는 585 px 한계 — zoom 또는 scale 추가 적용 필요) +- 실제 measurement = impl 시 partial render 후 검증 (smoke harness 가 char count 측정) + +→ 각 frame impl 시 *index.html 의 R19 zoom 값* 또는 *flat.md 의 frame 원본 height* 에서 derive. handoff #15321 §4 의 8-step 의 1 단계로 추가. + +--- + +## §7. Resource completeness summary + +| status | count | template_ids | +|---|---|---| +| Full (A+T+I+F+S) | 19 | (16 reusable-now 중 15 + active 4 중 4) | +| index 있음, assets 없음 | 1 | `three_parallel_requirements` (F13 active) | +| A+T+F (index 부재) | 1 | `sw_dependency_four_problems` (visual-pending, flat 만 있음) | +| A+T (visual 모두 부재) | 11 | 위 §3.2 의 나머지 11 visual-pending | + +→ visual-pending 12 frame 중 1 (`sw_dependency_four_problems`) 은 *flat.md 보유* — 약간 head-start. 나머지 11 은 figma_to_html agent 재실행 필요. + +--- + +## §8. 다음 단계 — user 확인 후 ㄱ + +1. 본 matrix 가 *prerequisite 자료* 로 충분한가? 추가 추출 필요 정보? +2. Track B option (a/b/c) 합의 — 자체 추천 = (c) 본 issue 외 분리 +3. Track A 진행 순서 — §4.1 의 priority list 합의? +4. Track C (matching schema canonical) IMP-05+ 분리 합의? +5. impl 시 build 순서 — frame 별 sequential commits + Codex per-frame review 또는 batch review? + +100% 합의 후 step 6 (Track A 진입 — `three_persona_benefits` refinement 부터) 시작.