跳到主要内容

Admin v2 Route Compatibility

Status​

superseded — see docs/adr/ADR-009-multi-brand-domain-routed-isolation.md and servers_v2/admin_service/tests/test_legacy_routes_removed.py.

The /v2/* compatibility surface described in this document is not being restored. Legacy /v2/* callers must migrate to /api/v1/* on servers_v2/admin_service. The router-deletion decision is locked in by a regression test that asserts every legacy path returns 404.

Date​

  • Drafted: 2026-04-22
  • Superseded: 2026-05-05

Owners​

  • Platform Backend

Original Goal (no longer being pursued)​

Restore the legacy servers/admin_server v2 HTTP surface on servers_v2/admin_service so old back-office callers can move to servers_v2 without changing route prefixes, HTTP verbs, or high-level resource families.

Scope​

This migration covers the legacy admin_server v2 API surface rooted at /v2/*.

It does not cover:

  • legacy v1 admin routes under /v1/*
  • middle_server legacy compatibility routes under /api/admin/*
  • player-facing or agent-facing non-admin HTTP entrypoints

Compatibility Rules​

For every legacy admin_server v2 route family we should preserve:

  • the /v2/* path family
  • the historical HTTP verb
  • auth semantics: admin JWT required
  • the historical success/error envelope shape

Internal implementation may differ, but route behavior must remain compatible enough for BO callers to cut over without route rewrites.

Implemented So Far​

The compatibility work now restores a dedicated /v2 router in admin_service for both the original low-risk families and a broader set of legacy resource paths that BO callers still use.

Exact or Near-Exact Families Restored​

  • players base resource routes already implemented in player.py
  • banks
  • bank-cards
  • bank-card-groups
  • bank-owner-colors
  • rebate-configs
  • lossback-configs
  • player-levels
  • bans
  • banners
  • downloads
  • global-vars
  • plural ip-blacklists aliases

Legacy Resource Families Added In The Compatibility Layer​

  • player-groups
  • player-tags
  • player-notices
  • player-messages
  • player-deposits/actions/*
  • player-withdrawals/actions/*
  • player-rollings/{id}/actions/force-complete
  • player-registrations/{id}/actions/audit
  • agent-settings/bulk
  • agent-announcements
  • agent-notices
  • promotions
  • coupons/actions/send
  • coupons/{coupon_id}/actions/recycle
  • attendance-events
  • deposit-events
  • register-events
  • providers/{provider_id}
  • message-templates/{template_id}
  • site-maintenance
  • agents
  • agent-withdrawals
  • meta

Selected Historical Action Aliases Added​

  • /players/{id}/actions/lock
  • /players/{id}/actions/unlock
  • /players/{id}/actions/unlock-freeze
  • /players/{id}/actions/reset-password
  • /players/{id}/actions/update-bank

Remaining Gaps​

The highest-risk route-family gaps are now closed, but the cutover still needs a final semantic sweep before we can claim a full no-diff replacement.

These are still open:

  • payload-shape and validation drift review for every compatibility endpoint
  • route-order and duplicate-surface review for legacy/current player and promotion families that still coexist under /v2
  • semantic drift review for site-maintenance because the legacy service used R2-backed content state while the current implementation delegates to the new maintenance endpoint
  • full route inventory comparison against old admin_server v2
  • BO caller verification for multipart and upload-heavy flows such as coupon Excel send and image-bearing resources
  • direct BO smoke verification for the restored agents, agent-withdrawals, and meta slices against real admin workflows

Acceptance Criteria​

  • admin_service exposes a real /v2/* route family again.
  • Legacy callers can hit the implemented compatibility families without moving to /api/v1/*.
  • Regression tests cover both route registration and representative alias execution for the compatibility slice.
  • The restored agents, agent-withdrawals, and meta route families are covered by compatibility tests and local full-suite validation.