Private
Tracker *Bug Feature Support
Subject *
Description # [T155] 크롤러 관리자 API 및 권한 연동 ## 1. 작업 목적 AI Career Platform의 기존 FastAPI Backend와 T151~T154에서 구축한 크롤러 기능을 연동하여, **관리자가 웹 화면에서 크롤러 검색어·수집 일정·실행 상태·오류·통계를 조회하고 관리할 수 있는 REST API**를 개발한다. 기존 인증·인가 API(T15) 및 공통 Backend 구조를 최대한 재사용한다. 이번 작업의 핵심은 새로운 크롤러 엔진을 개발하는 것이 아니라, 기존 크롤러 기능을 안전하게 호출하고 관리할 수 있는 API 계층을 구현하는 것이다. 최종적으로 T156 관리자 웹 UI에서 사용할 수 있도록 OpenAPI/DTO 계약, 권한 검증, 오류 처리 및 감사 이력을 제공한다. ## 2. 주요 개발 내용 ### ① 기존 Backend·인증 구조 확인 개발 전 다음 항목을 확인한다. - 기존 FastAPI 애플리케이션 및 Router 구조 - T15 로그인·인증·인가 구현 상태 - 관리자 역할 및 권한 관리 방식 - PostgreSQL 연결 및 Session 관리 구조 - 기존 API 응답·예외 처리·로깅 규칙 - T151~T154에서 구현한 관리 기능 및 데이터 계약 기존 인증·인가 기능이 검증되지 않았다면 임의의 관리자 인증을 새로 만들지 않는다. 인증 검증이 가능한 범위에서만 API를 구현하며, 관리자 인증이 필요한 기능은 선행 조건 미충족 시 HOLD로 관리한다. ### ② 검색어 관리 API T151의 검색어 관리 기능을 API로 제공한다. 주요 기능: - 검색어 목록 조회 - 검색어 신규 등록 - 검색어 수정 - 검색어 활성화·비활성화 - 검색어 삭제 - 검색어 우선순위 변경 예시 API: | Method | Endpoint | 기능 | |---|---|---| | GET | /api/v1/admin/crawler/keywords | 검색어 목록 | | POST | /api/v1/admin/crawler/keywords | 검색어 등록 | | PATCH | /api/v1/admin/crawler/keywords/{keyword_id} | 검색어 수정 | | DELETE | /api/v1/admin/crawler/keywords/{keyword_id} | 검색어 삭제 | 경로는 예시이며 기존 T06 API 계약 및 Backend Router 구조와 대조한 후 확정한다. 초기 등록된 AX 2기 검색어 6개를 조회·편집할 수 있어야 한다. ### ③ 수집 스케줄·설정 관리 API T154의 Scheduler 및 작업 관리 기능과 연동한다. 관리 대상: - 실행 가능 시작·종료 시각 - 검색어별 활성화 여부 - 배치당 처리 건수 - 최대 동시 실행 작업 수 - 최근 공고 재확인 기간 - 마지막 성공 수집 시각 - 다음 예정 실행 시각 - 스케줄 활성화·비활성화 상태 예시 API: - GET /api/v1/admin/crawler/schedules - PATCH /api/v1/admin/crawler/schedules 초기 실행 가능 시간창은 21:00~다음 날 08:00 KST로 설정하되 관리자가 변경할 수 있도록 한다. 단, 관리자 설정 변경이 실제 외부 사이트 수집 권한을 자동으로 부여하지 않는다. 실제 Live 수집은 T61의 별도 실행 조건이 충족되지 않으면 차단한다. ### ④ 수집 작업 및 실행 이력 조회 API T151 작업 큐와 T64 Scheduler·Dispatcher 실행 이력을 활용한다. 주요 조회 항목: - 실행 ID 및 작업 ID - 검색어 - 실행 예정 시각 - 시작·종료 시각 - 현재 실행 상태 - 수집 대상 건수 - 수집 완료 건수 - 신규 INSERT 건수 - UPDATE 건수 - 중복 건수 - 파싱 실패 건수 - 오류 코드 - 마지막 체크포인트 예시 API: - GET /api/v1/admin/crawler/jobs - GET /api/v1/admin/crawler/jobs/{job_id} - GET /api/v1/admin/crawler/runs - GET /api/v1/admin/crawler/runs/{run_id} 목록 조회는 페이지네이션·필터·정렬을 지원한다. ### ⑤ 실패 작업 재처리 및 실행 관리 API 관리자가 실패 작업을 확인하고 허용된 범위에서 재처리할 수 있도록 한다. 주요 기능: - 실패 작업 상세 조회 - 실패 원인 및 오류 이력 조회 - 저장된 Raw HTML 재파싱 요청 - 미완료 작업 재개 요청 - 작업 중단 요청 - 실행 상태 및 결과 확인 예시 API: - POST /api/v1/admin/crawler/jobs/{job_id}/retry - POST /api/v1/admin/crawler/jobs/{job_id}/cancel - POST /api/v1/admin/crawler/artifacts/{artifact_id}/reparse 재처리는 기존 T153·T154 기능을 호출하며, 관리 API에서 별도의 크롤러 처리 로직을 중복 구현하지 않는다. 동일 요청 중복 처리 방지, 실행 상태 검증 및 감사 이력 기록을 적용한다. ### ⑥ 수집 통계 및 오류 로그 API 관리자가 수집 결과와 장애 현황을 확인할 수 있도록 한다. 주요 통계: - 검색어별 수집 건수 - 신규·수정·중복 공고 건수 - 정상 파싱·검증 실패 건수 - 실행 성공·실패·중단 건수 - 마지막 정상 실행 시각 - 최근 실행 이력 - 오류 유형별 발생 건수 예시 API: - GET /api/v1/admin/crawler/stats - GET /api/v1/admin/crawler/events 수집 오류와 실행 로그는 관리자가 문제를 진단하는 데 필요한 범위로 제공한다. Raw HTML 전체 본문·DB 비밀번호·인증 토큰·민감정보는 API 응답과 로그에 노출하지 않는다. ### ⑦ 관리자 인증·인가 및 감사 이력 관리자 API에는 기존 T15 인증·인가 체계를 적용한다. - 인증되지 않은 요청: 401 - 권한 없는 사용자: 403 - 잘못된 입력값: 422 또는 기존 API 계약의 오류 코드 - 존재하지 않는 데이터: 404 - 중복·충돌 요청: 409 등 계약에 맞는 응답 검색어 변경, 스케줄 변경, 수집 작업 재처리 및 중단 등 관리 작업은 감사 이력을 기록한다. 관리자라도 T61 수집 제한을 우회할 수 없도록 한다. ### ⑧ API 문서 및 테스트 FastAPI OpenAPI/Swagger 문서를 통해 관리자 API를 확인할 수 있도록 구성한다. 주요 테스트: - 정상 요청 및 응답 DTO 검증 - 검색어 중복 등록 - 잘못된 검색어·설정값 - 존재하지 않는 작업 ID - 권한 없는 사용자 접근 - 중복 실행 및 재처리 요청 - Live 수집 활성화 차단 - 기존 Backend API 회귀 테스트 외부 사이트 요청 없이 합성 Fixture 및 격리 DB로 검증한다. ## 3. 개발 일정 **시작일: 2026-12-02 (수)** **완료예정일: 2026-12-07 (월)** | 날짜 | 주요 작업 | |---|---| | 12/02 (수) | 기존 FastAPI·T15 인증·T151~T154 계약 분석, API/DTO 확정 | | 12/03 (목) | 검색어 CRUD·스케줄 설정 API 구현 | | 12/04 (금) | 작업 이력·통계·오류·재처리 및 관리자 권한 연동 | | 12/07 (월) | Swagger·권한·Fixture 통합 테스트, PR·CI 및 완료 보고 | 일정은 선행 일감 완료를 전제로 한 계획이며 실제 개발 결과에 따라 조정할 수 있다. ## 4. 기존 시스템 재사용 - T15 인증·인가 API - T151 검색어·수집 작업 관리 - T152 Raw HTML Storage - T153 Parse Worker·Validation·재처리 - T154 증분 수집·Scheduler·작업 재개 - T64 실행 이력·run_events·Dispatcher - 기존 FastAPI Router·DTO·DB 연결 및 오류 처리 체계 기존 기능을 중복 구현하지 않고 API 계층에서 연결한다. ## 5. 개발 및 안전 원칙 1. 기존 FastAPI 및 인증·인가 구조를 최대한 재사용한다. 2. 관리자 API를 인증 없이 외부에 공개하지 않는다. 3. 관리자 권한만으로 Live 수집을 활성화할 수 없도록 한다. 4. 실제 잡코리아 수집은 현재 HOLD를 유지한다. 5. 합성 Fixture 및 격리 DB로 우선 검증한다. 6. Raw HTML 전체 본문과 민감정보를 관리자 API 응답에 노출하지 않는다. 7. 모든 관리 변경 작업은 감사 이력을 남긴다. 8. 기존 DB·Auto-CD·Docker 볼륨 및 서비스를 보호한다. 9. 기존 Live 스케줄 및 systemd Timer 비활성 상태를 유지한다. 10. 관리자 웹 UI 구현은 T156에서 진행한다. ## 6. 완료 기준 (DoD) - [ ] 기존 FastAPI·인증·인가 구조 확인 - [ ] 검색어 목록·등록·수정·삭제 API - [ ] 검색어 활성화·비활성화·우선순위 변경 - [ ] 수집 일정·배치 설정 조회·변경 API - [ ] 수집 작업 목록 및 상세 조회 API - [ ] 실행 이력 및 오류 로그 조회 API - [ ] 검색어별 수집 통계 API - [ ] 실패 작업 재처리·중단 API - [ ] 관리자 인증·인가 적용 - [ ] 비관리자 401/403 및 쓰기 차단 테스트 - [ ] 중복 요청·실행 충돌·입력 오류 처리 - [ ] 관리 작업 감사 이력 검증 - [ ] Live 수집 무단 활성화 차단 - [ ] Swagger/OpenAPI 계약 확인 - [ ] 기존 Backend API 회귀 테스트 - [ ] 합성 Fixture 기반 관리자 API E2E PASS - [ ] 외부 HTTP 요청 0건 확인 - [ ] 기존 서비스·DB·Auto-CD 보존 - [ ] GitHub PR 및 필수 CI PASS - [ ] main Merge 및 실제 Staging Fixture QA PASS - [ ] Redmine Evidence 등록 및 완료 검수 ## 7. 제출 산출물 - FastAPI 관리자 Router 및 Service 코드 - 검색어·수집 설정·실행 이력 API - 관리자 인증·인가 및 감사 로그 연동 - OpenAPI/DTO 계약 문서 - pytest·TestClient 정상·오류·권한 테스트 - 합성 Fixture 기반 API 통합 검증 결과 - GitHub PR URL·CI 결과·Merge SHA - Staging API 검증 및 기존 서비스 보호 보고서 ## 8. GitHub 작업지시서 https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/work-orders/crawler-enhancement/T155.md ## 9. 최종 목표 관리자가 크롤러 검색어, 실행 일정, 수집 작업 상태, 오류 및 결과 통계를 안전하게 관리할 수 있는 FastAPI 기반 관리자 API를 구축한다. 기존 T151~T154 기능을 재사용하여 중복 개발을 방지하고, T156 관리자 웹 UI가 직접 연동할 수 있는 완성된 API 계약을 제공한다. **완료 판정:** 관리자 API의 기능·권한·오류·Fixture 통합 검증이 PASS되고, GitHub PR·CI·Staging QA Evidence가 확인되면 완료 처리한다. Edit
Status *New In Progress Resolved Feedback Closed Rejected
Priority *Low Normal High Urgent Immediate
Assignee 길래 문DONGHYUN WooLio yunRedmine AdminYeoreum Kim길래 문나경 고다라 정박 진상재 이서현 임성용 양성호 최수아 황영우 조예주 김예진 전우섭 심정민 조종복 김중섭 안지나 팡충만 장형준 안희주 노희주 채
Parent task
Start date
Due date
Estimated time Hours
% Done0 % 10 % 20 % 30 % 40 % 50 % 60 % 70 % 80 % 90 % 100 %
Spent time Hours
Activity--- Please select --- Design Development
Comment