DocMaster AI 사용자 메뉴얼

1. 서비스 개요 및 전체 플로우

DocMaster AI는 PDF·PPTX 파일을 업로드하면, 문서에서 텍스트와 표를 추출하고, 선택한 유형에 맞춰 보고서·개발 피처 목록·테스트 케이스 등을 자동 생성하는 서비스입니다.

전체 사용 흐름

1. 시작 전: 우측 상단 [Key 설정]에서 LLM API 키를 등록합니다.
2. Step 1: 메인 화면에서 PDF 또는 PPTX 파일을 업로드합니다. 서버가 문서를 추출해 마크다운으로 변환합니다.
3. Step 2: 만들고 싶은 문서 유형(기획서 기반 보고서 / 개발 피처 / 테스트 케이스)을 선택하고, 보고서 유형이라면 경영진용·실무용과 HTML 형식을 고른 뒤 [보고서 생성] 또는 [생성]을 누릅니다.
4. 맞춤 질문 (선택): 기획서 기반 보고서를 처음 생성할 때, 정리 초안이 나온 뒤 **의도 반영용 질문**이 2~3개 뜨는 경우가 있습니다. 원하는 선택지를 고른 뒤 [반영하여 계속]을 누르면 해당 포인트를 강조·구체화한 최종 보고서가 만들어집니다. [건너뛰기]를 누르면 초안 그대로 HTML이 생성됩니다.
5. 결과 확인: 생성이 끝나면 보고서 보기 팝업에서 HTML을 확인하고, HTML·정리 md 다운로드가 가능합니다.

flowchart TB
  subgraph prep["시작 전"]
    A["Key 설정
API 키 등록"]
  end
  subgraph step1["Step 1"]
    B["PDF/PPTX 업로드"]
    C["서버 추출 · 마크다운 변환"]
    B --> C
  end
  subgraph step2["Step 2"]
    D["문서 유형 선택"]
    D --> E["기획서 기반 보고서"]
    D --> F["개발 피처 목록"]
    D --> G["테스트 케이스"]
    E --> H["경영진/실무 · HTML 형식 선택"]
    H --> I["보고서 생성"]
    I --> J{"맞춤 질문
표시?"}
    J -->|반영| K["정리 md 보강 후 HTML 생성"]
    J -->|건너뛰기| L["HTML 생성"]
    K --> L
    F --> M["개발 피처 생성"]
    G --> N["테스트 케이스 생성"]
  end
  subgraph result["결과"]
    O["보고서 보기 · HTML/정리 md 다운로드"]
  end
  A --> B
  C --> D
  L --> O
  M --> O
  N --> O
      

그림 1. 서비스 전체 사용 흐름

2. 시작 전 준비 (Key 설정)

보고서 생성은 외부 LLM(OpenAI, Anthropic, Google 등) API를 사용합니다. 반드시 우측 상단 [Key 설정]에서 API 키를 입력하고, 사용할 LLM을 선택해야 합니다.

[ 스크린샷: 메인 화면 우측 상단 — Key 설정 버튼 위치 ]
생성: docmaster-web에서 node scripts/capture-manual-screenshots.mjs

그림 2. 메인 화면 상단 (Key 설정 버튼)

[ 스크린샷: 설정 모달 — API 키 화면 ]

그림 3. 설정 모달 — API 키 화면

설정 화면 정책

• API 키와 설정은 브라우저 Local Storage에만 저장됩니다. 서버에 설정을 보내지 않습니다.
• 보고서 생성 시에는 추출된 문서 내용(텍스트·표 등)만 선택한 LLM 제공업체 API로 전송됩니다. 원본 PDF/PPTX 파일은 추출 후 즉시 삭제되며 서버에 남기지 않습니다.

버튼·항목별 동작

3. Step 1 — 파일 업로드 & 추출

메인 화면 중앙의 업로드 영역에 PDF 또는 PPTX 파일을 드래그 앤 드롭하거나, 영역을 클릭해 파일을 선택합니다.

[ 스크린샷: 메인 화면 — 업로드 영역 (클릭 또는 드래그 앤 드롭) ]

그림 4. Step 1 — 업로드 영역

정책

• 지원 형식: PDF, PPTX만 지원합니다. 그 외 파일은 업로드 시 안내 메시지가 나옵니다.
• 처리 방식: 파일은 파싱 백엔드(로컬 또는 배포 서버)로 전송되어 텍스트·표가 추출됩니다. 추출이 끝나면 원본 파일은 즉시 삭제되며 서버에 보관하지 않습니다.

버튼·동작

파싱이 진행되는 동안 "파이썬 서버가 문서를 추출 중입니다..." 메시지와 로딩 표시가 나타납니다. 완료되면 Step 2 영역이 나타납니다.

4. Step 2 — 문서 유형 선택 & 보고서 생성

추출이 끝나면 Step 1 완료 배너와 추출 콘텐츠 미리보기, 그 아래 「어떤 문서를 만들까요?」 카드 3종이 표시됩니다.

[ 스크린샷: Step 2 — 기획서 기반 보고서 / 개발 피처 목록 / 테스트 케이스 카드 3종 ]

그림 5. 문서 유형 선택 카드

문서 유형(카드)별 동작

각 카드의 [프롬프트 편집] 버튼을 누르면 해당 유형의 프롬프트(역할·규칙·Step)를 편집할 수 있습니다. 저장한 내용은 다음 생성부터 적용됩니다.

[ 스크린샷: Step 1 완료 배너 + 미리보기 + 경영진/실무 탭 + HTML 형식 + 고품질 + 보고서 생성 버튼 ]

그림 6. Step 2 — 보고서 옵션 및 생성 버튼

보고서 유형 선택 시 항목·버튼

생성이 완료되면 "보고서 생성이 완료되었습니다." 메시지와 함께 토큰 사용량(정리 md + HTML 생성 합산) 및 예상 비용이 표시되고, [만들어진 보고서 보기], 정리 내용 (.md) 다운로드 버튼이 나타납니다. 표시되는 토큰·비용은 1단계(정리 md)와 2단계(HTML 생성)의 합산입니다.

HTML 생성이 실패한 경우: 2단계(HTML 변환)에서 오류가 나도 1단계에서 생성된 정리 md가 있으면 해당 내용은 유지·표시되며, 「정리 내용 (.md) 다운로드」로 받을 수 있습니다. 이때 "HTML 보고서 생성에 실패했습니다. 정리된 내용(.md)은 아래에서 다운로드할 수 있습니다." 안내가 표시됩니다.

4.1 맞춤 질문 (의도 반영)

기획서 기반 보고서를 선택하고 [보고서 생성]을 누르면, 정리 초안이 만들어진 뒤 「맞춤 질문」 팝업이 뜨는 경우가 있습니다. 초안 내용을 바탕으로 "어떤 포인트를 강조·구체화할지" 2~3개의 다지선다 질문이 표시됩니다.

[ 스크린샷: 맞춤 질문 모달 — 질문 2~3개, 선택지, 건너뛰기 / 반영하여 계속 버튼 ]

그림 6-1. 맞춤 질문 모달

정책

• 질문은 정리 초안에 실제로 등장하는 섹션·항목을 기준으로 생성됩니다. LLM이 초안을 분석해 JSON 형태로 질문을 만들며, 파싱이 실패하거나 질문이 0개면 이 단계는 건너뛰고 곧바로 HTML이 생성됩니다.
• 같은 파일·같은 보고 유형(경영진 또는 실무)에서 HTML 형식만 바꿔서 재생성할 때는 정리 md를 다시 만들지 않고, 선택한 HTML 형식으로만 HTML이 다시 만들어집니다. 이때 맞춤 질문 단계도 다시 뜨지 않습니다. 새로 정리 md를 만들 때만(처음 생성하거나, 경영진↔실무를 바꾼 뒤 생성할 때) 질문이 나올 수 있습니다.

버튼별 동작

5. 보고서 보기 & 다운로드

[만들어진 보고서 보기]를 누르면 생성된 HTML 보고서가 팝업(또는 전체 화면)으로 표시됩니다. 보고서 HTML 안에 Mermaid 다이어그램 코드가 있으면 자동으로 다이어그램으로 렌더됩니다. HTML 생성이 실패했지만 정리 md가 있는 경우에는 해당 정리 md가 뷰어에 표시되거나, Step 2 패널에서 「정리 내용 (.md) 다운로드」로 받을 수 있습니다. 모델이 요청을 거절한 경우에는 안내 메시지와 함께 정리 md 다운로드가 권장됩니다.

[ 스크린샷: 보고서 뷰어 — 상단 헤더 + HTML 내용 영역 ]

그림 7. 보고서 뷰어

버튼별 동작

Step 2 패널에서 정리 내용 (.md) 다운로드를 누르면, LLM이 생성한 정리 마크다운이 파일명_report.md로 다운로드됩니다.

6. 프롬프트 편집

「어떤 문서를 만들까요?」 카드에서 [프롬프트 편집]을 누르면, 해당 유형(기획서 기반 보고서 / 개발 피처 / 테스트 케이스)의 프롬프트를 편집하는 모달이 열립니다.

[ 스크린샷: 프롬프트 편집 모달 — 경영진용/실무용 탭, 편집 가능 영역, HTML 출력 시 자동 적용(수정 불가) 영역 ]

그림 8. 프롬프트 편집 모달 (보고서 유형)

정책

• 편집 가능: 역할·목표, 입력 데이터 규칙, 핵심 규칙, 필수 출력 항목, 실행 Step 등이 텍스트 영역에 표시되며 수정할 수 있습니다. 저장 시 Local Storage에 저장되어 다음 생성부터 적용됩니다.
• 수정 불가: "HTML 출력 시 자동 적용 (수정 불가)" 영역은 고정 규칙입니다. HTML을 어떤 형식으로 낼지(코드 블록 하나만 출력, 변수 매핑 등)를 정의하며, 화면에서는 보기만 가능합니다.

버튼별 동작

7. 템플릿 관리

우측 상단 [템플릿 관리]를 누르면 HTML 템플릿(기획/제안서 스타일, 프레젠테이션 스타일, 프리포맷, 테스트 케이스, 개발 피처)을 확인·관리할 수 있습니다. 기획서 기반 보고서용은 스타일 가이드 기반으로 LLM이 HTML 전체를 생성합니다. 테스트 케이스·개발 피처용 템플릿은 API에서 불러오며, API가 없거나 404일 때는 앱 내 기본값이 사용됩니다.

[ 스크린샷: 템플릿 관리 모달 ]

그림 9. 템플릿 관리

자세한 내용은 docs/07-html-template-handling-ko.md를 참고하세요.

8. 이용 팁

• 처음 사용 시: 반드시 [Key 설정]에서 사용할 LLM과 API 키를 먼저 등록하고 [연결 확인]으로 동작을 확인한 뒤 업로드하세요.
• 경영진용 vs 실무용: 경영진용은 1페이지 요약·결론·액션 중심으로 짧게, 실무용은 담당·일정·조건을 풍부하게 작성합니다. 기획서가 길면 실무용을 선택하는 것이 유리할 수 있습니다.
• 고품질 옵션: 중요한 보고서는 "고품질"을 켜면 N회차 검토로 품질이 올라가지만, 생성 시간과 비용이 늘어납니다.
• 추출 결과 보관: [추출 결과 다운로드 (.md)]로 원본 추출본을 보관해 두면, 나중에 같은 원본으로 다른 유형(경영진/실무/개발 피처 등)을 다시 만들 때 참고할 수 있습니다.
• 정리 md 재활용: 같은 추출 결과·같은 보고 유형(경영진 또는 실무)에서 HTML 형식만 바꿔서 [보고서 생성]을 다시 누르면 정리 md는 재사용되고, 선택한 형식(기획/제안서 스타일, 프레젠테이션 스타일, 프리포맷)으로만 HTML이 다시 만들어집니다. 원하는 형태가 다르다면 «정리 내용 (.md)»을 다운로드해 두고 노션·위키·외부 도구에서 가공할 수도 있습니다.
• 프롬프트 커스터마이즈: 팀에서 쓰는 용어나 필수 섹션을 맞추려면 [프롬프트 편집]에서 "필수 출력 항목" 등을 수정해 두면 됩니다.
• 맞춤 질문 활용: 기획서 기반 보고서 생성 시 "맞춤 질문" 팝업이 뜨면, 강조하고 싶은 포인트를 선택한 뒤 [반영하여 계속]을 누르면 의도에 맞게 보강된 보고서가 만들어집니다. 질문이 안 뜨는 경우는 LLM이 질문을 만들지 못한 경우이며, 그때는 초안 그대로 HTML이 생성됩니다.
• 오류 시: "503" 또는 과부하 메시지가 나오면 잠시 후 재시도하거나, [설정]에서 다른 LLM(예: OpenAI ↔ Claude)으로 바꿔 보세요.
• 정리 md 보기: [정리 md 보기]로 열리는 뷰어에서는 마크다운 표가 테이블로, 목록은 단계별로 다른 블릿(●○■)으로 표시되며, Mermaid 코드 블록은 다이어그램으로 시각화됩니다.
• 결과가 마음에 들지 않을 때: 다시 만들도록 지시해 주세요. 몇 번이고 다른 버전으로 만들어 드릴 수 있습니다.
• 품질 변동: LLM 특성상 생성 결과물의 품질이 케바케로 다를 수 있습니다. 원하는 결과가 나올 때까지 계속 다시 시도해 보세요.

9. 정책 요약

— DocMaster AI 사용자 메뉴얼 (HTML) —