시리즈: 모듈형 평가 엔진 구축하기 (8/10)

이전 포스트에서는 개별 모듈들을 다루었습니다. 이번 포스트에서는 이들을 하나로 묶어주는 접착제 역할을 하는 부분을 다룹니다. 즉, 사용자의 단일 입력을 받아 지식 생성(knowledge creation), AI 계획(AI planning), 스트리밍 실행(streaming execution), 그리고 발행(publishing)까지 이끌어가는 newapp.html의 프론트엔드 파이프라인(frontend pipeline)에 대해 설명합니다. 이 모든 과정은 단 하나의 SSE(Server-Sent Events) 연결을 통해 이루어집니다.

사용자 경험 (The User Experience)

사용자는 텍스트 박스를 보게 됩니다. 사용자는 문서, URL, 또는 "직장 스트레스 평가 도구 만들기"와 같은 문장 등 자신의 요청 사항을 입력(또는 붙여넣기)합니다. 그러면 두 개의 버튼이 나타납니다:

• 검토 및 수정 (Review & Edit) — 실행 전 AI의 계획을 확인합니다.
• 직접 생성 (Create Directly) — 계획 검토를 건너뛰고 즉시 생성 단계로 넘어갑니다.

어떤 방식을 선택하든 파이프라인은 동일합니다. 유일한 차이점은 사용자가 실행 전에 계획을 확인하고 수정할 수 있는지 여부뿐입니다.

4단계 파이프라인 (The Four-Phase Pipeline)

Phase 1: 생성 (Generate)     → POST /api/v1/fetch/generate
Phase 2: 계획 (Plan, SSE)   → SSE  /api/v1/assess/v1/chat (plan mode)
Phase 3: 실행 (Execute, SSE) → SSE /api/v1/assess/v1/chat (execute mode)
...

Phase 1: 지식 + 앱 스켈레톤 (Knowledge + App Skeleton)

const res = await $server.post('/api/v1/fetch/generate', {
    name: title,
    content: reqContent,           // 붙여넣은 텍스트
...

이 호출은 세 가지 작업을 수행합니다:

1. 입력값(텍스트, URL 또는 파일 첨부물)으로부터 지식 베이스(knowledge base)를 생성합니다.
2. 앱 스켈레톤(app skeleton) (빈 Flower 도메인 객체)을 생성합니다.
3. 계획 에이전트(plan agent)를 위한 구조화된 입력(structured input)을 반환합니다.

응답에는 다음이 포함됩니다:

• appId — 새 앱의 ID
• input — 컨텍스트 태그(context tags)가 포함된 구조화된 입력
• displayContent — 텍스트 영역(textarea)에 표시될 깔끔한 텍스트 (태그 없음)

Phase 2: 계획 (SSE 스트림) (Plan (SSE Stream))

runPlanPhase(appId, input, option) {
    this.startPlanLoadingTimer();
    $agent.assessChat(appId, input, null, (event, data) => {
...

계획 단계는 사용자 입력을 AssessAgent로 전송하며, 이 에이전트는 다음과 같은 역할을 수행합니다:

1. agents/assess-plan.md를 시스템 프롬프트 (system prompt)로 로드합니다.
2. 사용 가능한 기술 목록 (skill list)을 동적으로 주입합니다.
3. AI 모델을 호출합니다.
4. YAML 응답을 AssessPlan 객체로 파싱 (parse)합니다.
5. 계획을 plan 이벤트로 다시 스트리밍 (stream)합니다.

로딩 메시지 문제 (The Loading Message Problem)

AI 계획 수립에는 10~30초가 소요됩니다. 그동안 사용자는 로딩 스피너 (loading spinner)를 바라보며 기다려야 합니다. 만약 15초 동안 아무런 변화가 없다면, 사용자는 시스템이 고장 났다고 판단하고 이탈합니다.

해결책은 8초마다 메시지를 교체하는 **점진적 로딩 메시지 타이머 (progressive loading message timer)**를 사용하는 것입니다:

const steps = [
    'newapp.loading.plan',
    'newapp.loading.plan_step1',  // "사용자의 요청을 분석하는 중..."
...

이 메시지들은 심미적 (cosmetic) 용도입니다. 즉, 실제 진행 상황을 반영하는 것은 아닙니다. 하지만 사용자에게 무언가 진행되고 있다는 느낌을 줍니다. SSE 하트비트 (heartbeats, 메시지 순환을 진행시키는 역할)와 결합하여, 사용자는 항상 변화하는 콘텐츠를 보게 됩니다.

이것이 정직한 방식일까요? 부분적으로 그렇습니다. 메시지들은 우리가 정확한 진행률을 추적할 수는 없더라도, AI가 개념적으로 무엇을 하고 있는지(분석 중, 차원 설계 중, 점수 계획 중 등)를 설명합니다. 이는 정적인 스피너보다 훨씬 낫습니다.

단계 3: 실행 (SSE 스트림) (Phase 3: Execute (SSE Stream))

startExecute() {
    this.stage = 'executing';
    const plan = Object.assign({}, this.currentPlan);
...

실행 단계는 AssessAgent의 execute() 메서드를 구동합니다. 이벤트가 다음과 같이 다시 흘러나옵니다:

SSE 이벤트 처리 (The SSE Event Processing)

onExecuteEvent(event, data) {
    if (event === 'task.start' && data) {
        const t = this.findProgTask(data.taskId);
...

각 이벤트는 실시간으로 UI를 업데이트합니다. 사용자는 다음과 같은 과정을 보게 됩니다:

1. "양식 설계 중..." (Designing form...) → 실행 중 (running)
2. "필드 생성됨: workload_1" (Created field: workload_1) → 설명 업데이트
3. "필드 생성됨: workload_2" (Created field: workload_2) → 설명 업데이트
4. "양식 완료" (Form complete) → 작업 완료 (task done)
5. "점수 설정 중..." (Configuring scoring...) → 다음 작업 시작

이러한 투명성은 신뢰를 구축합니다. 사용자는 단순히 스피너만 보는 것이 아니라, AI가 실제로 작동하고 있는 모습을 볼 수 있습니다.

단계 4: 완료 (Phase 4: Completion)

async onPlanDone() {
    if (this.isDone) return;
    this.isDone = true;
...

600ms의 지연 시간은 의도된 것입니다. 이는 화면이 전환되기 전에 마지막 진행 애니메이션 (progress animation)이 완료되도록 합니다. 이 지연이 없다면 전환 과정이 부자연스럽게 느껴집니다.

지식 베이스 입력 모드 (The Knowledge Base Input Modes)

파이프라인은 서로 다른 전처리 (preprocessing) 과정을 가진 네 가지 입력 모드를 처리합니다:

contentPreprocessed 플래그가 중요합니다. 파일이 업로드될 때, 프론트엔드 (frontend)는 이미 콘텐츠를 포맷팅하기 위해 AI 추출 단계를 실행합니다. 만약 백엔드 (backend)가 이를 다시 압축하려고 시도하면, 이중 처리 (double-processes)가 발생하여 정보가 손실됩니다. 이 플래그는 백엔드에 압축을 건너뛰도록 지시합니다.

PlanType 오버라이드 (The PlanType Override)

사용자는 생성 전에 선택적으로 플랜 타입 (plan type)을 지정할 수 있습니다:

let directInput = genData.input;
if (this.planConfig.planType) {
    directInput = 'planType=' + this.planConfig.planType + '\n\n' + directInput;
...

이는 입력의 최상단에 제약 지시문 (constraint directive)을 주입합니다. 플랜 에이전트 (plan agent)는 이를 확인하고 준수합니다. 예를 들어 사용자가 planType=exam이라고 말하면, 에이전트는 해당 콘텐츠가 평가 (assessment)로 쓰일 수 있더라도 시험 (exam) 시퀀스를 생성합니다.

이 기능이 없다면, 플랜 에이전트는 지식 테스트에 대해 assessment를 선택할 수 있으며, 이 경우 정오답 표시 대신 리커트 척도 (Likert scales)를 사용하게 됩니다. 잘못된 플랜 타입은 앱 전체 구조의 오류로 이어집니다.

SSE 연결 라이프사이클 (The SSE Connection Lifecycle)

SSE 연결은 플랜 (plan) 단계와 실행 (execute) 단계 모두에 걸쳐 유지됩니다. 플랜 모드에서 이는 읽기 전용 스트림 (read-only stream)이며, 클라이언트는 plan 이벤트를 수신합니다. 실행 모드에서 클라이언트는 플랜 객체를 전송하고 태스크 (task) 이벤트를 수신합니다.

// 플랜 단계: 입력만 존재, 플랜 없음
$agent.assessChat(appId, input, null, callback);

...

백엔드는 request.hasPlan()을 확인하여 두 단계를 구분합니다:

if (request.hasPlan()) {
    // 실행 단계
    agent.execute(request.getPlan(), session, listener);
...

종료 이벤트의 모호성 (The Close Event Ambiguity)

close 이벤트는 모호합니다. 이 이벤트는 SSE 연결이 종료될 때 발생하며, 다음과 같은 상황에서 발생할 수 있습니다:

1. 정상적인 종료 (Normally) — 모든 이벤트가 전송된 후
2. 타임아웃 (Due to timeout) — 네트워크 문제 또는 서버 타임아웃
3. 오류 (Due to error) — 서버에서의 처리되지 않은 예외 (Unhandled exception)

프론트엔드에서는 상태를 확인하여 이를 처리합니다:

} else if (event === 'close') {
    if (this.stage === 'executing') {
        this.onPlanDone();  // 실행 중 SSE가 종료되면 완료된 것으로 간주
...

만약 플래닝 (Planning) 단계 중(플랜을 받기 전)에 연결이 종료된다면 이는 오류입니다. 반면, 실행 (Execution) 단계 중에 종료된다면 완료된 것으로 처리합니다. 서버가 연결을 닫기 전에 모든 이벤트를 전송 완료했을 수 있기 때문입니다.

이는 완벽하지 않습니다. 실행 중 서버가 충돌(Crash)하더라도 성공적으로 완료된 것으로 처리될 것입니다. 하지만 모든 종료를 오류로 처리하는 대안은, 서버가 정상적으로 작업을 마쳤을 때 잘못된 오류 메시지를 생성하게 됩니다.

교훈 (Lessons Learned)

1. 로딩 메시지는 반드시 순환(Rotate)되어야 합니다. 20초 이상 정적인 스피너만 보여주는 것은 전환율(Conversion)을 떨어뜨립니다. 시각적인 진행 상황(Progress)을 보여주는 것만으로도 도움이 됩니다.

2. 입력 모드 (Input mode)가 중요합니다. 서로 다른 입력 유형 (텍스트, URL, 파일, 지식 베이스 (KB))은 서로 다른 전처리 (Preprocessing)가 필요합니다. 중복 처리하지 마세요.

3. SSE 이벤트 유형은 모호하지 않아야 합니다. 플래닝 중의 close ≠ 실행 중의 close. 이벤트를 해석하기 전에 애플리케이션 상태를 확인하세요.

4. 600ms의 완료 지연 (Completion delay)은 중요한 UX 디테일입니다. 긴 로딩 후에 화면이 즉시 전환되면 사용자에게 이질감을 줍니다. 약간의 지연을 두면 전환이 자연스럽게 느껴집니다.

5. 플랜 유형 오버라이드 (Plan type override)는 안전장치입니다. AI가 잘못된 플랜 유형을 선택했을 때 사용자가 강제로 변경할 수 있습니다. 이 단 하나의 기능이 수많은 고객 지원 티켓을 방지했습니다.

다음: [SSE 신뢰성 — 이벤트 손실을 해결하는 세 단계]