Fix invoice preview SDK schema

[midagedev]

Summary

• Fill Stripe Invoice default fields on /v1/invoices/create_preview responses so generated SDK models can deserialize preview invoices.
• Return invoice/subscription discounts as Stripe-style arrays instead of list envelopes.
• Add regression assertions for preview schema defaults, period fields, tax defaults, status transitions, and discount arrays.

Verification

• go test ./internal/api
• go test ./...
• git diff --check
• Public keyword scan: rg -n -i "dentbird|imagoworks|\bds1\b|\bds4\b" . --glob '!.git/' --glob '!node_modules/' --glob '!dist/**' --glob '!package-lock.json'
• Local stripe-java 31.1.0 smoke: ApiResource.GSON parsed a live Billtap /v1/invoices/create_preview response into com.stripe.model.Invoice.

[claude]

APPROVE

Summary

이 PR은 Stripe SDK와의 호환성을 개선하기 위해 invoice preview 응답 스키마를 수정합니다. 변경사항은 잘 격리되어 있고 테스트 커버리지가 적절히 추가되었습니다.

변경사항 분석

1. Invoice Preview 스키마 확장

• Stripe Invoice의 표준 필드(period_start, period_end, status_transitions, automatic_tax, payment_settings, billing_reason 등)를 추가
• 새로운 헬퍼 함수들(invoicePreviewPeriod, stripeInvoiceParent, stripeInvoiceStatusTransitions, stripeAutomaticTax, stripeInvoicePaymentSettings)이 잘 구조화되어 있음
• api.go:1963-2119

2. Discounts 배열 형식 변경

• discounts 필드를 stripeList envelope에서 직접 배열([]map[string]any)로 변경
• 이는 Stripe의 실제 API 형식과 일치하며, SDK deserialization 호환성을 위해 필요한 변경
• subscription과 invoice 응답에서도 동일하게 적용되어 일관성 유지
• api.go:4943

3. Regression Tests 추가

• Preview schema defaults, period fields, tax defaults, status transitions, discount arrays에 대한 assertion 추가
• api_test.go:4490-4553

검증 관찰사항

1. Billing state correctness: invoicePreviewPeriod 함수가 subscription의 CurrentPeriodStart/CurrentPeriodEnd를 올바르게 사용하며, fallback 동작도 적절함
2. Webhook reliability: webhook 관련 변경 없음
3. Safety: 실제 결제 처리 경로 변경 없음, card data handling 없음
4. Scenario/fixture contract: scenario/fixture 관련 변경 없음
5. UI/API coherence: API 스키마 변경이 SDK deserialization을 목적으로 하며, 문서에 반영됨

문서 업데이트

• COMPATIBILITY.md에 invoice/preview 응답의 default fields와 array-shaped discounts가 문서화됨

결론

Blocking issue 없음. 변경사항은 SDK 호환성 개선이라는 명확한 목적을 가지며, 테스트 커버리지가 적절히 추가되었습니다.