donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
7bcb54c4647589f64c703fd0de34b9c9ea759661
llm-wiki/raw/branch-notes/feature-frontend-multi-protocol-api-transport-contract.md
T
DongHyeonka 7bcb54c464 docs(branch-spec): feature-frontend-binary-file-io-store-contract 채움 
MDN 근거 3건 수집 후 결정 7개를 근거 기반으로 확정하고 §구현 가이드
4개 sub-section 을 채웠다. 조사에서 기존 계약 2건의 사실 오류가 나왔다.

- EVICTION_SCOPE_DRIFT: 브라우저 eviction 은 origin 전량 삭제이므로
  FE-REG-STORAGE.evictionOrder 는 애플리케이션 주도 정리에만 유효
- CACHE_STORAGE_CONSTRAINT_DRIFT: Cache Storage 는 SW 전용이 아니다
  (Window.caches 접근 가능). FE-D027 의 제한은 정책이지 플랫폼 제약이 아님
- NO_GROUND_TRUTH: ca-tmpl 은 backend 전용이라 이 branch 에 미적용
- CAPABILITY_NAME_COLLISION: ca-tmpl capabilities.yaml 과 다른 개념

신규 raw: mdn-storage-quotas-eviction-persistence,
mdn-file-system-access-opfs, mdn-object-url-cache-storage
6개 신규 branch-note 전부에 governing_docs 추가.
2026-07-28 15:24:19 +09:00

14 KiB
Raw Blame History

title, source_type, status, id, kind, project, work_item, inherits, refines, overrides, depends_on, imports, delegates, accepts_delegations, contract_packet, branch, parent_branch, related_projects, governing_docs, tags, created, target_merge, status_label
title source_type status id kind project work_item inherits refines overrides depends_on imports delegates accepts_delegations contract_packet branch parent_branch related_projects governing_docs tags created target_merge status_label
branch / feature-frontend-multi-protocol-api-transport-contract branch-note raw BR-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-031 project-work-item ca-skeleton-frontend-operational-contract WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-031
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-PROTOCOL-001@1
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-VALIDATION-001@1
WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-005
WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-006
WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-007
FE-GATE-030@1
FE-OC-006@1
FE-OC-007@1
FE-OC-008@1
FLOW-FE-RESP-004@1
FLOW-FE-RESP-005@1
FLOW-FE-RESP-006@1
DELEG-FE-010@1
1 feature-frontend-multi-protocol-api-transport-contract
ca-skeleton-frontend
ca-skeleton
raw/project-notes/ca-skeleton-frontend-operational-contract.md
branch
ca-skeleton-frontend
api
protocol
graphql
grpc-web
2026-07-28 in-progress

branch: feature-frontend-multi-protocol-api-transport-contract

부모 (필수)

형제 branch (같은 부모, 이번 확장에서 함께 생성):

브랜치 계약 패킷

  • 생성 시 프로젝트 개정: 2
  • 패킷 스키마: contract_packet: 1
  • 완료 조건: protocol별 성공/실패 정규화와 gateway fallback fixture가 통과한다

상속한 프로젝트 결정

Decision Ref Project Summary Branch Application Source
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1 신규 runtime capability 6종은 FE-REG-CAPABILITY flag로 default OFF이며 활성화는 owner·gate·runbook을 동반한다 CAP_FE_ALT_PROTOCOL 을 이 branch 가 소유하고 default OFF 로 유지한다 raw/project-notes/ca-skeleton-frontend-operational-contract
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-PROTOCOL-001@1 transport default는 REST이고 GraphQL·gRPC-Web·Connect-Web은 FE-REG-API의 protocol 필드로 opt-in하며 미지원 환경은 REST gateway로 fallback한다 FE-REG-API.protocol 값에 따른 adapter 선택 규칙에 적용한다 raw/project-notes/ca-skeleton-frontend-operational-contract
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-VALIDATION-001@1 boundary runtime validation은 Zod schema로 수행한다 codec 디코드 결과도 예외 없이 스키마 검증을 거친다 raw/project-notes/ca-skeleton-frontend-operational-contract

브랜치 지역 결정

Decision ID Decision Relation Supporting Claims Status
D1 이 branch 는 신규 port 를 정의하지 않는다. GraphQL·gRPC-Web·Connect-Web adapter 는 기존 ResourceQueryPort/ResourceCommandPort 를 구현한다 refines DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-PROTOCOL-001@1 근거 raw 미수집 (FE-Q-011) proposed
D2 transport status 만으로 성공을 판정하지 않는다. protocol 별 성공 판정 함수가 별도로 존재한다 local 근거 raw 미수집 (FE-Q-011) proposed
D3 GraphQL 200 OK + errors[] 는 부분 성공이 아니라 PARTIAL_RESULT_FAILURE 로 정규화한다 local 근거 raw 미수집 (FE-Q-011) proposed

선언한 예외

해당 없음.

가져온 artifact 계약

Artifact Ref Owner Producer Schema Ref

가져온 프로젝트 계약

Ref Owner 요약 Branch 적용
FE-GATE-030@1 raw/project-notes/ca-skeleton-frontend-operational-contract protocol 별 성공/실패 정규화 fixture 가 실패하면 merge 를 MUST 차단 이 branch 가 owner 로서 fixture 와 report 를 산출
FE-OC-006@1 raw/branch-notes/feature-api-client-response-envelope-contract 모든 HTTP는 shared client를 MUST 통과하고 timeout·abort·response parsing을 page에서 구현하면 안 됨 protocol adapter 도 shared client 위에 얹힌다
FE-OC-007@1 raw/branch-notes/feature-runtime-schema-validation-contract JSON envelope와 payload는 boundary에서 runtime schema를 MUST 통과 디코드 후 검증을 DELEG-FE-010 으로 위임
FE-OC-008@1 raw/branch-notes/feature-frontend-error-classification-boundary-contract 모든 failure는 stable frontend error kind로 MUST 정규화하고 raw body·stack을 UI에 노출하면 안 됨 protocol 실패 3종의 정규화 대상

수신한 위임

없음. 이 branch 는 DELEG-FE-010 의 delegator 다.

가져온 흐름 단계

Stage Ref Order Owner Input Action Output
FLOW-FE-RESP-004@1 4 feature-runtime-schema-validation-contract unvalidated JSON envelope 공유 스키마 검증 discriminated envelope
FLOW-FE-RESP-005@1 5 feature-runtime-schema-validation-contract discriminated envelope success/failure 분기 검증 분기 확정 envelope
FLOW-FE-RESP-006@1 6 feature-runtime-schema-validation-contract 분기 확정 envelope payload per-operation 스키마 검증 검증된 payload(deep clone)

목표

GraphQL·gRPC-Web·Connect-Web adapter 가 기존 ResourceQueryPort/ResourceCommandPort 를 구현하도록 고정하고, protocol 별 성공/실패 판정을 정규화된 failure 로 매핑한다. 이 계약이 없으면 200 OK + errors[] 응답이 success 로 반환되어 빈 화면이 정상처럼 보이고, HTTP 200 + grpc-status: 13 이 성공으로 처리된다.

  • 이슈:
  • PR:

범위

포함 범위

  • FE-REG-API 의 protocol·operationRef·transferMode 소비와 adapter 선택
  • GraphQL codec — persisted-document ID 기반 요청, errors[] 처리
  • gRPC-Web·Connect-Web codec — protobuf 인코딩/디코딩, grpc-status ↔ 정규화 kind 매핑
  • REST gateway fallback (disabledFallback: degraded-alternative)
  • 신규 실패 3종 정규화: PROTOCOL_STATUS_MISMATCH·CODEC_DECODE_FAILURE·PARTIAL_RESULT_FAILURE
  • CAP_FE_ALT_PROTOCOL capability 행 소유

제외 범위

근거 (필수, 최소 1개+)

Source 정당화하는 결정
[[docs/superpowers/specs/2026-07-28-ca-skeleton-frontend-runtime-adapter-features-design]] §5.2·§6.2 신규 port 0개 결론과 FE-REG-API 확장
raw/official-docs/zod-runtime-schema-validation-official 디코드 후 검증의 상위 근거
raw/project-notes/ca-skeleton-frontend-operational-contract §2.1.4·§7.3·§8.2 응답 흐름 8단계와 실패 정규화

근거 등급 경계: FE-D031(protocol opt-in)의 rationale 은 project-local default, 외부 source claim 아님 이다. gRPC-Web·Connect 프로토콜 명세와 GraphQL over HTTP 규약을 다룬 raw 자료는 이 repo 에 없다(FE-Q-011). 특히 grpc-status ↔ 정규화 kind 매핑표는 명세 확인 없이 확정할 수 없으므로 §구현 가이드를 비워 둔다.

TODO

  • FE-REG-API.protocol 별 adapter 선택 규칙 확정 — 등급: planned
  • protocol 별 성공 판정 함수 분리 — 등급: planned
  • GraphQL errors[] → PARTIAL_RESULT_FAILURE 매핑 — 등급: planned
  • grpc-status → 정규화 kind 매핑표 (명세 확인 후) — 등급: planned
  • codec decode 실패 → CODEC_DECODE_FAILURE — 등급: planned
  • REST gateway fallback 경로 — 등급: planned
  • FE-GATE-030 protocol mapping report 산출 — 등급: planned

진행 중 메모

이 branch 의 가치는 "무엇을 추가했는가" 보다 "무엇을 추가하지 않았는가" 에 있다. 신규 port 0개라는 결론이 유지되어야 backend 가 REST 에서 gRPC 로 옮겨갈 때 use case 를 다시 쓰지 않는다. 리뷰 시 port 가 늘어나 있으면 그 자체가 회귀 신호다.

결정 사항

  • 2026-07-28: 신규 port 0개 / 이유: 프로토콜은 registry 데이터이지 타입이 아니며, port 로 새면 dependency inversion 이 무너짐 / 검토한 대안: GraphQLPort·GrpcWebPort 분리 / 근거: 설계문서 §5.2
  • 2026-07-28: 200 + errors[] 를 실패로 정규화 / 이유: 부분 데이터를 성공으로 취급하면 빈 화면이 정상처럼 보임 / 검토한 대안: 부분 성공 상태 신설 / 근거: 근거 raw 미수집, project-local 판단 (FE-Q-011)

결정-근거 매핑

Decision ID Decision 선택 조건 (언제 이 결정 / 언제 대안) Supporting Claims Evidence Strength Open Risk
D1 신규 port 0개 항상. 프로토콜 고유 기능(gRPC 양방향 스트림 등)이 use case 레벨에 필요해지면 재검토 없음 — FE-Q-011 project decision 추상화가 새는 프로토콜 기능이 있을 수 있음
D2 protocol 별 성공 판정 함수 분리 항상 없음 — FE-Q-011 project-local default 판정 로직이 프로토콜마다 흩어져 중복될 수 있음
D3 200 + errors[] → PARTIAL_RESULT_FAILURE 항상. 제품이 부분 데이터를 의미 있게 쓸 수 있으면 재검토 없음 — FE-Q-011 project-local default 일부 필드만 실패한 응답을 통째로 버리게 됨

구현 가이드

근거 raw 자료(FE-Q-011, FE-Q-013) 수집 전까지 비워 둔다. grpc-status 코드별 매핑과 Connect 의 error 표현은 명세를 읽지 않고 쓸 수 없으며, 추측으로 쓰면 전부 UNSUPPORTED_IMPL_DECISION 이다.

엣지·실패·의존

검증해야 할 주장

Claim Why uncertain How to verify Status
200 OK + errors[] 가 success 로 반환되지 않는다 GraphQL 클라이언트 기본 동작이 부분 성공 negative fixture — 해당 응답 주입 후 PARTIAL_RESULT_FAILURE 확인 planned
HTTP 200 + grpc-status: 13 이 실패로 정규화된다 transport status 만 보는 구현이 흔함 negative fixture — trailer 주입 후 kind 확인 planned
protocol adapter 가 신규 port 를 만들지 않았다 구현 중 편의로 port 가 늘어나기 쉬움 architecture fixture — application/ports/ 파일 수가 늘지 않았는지 planned
REST gateway fallback 이 실제로 도달한다 capability OFF 경로가 테스트에서 빠지기 쉬움 integration test — flag OFF 로 같은 operation 호출 planned
codec 산출물이 반드시 스키마 검증을 거친다 디코드가 이미 타입을 보장한다고 착각하기 쉬움 negative fixture — 스키마 위반 디코드 결과 주입 후 SCHEMA_MISMATCH planned
grpc-status 매핑표가 명세와 일치한다 명세 미확인 상태 FE-Q-011 수집 후 명세 대조 needs-confirmation

관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)

미생성.

마주친 문제

없음.

묶음 (이 branch에서 파생된 자료)

Sub-branches (세부 작업)

아직 없음.

오류 기록 (이 branch 작업 중 발생)

아직 없음.

면접 준비 (이 작업에서 나올 수 있는 면접 질문)

아직 없음.

강의 (이 작업을 위해 학습한 강의)

아직 없음.

job-posting tie-ins (이 작업에서 파생된 글감)

아직 없음.

관련 일일 노트

  • 아직 없음

완료 후 정리

  • PR 링크:
  • 리뷰 메모:
  • 머지 결과 / 배포 환경:
  • wiki 추출 대상 (verified만, wiki/projects/로만 추출):
    • actually-implemented 항목: 없음
    • locally-verified 항목: 없음
    • prod-verified 항목: 없음
  • 추출하지 않을 항목: 현재 전 항목 planned
Reference in New Issue View Git Blame Copy Permalink