단순 파일 이동 스크립트가 왜 데이터 유실로 이어지는가: 윈도우 업무용 파일 정리기 아키텍처 구축기 ① — 비파괴 파일 트랜잭션과 중단 복구(Crash-Safe Recovery) 엔진
OS 파일시스템의 비원자성(Non-Atomicity)과 TOCTOU 경쟁 조건을 극복하기 위해 4-Layer 클린 아키텍처, 8-Tuple 불변 지문(Fingerprint), 폴더 트리 스냅샷(TreeSnapshots), 선행 의도 저널링(Write-Ahead Intent Log), 그리고 9-State 중단 복구 상태 머신을 설계한 엔지니어링 기록입니다.
시리즈 구성 — 윈도우 업무용 파일 정리 및 이식형 자료실 아키텍처 구축기 (총 3부작)
로컬 스토리지에 누적된 수천 건의 실무 문서와 폴더를 규칙에 따라 분류·개명·재배치하는 시스템을 설계할 때, 가장 흔히 범하는 아키텍처적 오류는 파일시스템 조작을 단순한 문자열 경로 변경이나 표준 라이브러리의 copy / move 호출 묶음으로 취급하는 것입니다.
관계형 데이터베이스(RDBMS) 내부의 레코드 갱신은 단일 트랜잭션(BEGIN ... COMMIT / ROLLBACK)으로 원자성(Atomicity)과 격리성(Isolation)을 보장받을 수 있습니다. 반면 Windows NTFS를 비롯한 운영체제 파일시스템 상에서 다수의 파일과 중첩 디렉토리 트리를 복사·이동·개명하는 작업은 본질적으로 비원자적(Non-Atomic)이며 외부 프로세스에 완전히 노출된 공유 상태 변이입니다.
제이앤코어는 실무용 윈도우 파일 정리 및 자료실 시스템을 설계하면서, 초기 요구사항이었던 “지정된 폴더 내 파일들의 일괄 정리”를 데이터 유실 가능성 0%의 엔터프라이즈급 스토리지 엔진 수준으로 끌어올리기 위해 파일 조작 전 과정을 **선행 의도 저널링(Write-Ahead Intent Logging)**과 불변 지문 대조(Cryptographic Fingerprint Verification) 기반의 트랜잭션 엔진으로 구축했습니다.
본 1부에서는 OS 파일시스템의 구조적 한계를 정의하고, 이를 해결하기 위해 구축한 4-Layer 아키텍처, Fingerprint 및 TreeSnapshots 도메인 모델, Windows 커널 수준 비파괴 개명 프리미티브, 그리고 프로세스 강제 종료 이후에도 정확히 상태를 판별해 복원하는 9-State 중단 복구(Crash-Safe Recovery) 상태 머신의 내부 설계를 상세히 해부합니다.
1. 문제 정의: 왜 단순 파일 이동 스크립트는 실무 환경에서 실패하는가
수백 개의 실무 파일과 하위 폴더를 일괄 정리하는 도중 발생할 수 있는 장애 시나리오를 공학적으로 분해하면 다음 네 가지 치명적 결함 지점이 드러납니다.
1.1 검사 시점과 실행 시점의 괴리 (TOCTOU: Time-of-Check to Time-of-Use)
사용자가 정리 미리보기(Preview)를 생성한 시점(t0)과 실제 파일 이동(Apply) 버튼을 누른 시점(t1) 사이에는 수십 초에서 수십 분의 시간차가 존재합니다. 이 간격 동안 사용자가 한글(HWP)이나 엑셀(XLSX)에서 원본 문서를 열어 수정·저장했거나, 백그라운드 동기화 클라이언트가 파일을 교체했을 수 있습니다. t0에 계산된 계획(PlanItem)을 t1에 무검증 실행하면, 변경된 최신 문서가 구버전 메타데이터 기준의 경로로 덮어써지거나 손상됩니다.
1.2 다단계 파일 조작 도중의 프로세스 비정상 종료 (Partial Mutation)
파일 이동(move)은 단일 볼륨 내 메타데이터 포인터 변경이 아닌 이상 물리적으로 (1) 목적지 파일 스트림 생성 → (2) 청크 단위 바이트 기록 → (3) 메타데이터 복제 → (4) 원본 파일 삭제의 다단계 I/O로 실행됩니다. 만약 2단계 도중 전원이 차단되거나 프로세스가 강제 종료(SIGKILL / 작업 관리자 종료)되면 목적지에는 절반만 기록된 손상 파일(Corrupted Partial File)이 남고, 재실행 시 이 불완전한 사본이 정상 완료본으로 오인되거나 원본 삭제 여부조차 판별할 수 없는 불확정(Uncertain) 상태에 빠집니다.
1.3 폴더 단위 번들 이동 시 내부 구조 변형 및 침묵 실패
하위 파일 30개와 빈 폴더 4개로 구성된 프로젝트 폴더를 통째로 복사할 때, 도중에 단 하나의 하위 파일이라도 다른 프로세스의 파일 잠금(Sharing Violation)으로 인해 복사에 실패하거나 하위 상대 경로가 누락되면, 상위 폴더 이름은 존재하더라도 내부 산출물 세트의 무결성은 깨집니다.
1.4 Windows 경로 규격 및 특수 파일시스템 엔트리 위험
Windows 환경에서는 대소문자 비구분 충돌(Report.pdf vs report.pdf), 예약 장치명(CON, PRN, AUX, NUL, COM1COM9, LPT1LPT9), 후행 공백 및 마침표 자동 절삭, MAX_PATH 경계, 대체 데이터 스트림(ADS, file.txt:secret), 그리고 디렉토리 접합점(Junction)이나 심볼릭 링크(Reparse Point)를 통한 작업 루트 외부 탈출(Directory Traversal / Symlink Escape) 위험이 상존합니다.
2. 4-Layer 클린 아키텍처와 단방향 의존성 제어
시스템이 파일 정리기에서 문서 구조 분석기, 나아가 로컬 시맨틱 검색 및 이식형 자료실로 확장되는 과정에서도 코어 파일 안전성 불변식(Invariant)이 절대 훼손되지 않도록, 전체 코드베이스를 엄격한 4-Layer 아키텍처로 분리하고 모든 자체 모듈에 파일당 1,000줄 이하의 복잡도 상한을 강제했습니다.
[ Presentation Layer ] Desktop UI (Tk) / Local Web UI (React + HTTP Server)
│
▼
[ Application Layer ] Use Cases (Preview, Apply, RecoveryService, SemanticSearchService)
│ + Abstract Ports (RecoveryFiles, RecoveryStore, ContentAdapter)
▼
[ Domain Layer ] Pure Models & Deterministic Policies (Fingerprint, PlanItem,
▲ RecoveryItem.assess, FactContractV3, WorkspaceIdentity, SearchFusion)
│
[ Infrastructure Layer ] OS Filesystem I/O, Win32 FileRenameInfo, JSONL Intent Journal,
SQLite Stores (BEGIN IMMEDIATE), SafeDocumentReader, Isolated Workers
2.1 계층별 책임과 의존성 규칙
domain계층: 운영체제 파일 I/O, SQLite, HTTP, 외부 AI SDK를 일절 import하지 않는 순수 결정론적(Deterministic) 계층입니다. 파일 지문 동등성 비교, 경로 충돌 판정, 중단 복구 상태 판정(assess), 날짜 후보 역할 해소(resolve_dates), 작업실 파일 일대일 대응(correspondence) 등 모든 핵심 비즈니스 규칙이 순수 함수와 불변 데이터클래스(@dataclass(frozen=True))로만 정의됩니다.application계층: 작업 흐름(Orchestration)과 추상 포트(Protocol/ 인터페이스)만 정의합니다. 예를 들어RecoveryService는 실제 디스크에 접근하는 대신RecoveryFiles포트와RecoveryStore포트에만 의존합니다.infrastructure계층: 실제 Windows 파일시스템 호출, Win32 API 바인딩,.jsonl저널 파일flush/fsync, SQLite 트랜잭션, OOXML/PDF/HWP 파서 등을 구현하여application포트를 충족합니다.- 조립 경계 (
bootstrap.py/web_bootstrap.py): 의존성 주입(Dependency Injection)은 오직 최상위 부트스트랩 모듈에서만 수행됩니다. 이를 통해 데스크톱 환경과 로컬 웹 서버 환경이 완벽히 동일한 도메인·애플리케이션 엔진을 공유합니다.
3. 8-Tuple 불변 지문(Fingerprint)과 폴더 트리 스냅샷(TreeSnapshots)
파일의 동일성과 변경 여부를 판정할 때 단순히 파일 크기(size)와 수정 시각(mtime)만 비교하는 방식은 치명적인 허점을 갖습니다. 메타데이터 보존 복사 시 mtime이 동일하게 유지된 채 바이트 일부가 손상될 수 있으며, 반대로 파일 교체(운용 중 다른 파일이 같은 이름으로 이동) 시 볼륨 내 파일 식별자(inode / Windows nFileIndexHigh/Low)가 달라진 것을 놓칠 수 있습니다.
3.1 Fingerprint 불변 값 객체 설계
domain/transfer.py에 정의된 Fingerprint는 파일과 폴더 번들 모두를 포괄하는 8-Tuple 불변 구조체입니다.
@dataclass(frozen=True)
class Fingerprint:
size: int
mtime_ns: int
device: int
inode: int
sha256: str
entry_type: str = 'file'
file_count: int = 1
directory_count: int = 0
| 필드명 | 자료형 | 물리적 의미 및 무결성 검증 역할 |
|---|---|---|
size | int | 바이트 단위 정확 크기 (폴더 번들의 경우 하위 전체 파일 바이트 총합) |
mtime_ns | int | 나노초(ns) 정밀도의 최종 수정 타임스탬프 (초 단위 절삭으로 인한 미세 수정 누락 방지) |
device | int | OS 볼륨 디바이스 식별자 (st_dev, 교차 볼륨 여부 판별) |
inode | int | NTFS 파일 인덱스 번호 (st_ino, 동일 경로 내 파일 삭제 후 재생성/교체 검출) |
sha256 | str | 64자리 16진수 암호화 해시 (단일 파일은 바이트 스트림 SHA-256, 폴더는 트리 구조 다이제스트) |
entry_type | str | 'file' 또는 'directory' 엔트리 구분자 |
file_count | int | 엔트리 내 포함된 정규 파일 총수 (단일 파일은 1, 폴더는 하위 파일 수) |
directory_count | int | 폴더 번들 내부의 하위 디렉토리 총수 (빈 폴더 누락 검출용) |
이 8-Tuple 구조 덕분에 @dataclass(frozen=True)의 값 동등성 비교(current_source == original) 한 줄만으로 바이트 변조, 타임스탬프 변경, 파일 교체(Inode 변경), 하위 폴더/파일 개수 변화를 동시에 O(1)로 판정할 수 있습니다.
3.2 폴더 번들 복사 계약 (folder-copy-v1)과 TreeSnapshots
실무에서는 개별 파일뿐 아니라 관련 도면·내역서·사진이 묶인 프로젝트 폴더 전체를 하나의 단위로 정리해야 하는 경우가 빈번합니다. 폴더를 복사할 때 내부 파일 중 하나라도 변경되거나 빈 디렉토리가 유실되는 것을 막기 위해 TreeSnapshots와 결정론적 트리 해시(content_digest) 계약을 설계했습니다.
- 사전 보안 게이트: 스캔 단계에서 루트 폴더 및 하위 엔트리 전체에 대해 심볼릭 링크·디렉토리 접합점(
is_symlink및 Windows Reparse Point), 숨김/시스템 속성, 허용되지 않은 특수 파일 엔트리가 단 하나라도 발견되면 즉시 해당 폴더 번들 전체를blocked상태로 격리하고 작업을 거부합니다. - 결정론적 트리 다이제스트(
content_digest) 산출:- 폴더 내부의 모든 하위 디렉토리 상대 경로(정규화된 POSIX 슬래시 표기)와 모든 하위 파일의
(상대 경로, 파일 크기, 파일 바이트 SHA-256)튜플을 사전순으로 정렬합니다. - 정렬된 매니페스트 전체에 대해 상위 SHA-256 다이제스트를 계산하여 폴더
Fingerprint.sha256에 기록합니다. - 따라서 하위 깊숙한 곳의 빈 폴더 이름이 바뀌거나, 1바이트짜리 텍스트 파일 하나가 수정되어도 상위 폴더의
Fingerprint가 즉시 변경되어 실행 직전 재검증(Re-probe) 단계에서 차단됩니다.
- 폴더 내부의 모든 하위 디렉토리 상대 경로(정규화된 POSIX 슬래시 표기)와 모든 하위 파일의
- 상한 제어: 단일 번들 프리뷰가 시스템 메모리를 고갈시키지 않도록 폴더 내 항목 수(
500개)와 총 바이트(500MiB) 하드 캡을 두고, 이를 초과하는 경우 부분 복사를 시도하는 대신PreviewLimitError를 발생시켜 명시적으로 보류합니다.
4. 선행 의도 저널링(Write-Ahead Intent Logging)과 커널 수준 비파괴 실행
데이터베이스 엔진이 데이터 페이지 디스크 기록 전에 WAL(Write-Ahead Log)을 먼저 플래시하는 원리를 파일시스템 조작에 그대로 이식했습니다. 모든 실행(Run)은 고유 ID를 부여받으며, .local/recovery/run-<id>.jsonl에 각 단계의 **실행 의도(Intent)**와 **검증 결과(Verified Outcome)**를 JSON Lines 포맷으로 기록하고 매 레코드마다 flush() 및 OS 디스크 동기화(os.fsync())를 수행합니다.
4.1 실행 단위 독점 잠금 (.lock Lease)과 저널 프로토콜
동일한 실행 이력(run_id)에 대해 복수의 프로세스나 중복 HTTP 요청이 동시에 복원(Undo)이나 재검사를 수행하면 심각한 경쟁 조건이 발생합니다. 이를 막기 위해 RecoveryStore.lease(run_id)는 OS 파일 디스크립터 수준의 배타적 잠금 파일(.lock)을 획득한 상태에서만 저널 읽기와 상태 전이를 허용합니다.
단일 항목을 복사·이동할 때 기록되는 저널 이벤트 시퀀스는 다음과 같습니다.
[1] header 기록 (run_id, source_root, output_root, mode, operation, selected[]) + fsync
│
[2] item_intent 기록 (source 상대경로, destination 상대경로, original Fingerprint) + fsync
│
[3] 현재 원본 Fingerprint 재측정 (Original과 불일치 시 파일 열기 전 즉시 중단)
│
[4] copy_opened (또는 rename_starting) 기록 + fsync <-- "디스크 변이 시작" 경계선
│
[5] 스트림 복사 수행 (폴더인 경우 각 하위 엔트리마다 bundle_entry_copied 기록)
│
[6] 목적지 사본 Fingerprint 실측 및 Original과 SHA-256 / 트리 다이제스트 대조
│
[7] copy_verified (검증된 destination_fingerprint 포함) 기록 + fsync <-- "사본 무결성 확증" 경계선
│
[8] (mode == 'move'인 경우에만) source_removal_intent 기록 + fsync 후 원본 제거
이 프로토콜의 핵심은 [4] copy_opened와 [7] copy_verified 사이의 비대칭성입니다. 만약 [5]번 복사 도중 정전이 발생하면 저널에는 copy_opened만 존재하고 copy_verified는 존재하지 않습니다. 복구 엔진은 이 흔적을 보고 목적지에 남아 있는 파일이 “검증되지 않은 불완전 사본”임을 수학적으로 확신할 수 있습니다.
4.2 Windows 커널 FileRenameInfo(ReplaceIfExists=0)를 통한 덮어쓰기 원천 차단
Python 표준 라이브러리의 os.replace()는 목적지에 파일이 있으면 조용히 덮어쓰며, if not os.path.exists(dst): os.rename(src, dst) 패턴은 존재 여부 검사와 실제 개명 호출 사이에 다른 프로세스가 파일을 생성하는 고전적인 TOCTOU 취약점을 가집니다.
본 엔진은 개명 및 복원 이동 시 사전에 원본 핸들의 지문을 검증한 뒤, Windows Win32 API의 SetFileInformationByHandle에 FileRenameInfo 구조체(ReplaceIfExists = FALSE (0))를 전달하여 커널 수준에서 원자적 이동을 요청합니다. 목적지 경로에 파일이 1바이트라도 존재하면 OS 커널 자체가 ERROR_ALREADY_EXISTS로 호출을 거부하므로, 어떠한 경쟁 조건 하에서도 기존 파일을 덮어쓰는 사고가 물리적으로 불가능합니다.
5. 9-State 중단 복구 상태 머신 (RecoveryService.assess)
프로세스가 비정상 종료된 후 재기동되었거나 사용자가 이전 실행 이력을 조회·복원하려 할 때, 시스템은 단순히 저널의 마지막 줄만 믿지 않습니다. 저널에 기록된 과거 상태와 **현재 디스크의 실제 물리 상태(probe)**를 3자 대조하여 각 항목을 9가지 결정론적 상태 중 하나로 분류합니다.
아래는 src/file_organizer/domain/recovery.py와 src/file_organizer/application/recovery.py에 구현된 실제 상태 판정 알고리즘입니다.
@dataclass(frozen=True)
class RecoveryItem:
source: str
destination: str
status: str
reason: str
reversible: bool = False
entry_type: str = 'file'
def assess(
source, destination, mode,
original, current_source, current_destination,
verified, opened, removal,
undo_target=None, current_undo=None
):
def result(status, reason, reversible=False):
return RecoveryItem(source, destination, status, reason, reversible)
# 1. 이미 역방향 복원(Undo) 의도가 기록된 항목의 사후 검증
if undo_target:
if current_destination is None and current_undo == verified and verified is not None:
return result('reverted', '되돌린 위치와 파일 식별값 일치')
if current_undo is not None:
return result('conflict', '되돌릴 위치에 파일 존재')
# 2. 목적지에 결과 파일이 존재하지 않는 경우
if current_destination is None:
if current_source == original and not opened:
return result('not_applied', '파일 작업 시작 전 중단 · 자동 재실행 없음')
return result('missing', '결과 파일 없음 · 수동 확인')
# 3. 목적지에 파일은 존재하나 copy_verified 저널이 없는 경우 (복사 중 크래시 등)
if verified is None:
return result('uncertain', '검증된 목적지 식별 기록 없음 · 자동 처리 금지')
# 4. 목적지 파일이 완료 이후 외부에서 수정·교체된 경우
if current_destination != verified:
return result('changed', '결과 파일이 변경/교체됨')
# 5. 이동(move) 모드에서의 추가 정합성 검증
if mode == 'move' and current_source is not None:
return result('conflict', '원래 위치에 파일 존재 · 복원하지 않음')
if mode == 'move' and not removal:
return result('uncertain', '원본 제거 의도 기록 없음')
# 6. 모든 무결성 검증을 통과한 완료 항목만 역방향 복원(reversible=True) 허용
return result('completed', '검증된 결과 확인 · 승인 후 되돌리기 가능', True)
5.1 9대 복구 상태 정의 및 자동 처리 허용 매트릭스
상태 코드 (status) | 발생 조건 (저널 이벤트 vs 디스크 실측 지문) | 역방향 복원 (reversible) | 엔진 후속 처방 |
|---|---|---|---|
not_started | 실행 헤더의 selected 목록에는 있으나 item_intent조차 기록되기 전 중단됨 | False | 디스크 변이 없음 확증 · 자동 재실행 금지 |
not_applied | item_intent는 기록되었으나 copy_opened 이전 중단 + 현재 원본 지문이 original과 완벽 일치 | False | 원본 무결성 확증 · 자동 재실행 금지 |
completed | copy_verified 존재 + 현재 목적지 지문이 verified와 일치 (이동 모드는 원본 부재 및 removal 확인) | True | 유일하게 사용자 승인 하에 원자적 되돌리기(undo) 허용 |
uncertain | 목적지에 파일은 존재하나 copy_verified가 없음 (복사 도중 프로세스 강제 종료 또는 선제 존재 파일) | False | 절대 자동 삭제·복원 금지 (부분 기록 파일이거나 무관한 기존 파일일 수 있으므로 격리) |
changed | copy_verified 완료 이후 사용자가 목적지 파일을 열어 수정했거나 다른 파일로 교체함 (current_destination != verified) | False | 사용자의 사후 작업 산출물 보호를 위해 되돌리기 차단 |
conflict | 이동 모드에서 원래 위치에 새 파일이 생겼거나, 되돌리기 대상 위치에 이미 다른 파일이 존재함 | False | 덮어쓰기 방지를 위해 복원 차단 |
missing | copy_opened 이후 또는 완료 이후 목적지 파일이 외부에서 삭제·이동되어 사라짐 | False | 수동 확인 상태로 보류 |
reverted | undo_intent 실행 후 목적지 파일이 소거되고 복원 위치(undo_target) 지문이 verified와 일치함 | False | 되돌리기 최종 완료 확증 |
failed | 디스크 권한 거부(PermissionError), 경로 손상, 또는 rename_verified 실행 중 OS 예외 발생 | False | 오류 사유 기록 및 현장 보존 |
5.2 왜 uncertain과 changed 상태에서 자동 롤백을 금지하는가
일반적인 설치 프로그램이나 허술한 배치 스크립트는 작업 도중 오류가 발생하면 목적지 경로에 생성된 파일을 일괄 unlink(삭제)하는 방식으로 롤백을 시도합니다. 그러나 이는 두 가지 치명적인 데이터 파괴를 유발합니다.
changed상태에서의 삭제 위험: 정리 작업이 끝난 직후 사용자가 정리된 폴더에서 문서를 열어 30분간 추가 편집 후 저장했습니다. 이때 뒤늦게 이전 실행에 대해 “전체 되돌리기”를 눌렀을 때 지문 재검증(current_destination == verified) 없이 파일을 덮어쓰거나 삭제하면, 사용자가 방금 작업한 30분간의 수정본이 증발합니다. 본 엔진의rename_verified는 실행 직전까지 목적지 지문이verified와 나노초 타임스탬프·SHA-256까지 일치하는지 재확인하므로 수정된 파일은 절대 건드리지 않습니다.uncertain상태에서의 삭제 위험:copy_opened직후 크래시가 난 경우 목적지의 불완전 파일을 지우는 것이 안전해 보일 수 있으나, 만약 외부 요인으로 저널 기록 직전에 사용자가 동일한 이름의 중요 파일을 해당 위치에 옮겨 놓았다면 자동 삭제는 곧 원본 유실이 됩니다. 따라서verified지문이 확증되지 않은 모든 파일은uncertain으로 분류하여 사람의 육안 확인 전까지 어떠한 자동 삭제도 수행하지 않습니다.
또한 복사(copy) 작업의 되돌리기는 목적지 사본을 영구 삭제(unlink)하는 대신, .local/recovery/reverted/<run_id>/ 격리 보관소로 원자적 이동(rename_verified)시켜 만일의 오조작 시에도 사본 데이터조차 2차 복구할 수 있도록 이중 안전망을 두었습니다.
6. SQLite 상태 저장소의 원자적 스냅샷 교체와 동시성 제어
파일 트랜잭션 엔진 위에서 동작하는 로컬 상태 저장소들(검토 상태 저장소 SqliteReviewStore, 출처 원장 library.sqlite3, 검색 색인 semantic-search.sqlite3) 역시 멀티탭 브라우저 요청이나 백그라운드 워커와의 경쟁 조건으로부터 보호되어야 합니다.
- 스키마 버전 강제 (
PRAGMA user_version): 데이터베이스 연결 즉시PRAGMA user_version과PRAGMA quick_check를 검사합니다. 예상 버전과 불일치하거나 무결성 검사에 실패하면 테이블을 임의로 드롭(Drop)하거나 덮어쓰지 않고 즉시 읽기 전용 오류를 반환하여 기존 DB 파일을 보존합니다. BEGIN IMMEDIATE기반 쓰기 직렬화: SQLite의 기본 지연 트랜잭션(DEFERRED)은 읽기 잠금 상태에서 쓰기로 승격할 때SQLITE_BUSY데드락을 유발할 수 있습니다. 모든 상태 갱신 트랜잭션은 시작 즉시BEGIN IMMEDIATE를 선언하여 쓰기 잠금을 선점합니다.- 낙관적 동시성 제어 (
expected_revision):- 클라이언트가 검토 결정이나 메타데이터 수정을 저장할 때 자신이 조회했던
expected_revision번호를 함께 제출합니다. - 저장소는 트랜잭션 내부에서 현재 DB의
revision이expected_revision과 일치하는지 확인하고, 다른 탭이나 프로세스가 먼저 상태를 갱신해 버전이 어긋난 경우 덮어쓰기를 거부(RevisionConflict)합니다.
- 클라이언트가 검토 결정이나 메타데이터 수정을 저장할 때 자신이 조회했던
7. 1부 요약 및 다음 단계: “안전하게 옮기는 것”에서 “무엇을 근거로 이름을 지을 것인가”로
1부에서 다룬 비파괴 파일 트랜잭션과 9-State 중단 복구 엔진을 통해, 우리는 **“어떠한 프로세스 강제 종료나 외부 파일 변경 상황에서도 원본과 사본을 단 1바이트도 유실하거나 덮어쓰지 않는다”**는 물리적 기반을 완성했습니다.
그러나 물리적 파일 이동이 완벽히 안전해지자, 그 다음 단계의 본질적인 질문이 대두되었습니다.
“이름이
b19f8c2a-4d3e-...docx나최종_수정의수정(2).xlsx로 되어 있는 실무 파일들을, 사람의 수작업 개입 없이 어떻게 정확한 문서 성격과 날짜·출처 기반의 파일명으로 재구성할 것인가?”
초기에는 모든 문서에서 거래처 / 현장·품목 / 문서종류 / 작성일 4가지 고정 항목을 추출하겠다는 단순한 규칙으로 접근했습니다. 하지만 실제 다운로드 폴더에서 무작위로 가져온 8개의 실무 파일에 이 규칙을 적용하자 **0개 성공 / 8개 전원 보류(0 ready / 8 hold)**라는 결과가 나왔습니다.
이어지는 2부에서는 이 초기 실패를 분석하고, OOXML(DOCX/XLSX)·PDF·HWP5 복합 문서의 구조적 조각 추출기(SafeDocumentReader), 빈 서식 셀 폭증을 제어한 표 파싱 알고리즘, 본문 내 다중 날짜의 역할 분해(date_candidates), 그리고 생성형 모델의 환각(Hallucination)을 코드로 원천 봉쇄한 **선택 전용 사실 계약(fact_contract_v3)**의 설계 과정을 상세히 다룹니다.
시리즈 이어 읽기
2~4주 정찰제 맞춤 개발
우리 회사 엑셀 업무도 웹 시스템으로 바꿀 수 있을까요?
사내 ERP를 무리하게 바꾸지 않고, 매달 반복되는 엑셀 병목만 독립 웹 시스템으로 2~4주 만에 전환합니다.
