문서 목록으로 돌아가기
requirements / ux_process_v1.md

UX / 전체 프로세스 설계 v1

작성일: 2026-04-19

기준 문서:

  • requirements/requirements_v1.md
  • requirements/local_agent_spec_v1.md

상태: v1 초안

1. 문서 목적

이 문서는 한별님이 지적한 핵심 질문, 즉

  • 사용자는 이 에이전트를 어떻게 다운받고
  • 어떻게 설치하고
  • 실행하면 어떤 경험을 보고
  • 어떤 단계에서 정보를 넣고
  • 어떤 단계가 자동화되고
  • 어디서 사용자가 개입하며
  • 지금 코드가 어디까지 커버하는지

를 한 번에 정리하기 위한 UX/프로세스 기준 문서다.

핵심은 "기능 목록"이 아니라 "실제 사용자 여정" 기준으로 MVP를 재정렬하는 것이다.

2. 한 줄 제품 정의

이 제품은

"웹앱이 계약/첨부 등록, OCR 보정, 제출 패키지 생성을 담당하고, Windows 로컬 에이전트는 렌트홈 로그인 이후 신고 화면 이동·자동 입력·첨부 업로드·결과 회수처럼 로컬에서만 가능한 단계만 처리하는 반자동 신고 시스템"

이다.

3. 사용자 관점 전체 여정

Phase A. 웹앱 가입 / 로그인

1. 사용자는 웹사이트에 접속한다.

2. 회원가입 또는 로그인한다.

3. 웹앱 홈에서 현재 계약 사건, 제출 대기 작업, 후속 일정, 최근 결과를 본다.

사용자에게 보여야 하는 것

  • 오늘 처리할 계약 건수
  • 제출 대기 작업 수
  • 최근 접수 결과
  • "새 계약 등록" 버튼

현재 커버 상태

  • 미완료
  • 현재는 작업 허브/문서 허브가 있지만, 실제 사용자용 웹앱 홈은 아직 없다

Phase B. 계약/증빙 등록 및 보정

1. 사용자는 웹앱에서 계약서와 증빙을 업로드한다.

2. 시스템이 OCR/추출을 수행한다.

3. 사용자는 웹앱에서 자동 추출값을 확인/수정한다.

4. 시스템이 filing job과 제출 패키지를 만든다.

사용자에게 보여야 하는 것

  • 업로드 상태
  • 자동 추출 결과
  • 누락 필드 / 누락 첨부 경고
  • 제출 패키지 준비 완료 여부

현재 커버 상태

  • 부분 완료
  • 서버 preflight/checklist, filing job 생성은 있음
  • 사용자용 웹앱 입력/보정 경험은 아직 없음

Phase C. 로컬 에이전트 설치 / 연결

1. 웹앱이 "렌트홈 제출 시작" 단계에서만 로컬 에이전트 설치를 요구한다.

2. 사용자는 그 시점에만 DuduAgent를 설치한다.

3. 에이전트는 웹앱이 준비한 제출 작업을 로컬에서 읽을 수 있게 연결된다.

사용자에게 보여야 하는 것

  • 왜 로컬 에이전트가 필요한지 한 줄 설명
  • 설치 버튼
  • 설치 후 연결 상태
  • 현재 연결된 agent_id / PC 이름

현재 커버 상태

  • 부분 완료
  • 설치 스크립트/manifest/zip 있음
  • 웹앱과의 자연스러운 연결 UX는 아직 없음

5. Phase D. 렌트홈 진입 / 로그인

C-1. 렌트홈 열기

에이전트가 해야 하는 일

  • 렌트홈 시작 URL 열기
  • 로그인 전 화면 감지
  • 로그인 대기 상태로 전환

사용자에게 보여야 하는 것

  • "렌트홈이 열렸습니다"
  • "공동인증서/간편인증으로 로그인해 주세요"
  • 로그인 완료 후 자동 진행된다는 안내

C-2. 로그인 완료 감지

에이전트가 해야 하는 일

  • 로그인 화면인지 여부 확인
  • 로그인 후 landing 화면으로 바뀌었는지 감지
  • 필요한 경우 신고 메뉴로 자동 이동

현재 커버 상태

  • 부분 완료
  • awaiting_login 상태 보고는 됨
  • HTML snapshot 기준 login / filing_form 감지는 됨
  • 실제 브라우저 열기 / 로그인 성공 감지 / 로그인 후 메뉴 이동은 아직 미완료

6. Phase E. 신고 페이지 이동 / UI 판독

D-1. 신고 페이지 진입

에이전트가 해야 하는 일

  • 렌트홈 로그인 후 신고 메뉴까지 자동 이동
  • 신규계약/변경계약/재계약 등 맞는 entry 선택

D-2. 신고 화면 읽기

에이전트가 해야 하는 일

  • 현재 화면이 신고 입력 화면인지 판별
  • 입력칸/라벨/selector 추출
  • 제출 패키지 값과 매핑
  • 누락 필드 또는 selector drift 감지

사용자에게 보여야 하는 것

  • "신고 페이지 확인 완료"
  • 자동 입력 예정 항목 요약
  • 매핑 실패 항목 경고

현재 커버 상태

  • 부분 완료
  • snapshot 분석 CLI로 HTML 기준 화면 분류/field 추출/input plan 생성 가능
  • 실제 live browser DOM에서 읽는 단계는 아직 미완료

7. Phase F. 자동 입력 / 첨부 업로드

E-1. 자동 입력

에이전트가 해야 하는 일

  • 매핑된 selector에 값 입력
  • 날짜/숫자 포맷 보정
  • 입력 후 값 검증

E-2. 첨부 업로드

에이전트가 해야 하는 일

  • 계약서/증빙 업로드
  • 업로드 성공 여부 확인
  • 미리보기 또는 첨부 목록 검증

사용자에게 보여야 하는 것

  • 입력 완료 항목 수
  • 업로드 완료 파일 수
  • 실패 항목과 재시도 버튼

현재 커버 상태

  • 설계/테스트 골격만 있음
  • awaiting_final_approval / manual_handoff / result upload helper는 있음
  • 실제 live 입력/첨부 업로드 동작은 아직 미완료

8. Phase G. 최종 검토 / 사용자 제출

F-1. 최종 검토 화면

사용자에게 보여야 하는 것

  • 주요 필드 요약
  • 첨부 완료 여부
  • 접수 직전 화면 캡처 또는 DOM 요약
  • 버튼
  • 제출
  • 뒤로 가서 수정
  • 수동 전환

F-2. 제출

원칙

  • 최종 제출은 사용자 승인을 반드시 거친다.
  • MVP에서는 사용자가 직접 제출 버튼을 누르는 방식이 기본이다.

현재 커버 상태

  • 부분 완료
  • awaiting_final_approval 상태 및 review_items 보고 가능
  • 실제 최종 검토 창/제출 버튼 UX는 아직 없음

9. Phase H. 결과 회수 / 후속 절차

에이전트가 해야 하는 일

  • 접수번호 읽기
  • 결과 캡처 저장
  • 접수증/필증 다운로드
  • 서버 결과 업로드
  • followup 생성

사용자에게 보여야 하는 것

  • 접수 성공/실패
  • 접수번호
  • 회수 파일 목록
  • 후속 일정 안내

현재 커버 상태

  • 부분 완료
  • 결과 업로드 API/helper/followup 생성 있음
  • 실제 브라우저 결과 화면 읽기/다운로드 자동화는 아직 미완료

10. 핵심 검증 단계 정의

이 MVP에서 반드시 따로 검증해야 하는 핵심 단계는 아래 8개다.

1. 설치/실행 검증

  • 다운로드, 설치, 설정 저장, 실행 성공 여부

2. 작업 수신 검증

  • agent가 package_ready 작업을 실제로 받는가

3. 패키지/체크리스트 검증

  • 계약/첨부/입력값 누락을 사전에 잡는가

4. 로그인 진입 검증

  • 렌트홈을 열고 login 대기 상태까지 가는가

5. 로그인 성공 후 화면 전환 검증

  • 로그인 이후 신고 메뉴/입력 화면까지 이동하는가

6. 신고 UI 판독 검증

  • 현재 화면 field를 읽고 input plan을 만들 수 있는가

7. 자동 입력/첨부 업로드 검증

  • 실제 DOM에 값이 들어가고 파일이 붙는가

8. 결과 회수/후속 처리 검증

  • 접수번호/파일/후속 일정까지 끊김 없이 이어지는가

11. 현재 커버리지 매핑

이미 커버된 단계

  • 1. 설치/실행 검증
  • 2. 작업 수신 검증
  • 3. 패키지/체크리스트 검증
  • 4. 로그인 진입 검증의 일부 (`awaiting_login`까지)
  • 8. 결과 회수/후속 처리 검증의 서버 업로드 쪽

부분 커버 단계

  • 5. 로그인 성공 후 화면 전환 검증
  • HTML snapshot 기반 판독만 있음
  • 실제 로그인 성공 감지와 메뉴 이동 없음
  • 6. 신고 UI 판독 검증
  • snapshot 분석 CLI는 있음
  • live browser DOM 연결은 없음
  • 7. 자동 입력/첨부 업로드 검증
  • 서버 상태 helper는 있음
  • 실제 브라우저 조작은 없음

아직 미커버 단계

  • 설치 후 GUI/런처 기반 첫 실행 UX
  • 계약/첨부 수집용 사용자 화면
  • 로그인 완료 감지 후 자동 네비게이션
  • live 브라우저 기준 selector 실행/재시도/복구
  • 최종 검토 전용 사용자 화면

12. 지금 코드 기준 단계별 상태표

  • 설치 스크립트/업데이트/worker launcher: 있음
  • resident worker + control plane: 있음
  • filing job detail/checklist/current_status: 있음
  • awaiting_login / awaiting_final_approval / manual_handoff / result_collected 상태 흐름: 있음
  • renthome HTML snapshot 판독 helper: 있음
  • snapshot 분석 CLI: 있음
  • 실제 렌트홈 브라우저 열기: 없음
  • 실제 로그인 성공 감지: 없음
  • 실제 신고 페이지 자동 이동: 없음
  • 실제 자동 입력/첨부 업로드: 없음
  • 실제 결과 화면 다운로드 자동화: 없음

13. 다음 설계 원칙

1. 지금부터는 기능 추가를 "어느 Phase를 완성하는가" 기준으로만 진행한다.

2. 특히 아래 4개를 최우선 검증 포인트로 잡는다.

  • 렌트홈 로그인 성공 감지
  • 신고 페이지 자동 이동
  • 신고 UI live 판독
  • 실제 input/upload

3. 사용자 경험은 최종적으로 아래 3개 화면으로 압축한다.

  • 홈/작업대기 화면
  • 신고 준비/패키지 확인 화면
  • 최종 검토/제출 화면

14. 바로 다음 WP 권장

WP-038 로그인 후 live 화면 감지 설계

  • 목표: snapshot이 아니라 실제 browser session 기준으로 login 성공 여부와 현재 화면 타입을 읽는 경로를 정한다.

WP-039 신고 페이지 진입 경로 고정

  • 목표: 렌트홈 메뉴 이동/페이지 전환을 단계별 selector 계약으로 문서화한다.

WP-040 live input/upload 실행 helper

  • 목표: input plan actions를 실제 브라우저 action으로 실행하는 helper를 붙인다.

15. 한별님 기준 지금 해석

한별님 말씀이 맞다.

지금까지는 "서버-에이전트 상태 흐름"과 "snapshot 기반 판독 뼈대"가 중심이었다.

하지만 실제 제품 판단은

  • 설치했을 때 사용자가 무엇을 보는가
  • 어떤 흐름으로 계약/첨부를 준비하는가
  • 렌트홈 로그인 후 어디까지 자동으로 가는가
  • 최종 제출 전 사용자가 무엇을 검토하는가

라는 end-to-end UX 관점에서 다시 정리해야 한다.

이 문서는 앞으로 구현과 검증을 그 UX 흐름 기준으로 다시 묶기 위한 기준점이다.