Files
clean-architecture-frontend…/docs
DongHyeonka c5f87aaef5 fix(browser-transfer): part 발급 401/403을 NONE으로 낸다 (0929/01-01)
문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를
남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서
toUploadAction 한 곳에서 가를 수 없었다.

고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의
uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을
안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로
만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역
(toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개
타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는
곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다.
PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새
capability를 받는다(지난 수정의 보존 조건).

버린 대안:
- 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야
  한다.
- code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다.
  PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다.
- 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라
  [계약]이다. 같은 일을 기존 값으로 할 수 있다.
- 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개
  BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고,
  WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시
  만들면 말없이 표시가 사라진다.
- control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히
  RESUME을 낸다.

위험·한계:
- BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림
  화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다.
- control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지
  않는다. 재인증 전에는 결과가 같기 때문이다.
- 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다.
- 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다.
- file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100).

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중
  BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403
  1건은 수정 전에도 RESUME으로 통과(보존 조건 고정).
- GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다.
- 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새
  테스트, 기존 01-05 표 테스트)이 실패한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
  image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼
  파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
  check-optional-recipes(source) file-transfer 56053/56100.
- 미실행: check:architecture(pnpm 필요).

Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
2026-11-03 00:36:28 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md verify:documentation (FE-GATE-017)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다