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,69 @@
+# CI Smoke Gates Runbook
+
+- Scope: BAT-006 / REQ-006 pytest, Streamlit AppTest, dashboard HTTP smoke, and DB safety smoke gates.
+- Safety rule: every command below creates or uses a synthetic fixture/temporary validation DB only. Do not set `JARCA_LEDGER_DB_PATH` to the operating ledger DB for CI reproduction.
+
+## GitHub Actions gates
+
+The workflow is `.github/workflows/ci.yml` and runs on:
+
+- `pull_request`
+- `push` to `main`
+- `workflow_dispatch`
+
+Stable job/check names:
+
+- `pytest-regression`
+- `dashboard-app-test`
+- `dashboard-http-smoke`
+- `db-safety-smoke`
+
+## Local reproduction
+
+From repository root:
+
+```bash
+source .venv/bin/activate
+pytest --ignore=tests/test_dashboard_app.py
+pytest tests/test_dashboard_app.py
+python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
+python scripts/ci_db_safety_smoke.py --timeout 45
+```
+
+With uv, equivalent CI-style commands are:
+
+```bash
+uv sync --extra dev --extra dashboard
+uv run pytest --ignore=tests/test_dashboard_app.py
+uv run pytest tests/test_dashboard_app.py
+uv run python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
+uv run python scripts/ci_db_safety_smoke.py --timeout 45
+```
+
+## Wrapper responsibilities
+
+- `scripts/ci_fixture_db.py`
+  - Creates a deterministic synthetic fixture DB named `fixture.sqlite3`, `ci-ledger-fixture.sqlite3`, or `ledger-fixture.sqlite3`.
+  - Refuses the default operating DB path.
+  - Seeds only synthetic accounts, categories, budgets, and transactions.
+- `scripts/ci_dashboard_http_smoke.py`
+  - Creates a temp synthetic fixture DB.
+  - Starts Streamlit with `JARCA_LEDGER_DB_PATH` pointed at that fixture.
+  - Polls a loopback URL until HTTP 200 or timeout.
+  - Terminates/kills the Streamlit process during cleanup.
+  - Emits status-only JSON.
+- `scripts/ci_db_safety_smoke.py`
+  - Creates a temp synthetic fixture DB and backup copy.
+  - Runs `scripts/ledger_restore_smoke.py` against temp source/backup/target paths only.
+  - Emits status-only JSON and never requires restore approval because the target is newly created under temp space.
+
+## Browser evidence boundary
+
+Browser screenshot/DOM evidence remains local evidence from `scripts/streamlit_browser_evidence.py`. It is not a required GitHub Actions gate. Use it in addition to the CI gates when a change materially affects visual layout or browser-only behavior.
+
+## Failure triage
+
+- `pytest-regression` failure: reproduce with `pytest --ignore=tests/test_dashboard_app.py` and fix the failing unit/service/parser test.
+- `dashboard-app-test` failure: reproduce with `pytest tests/test_dashboard_app.py`; inspect Streamlit AppTest exceptions first.
+- `dashboard-http-smoke` failure: check whether port 18501 is already in use locally, then rerun with a different port if needed. In CI the job uses a fresh runner.
+- `db-safety-smoke` failure: inspect the wrapper JSON fields `restore_smoke_exit_code`, `restored_integrity`, and `health_success`. Do not retry against the operating DB.