feat: data_gaps 피드백 루프 — capabilities 짝꿍 엔드포인트 #72

Merged

xhh merged 1 commit from issue-15-data-gaps into main

2026-04-26 21:41:31 +09:00

xhh commented

2026-04-26 21:40:04 +09:00

Owner

요약

스킬 → 서버 피드백 루프(#15) 구현. capabilities(#62) 가 광고한 짝꿍 엔드포인트.
스킬이 본 플랫폼에서 못 찾은 데이터를 append-only 로 누적 기록하고, 주기적 리뷰로
다음 수집기 우선순위(#9, #10, #12 등) 결정에 환원한다.

엔드포인트

메서드	경로	인증	용도
GET	`/api/meta/data-gaps`	공개	갭 목록 (filter: resolved/category/requester/since)
GET	`/api/meta/data-gaps/summary`	공개	topic 별 집계 (주간 리뷰용)
GET	`/api/meta/data-gaps/{id}`	공개	단건 상세
POST	`/api/meta/data-gaps`	write	갭 기록 (스킬 호출)
PATCH	`/api/meta/data-gaps/{id}`	write	resolved 토글 + 메모

변경 파일

src/financial_platform/storage/models.py — DataGap 모델 (append-only, topic 인덱스)
src/financial_platform/api/schemas/data_gaps.py — Pydantic v2 스키마 4종
src/financial_platform/api/routers/data_gaps.py — 5개 엔드포인트
src/financial_platform/api/main.py — 라우터 등록
src/financial_platform/api/routers/system.py
- TRACKED_TABLES 에 data_gaps 추가 (헬스체크)
- capabilities 마크다운 안내: "#15 미구현 시 무시" → 실제 사용법 (topic 필수, /summary 안내)
tests/api/test_data_gaps.py — 19 case (post_then_get / 누적 / 필터 / 요약 / 인증)
README.md / CLAUDE.md — 12개 테이블, Phase 2 항목 체크

설계 결정

append-only: 같은 topic 이 여러 번 들어와도 별도 row. 누적 횟수는 /summary
의 group by 로 산출. 정규화로 정확도 손실 없음 — 분석 시 시간 분포까지 보존.
조회는 공개, 기록/해결은 write 스코프: 다른 라우터와 일관. 공개 인터넷에서는
쓰기 차단되지만 내용 자체는 노출 — 갭은 운영 메타데이터지 비밀이 아님.
resolved 토글 동작: PATCH 단일 엔드포인트. False→True 시 resolved_at 자동
기록, 되돌리면 None 으로 초기화 — 감사 시 직관적.

검증

uv run ruff check . 통과
uv run pytest 141 case 통과 (122 + 19)
post_then_get 회귀 테스트 1순위 배치 — deps.get_session commit 회귀 즉시 감지
auth_enabled_client 로 401 / 200 경계 검증

이슈

Closes #15

## 요약 스킬 → 서버 피드백 루프(#15) 구현. capabilities(#62) 가 광고한 짝꿍 엔드포인트. 스킬이 본 플랫폼에서 못 찾은 데이터를 append-only 로 누적 기록하고, 주기적 리뷰로 다음 수집기 우선순위(#9, #10, #12 등) 결정에 환원한다. ## 엔드포인트 | 메서드 | 경로 | 인증 | 용도 | |---|---|---|---| | GET | `/api/meta/data-gaps` | 공개 | 갭 목록 (filter: resolved/category/requester/since) | | GET | `/api/meta/data-gaps/summary` | 공개 | topic 별 집계 (주간 리뷰용) | | GET | `/api/meta/data-gaps/{id}` | 공개 | 단건 상세 | | POST | `/api/meta/data-gaps` | write | 갭 기록 (스킬 호출) | | PATCH | `/api/meta/data-gaps/{id}` | write | resolved 토글 + 메모 | ## 변경 파일 - `src/financial_platform/storage/models.py` — `DataGap` 모델 (append-only, topic 인덱스) - `src/financial_platform/api/schemas/data_gaps.py` — Pydantic v2 스키마 4종 - `src/financial_platform/api/routers/data_gaps.py` — 5개 엔드포인트 - `src/financial_platform/api/main.py` — 라우터 등록 - `src/financial_platform/api/routers/system.py` - `TRACKED_TABLES` 에 `data_gaps` 추가 (헬스체크) - capabilities 마크다운 안내: "#15 미구현 시 무시" → 실제 사용법 (topic 필수, /summary 안내) - `tests/api/test_data_gaps.py` — 19 case (post_then_get / 누적 / 필터 / 요약 / 인증) - `README.md` / `CLAUDE.md` — 12개 테이블, Phase 2 항목 체크 ## 설계 결정 - **append-only**: 같은 topic 이 여러 번 들어와도 별도 row. 누적 횟수는 `/summary` 의 group by 로 산출. 정규화로 정확도 손실 없음 — 분석 시 시간 분포까지 보존. - **조회는 공개, 기록/해결은 write 스코프**: 다른 라우터와 일관. 공개 인터넷에서는 쓰기 차단되지만 내용 자체는 노출 — 갭은 운영 메타데이터지 비밀이 아님. - **resolved 토글 동작**: PATCH 단일 엔드포인트. False→True 시 `resolved_at` 자동 기록, 되돌리면 `None` 으로 초기화 — 감사 시 직관적. ## 검증 - `uv run ruff check .` 통과 - `uv run pytest` **141 case 통과** (122 + 19) - post_then_get 회귀 테스트 1순위 배치 — `deps.get_session` commit 회귀 즉시 감지 - auth_enabled_client 로 401 / 200 경계 검증 ## 이슈 Closes #15

xhh added 1 commit

2026-04-26 21:40:04 +09:00

feat: data_gaps 피드백 루프 — capabilities 짝꿍 엔드포인트 (#15 )

Tests (PR) / pytest (pull_request) Successful in 30s

Details

543d81b862

스킬이 본 플랫폼에서 못 찾은 데이터를 서버에 누적 기록 → 주기적
리뷰로 다음 수집기 우선순위에 환원하는 피드백 루프 구현. capabilities
(#62) 가 광고하는 진입점의 반대 방향.

추가:
- DataGap 모델 (storage/models.py): append-only, topic 인덱스
- 라우터 routers/data_gaps.py
  - GET    /api/meta/data-gaps          공개, 필터(resolved/category/requester/since)
  - GET    /api/meta/data-gaps/summary  공개, topic 별 집계 (주간 리뷰용)
  - GET    /api/meta/data-gaps/{id}     공개
  - POST   /api/meta/data-gaps          write 스코프
  - PATCH  /api/meta/data-gaps/{id}     write 스코프, resolved 토글 시 resolved_at 자동
- Pydantic 스키마 schemas/data_gaps.py
- system.py
  - TRACKED_TABLES 에 data_gaps 추가
  - capabilities 마크다운의 "미구현 시 무시" 문구 → 실제 사용법 안내로 교체
- main.py: 라우터 등록
- 테스트 19 case (post_then_get + 누적/필터/요약/인증)
- README / CLAUDE.md: 12개 테이블, Phase 2 진행 항목 체크

설계 결정:
- append-only — 같은 topic 이 여러 번 들어와도 별도 row. 누적 횟수는
  /summary 의 group by 로 산출. 정규화로 정확도 손실 없음.
- 조회는 공개, 기록/해결은 write 스코프 — 다른 라우터와 일관.
- resolved 토글은 PATCH 단일 엔드포인트. False→True 시 resolved_at 자동
  기록, 되돌리면 None 으로 초기화.

Closes #15