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

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

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

---

## 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 차단 가능성 감소

---

## 4. Gemini AI 운영 설정

### [ ] 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 실제 신규 논문 경로 검증
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 Alert 연동
아직 보류 중.

계획:
```text
Google Scholar Alert
-> Gmail
-> IMAP
-> ScholarGmailCollector
-> paper-monitor
```

웹 scraping 대신 Google Scholar Alert 메일을 사용하는 방식 권장.

필요:
- Google Scholar Alert 생성
- Gmail App Password
- NAS `.env`
- Gmail collector 활성화
- sender/subject filter 테스트

### [ ] 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 - 운영 전에 확인
- [ ] Semantic Scholar `enabled: false`
- [ ] IEEE `enabled: false`
- [ ] `.env` secret 권한 및 IEEE key rotation 여부 확인

## P1 - 접근 복구 후
- [ ] Semantic Scholar 재활성화 + 429 상태 확인
- [ ] IEEE 웹사이트 403 해제 확인
- [ ] IEEE API 승인 상태 확인
- [ ] IEEE 1-query 테스트 후 재활성화

## P2 - 기능 보강
- [ ] Google Scholar Alert + Gmail collector
- [ ] Groq 인증 해결 + Gemini fallback
- [ ] `skipped` 재평가 정책
- [ ] AI retry count / provider / model / processed_at DB 저장
- [ ] PDF section-aware extraction

## P3 - 장기 운영
- [ ] DB backup
- [ ] scheduler timestamp 로그 보관기간/정리 정책(예: 8주)
- [ ] dependency version pinning
- [ ] query/source 최적화
- [ ] Joplin report layout 개선

---

# 완료 항목 (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`