Paper-Monitoring-SW/paper-monitor-todo.md

# Paper Monitor 프로젝트 - 남은 작업 및 검토 TODO

최종 업데이트: 2026-08-21

이 문서는 지금까지 구축한 Synology NAS 기반 논문 자동 모니터링 시스템에서 **아직 미정이거나 수행하지 못한 항목**, 그리고 **운영 전에 변경 또는 추가 검토가 필요한 항목**을 정리한 TODO 목록이다.

---

## P0 - 다음 즉시 처리

### [ ] 최종 보고서 필터링 수정
현재 run 결과 예시:
- collected: 229
- merged: 207
- accepted: 28
- new: 0
- report_count: 86

`report_count`에 Scholar 관련성 임계값 변경 이전에 삽입된 논문이 포함되어 있음.

보고서 생성 시 현재 최종 관련성 기준을 반영하도록 수정 필요.

### [ ] 최종 보고서 선택에 Gemini 관련성 적용
현재 문제:
- rule-based 필터링이 Gemini 이전에 실행됨
- rule-based에서 accepted된 논문이 이후 Gemini 관련성 1~2를 받아도 보고서에 잔류함
- 자동차 레이더 보고서에 무관한 일반 MIMO/C-band/5G 안테나 논문이 포함됨

정책 정의 필요 (예):
- Gemini 분석 완료: AI 관련성 >= 3인 논문만 포함
- AI 분석 미수행/불가: rule-based 관련성으로 fallback

### [ ] Unpaywall HTTP 404 처리 수정
- 현재 404 응답이 traceback 예외로 처리됨
- `not_found`로 처리해야 함 (정상 케이스)
- `exc.response is not None` 조건으로 수정
- 누락된 DOI 레코드에 대한 불필요한 traceback 없이 파이프라인 계속 실행

---

## 1. 즉시 처리 권장

### [ ] Semantic Scholar 차단 해제 후 재활성화
- 현재 상태: 접근 제한/차단 상태이므로 `enabled: false` 권장
- 차단이 풀린 뒤 다시 활성화
- 재활성화 후 확인
  - 2.5초 이상 요청 간격이 실제 적용되는지
  - circuit breaker가 429 지속 시 정상 동작하는지
  - 한 run에서 과도한 재시도가 발생하지 않는지
- 정상화 후에도 429가 잦으면 검토
  - 요청 간격 3~5초로 증가
  - 검색 query 수 축소
  - `max_retries` 추가 축소

### [ ] IEEE 접근 차단 해제 여부 확인
- 현재 상태
  - 집 인터넷: `developer.ieee.org` -> HTTP 403
  - 동일 PC + 휴대폰 테더링: HTTP 200 OK
  - 현재 공인 IP 또는 해당 회선이 IEEE/Mashery/WAF에서 제한된 가능성이 매우 높음
- 현재는 `IEEE enabled: false` 유지
- 차단 해제 후에만 다시 활성화
- 재활성화 시 먼저 1개 query만 수동 테스트
- 401 / 403 / 429 / timeout / connection error 발생 시 해당 run의 IEEE 전체 중단 유지
- 동일 run에서 IEEE 자동 retry는 하지 않음
- 요청 간 최소 간격 5초 유지

### [ ] IEEE API 승인 상태 확인
- 네트워크 차단 문제와 API 승인 문제는 별개
- IEEE API key가 최종 승인되었는지 확인 후 활성화
- 웹사이트 접속 정상화와 API 승인 상태를 각각 확인

### [ ] 노출된 IEEE API key 교체 여부 확인
- 과거 오류 로그에 API key가 query string 형태로 노출된 적이 있음
- 아직 교체하지 않았다면 새 API key 발급/회전 권장
- 현재 수정한 IEEE collector는 향후 오류 로그에서 key가 노출되지 않도록 유지

---

## 2. 스케줄러 / 운영 설정

현재 미완료 항목 없음. 완료된 내용은 문서 하단 `완료 항목` 섹션 참조.

---

## 3. 검색 범위 및 수집 정책

### [ ] `lookback_days: 14` 유지 여부 장기 검토
현재:
```yaml
lookback_days: 14
```

주 1회 실행에는 안전한 값이며 현재는 유지 권장.

향후 확인:
- 매주 중복 수집량이 지나치게 많으면 10일 정도로 감소 검토
- publication date가 늦게 반영되는 source가 많으면 14일 유지

### [ ] Query 목록 재정비
현재 자동차 레이더 관련 다수 query 사용.

검토 필요:
- 중복도가 지나치게 높은 query 제거
- 실제 유용 논문을 거의 만들지 않는 query 제거
- 주요 관심영역별 query 분리

예:
- Automotive radar
- Imaging radar / 4D radar
- FMCW / Waveform
- MIMO / DDMA
- DOA / Wideband DOA / Super-resolution
- Antenna
- Target modeling / Scattering center
- Interference / RF impairment

### [ ] Source별 query 목록 분리 검토
IEEE, Semantic Scholar, Crossref에서 동일한 query 세트를 사용하는 대신 source 특성에 맞게 별도 query 목록을 둘지 검토.

예:
```yaml
sources:
  crossref:
    queries: [...]
  semantic_scholar:
    queries: [...]
  ieee:
    queries: [...]
```

장점:
- API 호출량 감소
- 불필요한 중복 감소
- IEEE와 Semantic Scholar 차단 가능성 감소

### [ ] Google Scholar 관련성 임계값 검토
수회 스케줄 실행 후 확인 필요.

현재 설정:
- Scholar 관련성 임계값: 3
- 전역 임계값: 2

확인:
- 관련 자동차 레이더 논문이 임계값 3으로 인해 누락되는지 여부
- 누락이 발견되면 임계값 2로 낮출지 검토

### [ ] Scholar 파서 개선 (필요 시)
현재 collector가 여전히 광범위한 알림 결과를 수집함.

권장 접근:
- 알림/쿼리 설정 개선 및 하위 관련성 점수 개선을 우선 시도
- 공격적인 제목 키워드 필터링보다 쿼리 수준에서 범위 조정
- 새로운 비논문 항목이 나타나면 UI 링크 제외 목록 추가

### [ ] `classify_and_score()` 점수 규칙 검토
다음 항목에 대해 자동차 레이더 관련성이 명확하지 않으면 낮은 관련성 점수 부여:
- 일반 MIMO
- 일반 안테나
- 통신 전용 ISAC
- C/X/sub-6 GHz 논문
- 비레이더 DOA 논문

---

## 4. Gemini AI 운영 설정

### [x] Gemini 13초 요청 간격 추가
무료 5 RPM 한도 보호를 위해 요청 간 13초 대기 적용 완료.

### [x] Gemini 무료 5 RPM 한도에서 429 오류 없음 확인
13초 간격 적용 후 실제 운영에서 429 발생 없음 확인.

### [x] 이전 실패 Gemini 논문 재시도 구현
`ai_status=failed`인 논문을 다음 run에서 자동 재시도하는 로직 구현 완료.

### [ ] Gemini 429 RetryInfo/backoff 명시적 처리
13초 간격이 주 보호 수단.
그러나 임시 quota/rate-limit 응답에 대한 방어 처리 추가 검토:
- `RetryInfo` 헤더를 파싱하여 대기 시간 준수
- 429 발생 시 지수 백오프 fallback

### [ ] Gemini 무료 quota 실제 사용량 모니터링
확인 항목:
- full-text 요청 수
- abstract-only 요청 수
- 한 run에서 token 사용량
- quota 초과/429 발생 여부

필요 시:
- full-text 분석 대상 relevance threshold 추가
- 예: rule-based 또는 abstract AI relevance가 높은 논문만 full-text 분석

### [ ] Full-text AI 2단계 분석 구조 검토
현재는 OA PDF가 있으면 바로 full-text 분석.

향후 비용 절감 구조 검토:
1. 모든 신규 논문 -> title + abstract 분석
2. relevance >= 특정 값인 논문만 OA PDF full-text 분석

예:
```text
abstract AI relevance >= 4/5
    -> full-text AI
else
    -> abstract 결과만 유지
```

장점:
- Gemini 호출량/토큰 절감
- PDF 다운로드/파싱 횟수 감소

### [ ] Gemini 모델명 config 기반 유지
현재 `gemini-3.6-flash` 사용.

향후 모델 변경 가능성을 고려해 hard-code 최소화.
`config.nas.yaml` 값만 바꾸면 동작하도록 유지.

### [ ] Gemini AFC 경고 정리
현재 정상 동작하지만 아래 경고가 발생했음:

```text
Direct use of automatic function calling (AFC) in Models.generate_content is not recommended...
```

기능에는 문제가 없으나 향후 Google 권장 API 방식으로 migration 검토.

---

## 5. Groq fallback

### [ ] Groq API 인증 문제 해결
현재 상태:
- Groq API key를 등록했으나 401 `Invalid API Key`
- 새 key 교체 후에도 인증 문제로 일단 보류

향후:
- Groq Console에서 project/key 상태 재확인
- `models.list()` 인증 테스트
- 인증 성공 후 Gemini fallback provider로 연결

목표:
```text
Gemini 성공
    -> 완료

Gemini quota/timeout/API 오류
    -> Groq fallback

Groq도 실패
    -> AI 없이 논문 저장
```

### [ ] Groq dependency는 인증 성공 후 정식 추가
현재 Gemini는 정식 dependency 추가 완료.
Groq는 인증 정상화 후 `pyproject.toml`에 추가.

---

## 6. OA / PDF 처리

### [ ] Semantic Scholar `openAccessPdf` 우선 사용 검증
계획:
1. Semantic Scholar `openAccessPdf`
2. 없으면 Unpaywall
3. 없으면 abstract fallback

Semantic Scholar가 다시 활성화된 뒤 실제 논문에서 `pdf_url`이 정상 채워지는지 확인 필요.

### [ ] Unpaywall HTTP 404 처리 수정
현재 상태:
- 404 응답이 traceback 예외로 처리됨
- DOI가 없는 정상 케이스인데도 불필요한 오류 로그 발생

수정 사항:
- `exc.response is not None` 조건으로 404 여부 판별
- 404는 `not_found`로 처리, 파이프라인 중단 없이 계속 진행
- traceback 없이 조용히 처리

### [ ] Unpaywall 실제 신규 논문 경로 검증
standalone 테스트는 성공했지만 실제 신규 논문 run에서 다음 로그를 아직 충분히 확인하지 못함:

```text
Unpaywall candidates: N / M new papers
Unpaywall resolved: status=... pdf=YES ...
```

신규 논문 발생 시 확인.

### [ ] PDF 다운로드 실패 유형 통계/로그 개선
현재 예외처리는 되어 있음.

향후 구분 로그 검토:
- 403
- 404
- timeout
- HTML 응답
- invalid PDF signature
- max file size 초과
- parse failure
- no extractable text

### [ ] 스캔 PDF OCR 지원 여부
현재 `pypdf` 기반 텍스트 추출.
스캔 이미지 PDF는 `No extractable text`가 될 수 있음.

현재 권장:
- OCR은 우선 미지원
- abstract fallback

필요성이 커질 경우에만 OCR 기능 추가 검토.

### [ ] PDF text 선택적 추출 개선
현재 제한:
- 최대 40 pages
- 최대 약 120,000 chars
- 최대 PDF 25 MB

향후 개선 검토:
- Abstract
- Introduction
- Method
- Results
- Conclusion

섹션을 우선적으로 추출하여 Gemini에 전달.

---

## 7. AI 상태 / retry 정책

### [ ] 실제 운영 데이터에서 `failed -> retry -> done` 경로 확인
임시 DB E2E 테스트는 성공함.

실제 운영에서 최초 Gemini/API 오류가 발생했을 때:
```text
ai_status = failed
```
저장 후 다음 주 실행에서:
```text
retry -> done
```
되는지 로그 확인.

### [ ] `skipped` 논문 재평가 정책 결정
현재:
```text
PDF 없음 + abstract 없음
-> ai_status = skipped
-> 자동 재시도 안 함
```

문제:
- 나중에 Semantic Scholar에서 abstract가 추가되거나
- Unpaywall에서 OA PDF가 생길 수 있음

향후 정책 후보:
- skipped 논문을 30일 후 1회 재조회
- metadata가 개선된 경우에만 재분석
- 계속 skipped인 논문은 영구 종료

### [ ] AI retry 횟수 제한 추가 검토
현재 `failed`는 이후 run에서 다시 시도 가능.

향후 DB 필드 추가 검토:
```text
ai_retry_count
ai_last_attempt_at
```

예:
- 최대 3회 실패 후 `permanent_failed`
- 무한 재시도 방지

---

## 8. DB schema / 데이터 관리

### [ ] AI provenance 정보 추가 검토
현재 저장:
- relevance
- categories
- summary
- ai_reason
- oa_status
- pdf_url
- ai_analysis_level
- ai_status

추가 검토:
```text
ai_provider
ai_model
ai_processed_at
ai_retry_count
```

장점:
- 어떤 모델이 만든 요약인지 추적 가능
- 모델 변경 전/후 비교 가능

### [ ] DB backup 정책
`papers.db`는 시스템의 핵심 상태 데이터.

권장:
- Synology Hyper Backup 또는 별도 주기 backup
- 최소 주 1회
- `papers.db` + config + source code 함께 backup 검토

### [ ] 오래된 테스트 데이터 확인
임시 DB는 `/tmp`에 생성했으므로 container 종료 시 영향 없음.
운영 `papers.db`에 테스트 논문이 섞여 있지 않은지 한 번 확인 권장.

---

## 9. Joplin 출력 개선

### [ ] 실제 AI 분석된 신규 논문이 Joplin에 출력되는 것 확인
render standalone 테스트는 성공.

실제 신규 논문에서 확인할 항목:
```text
AI Analysis: Full text
또는
AI Analysis: Abstract only

AI Summary
Why relevant
OA Status
OA PDF
```

### [ ] Joplin note layout 개선 검토
현재:
1. New papers 표
2. Summaries 상세 항목

향후 가능:
- relevance별 section
- category별 section
- AI Full-text 분석 논문 상단 배치
- Top 5 paper 별도 section

### [ ] 같은 날 재실행 시 note replacement 정책 확인
현재 같은 날짜 note를 교체하면서 해당 날짜 발견 논문을 누적하는 구조.

주 1회 운영에서는 큰 문제 없음.

---

## 10. Source 추가 / Google Scholar 운영

### [x] Google Scholar Alert Gmail IMAP 연동 구현
구현 완료:
- Google Scholar Alert -> Gmail -> IMAP -> ScholarGmailCollector -> paper-monitor 파이프라인
- Gmail App Password 인증 동작 확인
- Scholar UI/alert-label 필터링 추가

### [ ] Gmail IMAP 수집 최적화
현재 구현이 최근 메시지를 가져온 후 필터링.

개선 검토:
- 서버 측 `SINCE` + `FROM` 필터링으로 IMAP 트래픽 및 실행 시간 감소

### [ ] 알림 쿼리 품질 평가
- 관련 없는 MIMO/DOA/안테나 논문을 과다 생성하는 Scholar 알림 쿼리 검토
- 중요 자동차 레이더 논문을 놓치지 않는 선에서 알림 범위 축소

### [ ] Semantic Scholar 연결/접근 안정화 후 재활성화
(기존 섹션 1 참조)

### [ ] IEEE 웹사이트/API 접근 확인 후 재활성화
(기존 섹션 1 참조)

### [ ] provider circuit breaker 지속 운용
현재 circuit breaker 정상 동작 중. 계속 유지.

### [ ] Crossref 간헐적 네트워크 타임아웃 모니터링
간헐적 타임아웃 발생 여부 실행 로그에서 주기적 확인.

### [ ] IEEE 복구 후 source 우선순위 재정의
장기 목표 예:
```text
IEEE Xplore
Semantic Scholar
Crossref
Google Scholar Alert
```

각 source의 역할 중복을 보고 일부 source를 보조용으로 낮출지 검토.

---

## 11. 보안

### [ ] `.env` 권한 확인
API key, Gmail password 등이 들어있으므로 NAS에서 접근 권한 최소화.

예:
```sh
chmod 600 .env
```

단, Docker/실행 사용자가 읽을 수 있는지 확인 후 적용.

### [ ] 로그에 secret 노출 여부 재점검
특히 확인:
- IEEE API key
- Gemini API key
- Semantic Scholar API key
- Gmail App Password

로그에는 key value를 출력하지 않도록 유지.

### [ ] API key rotation 정책
키가 채팅/로그에 노출되었다면 즉시 교체.
장기적으로 필요 시 주기적 rotation 검토.

---

## 12. Docker / 유지보수

### [ ] dependency 버전 pinning 검토
현재 패키지 버전을 느슨하게 두면 향후 rebuild 시 API가 깨질 수 있음.

특히:
- `google-genai`
- `pypdf`
- `requests`
- `PyYAML`

운영 안정화 후 known-good version으로 pinning 검토.

### [ ] Docker image rebuild 정책
기억할 규칙:

```text
config.nas.yaml 변경
-> rebuild 불필요

.env 변경
-> rebuild 불필요

Python source 변경
-> rebuild 필요

pyproject.toml 변경
-> rebuild 필요
```

### [ ] 테스트 파일 유지 여부
현재 생성한 테스트 모듈:
- `test_e2e_ai.py`
- `test_retry_ai.py`

향후:
- 유지해서 regression test로 사용할지
- 별도 `tests/` 폴더로 이동할지 결정

---

# 현재 운영 권장 설정

현재 접근 제한 상황을 고려하면 당분간 다음 구성이 안전하다.

```yaml
app:
  timezone: Asia/Seoul
  lookback_days: 14
  max_papers_per_source_per_query: 20
  min_relevance: 2

sources:
  ieee:
    enabled: false

  semantic_scholar:
    enabled: false

ai:
  enabled: true
  provider: gemini
  api_key_env: GEMINI_API_KEY
  model: gemini-3.6-flash
  max_papers_per_run: 20

oa:
  enabled: true
  provider: unpaywall
  email_env: UNPAYWALL_EMAIL
```

스케줄:

```text
매주 월요일 09:00 KST
lookback: 14일
```

현재 IEEE와 Semantic Scholar가 비활성화되어 있으므로 당분간 Crossref 중심으로 수집되고, DOI가 있는 신규 논문에 대해 Unpaywall OA 검색 및 Gemini 분석이 수행된다.

---

# 우선순위 요약

## P0 - 다음 즉시 처리
- [ ] 최종 보고서 필터링 수정 (report_count에 이전 기준 논문 포함 문제)
- [ ] 최종 보고서 선택에 Gemini 관련성 적용 (관련성 1~2 논문 제외)
- [ ] Unpaywall HTTP 404 처리 수정 (traceback 대신 not_found로 처리)

## P1 - 필터링 품질
- [ ] 수회 스케줄 실행 후 Google Scholar 관련성 임계값 검토 (현재: 3, 전역: 2)
- [ ] Scholar 파서 개선 (필요 시)
- [ ] `classify_and_score()` 점수 규칙 검토 (일반 MIMO/안테나/통신 전용 논문 처리)

## P1 - AI
- [ ] Gemini 429 RetryInfo/backoff 명시적 처리 (13초 간격이 주 보호, 방어 처리 추가)
- [ ] Gemini AFC 경고 정리 (현재 동작에 문제 없음, 낮은 우선순위)
- [ ] Gemini -> Groq fallback (인증 문제 미해결, 파이프라인 차단하지 않음)

## P1 - 소스
- [ ] Semantic Scholar 연결/접근 안정화 후 재활성화
- [ ] IEEE 웹사이트/API 접근 확인 후 재활성화
- [ ] provider circuit breaker 지속 운용
- [ ] Crossref 간헐적 네트워크 타임아웃 모니터링

## P2 - Google Scholar
- [ ] Gmail IMAP 수집 최적화 (서버 측 SINCE + FROM 필터링 검토)
- [ ] 알림 쿼리 품질 평가 (관련 없는 MIMO/DOA/안테나 논문 과다 생성 쿼리 검토)

## P2 - 데이터베이스 / 보고서
- [ ] 수집 관련성과 최종 AI 관련성을 DB에서 명확히 분리
- [ ] 관련성 점수 출처 저장/보고 (rule-based / Gemini abstract / Gemini full-text)
- [ ] `ai_status=skipped` 처리 정책 결정
- [ ] 기준 변경 시 같은 날 기존 논문을 재생성 보고서에서 제거할지 결정
- [ ] DB backup/보존 정책 추가
- [ ] scheduler.log 로그 로테이션 추가

## P3 - 운영
- [ ] Docker Hub / Crossref / IEEE / Semantic Scholar 연결 문제 모니터링
- [ ] 파이프라인 안정화 후 주요 Python dependency 버전 고정
- [ ] query/source 최적화
- [ ] Joplin 보고서 레이아웃 개선

---

# 완료 항목 (2026-08-15 기준)

## 스케줄러 / 운영
- [x] DSM Task Scheduler 최종 등록 확인
- [x] DSM 월요일 09:00 scheduler 최종 등록/활성화
- [x] DSM에서 등록한 작업 수동 1회 실행 및 `RESULT=0` 확인
- [x] Joplin import / WebDAV sync 정상 동작 확인
- [x] Scheduler 로그를 실행별 개별 파일로 생성하도록 적용

적용 로그 파일명 형식:
```text
scheduler-YYYY-MM-DD_HH-MM-SS.log
```

## Gemini 운영값
- [x] `max_papers_per_run` 운영값 확정: `20`

## Google Scholar Alert 연동 (2026-08-21)
- [x] Google Scholar Alert Gmail IMAP 연동 구현
- [x] Gmail App Password 인증 동작 확인
- [x] Scholar UI/alert-label 필터링 추가

## Gemini AI 개선 (2026-08-21)
- [x] Gemini 13초 요청 간격 추가 (무료 5 RPM 한도 보호)
- [x] Gemini 무료 5 RPM 한도에서 429 오류 없음 확인
- [x] 이전 실패(`ai_status=failed`) Gemini 논문 재시도 구현