Expand simulation API coverage

[midagedev]

Summary

• Add Stripe-shaped customer search plus subscription, invoice, and PaymentIntent search subsets for deterministic local evidence lookup.
• Add nested customer subscription history routes with status/metadata filters, plus subscription pause_collection and /resume simulation.
• Add sandbox PaymentMethod create/retrieve/attach/detach coverage, including nested customer PaymentMethod retrieve.
• Update compatibility tracking to the current OpenAPI inventory baseline: 160 / 587 operations (27.3%).

Verification

• go test ./... -count=1
• go run ./cmd/billtap compatibility scorecard --output-dir /tmp/billtap-scorecard-simulation-impl
• go run ./cmd/billtap compatibility inventory --openapi /tmp/stripe-openapi-spec3.json --output-dir /tmp/billtap-inventory-simulation-impl --source stripe-openapi-local
• git diff --check
• rg -n -i 'DEN-[0-9]+|dentbird|imagoworks|\\bds1\\b|\\bds4\\b' docs internal specs README.md .github || true

[claude]

APPROVE

Summary

이 PR은 Billtap의 Stripe-compatible simulation API 범위를 144개에서 160개(24.5% → 27.3%)로 확대합니다. Customer search, subscription/invoice/payment intent search, customer nested subscription routes, subscription pause_collection/resume, 그리고 PaymentMethod create/attach/detach 기능이 추가되었습니다.

Billing State Correctness

✅ 안전: 새로운 search API는 읽기 전용이며 기존 billing state를 수정하지 않습니다. Customer nested subscription routes는 기존 subscription graph를 재사용하며 customer ownership 검증이 포함되어 있습니다 (internal/api/api.go:382-390).

✅ 안전: Subscription pause_collection과 resume은 metadata에 local evidence를 저장하며, billing-cycle side effects가 bounded하다고 명시되어 있습니다 (internal/stripecompat/registry.go:232).

✅ 안전: PaymentMethod attach/detach는 customer metadata에만 영향을 미치며, 실제 payment processor 연동 없이 local sandbox card projection만 처리합니다.

Webhook Reliability

✅ 안전: 새로운 webhook 이벤트(payment_method.attached)은 기존 webhook delivery 시스템을 재사용합니다. Webhook signature, retry, idempotency semantics는 변경되지 않았습니다.

Safety

✅ 안전: PaymentMethod create는 "creates local sandbox card projection only; real card data is rejected"라고 명시되어 있습니다 (internal/stripecompat/registry.go:268). Raw card data persistence는 없습니다.

✅ 안전: Production-facing relay/safety feature는 optional/bounded로 유지됩니다.

Scenario/Fixture Contract

✅ 안전: 새로운 search API는 fixture isolation을 깨뜨리지 않습니다. Customer search는 local customer list만 필터링합니다.

✅ 안전: 테스트가 추가되었습니다: TestCustomerSearchAndNestedSubscriptionRoutes, TestSubscriptionPauseCollectionAndResume, TestPaymentMethodAttachDetach (internal/api/api_test.go:3624-3727).

UI/API Coherence

✅ 해당 없음: Dashboard 또는 sample-app 변경이 없습니다.

Documentation

✅ 완료: docs/SIMULATION_CAPACITY_BACKLOG.md가 추가/업데이트되어 public capability tracking이 명확합니다. Compatibility 문서가 160/587 (27.3%)으로 업데이트되었습니다.

Validation

✅ 완료: 새로운 endpoint에 대한 validation이 추가되었습니다 (internal/api/validation.go):

• validateCustomerSearch, validateSearch
• validateSubscriptionUpdate 확장 (pause_collection 파라미터)
• validateSubscriptionResume
• validatePaymentMethodCreate, validatePaymentMethodAttach, validatePaymentMethodUpdate

Minor Suggestions

1. Customer nested subscription routes (/v1/customers/{id}/subscriptions)는 "legacy nested route"라고 명시되어 있지만, 향후 deprecation 계획이 있다면 문서화하면 좋습니다.
2. Search API의 "measured subset" 한계가 docs/COMPATIBILITY.md에 명시되어 있는데, 향후 Stripe Search Query Language 확장 시 해당 limitation을 명확히 유지하면 좋습니다.

Verification

PR description에 명시된 verification 단계가 포함되어 있습니다:

• go test ./... -count=1
• go run ./cmd/billtap compatibility scorecard
• go run ./cmd/billtap compatibility inventory
• git diff --check
• Private data grep 검증

Blocking issue가 없습니다. 이 PR은 simulation capacity backlog를 체계적으로 구현하고 compatibility를 투명하게 추적합니다.

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