DocuStory
한국 부동산 관련 PDF 문서를 위험 신호로 정리해주는 분석 엔진.
- Python
- FastAPI
- Real Estate
Setup
- Context
위험 판단을 "룰"로 분리해서, 같은 문서에 대해 같은 점수가 나오도록 만드는 실험.
Build
- QA considerations
- 같은 문서에 늘 같은 점수 - now를
FIXED_NOW로 고정 주입해 골든 결과와 완전히 일치하는가 - 룰 카탈로그가 실제 등기부의 위험 신호(근저당·압류·가압류)를 놓치지 않고 커버하는가
- 놓친 위험(false-negative) vs 과탐지(false-positive)의 비용을 어느 쪽으로 기울일지 결정했는가
- 말소 탐지(가로선 + 텍스트 단서)와 채권최고액·날짜 정규화가 다양한 PDF 레이아웃에서 견고한가
- 텍스트 레이어 없는 스캔본은 OCR 미구현으로 명시 거부(
PARSER_OCR_NOT_IMPLEMENTED)하고, 검증 못 한 한계는 PARSER_*·ANALYZER_* warning으로 표면화해 조용히 틀린 답을 내지 않는가 - 6개 레포에 걸친 계약 스키마(ParsedDocument·Rule·AnalysisResult 등)를 각 레포
test_contract·platformtest_openapi로 메타검증해 계약과 구현이 어긋나지 않는가 - 룰 카탈로그 무결성·패키징·정렬 결정성 테스트로 가중 점수(warning 15·danger 40, cap 100) 집계가 실행 순서와 무관하게 재현되는가
- 같은 문서에 늘 같은 점수 - now를
Outcome
- Metrics
현재 외부 검증 중. 아키텍처·룰 카탈로그·구현 세부는 검증이 마무리된 뒤 공개할 예정.
진행 과정 (기획 → 개발)
문제·가설에서 스코프·스펙(SSOT)·개발·QA 게이트·배포까지, 같은 틀로 이 앱을 어떻게 기획하고 끌고 갔는지.
진행 과정 (기획 → 개발)
문제 · 가설
한국 부동산 등기부등본 PDF에는 근저당·압류·가압류 같은 위험 신호가 들어 있지만 일반인은 이를 일관되게 읽어내기 어렵다. 핵심 가설은 '위험 판단을 선언적 룰로 분리하면 회귀 테스트가 가능해진다' - 같은 문서는 늘 같은 점수를 내야 한다는 것이다.
역량 · 문제 정의 · 가설
스코프 · 우선순위
킥오프에서 범위를 '등기부 PDF 1장 → 갑구·을구 추출 → 근저당·압류 탐지 → 한국어 한 줄 요약'의 가장 얇은 e2e 슬라이스로 못박았다(`_roundtable/brief.md`, 각 레포 CLAUDE.md가 안건으로 참조하는 문서). 등기부만·텍스트 레이어 우선을 코어로 두고, OCR(파서가 `PARSER_OCR_NOT_IMPLEMENTED`로 명시 거부)·인증·재무제표/계약서 문서타입·실제 클라우드 배포는 후속으로 미뤘다.
역량 · 스코핑 · 우선순위
스펙 우선 (SSOT)
SSOT는 R2에서 동결한 계약 문서(`_roundtable/output/00-r2-decisions.md`)와 레포별 `contracts/*.schema.json`(ParsedDocument·Rule·RuleEvalResult·AnalysisResult·SampleManifest)이었고, 각 계약은 정확히 한 레포가 소유한다. 이후 빌드는 레포별 `NEXT_BUILD.md`를 다음 슬라이스 계획으로 삼아 슬라이스 단위로 쌓았고, 스키마 변경은 backward-compat 확장만 허용해 여러 슬라이스를 거치는 동안 `schema_version`을 0.1.0으로 유지했다.
역량 · 스펙 · 문서화
개발 · 이터레이션
6개 레포로 역할을 나눠(samples → parser/rules → analyzer → platform → infra) in-process import로 직렬 호출했다. parser는 pdfplumber 텍스트 추출 + 갑구·을구 셀 매핑 + 말소 탐지(시각적 가로선 + 텍스트 단서) + 채권최고액·날짜 정규화, rules는 선언적 JSON 카탈로그 7룰 + 결정론적 평가기, analyzer는 risk_level·가중 점수(warning 15·danger 40, cap 100)·한국어 요약, platform은 FastAPI POST/GET + CLI + SQLite 영속화를 담당한다.
역량 · 실행 · 전달
검증 (QA 게이트)
QA 렌즈가 검증을 끌고 갔다. analyzer 골든 테스트는 `now`를 FIXED_NOW(2026-06-05T12:00Z)로 고정 주입해 같은 입력이 저장된 골든과 완전히 동일한 AnalysisResult를 내는지 단언하며 '같은 문서 같은 점수' 가설을 직접 게이트하고, platform e2e는 실제 parser·rules·analyzer + 실제 샘플 PDF로 risk_level·룰 ID·score·요약 문구를 정확히 단언한다(예: danger_003은 기여합 190 → cap 100, 6 findings). 그 아래에 전 레포의 계약 스키마 메타검증(각 `test_contract`·platform `test_openapi`·infra manifest 스키마)과 룰 카탈로그 무결성·패키징·정렬 결정성 테스트를 깔고, 검증 못 한 한계는 `PARSER_*`/`ANALYZER_*` warning으로 정직하게 노출한다.
역량 · 품질 · 리스크
배포
dev compose와 prod compose(멀티스테이지·비-root 유저·healthcheck·named volume Docker)로 기동되고, 외부 표면은 `POST /v1/documents:analyze` + `GET /v1/documents/{document_id}` + CLI(단건·batch)이며 저장은 기본 SQLite다. 아직 MVP 단계라 샘플이 합성 PDF(`gen_synthetic_pdf.py`)여서 실제 등기부에 대한 정확도가 남은 관문이고, 인증·외부 DB·CI/CD·클라우드 배포 청사진은 후속 안건이다.
역량 · 릴리스
- Tech stack
- Python
- FastAPI