Admin Service API

Phase: 9 Status: P9-003 foundation

Scope

admin-service owns the native foundation for feature maintenance state and admin audit history.

This slice does not cut over public /api/* routes. The gateway continues to proxy legacy admin routes until auth/RBAC adapters and response compatibility are explicitly enabled.

Legacy Evidence

• Feature registry and exact labels: packages/shared/src/feature-maintenance.ts.
• Public/admin feature routes: apps/api/src/modules/admin/feature-maintenance.controller.ts.
• Feature state merge/cache/update behavior: apps/api/src/modules/admin/feature-maintenance.service.ts.
• Global maintenance guard and AI classification GET bypass: apps/api/src/common/feature-maintenance.guard.ts.
• Guard registration: apps/api/src/app.module.ts.
• Legacy models: apps/api/prisma/schema.prisma models FeatureMaintenance and AuditLog.
• Admin operations audit listing: apps/api/src/modules/admin/operations.controller.ts.
• Admin maintenance UI callers: apps/web/app/admin/maintenance/page.tsx.
• Admin operations audit UI shape: apps/web/app/admin/operations/page.tsx.

Native Routes

Method	Path	Purpose
GET	/v1	Service marker.
GET	/v1/feature-maintenance/public	Public active feature payload for guard/frontend adapters.
GET	/v1/admin/feature-maintenance	Admin list of all feature maintenance states.
PATCH	/v1/admin/feature-maintenance/{key}	Admin update for enabled and message.
POST	/v1/admin/audit-logs	Internal/admin audit event writer.
GET	/v1/admin/audit-logs	Admin audit list with filters.

Compatibility Rules

• Feature definitions are native data in Go, copied from the legacy registry.
• Preserve exact Vietnamese labels such as Trợ Lý AI, AI Phân Loại Ngân Hàng Câu Hỏi, Import Đề Thi Nhanh (VIP), MathType -> Word Equation, OCR Tài Liệu, and Mẫu Word.
• Feature update accepts only enabled and optional nullable message.
• Message values are trimmed; empty messages are stored as null.
• Public status returns { items, activeFeatureKeys, generatedAt }.
• Admin list returns every registry item, defaulting unconfigured rows to enabled=false.
• Read-only AI classification history/progress GETs must remain inspectable during maintenance: /api/questions/ai-classify/jobs and /api/questions/ai-classify/jobs/:id/....
• Audit logs preserve organizationId, actorId, action, entity, entityId, metadata, and createdAt.
• Audit listing preserves action, entity, limit, and skip filters; limit defaults to 100 and clamps to 1..500, skip defaults to 0.

Deferred Routes

• /api/admin/operations/health, queues, metrics, import jobs, outbox, and retry/clear commands.
• /api/admin/users* and teacher KYC review.
• /api/admin/ai-settings*.
• /api/admin/inbox* recipient targeting and broadcast audit integration.
• /api/admin/wallet*, /api/wallet*, and /api/hooks*.
• /api/support*.
• Admin dashboard aggregation.

Gateway Route Rehearsal

The default gateway route table keeps /api/feature-maintenance*, /api/admin/feature-maintenance*, /api/admin/operations*, and broad /api/admin* traffic on legacy.

Use deploy/gateway/routes.feature-maintenance-native-example.json for Compose or deploy/gateway/routes.feature-maintenance-native-localhost-example.json for local go run rehearsal. The non-default table rewrites only:

• GET /api/feature-maintenance/public to /v1/feature-maintenance/public without gateway auth.
• GET /api/admin/feature-maintenance to /v1/admin/feature-maintenance with gateway auth and ADMIN role.
• PATCH /api/admin/feature-maintenance/{key} to /v1/admin/feature-maintenance/{key} with gateway auth and ADMIN role.

Broad feature-maintenance siblings, nested admin feature-maintenance paths, AI classification job reads, operations/audit, users, AI settings, wallet, support, dashboard, broad admin, and fallback routes remain legacy-proxied until maintenance guard, RBAC, audit, and response compatibility adapters are explicit.

The admin audit route-table rehearsal uses deploy/gateway/routes.admin-audit-native-example.json for Compose or deploy/gateway/routes.admin-audit-native-localhost-example.json for local go run. The non-default table rewrites only:

• GET /api/admin/operations/audit to /v1/admin/audit-logs with gateway auth and ADMIN role.

This audit rehearsal intentionally does not require organization at the gateway because the legacy AdminOperationsController is guarded by global admin role only. Admin operations health, queues, retry/clear commands, metrics, import jobs, outbox, AI settings, feature-maintenance routes not in the table, broad admin, and fallback routes remain legacy-proxied until the remaining operational controls and tenant behavior are explicit.

Rollback

• Keep /api/feature-maintenance*, /api/admin/feature-maintenance*, and /api/admin/operations* as legacy_proxy gateway routes.
• Disable native adapters by removing route-table entries or switching them back to legacy_proxy.
• Drop service-owned feature_maintenance and audit_logs only for local test reset; do not delete legacy FeatureMaintenance or AuditLog.

Validation Queries

SELECT key, enabled, updated_at
FROM feature_maintenance
ORDER BY key;

SELECT action, entity, entity_id, actor_id, created_at
FROM audit_logs
ORDER BY created_at DESC
LIMIT 20;