11 KiB
11 KiB
Project Structure — Dashboard 관리자 인증
목적과 경계
Issue #6 인증을 기존 Dashboard 구조에 배치하고 fail-closed 경계와 server-only secret binding을 유지한다.
- 포함 경계:
dashboard/인증 adapter/gate, tests, 운영 문서 - 제외 경계: MCP transport, 금융 schema, DB migration, external auth middleware
디렉터리 구조
dashboard-source — Dashboard source
dashboard/
├── server.py
├── auth_server.py
├── authentication.py
├── app.py
├── common.py
└── page_views/
| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
|---|---|---|---|---|---|---|
dashboard/server.py |
source | ASGI app 조립 | app |
route wiring only | source review required | developer |
dashboard/auth_server.py |
source | login/cleanup/logout response | create_auth_routes() |
no DB/page imports | source review required | developer |
dashboard/authentication.py |
source | config, constant-time compare, token verify, gate | require_dashboard_authentication() |
server-only secret use | source review required | developer |
dashboard/app.py |
source | auth gate first, then DB path resolution, common shell/sidebar/refresh assembly, and target body renderer dispatch | main() |
shell/background remain outside the replaceable body; no token signing details | source review required | developer |
dashboard/common.py |
source | shared Dashboard shell, menu/query transition, stable body container, loading/error/retry rendering, and app background/style | render_sidebar_nav(), render_dashboard_body(), inject_app_css() |
no authentication transport or financial write orchestration | source review required | developer |
dashboard/page_views/ |
source | financial UI pages | page_* functions |
no auth transport calls | source review required | developer |
dashboard/common.py owns the shared visual theme through JARCA_COLORS, JARCA_PLOTLY_TEMPLATE, and inject_app_css(). Page renderers consume that theme but do not own or replace the authenticated shell/sidebar background.
verification-tests — 인증 검증
tests/
├── test_dashboard_authentication.py
├── test_dashboard_persistent_authentication.py
├── test_dashboard_auth_server.py
├── test_dashboard_menu_transition.py
├── test_streamlit_browser_evidence.py
└── test_dashboard_authentication_app.py
| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
|---|---|---|---|---|---|---|
tests/test_dashboard_authentication.py |
test | credential compare, delay, redaction | pytest tests | test-only settings | source change paired with test | developer |
tests/test_dashboard_persistent_authentication.py |
test | claims, TTL, tamper, rotation | pytest tests | no real secrets | source change paired with test | developer |
tests/test_dashboard_auth_server.py |
test | HTTP routes and cookie scope | pytest tests | synthetic test credentials | source change paired with test | developer |
tests/test_dashboard_menu_transition.py |
test | REQ-002 menu/query/body transition and cache-clear regression | pytest/AppTest | synthetic fixture DB; no real secrets | source change paired with test and browser evidence where required | developer |
tests/test_streamlit_browser_evidence.py |
test | transition evidence manifest, redaction, TLS fixture and fail-closed validation | pytest | generated synthetic values only; no captured credential values | evidence-harness change paired with test | developer |
tests/test_dashboard_authentication_app.py |
test | gate ordering and cleanup/UI | AppTest | fixture DB only | source change paired with test | developer |
browser-evidence — 실제 전환 관찰
| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
|---|---|---|---|---|---|---|
scripts/streamlit_browser_evidence.py |
verification tool | synthetic DB와 runtime 생성 인증 설정으로 실제 HTTPS Dashboard 전환의 frame/DOM/document/shell 관찰을 수집하고 redacted manifest를 검증 | --mode transition |
운영 DB·credential 사용 금지; 성공 증거는 browser/server teardown 뒤에만 확정 | source review and focused test required | developer |
docs/evidence/issue-9-dashboard-menu-transition/ |
evidence artifact | exact source hash에 결합한 authenticated browser frame, screenshot, runtime, validator 결과 | manifest.json |
synthetic fixture only; credential/token/cookie 값 금지 | immutable after verification except complete regeneration | verification runner |
deployment-docs — 운영 문서
docs/requirements/req-001_dashboard-administrator-authentication.md
docs/requirements/req-002_dashboard-menu-transition.md
docs/evidence/issue-9-dashboard-menu-transition/
docs/interface-contract.md
docs/runtime-flow.md
README.md
deploy/k8s/README.md
| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
|---|---|---|---|---|---|---|
docs/requirements/req-001_dashboard-administrator-authentication.md |
requirement | approved REQ-001 revision 2.0 | REQ-001 | canonical traceability | update in place | developer |
docs/requirements/req-002_dashboard-menu-transition.md |
requirement | approved REQ-002 revision 1.0 | REQ-002 | canonical traceability | update in place | developer |
docs/interface-contract.md |
contract | HTTP/cookie/gate contracts | contract IDs | no implementation secrets | update with API changes | developer |
docs/runtime-flow.md |
design | runtime states/transitions | flow IDs | no secret values | update with flow changes | developer |
README.md |
operations | local/deployment constraints | operator commands | no secret values | operational review | developer |
deploy/k8s/README.md |
operations | k3s secret/TLS procedure | deployment procedure | no secret values | deployment review | developer |
의존 방향
| 출발 영역 | 대상 영역 | 허용 여부 | 규칙 | 공유 계약 위치 |
|---|---|---|---|---|
dashboard.server |
dashboard.auth_server |
허용 | compose ASGI routes only | docs/interface-contract.md |
dashboard.server |
dashboard.app |
허용 | app remains protected by gate | docs/runtime-flow.md |
dashboard.app |
dashboard.authentication |
허용 | gate precedes DB/page dispatch | docs/interface-contract.md |
dashboard.authentication |
dashboard.page_views |
금지 | auth module never imports financial pages | docs/project-structure.md |
dashboard.app |
dashboard.common |
허용 | menu/query/body transition helpers only after auth gate | docs/interface-contract.md |
dashboard.auth_server |
jarca_ledger_mcp DB |
금지 | login/cleanup/logout are DB-free | docs/requirements/req-001_dashboard-administrator-authentication.md |
변경 규칙
| 구분 | 규칙 |
|---|---|
| 새 모듈·파일 배치 | auth route/gate changes stay in dashboard/; menu transition stays in existing dashboard.app/dashboard.common; no DB session module |
| 이름·패키지 | use existing dashboard package and snake_case modules |
| 소스·테스트 대응 | auth source behavior requires focused pytest/AppTest coverage; REQ-002 transition behavior requires focused pytest/AppTest targets and real-browser evidence where specified |
| 생성 산출물 | evidence may be redacted; never commit credentials, secrets, tokens, or cookie values |
검증
-
구조 검사 명령:
python -m compileall -q dashboard tests scripts -
구조 검사 기대 결과: exit 0 and no generated source outside ignored bytecode locations
-
정적 분석 명령:
uv run --extra dashboard --extra dev ruff check dashboard tests scripts -
정적 분석 기대 결과: exit 0 with no diagnostics
-
문서와 실제 트리의 정합성: every listed source/test/document path exists; dependency table has no forbidden reverse edge; REQ-002 symbols resolve to
dashboard/app.py,dashboard/common.py, and named tests
REQ-003 additive structure
ledger-application — shared valuation and snapshot services
jarca_ledger_mcp/
├── application/account_valuation_service.py
├── application/assets_service.py
├── application/accounts_write_services.py
├── application/imports_service.py
├── application/reconciliation_service.py
├── infrastructure/sqlite/migrations.py
├── adapters/mcp/server.py
└── adapters/streamlit/{accounts_gateway.py,assets_gateway.py}
| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
|---|---|---|---|---|---|---|
jarca_ledger_mcp/application/account_valuation_service.py |
source | validation, selection, idempotency, correction | named valuation functions | SQLite through shared db | source review + focused tests | developer |
jarca_ledger_mcp/application/assets_service.py |
source | preview, formula, close/correction | preview_asset_snapshot_close, close_asset_snapshot |
snapshot transaction | source review + focused tests | developer |
jarca_ledger_mcp/infrastructure/sqlite/migrations.py |
source | schema 12 additive migration | init_db, migrate_db |
no UI/MCP imports | migration review | developer |
tests/test_account_valuations.py |
test | valuation contracts | pytest | synthetic DB | paired with source | developer |
tests/test_asset_snapshots.py |
test | preview/close/report contracts | pytest | synthetic DB | paired with source | developer |
docs/data-model.md |
canonical doc | entity/schema authority | document | no secrets | update with schema | developer |
의존 방향 추가
| 출발 영역 | 대상 영역 | 허용 여부 | 규칙 | 공유 계약 위치 |
|---|---|---|---|---|
dashboard.page_views |
streamlit gateways |
허용 | page → gateway only | docs/interface-contract.md |
streamlit gateways |
application services |
허용 | adapter delegates; no SQL | docs/runtime-flow.md |
MCP adapters |
application services |
허용 | tool delegates; no duplicate business logic | docs/interface-contract.md |
application services |
infrastructure.sqlite |
허용 | service → shared db/schema | docs/data-model.md |
application services |
dashboard |
금지 | no reverse UI dependency | docs/project-structure.md |
변경 규칙 추가
| 구분 | 규칙 |
|---|---|
| 새 모듈·파일 배치 | valuation/snapshot logic stays in application; adapters remain thin; no direct SQL in page/MCP |
| 이름·패키지 | existing snake_case modules and service re-exports |
| 소스·테스트 대응 | every valuation/snapshot change paired with named synthetic tests and docs validator |
| 생성 산출물 | only redacted synthetic evidence; no credentials, cookie, token or actual account data |
REQ-003 preservation inventory
REQ-001 auth gate, cookie/cleanup/logout and auth-before-DB; REQ-002 menu labels/order, query sibling preservation, stable shell/background and browser evidence remain in the preceding sections. Missing semantic items: 0. Ambiguous semantic items: 0.