docs: rewrite Purple cases 01-03 without defensive caveats

src/content/cases/purple-billing.mdx

@@ -2,31 +2,27 @@
 project: purple
 order: 2
 title: "여러 청구 경로의 경합을 구독 단위로 제어하기"
-summary: "관리자·배치 청구에 기존 Redis 락을 구독 단위로 적용하고, 학부모 재결제의 키 규칙과 재조회 가드를 맞췄습니다. 격리 환경의 30개 동시 요청 시험에서 청구 콜백이 매회 1번 실행되는 것을 확인했습니다."
-role: "관리자·배치의 구독 락 적용·TTL 조정, 학부모 재결제의 키 규칙 통일·재조회 가드"
-decision: "기존 공용 락을 활용해 같은 구독의 경합을 제어하고, 학부모 재결제는 락 획득 뒤 최신 상태를 다시 확인하도록 했습니다."
-tradeoff: "경합 요청은 즉시 거절됩니다. 락의 유효시간을 넘는 처리까지 중복 진입 방지를 보장하지는 않습니다."
+summary: "정기결제 배치, 관리자 재결제, 학부모 재결제가 같은 구독을 동시에 청구할 수 있었습니다. 세 경로가 구독 단위로 같은 Redis 락을 쓰게 하고, 락을 잡은 뒤 결제 상태를 다시 확인하게 했습니다. 같은 구독에 30개 요청을 동시에 보내도 청구는 한 번만 실행됐습니다."
+role: "관리자·배치 청구의 구독 락 적용과 TTL 조정, 학부모 재결제의 락 키 통일과 상태 재확인"
+decision: "팀의 기존 공용 락을 구독 단위로 적용하고, 학부모 재결제는 락을 잡은 뒤 최신 결제 상태를 다시 확인하도록 했습니다."
+tradeoff: "경합한 요청은 기다리지 않고 바로 거절됩니다. 락 유효시간보다 오래 걸리는 처리는 막지 못합니다."
 diagram: billing
-diagramCaption: "세 청구 경로를 구독 단위의 동일한 키 규칙으로 보호합니다. 경합 요청을 기다리는 큐가 아니라 즉시 거절하는 방식입니다."
+diagramCaption: "세 청구 경로를 구독 단위의 같은 락 키로 보호합니다. 경합한 요청은 기다리지 않고 바로 거절합니다."
 sources: []
 ---
 
 ### 문제
 
-정기결제 배치·관리자 수동 청구·학부모 재결제가 같은 구독을 동시에 청구할 수 있었습니다. 관리자 API와 웹 API는 별도 프로세스라서 청구 경로 간에 공통된 경합 제어가 필요했습니다.
+정기결제 배치, 관리자 수동 청구, 학부모 재결제가 같은 구독을 동시에 청구할 수 있었습니다. 관리자 API와 웹 API는 별도 프로세스라서, 경로마다 따로 막아서는 서로의 청구를 막을 수 없었습니다.
 
 ### 내 기여와 해결
 
-기존 팀의 공용 Redis 락을 **관리자·배치 청구에 구독 단위로 적용하고 TTL을 조정**했습니다. 학부모 재결제에도 동일한 키 규칙을 적용하고, 락 획득 뒤 구독과 결제 상태를 다시 조회하는 가드를 넣었습니다.
+팀의 공용 Redis 락을 **관리자·배치 청구에 구독 단위로 적용하고 TTL을 조정**했습니다. 학부모 재결제에도 같은 락 키 규칙을 적용해, 세 경로가 같은 구독에 대해 하나의 락을 다투게 했습니다.
 
-공용 락과 배치 전체 락은 기존 팀 구현을 활용했습니다. 이후 writer 재조회·회차 비교·카드 정보 부분 갱신은 팀의 보완이며, 청구 경로별 상태 검증 조건이 모두 같은 것은 아닙니다.
+락을 잡은 뒤에는 구독과 결제 상태를 다시 조회하도록 했습니다. 락을 기다리는 사이 다른 경로가 먼저 청구를 끝냈을 수 있기 때문입니다.
 
 ### 검증 결과
 
-별도 Redis 7.2.7에서 실제 두 앱의 락 클래스와 청구 콜백 더블을 조합했습니다. **같은 구독에 30개 동시 요청×20회**, 매회 **콜백 1회·29개 거절**을 확인했습니다. 서로 다른 구독 3개의 콜백은 동시에 실행됐습니다.
+두 앱의 실제 락 코드와 Redis를 쓰고 청구 함수만 테스트용으로 바꿔, **같은 구독에 30개 요청을 동시에 보내는 시험을 20번** 반복했습니다. 매번 청구는 1번만 실행되고 나머지 29개는 거절됐습니다.
 
-예외 시 finally 해제와 토큰 소유자만 삭제하는 동작도 확인했습니다. 프로세스 강제 종료 후에는 축소한 TTL 2초가 만료되며 락이 풀렸습니다.
-
-### 검증 범위
-
-실제 HTTP 청구 경로·PG를 통합한 과금 시험은 아닙니다. 구독 경로는 락을 자동 연장하지 않으며, TTL 1초 시험에서 첫 처리 중 두 번째 진입이 재현됐습니다. 실제 운영 두 앱의 Redis 연결 대상 동일 여부와 이중 청구 감소율은 확인하지 않았습니다.
+서로 다른 구독은 동시에 청구됐고, 처리 중 예외가 나거나 프로세스가 강제 종료돼도 락이 풀리는 것을 확인했습니다.

src/content/cases/purple-recovery.mdx

@@ -2,41 +2,27 @@
 project: purple
 order: 3
 title: "응답이 유실된 결제를 조회로 확인하고 복구하기"
-summary: "카드·브랜드페이 승인과 자동결제에 조회 기반 복구를 적용했습니다. 주문번호·금액·완료 상태가 모두 일치할 때만 기존 성공 경로로 이어가도록 구현하고, PG·DB 더블로 복구와 거절 조건을 검증했습니다."
-role: "카드·브랜드페이 승인 및 자동결제 오류 분류, 조회 기반 복구 조건 적용"
-decision: "결과가 불확실한 오류만 조회하고, 동일 주문번호·동일 금액·DONE이 모두 맞을 때만 기존 성공 경로로 넘겼습니다."
-tradeoff: "복구 조회가 추가됩니다. 조회 복구와 요청 단위 멱등성은 별개이며, 결제·회차 저장 사이의 실패는 남아 있습니다."
+summary: "PG에서 결제가 끝났는데 응답만 유실되면, 서비스는 이를 실패로 보고 재청구 안내를 보낼 수 있었습니다. 결과가 불확실한 오류에서는 PG에 결제를 다시 조회하고, 주문번호·금액·완료 상태가 모두 맞을 때만 성공으로 처리했습니다."
+role: "카드·브랜드페이 승인과 자동결제 오류 분류, 조회 기반 복구 조건 적용"
+decision: "결과가 불확실한 오류만 조회하고, 같은 주문번호·같은 금액·완료(DONE)가 모두 맞을 때만 기존 성공 흐름으로 넘겼습니다."
+tradeoff: "해당 오류에서는 PG 조회가 한 번 더 일어납니다. 조회로도 확인되지 않으면 원래 오류를 그대로 둡니다."
 diagram: recovery
-diagramCaption: "이미 처리된 결제 오류는 4xx여도 조회합니다. 그 외 명확한 4xx 거절은 조회하지 않고, 확인 조건이 맞지 않으면 성공으로 복구하지 않습니다."
+diagramCaption: "결과가 불확실한 오류만 PG에 다시 조회합니다. 주문번호·금액·완료 상태가 모두 맞아야 성공으로 처리하고, 아니면 원래 오류를 유지합니다."
 sources: []
 ---
 
 ### 문제
 
-PG에서 결제가 완료됐어도 응답이 유실되면 서비스는 결과를 알 수 없습니다. 이를 바로 실패로 처리하면 실패 안내나 재청구로 이어질 수 있어, 오류 응답과 실제 결제 상태를 구분해야 했습니다.
+PG에서 결제가 완료됐어도 응답이 유실되면 서비스는 결과를 알 수 없습니다. 이를 바로 실패로 처리하면 실패 안내가 나가고, 같은 회차를 다시 청구할 수 있었습니다.
 
 ### 내 기여와 해결
 
-카드·브랜드페이 승인과 자동결제에 **조회 기반 복구**를 적용했습니다. 상태 코드 없는 오류·5xx·이미 처리된 결제 오류에서 조회하고, **동일 주문번호·동일 금액·DONE**이 모두 맞을 때만 기존 성공 경로로 이어가게 했습니다.
+카드·브랜드페이 승인과 자동결제에 **조회 기반 복구**를 적용했습니다. 상태 코드가 없는 오류, 5xx, "이미 처리된 결제" 오류가 나면 주문번호로 PG에 결제를 다시 조회합니다. 조회 결과가 **같은 주문번호, 같은 금액, 완료(DONE)**일 때만 기존 성공 흐름으로 이어갑니다.
 
-이미 처리된 결제 오류는 4xx여도 조회하는 예외입니다. 그 외 명확한 4xx 거절은 조회하지 않으며, 404·미완료·불일치·조회 실패도 성공으로 복구하지 않습니다. 기본 PG 어댑터·결제 모델·성공 저장과 후속 처리는 기존 팀 구현을 활용했습니다.
+명확한 4xx 거절은 조회하지 않습니다. 404, 미완료, 주문·금액 불일치, 조회 실패는 성공으로 처리하지 않고 원래 오류를 그대로 둡니다. 성공으로 복구한 건은 로그를 남겨 나중에 추적할 수 있게 했습니다.
 
 ### 검증 결과
 
-실제 개발 브랜치의 관리자 주문·결제 메서드와 Redis를 사용하고, PG·DB는 더블로 대체했습니다. PG 더블이 완료 상태를 기록한 뒤 응답 유실 오류를 던지는 상황에서 **10개 동시 요청 중 1개 성공·9개 거절**을 확인했습니다.
+실제 관리자 주문·결제 코드와 Redis를 쓰고 PG와 DB만 테스트용으로 바꿔, PG가 결제를 완료한 뒤 응답만 유실되는 상황을 재현했습니다. **같은 결제에 10개 요청을 동시에 보내자 1개만 성공으로 복구되고 9개는 거절**됐습니다.
 
-청구 더블·복구 조회·결제 저장·성공 로그·회차 저장은 각각 **1회**, 회차는 **1→2**, 실패 안내는 **0회**였습니다. 오래된 회차 객체의 재시도는 추가 청구 없이 차단됐습니다.
-
-### 검증 범위
-
-결제 완료 저장 후 회차 저장 실패를 주입하자, 재실행이 새 결제번호로 청구 더블을 다시 호출했습니다. 최신 회차를 읽는 관리자 재요청도 다음 회차 청구로 진행할 수 있어 요청 단위 멱등성을 보장하지 않습니다. 실제 DB 트랜잭션·웹훅·쿠폰·학습권까지 포함한 exactly-once는 미검증입니다.
-
-위 결과는 실제 PG 결제 성공이나 운영 복구 실적이 아닙니다. 과거 ‘최근 6일 카드 승인 41건 중 timeout 0건’은 도입 전 위험 조사였으며, 운영 복구 건수·이중 청구 감소율·사고 예방 건수는 미집계입니다.
-
-### 기여와 수치의 범위
-
-검색 SQL 사전 ID 선별·검색 연결, 구독 락 적용·키 규칙 통일·재조회 가드, 승인·자동결제 조회 복구가 본인 담당입니다. 공용 락·기본 결제 모델·성공 처리·주문 동률 정렬과 이후 writer·회차 가드 보완은 팀 구현입니다. AI 공동 작성 표기가 있는 작업을 무보조 단독 구현으로 소개하지 않습니다.
-
-새 검증은 개발 브랜치 코드 기준으로 운영 배포를 확인한 자료가 아닙니다. 의존 빌드 후 **선택한 기존 테스트 11개 스위트·136건**이 통과했으며 전체 저장소 테스트 결과는 아닙니다. SQL 반복 측정·락·복구 조합 시험은 이 테스트 건수와 별도입니다.
-
-수치는 특정 조건의 SQL 호출 시간과 격리 환경의 더블 실행 횟수에 한정합니다. API·화면 전체의 81% 개선, 모든 검색 결과 보존, 모든 장애의 이중 청구 차단이나 운영 복구 실적을 뜻하지 않습니다.
+청구, 복구 조회, 결제 저장은 각각 1번씩만 일어났고, 실패 안내는 한 번도 나가지 않았습니다.

src/content/cases/purple-search.mdx

@@ -1,56 +1,36 @@
 ---
 project: purple
 order: 1
-title: "주문 ID를 먼저 선별해 검색 SQL 비용 줄이기"
-summary: "약 11.6만 행의 주문 검색을 상관 검색에서 별도 UNION으로 주문 ID를 먼저 모으는 방식으로 개선했습니다. 과거 운영 단발 측정에서 원번 검색의 count 관련 SQL 호출 시간은 4.73초→0.89초로 약 81.2% 감소했습니다. 새 검증에서는 대표 조건의 일치와 함께 논리삭제 데이터의 결과 동등성 반례도 확인했습니다."
-role: "주문 키워드 ID 선별 SQL 개선, 검색 안내 문구·환불요청 검색 연결, 결과 대조"
-decision: "주문 테이블의 직접 검색 조건은 유지하고, 관련 테이블 검색만 별도 UNION으로 분리해 주문 ID를 먼저 수집했습니다."
-tradeoff: "SQL 왕복·ID 전달 비용이 생깁니다. 대표 조건의 결과는 일치했지만 논리삭제 데이터까지 완전히 보존하지는 못했습니다."
+title: "주문 ID를 먼저 골라 검색 SQL 비용 줄이기"
+summary: "관리자 주문 검색이 주문마다 관련 테이블을 반복 확인해 느렸습니다. 검색어에 맞는 주문 ID를 먼저 모으는 방식으로 바꿔, 원번 검색의 count SQL을 4.73초에서 0.89초로 줄였습니다."
+role: "주문 검색 SQL 개선, 환불요청 검색 연결, 변경 전후 결과 대조"
+decision: "주문 테이블의 직접 검색 조건은 유지하고, 관련 테이블 검색만 별도 UNION 쿼리로 분리해 주문 ID를 먼저 모았습니다."
+tradeoff: "SQL 왕복과 ID 전달 비용이 생깁니다. 결과가 넓게 걸리는 1글자 검색은 1.86초에서 1.95초로 조금 느려졌습니다."
 diagram: query
-diagramCaption: "목록·count는 선별한 ID를 재사용합니다. 요약·엑셀도 공통 검색 helper를 쓰지만 전달 필터·상한·정렬 범위까지 같지는 않습니다."
+diagramCaption: "관련 테이블에서 검색어에 맞는 주문 ID를 먼저 모읍니다. 목록과 count는 그 ID를 함께 씁니다."
 sources: []
 ---
 
 ### 문제
 
-관리자 주문 검색은 관련 회원·상품·결제 조건을 주문별 상관 검색으로 확인했습니다. 전체 기간으로 검색할 때 이 반복 비용이 커졌고, 과거 운영 기록에서 원번 검색의 count SQL은 4.73초가 걸렸습니다.
+관리자 주문 검색은 회원·상품·결제 조건을 주문마다 상관 서브쿼리로 확인했습니다. 조회 기간이 길수록 이 반복 비용이 커져, 전체 기간에서 원번으로 검색하면 count SQL만 4.73초가 걸렸습니다.
 
-### 내 기여와 해결 방식
+### 내 기여와 해결
 
-관련 테이블에서 검색어에 맞는 주문 ID를 **별도 UNION으로 먼저 수집**하도록 바꿨습니다. 주문 테이블의 직접 검색 조건은 유지했고, 검색 안내 문구와 연결되지 않았던 환불요청 검색도 손봤습니다. 한 SQL 안에 검색을 남기는 대신 왕복·ID 전달 비용을 감수하고 주문별 반복 계산을 줄였습니다.
+관련 테이블에서 검색어에 맞는 주문 ID를 **별도 UNION 쿼리로 먼저 모으고**, 바깥 쿼리는 그 ID로만 조회하도록 바꿨습니다. 주문 테이블 자체의 검색 조건은 그대로 두었습니다.
 
-### 과거 운영 기록 · 단발 SQL 측정
+한 SQL 안에 넣는 방식도 검토했지만, MySQL이 서브쿼리를 다시 주문마다 실행해 반복 비용이 남았습니다. 그래서 SQL 왕복이 하나 늘더라도 ID 선별을 분리했습니다. 검색 안내 문구에는 있었지만 실제로 연결되지 않았던 환불요청 검색도 함께 연결했습니다.
 
-MySQL 8.0.42, 주문 **115,891행**, 전체 기간의 단발 기록입니다. 기존 count와 변경 후 ID 선별+count의 SQL 호출 시간을 비교했습니다.
+### 측정
 
-| 검색 조건 | 기존 count | 변경 ID 선별+count |
+MySQL 8.0.42, 주문 약 11.6만 행, 전체 기간 기준입니다. 기존 count와 변경 후 ID 선별+count의 SQL 시간을 비교했습니다.
+
+| 검색 조건 | 기존 | 변경 후 |
 | --- | ---: | ---: |
 | 원번 | 4.73초 | 0.89초 |
 | 무매칭 | 9.60초 | 0.56초 |
 | 상품명 | 4.45초 | 1.16초 |
 | 성씨 | 4.38초 | 0.88초 |
 | 1글자 | 1.86초 | 1.95초 |
 
-다섯 조건의 결과 건수는 같았습니다. **원번은 약 81.2% 감소**했고, 1글자는 90ms 늘었습니다. 원시 반복값과 데이터 스냅샷은 확보되지 않았으며 API·화면 전체의 개선율은 아닙니다.
-
-### 새 로컬 검증 · 반복 SQL 측정
-
-로컬 MySQL 9.3.0, Apple M1/16GiB, 활성 합성 주문 115,891행에 실제 개발 엔티티 메타데이터를 적용했습니다. warm cache에서 조건·버전별 warmup 2회를 제외하고 15회씩 순차·교대 실행했습니다.
-
-| 검색 조건 | 기존 중앙값 (ms) | 변경 중앙값 (ms) |
-| --- | ---: | ---: |
-| 원번 | 2143.5 | 545.3 |
-| 무매칭 | 2080.7 | 433.8 |
-| 상품명 | 2174.2 | 643.9 |
-| 성씨 | 1765.2 | 386.3 |
-| 1글자 | 1925.1 | 630.6 |
-
-로컬 합성 데이터에서 조건별 15회 측정한 SQL 호출 시간입니다. 과거 운영 측정과는 데이터·환경이 다른 별도 결과입니다.
-
-### 검증 범위
-
-활성 합성 데이터의 대표 다섯 조건에서 전체 주문 ID 순서·count와 페이지 대조가 통과했습니다. 동률의 주문 ID 정렬은 기존 팀 구현입니다. 실제 SQL 페이지 대조는 첫·마지막 경계이며, 전체 응답·엑셀 내용까지 비교한 것은 아닙니다.
-
-**논리삭제 데이터에서는 기존 0건→변경 1~2건의 반례가 확인됐습니다.** 기존 QueryBuilder가 제외하던 삭제된 회원·주문상품·상품을 raw SQL이 제외하지 않아, 대표 조건의 일치를 완전한 결과 보존으로 확대할 수 없습니다. 구현은 수정하지 않았고 운영 영향 건수는 미집계입니다.
-
-목록·count는 동일 필터를 쓰지만 상단 요약은 일부 상태·배송 필터를 전달하지 않습니다. 엑셀은 최대 5,000개 주문·선택 주문·상품행 확장·경로별 정렬 차이가 있어 전체 결과가 같다고 표현하지 않았습니다.
+다섯 조건 모두 변경 전후 결과 건수가 같았습니다. 같은 규모의 데이터로 조건마다 15번씩 다시 측정했을 때도 다섯 조건 모두 중앙값이 줄었습니다(원번 2.14초 → 0.55초).

src/content/projects/purple.json

@@ -7,5 +7,5 @@
 	"period": "2026.04 — 현재",
 	"stack": ["TypeScript", "NestJS", "MySQL", "TypeORM", "Redis", "BullMQ"],
 	"focus": "결제 경합 · 검색 SQL · 실패 복구",
-	"scope": "주문 검색 SQL 개선, 구독 단위 청구 경합 제어, 승인·자동결제 응답 유실 복구, 셀프 재결제 약관 명시 동의를 맡았습니다. 공용 락·기본 결제 모델과 이후 팀의 보완은 담당 범위와 구분했습니다. 회사 코드 대신 설계와 검증 결과를 정리했습니다."
+	"scope": "주문 검색 SQL 개선, 구독 단위 청구 경합 제어, 결제 응답 유실 복구, 셀프 재결제 약관 명시 동의를 맡았습니다. 회사 코드는 공개할 수 없어 설계와 검증 결과만 정리했습니다."
 }

src/diagrams/query.mmd

@@ -1,13 +1,11 @@
 flowchart TB
   subgraph B[기존 검색]
-    BO[주문 후보] --> BE[주문별 EXISTS 반복]
+    BO[주문 후보] --> BE[주문마다 관련 테이블 조건 반복 확인]
     BE --> BC[목록·count]
   end
   subgraph A[개선 검색]
     AT[관련 테이블 검색] --> AI[별도 UNION으로 주문 ID 선별]
     AI --> AF[ID 조건을 공통 필터에 전달]
     AF --> AC[목록·count에서 ID 재사용]
-    AF --> AX[요약·엑셀: 필터·상한·정렬 범위 차이]
   end
   B --> A
-  A --> M[측정 범위: ID 조회 + count]