docs(proofline): capture portfolio ledger discovery

2026-08-20 12:36:24 +09:00
parent ac742b1150
commit f48a7c5cd7
12 changed files with 367 additions and 2 deletions
@@ -0,0 +1,36 @@
+<!-- Source URL: https://github.com/fourblocks2020/portfolio-hub/issues/29#issuecomment-5349683566
+Source author: genichin
+Source created_at: 2026-08-20T00:30:07Z
+Body SHA-256: e90881b5df47b17650169c0858e7f39c300682ab70d3a88032b6fe41d31f65c7
+Snapshot: exact source body begins after this header.
+-->
+
+## 구현 진행 상황
+
+- **대상:** [portfolio-hub] discovery: 포트폴리오 전체 원장 조회 API (#29)
+- **브랜치:** `main`
+- **기준:** `main` (`fe22be0b6686f346f4e6a5c9b64f7b3469e75810`)
+- **상태:** 로컬 main 구현·검증·커밋 완료 — 미푸시, 미배포, 미릴리스
+- **최종 업데이트:** 2026-08-20T11:05:00+09:00 (KST)
+
+### 구현 계획 및 작업 목록
+
+- [x] 통합 원장 조회 API의 응답·입력 계약을 추가했다.
+  - 모든 출처를 하나의 대문자 `action` 모델로 표현하고, 출처별로 없는 사실은 `null`로 명시한다.
+- [x] source 필터와 cursor 기반 페이지 조회를 구현했다.
+  - cursor는 portfolio·source 조건과 정렬 기준에 결속하며, 잘못되거나 다른 조건의 cursor는 HTTP 422로 거부한다.
+- [x] 소유자 권한과 기존 manual 전용 조회의 하위호환성을 검증했다.
+  - user/session owner만 허용하고 기존 `/ledger/manual` 계약을 변경하지 않았다.
+- [x] API/OpenAPI 문서와 단위·통합 회귀 검증을 추가·실행했다.
+  - manual·broker 혼합, source filter, 권한 경계와 cursor 오류를 검증했다.
+- [x] 실제 PostgreSQL query plan 및 index/migration을 검증했다.
+  - disposable PostgreSQL DB에서 `20260820_0030` migration head와 `idx_portfolio_ledger_portfolio_recorded_entry_desc` 생성을 확인했다.
+
+### 진행 기록
+
+- 2026-08-20T09:29:48+09:00 (KST): 승인된 Discovery(OQ-001~007)와 현재 `main` 기준 SHA를 확인했다. 별도 구현 worktree는 만들지 않고 `main`에서 구현·검증을 시작한다.
+- 2026-08-20T10:40:54+09:00 (KST): source-중립 `GET /v1/portfolios/{portfolio_id}/ledger` vertical slice를 추가했다. focused `tests/test_v1_portfolios_manual_ledger.py`는 `14 passed`였다.
+- 2026-08-20T10:55:00+09:00 (KST): disposable PostgreSQL fresh upgrade에서 migration head와 unified-ledger keyset index 생성을 확인했다.
+- 2026-08-20T11:05:00+09:00 (KST): 권한/source/OpenAPI/release-contract 회귀를 보완했다. 전체 회귀 `664 passed, 16 skipped`, 변경 범위 lint와 `git diff --check`를 통과했고, 로컬 `main`에 `ac742b1`로 커밋했다. `temp/`는 후보 source가 아니므로 auth-surface 정적 검사의 재귀 대상에서 제외했다.
+
+> 각 작업이 실제로 완료되고 검증될 때마다 이 댓글의 체크박스와 진행 기록을 갱신한다. 체크 표시는 구현 완료 또는 해당 검증의 실제 통과를 의미하며, 배포·릴리스 완료를 의미하지 않는다.