102 lines
5.2 KiB
Markdown
102 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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 — 인증 검증
|
|
|
|
```text
|
|
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 — 운영 문서
|
|
|
|
```text
|
|
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 |
|
|
|
|
## 검증
|
|
|
|
- 구조 검사 명령:
|
|
|
|
```text
|
|
python -m compileall -q dashboard tests scripts
|
|
```
|
|
|
|
- 구조 검사 기대 결과: exit 0 and no generated source outside ignored bytecode locations
|
|
- 정적 분석 명령:
|
|
|
|
```text
|
|
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
|