jun-bank 설계 문서

jun-bank 시스템의 단일 설계 출처. 각 서비스 저장소의 README는 "그 서비스를 어떻게 돌리나"만 다루고, "왜 그렇게 설계했나"는 전부 여기에 있다.

★ 세션 인계·현황의 정본은 HANDOFF.md다. 이 문서는 무엇이 어디 있나(지도)를 맡고, HANDOFF.md는 지금 무엇을 하는 중이고 무엇을 되돌리면 안 되나를 맡는다. 두 문서가 갈리면 HANDOFF가 이긴다.

Phase 1 ✅ ── 2 ✅ ── 3 ✅ ── 4 ✅ ── 5 ⏳ ── 6 ⬜
                                     ▲
                                 현재 위치

다음 한 걸음(Phase 5 진행 중): ① 워킹 스켈레톤 라우팅 실증 — 최소 서비스 3 + Spring Cloud Gateway를 docker compose로 띄워 라우팅을 확인한다 ② 첫 실배포 — 인프라 배포 파이프라인으로 스켈레톤을 실제로 배포한다 ③ 배포 파이프라인·JWKS e2e [구현 검증] 해소 — 문서가 이연한 판정(IV 대장 implementation-verification.md)을 실 배포·인증 흐름으로 실증한다 ④ 도메인 로직 — 그 위에 컨텍스트별 실 구현을 얹는다. (병행 이월: C7 관리 API의 UC·계약 L1-15.)

양식과 내용은 다르다. 양식은 study-note repo project/jun-bank/workflow/(2026-09-16 이관)에, 내용은 이 repo의 product/·domain/·architecture/·usecases/ 같은 정규 위치에 있다. (초기 계획은 Phase 0~9의 10단계 체계였다 — 위 6단계 체계로 통합됐고 10단계 표기는 이력이다.)

설계는 이 docs 저장소, 구현은 각 repo. 이 문서가 설계 정본 허브이고, 실제 코드는 별도 저장소에 산다 — infra(Go 인프라 도구 deploy-agent·dispatcher·watchdog) · common(Kotlin 공통 라이브러리 — 계약·인프라만 공유, 도메인 비공유 ADR-025) · core·settlement·ledger(Kotlin/Spring 서비스 = 배포 3단위, 현재 워킹 스켈레톤) · gateway(내부 API 게이트웨이 Spring Cloud Gateway). "그 서비스를 어떻게 돌리나"는 각 repo README, "왜 그렇게 설계했나"는 여기.

product/01-business-rules.md가 이긴다. BR과 불일치 유형은 거기가 정본이고, ADR·애그리게이트·유스케이스 문서는 그것을 어떻게 하는지를 적는다. 용어는 domain/glossary.md, 현황·인계는 HANDOFF.md가 정본이다.

★ 처음부터 전부 읽는 상세 순서는 READING-ORDER.md — 일곱 층(제품→도메인→아키텍처→유스케이스→설계변경→배포)으로 무엇을 왜 그 순서로 읽는지 안내한다. 아래는 그 요약이다.

① README.md (이 문서)                    무엇이 어디 있나
② HANDOFF.md                              지금 어디까지 왔고 무엇을 건드리면 안 되나
③ product/00-product-definition.md        이 시스템은 무엇인가
④ domain/glossary.md                      어떤 개념으로 이루어지나
⑤ architecture/README.md                  구조가 왜 이렇게 됐나 (ADR로 이어진다)

① HANDOFF.md 에서 현재 Phase 확인
② study-note repo project/jun-bank/workflow/ 에서 그 Phase의 양식(*-format.md) 확인
③ §3 양식을 복사해 정규 위치(product/, domain/, architecture/, usecases/)에 채운다
④ 양식의 §6 완료 기준으로 검증
⑤ python3 tools/check_docs.py · tools/mutation_test.py 로 검산

1. 결정은 ADR에만. 다른 문서에 "~하기로 했다"가 있으면 ADR 링크를 단다. 근거가 두 곳에 있으면 반드시 갈라진다.
2. 미확정은 숨기지 않는다. 정해지지 않은 것은 문서 안에 [미확정]·열린 의문으로 남긴다. 다음 Phase로 추정해서 넘기지 않는다.
3. 용어는 domain/glossary.md가 정본. 다른 문서에서 용어를 새로 정의하지 않는다.
4. 규칙은 product/01-business-rules.md가 정본. 다른 문서는 BR-nn으로 참조만 한다.
5. 순서를 앞지르지 않는다. 선행 Phase의 산출물이 없으면 그 Phase를 시작하지 않는다.
6. 문서도 버전을 갖는다. 각 문서 하단에 변경 이력.
7. ★ "반영 완료"를 적기 전에 본문을 다시 연다. 이 프로젝트에서 "고쳤다고 적고 안 고침" 이 반복 발생한 실측 결함이다(HANDOFF §3).

네 단계만 쓴다. "초안 v0.1", "골격만", "제안됨" 같은 임의 표현을 섞지 않는다.

각 문서 상단에 한 줄로 표기한다: - 상태: 작성중

기법을 써보기 위해 도메인을 고르는 것이 아니라, 도메인이 기법을 요구하게 만드는 것.

결제 도메인은 분산 시스템 기법이 "있으면 좋은 것"이 아니라 없으면 실제로 돈이 틀어지는 몇 안 되는 영역이다. 멱등성이 없으면 이중 승인이 나고, 이벤트 유실 방지가 없으면 정산 대사에서야 원장 누락이 발견된다.

그래서 이 저장소의 1차 산출물은 동작하는 은행이 아니라 판단의 근거다. 그리고 설계 워크플로우 자체가 두 번째 산출물이며, 그쪽이 더 오래 산다(HANDOFF §1).

Q. study/는 어디 갔나? 2026-09-16에 study-note repo로 이관됐다. 개인 학습 노트(CS·개념)는 study-note/cs/로, 워크플로우 양식·infra 개발 기록은 study-note/project/jun-bank/로 옮겼다.
학습 노트는 결정의 근거가 될 수 없다(결정은 이 repo의 ADR에만). 워크플로우는 study-note에서 문서 작성 순서·양식의 정본으로 유지된다.

Q. 왜 양식과 내용을 분리하는가? 특정 프로젝트에 맞춰 미리 써둔 문서는 대부분 읽히지 않고 낡는다. 재사용되는 것은 양식과 작성법이다.

Q. 문서가 코드와 다르면? 문서를 고친다. 틀린 문서는 없는 문서보다 나쁘다. 고칠 수 없으면 상태를 낮추거나 폐기한다.

Q. 검산이 통과하면 결함이 없는 것인가? 아니다. check_docs.py가 통과한 상태에서 치명 결함이 나온 적이 있다(HANDOFF §4). 검산은 과거에 겪은 결함 형태를 다시 잡아줄 뿐이다.