시스템 아키텍처 16분 제이앤코어 기술연구소

폴더를 통째로 다른 드라이브에 복사해도 색인과 맥락이 유지되는 이유: 윈도우 업무용 파일 정리기 아키텍처 구축기 ③ — 추출·색인·랭킹 경계 분리와 이식형 자료실(Portable Workspace) 엔진

단순 파일 정리기에서 출발한 시스템이 실무 검색 병목을 해결하며 추출·색인·랭킹 3단 버전 경계 분리, 다중 채널 교차 병합(search_fusion), 선행 상태 기록(Write-Ahead Pending) 사용자 맥락 동기화, 그리고 4단계 해시 재앵커링(workspace_identity) 기반 이식형 자료실로 진화한 아키텍처 기록입니다.

시리즈 구성 — 윈도우 업무용 파일 정리 및 이식형 자료실 아키텍처 구축기 (총 3부작)


**1부**의 비파괴 파일 트랜잭션 엔진과 **2부**의 복합 문서 구조적 근거 추출 파이프라인을 완성했을 때, 우리의 1차 목표였던 “안전하고 근거 있는 로컬 파일 정리기”는 이미 작동하고 있었습니다.

그러나 완성된 정리 엔진을 실제 업무 파일 세트에 적용하며 시스템을 고도화하는 과정에서, 우리는 파일 정리만으로는 결코 해결되지 않는 구조적 병목과 마주했습니다.

아무리 파일 이름을 기본이름_저장일_부모폴더명.ext 규칙으로 정교하게 다듬고 폴더 트리를 깔끔하게 분류해 두어도, 단일 트리 계층(Hierarchical Directory Tree)과 파일명 길이 제한이라는 운영체제 파일시스템의 물리적 한계 때문에 문서가 가진 다차원적 업무 맥락을 모두 표현할 수 없었기 때문입니다.

6개월 뒤 실무자가 파일을 다시 찾을 때 떠올리는 단서는 정확한 파일명이 아닙니다.

  • “일주일 전쯤 회의에서 자재 납기 지연 문제로 검토했던 문서”
  • “컴퓨터 조립 견적서 이미지나 문서”
  • “문서 본문에는 안 적혀 있지만, 내가 따로 메모해 둔 ‘현장 소장님 구두 승인 보류 건’”

더 나아가 실무 환경에서는 작업 폴더 전체를 외장 스토리지에 백업하거나 다른 PC의 다른 드라이브(D:\업무자료 → C:\프로젝트_이관)로 통째로 복사해 이동하는 일이 일상적으로 일어납니다. 만약 검색 색인과 사용자가 입력한 맥락 메모가 특정 PC의 절대 경로(D:\...)에 종속되어 있다면, 폴더를 옮기는 순간 수백 건의 맥락 데이터와 색인은 모두 끊어진 고아 레코드가 됩니다.

본 3부에서는 파일 정리기에서 출발한 시스템이 이 문제들을 정면으로 돌파하는 과정에서 어떻게 3단 버전 경계 분리 아키텍처, 하이브리드 어휘-맥락 랭킹 및 다중 채널 병합 엔진, 프로세스 중단 내성(Crash-Resilient) 사용자 맥락 동기화, 그리고 **4단계 해시 재앵커링 기반의 이식형 자료실(PortableSemanticStore)**까지 완성하게 되었는지 그 엔지니어링 진화 과정을 상세히 다룹니다.


1. 초기 검색 프로토타입의 한계와 실패 재현 (SEARCH01 → SEARCH03)

문서 정리 과정에서 이미 확보된 본문 추출 조각(Fragments)과 파일 메타데이터를 활용해 첫 번째 맥락 검색 프로토타입(SEARCH01)을 구축했을 때, 초기 파이프라인은 다음과 같은 단순 벡터 거리 정렬 방식이었습니다.

  1. 문서 본문을 일정 길이 조각으로 분할하고 파일명·경로·생성일 문자열을 앞에 붙여 단일 고차원 벡터 공간에 매핑한다.
  2. 사용자의 검색 질의와 코사인 유사도(Cosine Similarity)가 높은 순서대로 모든 파일을 정렬해 반환한다.

그러나 실제 HTTP 통합 환경에서 다양한 실무 질의를 투입해 대조 실험(http-reproduction.json)을 수행하자, 이 단순한 구조에서 세 가지 치명적인 결함이 즉시 드러났습니다.

1.1 결함 ①: 밀집 벡터 공간의 고점 집중 현상과 무관 문서 유출

밀집 임베딩(Dense Embedding) 공간에서는 전혀 무관한 주제의 질의와 문서 사이라도 원시 코사인 유사도가 0.70~0.80 구간에 밀집하는 특성(Anisotropy)이 존재합니다. 그 결과 작업 폴더 안에 ‘배관 자재 단가표’와 ‘설비 설치 안내서’만 들어 있는 상태에서 사용자가 전혀 관계없는 "보디빌딩 대회 일정"이나 "화성 탐사 계획"을 검색해도, 코사인 거리가 상대적으로 가장 가까운 배관 자재 문서가 1순위 결과로 반환되었습니다. 또한 파일명과 경로 문자열까지 본문 조각과 함께 벡터화했기 때문에, 반환된 점수가 본문 내용의 일치 때문인지 단순 경로 문자열 때문인지 분별할 수 없었습니다.

1.2 결함 ②: 짧은 핵심 키워드 질의("견적", "납품 일정")의 맥락 희석

실무자는 긴 자연어 문장뿐 아니라 "견적", "배관", "납품 일정"처럼 1~3단어로 구성된 짧은 핵심어 검색을 훨씬 더 자주 수행합니다. 그러나 문맥 중심 대조 모델에만 의존하자, 본문이나 파일명에 해당 단어가 글자 그대로 포함되어 있음에도 전체 문단 맥락 점수가 낮게 산출되어 정작 찾으려는 문서가 하위권(예: "견적" 단독 검색 시 17위)으로 밀려나거나 필터링에서 탈락하는 회귀(Regression)가 발생했습니다.

1.3 결함 ③: 추출·임베딩·랭킹의 강결합으로 인한 재색인 비용 폭발

초기에는 추출 로직, 벡터 인코딩, 랭킹 점수 계산식이 하나의 파이프라인 버전으로 묶여 있었습니다. 이 구조에서는 검색 결과의 정렬 가중치나 임계값을 단 한 줄만 수정해도 기존 저장된 수천 개 문서 조각의 버전이 무효화(Invalidated)되어, 모든 문서와 미디어를 처음부터 다시 추출하고 벡터를 재계산해야 했습니다.


2. 추출(ContentResult) · 색인(VectorVersion) · 랭킹(MatchingContract)의 3단 경계 분리

위 세 번째 결함을 근본적으로 제거하기 위해, 마일스톤 SEARCH04에서 우리는 문서에서 텍스트를 읽어내는 층(Extraction), 텍스트를 벡터로 변환해 저장하는 층(Indexing), 그리고 **질의와 문서를 대조해 순위를 매기고 화면에 표현하는 층(Ranking & Presentation)**의 버전 의존성 경계를 완전히 해체하여 재설계했습니다.

┌─────────────────────────────────────────────────────────────────────────┐
│ [Layer 1] 공통 추출 경계 (ContentExtractor & Format Adapters)            │
│  - 출력 계약: ContentResult(text, status, reason, coverage,             │
│               fingerprint, truncated, fragments, omissions)             │
│  - 무효화 조건: 원본 파일 Fingerprint 변이 OR 해당 포맷 파서 버전 변경   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ (추출문 재사용: 벡터 규칙만 변경 시 재파싱 0회)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ [Layer 2] 저장 벡터 경계 (Vector Indexing & Portable SQLite Store)       │
│  - 버전 결정 인자 (단 3가지만 허용):                                     │
│    1) 인코딩 워커의 실제 수치 연산 구현 버전                             │
│    2) 조각 분할 규칙 (240자 윈도우 / 160자 스트라이드 입력 구성)         │
│    3) 모델 및 토크나이저 자산의 파일 해시                                │
│  - 불변 보장: 랭킹 정책·대조 판별기·임계값·UI가 바뀌어도 벡터 재계산 0회 │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ (저장 벡터 해시 100% 보존)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ [Layer 3] 하이브리드 랭킹 및 모델 비의존 표현 경계 (Ranking & UI)        │
│  - 다중 채널 교차 병합(SearchFusion) + 어휘 직접 포함 우선 + 본문 대조   │
│  - UI 응답 계약: matching(value: 0~100, label, unit, description)       │
└─────────────────────────────────────────────────────────────────────────┘

2.1 단일 추출 등록기(create_extractors) 공유와 포맷별 독립 버전

web_bootstrap.py에서 생성된 단일 ContentExtractor 등록기 인스턴스를 파일 분류기, 이름 검토기, 맥락 검색 엔진 세 곳에 동일하게 주입합니다.

  • 모든 포맷 어댑터(TXT, MD, PDF, DOCX, XLSX, HWP5 등)는 동일한 ContentResult 구조체를 반환하며, 문서의 페이지·문단·시트·셀 좌표(fragments)와 생략 범위(omissions)를 손실 없이 보존합니다.
  • 각 포맷 어댑터는 자신만의 독립적인 추출 버전을 가집니다. 예를 들어 HWP5 파서의 버그를 수정해 HWP 어댑터 버전을 올리더라도, 이미 색인된 PDF나 XLSX 문서의 추출 캐시와 벡터는 단 하나도 무효화되지 않습니다.

2.2 저장 벡터 버전의 최소 의존성 원칙

저장된 문서 벡터가 언제 재생성되어야 하는지를 결정하는 버전 해시에서 검색 서비스 소스 코드, 관련성 대조 모델, 점수 변환 공식, 임계값, UI 표시 코드를 모두 제외했습니다.

  • 실제 검증(real-reuse.json)에서 관련성 판별 어댑터를 통째로 교체한 뒤 검색을 수행했을 때, 기존 저장된 문서들에 대해 문서 재추출 0회, 문서 벡터 재계산 0회, 저장 벡터 SHA-256 해시 불변을 유지한 채 오직 검색 질의 임베딩 1회만으로 새로운 랭킹 정책이 즉시 적용됨을 입증했습니다.

2.3 모델을 모르는 결과 화면 (MatchingContract)

프런트엔드(React SearchHit)가 특정 모델의 이름이나 원시 로짓(Logit), 코사인 유사도 수식을 직접 해석하면 백엔드 랭킹 알고리즘을 고도화할 때마다 UI 코드가 깨집니다. 이를 막기 위해 서버는 항상 정규화된 matching 계약(value: 0.0~100.0 유한 실수, label, unit, description, details)만을 반환하며, 원시 코사인 값이나 단조 변환 전 로짓 값은 내부 진단용(ⓘ 상세 패널)으로만 격리했습니다.


3. 하이브리드 어휘-맥락 랭킹과 다중 채널 교차 병합 (search_fusion.py)

검색 품질을 끌어올리기 위해 우리는 “단일 점수 공식으로 모든 질의를 해결한다”는 환상을 버리고, 질의의 형태와 문서의 증거 채널을 분리해 결합하는 **다계층 하이브리드 랭킹 엔진(SEARCH03~05)**을 설계했습니다.

3.1 본문과 메타정보의 분리 대조 및 어휘 직접 포함(Lexical Containment) 우선 규칙

  1. 본문 대조와 메타정보 대조의 엄격한 분리: 후보 조각을 추출할 때 본문이 존재하는 문서는 오직 순수 본문 텍스트(서두 180자 + 상위 후보 조각 앞뒤 문맥, 최대 512토큰)만을 교차 대조 판별기에 전달합니다. 파일명·상대 경로·날짜는 «파일 메타정보» 채널로 분리하여 처리하며, 메타정보의 유사도 점수를 본문 일치 점수와 임의로 합산해 왜곡하지 않습니다.
  2. 짧은 핵심어(1~3단어) 직접 포함 우선 계층: 사용자의 질의가 1~3단어로 이루어진 경우, 정규화된 검색어가 (1) 실제 문서 본문 텍스트, (2) 반영 완료(ready)된 사용자 입력 설명·태그·추가 속성, (3) 상대 파일명에 직접 포함되어 있는지를 먼저 판별합니다. 직접 포함이 확인된 문서는 맥락 대조 점수가 낮더라도 절대 후보에서 탈락시키지 않고 최상위 그룹에 우선 배치합니다.
  3. 단조 변환 참고 점수 산출: 본문 맥락 대조 원시 값(raw_score)은 시그모이드 단조 변환을 통해 0~100 구간의 참고 지표로 변환합니다.
matching_score = round(100.0 / (1.0 + math.exp(-raw_score)), 1)

이 점수는 결과 집합의 최대·최소에 맞춰 매번 인위적으로 늘리는 상대 정규화(Min-Max Stretching)를 하지 않으며, 절대적인 정답 확률이 아닌 상대적 검토 우선순위 지표로만 제공됩니다.

3.2 다중 채널 중복 가산 방지 알고리즘 (all-candidates-best-channel-rank-v1)

작업 폴더 안에는 일반 문서뿐 아니라 텍스트와 시각적 특징을 동시에 가진 이미지·스캔 자료가 함께 존재합니다. 이때 특정 이미지 파일이 텍스트 채널(추출된 글자 또는 사용자 메모)에서도 검색되고 시각 채널에서도 검색되었다고 해서 두 채널의 점수를 단순 합산(Double-counting)하면, 텍스트만 있는 핵심 기획서나 엑셀 단가표보다 이미지 파일이 부당하게 상위권을 독점하는 편향이 발생합니다.

src/file_organizer/domain/search_fusion.py는 단 13줄의 순수 함수로 이 다중 채널 병합 문제를 결정론적으로 해결합니다.

"""Interleave ranked channels without counting an image's presence as a second vote."""
VERSION = 'all-candidates-best-channel-rank-v1'

def merge(text_ids, image_ids):
    text = {identifier: i for i, identifier in enumerate(text_ids, 1)}
    image = {identifier: i for i, identifier in enumerate(image_ids, 1)}
    infinity = float('inf')

    def order(identifier):
        a, b = text.get(identifier, infinity), image.get(identifier, infinity)
        # 어느 한 채널에서라도 달성한 '최고 순위(min(a, b))'만을 대표 순위로 채택한다.
        # 동순위일 때는 텍스트 채널(0)을 우선하고 교차 배치하며, 어떤 후보도 누락시키지 않는다.
        return min(a, b), 0 if a <= b else 1, a, b, identifier

    return sorted(set(text) | set(image), key=order)

이 알고리즘은 각 자료가 텍스트 채널과 시각 채널 중 더 높은 순위를 기록한 쪽의 순위(min(a, b)) 하나만 인정하고 두 번째 채널 등장을 가산점으로 중복 계산하지 않습니다. 덕분에 모든 후보를 누락 없이 보존하면서도 채널 간 공정한 교차 정렬을 보장합니다.

3.3 상대 날짜 기억 검색(±3일 → ±7일)과 96.5% 지연 시간 단축 캐시

  • 탄력적 날짜 윈도우 확장: 실무자가 "일주일 전 회의 자료"라고 기억할 때 정확히 7 × 24시간 전의 파일만 찾으면 6일 전이나 8일 전에 생성된 파일을 놓칩니다. domain/context_search.py는 "1주일 전 / 일주일 전 / N일 전" 질의에 대해 중심일 기준 ±3일 구간을 1차 탐색하고, 해당 구간에 후보가 없으면 자동으로 ±7일까지 확장한 뒤 실제 적용된 탐색 기간을 UI에 투명하게 고지합니다.
  • 버전 결합 인메모리 캐시: 동일 세션 내 반복 질의나 탭 전환 시 불필요한 재연산을 막기 위해 질의 임베딩(상한 64개)과 문서-질의 대조 쌍(상한 1,024개)을 입력 및 모델 버전에 결합해 캐싱합니다. 단, 캐시를 반환하기 직전에도 대상 파일의 현재 디스크 Fingerprint와 DB revision 일치 여부는 매 검색마다 실시간으로 검증합니다. 이를 통해 무결성 손상 없이 동일 질의 응답 시간을 15.325초에서 0.540초로 96.5% 단축했습니다.

4. 선행 상태 기록(Write-Ahead Pending) 기반 사용자 맥락 필드와 exit 73 중단 복원

파일 정리와 자동 본문 추출을 아무리 고도화해도, 파일 바이트 내부에 애초에 적혀 있지 않은 인간의 암묵지(Tacit Knowledge) — 예컨대 “거래처 김 부장님이 급하게 요청한 수정본”, “2공장 배관 누수 현장 사진” — 는 기계가 파일만 보고 알아낼 수 없습니다.

실제 실험(SEARCH05)에서도 텍스트가 복잡한 컴퓨터 부품 견적 캡처 이미지를 자동 추출만으로 "견적"이라고 검색했을 때는 17위에 머물렀지만, 사용자가 한 줄의 맥락 설명이나 태그를 보강한 즉시 **1순위(Rank 1)**로 정확히 검색되었습니다. 즉, 완벽한 자료실 아키텍처는 자동 추출 근거와 사용자의 수동 맥락 보강을 하나의 상태 머신 안에서 유기적으로 결합해야 합니다.

4.1 전 포맷 공통 사용자 맥락 스키마

문서·이미지·오디오·영상·기타 모든 파일 형식에 대해 동일한 도메인 검증 계약을 적용하는 3종의 사용자 맥락 필드를 설계했습니다.

사용자 필드목적 및 활용 방식도메인 검증 상한
description (설명)실무자가 기억하는 파일의 배경·회의 맥락·특이사항 서술최대 2,000자
tags (태그)즉각적인 분류 및 핵심어 매칭을 위한 단서 목록항목당 80자 × 최대 20개
custom_fields (추가 정보)사용자가 직접 정의하는 Key: Value 구조화 속성 (예: 담당자: 이대리, 현장: 안산)키 40자 / 값 200자 × 최대 20개

중요한 불변식은 사용자 입력을 자동 확인된 원본 사실(예: 문서 내 확정 거래처나 EXIF 촬영지)로 둔갑시키지 않고 별도 레이어로 보존하며, 입력 문자열 안에 경로(..\)나 쉘 명령어가 포함되어 있어도 순수 데이터로만 취급해 인젝션을 원천 차단한다는 점입니다.

4.2 5단계 비동기 벡터 동기화 계약과 프로세스 강제 종료(exit 73) 복원

사용자가 설명을 입력하고 저장 버튼을 눌렀을 때, 백그라운드에서 해당 설명을 벡터화하는 도중 프로그램이 꺼지거나 오류가 발생하면 어떻게 될까요? 허술한 시스템은 벡터 계산이 끝나기 전에 DB 저장을 미루다 입력을 날려버리거나, 반대로 텍스트만 바뀐 채 예전 설명의 벡터가 남아 검색 결과가 어긋나는 불일치(Stale Vector) 상태를 만듭니다.

우리는 이를 막기 위해 5단계 선행 상태 기록(Write-Ahead Pending) 동기화 프로토콜을 구현했습니다.

[Step 1] 입력 정규화 및 낙관적 동시성(expected_revision) 검사
   │     (정규화 결과가 기존 저장값과 동일하면 revision 증가 및 재임베딩 0회로 즉시 종료)
   ▼
[Step 2] SQLite DB에 새 사용자 텍스트를 즉시 커밋 + sync_state = 'pending' 기록 + revision 증가
   │     (이 시점 이후 프로세스가 죽어도 사용자의 타이핑 결과는 디스크에 100% 영구 보존됨)
   ▼
[Step 3] 기존(구버전) 사용자 맥락 벡터를 인덱스에서 즉시 제거
   │     (갱신 도중 구버전 설명으로 잘못 검색되는 유령 매칭 방지)
   ▼
[Step 4] 오직 변경된 사용자 맥락 텍스트만 독립 워커로 벡터화
   │     (원본 문서 본문 재추출 0회 · 이미지 픽셀 재분석 0회 · 오디오 재전사 0회)
   ▼
[Step 5] 완료 후 DB의 현재 revision이 Step 2의 revision과 여전히 동일한지 재확인
         - 일치 시: 새 사용자 벡터 저장 + sync_state = 'ready' 전환
         - 불일치 시(도중에 사용자가 또 수정함): 뒤늦게 도착한 구버전 벡터를 즉시 폐기(Stale Drop)

실제 검증에서 Step 4가 진행되는 도중 워커 프로세스를 강제 종료(exit code 73)시킨 뒤 서버를 재기동했을 때, Step 2에서 선기록된 사용자 입력과 pending 상태가 유실 없이 복원되었으며, UI에서 대기 상태 확인 및 재시도(Retry)를 통해 즉시 ready 상태로 완결됨을 확인했습니다. 또한 만약 실행 환경에 벡터 모델 자산이 설치되어 있지 않더라도 기존 저장된 벡터나 사용자 메모를 절대 삭제하지 않으며, 즉시 어휘(Keyword) 기반 검색으로 끊김 없이 폴백(Fallback)하여 자료실을 열람·편집할 수 있습니다.


5. 절대 경로 종속성 탈피: 폴더 귀속형 DB(workspace.sqlite3)와 4단계 해시 재앵커링

시리즈의 대미를 장식하는 아키텍처는 **“작업 폴더를 통째로 복사해 다른 드라이브나 다른 PC로 옮겨도 어떻게 재추출·재임베딩 한 번 없이 모든 색인과 사용자 메모를 즉시 이어서 쓸 수 있는가”**에 대한 해답입니다.

대부분의 데스크톱 관리 도구는 애플리케이션 설치 폴더나 사용자 홈 디렉토리(AppData) 밑의 중앙 DB에 D:\업무폴더\계약서.pdf 같은 **절대 경로(Absolute Path)**를 기본키(Primary Key)처럼 저장합니다. 이 방식은 사용자가 탐색기에서 D:\업무폴더를 외장하드나 C:\백업_2026\업무폴더_사본으로 복사하는 순간 완전히 무너집니다. 경로 문자열이 달라졌고, 복사본 파일의 OS 생성일(ctime), 볼륨 디바이스 번호(st_dev), 파일 인덱스 번호(st_ino)까지 모두 새로 부여되기 때문입니다.

5.1 “절대 경로는 식별자가 아니라 런타임 바인딩이다” (PortableSemanticStore)

src/file_organizer/infrastructure/portable_semantic_store.py의 첫 줄 독스트링은 이 아키텍처의 핵심 철학을 한 문장으로 정의합니다.

"""Folder-owned workspace DB. Absolute paths are runtime bindings, not identities."""

우리는 색인과 사용자 맥락 DB를 앱 내부가 아닌 **선택한 작업 폴더 내부의 .file-organizer/workspace.sqlite3에 직접 동봉(Self-Contained)**시켰습니다.

class PortableSemanticStore:
    portable = True
    ...
    @staticmethod
    def relative(value):
        if (not isinstance(value, str) or not value
            or '\\' in value or ':' in value
            or value.startswith('/')
            or any(x in ('', '..', '.') for x in value.split('/'))):
            raise ValueError('작업 DB의 상대 경로가 안전하지 않습니다.')
        return PurePosixPath(value)

    def snapshot(self, root):
        store, meta = self._db(root)
        value = self._snapshot(store)
        for entry in value['entries']:
            relative = self.relative(entry['relative'])
            # 절대 경로(path)는 DB에 고정 저장하지 않고, 조회 시점에 현재 root + relative로 동적 합성한다.
            entry.update(root=str(root), path=str(Path(root).joinpath(*relative.parts)))
            entry['metadata'] = {**entry.get('metadata', {}), 'path': entry['relative']}
        return dict(value, workspace=meta)
  1. 절대 경로 제거 및 상대 경로 보안 검증: DB에 레코드를 저장(replace)할 때는 런타임 속성인 path와 root를 제거(pop)하고 오직 정규화된 POSIX 상대 경로(relative)만 기록합니다. 외부에서 전달받은 폴더의 DB가 악의적으로 조작되어 상위 디렉토리 탈출(..)이나 드라이브 문자(:)를 포함하고 있으면 relative() 검증기가 즉시 로드를 차단합니다.
  2. DB 무결성 사전 검문: 폴더 내 workspace.sqlite3를 열 때마다 파일 크기 상한(64 MiB), PRAGMA quick_check 물리 무결성, workspace_meta 스키마 버전을 확인하며, 손상되었거나 상위 버전인 경우 기존 파일과 DB를 훼손하지 않고 즉시 보호 모드로 중단합니다.

5.2 폴더 이동 및 내부 개명 시 4단계 일대일 대응 알고리즘 (workspace_identity.py)

사용자가 폴더를 D:\ 드라이브에서 C:\ 드라이브의 다른 이름 폴더로 복사했거나(rebind), 작업 폴더 안에서 파일 이름을 바꾸고 하위 폴더로 옮겼을 때, 시스템은 어떻게 기존 파일 ID(file_id)와 사용자 메모·벡터를 찾아 연결할까요?

src/file_organizer/domain/workspace_identity.py의 correspondence(previous, current) 함수는 모호한 중복 파일에 엉뚱한 메모가 복제되는 참사를 막기 위해 엄격한 4단계 결정론적 매칭을 수행합니다.

"""One-to-one file correspondence. Ambiguous duplicates never inherit another note."""

def same_content(a, b):
    a, b = a.get('fingerprint', {}), b.get('fingerprint', {})
    return bool(a.get('sha256')) and all(a.get(k) == b.get(k) for k in ('size', 'sha256'))

def correspondence(previous, current):
    found = {}
    used = set()
    def bind(i, old):
        found[i] = old
        used.add(old['id'])

    # [Stage 1] 상대 경로(대소문자 무시)가 그대로이고 파일 크기 + SHA-256이 일치하면 최우선 확정 바인딩
    # (폴더 내 동일한 내용의 복사본 파일이 여러 개 있어도 위치가 같은 원본은 흔들리지 않음)
    by_path = {e['relative'].casefold(): e for e in previous}
    for i, entry in enumerate(current):
        old = by_path.get(entry['relative'].casefold())
        if old and old['id'] not in used and same_content(old, entry):
            bind(i, entry_old := old)

    def unique_pairs(key):
        old_groups = {}
        new_groups = {}
        for old in previous:
            value = key(old)
            if old['id'] not in used and value is not None:
                old_groups.setdefault(value, []).append(old)
        for i, entry in enumerate(current):
            value = key(entry)
            if i not in found and value is not None:
                new_groups.setdefault(value, []).append(i)
        # 오직 이전 집합에서도 유일(len==1)하고 현재 집합에서도 유일(len==1)할 때만 1:1 바인딩!
        for value, olds in old_groups.items():
            incoming = new_groups.get(value, [])
            if len(olds) == len(incoming) == 1:
                bind(incoming[0], olds[0])

    # [Stage 2] 동일 볼륨 내 파일 이동/개명: (device, inode, size, sha256) 4-Tuple 유일 일치 바인딩
    def identity(entry):
        fp = entry['fingerprint']
        if fp.get('device') is None or not fp.get('inode') or not fp.get('sha256'):
            return None
        return fp['device'], fp['inode'], fp['size'], fp['sha256']
    unique_pairs(identity)

    # [Stage 3] 교차 드라이브 복사 후 이동/개명: (size, sha256) 바이트 해시 유일 일치 바인딩
    unique_pairs(lambda e: (e['fingerprint']['size'], e['fingerprint']['sha256'])
                 if e['fingerprint'].get('sha256') else None)

    # [Stage 4] 기존 상대 경로에서 파일 내용이 편집된 경우:
    # 사용자가 공들여 작성한 설명·태그·고정 ID는 그대로 승계하되, 변경된 본문만 재추출/재임베딩한다.
    for i, entry in enumerate(current):
        old = by_path.get(entry['relative'].casefold())
        if i not in found and old and old['id'] not in used:
            bind(i, old)
    return found

이 37줄의 도메인 코드에 담긴 엔지니어링 디테일을 살펴보면 다음과 같습니다.

  1. Stage 1 (상대 경로 + 해시 불변): 작업 폴더를 D:\에서 C:\로 통째 복사하면 OS device, inode, 복사본 생성일은 모두 바뀌지만 폴더 내부의 relative 경로와 파일 바이트(size, sha256)는 100% 동일합니다. Stage 1과 PortableSemanticStore.rebind()는 이를 즉시 인식하여 새 드라이브의 물리 지문으로 바인딩을 갱신합니다. 이때 **본문 재추출 0회, 본문·픽셀·사용자 벡터 재계산 0회**로 모든 색인이 즉시 활성화됩니다.
  2. Stage 2 & Stage 3 (len(olds) == len(incoming) == 1 유일성 가드): 작업 폴더 안에서 파일 이름을 바꾸거나 하위 폴더로 옮긴 경우, Stage 2(동일 볼륨 Inode 추적)와 Stage 3(바이트 해시 추적)가 작동합니다. 이때 만약 내용이 똑같은 양식 파일 2개가 동시에 다른 곳으로 이동했다면, 어느 파일이 기존 메모의 주인인지 확신할 수 없습니다. len(olds) == len(incoming) == 1 조건은 유일한 1:1 대응이 증명될 때만 메모와 ID를 승계하고, 모호한 중복본에는 절대 타 파일의 메모를 오염시키지 않습니다.
  3. Stage 4 (제자리 편집의 맥락 보존과 본문 재색인 분리): 사용자가 기존 위치의 엑셀 문서를 열어 내용을 수정·저장한 경우, 파일 해시(sha256)가 바뀌었으므로 본문 텍스트는 당연히 다시 추출하고 본문 벡터는 새로 계산해야 합니다. 하지만 Stage 4가 동일 상대 경로를 통해 기존 파일 엔티티(id)를 승계해 주므로, 사용자가 그 파일에 적어 두었던 2,000자짜리 업무 설명과 태그는 날아가지 않고 그대로 유지됩니다.

실제 드라이브 간 이식 검증(WORK01)에서 6종의 서로 다른 포맷 파일과 각각의 사용자 정의 필드·벡터가 담긴 D:\ 드라이브 작업 폴더를 C:\ 드라이브의 전혀 다른 이름 폴더로 복사한 뒤 연결했을 때, **고정 파일 ID 6/6 유지, 사용자 커스텀 필드 6/6 유지, 저장 벡터 해시 6/6 일치, 본문 재추출 및 재임베딩 0회**로 완벽히 복원됨을 확인했습니다.


6. 시리즈 총괄 요약: 타협하지 않는 요구사항이 만드는 아키텍처의 깊이

총 3부에 걸쳐 살펴본 윈도우 업무용 파일 정리 및 이식형 자료실 시스템은 처음부터 거대한 복합 시스템으로 기획된 것이 아니었습니다. **“폴더 안에 흩어진 실무 파일들을 안전하고 정확하게 정리하자”**는 단 하나의 목표를 완수하는 과정에서, 현장의 예외 상황과 데이터 무결성 앞에서 타협하지 않고 한 단계씩 공학적 해법을 쌓아 올린 결과물입니다.

진화 단계마주한 실무 한계 및 장애 요인제이앤코어가 구축한 아키텍처 해법
1단계 (1부)OS 파일 이동 도중 크래시·전원 차단 시 부분 기록 손상 및 TOCTOU 덮어쓰기 위험8-Tuple Fingerprint + TreeSnapshots + 선행 의도 저널(run-<id>.jsonl) + Win32 FileRenameInfo(ReplaceIfExists=0) + 9-State RecoveryService.assess 복구 상태 머신
2단계 (2부)고정 4필드 강제 시 실무 문서 0 ready / 8 hold 실패, 엑셀 빈 셀 폭증, 날짜 혼선 및 생성형 모델의 인용 왜곡자료 성격별 2단계 정책 + 경계 제한 파서(SafeDocumentReader, 방문 노드 10,000 / 유효 셀 1,500 분리) + 6대 날짜 역할 분해 + 자유 서술을 박탈한 선택 전용 계약(fact_contract_v3)
3단계 (3부)단일 폴더 트리의 검색 한계, 순수 벡터 검색의 무관 문서 노출 및 재색인 비용, 폴더 복사/이동 시 절대 경로 색인 파괴추출·색인·랭킹 3단 버전 분리 + 어휘 포함 우선 및 다중 채널 교차 병합(search_fusion) + pending 선기록 사용자 맥락 동기화 + 4단계 해시 재앵커링 기반 동봉형 DB(.file-organizer/workspace.sqlite3)

제이앤코어가 지향하는 엔지니어링은 단순히 외부 라이브러리를 조합해 그럴듯한 데모 화면을 만드는 것이 아닙니다. 프로세스가 언제 강제 종료되어도, 문서 양식이 어떻게 변칙적으로 작성되어 있어도, 사용자가 폴더를 통째로 다른 드라이브에 복사해 가져가도 데이터가 단 1바이트도 깨지지 않고 의도한 그대로 작동하는 결정론적 시스템 아키텍처를 구축하는 것입니다.

사내 문서 자산의 아카이빙, 비정형 실무 데이터 파이프라인, 혹은 고신뢰 로컬/사내망 업무 도구 구축이 필요하시다면 언제든 제이앤코어 기술연구소와 상의해 주시기 바랍니다.


시리즈 전체 목차

#검색엔진아키텍처#이식형데이터베이스#하이브리드랭킹#버전경계분리#상태동기화#콘텐츠해시앵커링#SQLite아키텍처#도메인주도설계#시스템진화#제이앤코어
목록으로 돌아가기

2~4주 정찰제 맞춤 개발

우리 회사 엑셀 업무도 웹 시스템으로 바꿀 수 있을까요?

사내 ERP를 무리하게 바꾸지 않고, 매달 반복되는 엑셀 병목만 독립 웹 시스템으로 2~4주 만에 전환합니다.