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.