Support public base path deployments

[midagedev]

Summary

• add PUBLIC_BASE_PATH and BILLTAP_PUBLIC_BASE_PATH config for shared reverse proxy mounts
• make server redirects, hosted checkout/portal URLs, /api, and /v1 routes prefix-aware, including X-Forwarded-Prefix
• make Vite app assets, app links, dashboard fetches, and web smoke tests work under a prefixed path
• document the reverse proxy contract in README, runbook, compatibility docs, release checklist, and ADR 0003

Validation

• go test ./... -count=1
• npm run build
• PUBLIC_BASE_PATH=/billtap BILLTAP_PUBLIC_BASE_URL=http://127.0.0.1:18080 npm run smoke:web
• Playwright smoke: opened http://127.0.0.1:18080/billtap/app/dashboard/ and verified dashboard links plus /billtap/api and /billtap/v1 network calls
• curl smoke: verified /billtap and X-Forwarded-Prefix: /billtap redirects produce /billtap/app/dashboard/

Notes

• Internal service calls can remain unprefixed, for example http://billtap:8080/v1.
• Browser-facing URLs should set BILLTAP_PUBLIC_BASE_URL to the origin and PUBLIC_BASE_PATH or BILLTAP_PUBLIC_BASE_PATH to the mount path.

[claude]

APPROVE

요약

이 PR은 Billtap이 공유 리버스 프록시 뒤에서 경로 접두사(예: https://localhost:8081/billtap)로 실행될 수 있도록 지원합니다.

변경사항 분석

1. Billing State Correctness

• ✅ 청구 상태 로직에 변경 없음. URL 라우팅만 수정됨.
• absoluteURL() 함수는 URL 생성에만 사용됨.

2. Webhook Reliability

• ✅ 웹훅 서명, 재시도, 중복, 지연, 재생 로직에 변경 없음.
• requestForwardedPrefix()는 URL 생성에만 영향.

3. Safety

• ✅ ValidatePublicBasePath()에서 경로 검증:
  • 전체 URL 거부 (:// 포함)
  • 쿼리 문자열/조각 거부 (?, # 포함)
  • 점 경로 세그먼트 거부 (.., .)
  • 빈 경로 세그먼트 거부 (//)
• ✅ X-Forwarded-Prefix 헤더 적절히 정규화 및 검증
• ✅ 실제 결제 처리 없음

4. Scenario/Fixture Contract

• ✅ 웹 스모크 테스트 smoke-web.mjs 업데이트됨
• ✅ 새로운 테스트 추가됨:
  • TestPublicBasePathPrefixesBrowserRoutes
  • TestForwardedPrefixDrivesRedirects
  • TestPublicBasePathPrefixesAPISessionURLs
  • TestForwardedPrefixPrefixesAPISessionURLs

5. UI/API Coherence

• ✅ basePath.ts 모듈로 경로 처리 중앙화
• ✅ 모든 앱 링크, API 호출, 호스팅 URL이 접두사를 인식하도록 수정됨
• ✅ Vite 설정에서 base 경로 올바르게 구성됨

문서화

• ✅ ADR 0003로 의사결정 기록됨
• ✅ README에 리버스 프록시 섹션 추가됨
• ✅ 호환성 문서 업데이트됨
• ✅ 릴리스 체크리스트 업데이트됨

검증

PR 설명에서 제공된 검증 단계:

• go test ./... -count=1
• npm run build
• PUBLIC_BASE_PATH=/billtap으로 웹 스모크 테스트 통과
• Playwright 스모크로 대시보드 링크 및 네트워크 호출 확인

결론

청구 상태, 웹훅 신뢰성, 보안에 영향을 주지 않는 잘 구현된 기능입니다. 경로 검증이 적절하고, 테스트가 포함되어 있으며, 문서화가 철저합니다.

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