feat: implement redemption code management including creation, listing, and redemption functionality

[chenyme]

Summary

Added billing redemption code functionality and improved the handling of recurring subscription benefits.

This change allows administrators to create, edit, start, stop, delete, batch copy, and export redemption codes in the backend; users can use redemption codes on the subscription/billing page. Redemption codes take effect according to the current billing mode: usage mode for redeeming balance, period mode for redeeming subscription benefits; redemption is not possible if the billing mode does not match or the self-use mode is not supported.

The backend adds redemption code definition, redemption records, subscription benefit queue, and balance crediting logic; redemption codes are processed as secrets in plaintext, and the list does not return the complete plaintext; decryption is performed as needed when copying. The frontend adds backend redemption code management, user redemption entry, subscription benefit display, status filtering, availability filtering, and local optimistic updates.

Included commits:

• 142604b feat: implement redemption code management including creation, listing, and redemption functionality
• ede6c1c feat: load redemption codes when availability filter is set to available

Change type

• Bug fix
• Feature
• Documentation
• Refactor
• Configuration/deployment
• Security hardening
• Other

Affected areas

• Frontend / UI
• Backend/API
• Authentication/authorization
• Conversations / streaming
• Files/RAG/extraction
• Model routing / providers
• MCP/tools
• Billing/payments
• Admin console
• Deployment/Docker/configuration
• Documentation

Verification

-[x] cd backend && go test ./internal/application/billing ./internal/infra/persistence/postgres/billing ./internal/shared/response

• cd frontend && pnpm lint
• cd frontend && pnpm build
• cd backend && make swagger
• git diff --check

Screenshots, API examples, or logs

UI changes include:

• Admin billing redemption-code management section
• User subscription redemption entry
• Subscription entitlement timeline display
• Redemption code creation result dialog
• Redemption code filters for status and availability

No secrets, tokens, or personal data are included.

Configuration, migration, and compatibility notes

• Adds billing redemption-code persistence tables and indexes:
• billing_redemption_codes
• billing_redemptions
• Adds encrypted redemption-code plaintext storage for admin copy/reveal behavior.
• Adds redemption balance transaction type.
• Updates billing subscription grant semantics to queue/merge paid entitlements instead of replacing active paid plans.
• Updates generated Swagger docs for new billing redemption APIs.
• No data backfill is required for existing users.
• Existing billing, payment, balance, and subscription APIs remain compatible.

Documentation

• Documentation is not needed for this change.
• Documentation was updated.
• Documentation still needs to be updated.

Security and privacy

• No secrets, tokens, credentials, local config, or personal data are included.
• User data access remains scoped by authenticated user context unless an admin-only path explicitly requires broader access.
• Security-sensitive behavior was reviewed, including authentication, authorization, provider routing, file processing, billing, and admin APIs where relevant.

Security notes:

• Redemption codes are treated as bearer secrets.
• List APIs do not expose full plaintext codes.
• Code lookup uses HMAC-SHA256 hash.
• Admin copy/reveal uses encrypted stored plaintext and remains admin-only.
• Redemption is validated against status, expiration, total limit, per-user limit, and current billing mode.

Checklist

• I searched existing issues and pull requests.
• Changes are focused and do not include unrelated refactors.
• Tests or static verification were run where practical.
• User-facing behavior, deployment steps, API contracts, or configuration changes are documented.
• Generated artifacts are included only when this project explicitly requires them.
• Caches, build output, .pyc files, .env files, and local storage data are not committed.