Claude 보고서/개선점

신규 기능이 아니라, **이미 있는 구현에서 다듬을 부분**을 정리합니다. 상위 문서: [[Claude 보고서]].

## 우선순위별 개선 항목

### 검색 랭킹 한계
주의: 영향: 중 · 난이도: 중
D1 FTS5 trigram + 짧은 질의 LIKE fallback 은 동작은 하지만 **관련도 랭킹(BM25 튜닝)·패싯·동의어가 약함**. Workers AI 임베딩 + Vectorize 하이브리드(키워드+시맨틱)로 보강 권장. → [[Claude 보고서/외부 서비스 연동]]


### 알림의 읽음/보관 모델 부재
인앱 알림은 명시적 read 마커 없이 **링크 진입 시 자동 삭제**로 처리됩니다. 읽음/안읽음·보관·전체 히스토리 모델로 전환하면 사용자가 지난 알림을 다시 찾을 수 있습니다.

### 접근성(A11y)
- 콜아웃 배경 틴트가 라이트 8–10%로 낮아 대비가 부족할 수 있음 → 토큰화하고 대비 검증.
- 다수 애니메이션(page enter, SPA 진행바, fold)에 대한 `prefers-reduced-motion` 분기 명문화 필요.
- 탭·아코디언·스텝의 ARIA 상태(`aria-current` 등) 전수 점검.
- diff 의 green/red는 `+`/`-` 마커가 있어 양호하나 색맹 사용자용 패턴 보강 고려.

### 국제화 부채
UI 문자열이 한국어로 하드코딩되어 있어 **화이트라벨/다국어 운영이 불가**. 문자열 외부화(메시지 카탈로그)를 선제적으로 도입할수록 비용이 낮습니다.

### 인증 다양성
OAuth 공급자가 Google·Discord 둘뿐입니다. **범용 OIDC 공급자**를 추가하면 기업/조직 도입(SSO)이 쉬워집니다.

### 미디어 처리
업로드 이미지는 `{size:...}` CSS 힌트만 있고 **서버사이드 리사이즈/포맷 변환이 없음**. Cloudflare Images 로 반응형·AVIF/WebP 변형을 생성하면 성능·대역폭이 개선됩니다.

### 문서 이동 시 리다이렉트
`move_page`(관리자 MCP) 존재. 이동/이름변경 시 **구 슬러그 → 신 슬러그 리다이렉트 자동 생성**과 사용자용 이름변경 UI 가 있으면 링크 깨짐을 막습니다. (현재 동작이 그렇지 않다면 추가 권장.)

### 캐시 무효화 복잡도
백링크/페이지 캐시 무효화가 `:` 인코딩 변형(`%3A`·raw)을 직접 다뤄 **취약**합니다. 테스트로 고정하고 캐시 키 정규화를 한 곳으로 모으는 리팩터링 권장.

### 스팸·남용 방어
편집/토론/티켓에 대한 **레이트 리미팅과 익명 편집 보류**가 약합니다. Turnstile 확대 적용(가입·티켓·토론)과 API/MCP 레이트 리미트를 권장.

### 관측성(Observability)
Analytics Engine 은 페이지뷰/검색/에러를 기록하나, **구조화된 에러 추적/경보**가 약합니다. Logpush/Tail Worker 또는 외부 에러 모니터링 연계 권장.

### 운영 거버넌스
슈퍼 관리자가 환경변수 이메일(`SUPER_ADMIN_EMAILS`)로 고정됩니다. DB 관리형 + 감사 로그(이미 `admin_log` 존재)와 결합하면 운영 유연성이 좋아집니다.

### 테마 모듈화
라이트/다크가 빌드 타임에 고정되어 **멀티 테마 확장이 어렵습니다**. 별도 문서 참조: [[Claude 보고서/모듈형 테마 시스템]], [[Claude 보고서/디자인 개선과 테마 아이디어]].

## 요약표

| 영역 | 우선순위 | 핵심 조치 |
| --- | :---: | --- |
| 검색 랭킹 |  높음 | Vectorize 하이브리드 |
| 알림 모델 |  중 | 읽음/보관 도입 |
| 접근성 |  중 | reduced-motion·대비·ARIA |
| i18n |  중 | 문자열 외부화 |
| 미디어 변환 |  중 | Cloudflare Images |
| 스팸 방어 |  중 | Turnstile 확대·레이트리밋 |
| 관측성 |  낮음 | Logpush/Tail |