comp-frame 검색과 대치
Rust 실행 기준

comp-frame은 사용자 내용이 기존 디자인의 어느 슬롯에 들어갈지 검색 단계에서 미리 계산한다. 2026-10-12 이후 검색·랭킹·중첩·Content Threading은 Rust 서버만 구현한다. 브라우저가 후보 DB를 직접 조회하고 TS 검색을 실행한다는 이전 설명은 현재 경로가 아니다. 2026-10-24 기준으로 화면은 서버가 매긴 결과 순서를 다시 섞지 않고 그대로 쓴다(PR #1541✓ merged).

코드 근거 · 문서 한 번 요청

코드 근거 · TS 검색 제거 기록

공개 ComponentSearchClient.search는 raw-text 또는 visual-summary를 받는다. 원문 경로는 생성·검색·병합·랭킹을 서버가 한 요청 안에서 끝낸다. entries에는 단일 후보와 여러 컴포넌트의 묶음 후보가 함께 들어올 수 있다.

제품은 별도 백엔드에서 받은 searchKey·활성 componentVersion을 전달하고, 디자인 문서(sheetJson)를 component.uuid로 받는다. 그다음 원본 RLSC(design_objects.structure_json)와 함께 buildReplacement({ component, sheetJson, rlsc })에 넣는다. rlsc는 어느 노드가 글자 노드(Text 또는 글자 든 도형)인지 가르는 데 쓰인다. 빼면 어느 노드도 자기 상자 폴백을 받지 못하므로 늘 넘긴다. 검색 통과 후에도 실제 렌더의 겹침·잘림·문장 의미를 확인해야 한다.

2026-10-17 이후 바뀐 계약이 셋 있다. ① 질의의 relations[].of가 가리키는 항목을 찾지 못하면 경고만 남기고 넘어가지 않는다. HTTP 422 unresolved_relation으로 요청 전체가 실패한다. unresolvedRelations는 deprecated이고 늘 빈 목록이다(PR #1543✓ merged·PR #1549✓ merged). ② buildReplacement 결과에 임시 문구로 채운 노드 id 목록 placeholderNodeIds가 붙는다(MOR-2845? 상태 확인 필요, PR #1545✓ merged). ③ 요청 옵션 pinned_do_id를 주면 응답 pinned에 그 design object의 결과와 상태(listed·added·not_found·no_l1)가 실린다. 서버가 지원하는지는 /v1/info의 features로 확인한다(PR #1559✓ merged). 클라이언트 패키지는 comp-frame-client 0.11.0이다.

코드 근거 · 제품 호출 흐름

코드 근거 · unresolvedRelations deprecated · pinned_do_id · PinnedWire

질의 Frame은 넣을 글을, 색인 Frame은 실제 노드 주소와 글 용량을 담는다. units는 항목, fields는 label·value·items 등의 슬롯, satellites는 공통 머리말, dataset은 표·차트 데이터다. aliases는 같은 물리적 칸의 다른 필드 이름이며 한 노드를 두 번 채우는 허가가 아니다.

현재 FRAME_VERSION = 5다. 적재 측 buildIisFrame은 IIS 구조 대응을 실제 노드와 연결하고, 만들 수 없으면 규칙 기반 Frame을 시도한다. 표 셀 지도와 표 기하도 색인에 들어간다. 규칙 기반 Frame도 이제 IIS 속성(properties)을 params에 싣는다(MOR-2683? 상태 확인 필요).

2026-10-19부터 슬롯 판정이 넓어졌다(MOR-2542? 상태 확인 필요, PR #1296✓ merged). 적재 Frame 빌더와 벤더 extractTextSlots는 isTextBearingNode로 Text와, content가 문자열인 SVG(글자 든 도형)를 함께 글자 슬롯으로 본다. 또 Frame의 관계는 문서의 Relation과 갈라져 FrameRelation이 됐다. of는 선택 필드라 색인 Frame에는 싣지 않고 질의 Frame만 읽는다. Frame 판 번호는 그대로 5다. Frame 스키마 버전, IIS 발행분, 제품 componentVersion, 서버 배포 버전을 혼동하지 않는다.

코드 근거 · packages/comp-frame-shared/src/frame.ts

코드 근거 · packages/comp-frame-index/src/frame/component-frame.ts

예: Timeline → Steps → Staircase → List. Steps의 행으로 갈아타지 않고 Timeline의 행을 끝까지 본다. 날짜 전용 필드를 못 읽는 도착지에서는 P3이 날짜를 items로 옮긴다. P2는 읽지 않는 params를 제거하고 P4/P5/P6은 데이터 형태를 바꾸며 P7은 관계의 설명을 옮긴다. 관계 전체의 의미가 언제나 무손실이라는 보장은 아니다. 2026-10-24 기준으로 P7이 설명을 붙일 관계 주인은 of를 모두 label로 읽어 찾고, 못 찾은 참조는 빼지 않고 422로 막는다(§1). 투영 함수 이름은 project_structure_keeping_content로 바뀌었다.

P8은 폐기됐다. 상한 15인 카테고리에 17항목을 억지로 접어 맞추지 않는다. 이후 align이 상세 문장을 한 슬롯에 합치는 일, 여러 장으로 나눠 담는 일은 별개의 처리다. 생성기가 처음부터 읽지 않는 필드에 내용을 쓰면 fallback P3이 자동 구제한다는 보장도 없다(B-33).

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/query_frame.rs

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/visual_summary/summary_projection.rs

후보는 서버 메모리 스냅샷에서 카테고리·중첩 카테고리·unit 수·dataset 종류·shape bits·용량 하한으로 먼저 좁힌다. Stage 0은 모양 비트가 같고, Stage 1·2는 각각 정확히 1·2비트 차이다. 20비트 가운데 앞 17개만 완화하며 dataset과 extraGrids는 하드 조건으로 남는다.

이것은 정확한 배치 일치나 최종 가독성 검사가 아니다. 제목 글자 수에 맞춘 사전 하한은 후보를 줄이는 근사 조건이고, 본문과 실제 줄바꿈·슬롯 대응은 후속 배정과 용량 검사가 본다. 과거 DB의 gc_passed 옵션은 현재 검색의 품질 통과와 같지 않으며 해당 컬럼 제거 마이그레이션이 존재한다.

shape bit: 어떤 칸이 「있는지」만 적은 20자리 지문

Frame 하나를 숫자 하나(u32)로 줄인 값이다. 질의 Frame에서도, 색인의 디자인 행에서도 같은 함수 compute_shape_bits로 계산한다. 각 자리는 「이 Frame 어딘가에 그 칸이 하나라도 있으면 1」이다. 몇 개 있는지, 글이 얼마나 긴지는 적지 않는다.

세 가지를 같이 기억한다. 첫째, marker는 14번째 필드지만 비트를 받지 않는다. 순번 글자는 내용이 아니라서다. 둘째, 비트 번호는 FIELD_ORDER 순서에 묶여 있어 필드 순서를 바꾸면 색인 전체의 비트가 달라진다. 코드가 「재배열 금지」로 못 박아 둔 이유다. 셋째, 항목이 2개인지 5개인지는 비트에 안 나타난다. unit 수는 따로 unit_count_min(질의 unit 수 이상)으로 거른다.

Stage 0·1·2: 허용할 비트 패턴의 목록

Stage는 점수가 아니라 「이 비트 값을 가진 행만 가져온다」는 허용 목록이다. 질의 비트를 qb라 하면 이렇게 만든다.

「뒤집는다」는 양쪽 방향이다. 후보 디자인에 질의에 없는 칸이 하나 더 있어도, 질의에 있는 칸이 하나 빠져 있어도 1비트 차이다. 그래서 Stage 1·2 후보는 빈 칸(blank)이 생기거나 질의 글을 받을 자리가 모자랄 수 있다. 그 결과를 쓸 수 있는지는 Stage가 정하지 않는다. 다음 절의 배정(align)과 용량 검사가 정하고, 내용 손실이 생기면 거기서 빠진다(§7).

비트 17–19는 아예 뒤집지 않는다. 게다가 필터는 dataset 종류를 따로 한 번 더 같은지 본다. 그래서 표 질의가 일반 목록 디자인으로, 수치 질의가 표 디자인으로 Stage를 타고 넘어가는 일은 없다. 이 절 제목의 「데이터 종류는 유지한다」가 이 뜻이다.

예시: 제목 + 항목 둘(이름·설명)

질의가 머리 제목 하나와, label·items를 가진 유닛 둘이라고 하자. 켜지는 비트는 0(label), 4(items), 14(title)이고 qb = 1 + 16 + 16384 = 16401이다.

Stage가 쓰이는 곳과 쓰이지 않는 곳

• 스캔 순서 — 카테고리마다 Stage 0 → 1 → 2 순서로 행을 읽는다. 카테고리 스캔 예산이나 승인 여유가 바닥나면 다음 Stage로 넘어가지 않는다. 첫 존재 tier는 승인 상한이 기본 0(무제한)이라 기본값에서는 Stage 2까지 전부 읽는다(§5).
• 예산 배분 — 카테고리별 스캔 예산은 Stage 0·1·2 패턴의 합집합으로 센 행 수에서 나온다. 첫 존재 tier는 그 수 그대로, 이후 tier는 배정량 ×4(CATEGORY_SCAN_MULTIPLIER)와 그 수 중 작은 쪽이다.
• 기록 — 행이 처음 후보 묶음에 들어온 Stage를 row_stage에 남긴다. include_explain을 켜면 결과마다 shape_bits_query·shape_bits_component·bit_diff(다른 비트의 이름, 예: satellites.desc)·stage가 붙는다. 다만 explain은 질의 비트를 다시 셀 때 extraGrids를 넣지 않으므로, 다중 격자 질의에서는 bit_diff에 extraGrids가 보일 수 있다.
• 순위에는 직접 쓰지 않는다 — rank.rs·cost.rs에 Stage 항목이 없다. Stage 1 후보가 Stage 0 후보보다 자동으로 뒤에 서지 않는다. 앞뒤는 §8의 잔여·tier·비용이 정한다.

이름이 비슷한 축과 섞지 않는다. Tier 1·2·3은 「어느 카테고리」, Stage 0·1·2는 「그 카테고리 안에서 어떤 모양까지」, N1~N5는 중첩 구조를 어디까지 포기하나(§6), 0군·1군은 사용자 지정 종류냐 추천이냐(§11)다. 나눠 담기 결과에 붙는 direct·threading·fallback 단계도 shape Stage와 상관이 없다.

코드 근거 · shape.rs · compute_shape_bits · shape.rs · SOFTENABLE_BIT_COUNT·shape_patterns · frame.rs · FIELD_ORDER

코드 근거 · filter.rs · matches · filter.rs · build_candidate_filter · filter.rs · shape_bits_for_stage

코드 근거 · comp-frame-pool search.rs · scan_category · union_filter_for_allocation · comp-pass-logic search.rs · explain의 비트 이름

코드 근거 · packages/comp-frame-index/sql/2026-09-22-drop-gc-passed.sql

9월 판의 “모든 카테고리는 목표 수 ×4까지만 스캔” 설명은 바뀌었다. 현재 첫 번째로 존재하는 tier는 하드 필터 통과 행을 전부 검사하고, 승인 후보 전체에서 순위를 매긴다. tier1_max_candidates=0은 무제한이다. 원래 tier 1이 비면 tier 2가 이 첫 tier 취급을 받을 수 있다.

행을 읽은 수, 배정·용량 검사를 통과한 수, fingerprint 중복 제거 후 반환 수는 서로 다르다. 통과 수가 0이면 다음 공급을 볼 수 있지만, 통과 행이 같은 Frame으로 중복되면 최종 카드 수가 적을 수 있다. 최신 메타의 tier1_fetched_rows·tier1_exhausted로 첫 tier를 어디까지 읽었는지도 확인한다. tier 하나를 다 훑을 때마다 누적 승인 수를 tier_targets와 비교하므로, 첫 tier에서 50건 넘게 승인되면 tier 2는 보지 않는다.

D.O. 지정 검색(PR #1559✓ merged)은 같은 tier·stage·승인·순위 규칙을 쓰되, 각 (카테고리, stage)에서 읽은 행 가운데 그 design object의 행만 남긴다. 반환 상한은 요청의 top_n을 그대로 쓴다. 결과가 비면 pinned.not_found에 읽은 행 수와 배제 사유별 수가 실린다.

코드 근거 · rust/comp-pass/crates/comp-frame-pool/src/search.rs · only_do_id · document_search.rs · D.O. 지정

코드 근거 · packages/comp-frame-shared/search-defaults/options.json

현재 구현은 Rust nested_search.rs다. N1 결과가 있으면 반환하는 실제 분기가 있다. 위키 D-7의 과거 이종중첩 공급 제외를 근거로 최신 풀의 N1이 “언제나 0”이라고 쓰지 않는다. N2의 조합 수, 검색 대상 풀, 성공 여부를 따로 확인한다. 부모 내용·관계 설명의 보존과 형제 순서도 함께 검사해야 한다.

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/nested_search.rs

align은 질의 슬롯과 디자인 슬롯을 맞추어 binding·blank·preserve·내용 손실을 만든다. 랭커는 이 배정을 비용 계산보다 먼저 실행한다. content_loss > 0 후보는 제외한다. 내용이 남았다는 계산만으로 원문 의미 전체가 보존됐다고 보장하지는 않으므로 원본 → projection → Frame → binding을 추적한다.

표는 별도 조건이 있다. native 표의 확장이 공간 예산을 넘으면 검색에서 제외하고, 측정할 기하가 없는 표는 tableUnmeasured로 낮춘다. 글상자 표는 dataset.cells의 IIS 셀 지도에 맞춰 셀별로 배정할 수 있다. matrix라는 이유만으로 모든 후보를 native Chart로 취급하지 않는다.

셀 지도의 칸 판정도 바뀌었다(MOR-2673? 상태 확인 필요, PR #1452✓ merged). 예전에는 칸이 TextItem이어야 했지만 지금은 RLSC 글자 노드면 된다. 대치가 글을 넣지 못하는 도형(ShapeItem, RLSC가 글자 노드로 모르는 ESI)만 거절한다.

MOR-2683? 상태 확인 필요(PR #1497✓ merged)으로 ListingTable 표 처리가 셋 더해졌다. 머리글 칸 줄이 없는 셀 지도에 ListingTable을 넣으면 열 제목을 버리고 데이터를 첫 행부터 넣는다. IIS 속성 params.header == false인 TableItem 표도 열 제목을 버린다(grid_drops_column_labels). 나눠 담기 탐색에서만 켜는 cell_map_probe는 셀 지도의 행 부족·빈 칸으로 후보를 빼지 않고 내용 손실 1로 매긴다. 열 부족은 여전히 뺀다.

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/align.rs

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/rank.rs

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/table_fit.rs

코드 근거 · packages/comp-frame-index/src/frame/cellMapFrame.ts · grid_drops_column_labels · cell_map_probe

기본 rank_mode=tier_pool·clean_first=above_tier에서는 사용자 내용이 아닌 잔여가 0인지 → tier → fallback 순서 → 꾸밈 선호 → 비용 → 단독 태그와 나머지 동점 규칙 순으로 비교한다. 조회된 tier 2의 온전한 후보가 tier 1의 잔여 있는 후보보다 앞설 수 있다. 조회하지 않은 후보를 정렬이 찾아 주지는 않는다.

같은 fingerprint 묶음에서는 잔여 0인 후보를 대표로 바꾸고 다시 정렬한다. unauthored_count는 임시 문구 대상 등을 세는 구현 지표다. Marker·비내용 역할(2026-10-23부터 Background 포함)·구조 토큰처럼 원문 보존이 정당한 노드는 잔여 비용과 이 계수에서 빠진다. 사람의 의미 평가를 대체하는 완성도 점수는 아니다.

기본 가중치 정본에는 비용 키 23개와 threading 전용 가중치 2개가 있다. 초기값과 과거 튜닝 이력이 섞여 있으므로 값의 크기나 합계만으로 다른 알고리즘보다 우수하다고 말하지 않는다.

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/rank.rs

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/rank.rs

코드 근거 · packages/comp-frame-shared/search-defaults/weights.json

현재 화면과 제품 SDK는 공유 buildNodeTextMap을 쓴다. 순서는 binding → blank → preserve → 안쪽 잔여 → 바깥 잔여 → 제목 구제다. 이미 사용자 글을 받은 노드를 뒤 단계가 덮지 않는다.

문서 제목이 안쪽 title binding에 없으면 바깥 Title 후보를 우선해 한 곳을 고른다. Title이 없을 때도 Marker·비내용 역할은 후보에서 제외한다. 선택되지 않은 공통 부제·설명은 일반 글이면 임시 문구가 된다. Background(워터마크처럼 배경에 깔린 글자)는 2026-10-23에 비내용 역할로 옮겨져 슬롯·벌점·제목 후보에서 모두 빠지고 원문으로 남는다(MOR-2753? 상태 확인 필요, PR #1551✓ merged). 상세 대조와 실제 정책으로 다시 계산한 예시는 역할별 텍스트 대치에 있다.

코드 근거 · packages/comp-frame-shared/src/nodeTextPolicy.ts · buildNodeTextMap · ELEMENT_ROLE_KINDS

이전 판은 TS 검색에서 F01~F09를 합성 재현하고 핵심 테스트 470개를 기록했다. 그 결과는 당시 커밋의 검증이다. 이후 Rust 이전, 첫 tier 전량 스캔, 정렬 비교, 내용 보존과 대치 정책 변경이 들어왔으므로 동일한 번호를 최신 결함으로 재선언하지 않는다.

현재 의심을 재현하려면 최신 Rust 함수와 같은 입력·풀·옵션을 고정하고 실행해야 한다. 이번 문서 갱신은 과거 테스트 수를 새로운 실행 결과로 재표시하지 않는다.

나눠 담기는 두 경로다. 유닛(카드) 경로의 프로파일은 List·Steps·QnACard·TableOfContents이고, ListingTable은 프로파일 없이 표 경로로 간다(MOR-2683? 상태 확인 필요, PR #1497✓ merged). 서버가 직접 배치 → 탐색용 질의 → 여러 장 계획 → 장별 검사·재정렬을 한다. 상위 binding은 첫 장이며 다음 장은 장별 데이터로 바꿔 그린다. 기본 장수 상한은 64다.

표 경로는 행을 쪼개지 않는다. 셀 지도 표는 데이터 칸의 행 수만큼, TableItem 표는 표 예산 안에 드는 만큼 한 장에 담는다. 장마다 담은 데이터 행 구간 rows가 응답에 실린다(PR #1539✓ merged). 표 밖에 entity나 중첩 컴포넌트가 같이 있는 질의는 표 경로로 받지 않는다(PR #1533✓ merged). 유닛 경로에서는 계획한 본문 하나라도 bullet이 붙으면 모든 본문에 bullet을 붙여 다시 계획한다(MOR-2623? 상태 확인 필요, PR #1538✓ merged).

threading 및 original_size_verified 결과는 원본 크기를 기준으로 배치한다. 제목 구제는 유지되며, 임시 문구는 원래 셀의 용량과 요청에서 쓴 언어별 문구 표를 기준으로 고른다. 검색 때와 렌더 때 다른 문구 표를 쓰면 맞음 보장이 깨진다.

사용자가 generationTypes를 지정한 경우는 별도 0군·1군 검색이다. 지정 종류의 0군을 tier1_only로 먼저 찾고 부족할 때 추천 1군을 찾는다. 이 군 번호는 Tier 1~3이나 Stage 0~2가 아니다. 나눠 담은 결과의 재정렬은 이제 서버가 군마다 하고, 0군 뒤에 1군을 붙인다. 화면은 그 순서를 그대로 쓴다(PR #1541✓ merged).

코드 근거 · rust/comp-pass/crates/comp-frame-core/src/threading/profile.rs · ThreadingKind

코드 근거 · rust/comp-pass/crates/comp-pass-logic/src/threading_search.rs

코드 근거 · src/comp-frame/useUnifiedSearch.ts

iui.comp_frames의 한 행은 디자인 전체가 아니라 IIS 경계 노드 하나를 나타낼 수 있다. 검색용 컬럼은 Frame에서 파생한 카테고리·모양·용량·버전 등이며, Rust 서버는 추출한 스냅샷을 읽는다. frame_version=5와 제품 버전 3.0, 내부 발행분 2.6 같은 이름은 같은 축이 아니다.

2026-10-02 제공된 DB 측정(재측정하지 않음): 전체 226,952행, 발행분 2.5의 113,614행·96,538 DO, 도형 속 글자 8,418개·3,357 DO라는 숫자는 당시 기록이다. 지금의 행 수·커버리지나 최신 적재 완료를 뜻하지 않는다.

지난 판의 「iui는 Text 기준」은 더 이상 맞지 않다. 2026-10-19 PR #1296✓ merged(MOR-2542? 상태 확인 필요)로 iui의 벤더 extractTextSlots와 적재 Frame 빌더도 aippt와 같은 isTextBearingNode를 쓴다. Text이거나 content가 문자열인 SVG면 글자 슬롯이다. SVG는 content가 있는지만 보므로, 대치로 글이 ''가 된 도형도 슬롯으로 남는다. 같은 판정이 aippt 원본, iui 사본, 용량 워커 세 곳에 있다.

코드 규칙이 바뀐 것과 운영 색인이 바뀐 것은 다르다. 서버가 지금 읽는 스냅샷이 이 판정으로 다시 적재됐는지는 저장소에서 확인하지 못했다. 따라서 「코드에서 도형 글자 대응」을 「운영 검색의 모든 슬롯에 반영 완료」로 넓혀 읽지 않는다.

코드 근거 · packages/comp-frame-shared/src/eregion/visual-summary/rlsc.ts · classifyFieldNode

aippt SVG 판정

코드 근거 · packages/comp-frame-index/src/frame/component-frame.ts

갱신 2026-10-26 · 문서 v1.1.0. iui는 origin/main 04585231b2339f034f3e89b5f94524591c372b02(2026-10-24, PR #1559✓ merged 머지)의 고정 파일을 읽었다. 직전 판의 iui bcd1d0218766cbba3a174d1819ab218d613e626f 이후 607커밋이 쌓였고, 직전 판이 인용한 iui 경로 22개 가운데 19개가 바뀌었다. 바뀐 파일은 diff로 하나씩 대조했고, 리팩터링만 있던 곳은 줄 번호만 옮겼다. wiki a0f8b01961db9396206b1ddf097c66cb44bde137와 aippt e6ffa4bdf65ec76f3d3031dc566f3fc7c19eade1는 이번에 다시 읽지 않았고 직전 판 고정 커밋 그대로다. iui 코드 줄 링크는 모두 위 고정 커밋의 git show로 확인했다. 로컬 브랜치나 미커밋 변경을 구현 완료로 포함하지 않았다.

위키 spec·design·reference는 9월 학습판 이후 변경이 없지만 실행 구현은 크게 달라졌다. 규약의 alternatives·P8·중첩 정책과 코드의 실제 동작을 분리했다. 이번 작업에서 운영 DB·서비스 배포·실제 렌더 품질이나 전수 회귀 테스트를 새로 측정한 것은 아니다.

전체 개념 수업과 50문항은 학습 페이지, 생성 원본과 고정 코드 지도는 강의자료에 있다. 이전 판의 상세 F01~F09·실험 수치는 보관본에서 당시 근거로 읽는다.