KArtSell.Aegis/docs/CURRENT/AEG-X-008_OPENAPI_BASELINE_DECISION.md

AEG-X-008: OpenAPI 기준선 & 릴리스 서명 승인 요청

WBS Item: AEG-X-008
Status: ⏳ IN_PROGRESS → DECISION_REQUIRED
Decision Owner: API Architect, DevOps
Blocks: FE OpenAPI 자동 생성, CI/CD 파이프라인 게이트, API 버전 관리
Impact: API 계약 검증 미완료, 클라이언트 생성 불가, 변경 추적 불명확

---

현재 상태

구현 완료:

• ✅ Host Release 빌드 (0 경고/오류)
• ✅ Architecture tests 17/17 PASS
• ✅ OpenAPI 게이트 로컬 검증: YAML/기준선/후보 검증 0 위반
• ✅ FE 회귀 57 files/150 tests PASS

아직 미결정:

• ⏳ 공식 기준선 승인 (baseline approval)
• ⏳ Gitea Actions 실행 권한
• ⏳ API Architect 릴리스 서명
• ⏳ 변경 추적 정책

알려진 이슈:

• 현재: >500 kB Vite 청크 경고 (AEG-X-002 최적화 후에도 지속)

---

필요한 4가지 결정

1️⃣ 공식 OpenAPI 기준선 (Baseline Snapshot)

결정: 프로덕션 릴리스 시 공식 기준선 정의

Current state:
- src/KArtSell.Host/artifacts/openapi/current_20260813_auto-off.json (기준)
- Generated on: 2026-08-13 14:02 UTC
- Total endpoints: [count required]
- Security schemes: X-KArtSell-User header + Role-based

Approval needed:
✅ 기준선 파일 지정: [ ] (git path)
✅ 버전 정책: [ ] (semantic/date-based)
✅ 승인 프로세스: [ ] (자동/수동)
✅ 기준선 갱신 빈도: [ ] (per-release/quarterly)

Linked Items:
- src/KArtSell.Host/artifacts/openapi/ (저장소)
- .gitea/workflows/openapi-gate.yml (CI 검증)
- docs/DECISIONS/ADR-API-BASELINE-001.md (현재 ADR)

2️⃣ 호환성 정책 (Compatibility Enforcement)

결정: 기준선 vs 후보 비교 규칙

Breaking changes that FAIL the gate:
- Endpoint 제거 또는 경로 변경
- 필수 파라미터 추가 (기존 클라이언트 호환 불가)
- 응답 필드 제거 (기존 클라이언트 parsing 실패)
- Status code 변경 (e.g., 200 → 400)

Non-breaking changes that PASS:
- 선택적 파라미터/필드 추가
- 새로운 status code 추가 (기존 클라이언트 무시 가능)
- 기존 필드 추가 필터/정렬 옵션

Approval needed:
✅ Breaking change 정의: [ ] (완전? 부분?)
✅ Deprecation 정책: [ ] (90일 공지? 기간?)
✅ 주요 버전 전략: [ ] (v1/v2 지원?)
✅ 예외 프로세스: [ ] (CTO 승인 필요?)

Linked Items:
- OpenAPI 3.1 deprecated keyword usage
- Semantic versioning (major.minor.patch)
- Client library generation (auto-off vs auto-on)

3️⃣ Gitea Actions 실행 & 서명 (CI/CD Gate)

결정: 자동 검증과 수동 서명 책임

Current CI/CD state:
- .gitea/workflows/openapi-gate.yml exists
- Runs on: push/PR (currently local only)
- Validation: YAML structure, baseline diff, schema compliance
- Status: No Gitea Actions configured server-side

Decisions needed:
✅ Gitea Actions enabled: [ ] (Yes/No)
✅ 실행 권한: [ ] (auto/manual)
✅ 릴리스 서명자: [ ] (단일/복수?)
✅ 서명 증명: [ ] (commit msg/tag/annotation?)

Approval needed:
✅ API Architect: [ ] (name/email)
✅ API Architect secondary: [ ] (name/email, fallback)
✅ DevOps gate owner: [ ] (name/email)
✅ Approval 보존 기한: [ ] (6개월/1년/영구)

Linked Items:
- .gitea/workflows/openapi-gate.yml (current workflow)
- src/KArtSell.Host/artifacts/openapi/ (baseline location)
- API Architect approval log (where to record?)

4️⃣ 클라이언트 생성 & 배포 (Client Generation)

결정: 공식 OpenAPI 기준선 기반 클라이언트 생성 여부

Option A: Manual (current state)
- Baseline: 수동 승인 → 배포
- Client: 개발자 수동 생성 (openapi-generator, swagger-codegen)
- 사용: 직접 임포트 또는 npm 게시

Option B: Automated
- Baseline: CI gate auto-pass (호환성 규칙 충족)
- Client: 자동 생성 (GitHub Actions / Gitea Actions)
- 배포: NPM registry (npm publish) 또는 S3
- 버전: OpenAPI 버전 태그 동기화

Option C: Hybrid
- Pre-release: 수동 승인 (API Architect sign-off)
- Patch: 자동 생성 (호환성 보장)
- Release: 태그 자동 + NPM publish

Approval needed:
✅ 정책 선택: [ ] (A/B/C)
✅ 클라이언트 저장소: [ ] (npm/@kartsell/client? git-submodule?)
✅ 배포 주기: [ ] (per-release/weekly)
✅ 자동 테스트: [ ] (생성된 클라이언트 검증?)

Linked Items:
- docs/CURRENT/V13-FE-009_ADR_OPENAPI_ZOD_STRATEGY.md (현재 전략)
- openapi-generator / swagger-codegen (도구)
- npm registry vs internal repository

---

제출 형식

승인자는 다음 정보 제공:

1. Baseline Approval

Official Baseline:
  File: [ ] (git path)
  Version: [ ] (vX.Y.Z or YYYY-MM-DD)
  
Update Policy:
  Frequency: [ ] (per-release/quarterly/on-demand)
  Approval Process: [ ] (auto/manual)
  Sign-off Required: [ ] (Yes/No)

2. Compatibility Rules

Breaking Changes:
  Defined: [ ] (comprehensive list)
  Deprecation Period: [ ] (days)
  
Non-Breaking:
  Auto-approved: [ ] (Yes/No)
  Client Notification: [ ] (Yes/No)

3. Gitea Actions & Signing

CI Execution:
  Enabled: [ ] (Yes/No)
  Trigger: [ ] (push/PR/manual)

API Architect:
  Primary: [ ] (name)
  Secondary: [ ] (name)
  Approval Record: [ ] (location)

4. Client Generation Strategy

Option: [ ] (A-Manual / B-Automated / C-Hybrid)

Deployment:
  Repository: [ ] (npm/@kartsell/client / git-submodule)
  Frequency: [ ] (per-release/weekly)
  Validation: [ ] (Yes/No)

---

의존성

• Blocks: FE OpenAPI 클라이언트 생성, CI/CD 완전 자동화
• Related: AEG-X-002 (번들 최적화), 빌드 파이프라인, 버전 관리
• Prerequisite: API Architect, DevOps 팀 협력

---

제출 기한: 2026-08-21 (1주)
승인자: API Architect, DevOps Lead
Escalation: Engineering Director (정책 논쟁 시)