docs: complete housekeeping migration matrix

2026-08-25 18:49:58 +02:00
1 parent 9b7d5de12f
commit 3b3d7780c9
@@ -0,0 +1,442 @@
+import { PERMS } from "@/lib/permission-slugs";
+import type { MigrationEntry } from "./types";
+
+type PlannedSystemEntry = Omit<
+	MigrationEntry,
+	"targetDomain" | "requiredTests" | "parityEvidence" | "status" | "notes"
+> & {
+	requiredTests?: MigrationEntry["requiredTests"];
+	notes?: MigrationEntry["notes"];
+};
+
+function plannedSystemEntry(entry: PlannedSystemEntry): MigrationEntry {
+	return {
+		...entry,
+		targetDomain: "system",
+		requiredTests: entry.requiredTests ?? ["integration", "e2e", "visual"],
+		parityEvidence: [],
+		status: "PLANNED",
+		notes: entry.notes ?? [],
+	};
+}
+
+export const systemMigrationEntries: readonly MigrationEntry[] = [
+	// Operator alerts and read-only analytics.
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/alerts",
+		sourceFile: "src/app/admin/alerts/page.tsx",
+		targetPath: "/admin/system/operations/alerts",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.NOTIFICATIONS_VIEW],
+			mutate: [PERMS.NOTIFICATIONS_EDIT, PERMS.NOTIFICATIONS_VIEW],
+		},
+		dependencies: {
+			queries: ["AlertLogs"],
+			mutations: [
+				"markAllAlertsRead",
+				"rcon.send hotelalert",
+				"sendHotelAlert",
+			],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: [
+			"Marking alerts read and broadcasting a hotel alert use different current permission slugs",
+		],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/analytics",
+		sourceFile: "src/app/admin/analytics/page.tsx",
+		targetPath: "/admin/system/observability/analytics",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.ANALYTICS_VIEW], mutate: [] },
+		dependencies: {
+			queries: [
+				"Ban",
+				"Rooms",
+				"RoomTradeLog",
+				"User",
+				"chatlogs_room raw SQL",
+				"redisCache",
+			],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/analytics/activity",
+		sourceFile: "src/app/admin/analytics/activity/page.tsx",
+		targetPath: "/admin/system/observability/analytics/activity",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.ANALYTICS_VIEW], mutate: [] },
+		dependencies: {
+			queries: [
+				"Ban",
+				"User",
+				"bans raw SQL",
+				"chatlogs_room raw SQL",
+				"commandlogs raw SQL",
+				"redisCache",
+				"users raw SQL",
+			],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/analytics/economy",
+		sourceFile: "src/app/admin/analytics/economy/page.tsx",
+		targetPath: "/admin/system/observability/analytics/economy",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.ANALYTICS_VIEW], mutate: [] },
+		dependencies: {
+			queries: [
+				"LogsShopPurchases",
+				"MarketplaceItems",
+				"RoomTradeLog",
+				"User",
+				"logs_shop_purchases raw SQL",
+				"redisCache",
+			],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+
+	// Runtime operations, health, and emulator configuration.
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/commandocentrum",
+		sourceFile: "src/app/admin/commandocentrum/page.tsx",
+		targetPath: "/admin/system/operations/command-center",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.RCON_EXECUTE],
+			mutate: [PERMS.RCON_EXECUTE],
+		},
+		dependencies: {
+			queries: [
+				"EmulatorErrors",
+				"StaffActivities",
+				"User",
+				"fetchOpsHealth",
+				"fetchOpsOnlineUsers",
+				"siteSettings.getBool",
+			],
+			mutations: [
+				"alertUser",
+				"disconnectUser",
+				"executeCommand",
+				"forwardUser",
+				"giveBadge",
+				"giveCredits",
+				"giveDiamonds",
+				"giveDuckets",
+				"hotelAlert",
+				"sendGift",
+				"setMotto",
+				"setRank",
+				"updateCatalog",
+				"updateNavigator",
+				"updateWordFilter",
+			],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: [
+			"The current set-rank action combines RCON with a database update and rank-relative authorization",
+		],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/devops",
+		sourceFile: "src/app/admin/devops/page.tsx",
+		targetPath: "/admin/system/observability/devops",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.DEVOPS_VIEW], mutate: [] },
+		dependencies: {
+			queries: [
+				"EmulatorErrors",
+				"EmulatorSettings",
+				"GET /api/admin/devops/health",
+				"fetchOpsHealth",
+			],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: ["Health checks probe the database, Redis, RCON, and online users"],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/devops/errors",
+		sourceFile: "src/app/admin/devops/errors/page.tsx",
+		targetPath: "/admin/system/observability/devops/errors",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.DEVOPS_VIEW], mutate: [] },
+		dependencies: { queries: ["EmulatorErrors"], mutations: [] },
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/emulator",
+		sourceFile: "src/app/admin/emulator/page.tsx",
+		targetPath: "/admin/system/configuration/emulator",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.SETTINGS_VIEW],
+			mutate: [PERMS.SETTINGS_EDIT],
+		},
+		dependencies: {
+			queries: ["EmulatorSettings", "EmulatorTexts"],
+			mutations: ["updateEmulatorSetting", "updateEmulatorText"],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: ["The current actions upsert emulator-owned settings and texts"],
+	}),
+
+	// Foundation-owned legacy pages are retired, not migrated as workflows.
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/housekeeping",
+		sourceFile: "src/app/admin/housekeeping/page.tsx",
+		targetPath: null,
+		decision: "REMOVE",
+		capabilities: { read: [PERMS.SETTINGS_VIEW], mutate: [] },
+		dependencies: {
+			queries: [
+				"AclModelPermission",
+				"AclPermission",
+				"AclRole",
+				"WebsiteHousekeepingPermissions",
+				"exportPermissions",
+				"getAuditLogs",
+				"legacy ACL comparison",
+			],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		requiredTests: ["integration", "e2e"],
+		notes: [
+			"Remove the legacy foundation surface while preserving its read-only export and ACL comparison value in the live access workflow",
+			"Legacy housekeeping writes already redirect to live Permissions",
+		],
+	}),
+
+	// Staff, audit, chat, command, and trade observability.
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/logs",
+		sourceFile: "src/app/admin/logs/page.tsx",
+		targetPath: "/admin/system/observability/logs/staff",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.LOGS_VIEW], mutate: [] },
+		dependencies: { queries: ["StaffActivities", "User"], mutations: [] },
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/logs/audit",
+		sourceFile: "src/app/admin/logs/audit/page.tsx",
+		targetPath: "/admin/system/observability/logs/audit",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.LOGS_VIEW], mutate: [] },
+		dependencies: { queries: ["getAuditLogs"], mutations: [] },
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/logs/chat",
+		sourceFile: "src/app/admin/logs/chat/page.tsx",
+		targetPath: "/admin/system/observability/logs/chat",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.LOGS_VIEW], mutate: [] },
+		dependencies: {
+			queries: ["chatlogs_room raw SQL", "loadChatLogList", "users raw SQL"],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/logs/commands",
+		sourceFile: "src/app/admin/logs/commands/page.tsx",
+		targetPath: "/admin/system/observability/logs/commands",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.LOGS_VIEW], mutate: [] },
+		dependencies: {
+			queries: ["commandlogs raw SQL", "loadCommandLogList", "users raw SQL"],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/logs/trades",
+		sourceFile: "src/app/admin/logs/trades/page.tsx",
+		targetPath: "/admin/system/observability/logs/trades",
+		decision: "REBUILD",
+		capabilities: { read: [PERMS.LOGS_VIEW], mutate: [] },
+		dependencies: {
+			queries: ["loadTradeLogList", "room_trade_log raw SQL", "users raw SQL"],
+			mutations: [],
+		},
+		auditRequirement: "NONE",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+	}),
+
+	// Global configuration and access control.
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/maintenance",
+		sourceFile: "src/app/admin/maintenance/page.tsx",
+		targetPath: "/admin/system/operations/maintenance",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.SETTINGS_VIEW],
+			mutate: [PERMS.SETTINGS_EDIT],
+		},
+		dependencies: {
+			queries: ["WebsiteSetting"],
+			mutations: ["saveMaintenance", "siteSettings.reload"],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: ["Maintenance changes global login availability and splash content"],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/menu",
+		sourceFile: "src/app/admin/menu/page.tsx",
+		targetPath: null,
+		decision: "REMOVE",
+		capabilities: {
+			read: [PERMS.SETTINGS_VIEW],
+			mutate: [PERMS.SETTINGS_EDIT],
+		},
+		dependencies: {
+			queries: ["ADMIN_NAV_GROUPS", "siteSettings.get"],
+			mutations: ["saveAdminNavConfig", "siteSettings.update"],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		requiredTests: ["integration", "e2e"],
+		notes: [
+			"Remove the manual legacy menu editor because foundation manifests own navigation",
+		],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/permissions",
+		sourceFile: "src/app/admin/permissions/page.tsx",
+		targetPath: "/admin/system/access/permissions",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.PERMISSIONS_MANAGE],
+			mutate: [PERMS.PERMISSIONS_MANAGE],
+		},
+		dependencies: {
+			queries: ["fetchEmulatorRankSummaries", "users grouped by rank"],
+			mutations: [
+				"createRank",
+				"deleteRank",
+				"repairAdminNavAclGrants",
+				"rcon.send updatepermissions",
+			],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: ["Keep this live ACL and emulator-rank workflow in System access"],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/permissions/:id",
+		sourceFile: "src/app/admin/permissions/[id]/page.tsx",
+		targetPath: "/admin/system/access/permissions/:id",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.PERMISSIONS_MANAGE],
+			mutate: [PERMS.PERMISSIONS_MANAGE],
+		},
+		dependencies: {
+			queries: [
+				"AclModelPermission",
+				"AclPermission",
+				"AclRole",
+				"User",
+				"fetchEmulatorRankForEdit",
+			],
+			mutations: [
+				"AclRole load-time synchronization",
+				"rcon.send updatepermissions",
+				"saveRank",
+				"setCmsPermissions",
+			],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: [
+			"The current route can create or retitle a CMS role while loading rank detail",
+		],
+	}),
+	plannedSystemEntry({
+		surface: "admin",
+		legacyPath: "/admin/settings",
+		sourceFile: "src/app/admin/settings/page.tsx",
+		targetPath: "/admin/system/configuration/settings",
+		decision: "REBUILD",
+		capabilities: {
+			read: [PERMS.SETTINGS_VIEW],
+			mutate: [PERMS.SETTINGS_EDIT],
+		},
+		dependencies: {
+			queries: ["WebsiteSetting"],
+			mutations: [
+				"createSetting",
+				"deleteSetting",
+				"saveManagedSettings",
+				"siteSettings.reload",
+				"updateSetting",
+			],
+		},
+		auditRequirement: "PRIVILEGED_MUTATION",
+		localization: "PARTIAL",
+		accessibility: "PARTIAL",
+		notes: [
+			"Global setting changes can also invalidate official gamedata and badge caches",
+		],
+	}),
+];