fix: 하네스 제거 및 keycloak 문서 보강

raw/official-docs/google-api-error-format.md

@@ -1 +0,0 @@
-../../vault/20-evidence/official-docs/google-api-error-format.md

raw/official-docs/google-api-error-format.md

@@ -0,0 +1,137 @@
+---
+title: Google AIP-193 — Errors (google.rpc.Status)
+source_type: official-doc
+url: https://google.aip.dev/193
+archive_url:
+status: raw
+confidence: high
+tags: [ca-error-envelope, google, grpc, custom-envelope, rest-api, error-format, aip, official-doc]
+related_projects: [ca-skeleton-operational-contract]
+related_branches: [feature-operational-error-observability-foundation, feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
+created: 2026-05-22
+last_reviewed: 2026-05-27
+---
+
+# Google AIP-193 — Errors (google.rpc.Status)
+
+> Layer: `raw/official-docs/` — Google API Improvement Proposal 193 (Errors). REST 와 gRPC 양쪽에 동일 모델 매핑되는 typed error 표준의 1차 근거.
+> ca-tmpl Topic 4 (Error Envelope) 의 **대안 2 (Google `rpc.Status` / gRPC-derived)** 비교 근거.
+
+## Parent / 활용 branch (필수)
+
+| Branch | 이 자료가 정당화하는 결정 |
+|---|---|
+| [[raw/branch-notes/feature-operational-error-observability-foundation]] | ca-tmpl Topic 4 (Error Envelope) 대안 비교 — `details: Any[]` 다형성 + typed `ErrorInfo`/`RetryInfo`/`LocalizedMessage` 의 표준 근거 |
+| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | boundary 입력 검증 실패 시 `BadRequest` typed detail 옵션의 표준 근거 |
+| [[raw/branch-notes/feature-business-rule-validation-contract]] | business rule 실패의 `ErrorInfo.reason + domain` 기반 머신리더블 식별자 패턴 — RFC 7807 `type` URI 와의 비교 |
+
+## 컨텍스트 / 왜 저장했는지
+
+가장 정교한 typed error model. `details` array 가 `Any` 패킹으로 다형성을 가지며, 그 안에 `ErrorInfo` / `LocalizedMessage` / `Help` / `RetryInfo` / `QuotaFailure` / `BadRequest` 등이 들어감 → ca-tmpl 의 `details: object` 와 비교했을 때 표현력 trade-off 가 명확해짐. gRPC 생태계 (grpc-gateway, gapic generator) 의 사실상 표준.
+
+## 출처 / Source
+
+- 원본 URL: https://google.aip.dev/193
+- 기반: `google.rpc.Status` (protobuf), `google.rpc.Code` enum
+- 아카이브 URL: (미수집)
+- 저자 / 조직: Google (AIP Working Group)
+- 발행일: rolling (AIP-193, current)
+- 마지막 확인일: 2026-05-27
+
+## 핵심 인용 / Key quotes (verbatim)
+
+> [§Status.code] "The `code` field is the status code, which must be the numeric value of one of the elements of the `google.rpc.Code` enum."
+
+> [§Status.message] "The `message` field is a developer-facing, human-readable \"debug message\" which should be in English."
+
+> [§Status.details] "The `details` field allows messages with additional error information to be included in the error response, each packed in a `google.protobuf.Any` message."
+
+> [§Status.details — ErrorInfo requirement] "All error responses must include an `ErrorInfo` within `details`."
+
+> [§Status.details — standard payloads] "BadRequest", "PreconditionFailure", "ErrorInfo", "LocalizedMessage", "Help" — 표준 detail payload 로 명시 (RetryInfo, QuotaFailure 등 추가 표준 payload 는 별도 `error_details.proto` 정의)
+
+## Claims Extracted / 추출된 주장
+
+| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
+|---|---|---|---|---|---|
+| GOOG-ERR-C1 | `code` 필드는 **`google.rpc.Code` enum 의 정수 값** 이어야 함 (must) | [§Status.code] "The `code` field is the status code, which must be the numeric value of one of the elements of the `google.rpc.Code` enum." | `official-vendor-doc` | Google API / gRPC `Status` 호환 응답 | HTTP status code 와 1:1 매핑이라는 뜻은 아님 — `google.rpc.Code` 는 별도 enum (NOT_FOUND=5 등) |
+| GOOG-ERR-C2 | `message` 필드는 **개발자 대상의 영어 debug message** (should) — end-user 표시용 아님 | [§Status.message] "The `message` field is a developer-facing, human-readable \"debug message\" which should be in English." | `official-vendor-doc` | API 응답의 message 필드 표시 정책 | end-user 메시지가 별도 `LocalizedMessage` 로 강제된다는 뜻은 아님 — 본 인용은 `message` 자체의 의도만 정의 |
+| GOOG-ERR-C3 | `details` 필드는 **`google.protobuf.Any` 로 패킹된** 추가 정보를 array 로 포함 (다형성) | [§Status.details] "The `details` field allows messages with additional error information to be included in the error response, each packed in a `google.protobuf.Any` message." | `official-vendor-doc` | typed error details 표현 | client 가 `Any` 디코딩 비용 없이 처리 가능하다는 뜻은 아님 — `@type` URL 기반 해석 필요 |
+| GOOG-ERR-C4 | **모든 error 응답** 은 `details` 안에 **`ErrorInfo` 를 반드시 포함** 해야 함 (must) | [§Status.details — ErrorInfo requirement] "All error responses must include an `ErrorInfo` within `details`." | `official-vendor-doc` | AIP-193 준수 API 의 모든 error 응답 | `ErrorInfo.reason` 값 카탈로그가 spec 에 고정되어 있다는 뜻은 아님 — domain 별 자유 정의 |
+| GOOG-ERR-C5 | 표준 detail payload 로 `BadRequest`, `PreconditionFailure`, `ErrorInfo`, `LocalizedMessage`, `Help` 등이 정의됨 | [§Status.details — standard payloads] "BadRequest", "PreconditionFailure", "ErrorInfo", "LocalizedMessage", "Help" | `official-vendor-doc` | typed details 카탈로그 사용 | `RetryInfo` / `QuotaFailure` 가 본 AIP-193 페이지에 직접 인용되었다는 뜻은 아님 — `error_details.proto` 의 추가 payload (별도 확인) |
+
+## Usage Boundaries / 적용 경계
+
+- **이 자료가 직접 증명하는 것**:
+  - `GOOG-ERR-C1`: `code` 가 `google.rpc.Code` enum 정수임 (HTTP status code 와 별개)
+  - `GOOG-ERR-C2`: `message` 의 developer-facing English 의도
+  - `GOOG-ERR-C3`: `details: Any[]` 다형성 구조
+  - `GOOG-ERR-C4`: 모든 error 응답에 `ErrorInfo` 필수
+  - `GOOG-ERR-C5`: 표준 detail payload 5종 (BadRequest, PreconditionFailure, ErrorInfo, LocalizedMessage, Help) 의 존재
+- **이 자료가 증명하지 않는 것**:
+  - `RetryInfo.retry_delay` 가 client 의 표준 재시도 정책으로 강제됨 (별도 `error_details.proto` 참조 필요)
+  - REST mapping 의 정확한 JSON shape (`error.code` 가 정수 vs 문자열 enum name 인지 — AIP-193 본문은 다른 § 에서 정의)
+  - HTTP status code 와 `google.rpc.Code` 간 매핑 표 (별도 AIP — AIP-194 또는 grpc-status-codes-to-http 표)
+  - `@type` 의 정확한 URL prefix 정책 (`type.googleapis.com` 외 cusotm prefix 허용 여부)
+- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
+  - ca-tmpl 의 `retryable: boolean` 을 `RetryInfo.retry_delay` 로 대체 시 client SDK 영향
+  - `details` 다형성 채택 시 client 가 알아야 할 `@type` 카탈로그의 운영 비용
+  - LocalizedMessage 채택 시 i18n 파이프라인 (`message` vs `LocalizedMessage.message` 분리) 의 구현 비용
+
+## 메모 / Notes (내 프로젝트 해석)
+
+> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
+
+- 응답 shape 예시 (REST 매핑, 해석):
+  ```json
+  {
+    "error": {
+      "code": 404,
+      "message": "Resource 'projects/foo' not found.",
+      "status": "NOT_FOUND",
+      "details": [
+        {
+          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+          "reason": "RESOURCE_NOT_FOUND",
+          "domain": "googleapis.com",
+          "metadata": {"resource": "projects/foo"}
+        },
+        {
+          "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
+          "locale": "ko-KR",
+          "message": "..."
+        }
+      ]
+    }
+  }
+  ```
+- **장점 (해석)**:
+  - typed details — `RetryInfo` 로 retryable + delay 까지 표준화, ca-tmpl 의 `retryable` boolean 보다 풍부
+  - `LocalizedMessage` 로 i18n 이 spec 수준에서 정의됨
+  - REST/gRPC 일관 — bilingual API 에 유리
+  - `ErrorInfo.reason + domain` 이 RFC 7807 의 `type` URI 역할
+- **단점 (해석)**:
+  - 복잡도가 매우 높음. `Any` 디코딩이 client 에 부담
+  - 가벼운 CRUD API 에는 과함
+  - 표준 detail 타입 카탈로그를 알아야 효용 발휘
+- **ca-tmpl custom envelope 와의 차이 (해석)**:
+  - ca-tmpl: `retryable: boolean`, Google: `RetryInfo { retry_delay }`. 후자가 client 에 더 actionable
+  - ca-tmpl: 단일 `details: object`, Google: `details: Any[]` 다형성
+  - ca-tmpl: `category: string`, Google: 정수 `code` + 문자열 `status` enum
+- **표준 준수 / lock-in / client 호환성 (해석)**:
+  - Google 진영의 사실상 표준. 외부 표준은 아니지만 gRPC 생태계 전체가 따라감 → grpc-gateway, gapic generator 등
+  - lock-in: protobuf/grpc 생태계와 강결합
+- **localization / i18n 지원 여부 (해석)**:
+  - `LocalizedMessage` detail 로 1급 지원. 5개 대안 중 가장 명시적
+
+## Related / 관련
+
+- 같은 주제 다른 official-doc / company-tech-blog:
+  - [[raw/official-docs/spring-problem-detail]] (대안 1 구현체 — RFC 7807/9457)
+  - [[raw/official-docs/json-api-errors-spec]] (대안 3 — JSON:API errors)
+  - [[raw/official-docs/graphql-errors-spec]] (대안 4 — GraphQL errors)
+  - [[raw/company-tech-blogs/stripe-error-format]] (대안 5 — Stripe custom envelope)
+- canonical contract 섹션:
+  - [[raw/project-notes/ca-skeleton-operational-contract]] §3 Structured API Response Contract, §6 Operational Error Category
+- 본 source 의 위치: ca-tmpl Topic 4 — Error Envelope, **대안 2: Google rpc.Status (gRPC-derived)**
+- 인용하는 wiki: (미작성)