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

local_agent_spec_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

상태: v1 초안

1. 목표

이 문서는 등록임대 계약신고 반자동 MVP에서 로컬 실행 에이전트가 실제로 무엇을 하고, 서버와 어떤 식으로 상태를 주고받는지 고정한다.

전제:

  • 기본 사용자 경험의 중심은 웹앱이다.
  • 로컬 실행 에이전트는 전체 업무 UI를 다시 만드는 앱이 아니라, 렌트홈/지자체처럼 로컬 인증과 브라우저 자동화가 꼭 필요한 구간만 담당하는 thin execution client다.

핵심 역할은 아래 5가지다.

1. 웹앱이 준비한 제출 작업을 사용자 PC에서 실행한다.

2. 서버가 만든 제출 패키지를 받아 실제 입력 흐름으로 옮긴다.

3. 로그인/인증/최종 제출 직전에는 반드시 사용자에게 제어권을 넘긴다.

4. 접수증/필증/결과 캡처를 회수해 서버에 올린다.

5. 실패 시 어디까지 자동으로 복구하고, 어디서 사람 개입을 요청할지 분명히 한다.

2. 왜 로컬 실행 에이전트가 필요한가

  • 렌트홈/지자체는 공개 API 제출을 전제로 보기 어렵다.
  • 로그인, 인증서, 간편인증, 보안모듈은 사용자 로컬 환경 의존성이 크다.
  • 서버에 인증서/비밀번호를 장기 저장하지 않는 것이 보안상 맞다.
  • 따라서 서버는 판단/상태/패키지/증빙 보관을 맡고, 로컬 실행 에이전트는 실제 제출 연결을 맡는다.

3. 실행 환경

3.1 기본 전제

  • 실행 위치: 사용자 PC 또는 업무용 로컬 PC
  • 네트워크: 서버 API 접근 가능
  • 브라우저: Chrome 계열 우선
  • 자동화 방식: Playwright 또는 동급 브라우저 자동화 도구
  • 파일 저장 위치: 로컬 임시 작업 폴더 + 다운로드 폴더

3.2 보안 전제

  • 인증서 원본 서버 업로드 금지
  • 비밀번호 원문 서버 저장 금지
  • 로그인/인증은 로컬 브라우저 세션에서만 수행
  • 서버에는 상태, 결과 메타, 회수 파일만 전달

4. 에이전트 역할 범위

포함

  • 웹앱이 준비한 제출 작업 시작 선언
  • 제출 패키지 조회
  • 사이트 진입 및 로그인 화면 이동
  • 사용자 로그인 대기
  • 입력값 자동 채우기
  • 첨부파일 자동 업로드
  • 최종 제출 직전 사용자 승인 대기
  • 제출 후 접수번호/필증/캡처 회수
  • 서버 상태 갱신

제외

  • 회원가입 / 로그인 / 계약 등록 / OCR 보정 같은 일반 업무용 웹앱 기능
  • 사업자/계약 판단 로직 최종 결정
  • 서버 DB 직접 수정
  • 사용자 승인 없이 최종 제출 강행
  • 장기 credential 저장
  • 법률 해석 자체 결정

5. 로컬 에이전트 기준 상태 머신

5.1 high-level 단계

1. idle

2. job_fetched

3. browser_opened

4. awaiting_login

5. filling_form

6. uploading_files

7. awaiting_final_approval

8. submitting

9. collecting_result

10. completed

11. failed

12. manual_handoff

5.2 서버 상태와 매핑

  • `idle` → 서버 상태 없음
  • `job_fetched` → `package_ready`
  • `awaiting_login` → `awaiting_login`
  • `filling_form` / `uploading_files` → `filling`
  • `awaiting_final_approval` → `awaiting_final_approval`
  • `submitting` → `submitted`
  • `collecting_result` → `submitted` 또는 내부 중간 상태
  • `completed` → `result_collected`
  • `failed` → `failed`

6. 표준 작업 흐름

Step 1. 작업 시작

에이전트는 서버에서 작업을 선택하거나 filing_job_id를 입력받는다.

호출 API

  • `GET /api/filing-jobs/{filing_job_id}`
  • `POST /api/filing-jobs/{filing_job_id}/agent-session`

예시 payload

{
  "agent_id": "macbook-hb-local",
  "action": "start"
}

기대 결과

  • 서버 상태가 `awaiting_login`으로 바뀐다.
  • 서버는 해당 작업이 누가 실행 중인지 기록한다.

Step 2. 패키지 로드

에이전트는 package_json, checklist_json, 첨부 경로를 로드한다.

에이전트 내부 검증

  • 필수 입력값 존재 여부
  • 필수 첨부 경로 존재 여부
  • channel 확인 (`renthome` / `local_government`)
  • 제출 대상 주택/계약 식별값 존재 여부

실패 시

  • 바로 `failed`로 두지 말고 먼저 로컬 validation 에러를 사용자에게 보여준다.
  • 서버에는 `POST /api/filing-jobs/{id}/status`로 사유 전달

예시 payload

{
  "job_status": "failed",
  "error_message": "required attachment missing: registration_doc",
  "payload": {
    "step": "preflight_validation"
  }
}

Step 3. 사이트 진입 및 로그인 대기

에이전트는 대상 채널에 맞는 로그인/초기 화면까지 이동한다.

채널별 기본 방향

  • `renthome`: 렌트홈 계약신고 흐름 진입
  • `local_government`: 지자체 신고 페이지 진입
  • `rtms_reference`: v1에서는 참고 흐름, 실제 제출 job 기본 비권장

이 시점 규칙

  • 사용자에게 로그인/인증을 요청한다.
  • 이 구간은 자동 우회하지 않는다.
  • 로그인 완료를 사용자가 클릭 또는 에이전트가 화면 변화를 감지해 확인한다.

서버 상태 갱신 예시

{
  "job_status": "awaiting_login",
  "error_message": null,
  "payload": {
    "screen": "login",
    "message": "사용자 로그인 대기"
  }
}

Step 4. 입력 자동화

로그인 완료 후 에이전트는 패키지 값을 폼에 채운다.

입력 대상 예시

  • 임대사업자 식별 정보
  • 주택 정보
  • 계약 체결일
  • 임대 개시/종료일
  • 보증금
  • 월세
  • 사건 유형
  • 변경 전후 정보

입력 원칙

  • 입력값은 `corrected_data_json` 우선
  • 없으면 `extracted_data_json` fallback
  • 자동 입력 전 화면값과 패키지 값을 비교할 수 있게 로컬 확인 UI 제공
  • 핵심 필드 입력 후 스크린샷 또는 DOM capture를 남길 수 있다.

서버 상태 갱신 예시

{
  "job_status": "filling",
  "error_message": null,
  "payload": {
    "step": "form_fields_completed",
    "completed_fields": [
      "lease_start_date",
      "lease_end_date",
      "deposit_amount",
      "monthly_rent"
    ]
  }
}

Step 5. 첨부 업로드

에이전트는 패키지에 지정된 첨부를 업로드한다.

업로드 대상 예시

  • 계약서 PDF
  • 표준임대차계약서
  • 등록증빙
  • 변경 증빙

규칙

  • 실제 업로드된 파일명/로컬 경로를 내부 로그로 남긴다.
  • 업로드 성공/실패를 구분해 사용자에게 보여준다.
  • 업로드 후 미리보기/첨부 목록 화면을 캡처 가능하게 둔다.

실패 처리

  • 특정 파일만 실패하면 우선 재시도 1~2회
  • 계속 실패하면 `awaiting_final_approval`로 가지 않고 `failed` 또는 `manual_handoff`

Step 6. 최종 제출 직전 사용자 승인

이 단계는 MVP에서 가장 중요하다.

원칙

  • 에이전트가 모든 필드를 채웠더라도 마지막 제출 버튼은 기본적으로 사용자가 직접 승인한다.
  • 에이전트는 화면 요약을 보여주고 “최종 제출 준비 완료” 상태를 만든다.

서버 상태 갱신

{
  "job_status": "awaiting_final_approval",
  "error_message": null,
  "payload": {
    "message": "최종 제출 직전",
    "review_items": [
      "tenant_name",
      "deposit_amount",
      "monthly_rent"
    ]
  }
}

사용자 승인 방식 v1

  • 버튼 클릭 전 확인 모달
  • 사용자가 “확인 후 제출” 버튼 클릭
  • 또는 사용자가 직접 최종 제출 버튼 클릭

Step 7. 제출 및 결과 감지

제출 후 에이전트는 결과 화면을 감지한다.

회수 대상

  • 접수번호
  • 접수 완료 문구
  • 필증 다운로드 링크 또는 파일
  • 결과 화면 캡처
  • 오류 메시지(실패 시)

서버 업로드 전 로컬 저장

  • 로컬 임시 폴더에 receipt/certificate/capture 보관
  • 업로드 성공 후 정리 또는 보존 정책 적용

Step 8. 결과 업로드

에이전트는 POST /api/filing-jobs/{filing_job_id}/results를 호출한다.

예시 payload

{
  "submission_status": "success",
  "receipt_number": "2026-RT-000123",
  "result_message": "정상 접수",
  "collected_at": "2026-04-19T16:20:00"
}

파일 첨부 예시

  • `receipt_file`
  • `certificate_file`
  • `result_capture`

기대 결과

  • 서버가 `filing_results` 생성
  • `followup_tasks` 자동 생성
  • `contract_events.event_status = filed`
  • `filing_jobs.job_status = result_collected`

7. 로컬 에이전트 입력값

필수 입력

  • `filing_job_id`
  • `agent_id`
  • 서버 base URL

선택 입력

  • 브라우저 프로필 경로
  • 다운로드 디렉터리
  • headless 여부 (운영 기본은 false 권장)
  • 디버그 캡처 여부

8. 로컬 에이전트 출력값

사용자에게 보여줄 것

  • 현재 단계
  • 로그인 필요 여부
  • 자동 입력 완료 항목
  • 첨부 업로드 상태
  • 최종 제출 대기 상태
  • 접수번호/회수 여부
  • 실패 시 수동 처리 필요 포인트

서버에 보낼 것

  • 현재 작업 상태
  • 오류 메시지
  • 결과 메타
  • 회수 파일
  • 선택적으로 progress payload

9. 실패 복구 규칙

9.1 자동 재시도 허용

다음은 1~2회 재시도 허용

  • 일시적 네트워크 오류
  • 페이지 느린 로딩
  • 업로드 클릭 미반응
  • 결과 파일 다운로드 타이밍 문제

9.2 즉시 사람 개입 요청

다음은 자동 재시도보다 사람 개입이 우선

  • 로그인 실패
  • 인증서/간편인증 실패
  • 보안모듈 설치 요구
  • 필수 입력값 불일치
  • 사이트 구조가 바뀌어 selector가 사라짐
  • 최종 제출 후 오류 사유가 법률/업무 판단 필요 케이스

9.3 실패 시 서버 보고 방식

기본 예시

{
  "job_status": "failed",
  "error_message": "selector_not_found: submit_button",
  "payload": {
    "step": "awaiting_final_approval",
    "recoverable": false
  }
}

9.4 manual_handoff 조건

아래면 수동 전환 권장

  • 제출 자체는 가능하지만 자동화가 불안정
  • 파일 업로드까지만 성공하고 마지막 단계에서 selector drift
  • 접수는 됐지만 필증 회수만 실패

이 경우 서버에는 failed 또는 별도 note를 남기고 운영 화면에서 “수동 후속 처리 필요”로 본다.

10. 로컬 저장소 규칙

권장 디렉터리 예시

  • `~/dudu-agent/jobs/{filing_job_id}/input/`
  • `~/dudu-agent/jobs/{filing_job_id}/downloads/`
  • `~/dudu-agent/jobs/{filing_job_id}/captures/`
  • `~/dudu-agent/jobs/{filing_job_id}/logs/`

보관 대상

  • 실행 로그
  • 주요 단계 캡처
  • 다운로드 파일 원본
  • 업로드에 사용한 파일 사본(선택)

주의

  • 장기 보관이 필요한 원본/결과는 서버에도 올려야 한다.
  • 로컬 경로만 있고 서버 업로드가 안 된 상태를 성공으로 보면 안 된다.

11. 사용자 UX 원칙

  • 로그인과 최종 제출은 사용자가 확실히 인지해야 한다.
  • “지금 무엇을 기다리는지”를 짧고 명확하게 보여준다.
  • 실패 시 기술용어보다 행동지시를 먼저 보여준다.
  • 예: “로그인 다시 필요”
  • 예: “등록증빙 파일 다시 선택 필요”
  • 예: “최종 제출 화면 구조가 바뀌어 수동 진행 필요”

12. v1 비목표

  • 여러 채널 동시 자동 제출
  • 백그라운드 무인 대량 제출
  • 사이트별 완전 공통 추상화
  • 원클릭 무인 운영
  • 인증수단 자동 보관/재사용

13. 구현 체크리스트

1. `GET /api/filing-jobs/{id}` 연동

2. `POST /api/filing-jobs/{id}/agent-session` 연동

3. `POST /api/filing-jobs/{id}/status` 연동

4. `POST /api/filing-jobs/{id}/results` multipart 업로드 연동

5. 채널별 브라우저 진입 함수 분리

6. 로그인 대기 UI 구현

7. 자동 입력/첨부 업로드 모듈 구현

8. 최종 승인 대기 모듈 구현

9. 결과 회수 모듈 구현

10. 실패 복구/수동 전환 메시지 구현

14. 바로 다음 작업

  • `test_scenarios_v1.md` 작성
  • 아래 시나리오를 이 명세 기준으로 고정
  • 신규 계약 정상 제출
  • 변경 계약 정상 제출
  • 재계약/묵시적 갱신 분기
  • 로그인 실패
  • 첨부 업로드 실패
  • 접수증 회수 실패
  • 제출 후 수동 전환