docs(browser-transfer): presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 적는다
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는 2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기 Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데 서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현" 이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야 짝이 아님을 안다. 고친 방법(리뷰 D1 (다)): - server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은 구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현" 으로 고치고 짝 아님 안내를 머리에 둔다. - presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned 다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다. - 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver POST /v1/files)를 적는다. - docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로 비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다. 위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이 커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은 백엔드 repo 몫이라 하지 않았다. 검증: - verify:documentation PASS_SCOPED - check:optional-recipes:source PASS (file-transfer 56,084/57,800) Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
This commit is contained in:
@@ -196,7 +196,7 @@
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."],
|
||||
"bundleBudgetGzipBytes": 57800,
|
||||
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.",
|
||||
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation. The paired backend template has no presigned or direct multipart server (removed 2026-09-25): with it, upload through its Fileserver (POST /v1/files).",
|
||||
"removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."],
|
||||
"serverStatePolicy": "query-cache-metadata-only"
|
||||
},
|
||||
|
||||
@@ -11,6 +11,15 @@ authorization owner는 아직 조합하지 않는다. 이 개별 runtime은
|
||||
표처럼 다른 상태다. 어느 경로도 임의의 URL이나 object key를 application caller가
|
||||
직접 전달하는 범용 HTTP facade가 아니다.
|
||||
|
||||
> **짝 백엔드와 맞지 않는다(2026-11-03 리뷰 01-01).** 이 문서의 presigned·resumable
|
||||
> 프로토콜(`PRESIGNED_MULTIPART_V1`)을 받는 서버가 짝 백엔드 템플릿에는 없다. 짝 백엔드는
|
||||
> 2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일을 자기 Fileserver로 직접
|
||||
> 받는다(`POST /v1/files` multipart 한 번, `POST /v1/files:raw`, tus `/v1/uploads`). 두 템플릿을
|
||||
> 그대로 쓰는 업로드는 그 Fileserver로 올리는 것이다(`docs/manual/02-decision-tables.md`
|
||||
> 「파일 업로드」). 이 문서의 경로는 제품 backend가 같은 BFF 계약을 직접 만들 때 쓴다
|
||||
> ([`server-file-capability-infrastructure.md`](./server-file-capability-infrastructure.md)).
|
||||
> presigned 다운로드와 private Image CDN descriptor 발급 서버도 같은 이유로 짝 백엔드에 없다.
|
||||
|
||||
## 0. 현재 구현과 목표 상태
|
||||
|
||||
이 문서에서 “설계됨”, “reference source가 있음”, “제품에 조합됨”과 “target
|
||||
|
||||
@@ -1,10 +1,20 @@
|
||||
# Server file capability infrastructure handoff
|
||||
|
||||
- 상태: 설계 완료, 서버 구현 대기
|
||||
- 상태: 설계 완료. 짝 백엔드 템플릿은 구현하지 않음(2026-09-25 제거)
|
||||
- 목표 상태: `AVAILABLE_NOT_COMPOSED`
|
||||
- 대상: 이후 서버 template 또는 제품 backend에서 구현할 공통 file capability
|
||||
- 대상: 제품 backend가 직접 구현할 공통 file capability
|
||||
- 비대상: 제품 domain, 제품 use case, HTTP route/controller, provider 선택
|
||||
- 기준일: 2026-07-28
|
||||
- 기준일: 2026-07-28 (상태 줄은 2026-11-04에 고침)
|
||||
|
||||
> **짝 백엔드와 맞지 않는다.** 짝 백엔드 템플릿(`clean-architecture-backend-template`)은
|
||||
> 2026-09-25에 presigned·direct multipart 코드를 지웠다(그 repo의
|
||||
> `docs/storage-capability-boundary.md`, `docs/capability-status.md` 「제거된 코드」).
|
||||
> 그래서 이 문서의 server port와 프론트 `PRESIGNED_MULTIPART_V1` 레시피를 받는 서버가
|
||||
> 짝 백엔드에는 없다. 짝 백엔드는 파일을 자기 Fileserver가 직접 받는다
|
||||
> (`POST /v1/files` multipart 한 번, `POST /v1/files:raw`, tus `/v1/uploads`).
|
||||
> 두 템플릿을 그대로 쓰는 업로드는 짝 백엔드 Fileserver로 올리는 것이다. 고르는 기준은
|
||||
> `docs/manual/02-decision-tables.md` 「파일 업로드」에 있다. 이 문서는 제품 backend가
|
||||
> presigned 경로를 직접 만들기로 할 때의 설계로 남긴다.
|
||||
|
||||
이 문서는 frontend에 준비된 File/Blob/picker/download capability와 이후 연결할
|
||||
서버측 기반을 정의한다. 서버는 object storage, multipart, integrity,
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 02. 결정표
|
||||
|
||||
기능을 만들며 고르는 여섯 가지다. 각 절은 같은 순서로 쓴다.
|
||||
기능을 만들며 고르는 일곱 가지다. 각 절은 같은 순서로 쓴다.
|
||||
|
||||
```text
|
||||
무엇을 고르나 → 선택지 비교 → 고르는 기준 → 어디에 적나 → 틀리면 무엇이 잡나
|
||||
@@ -224,3 +224,28 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|
||||
- 템플릿은 데이터를 가져오지 않는다. 데이터와 동작은 props로 받는다. 템플릿 파일이 application·어댑터를 import하면 `check:architecture`가 `page-templates-own-layout-only`로 막는다.
|
||||
- 디자인 시스템 하위 경로를 import하면 `design-system-is-reached-through-its-index`로 막는다.
|
||||
- 템플릿을 잘못 고른 것은 검사가 잡지 못한다.
|
||||
|
||||
---
|
||||
|
||||
## 7. 파일 업로드
|
||||
|
||||
**무엇을 고르나**: 기능이 파일을 서버에 올리는 경로.
|
||||
|
||||
**두 템플릿을 짝으로 쓰면 presigned 레시피는 맞지 않는다.**
|
||||
|
||||
- 프론트 `src/adapters/browser-transfer/`의 resumable upload는 `PRESIGNED_MULTIPART_V1` 서버를 가정한다. 브라우저가 object store에 바로 PUT하는 방식이다.
|
||||
- 짝 백엔드는 2026-09-25에 그 서버 코드(presigned·direct multipart)를 지웠다. 파일은 자기 Fileserver가 직접 받는다(`clean-architecture-backend-template/docs/fileserver/http-contract.md`: `POST /v1/files` multipart 한 번, `POST /v1/files:raw`, tus `/v1/uploads`).
|
||||
- 이 레시피를 짝 백엔드에 그대로 붙이면 첫 응답부터 읽지 못한다. 백엔드는 응답을 Envelope로 감싸고, 레시피의 control plane은 감싸지 않은 DTO를 기대한다.
|
||||
|
||||
| | 짝 백엔드 Fileserver | presigned resumable 레시피 |
|
||||
|---|---|---|
|
||||
| 짝 백엔드 | 있다 | 서버가 없다 |
|
||||
| 끊긴 뒤 | multipart 한 번은 처음부터. tus는 이어 간다 | part 단위로 이어 간다 |
|
||||
| 바이트 경로 | 앱 서버를 지난다 | 브라우저 → object store |
|
||||
|
||||
**기준**
|
||||
|
||||
- 짝 백엔드를 그대로 쓰면 Fileserver로 올린다.
|
||||
- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/architecture/server-file-capability-infrastructure.md`)을 직접 만들 때만 쓴다.
|
||||
|
||||
**틀리면**: 검사가 잡지 못한다. 레시피와 짝 백엔드를 함께 조립하는 테스트는 없다.
|
||||
|
||||
@@ -27,7 +27,7 @@ README (이 문서)
|
||||
| 문서 | 내용 |
|
||||
|---|---|
|
||||
| [`01-add-a-feature.md`](01-add-a-feature.md) | 0~11단계. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것, 쓸 스킬 |
|
||||
| [`02-decision-tables.md`](02-decision-tables.md) | context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿 |
|
||||
| [`02-decision-tables.md`](02-decision-tables.md) | context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드 |
|
||||
| [`03-outside-feature-folder.md`](03-outside-feature-folder.md) | 기능 폴더 밖 파일. 생성 명령이 하는 것과 사람이 하는 것 |
|
||||
| [`reference/create-feature.md`](reference/create-feature.md) | `create:feature`의 인자, 만드는 파일, 거부 조건, 출력 |
|
||||
| [`reference/global-ids.md`](reference/global-ids.md) | 전역 ID 종류, 생성 명령이 만드는 값, 유일성 검사 |
|
||||
|
||||
Reference in New Issue
Block a user