388 lines
9.5 KiB
Markdown
388 lines
9.5 KiB
Markdown
---
|
|
title: ""
|
|
source_type: "report"
|
|
status: "draft"
|
|
confidence: "unknown"
|
|
derived_from:
|
|
- "raw/branch-notes/<branch-name>"
|
|
- "wiki/projects/<canonical-doc>"
|
|
related_projects:
|
|
- "ca-tmpl"
|
|
target_branch: ""
|
|
target_module: ""
|
|
audience: "self"
|
|
purpose: "branch-implementation-understanding"
|
|
last_reviewed: ""
|
|
status_label: "draft"
|
|
---
|
|
|
|
# {{title}}
|
|
|
|
> 이 문서는 이해를 위한 derived report입니다.
|
|
> SSOT는 `raw/branch-notes/`와 `wiki/projects/`의 canonical 문서입니다.
|
|
> 이 문서는 branch-note의 모든 내용을 보존하지 않고, 사람이 읽고 설명할 수 있도록 재구성합니다.
|
|
|
|
---
|
|
|
|
## 0. Executive Summary
|
|
|
|
### 한 문장 요약
|
|
|
|
> 이 기능은 `<무엇>`이 `<어떤 문제>`를 일으키지 않도록, `<어느 계층>`에서 `<어떤 계약>`으로 통제하는 기능이다.
|
|
|
|
### 이 보고서를 읽고 답할 수 있어야 하는 질문
|
|
|
|
- 이 기능은 왜 필요한가?
|
|
- 이 기능이 없으면 어떤 실패가 발생하는가?
|
|
- Clean Architecture 구조에서 어디에 위치하는가?
|
|
- 어떤 모듈이 무엇을 책임지고 무엇을 몰라야 하는가?
|
|
- 실제 구현은 어떤 원리로 동작하는가?
|
|
- 무엇을 테스트로 증명해야 하는가?
|
|
|
|
### 관련 문서
|
|
|
|
- Branch note:
|
|
- `raw/branch-notes/<branch-name>`
|
|
- Canonical project:
|
|
- `wiki/projects/<canonical-doc>`
|
|
- 관련 코드:
|
|
- `<module>/<path>`
|
|
- 관련 테스트:
|
|
- `<module>/<test-path>`
|
|
|
|
---
|
|
|
|
## 1. 이 기능은 어떤 문제를 해결하는가?
|
|
|
|
### 문제 정의
|
|
|
|
`<문제 설명>`
|
|
|
|
### 이 문제가 중요한 이유
|
|
|
|
- `<이유 1>`
|
|
- `<이유 2>`
|
|
- `<이유 3>`
|
|
|
|
### 이 기능이 없을 때 생기는 구조적 문제
|
|
|
|
- `<레이어 침투>`
|
|
- `<기술 누출>`
|
|
- `<실패 분류 불일치>`
|
|
- `<테스트로 감지 불가>`
|
|
|
|
---
|
|
|
|
## 2. 실제 실패 시나리오
|
|
|
|
### 시나리오 A. `<실패 이름>`
|
|
|
|
**상황**
|
|
|
|
`<현실적인 상황 설명>`
|
|
|
|
**실패 흐름**
|
|
|
|
```text
|
|
<입력/요청>
|
|
→ <잘못된 처리>
|
|
→ <장애/버그>
|
|
→ <운영 영향>
|
|
```
|
|
|
|
**이 기능이 막는 방식**
|
|
|
|
`<어떤 계약/테스트/모듈 경계가 이 실패를 막는지>`
|
|
|
|
---
|
|
|
|
### 시나리오 B. `<실패 이름>`
|
|
|
|
**상황**
|
|
|
|
`<현실적인 상황 설명>`
|
|
|
|
**실패 흐름**
|
|
|
|
```text
|
|
<입력/요청>
|
|
→ <잘못된 처리>
|
|
→ <장애/버그>
|
|
→ <운영 영향>
|
|
```
|
|
|
|
**이 기능이 막는 방식**
|
|
|
|
`<어떤 계약/테스트/모듈 경계가 이 실패를 막는지>`
|
|
|
|
---
|
|
|
|
## 3. Clean Architecture 안에서의 위치
|
|
|
|
### 관련 모듈
|
|
|
|
| 모듈 | 이 기능과의 관계 |
|
|
| ------------------- | ---------------- |
|
|
| domain-core | |
|
|
| application-core | |
|
|
| adapter-web | |
|
|
| adapter-persistence | |
|
|
| adapter-outbound | |
|
|
| shared-contract | |
|
|
| app-bootstrap | |
|
|
| sample-portfolio | |
|
|
|
|
### 의존 방향
|
|
|
|
```text
|
|
<허용되는 의존 방향>
|
|
```
|
|
|
|
### 이 기능의 소유 계층
|
|
|
|
- 주 소유 계층:
|
|
- 보조 계층:
|
|
- 소비 계층:
|
|
|
|
---
|
|
|
|
## 4. 각 모듈은 무엇을 책임지고 무엇을 몰라야 하는가?
|
|
|
|
| 모듈 | 책임 | 몰라야 하는 것 | 위반 예시 |
|
|
| ------------------- | ---- | -------------- | --------- |
|
|
| domain-core | | | |
|
|
| application-core | | | |
|
|
| adapter-web | | | |
|
|
| adapter-persistence | | | |
|
|
| adapter-outbound | | | |
|
|
| shared-contract | | | |
|
|
| app-bootstrap | | | |
|
|
| sample-portfolio | | | |
|
|
|
|
---
|
|
|
|
## 5. 핵심 설계 결정
|
|
|
|
| ID | 결정 | 이유 | 대안 | 선택하지 않은 이유 | 상태 |
|
|
| --- | ---- | ---- | ---- | ------------------ | ---- |
|
|
| D1 | | | | | |
|
|
| D2 | | | | | |
|
|
| D3 | | | | | |
|
|
|
|
### 가장 중요한 결정 1개
|
|
|
|
`<이 branch에서 가장 중요한 결정>`
|
|
|
|
### 이 결정이 중요한 이유
|
|
|
|
`<왜 이 결정이 전체 구조를 좌우하는지>`
|
|
|
|
---
|
|
|
|
## 6. 핵심 구현 원리
|
|
|
|
### 구현 원리 요약
|
|
|
|
`<핵심 구현 원리 설명>`
|
|
|
|
### 처리 흐름
|
|
|
|
```text
|
|
<입력>
|
|
→ <경계>
|
|
→ <변환>
|
|
→ <핵심 처리>
|
|
→ <외부 어댑터>
|
|
→ <응답/로그/테스트>
|
|
```
|
|
|
|
### 구현 위치
|
|
|
|
| 코드 위치 | 역할 | 관련 결정 |
|
|
| --------- | ---- | --------- |
|
|
| `<path>` | | D1 |
|
|
| `<path>` | | D2 |
|
|
| `<path>` | | D3 |
|
|
|
|
---
|
|
|
|
## 7. 상태나 데이터 모델은 어떻게 생기는가?
|
|
|
|
### 주요 타입
|
|
|
|
| 타입 | 위치 | 역할 | 노출 가능 여부 |
|
|
| ------------------- | ---- | ---- | -------------- |
|
|
| Request DTO | | | |
|
|
| Command/Query | | | |
|
|
| Domain Model | | | |
|
|
| Persistence Entity | | | |
|
|
| Response DTO | | | |
|
|
| Error/Envelope Type | | | |
|
|
|
|
### 변환 흐름
|
|
|
|
```text
|
|
HTTP JSON
|
|
→ Request DTO
|
|
→ Command / Query
|
|
→ Domain Model
|
|
→ Persistence Entity
|
|
→ Response DTO
|
|
→ Envelope
|
|
```
|
|
|
|
### 주의할 점
|
|
|
|
- DTO와 Domain을 섞지 않는다.
|
|
- Domain과 Persistence Entity를 동일시하지 않는다.
|
|
- 내부 진단 정보와 외부 응답 payload를 섞지 않는다.
|
|
|
|
---
|
|
|
|
## 8. 동시성/장애 상황에서 어떻게 동작하는가?
|
|
|
|
### 장애 분류
|
|
|
|
| 장애 상황 | 감지 위치 | 변환 결과 | client 노출 | log/trace |
|
|
| --------------------- | --------- | --------- | ----------- | --------- |
|
|
| validation failure | | | | |
|
|
| persistence failure | | | | |
|
|
| dependency timeout | | | | |
|
|
| authorization failure | | | | |
|
|
| concurrency conflict | | | | |
|
|
|
|
### 동시성 관련 동작
|
|
|
|
- transaction boundary:
|
|
- lock/retry/idempotency 관련 여부:
|
|
- 중복 실행 시 기대 동작:
|
|
- multi-instance 관련 제약:
|
|
|
|
---
|
|
|
|
## 9. 이 구현이 보장하는 것과 보장하지 못하는 것
|
|
|
|
### 보장하는 것
|
|
|
|
- `<자동 테스트나 컴파일 규칙으로 검증 가능한 것>`
|
|
- `<계약상 반드시 유지되는 것>`
|
|
|
|
### 보장하지 못하는 것
|
|
|
|
- `<정적 분석으로 잡기 어려운 것>`
|
|
- `<운영 환경에서 추가 검증이 필요한 것>`
|
|
- `<비즈니스 요구사항 자체의 정합성>`
|
|
|
|
### 표현 주의
|
|
|
|
아래 표현은 사용하지 않는다.
|
|
|
|
- 완벽히 보장한다
|
|
- 100% 방지한다
|
|
- 완전무결하다
|
|
- 모든 상황에서 안전하다
|
|
|
|
대신 아래처럼 쓴다.
|
|
|
|
- 빌드 시점에 감지한다
|
|
- 정적 import 위반을 차단한다
|
|
- 계약 위반을 테스트로 드러낸다
|
|
- 런타임 동적 우회는 코드 리뷰와 추가 테스트가 필요하다
|
|
|
|
---
|
|
|
|
## 10. 테스트는 무엇으로 증명해야 하는가?
|
|
|
|
| 테스트 종류 | 증명하는 것 | 실패해야 하는 조건 | 실행 명령 |
|
|
| ----------------- | ----------- | ------------------ | --------- |
|
|
| unit test | | | |
|
|
| contract test | | | |
|
|
| architecture test | | | |
|
|
| integration test | | | |
|
|
| smoke test | | | |
|
|
|
|
### 핵심 테스트
|
|
|
|
```bash
|
|
<명령어>
|
|
```
|
|
|
|
### 이 테스트가 깨졌을 때 의미
|
|
|
|
`<어떤 계약이 깨졌다는 뜻인지>`
|
|
|
|
---
|
|
|
|
## 11. Implementation Status
|
|
|
|
| 항목 | 상태 | 근거 | 비고 |
|
|
| -------- | ------------------------------------------------------------------------ | -------------------- | ---- |
|
|
| `<항목>` | `<decision-only / documented-only / local-verified / pending / unknown>` | `<문서/코드/테스트>` | |
|
|
|
|
### 상태 값 정의
|
|
|
|
| 상태 | 의미 |
|
|
| --------------- | ----------------------------------- |
|
|
| decision-only | 결정은 있으나 구현/검증은 아직 없음 |
|
|
| documented-only | 문서상 계약만 있음 |
|
|
| local-verified | 로컬 코드/테스트로 검증됨 |
|
|
| pending | 아직 착수 전 또는 잔여 작업 존재 |
|
|
| unknown | 근거 부족으로 판단 불가 |
|
|
|
|
---
|
|
|
|
## 12. Fact / Interpretation / Unknown
|
|
|
|
### 검증된 사실
|
|
|
|
- `<검증된 사실>` — 근거: `[[...]]`
|
|
|
|
### 내 해석
|
|
|
|
- `<내 해석>` — 이유: `<왜 그렇게 해석했는지>`
|
|
|
|
### 아직 모르는 것
|
|
|
|
- `<확인 필요 항목>`
|
|
|
|
---
|
|
|
|
## 13. 설명용 문장
|
|
|
|
### 30초 설명
|
|
|
|
`<짧은 설명>`
|
|
|
|
### 2분 설명
|
|
|
|
`<면접/리뷰에서 말할 수 있는 설명>`
|
|
|
|
### 깊게 질문받았을 때 답변
|
|
|
|
**Q. 왜 이렇게 나누었나?**
|
|
A. `<답변>`
|
|
|
|
**Q. 이 구조의 한계는 무엇인가?**
|
|
A. `<답변>`
|
|
|
|
**Q. 이게 실제 장애를 어떻게 막나?**
|
|
A. `<답변>`
|
|
|
|
---
|
|
|
|
## 14. 남은 리스크와 후속 작업
|
|
|
|
| 리스크 | 영향 | 확인 방법 | 후속 문서/branch |
|
|
| ------ | ---- | --------- | ---------------- |
|
|
| | | | |
|
|
|
|
---
|
|
|
|
## 15. Closure
|
|
|
|
- 이 보고서를 작성한 기준일:
|
|
- 반영한 branch-note:
|
|
- 반영한 코드 버전/커밋:
|
|
- 아직 반영하지 않은 자료:
|
|
- 다음에 읽을 문서:
|