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)로 통합합니다. 이 세 가지만 있으면 서버가 완전히 붕괴되어도 다른 환경에서 즉시 복호화 및 서비스 재개가 가능합니다.