chore: complete wiki-fication of remaining 00_Raw files

2026-04-25 22:54:21 +09:00
parent df275f935b
commit 8b6f51b719
5 changed files with 134 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Datacollector - processed 카운터 정체 및 엔진 루프 정지 감시 보강
+
+- 작성 시각: 2026-04-25 22:52:25 KST
+- 프로젝트: `/Volumes/Data/project/Antigravity/Datacollector`
+- 관련 파일: `src/lib/engine.ts`, `src/components/AgentDashboard.tsx`
+
+## 상황
+
+사용자는 작업이 되는 것처럼 보이지만 `processed` 수치가 계속 오르지 않고, 서버를 재시작하면 1개가 추가된 뒤 다시 멈춘 것처럼 보인다고 보고했다.
+
+## 확인한 내용
+
+브리지 서버 상태는 정상이고 `/api/health` 기준 `pendingRequests`도 0이었다. 따라서 서버 요청이 계속 물려 있는 문제보다는 프론트엔드 엔진 루프가 한 번 처리한 뒤 다음 반복으로 자연스럽게 이어지지 않는 가능성이 높았다.
+
+코드상 `processedCount`는 `executeTask()`가 마크다운 생성까지 끝낸 뒤 `store.incrementProcessed()`를 호출할 때만 오른다. 즉 카운터가 오르지 않는다는 것은 다음 중 하나일 가능성이 있다.
+
+- 다음 작업 합성이 아직 완료되지 않았다.
+- 프론트엔드 엔진 루프 타이머가 끊겼다.
+- UI 상태는 `running`인데 엔진 내부 싱글톤의 루프가 실제로는 잠든 상태가 되었다.
+
+## 조치
+
+`src/lib/engine.ts`:
+
+- `isLoopActive`, `lastActivityAt`, `loopTimer`를 추가했다.
+- `runLoop()` 중복 실행을 막으면서도, 루프가 잠든 경우 다시 깨울 수 있게 했다.
+- `kickIfStalled()`를 추가해 `running` 상태인데 45초 이상 루프 활동이 없으면 자동으로 다음 루프를 시작한다.
+- 다음 루프 예약을 `scheduleNextLoop()`로 통합해 타이머를 추적할 수 있게 했다.
+- 작업 완료 후 `processedCount`가 반영된 값을 로그로 남기도록 했다.
+
+`src/components/AgentDashboard.tsx`:
+
+- 상태가 `running`일 때 15초마다 엔진 heartbeat를 실행한다.
+- 엔진 루프가 잠든 것으로 판단되면 `kickIfStalled()`가 자동으로 다시 깨운다.
+
+## 검증
+
+다음 검증을 완료했다.
+
+```bash
+npm run lint
+```
+
+결과:
+
+- TypeScript 검사 통과
+
+## 운영 메모
+
+이제 작업 하나가 완료될 때 Mission Telemetry에 다음 형태의 로그가 추가된다.
+
+```text
+[ENGINE] '토픽명' 처리 카운트 반영 완료: N
+```
+
+이 로그가 보이면 `processed` 값도 함께 올라가는 것이 정상이다. 만약 이 로그가 보이지 않고 `최종 데이터 합성 중...` 이후 오래 멈춘다면, 그때는 카운터 문제가 아니라 NotebookLM 합성 요청이 오래 걸리거나 실패 응답을 기다리는 상태로 봐야 한다.
@@ -0,0 +1,27 @@
+# [[Performance Optimization]]
+
+## 📌 Brief Summary
+성능 최적화(Performance Optimization)는 웹 애플리케이션의 로딩 속도를 단축시키고 사용자 상호작용을 매끄럽게 만들기 위해 브라우저 렌더링 과정과 리소스 처리 방식을 개선하는 일련의 기술적 과정입니다 [1-3]. 주로 초기 렌더링 시간(Fast First Paint)을 앞당기고, 프레임 드롭(Jank)을 방지하며, 최대 콘텐츠풀 페인트(LCP)와 같은 핵심 웹 바이탈(Core Web Vitals) 지표를 향상하는 것을 목표로 합니다 [2-6]. 모던 프론트엔드에서는 중요 렌더링 경로(CRP)의 최소화, React와 같은 프레임워크 수준에서의 불필요한 렌더링 방지, 그리고 적절한 서버/클라이언트 렌더링 전략(SSR, SSG 등)의 선택을 통해 이루어집니다 [1, 7-9].
+
+## 📖 Core Content
+*   **중요 렌더링 경로(CRP) 최적화 및 브라우저 렌더링 제어**
+    *   브라우저가 HTML, CSS, JavaScript를 화면의 픽셀로 변환하는 '중요 렌더링 경로(Critical Rendering Path)'를 최적화하는 것이 가장 기본입니다 [1, 10]. 초기 렌더링 속도를 높이기 위해 렌더링을 차단하는 리소스를 지연시키거나 제거하며, 불필요한 DOM 노드의 깊이를 최소화해야 합니다 [8, 11, 12].
+    *   특히 계산 비용이 큰 레이아웃 재계산인 **리플로우(Reflow)**를 유발하는 속성(예: width, height, margin 조작) 사용을 최소화하고, 시각적 속성만 변경하는 리페인트(Repaint)나 GPU 가속 기반의 컴포지팅(Compositing) 기법을 활용하여 성능 저하를 방지해야 합니다 [6, 12-20].
+
+*   **React 프레임워크 레벨의 최적화 기법**
+    *   **리렌더링 폭포수(Re-render Cascade) 방지:** 부모 컴포넌트의 상태 변화가 무관한 자식 컴포넌트들의 렌더링까지 유발하는 것을 막기 위해 `React.memo`, `useMemo`, `useCallback`을 사용하여 얕은 비교를 통한 메모이제이션을 수행합니다 [21-25]. 
+    *   **자동 일괄 처리 (Automatic Batching):** React 18부터 도입된 기능으로, 네이티브 이벤트 핸들러뿐만 아니라 비동기 작업(Promise, setTimeout 등) 내에서 발생하는 여러 상태 업데이트들을 하나로 묶어(Batching) 단 한 번의 리렌더링만 발생하도록 하여 렌더링 성능을 극대화합니다 [26-33].
+    *   **동시성 렌더링 (Concurrent Rendering):** `useTransition` 및 `useDeferredValue` 훅을 사용하여 무거운 연산을 후순위로 미루고(Non-urgent), 사용자의 타이핑이나 클릭 같은 긴급한 상호작용(Urgent)을 우선적으로 처리함으로써 UI가 멈추는 현상을 방지합니다 [34-38].
+    *   **가상화 및 코드 분할:** 수백 개 이상의 긴 목록은 화면에 보이는 항목만 DOM 노드로 생성하는 가상화(Virtualization)를 적용하며 [39, 40], `React.lazy()`를 활용한 라우트 수준의 코드 분할(Code Splitting)로 초기 자바스크립트 번들 크기를 줄여 LCP 점수를 개선합니다 [41].
+
+*   **아키텍처 및 렌더링 전략 최적화**
+    *   애플리케이션 특성에 맞춰 **CSR(클라이언트 사이드 렌더링)**, **SSR(서버 사이드 렌더링)**, **SSG(정적 사이트 생성)**, **ISR(점진적 정적 재생성)** 등을 적절히 선택하거나 혼합(Hybrid)하여 사용합니다 [42-60]. 
+    *   최근 도입된 **[[React Server Components]] (RSC)**는 브라우저로 전송되는 자바스크립트 번들 크기를 '0 바이트'로 줄이고 서버 측 자원(DB 등)에 직접 접근하여 렌더링 된 HTML만을 스트리밍 형태로 클라이언트에 전달하므로, 클라이언트 측의 렌더링 및 하이드레이션(Hydration) 부하를 혁신적으로 제거합니다 [61-66].
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Critical Rendering Path]], [[Reflow and Repaint]], [[Automatic Batching]], [[React Compiler]], [[Virtual DOM]], [[Server-Side Rendering (SSR)]], [[React Server Components]]
+- **Projects/Contexts:** [[React 18 Concurrent Features]], [[Next.js App Router]]
+- **Contradictions/Notes:** 과거에는 개발자가 수동으로 `useMemo`나 `useCallback`, `React.memo`를 삽입하여 불필요한 리렌더링을 최적화해야 했으나, 최근 안정화된 **React Compiler**는 빌드 타임에 코드와 데이터 흐름을 분석하여 이러한 메모이제이션 경계를 자동으로 삽입해 줍니다. 따라서 이제 수동 메모이제이션은 컴파일러의 자동 처리에 의존하게 되어 대부분 제거될 수 있으나, 효과적인 의존성 제어나 서드파티 라이브러리 통합 등 특수한 예외 상황의 '비상 탈출구(Escape Hatch)' 용도로만 제한적으로 남게 됩니다 [25, 67-72].
+
+---
+*Last updated: 2026-04-25*
@@ -0,0 +1,24 @@
+# [[React 18]]
+
+## 📌 Brief Summary
+React 18은 렌더링 과정을 최적화하여 프론트엔드 성능을 크게 향상시키는 기능을 도입한 주요 버전입니다 [1-3]. 이 버전의 가장 핵심적인 특징은 '자동 일괄 처리(Automatic Batching)'가 기본적으로 활성화되어, 다양한 비동기 작업의 상태 업데이트를 하나로 묶어 처리한다는 점입니다 [3-5]. 이를 통해 불필요한 리렌더링을 방지하고 애플리케이션의 반응성과 전체적인 프레임 속도를 매끄럽게 개선합니다 [2, 6, 7].
+
+## 📖 Core Content
+* **자동 일괄 처리(Automatic Batching)의 전면 적용**
+  React 18 이전에는 `onClick`이나 `onChange` 같은 React의 네이티브 이벤트 핸들러 내부의 업데이트만 일괄 처리되었습니다 [2, 8, 9]. 하지만 React 18부터는 프로미스(Promises), `setTimeout`, `async/await` 함수와 같은 비동기 작업 내에서 발생하는 상태 업데이트까지 출처에 상관없이 자동으로 일괄 처리합니다 [2, 5, 8, 9]. 즉, 빠른 시간 내에 여러 상태 업데이트가 발생해도 DOM을 한 번만 업데이트하여 성능 병목 현상을 방지합니다 [4, 6, 10, 11].
+
+* **가상 DOM(Virtual DOM) Diffing 프로세스 경량화**
+  여러 상태 변화를 한 번의 리렌더링으로 결합함으로써 가상 DOM의 Diffing 작업 횟수 자체가 줄어듭니다 [12]. 또한 `React.memo`나 `useMemo` 등을 통해 메모이제이션된 값에 대한 검사 횟수도 줄어들어, 렌더링 주기 당 CPU 작업량이 대폭 감소합니다 [12]. 실제 데이터 집약적인 대시보드를 대상으로 한 벤치마크에 따르면, 자동 일괄 처리를 통해 전체 렌더링 횟수가 약 40% 감소하고 최대 부하 시 프레임 속도가 25% 향상되었습니다 [1, 13].
+
+* **업데이트 우선순위 제어 기능 (startTransition & flushSync)**
+  React 18은 렌더링 우선순위를 개발자가 직접 제어할 수 있는 API를 제공합니다 [13].
+  * **`startTransition`**: 목록 필터링과 같이 무겁고 긴급하지 않은 상태 업데이트를 표시하여, 사용자의 타이핑이나 클릭 같은 긴급한 인터랙션을 차단하지 않도록 양보(yield)합니다 [13, 14].
+  * **`flushSync`**: 즉각적인 UI 업데이트가 필수적인 경우(예: 상태 변경 직후의 입력 포커스 지정 등), React가 업데이트를 강제로 동기식으로 반영하게 만들어 자동 일괄 처리에서 예외로 둘 수 있습니다 [7, 13-15]. 
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Automatic Batching]], [[Virtual DOM]], [[startTransition]], [[flushSync]]
+- **Projects/Contexts:** [[React Performance Optimization]]
+- **Contradictions/Notes:** 소스에 따르면 `flushSync`를 사용해 자동 일괄 처리를 막을 수 있지만, 이를 남용하면 일괄 처리로 얻을 수 있는 성능 이점이 무효화될 수 있으므로 꼭 필요한 경우에만 제한적으로 사용해야 합니다 [7, 16].
+
+---
+*Last updated: 2026-04-25*
@@ -0,0 +1,27 @@
+# [[Performance Optimization]]
+
+## 📌 Brief Summary
+성능 최적화(Performance Optimization)는 웹 애플리케이션의 로딩 속도를 단축시키고 사용자 상호작용을 매끄럽게 만들기 위해 브라우저 렌더링 과정과 리소스 처리 방식을 개선하는 일련의 기술적 과정입니다 [1-3]. 주로 초기 렌더링 시간(Fast First Paint)을 앞당기고, 프레임 드롭(Jank)을 방지하며, 최대 콘텐츠풀 페인트(LCP)와 같은 핵심 웹 바이탈(Core Web Vitals) 지표를 향상하는 것을 목표로 합니다 [2-6]. 모던 프론트엔드에서는 중요 렌더링 경로(CRP)의 최소화, React와 같은 프레임워크 수준에서의 불필요한 렌더링 방지, 그리고 적절한 서버/클라이언트 렌더링 전략(SSR, SSG 등)의 선택을 통해 이루어집니다 [1, 7-9].
+
+## 📖 Core Content
+*   **중요 렌더링 경로(CRP) 최적화 및 브라우저 렌더링 제어**
+    *   브라우저가 HTML, CSS, JavaScript를 화면의 픽셀로 변환하는 '중요 렌더링 경로(Critical Rendering Path)'를 최적화하는 것이 가장 기본입니다 [1, 10]. 초기 렌더링 속도를 높이기 위해 렌더링을 차단하는 리소스를 지연시키거나 제거하며, 불필요한 DOM 노드의 깊이를 최소화해야 합니다 [8, 11, 12].
+    *   특히 계산 비용이 큰 레이아웃 재계산인 **리플로우(Reflow)**를 유발하는 속성(예: width, height, margin 조작) 사용을 최소화하고, 시각적 속성만 변경하는 리페인트(Repaint)나 GPU 가속 기반의 컴포지팅(Compositing) 기법을 활용하여 성능 저하를 방지해야 합니다 [6, 12-20].
+
+*   **React 프레임워크 레벨의 최적화 기법**
+    *   **리렌더링 폭포수(Re-render Cascade) 방지:** 부모 컴포넌트의 상태 변화가 무관한 자식 컴포넌트들의 렌더링까지 유발하는 것을 막기 위해 `React.memo`, `useMemo`, `useCallback`을 사용하여 얕은 비교를 통한 메모이제이션을 수행합니다 [21-25]. 
+    *   **자동 일괄 처리 (Automatic Batching):** React 18부터 도입된 기능으로, 네이티브 이벤트 핸들러뿐만 아니라 비동기 작업(Promise, setTimeout 등) 내에서 발생하는 여러 상태 업데이트들을 하나로 묶어(Batching) 단 한 번의 리렌더링만 발생하도록 하여 렌더링 성능을 극대화합니다 [26-33].
+    *   **동시성 렌더링 (Concurrent Rendering):** `useTransition` 및 `useDeferredValue` 훅을 사용하여 무거운 연산을 후순위로 미루고(Non-urgent), 사용자의 타이핑이나 클릭 같은 긴급한 상호작용(Urgent)을 우선적으로 처리함으로써 UI가 멈추는 현상을 방지합니다 [34-38].
+    *   **가상화 및 코드 분할:** 수백 개 이상의 긴 목록은 화면에 보이는 항목만 DOM 노드로 생성하는 가상화(Virtualization)를 적용하며 [39, 40], `React.lazy()`를 활용한 라우트 수준의 코드 분할(Code Splitting)로 초기 자바스크립트 번들 크기를 줄여 LCP 점수를 개선합니다 [41].
+
+*   **아키텍처 및 렌더링 전략 최적화**
+    *   애플리케이션 특성에 맞춰 **CSR(클라이언트 사이드 렌더링)**, **SSR(서버 사이드 렌더링)**, **SSG(정적 사이트 생성)**, **ISR(점진적 정적 재생성)** 등을 적절히 선택하거나 혼합(Hybrid)하여 사용합니다 [42-60]. 
+    *   최근 도입된 **[[React Server Components]] (RSC)**는 브라우저로 전송되는 자바스크립트 번들 크기를 '0 바이트'로 줄이고 서버 측 자원(DB 등)에 직접 접근하여 렌더링 된 HTML만을 스트리밍 형태로 클라이언트에 전달하므로, 클라이언트 측의 렌더링 및 하이드레이션(Hydration) 부하를 혁신적으로 제거합니다 [61-66].
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Critical Rendering Path]], [[Reflow and Repaint]], [[Automatic Batching]], [[React Compiler]], [[Virtual DOM]], [[Server-Side Rendering (SSR)]], [[React Server Components]]
+- **Projects/Contexts:** [[React 18 Concurrent Features]], [[Next.js App Router]]
+- **Contradictions/Notes:** 과거에는 개발자가 수동으로 `useMemo`나 `useCallback`, `React.memo`를 삽입하여 불필요한 리렌더링을 최적화해야 했으나, 최근 안정화된 **React Compiler**는 빌드 타임에 코드와 데이터 흐름을 분석하여 이러한 메모이제이션 경계를 자동으로 삽입해 줍니다. 따라서 이제 수동 메모이제이션은 컴파일러의 자동 처리에 의존하게 되어 대부분 제거될 수 있으나, 효과적인 의존성 제어나 서드파티 라이브러리 통합 등 특수한 예외 상황의 '비상 탈출구(Escape Hatch)' 용도로만 제한적으로 남게 됩니다 [25, 67-72].
+
+---
+*Last updated: 2026-04-25*