[codex] Document release compatibility

[midagedev]

Summary

• add a public compatibility matrix for Billtap supported and unsupported Stripe-like behavior
• add the v0.1.0 source-first release process
• link release and compatibility docs from README/docs index/changelog
• correct the API contract so it matches the implemented release-compatible surface

Validation

• npm ci
• git diff --check
• go test ./...
• npm run typecheck

Notes

• Keeps the existing Z.ai PR review workflow unchanged.
• Does not choose or add a LICENSE file.

[claude]

APPROVE

Summary

이 PR은 Billtap v0.1.0 공개 릴리스를 위한 호환성 매트릭스와 릴리스 프로세스 문서를 추가하고, API 명세를 실제 구현된 surface에 맞춰 정확하게 수정합니다. documentation-only 변경으로 billing state, webhook reliability, safety에 영향을 주지 않습니다.

주요 변경 사항

1. docs/COMPATIBILITY.md 추가 (새 파일)

https://github.com/midagedev/billtap/blob/codex/release-compat-docs/docs/COMPATIBILITY.md

명확한 호환성 레벨 정의와 지원되는 Stripe-like API subset을 문서화합니다:

• Compatibility levels: Supported, Billtap-specific, Partial, Unsupported
• Supported Stripe-like APIs: customer, product, price, checkout session, billing portal session, subscription (GET/UPDATE/DELETE), invoice (GET/preview), payment intent (GET), payment method (GET), webhook endpoint, event
• Billtap APIs: /api/* 하위의 체크아웃, 포털, 대시보드, 웹훅, fixture, scenario, boundary control endpoints
• Webhook compatibility: checkout.session.completed, customer.subscription.*, invoice.*, payment_intent.* 이벤트 타입 지원
• Unsupported behavior: 실제 결제 처리, full Stripe API, real card data, request idempotency-key semantics, Connect, tax, coupons 등

2. docs/RELEASE.md 추가 (새 파일)

https://github.com/midagedev/billtap/blob/codex/release-compat-docs/docs/RELEASE.md

v0.1.0 source-first 릴리스 프로세스를 정의합니다:

• Release goals: Billtap이 local/CI billing sandbox이지 real payment processor가 아님을 명확히 함
• Required public statements: 모든 릴리스 노트에 "실제 결제 처리 불가", "real card data 미접수", "full Stripe 호환 아님"을 명시하도록 강제
• Release flow: 브랜치 생성 → 로컬 검증 → PR → merge → tag → GitHub release
• Local verification: npm ci, go test, npm run typecheck/build, Docker build, scenario smoke
• Release blockers: unsupported behavior를 지원한다고 암시하는 문서, real payment processing 암시, credential/customer data 노출 시 차단

3. specs/000-product/contracts/api.md 수정

https://github.com/midagedev/billtap/blob/codex/release-compat-docs/specs/000-product/contracts/api.md

API 명세를 실제 구현과 일치하도록 수정합니다:

• 추가된 endpoints: GET /v1/products/search, GET /v1/checkout/sessions, POST /v1/invoices/create_preview, GET /v1/payment_methods, POST /v1/billing_portal/sessions
• 제거된 endpoints: POST /v1/subscriptions, POST /v1/invoices/{id}/finalize|pay|void, POST /v1/payment_intents, POST /v1/payment_intents/{id}/confirm
• 명시적 제약: direct invoice finalize/pay/void, direct payment intent create/confirm은 현재 release-compatible subset이 아님을 명시

4. README, CHANGELOG, docs index 수정

• README.md: COMPATIBILITY.md과 RELEASE.md 링크 추가, supported surface 경고 문구 추가
• CHANGELOG.md: unreleased에 compatibility/release docs 추가 내용 기록
• docs/README.md: COMPATIBILITY.md, RELEASE.md index에 추가

검증

문서의 주요 claim이 실제 구현과 일치하는지 확인했습니다:

• products/search endpoint가 internal/api/api.go에 구현됨
• billing_portal/sessions endpoint가 internal/api/api.go에 구현됨
• Production boundary 문서의 no-real-payment, no-real-card-data, relay-mode masking 제약이 COMPATIBILITY.md의 unsupported behavior와 일치

문서화 평가

장점

1. 명확한 scope 정의: Compatibility levels를 도입하여 "Supported", "Billtap-specific", "Partial", "Unsupported"의 차이를 명확히 합니다. 이는 사용자가 Billtap을 Stripe clone으로 오해하는 것을 방지합니다.
2. 실제 구현과의 일치: API contract에서 실제로 구현되지 않은 endpoint들(POST /v1/subscriptions, invoice finalize/pay/void 등)을 제거하여 문서가 구현과 일치하도록 수정했습니다. 이는 spec-driven development 원칙을 준수합니다.
3. Safety 강조: 모든 릴리스 노트에 "실제 결제 처리 불가"를 명시하도록 강제하는 규칙을 추가하여, Billtap이 실제 payment path로 오용되는 것을 방지합니다.
4. Fixture-backed approach: 호환성 주장은 fixture, test, 문서가 있을 때만 추가하도록 규칙을 정의하여 future-proof하게 만듭니다.

Suggestion (비차단)

1. Versioning strategy: 현재 문서는 v0.1.0을 언급하지만, 향후 버전에서 compatibility가 어떻게 evolve할지에 대한 가이드라인이 COMPATIBILITY.md의 "Compatibility Change Rules"에 이미 포함되어 있습니다. 이는 잘 작성되었습니다.
2. Verification automation: docs/RELEASE.md의 manual smoke 목록이 상세하지만, CI에서 자동으로 검증할 수 있는 항목(npm ci, go test, npm run typecheck)과 수동 검증이 필요한 항목이 명확히 구분되어 있습니다. 이는 적절한 균형입니다.

결론

이 PR은 Billtap의 공개 릴리스를 위해 필수적인 호환성과 릴리스 프로세스 문서를 추가하고, API 명세를 실제 구현과 일치하도록 수정합니다. 변경 사항은 documentation-only이며 billing state correctness, webhook reliability, safety에 영향을 주지 않습니다. Release blockers에 명시된 criteria를 충족하며 APPROVE합니다.

_{Reviewed by Z.ai GLM via Claude Code Action}