Project

General

Profile

Feature #1583

open
길문 길문

Feature #1577: [AX 2기] 채용공고 크롤러 고도화 및 관리자 웹 통합 구축

[T156] 크롤러 관리자 웹 UI 및 통합 QA

Feature #1583: [T156] 크롤러 관리자 웹 UI 및 통합 QA

Added by 길래 문 9 days ago.

Status:
New
Priority:
Normal
Assignee:
Start date:
12/08/2026
Due date:
12/14/2026 (Due in 27 days)
% Done:

0%

Estimated time:

Description

[T156] 크롤러 관리자 웹 UI 및 통합 QA

1. 작업 목적

AI Career Platform의 기존 Frontend 및 T151~T155에서 구현한 크롤러 기능을 활용하여, 크롤러 전체 운영 현황을 확인하고 관리할 수 있는 웹 기반 관리자 콘솔을 구축한다.

관리자는 별도의 Python 명령어를 실행하거나 PostgreSQL에 직접 접속하지 않고 브라우저에서 다음 기능을 사용할 수 있어야 한다.

  • AX 2기 채용공고 검색어 관리
  • 크롤러 수집 일정 및 설정 관리
  • 수집 작업 진행 상태 모니터링
  • 수집 결과 및 데이터 품질 통계 확인
  • 오류·실패 작업 조회 및 재처리
  • 최근 실행 이력 및 상세 로그 조회

기존 Frontend 공통 레이아웃·인증 체계를 재사용하고, T155 관리자 API와 연동한다.

최종적으로 관리자 UI → FastAPI → Scheduler / Worker → PostgreSQL까지 연결되는 전체 학습용 크롤러 파이프라인의 E2E 검증을 수행한다.

2. 관리자 웹 주요 화면

① 관리자 대시보드

크롤러 전체 운영 상태를 한 화면에서 확인할 수 있도록 한다.

주요 표시 항목:

  • 크롤러 활성화 상태
  • 현재 실행 중인 작업 수
  • 마지막 정상 실행 시각
  • 다음 예정 실행 시각
  • 등록된 검색어 수
  • 최근 수집 공고 수
  • 신규·수정·중복 공고 수
  • 파싱·검증 실패 건수
  • 최근 오류 및 실행 이력

각 수치에는 집계 기준 시각 및 기간을 표시하여 통계 의미가 명확하도록 한다.

② 검색어 관리 화면

T151에서 정의한 AX 2기 기본 검색어 6개를 표시한다.

우선순위 검색어 초기 상태
1 AI 활성
2 Python 활성
3 데이터 분석 활성
4 LLM 활성
5 업무 자동화 활성
6 AI 엔지니어 활성

관리 기능:

  • 검색어 등록
  • 검색어 수정
  • 검색어 활성화·비활성화
  • 검색어 삭제
  • 검색어 우선순위 변경
  • 검색어별 수집 결과 및 상태 확인

동일 검색어 중복 등록을 방지하고, 삭제 시 관련 공고 및 기존 수집 이력이 의도치 않게 삭제되지 않도록 한다.

검색어 변경은 T155 관리자 API를 통해 처리하며 Frontend에서 직접 DB를 수정하지 않는다.

③ 수집 일정 및 설정 관리 화면

T154의 Scheduler 설정을 관리자 화면에서 확인하고 변경할 수 있도록 한다.

주요 설정:

  • 실행 가능 시작 시각
  • 실행 가능 종료 시각
  • 시간대
  • 검색어별 활성화 상태
  • 배치당 처리 건수
  • 최대 동시 실행 작업 수
  • 최근 공고 재확인 기간
  • 스케줄 활성화·비활성화

초기 실행 가능 시간창은 21:00~다음 날 08:00 KST로 제안한다.

관리자는 시간창을 수정할 수 있지만, 설정 변경만으로 허용되지 않은 실제 외부 사이트 수집이 활성화되어서는 안 된다.

현재 Live 수집은 HOLD 상태를 유지하며, 허용 조건이 검증되지 않은 실행 옵션은 비활성화하거나 차단 사유를 명확하게 표시한다.

④ 수집 실행 현황 화면

실행 중인 작업과 완료된 작업의 진행 상태를 확인할 수 있도록 한다.

주요 표시 항목:

  • 실행 ID / 작업 ID
  • 검색어
  • 작업 유형
  • 예정·시작·종료 시각
  • 현재 상태
  • 완료 및 미완료 건수
  • 신규·수정·중복 건수
  • 마지막 체크포인트
  • 오류 여부

작업 상태는 Backend 계약에 정의된 실제 상태값을 사용한다.

진행률을 정확하게 계산할 수 없는 경우 임의의 백분율을 표시하지 않고, 완료 건수와 현재 처리 단계를 표시한다.

⑤ 원본·파싱·데이터 품질 현황

T152~T153의 원본 수집 및 후처리 상태를 조회한다.

주요 기능:

  • 목록·상세 원본 수집 건수
  • 원본 저장 성공·실패 건수
  • 파싱 완료·실패 건수
  • 검증 성공·실패 건수
  • 정제 DB 반영 건수
  • 오류 유형별 건수
  • 파서 버전별 처리 이력
  • Raw Artifact와 정제 공고 연결 상태 조회

원본 HTML 전체 본문은 기본적으로 관리자 화면에 노출하지 않는다.

필요한 경우에도 승인된 메타데이터만 조회하도록 한다.

⑥ 실행 이력 및 오류 관리 화면

검색어 및 실행 작업별 오류를 확인할 수 있도록 한다.

주요 기능:

  • 최근 실행 목록
  • 기간·검색어·상태별 검색
  • 작업별 상세 이벤트 조회
  • 실패 사유 및 오류 코드 표시
  • 이전 실행과 결과 비교
  • 재처리 가능 여부 표시
  • 실패 작업 재처리 요청
  • 작업 중단 요청

재처리 및 중단 기능은 T155 관리자 API의 권한·상태 검증을 통과한 경우에만 제공한다.

작업이 이미 완료되었거나 실행이 허용되지 않은 상태에서는 적절한 안내 메시지를 표시한다.

3. Frontend 구현 원칙

기존 기능 재사용

  • T19 Frontend 프로젝트 구조
  • T20 공통 레이아웃·UI 컴포넌트
  • T21 로그인·사용자 인증 UI
  • T155 크롤러 관리자 API
  • 기존 API 클라이언트 및 오류 처리 규칙

새로운 관리자 사이트를 별도 프로젝트로 중복 개발하기보다는 기존 Frontend 내 관리자 전용 메뉴와 화면으로 통합하는 것을 우선 검토한다.

실제 관리자 페이지 경로는 기존 라우팅 구조를 확인한 후 확정한다.

사용성 및 접근성

  • 검색어 편집 시 저장·취소 구분
  • 삭제 및 위험한 변경에 확인 절차 적용
  • API 오류 메시지 표시
  • 로딩·빈 결과·오류 상태 구분
  • 테이블 페이지네이션 및 필터
  • 날짜·시간대 명확히 표시
  • 키보드 조작 및 기본 웹 접근성 지원
  • 관리자 권한 없는 사용자 접근 차단

4. 전체 통합 E2E 검증

이번 일감의 핵심 완료 조건은 화면 구현뿐 아니라, 기존 크롤러 기능이 하나의 시스템으로 연결되어 실제 동작하는지 확인하는 것이다.

다음 통합 시나리오를 검증한다.

STEP 01 — 검색어 관리

관리자 로그인 → AX 2기 검색어 6개 조회 → 검색어 등록·수정·비활성화 검증

STEP 02 — 수집 작업 생성

관리자 설정 → 검색어별 Fixture 수집 작업 생성 → 작업 큐·실행 상태 확인

STEP 03 — HTML 원본 수집

Fetch Worker → 합성 목록·상세 HTML 확보 → Raw Storage 저장 → 메타데이터 확인

STEP 04 — 파싱·검증

Parse Worker → 저장된 원본 로딩 → 필드 추출·정규화·검증 → 처리 결과 기록

STEP 05 — PostgreSQL 반영

정상 공고 UPSERT → 중복 제거 → 검색어·공고 발견 관계 확인

STEP 06 — 증분 수집·재개

마지막 성공 체크포인트 확인 → 미완료 작업 재개 → 동일 공고 중복 생성 방지

STEP 07 — 관리자 화면 검증

수집 결과·실행 이력·검색어별 통계·오류 로그 조회

STEP 08 — 장애 및 권한 검증

작업 실패·재처리·중단, 비관리자 401/403, 잘못된 입력 및 접근 제한 차단 검증

모든 테스트는 실제 외부 사이트 수집 없이 합성 Fixture 및 승인된 학습용 스테이징 환경에서 진행한다.

5. 개발 일정

시작일: 2026-12-08 (화)

완료예정일: 2026-12-14 (월)

날짜 주요 작업
12/08 (화) 기존 Frontend 분석, 관리자 메뉴·라우팅 및 화면 구조 설계
12/09 (수) 관리자 대시보드·검색어 관리 UI 구현
12/10 (목) 수집 일정·실행 현황·통계 UI 구현
12/11 (금) 실행 이력·오류·재처리 UI 및 T155 API 연동
12/14 (월) 전체 Fixture E2E, 권한·회귀 테스트, PR·CI·Staging QA 및 완료 보고

일정은 T151~T155의 필수 기능이 완료되었다는 전제의 계획이며 실제 개발 결과에 따라 조정할 수 있다.

6. 기존 시스템 재사용 및 보호

기존 구현을 우선 재사용한다.

  • T151 검색어·작업 관리
  • T152 Fetch Worker·Raw Storage
  • T153 Parse Worker·Validation·UPSERT
  • T154 Scheduler·증분 수집·장애 복구
  • T155 관리자 API·인증·인가
  • T19~T21 Frontend 기본 구조·공통 UI·인증
  • 기존 PostgreSQL 및 Docker Compose
  • 기존 GitHub CI·Auto-CD

기존 Frontend를 전면 교체하거나 별도 관리자 사이트를 중복 구축하지 않는다.

기존 서비스 및 DB, 컨테이너·볼륨, 크롤러 실행 이력과 스케줄 설정을 보존한다.

7. 개발 및 안전 원칙

  1. 기존 Frontend 공통 구조를 최대한 재사용한다.
  2. 관리자 UI는 인증 및 권한 검증을 거친 사용자에게만 제공한다.
  3. Frontend는 DB에 직접 접근하지 않고 T155 API를 사용한다.
  4. 실제 잡코리아 Live 수집은 현재 HOLD를 유지한다.
  5. 합성 Fixture 기반으로 기능을 개발하고 통합 검증한다.
  6. 원본 HTML 전체 본문 및 민감정보를 기본 화면에 노출하지 않는다.
  7. 실제 수집 권한이 없는 상태에서는 Live 실행·활성화 기능을 차단한다.
  8. 기존 Auto-CD·Docker 볼륨·DB 데이터를 보호한다.
  9. 기존 systemd Timer 및 Live 스케줄을 임의로 활성화하지 않는다.
  10. 테스트 결과가 확인되지 않은 기능은 PASS로 보고하지 않는다.

8. 완료 기준 (DoD)

  • 기존 Frontend 관리자 메뉴·라우팅 구조 확인
  • 관리자 대시보드 구현
  • AX 2기 검색어 6개 조회·CRUD UI
  • 검색어 활성화·비활성화 및 우선순위 변경
  • 수집 시간창·배치 설정 관리 UI
  • 작업 실행 현황 및 상태 조회
  • 검색어별 수집·신규·중복·오류 통계 표시
  • Raw HTML 수집·파싱·검증 상태 조회
  • 실행 이력·상세 오류 조회
  • 실패 작업 재처리·중단 UI
  • T155 관리자 API 정상 연동
  • 로그인·관리자 권한·비관리자 접근 차단
  • 401/403/404/409/422 등 API 오류 처리
  • 로딩·빈 결과·키보드 조작·접근성 검증
  • 검색어 변경 → Fixture 수집 → Raw 저장 → Parse → UPSERT → 결과 조회 E2E PASS
  • 증분 수집·작업 재개·중복 방지 검증
  • 기존 Frontend·Backend 회귀 테스트
  • 실제 외부 HTTP 요청 0건 확인
  • 기존 앱 DB·크롤러 DB·Docker 볼륨 및 Auto-CD 보존
  • GitHub PR 및 필수 CI PASS
  • main Merge 및 실제 Staging Fixture QA PASS
  • 관리자 웹 접근 URL 및 검증 Evidence 기록
  • Redmine Evidence 등록 및 최종 완료 검수

9. 제출 산출물

  • 크롤러 관리자 Frontend 화면 및 컴포넌트
  • 검색어 관리·스케줄·실행 현황·오류·통계 UI
  • T155 관리자 API 연동 코드
  • UI·API 통합 테스트
  • 관리자 인증·권한 및 오류 처리 테스트
  • Fixture 기반 전체 크롤러 E2E 검증 보고서
  • 기존 서비스·DB·Auto-CD 보호 검증 결과
  • GitHub PR URL·CI 결과·Merge SHA
  • 실제 Staging 배포 결과 및 관리자 화면 URL
  • 관리자 사용 안내 문서

10. GitHub 작업지시서

https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/work-orders/crawler-enhancement/T156.md

11. 최종 목표

AX 2기 채용공고 크롤러를 관리자 웹 화면에서 통합적으로 관리할 수 있도록 구현한다.

관리자는 검색어와 수집 설정을 변경하고, 작업 진행 상태·수집 건수·중복·파싱 오류·실행 이력을 확인하며, 허용된 범위에서 실패 작업 재처리를 요청할 수 있어야 한다.

최종 완료 판정: T151~T156 전체 기능이 학습용 Fixture 환경에서 통합 검증되고, GitHub PR·CI·Auto-CD·Staging QA Evidence 및 기존 서비스 보존 결과가 확인되면 완료 처리한다. 실제 외부 사이트 Live 수집 활성화는 별도 조건으로 관리한다.


Add

Subtasks


Add

Related issues

No data to display

Also available in: PDF Atom