# 13. 사용자 간편 테스트 가이드

## 이 문서의 목적

이 문서는 내부 검증표가 아니다. 학원 운영자, 교사, 내부 검토자가 AI 시험지 첨삭 기능을 직접 눌러 보며 전체 흐름을 이해하기 위한 간편 사용 가이드다.

현재 버전은 실제 OCR 모델을 완전히 연결하기 전 단계다. 따라서 일부 결과는 mock 데이터로 표시된다. 중요한 확인 포인트는 모델 정확도가 아니라 다음 흐름이 끊기지 않는지다.

- 시험지 프로젝트를 만든다.
- 시험지 파일을 올린다.
- 연구내용 이미지 순서와 같은 8단계 분석 결과를 본다.
- 풀이 분석 결과를 교사가 검토한다.
- 교사 승인 후에만 첨삭 오버레이가 생성된다.
- 승인되지 않은 결과는 학생용 최종 출력으로 나가지 않는다.

## 접속 위치

| 목적 | 주소 |
|---|---|
| 제품 소개 | `/solutions/exam-annotation/` |
| 연구내용 | `/solutions/exam-annotation/research/` |
| 기술설명 | `/solutions/exam-annotation/technology/` |
| 시험지 첨삭 앱 | `/app/exam-annotation/` |
| 프로젝트 생성 | `/app/exam-annotation/projects/new/` |
| Local Backend 설정 | `/app/exam-annotation/settings/local-backend/` |
| 관리자 화면 | `/admin/exam-annotation/` |

관리자 화면은 임시 로그인 방식이다.

```text
ID: flownco
PW: flownco
```

## 가장 빠른 체험 순서

### 1. 프로젝트 생성

`/app/exam-annotation/projects/new/`로 이동한다.

입력 예시:

| 항목 | 예시 |
|---|---|
| 프로젝트명 | 중2 수학 1학기 중간 |
| 학년 | 중2. 비워도 되며, 없으면 OCR 내용에서 확인한다. |
| 과목 | 수학. 비워도 되며, 없으면 OCR 내용에서 확인한다. |
| 시험명 | 기본값은 없음이다. 필요한 경우 직접 입력한다. |
| 파일 | 시험지 이미지 1장 또는 PDF |

화면에는 `학년정보와 과목정보를 입력하면 더 정확한 결과를 받을 수 있습니다.` 안내가 표시된다.

현재 MVP에서는 시험지를 최대 5장까지만 올릴 수 있다.

정상 결과:

- 프로젝트가 생성된다.
- 업로드 파일명, 용량, 페이지 수가 저장된다.
- Local Agent로 시험지가 전송되고 OCR 후보가 저장된다.
- 8단계 분석 Job이 자동 생성되고 실행된다.
- 생성 완료 메시지가 나온다.
- 과정별 결과물이 이미지 카드로 화면에 순서대로 보인다.

### 2. 자동 분석 결과 확인

프로젝트 생성 후 별도 입력 없이 자동으로 `분석 Job`이 만들어진다. 화면에는 `자동 분석 결과`와 8단계 이미지 카드가 표시된다.

이미 프로젝트 상세 화면에 있다면 `분석 Job` 탭에서 같은 결과를 확인한다.

사용자 확인 포인트:

- 분석 Job 카드가 생긴다.
- 진행 상태가 표시된다.
- 연구내용 이미지와 같은 8단계 산출물이 모두 보인다.
- 각 단계 카드에는 이미지, 단계명, 상태가 함께 표시된다.

## 8단계 결과 보는 법

분석 결과는 홈페이지 연구내용에 올라간 시험지 이미지 순서를 그대로 따른다. 사용자는 별도 탭을 열지 않고 8개 이미지 카드를 한 화면 흐름에서 확인한다.

| 순서 | 화면 표시 | 의미 |
|---:|---|---|
| 1 | 원본 시험지 | 사용자가 올린 시험지 기준 이미지 |
| 2 | 문제 레이어 복원 | 정형 인쇄 폰트를 시험지로 분리하고, 지워져 약한 획은 원본 대비로 보강해 시험지만 복원한 결과 |
| 3 | 문제 격자 인식 | 문항, 답안란, 풀이공간을 좌표로 나눈 결과 |
| 4 | 문제 레이어 분리 | 인쇄문항만 따로 분리한 결과 |
| 5 | 풀이 격자 적용 | 학생 풀이가 어느 문항에 속하는지 맞춘 결과 |
| 6 | 풀이 레이어 분리 | 학생 손글씨 풀이를 따로 분리한 결과 |
| 7 | 풀이 분석 | 풀이 흐름, 오류 가능성, 근거 패키지를 만든 결과 |
| 8 | 첨삭 오버레이 | 교사 승인 후 시험지 위에 첨삭을 얹은 결과 |

주의할 점:

- 1~7단계는 분석 초안이다.
- 8단계는 교사 승인 후에만 최종 결과로 봐야 한다.
- `pending`은 아직 생성되지 않은 단계다.
- `generated`는 해당 단계의 예시 결과가 생성된 상태다.

## 교사 승인하기

mock pipeline을 실행하면 분석 Job 상태가 `review_pending`으로 바뀐다.

이때 `교사 승인` 버튼을 누른다.

승인 후 확인할 내용:

- Job 상태가 `approved`로 바뀐다.
- 교사 승인 annotation이 생성된다.
- 학생용 출력 준비가 가능해진다.

운영 원칙:

- AI 결과는 후보일 뿐이다.
- 교사 승인 전에는 최종 첨삭으로 사용하지 않는다.
- 인식이 불확실한 내용은 확정값으로 처리하지 않는다.

## 첨삭 오버레이 생성

교사 승인 후 `오버레이 렌더링` 버튼을 누른다.

정상 결과:

- Job 상태가 `rendered`로 바뀐다.
- 8번 `첨삭 오버레이`가 `generated` 상태가 된다.
- 출력 이력에 PDF 기록이 남는다.

출력이 막히는 경우:

| 화면 메시지 | 의미 |
|---|---|
| 인식불가영역이 남아 있음 | 교사가 먼저 전사하거나 무시 처리해야 한다. |
| DRAFT 첨삭이 남아 있음 | 교사가 승인 또는 거절해야 한다. |
| 교사 승인 전 분석 결과가 있음 | `교사 승인`을 먼저 눌러야 한다. |
| evidence audit 실패 | 근거 없는 AI 문장이 있어 최종 출력할 수 없다. |

## 기존 수동 입력 기능

프로젝트 상세 화면에는 기존 MVP 기능도 남아 있다.

| 탭 | 사용 목적 |
|---|---|
| 문서 | 업로드 파일과 페이지 확인 |
| 영역 설정 | 문항, 답안, 첨삭 가능 영역 수동 저장 |
| 풀이 인식 | OCR/VLM 인식 후보 저장 |
| 인식불가영역 | 교사 전사가 필요한 영역 관리 |
| 풀이 추론 | 오류 가능성 후보 저장 |
| 첨삭 문구 | AI 첨삭 문구 후보 저장 |
| 교사 승인 | DRAFT annotation 승인/거절 |
| PDF 출력 | 승인된 annotation만 출력 |
| 이력 | 저장된 데이터와 감사 로그 확인 |

처음 사용하는 사용자는 `분석 Job` 탭만 따라가면 된다.

## Local Backend 설정

Local Backend는 사용자 PC 또는 내부 서버에서 OCR/LLM 후보를 만들기 위한 연결 정보다.

`/app/exam-annotation/settings/local-backend/`에서 설정한다.

기본 입력 예시:

| 항목 | 값 |
|---|---|
| 프로토콜 | `http` |
| Host/IP | `127.0.0.1` |
| Port | `8787` |
| Agent Token | `dev-local-token` |
| Provider | Ollama / LM Studio / vLLM 등 |

사용자가 확인할 내용:

- 저장 버튼을 눌렀을 때 오류가 없어야 한다.
- 연결 테스트 결과가 표시되어야 한다.
- Agent Token은 화면에 평문으로 다시 보이지 않아야 한다.

운영 주의:

- Flownco 서버가 사용자가 입력한 IP로 대신 접속하지 않는다.
- 브라우저가 Local Agent에 직접 연결한다.
- 외부 API는 기본 차단이다.

## 관리자 화면에서 확인하기

관리자 로그인 후 다음 화면을 확인한다.

| 화면 | 확인 내용 |
|---|---|
| 관리자 대시보드 | 프로젝트 수, 문서 수, 분석 Job 수 |
| 프로젝트 목록 | 생성된 프로젝트 |
| 데이터 화면 | 분석 Job, 산출물, evidence, diagnosis, model run |
| 감사 로그 | 생성, 승인, 출력, 차단 이력 |

사용자 확인 포인트:

- `analysisJobs`가 보인다.
- `pageArtifacts`가 8단계로 보인다.
- `evidencePackages`와 `diagnosisResults`가 보인다.
- 승인/출력 행동이 `auditLogs`에 남는다.

## 정상 동작 기준

사용자는 아래 항목만 확인하면 된다.

| 항목 | 정상 기준 |
|---|---|
| 프로젝트 생성 | 오류 없이 상세 화면으로 이동 |
| 업로드 제한 | 5장 초과 시 거부 안내 |
| 분석 Job | 생성 후 8단계 목록 표시 |
| 8단계 순서 | 원본 시험지부터 첨삭 오버레이까지 순서 유지 |
| 교사 승인 | 승인 전에는 최종 출력 불가 |
| 오버레이 | 승인 후에만 생성 |
| 관리자 이력 | 작업 기록과 감사 로그 표시 |
| 보안 | token 평문 미노출, 외부 API 기본 차단 |

## 자주 막히는 상황

### 프로젝트는 생성됐지만 분석 결과가 없습니다

프로젝트 상세 화면의 `분석 Job` 탭에서 `자동 분석 시작`을 누른다. 일반적인 사진 업로드 흐름에서는 이 버튼을 누르지 않아도 자동으로 실행된다.

### 오버레이 렌더링 버튼이 없습니다

Job 상태가 아직 `approved`가 아닐 수 있다. 먼저 `교사 승인`을 누른다.

### PDF 출력이 차단됩니다

미해결 인식불가영역, DRAFT annotation, 교사 승인 전 분석 결과가 남아 있는지 확인한다.

### Local Backend 연결이 안 됩니다

Local Agent가 실행 중인지 확인한다. 운영 환경에서는 HTTPS, 방화벽, 포트포워딩, VPN 또는 터널 설정이 필요할 수 있다.

### 8단계 중 일부가 pending입니다

mock pipeline을 아직 실행하지 않았거나 해당 단계가 아직 생성되지 않은 상태다. `생성 후 mock pipeline 실행`을 누른다.

## 도움 요청 시 전달할 정보

문제가 반복되면 아래 정보를 함께 전달한다.

| 항목 | 예시 |
|---|---|
| 접속 화면 | 프로젝트 생성, 분석 Job, 관리자 데이터 등 |
| 프로젝트명 | 중2 수학 1학기 중간 |
| Job 상태 | uploaded, review_pending, approved, rendered |
| 막힌 단계 | 8단계 중 몇 번 단계인지 |
| 화면 메시지 | PDF 출력 차단, Local Backend 연결 실패 등 |
| 사용 파일 | 이미지 1장, PDF 3페이지 등 |