chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

2026-06-30 16:06:47 +09:00
parent 67d8d4871b
commit 4929e52189
75 changed files with 8367 additions and 252 deletions
@@ -0,0 +1,62 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18501",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835",
+  "fixture": {
+    "account_id": "acct_a4f4de4cdd0f",
+    "transaction_ids": [
+      "tx_cba36b3d2c33",
+      "tx_24fa1050eb2b",
+      "tx_8cd3af3d60b6"
+    ],
+    "db_path": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "분류 규칙",
+      "url": "http://127.0.0.1:18501/?page=%EB%B6%84%EB%A5%98%20%EA%B7%9C%EC%B9%99",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/rules.png",
+      "screenshot_bytes": 364876,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/rules.dom.html",
+      "snapshot_bytes": 174470,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\nStop\nDeploy\n⚙️ Rule Engine\n분류 규칙\n\n반복되는 사용처와 거래 패턴을 규칙으로 관리해 분류 자동화 품질을 높입니다.\n\n자동 분류\nPreview\nSeed/Update\nkeyboard_arrow_right\n\n🟢 이자 · merchant/contains → 수입 / 이자 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 환급 · merchant/contains → 수입 / 환급 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 급여 · merchant/contains → 수입 / 급여 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 KB카드출금 · merchant/contains → 금융 / 카드대금 · p20 · expense\n\nkeyboard_arro"
+    },
+    {
+      "page": "확인필요 큐",
+      "url": "http://127.0.0.1:18501/?page=%ED%99%95%EC%9D%B8%ED%95%84%EC%9A%94%20%ED%81%90",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/transfer-review.png",
+      "screenshot_bytes": 275792,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/transfer-review.dom.html",
+      "snapshot_bytes": 25551,
+      "devtools_port": 19223,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\nStop\nDeploy\n🔁 Transfer Review\nKB↔토스뱅크 확인필요 큐\n\n날짜·금액·상대 기준으로 계좌 간 이동 후보를 대조하고, 드라이런 후 안전하게 매칭합니다.\n\n드라이런 우선\n본인계좌이동\n수동 검토\n📌\n확인필요 큐\n\n거래 ID: tx_8cd3af3d60b6\n\n2026-06-29 · SYNTHETIC_TRANSFER · 120,000원"
+    },
+    {
+      "page": "Import",
+      "url": "http://127.0.0.1:18501/?page=Import",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/import.png",
+      "screenshot_bytes": 297424,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/import.dom.html",
+      "snapshot_bytes": 23649,
+      "devtools_port": 19224,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\nStop\nDeploy\n\n토스증권 거래내역서 PDF를 업로드하면 투자계좌 거래로 가져옵니다. 매수/매도/환전/입출금은 이체/투자이동, 배당/이자는 실제 수입으로 분류합니다.\n\n토스뱅크 계좌 거래내역 PDF를 업로드하면 입출금/이체/카드결제를 가져옵니다. 타인 이체/출금은 이체/확인필요로 분류됩니다."
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18501",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,62 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18501",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632",
+  "fixture": {
+    "account_id": "acct_7579e5091359",
+    "transaction_ids": [
+      "tx_22a85feba578",
+      "tx_04e500d0745c",
+      "tx_3ee6a6e14179"
+    ],
+    "db_path": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "분류 규칙",
+      "url": "http://127.0.0.1:18501/?page=%EB%B6%84%EB%A5%98%20%EA%B7%9C%EC%B9%99",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/rules.png",
+      "screenshot_bytes": 364622,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/rules.dom.html",
+      "snapshot_bytes": 190599,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\nStop\nDeploy\n⚙️ Rule Engine\n분류 규칙\n\n반복되는 사용처와 거래 패턴을 규칙으로 관리해 분류 자동화 품질을 높입니다.\n\n자동 분류\nPreview\nSeed/Update\n📚\n현재 분류 규칙\nkeyboard_arrow_right\n\n🟢 급여 · merchant/contains → 수입 / 급여 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 이자 · merchant/contains → 수입 / 이자 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 환급 · merchant/contains → 수입 / 환급 · p10 · income\n\nkeyboard_arrow_right\n\n🟢 KB카드출금 · merchant/contains → 금융 / 카드대금 · p20 · expense\n\nke"
+    },
+    {
+      "page": "확인필요 큐",
+      "url": "http://127.0.0.1:18501/?page=%ED%99%95%EC%9D%B8%ED%95%84%EC%9A%94%20%ED%81%90",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/transfer-review.png",
+      "screenshot_bytes": 282069,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/transfer-review.dom.html",
+      "snapshot_bytes": 27701,
+      "devtools_port": 19223,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\n\n새로고침\n\nStop\nDeploy\n🔁 Transfer Review\nKB↔토스뱅크 확인필요 큐\n\n날짜·금액·상대 기준으로 계좌 간 이동 후보를 대조하고, 드라이런 후 안전하게 매칭합니다.\n\n드라이런 우선\n본인계좌이동\n수동 검토\n\n미리보기(드라이런)\n\n자동 매칭 실행\n\n📌\n확인필요 큐\n\n거래 ID: tx_3ee6a6e14179\n\n2026-06-29 · SYNTHETIC_TRANSFER · 120,000원"
+    },
+    {
+      "page": "Import",
+      "url": "http://127.0.0.1:18501/?page=Import",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/import.png",
+      "screenshot_bytes": 298123,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-195632/import.dom.html",
+      "snapshot_bytes": 15721,
+      "devtools_port": 19224,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\nStop\nDeploy\n\n토스증권 거래내역서 PDF를 업로드하면 투자계좌 거래로 가져옵니다. 매수/매도/환전/입출금은 이체/투자이동, 배당/이자는 실제 수입으로 분류합니다.\n\n토스뱅크 계좌 거래내역 PDF를 업로드하면 입출금/이체/카드결제를 가져옵니다. 타인 이체/출금은 이체/확인필요로 분류됩니다."
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18501",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,44 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18501",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260630-071603",
+  "fixture": {
+    "account_id": "acct_75c4cbc5a305",
+    "transaction_ids": [
+      "tx_2123d9b9c1f5",
+      "tx_a13db72f4885",
+      "tx_3edaa32c38ae",
+      "tx_fe176567300b",
+      "tx_d674d4ddbf1e"
+    ],
+    "db_path": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260630-071603/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "요약",
+      "url": "http://127.0.0.1:18501/?page=%EC%9A%94%EC%95%BD",
+      "screenshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260630-071603/overview.png",
+      "screenshot_bytes": 300562,
+      "snapshot": "docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260630-071603/overview.dom.html",
+      "snapshot_bytes": 33871,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\n\n새로고침\n\nStop\nDeploy\n📊 요약\n가계부 운영 대시보드\n\n이번 달 실제 현금흐름, 자산 유동성, 운영 경고를 우선순위대로 확인합니다.\n\nschema v8\nKST 이번 달\nlast_balance 기준 자산\n\nDB: /root/projects/jarca-ledger-mcp/docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260630-071603/fixture.sqlite3\n\n💎\n이번 달 수입/지출 현황\n\n기준: KST 현재 월 2026-06, transactions.transaction_date, ledger_categories.cashflow_kind 실제 현금흐름\n\n🏦\n자산 유동성 현황\n\n기준: accounts.liquidity_bucket"
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18501",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,33 @@
+# BAT-004 Implementation
+
+## 코드 변경
+
+- `scripts/streamlit_browser_evidence.py`
+  - synthetic fixture DB 생성.
+  - 운영 DB 기본 경로 사용 거부 안전장치.
+  - Streamlit local server 기동 및 HTTP 200 readiness 확인.
+  - `/usr/bin/google-chrome-stable` headless Chrome DevTools Protocol 연결.
+  - page별 DOM 텍스트 로드 확인 후 PNG screenshot 및 DOM snapshot 저장.
+  - manifest JSON에 evidence path/byte size/fixture DB/command 정보를 기록.
+- `dashboard/app.py`
+  - Import page의 import batch 조회와 rollback 실행이 현재 dashboard `db_path`를 사용하도록 수정.
+  - 이 수정은 browser evidence fixture DB 원칙을 지키기 위한 안전 보완이며 운영 DB 누수를 막는다.
+
+## 문서 변경
+
+- `docs/srs/Testing/req-004_browser-streamlit-e2e-evidence-recovery.md`
+- `docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/`
+- `docs/runbooks/streamlit-browser-evidence.md`
+- `docs/runtime-flows.md`
+- `docs/interface-contract.md`
+- `docs/project-structure.md`
+- `docs/srs/index.md`
+- `docs/batches/index.md`
+- source Discovery의 생성된 REQ 참조
+
+## 운영 안전
+
+- evidence script는 `~/.local/share/jarca/ledger.sqlite3`를 fixture DB로 사용하는 것을 거부한다.
+- fixture에는 `SYNTHETIC_*` 가짜 계좌/거래/상대명만 사용한다.
+- 원본 금융 파일, 실제 계좌번호, 비밀번호, raw_payload는 screenshot/log/docs에 남기지 않는다.
+- CI 통합은 이번 batch 범위가 아니며, 로컬 재현 절차만 제공한다.
@@ -0,0 +1,24 @@
+# BAT-004 Browser/Streamlit E2E evidence 환경 복구
+
+- Profile: batch-lite
+- Status: release-candidate
+- Included REQ: REQ-004
+- Discovery: dcy-004
+- Owner: 렛저장인
+- Date (KST): 2026-06-29
+
+## 목표
+
+Streamlit UI batch 검증에서 AppTest/HTTP 200 대체 증거에 머물지 않도록, synthetic DB와 `/usr/bin/google-chrome-stable` 기반 로컬 browser screenshot/snapshot evidence 절차를 복구한다.
+
+## 산출물
+
+- `scripts/streamlit_browser_evidence.py` 로컬 evidence 수집 스크립트
+- `docs/runbooks/streamlit-browser-evidence.md` 운영 runbook
+- REQ-004 및 BAT-004 planning/implementation/verification 문서
+- runtime/interface/project-structure 문서의 evidence gate 기준 갱신
+- synthetic DB 기반 browser screenshot/snapshot evidence
+
+## 범위 제한
+
+CI 통합, Playwright/Selenium 도입, pixel-diff visual regression, Streamlit 신규 화면 기능 개발은 포함하지 않는다.
@@ -0,0 +1,31 @@
+# BAT-004 Planning
+
+## 구현 전략
+
+1. `REQ-004`를 Testing 요구사항으로 정리한다.
+2. 운영 DB와 실제 금융 파일을 배제한 synthetic fixture DB를 evidence script가 직접 생성한다.
+3. Streamlit은 `JARCA_LEDGER_DB_PATH=<fixture.sqlite3>`로 기동한다.
+4. `/usr/bin/google-chrome-stable` headless + Chrome DevTools Protocol로 대상 페이지를 열고, 화면 텍스트 로드 완료를 확인한 뒤 screenshot과 DOM snapshot을 저장한다.
+5. UI/dashboard 영향 batch의 QC gate 기준을 문서화한다.
+
+## Design Gate
+
+- Profile: `batch-lite`
+- 판단 근거: 신규 도메인 기능이나 DB schema 변경 없이 검증 스크립트와 문서 기준을 추가한다.
+- 설계 문서 별도 작성 여부: 별도 `design.md`는 만들지 않는다. 구현 결정은 이 planning 및 REQ-004에 충분히 국소적으로 기록한다.
+
+## Evidence Gate 기준
+
+| Batch 유형 | 최소 evidence | Gate 판정 |
+| --- | --- | --- |
+| Streamlit UI 또는 `dashboard/app.py` 영향 | Browser screenshot + DOM snapshot + manifest | 누락 시 BLOCK 또는 재검증 |
+| 비-UI service/MCP/parser 변경 | pytest/py_compile 중심, browser evidence 선택 | browser 누락은 비차단 |
+| docs-only 변경 | 문서 diff/review | browser evidence 불필요 |
+| Chrome 환경 장애가 입증된 UI 변경 | AppTest + HTTP 200 + 실패 원인 로그 | `PASS_WITH_NOTES`만 허용 |
+
+## 리스크와 완화
+
+- Chrome/DevTools 기동 실패: 실행 전 Chrome 경로를 검증하고 명확한 오류를 출력한다.
+- Streamlit 렌더링 지연: HTTP 200 대기 후 CDP에서 page 제목 텍스트가 실제 DOM에 나타날 때까지 대기한다.
+- 민감정보 노출: script가 기본 운영 DB 경로를 거부하고 synthetic fixture만 생성한다.
+- dependency 증가: Playwright/Selenium을 추가하지 않고 현재 dashboard extra에 이미 존재하는 `websockets`를 사용한다.
@@ -0,0 +1,43 @@
+# BAT-004 Verification
+
+## 검증 계획
+
+1. Python 문법 검증
+   - `.venv/bin/python -m py_compile scripts/streamlit_browser_evidence.py dashboard/app.py`
+2. 대상 browser smoke
+   - `.venv/bin/python scripts/streamlit_browser_evidence.py`
+   - 확인 대상: `분류 규칙`, `확인필요 큐`, `Import`
+3. 전체 테스트
+   - `.venv/bin/python -m pytest -q`
+4. evidence 민감정보 검토
+   - manifest와 DOM snapshot에는 synthetic fixture 식별자만 포함되어야 한다.
+   - 운영 DB 기본 경로, 원본 금융 파일명, 비밀번호, 실제 raw_payload는 포함하지 않는다.
+
+## Acceptance Mapping
+
+- AC-1: `scripts/streamlit_browser_evidence.py`의 `assert_synthetic_db_path` 및 fixture 생성 로직.
+- AC-2: py_compile 결과.
+- AC-3: full pytest 결과.
+- AC-4/5: browser evidence script manifest 및 screenshot/snapshot 파일.
+- AC-6: `dashboard/app.py` Import page의 `db_path` 전달 수정.
+- AC-7: REQ/BAT/runtime/interface/project-structure/runbook 문서 갱신.
+
+## 결과
+
+최종 검증 결과(2026-06-29 KST):
+
+- `.venv/bin/python -m py_compile scripts/streamlit_browser_evidence.py dashboard/app.py jarca_ledger_mcp/db.py jarca_ledger_mcp/service.py jarca_ledger_mcp/server.py tests/test_service.py` — PASS.
+- `.venv/bin/python -m pytest -ra` — PASS (`27 passed, 4 skipped in 27.37s`).
+- `.venv/bin/python scripts/streamlit_browser_evidence.py` — PASS.
+  - Evidence directory: `docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-20260629-192835/`
+  - Manifest: `manifest.json` (`success: true`).
+  - Captured pages:
+    - `분류 규칙`: `rules.png` 364,876 bytes, `rules.dom.html` 174,470 bytes.
+    - `확인필요 큐`: `transfer-review.png` 275,792 bytes, `transfer-review.dom.html` 25,551 bytes.
+    - `Import`: `import.png` 297,424 bytes, `import.dom.html` 23,649 bytes.
+
+## Sensitive Evidence Review
+
+- Evidence DB path is the generated fixture path under BAT-004 evidence, not the operating DB default path.
+- Fixture rows use `SYNTHETIC_*` labels and do not include real account numbers, real financial source filenames, passwords, or raw payloads.
+- DOM/screenshot evidence was generated from synthetic fixture data only.