5.2 KiB
5.2 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
└── 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 | gate then page dispatch | main() |
no token signing details | source review required | developer |
dashboard/page_views/ |
source | financial UI pages | page_* functions |
no auth transport calls | source review required | developer |
verification-tests — 인증 검증
tests/
├── test_dashboard_authentication.py
├── test_dashboard_persistent_authentication.py
├── test_dashboard_auth_server.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_authentication_app.py |
test | gate ordering and cleanup/UI | AppTest | fixture DB only | source change paired with test | developer |
deployment-docs — 운영 문서
docs/requirements/req-001_dashboard-administrator-authentication.md
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/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.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/; no DB session module |
| 이름·패키지 | use existing dashboard package and snake_case modules |
| 소스·테스트 대응 | auth source behavior requires focused pytest/AppTest coverage |
| 생성 산출물 | 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