Skip to main content

Admin Web Content Compatibility Migration

Status​

Implemented

Date​

2026-04-22

Owners​

  • Platform Backend

Problem​

bo/admin still depends on the legacy middle_server web CMS routes:

  • /api/admin/web/rules/*
  • /api/admin/web/faq/*
  • /api/admin/web/config/*

The admin UI does not just depend on the route names. It also depends on:

  1. the old status/msg/data response envelope;
  2. the exact result, bucket, i18ns, and content field names;
  3. the exact R2 object layout that the frontend later fetches directly;
  4. legacy admin-session authentication with JWT refresh on response.

Without preserving all four, servers_v2 cannot replace this middle_server slice without BO-visible regressions.

Decision​

Implement the legacy web CMS slice inside servers_v2/admin_service.

Do not create a separate service for this slice right now.

Rationale:

  • the callers are back-office only;
  • the auth boundary already belongs to admin_service;
  • the runtime behavior is orchestration plus object-storage persistence rather than an end-user domain API;
  • compatibility is easier when the legacy /api/admin/* surface stays on the existing admin edge.

Compatibility Contract​

Legacy routes preserved​

  • /api/admin/web/rules/list
  • /api/admin/web/rules/add
  • /api/admin/web/rules/edit
  • /api/admin/web/rules/move
  • /api/admin/web/rules/delete
  • /api/admin/web/faq/list
  • /api/admin/web/faq/add
  • /api/admin/web/faq/edit
  • /api/admin/web/faq/move
  • /api/admin/web/faq/delete
  • /api/admin/web/config/categories
  • /api/admin/web/config/detail
  • /api/admin/web/config/set

Auth contract preserved​

  • uses legacy admin JWT/session validation
  • returns refreshed Authorization header after authenticated requests
  • does not expose these routes as unauthenticated internal write APIs

R2 layout preserved​

  • rules config: web/rules/config.json
  • rules text files: web/rules/<uuid>_<i18n>.txt
  • FAQ config: web/faqs/config.json
  • FAQ text files: web/faqs/<uuid>_<i18n>.txt
  • single-page config: web/contents/<category>/config.json
  • single-page text files: web/contents/<category>/<i18n>.txt

This is mandatory because BO later fetches the text files directly from the R2 public URL instead of reading them back through admin_service.

Implementation Notes​

  • implementation lives in servers_v2/admin_service/app/services/legacy_web_content.py
  • routes live in servers_v2/admin_service/app/api/routes/legacy_web_content.py
  • compatibility is explicit and route-by-route
  • no generic middle_server catch-all forwarding is reintroduced

Test Evidence​

Validated by servers_v2/admin_service/tests/test_admin_integration.py:

  • legacy rules list response shape
  • legacy rules CRUD R2 path contract
  • legacy FAQ add/list compatibility
  • legacy content config category/detail/set compatibility

Remaining Non-Goals​

This migration does not yet cover other middle_server residual slices such as:

  • role/menu management
  • old config management
  • i18n management
  • BI tooling
  • legacy /coin/*
  • generic catch-all forwarding