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

test_scenarios_v1

작성일: 2026-04-19

기준 문서:

  • /home/ubuntu/workspace/autonomous-sales-ops/requirements/requirements_v1.md
  • /home/ubuntu/workspace/autonomous-sales-ops/requirements/db_schema_v1.md
  • /home/ubuntu/workspace/autonomous-sales-ops/requirements/api_spec_v1.md
  • /home/ubuntu/workspace/autonomous-sales-ops/requirements/local_agent_spec_v1.md

상태: v1 초안

1. 목표

이 문서는 등록임대 계약신고 반자동 MVP가 구현 완료되었는지 판단하기 위한 테스트 시나리오를 고정한다.

핵심 원칙

  • 테스트는 계약 사건 단위로 본다.
  • 서버 API 검증과 로컬 실행 에이전트 검증을 분리한다.
  • 정상 흐름뿐 아니라 로그인 실패, 첨부 실패, 결과 회수 실패 같은 복구 시나리오를 반드시 포함한다.
  • “성공”은 단순 제출 버튼 클릭이 아니라 접수번호/필증/후속 일정까지 이어졌을 때로 본다.

2. 테스트 범위

포함

  • 신규 계약
  • 변경 계약
  • 재계약
  • 묵시적 갱신
  • 로그인 실패
  • 첨부 업로드 실패
  • 제출 실패
  • 접수증/필증 회수 실패
  • 수동 전환
  • 후속 일정 생성

제외

  • 실정부 사이트 대규모 부하 테스트
  • 인증서 자체 보안 검증 전문 테스트
  • 법령 해석 정확성 전수 검증
  • RTMS 전체 자동화 회귀 테스트

3. 환경 가정

서버

  • FastAPI 앱 실행 중
  • SQLite 초기화 가능
  • 테스트용 파일 업로드 경로 분리 가능

로컬 실행 에이전트

  • 테스트 모드에서 브라우저 자동화 stub 또는 sandbox 페이지 사용 가능
  • 파일 다운로드 폴더 제어 가능
  • 결과 회수용 가짜 receipt/certificate 파일 생성 가능

데이터 기준

  • 임대사업자 유형은 4분류 분기 유지
  • 개인 / 주임사 등록
  • 개인 / 주임사 미등록
  • 법인 / 주임사 등록
  • 법인 / 주임사 미등록
  • MVP 본체 흐름은 등록 사업자 중심

4. 공통 완료 기준

각 시나리오는 아래 중 해당 항목을 만족해야 통과다.

  • 올바른 DB row 생성
  • 올바른 상태 전이
  • 올바른 API 응답
  • 올바른 파일 저장/연결
  • 올바른 결과 회수
  • 올바른 followup task 생성
  • 실패 시 올바른 error_message 및 manual handoff 표기

5. 시나리오 목록

1. 신규 계약 정상 제출

2. 변경 계약 정상 제출

3. 재계약 정상 제출

4. 묵시적 갱신 분기 확인

5. 미등록 사업자 등록임대 filing 차단

6. 로그인 실패

7. 첨부 업로드 실패

8. 최종 제출 직전 사용자 취소

9. 제출 후 사이트 에러

10. 접수증 회수 실패

11. 필증만 누락된 partial 회수

12. 후속 일정 생성 검증

13. selector 변경으로 manual handoff

14. 중복 결과 업로드 방지

6. 상세 시나리오

시나리오 1. 신규 계약 정상 제출

목적

  • 가장 기본적인 happy path 검증

사전조건

  • `landlord_profiles.is_registered_landlord = 1`
  • `rental_properties.registered_number` 존재
  • 계약서 PDF, 등록증빙 파일 준비

입력

  • event_type = `new_contract`
  • 계약서 파일 업로드
  • 사용자 보정 완료
  • filing_required = true
  • channel = `renthome`

절차

1. `POST /api/landlords`

2. `POST /api/properties`

3. `POST /api/contracts`

4. `POST /api/contracts/{id}/files`

5. `POST /api/contracts/{id}/extract`

6. `POST /api/contracts/{id}/confirm`

7. `POST /api/contracts/{id}/filing-jobs`

8. 로컬 에이전트 `POST /agent-session`

9. 로컬 에이전트 `POST /status` (`awaiting_login` → `filling` → `awaiting_final_approval`)

10. 사용자 최종 승인

11. 로컬 에이전트 `POST /results`

12. `GET /api/contracts/{id}/timeline`

기대결과

  • `contract_events.event_status = filed`
  • `filing_jobs.job_status = result_collected`
  • `filing_results.receipt_number` 존재
  • receipt/certificate/capture 파일 연결
  • `followup_tasks` 1건 이상 생성

핵심 검증 포인트

  • happy path 전체 연결
  • 결과 회수 후 상태 반영

시나리오 2. 변경 계약 정상 제출

목적

  • 변경 전후 값 기록과 변경 사유 저장 검증

사전조건

  • 기존 계약 이벤트 1건 존재

입력

  • event_type = `amended_contract`
  • previous_contract_event_id 존재
  • change_summary 존재
  • 변경 전후 보증금/월세 값 포함

절차

  • 신규 계약과 동일하되 `confirm` 단계에서 변경 전후 값 반영

기대결과

  • `contract_events.previous_contract_event_id` 저장
  • `change_summary` 저장
  • `corrected_data_json`에 변경값 반영
  • 정상 제출되면 `filed`

핵심 검증 포인트

  • 변경 이벤트 링크 유지
  • 변경 사유 누락 시 검증 에러 처리 가능

시나리오 3. 재계약 정상 제출

목적

  • renewal 분기 처리 검증

입력

  • event_type = `renewal`
  • 기존 계약 참조 존재

기대결과

  • filing_required 판정이 올바름
  • renewal로 저장
  • 결과 회수까지 정상 진행 가능

핵심 검증 포인트

  • renewal과 amended_contract 구분

시나리오 4. 묵시적 갱신 분기 확인

목적

  • implied_renewal 처리와 사용자 확인 강제 검증

사전조건

  • 자동 판정은 `implied_renewal` 후보

절차

1. extract 결과에서 implied_renewal 후보 제시

2. 사용자 confirm 전에는 filing job 생성 금지

3. 사용자 confirm 후에만 다음 단계 가능

기대결과

  • confirm 전 `event_status = classified`
  • confirm 후 `ready_for_filing`
  • 사용자가 event_type 확인하지 않으면 job 생성 실패 또는 차단

핵심 검증 포인트

  • 묵시적 갱신은 자동 확정이 아니라 사용자 확인 필요

시나리오 5. 미등록 사업자 등록임대 filing 차단

목적

  • MVP 범위 바깥 대상이 잘못 등록임대 흐름으로 들어가지 않게 검증

사전조건

  • `is_registered_landlord = 0`

절차

1. landlord/profile/property/contract 생성

2. `filing_required = true`로 confirm 시도 또는 filing job 생성 시도

기대결과

  • 400 또는 차단 응답
  • 오류 메시지에 등록 사업자 조건 부족 표시
  • filing_jobs 생성 안 됨

핵심 검증 포인트

  • 분기 로직 안전성

시나리오 6. 로그인 실패

목적

  • 로컬 에이전트가 로그인 실패를 정상적으로 실패 처리하는지 검증

절차

1. filing job 생성

2. `agent-session` 시작

3. 로그인 화면 진입

4. 사용자 로그인 실패 또는 timeout

5. 에이전트가 `POST /status` with `failed`

예시 payload

{
  "job_status": "failed",
  "error_message": "login_failed",
  "payload": {
    "step": "awaiting_login"
  }
}

기대결과

  • `filing_jobs.job_status = failed`
  • `error_message = login_failed`
  • `contract_events.event_status`는 `ready_for_filing` 유지 가능

핵심 검증 포인트

  • 제출 전 실패가 계약 전체 파손으로 이어지지 않는지

시나리오 7. 첨부 업로드 실패

목적

  • 첨부 업로드 실패 시 재시도/실패 처리를 검증

사전조건

  • 필수 첨부 1개를 일부러 누락하거나 업로드 실패 stub 사용

절차

1. filling 단계 진입

2. 업로드 클릭 실패 또는 파일 경로 없음

3. 에이전트 1~2회 재시도

4. 실패 지속 시 status 업데이트

기대결과

  • `job_status = failed` 또는 manual handoff
  • `error_message`에 실패 파일 종류 포함
  • 결과 업로드 API 호출 안 됨

핵심 검증 포인트

  • 첨부 실패가 조용히 묻히지 않는지

시나리오 8. 최종 제출 직전 사용자 취소

목적

  • 사람 승인형 반자동 원칙 검증

절차

1. 입력/첨부 완료

2. `awaiting_final_approval` 진입

3. 사용자가 취소 또는 중단 선택

기대결과

  • job은 `failed` 또는 별도 취소 note
  • 실제 제출 안 됨
  • 결과 파일 생성 안 됨

핵심 검증 포인트

  • 자동 제출 강행 금지

시나리오 9. 제출 후 사이트 에러

목적

  • 제출 버튼 이후 서버/사이트 오류 발생 시 처리 검증

절차

1. 최종 제출 실행

2. 결과 화면 대신 오류 문구 노출

3. 에이전트가 오류 캡처 후 실패 보고

기대결과

  • `job_status = failed`
  • `error_message`에 사이트 오류 내용 저장
  • result_capture 업로드 가능

핵심 검증 포인트

  • 제출 직후 오류도 감사 가능하게 남는지

시나리오 10. 접수증 회수 실패

목적

  • 제출은 됐지만 receipt 회수가 실패하는 케이스 검증

절차

1. 제출 성공 문구 확인

2. 접수번호는 화면에 보임

3. receipt 파일 다운로드만 실패

4. 에이전트가 수동 전환 또는 partial 결과 업로드

기대결과

  • 최소한 접수번호/캡처는 남음
  • `submission_status = partial` 허용
  • 운영 화면에 후속 회수 필요 표시

핵심 검증 포인트

  • “제출 성공 = 모든 산출물 회수 완료”로 착각하지 않는지

시나리오 11. 필증만 누락된 partial 회수

목적

  • receipt는 있지만 certificate만 없는 경우 검증

기대결과

  • `filing_results.submission_status = partial`
  • `receipt_number`는 존재
  • `certificate_file_path`는 null 가능
  • 수동 후속 task 또는 note 남김

핵심 검증 포인트

  • partial taxonomy 필요성 확인

시나리오 12. 후속 일정 생성 검증

목적

  • 성공 결과 업로드 후 followup task 생성 검증

절차

1. 성공 결과 업로드

2. `GET /api/followups`

3. `GET /api/contracts/{id}/timeline`

기대결과

  • `followup_tasks` 1건 이상 생성
  • due date 계산됨
  • contract_event_id 연결 정확

핵심 검증 포인트

  • 신고 이후 운영 관리까지 이어지는지

시나리오 13. selector 변경으로 manual handoff

목적

  • 사이트 구조 변경 시 안전하게 수동 전환되는지 검증

절차

1. filling 또는 final approval 단계에서 selector 미발견

2. 자동 재시도 후 실패

3. 에이전트가 manual handoff 메시지 표시

기대결과

  • `job_status = failed`
  • `error_message = selector_not_found: ...`
  • 운영 화면에서 수동 처리 필요 표시

핵심 검증 포인트

  • 숨은 실패 방지

시나리오 14. 중복 결과 업로드 방지

목적

  • 동일 job에 결과를 두 번 업로드하지 않게 검증

절차

1. 성공 결과 업로드 1회

2. 동일 `filing_job_id`로 다시 결과 업로드 시도

기대결과

  • 400 또는 idempotent 처리
  • DB에 filing_results 중복 생성되지 않음

핵심 검증 포인트

  • 중복 접수/중복 회수 오염 방지

7. API 레벨 테스트 체크리스트

최소 단위

  • landlord 생성/조회
  • property 생성/조회
  • contract 생성/조회
  • contract files 업로드
  • confirm 후 상태 전이
  • filing job 생성
  • 결과 업로드
  • timeline 조회
  • followups 조회

검증해야 할 것

  • status code
  • response body key
  • DB row count
  • 상태 전이 정확성
  • 파일 경로 저장 여부

8. 로컬 에이전트 레벨 테스트 체크리스트

  • 로그인 대기 화면 진입
  • 패키지 값 자동 입력
  • 첨부 업로드
  • 최종 승인 대기
  • 결과 화면 감지
  • 접수번호 추출
  • 결과 파일 회수
  • 실패 시 서버 상태 업데이트

9. 우선 구현용 테스트 묶음

1차 필수

  • 시나리오 1 신규 계약 정상 제출
  • 시나리오 5 미등록 사업자 차단
  • 시나리오 6 로그인 실패
  • 시나리오 7 첨부 업로드 실패
  • 시나리오 12 후속 일정 생성

2차 확장

  • 시나리오 2 변경 계약
  • 시나리오 3 재계약
  • 시나리오 4 묵시적 갱신
  • 시나리오 10 접수증 회수 실패
  • 시나리오 13 selector 변경 manual handoff
  • 시나리오 14 중복 결과 업로드 방지

10. 통과 기준

MVP 테스트 통과 기준

1. 1차 필수 시나리오 전부 통과

2. happy path에서 접수번호/필증/후속 일정까지 연결

3. 실패 path에서 silent failure 없음

4. 미등록 사용자 차단 동작 확인

5. 사람 승인 없이 최종 제출 강행 없음

11. 바로 다음 작업

  • 실제 코드 구현 시작
  • 우선순위:

1. db.py 테이블 추가

2. landlord/property/contract CRUD API

3. confirm + filing_job 생성 API

4. 결과 업로드 + followup 생성 API

5. 최소 happy path 테스트 추가