brain_dogfood/docs/logic_flow.md

# ⚙️ 로직 흐름 및 비즈니스 규칙 (v5.0+)

본 문서는 `뇌사료` 프로젝트 내부에서 작동하는 특수 로직들과 데이터 처리 규칙을 상세히 설명합니다.

## 🔒 1. 암호화 전이 및 보안 로직
본 시스템은 메모의 보안 상태 변화에 따른 정교한 전이 로직을 가지고 있습니다.

### 1.1 암호화 해제 시 상태 전이
- **명시적 해제**: 사용자가 비밀번호를 입력하여 암호화를 해제하고 저장하는 경우, 해당 메모는 **평문(Plaintext)** 상태로 전환됩니다. 이는 사용자의 명시적 의사 결정으로 간주합니다.
- **수정 시 유지**: 암호화된 상태에서 내용만 수정할 경우, 기존 비밀번호를 사용하여 백엔드에서 다시 암호화(Re-encrypt) 과정을 거쳐 저장됩니다.

### 1.2 첨부파일 접근 제어 (403 해결)
- **인증 연동**: `/api/download` 라우트는 단순히 파일 존재 여부만 체크하지 않고, 사용자의 **세션 로그인 여부**를 확인합니다.
- **인라인 표시**: 이미지 파일의 경우 `Content-Disposition: inline` 헤더를 강제하여 브라우저 마크다운 본문 내에서 선명하게 렌더링되도록 지원합니다.

---

## 🌌 2. 지식 네뷸라 성단(Constellation) 로직
D3.js 엔진은 데이터 간의 명시적 링크 외에도 의미론적 연결을 자동으로 시뮬레이션합니다.

### 2.1 자동 연결 규칙 (Semantic Linking)
1. **명시적 링크**: `[[#ID]]` 패턴으로 작성된 내부 링크 (실선 표시).
2. **비주얼 노드 링커 (Interactive Linker)**: 
    - **절차**: Alt + Badge 클릭 (Source) -> 다른 Badge 클릭 (Target) -> Target ID를 Source의 본문에 자동 추가 -> DB 저장 및 UI 갱신.
    - **좌표 동기화**: `requestAnimationFrame`을 통해 마우스 커서와 SVG 연결선의 실시간 좌표를 동기화하여 지연 없는 드래잉을 구현합니다.
3. **동일 그룹**: 같은 그룹에 속한 메모들끼리 부유하며 성단을 형성 (은은한 연결선).
4. **공통 태그**: 같은 태그를 공유하는 메모들 사이에 인력이 작용하여 근접 배치.

### 2.2 메타데이터 보호 및 이미지 보정
- **후처리 로직**: 마크다운 본문의 `img src="photo.png"`와 같은 상대 경로를 `fixImagePaths` 유틸리티가 감지하여 `/api/download/photo.png`로 자동 보정합니다.
- **즉시 수정 (e-key Logic)**: 전역 `keydown` 리스너가 마우스가 위치한 메모 ID(`window.hoveredMemoId`)를 감지하여 즉시 수정 모달을 호출합니다.

---

---

## 🔄 3. 애플리케이션 라이프사이클 및 데이터 흐름
### 3.1 초기화 및 갱신 사이클 (App Cycle)
1. **DOM 로드**: `DOMContentLoaded` 발생 시 모든 매니저(`Editor`, `Heatmap`, `Visualizer` 공히)가 `init()`을 거칩니다.
2. **데이터 호출**: `AppService.refreshData()`가 실행되어 첫 페이지 메모를 가져옵니다.
3. **병렬 동기화**: 메모 데이터 수신 시 `HeatmapManager.refresh()`가 별도 API를 호출하여 최근 1년(또는 선택 기간)의 통계를 가져와 렌더링합니다.

### 3.2 검색 및 실시간 필터링 (Debounce)
- **지연 처리**: 검색창 입력 시 300ms의 `searchTimer`가 작동하여 불필요한 API 요청을 최소화합니다.
- **상태 통합**: 검색어는 그룹/날짜 필터와 결합되어 중앙 상태(`AppService.state`)에서 관리됩니다.

### 3.3 무한 스크롤 및 페이징 (Infinite Scroll)
- **오프셋 제어**: `this.state.offset`을 통해 현재 로드된 개수를 추적하며, 하단 도달 시 `limit` 단위로 다음 데이터를 추가 로드합니다.

---

## 🚀 4. 정밀 배포 및 재난 복구 로직

### 4.1 수술적 정리 (Surgical Cleanup)
- **보호 대상**: `.env`, `data/`, `static/uploads/`, `memos.db` 등 사용자의 생성 데이터는 삭제 목록에서 철저히 제외됩니다.
- **정밀 삭제**: 부모 폴더(예: `static`)를 지우지 않고 그 내부의 코드(JS, CSS)만 선별 삭제하여, 하위의 보호 폴더(`uploads`) 유실을 방지합니다.

### 4.2 핵심 자산 백업 (Disaster Recovery)
- **3대 요소**: DB, 첨부파일, 환경설정(.env)을 하나의 압축파일(`tar.gz`)로 통합합니다. 이 세 가지만 있으면 서버가 완전히 붕괴되어도 다른 환경에서 즉시 복호화 및 서비스 재개가 가능합니다.