📝 주석 추가

TASK.md

@@ -1,67 +0,0 @@
-## Redis 기반 임베딩 큐 도입 계획
-
-### 1. 적합성 검토
-- 기존 Node.js 임베딩 API는 유지하면서도 Redis 큐를 사이에 두면 Spring Boot → Node.js 간의 느슨한 결합과 재시도를 확보할 수 있음.
-- Spring Boot 프로듀서는 이미 Redis LPUSH 로직을 보유하고 있어 추가 개발 부담이 낮음.
-- Node.js 컨슈머는 BRPOP 기반 무한 루프로 구현 가능하며, 현재 OpenAI 임베딩 호출 흐름과 자연스럽게 연결됨.
-- Redis 리스트는 선입선출 특성을 제공하고, 장애 시 실패 큐(`embedding:failed`)로 분리하여 운영팀이 모니터링/재처리하기 용이함.
-- 고가용성 Redis 인프라가 전제돼야 하며, 큐 적체/중복 처리에 대한 모니터링과 알람 체계가 필요함.
-
-### 2. 아키텍처 개요
-```
-[Spring Boot] → LPUSH → [Redis List embedding:queue] → BRPOP → [Node.js Consumer] → OpenAI 임베딩 → DB 저장
-                                                              ↘ 실패 시 LPUSH embedding:failed
-```
-
-### 3. 구현 계획
-1. **컨슈머 워커 초안 작성**
-   - `services/embedding.service.ts` 를 호출하는 `processEmbeddingQueue` 모듈 작성.
-   - Graceful shutdown, Concurrency(동시 워커 수) 옵션, 로깅(성공/실패/처리시간)을 포함.
-2. **큐 메시지 스키마 확정**
-   - `post_id`, `title`, `content`, `retryCount` 등을 포함하는 JSON 구조 정의 및 문서화.
-   - 추후 schema 변경 대비 버전 필드 도입 검토.
-3. **실패 처리 및 재시도 정책**
-   - 실패 시 `embedding:failed` 로 이동 후 경고 로그 기록.
-   - 재시도 워커(주기적 RPOP → LPUSH) 또는 Ops 수동 트리거 전략 결정.
-4. **운영 모니터링**
-   - `LLEN embedding:queue`, `embedding:failed` 메트릭을 Prometheus/Grafana 또는 기존 모니터링에 연동.
-   - 알람 기준: 큐 길이 임계치, 실패 큐 누적, 워커 미응답.
-5. **배포 전략**
-   - Node.js 컨슈머를 기존 서버 프로세스와 분리( Docker 컨테이너)하여 독립 운영.
-   - Spring Boot 측은 이미 구현된 LPUSH 로직을 활성화하고, 기존 REST 임베딩 호출은 점진적으로 감축.
-
-### 4. 추가 고려사항
-- 멱등성 확보를 위해 컨슈머 처리 완료 후 Redis 측에서 메시지를 제거했는지(이미 BRPOP 로 제거) 확인하고, 실패 재처리 시 중복 삽입 방지 로직 검토.
-- OpenAI API 호출 실패 시 exponential backoff 적용 여부.
-- 긴 콘텐츠 임베딩 시 chunking 로직(`chunkText`)과 큐 메시지 크기 제한 검토.
-- 보안: Redis 접근 제어, TLS 필요 여부 확인.
-
-### 5. 다음 단계
-- [x] Node.js 컨슈머 초안 코드 작성 및 환경 변수(`REDIS_URL`, `EMBEDDING_QUEUE_KEY`) 정리.
-- [ ] 개발 환경에서 Redis 로컬 인스턴스와 통합 테스트 진행.
-- [ ] 모니터링/알람 구성 논의.
-
-### 6. 컨테이너/배포 설계
-- **기본 이미지 재사용**: 기존 `Dockerfile` 로 빌드한 동일 이미지를 `api`(Express)와 `worker`(컨슈머)가 공유, 각 컨테이너는 `command` 만 다르게 지정.
-- **엔트리포인트 분리**: `src/worker/queue-consumer.ts` 추가 → `tsc` 결과가 `dist/worker/queue-consumer.js` 로 생성되도록 빌드 경로 확인. `package.json` 에 `worker` 스크립트(`node dist/worker/queue-consumer.js`) 등록.
-- **Docker Compose 초안**
-  ```yaml
-  services:
-    api:
-      build: .
-      command: ["node", "dist/server.js"]
-      ports: ["3000:3000"]
-      env_file: .env
-      depends_on: [redis]
-
-    worker:
-      build: .
-      command: ["node", "dist/worker/queue-consumer.js"]
-      env_file: .env
-      depends_on: [redis]
-
-    redis:
-      image: redis:7-alpine
-  ```
-- **환경 변수 공유**: `.env` 에 Redis 접속 정보(`REDIS_HOST`, `REDIS_PORT`, `REDIS_URL` 등)와 큐 이름, 실패 큐 이름 등을 명시하고 두 서비스 모두 로드.
-- **운영 고려**: `worker` 컨테이너 스케일 아웃(예: `docker compose up --scale worker=3`)에 대비해 작업 멱등성 확인. 장애 시 개별 컨테이너 재시작 전략, 로그 수집 경로(예: stdout→EFK) 정의.

src/app.ts

@@ -4,6 +4,7 @@ import aiRouter from './routes/ai.routes';
 import aiV2Router from './routes/ai.v2.routes';
 import searchRouter from './routes/search.routes';
 
+// Express 애플리케이션과 공용 미들웨어를 초기화
 const app: Express = express();
 
 // CORS 설정
@@ -26,7 +27,8 @@ app.use('/ai', aiRouter);
 app.use('/ai/v2', aiV2Router);
 app.use('/search', searchRouter);
 
-// Central Error Handler
+// 중앙 에러 처리기
+// 전역 에러 처리기로 예기치 못한 서버 오류를 JSON으로 반환
 app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
   console.error(err.stack);
   res.status(500).json({ 

src/config.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 
 dotenv.config();
 
+// 환경 변수를 스키마로 검증하여 타입 안전한 설정 객체 생성
 const configSchema = z.object({
   NODE_ENV: z.string().default('development'),
   PORT: z.coerce.number().default(3000),

src/controllers/ai.controller.ts

@@ -14,6 +14,7 @@ export const embedTitleHandler = async (
   res: Response,
   next: NextFunction
 ) => {
+  // 포스트 제목 임베딩을 생성하고 저장
   try {
     const { post_id, title } = req.body;
     await storeTitleEmbedding(post_id, title);
@@ -28,6 +29,7 @@ export const embedContentHandler = async (
   res: Response,
   next: NextFunction
 ) => {
+  // 본문을 청크 단위로 임베딩 생성 후 DB에 반영
   try {
     const { post_id, content } = req.body;
     const chunks = chunkText(content);
@@ -49,29 +51,30 @@ export const askHandler = async (
   res: Response,
   next: NextFunction
 ) => {
+  // RAG 기반 QA 결과를 SSE 스트림으로 클라이언트에 전달
   try {
     const { question, user_id, category_id, speech_tone, post_id, llm } = req.body as any;
 
-    // SSE headers and anti-buffering hints
+    // SSE를 위한 헤더 설정과 버퍼링 완화 옵션
     res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
     res.setHeader('Cache-Control', 'no-cache, no-transform');
     res.setHeader('Connection', 'keep-alive');
-    // Nginx buffering off
+    // Nginx 버퍼링 비활성화
     res.setHeader('X-Accel-Buffering', 'no');
-    // Flush headers early so clients start processing immediately
+    // 헤더를 먼저 전송해 클라이언트 처리를 즉시 시작
     (res as any).flushHeaders?.();
-    // Reduce Nagle’s algorithm buffering on the socket for faster flush
+    // 소켓의 네이글 알고리즘 버퍼링을 줄여 전송 지연 완화
     (res.socket as any)?.setNoDelay?.(true);
-    // Prime the SSE stream to break proxy buffering thresholds
+    // 프록시 버퍼링 임계값을 넘기기 위한 초기 keep-alive 전송
     res.write(':ok\n\n');
 
     const stream = await answerStream(question, user_id, category_id, speech_tone, post_id, llm);
-    // Manually bridge to ensure flushing of SSE deltas
+    // SSE 델타가 즉시 전송되도록 수동 브리징
     stream.on('data', (chunk) => {
       const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
       res.write(buf);
       const canFlush = typeof (res as any).flush === 'function';
-      // try to flush if supported by runtime/middleware
+      // 런타임 또는 미들웨어가 지원하면 즉시 플러시
       (res as any).flush?.();
       DebugLogger.log('sse', { type: 'debug.sse.write', at: Date.now(), bytes: buf.length, flushed: canFlush });
     });
@@ -82,7 +85,7 @@ export const askHandler = async (
       res.end();
     });
 
-    // Cleanup if client disconnects
+    // 클라이언트 연결이 끊기면 스트림 자원 해제
     req.on('close', () => {
       try {
         stream.destroy();

src/controllers/ai.v2.controller.ts

@@ -7,6 +7,7 @@ export const askV2Handler = async (
   res: Response,
   next: NextFunction
 ) => {
+  // 검색 계획 기반 v2 QA를 SSE로 중계
   try {
     const { question, user_id, category_id, speech_tone, post_id, llm } = req.body as any;
     res.setHeader('Content-Type', 'text/event-stream');
@@ -26,4 +27,3 @@ export const askV2Handler = async (
     next(error);
   }
 };
-

src/controllers/search.controller.ts

@@ -4,6 +4,7 @@ import { runHybridSearch } from '../services/hybrid-search.service';
 import { runSemanticSearch } from '../services/semantic-search.service';
 import { aggregatePosts } from '../services/search-aggregate.service';
 
+// 하이브리드 검색 API로 질문을 받아 검색 계획과 결과를 반환
 export const hybridSearchHandler = async (req: Request, res: Response) => {
   try {
     const question = String(req.query.question || '').trim();

src/llm/index.ts

@@ -9,6 +9,7 @@ import config from '../config';
 import { randomUUID } from 'crypto';
 import { DebugLogger } from '../utils/debug-logger';
 
+// LLM 제공자별 스트림을 추상화하여 공통 SSE 포맷으로 반환
 export const generate = async (req: GenerateRequest): Promise<PassThrough> => {
   const merged = { ...req };
   if (!merged.provider || !merged.model) {
@@ -23,13 +24,13 @@ export const generate = async (req: GenerateRequest): Promise<PassThrough> => {
   const model = merged.model as string;
   const provider = merged.provider as string;
 
-  // Pre-call logging: prompt tokens + estimated input cost
+  // 호출 전에 프롬프트 토큰 수와 예상 입력 비용을 기록
   const messages = merged.messages || [];
   let promptTokens = 0;
   try {
     promptTokens = countChatMessagesTokens(messages as any, model);
   } catch {
-    // ignore
+    // 무시
   }
   const pricing = getModelPricing(model);
   const estInputCost = pricing ? calcCost(promptTokens, pricing.input_per_1k) : 0;
@@ -63,20 +64,20 @@ export const generate = async (req: GenerateRequest): Promise<PassThrough> => {
           return s;
         })();
 
-  // Wrap provider stream to accumulate output tokens
+  // 공급자 스트림을 감싸 출력 토큰을 집계
   const outer = new PassThrough();
   let buffer = '';
   let outputText = '';
 
-  // Debug: start info
+  // 디버그: 호출 시작 정보
   try {
     DebugLogger.log('llm', { type: 'debug.llm.start', provider, model, messages: (messages || []).length });
   } catch {}
 
   const flushBuffer = () => {
-    // Split by double newline to get SSE events
+    // 두 줄바꿈을 기준으로 SSE 이벤트 단위로 분할
     const chunks = buffer.split('\n\n');
-    // Keep last partial
+    // 마지막 미완성 조각은 버퍼에 보존
     buffer = chunks.pop() || '';
     for (const block of chunks) {
       const lines = block.split('\n');

src/llm/model-registry.ts

@@ -5,8 +5,8 @@ type ModelEntry = {
   modelId: string;
 };
 
-// Minimal registry for now; can expand with tokenizer/pricing later.
+// 현재는 기본 레지스트리만 제공하며 추후 토크나이저나 과금 정보로 확장 가능
 const DEFAULT_CHAT: ModelEntry = { provider: 'openai', modelId: 'gpt-5-mini' };
 
+// 프로젝트 기본 채팅 모델 정보를 반환
 export const getDefaultChat = (): ModelEntry => DEFAULT_CHAT;
-

src/llm/providers/gemini.ts

@@ -2,17 +2,18 @@ import { PassThrough } from 'stream';
 import config from '../../config';
 import { GenerateRequest } from '../types';
 
-// Using @google/genai per project plan; keep types loose for compatibility
+// 프로젝트 계획에 따라 @google/genai를 사용하며 호환성을 위해 타입을 느슨하게 유지
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { GoogleGenAI } = require('@google/genai');
 
 const buildPromptFromMessages = (messages: { role: string; content: string }[]) => {
-  // Simple concatenation preserving roles
+  // 역할 정보를 유지한 채 단순 연결
   return messages
     .map((m) => `[${m.role}]\n${m.content}`)
     .join('\n\n');
 };
 
+// Gemini SDK를 호출해 응답 텍스트를 SSE로 분할
 export const generateGeminiStream = async (req: GenerateRequest): Promise<PassThrough> => {
   const stream = new PassThrough();
   try {
@@ -37,7 +38,7 @@ export const generateGeminiStream = async (req: GenerateRequest): Promise<PassTh
     const thinkingBudget = parseInt(process.env.GEMINI_THINKING_BUDGET || '0', 10) || 0;
     const configBlock: any = thinkingBudget > 0 ? { thinkingConfig: { thinkingBudget } } : {};
 
-    // Non-streaming first, then chunk SSE
+    // 먼저 동기 호출로 응답을 받고 이후 SSE 조각으로 분할
     const result = await ai.models.generateContent({
       model: modelId,
       contents: [
@@ -50,7 +51,7 @@ export const generateGeminiStream = async (req: GenerateRequest): Promise<PassTh
       config: configBlock,
     });
 
-    // Try common text access paths
+    // 응답 텍스트를 얻기 위한 여러 접근 경로를 시도
     const outputText = (result?.response?.text && result.response.text()) || (result?.text && result.text()) || '';
 
     const finalText = typeof outputText === 'string' ? outputText : '';
@@ -72,4 +73,3 @@ export const generateGeminiStream = async (req: GenerateRequest): Promise<PassTh
     return stream;
   }
 };
-