diff --git a/AGENTS.md b/AGENTS.md index 2ca4e1d..1ed0b30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,7 @@ MRP Codex is a modular Manufacturing Resource Planning platform intended to be a - admin diagnostics with runtime footprint, record counts, and persisted audit-trail visibility - admin user management with account creation, activation, role assignment, and role-permission editing - CRM/shipping audit coverage and startup validation surfaced through the admin diagnostics workflow +- backup/restore guidance and exportable support snapshots in the admin diagnostics workflow - Puppeteer PDF foundation - single-container Docker deployment @@ -122,7 +123,7 @@ If implementation changes invalidate those docs, update them in the same change Near-term priorities are: -1. Backup/restore workflow documentation and support-oriented admin tooling +1. Backup verification checklist and restore drill guidance 2. Deeper startup diagnostics and support export helpers When adding new modules, preserve the ability to extend the system without refactoring the existing app shell. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bf4318..46417c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ This file is the running release and change log for MRP Codex. Keep it updated w ### Added +- Backup/restore guidance surfaced in admin diagnostics with exportable support snapshot JSON for support handoff - CRM customer/vendor changes and shipping mutations now feed the shared audit trail - Startup validation now runs during server boot and surfaces readiness checks in admin diagnostics - Admin user-management screen with account creation, activation control, role assignment, and role-permission editing @@ -46,7 +47,7 @@ This file is the running release and change log for MRP Codex. Keep it updated w - The client entry bundle now stays lighter by loading major modules on demand instead of importing all route pages eagerly in `main.tsx` - Company settings now acts as the staging area for admin surfaces while user administration lives on its own dedicated page instead of inside the company-profile form - Admin diagnostics now includes startup-readiness status alongside runtime footprint and recent audit activity -- Roadmap and project docs now treat backup/restore workflow documentation and support-oriented admin tooling as the next active priority after the CRM/shipping audit and startup-validation slice +- Roadmap and project docs now treat backup verification checklist and restore drill guidance as the next active priority after the backup/support-tooling slice ## 2026-03-15 diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md index 655d208..4afe80b 100644 --- a/INSTRUCTIONS.md +++ b/INSTRUCTIONS.md @@ -30,6 +30,7 @@ This repository implements the platform foundation milestone: - admin diagnostics with runtime footprint, storage visibility, record counts, and recent audit activity - admin user management with account creation, activation, role assignment, and role-permission editing - CRM/shipping audit coverage and startup validation surfaced through diagnostics +- backup/restore guidance and exportable support snapshots in diagnostics - Dockerized single-container deployment - Puppeteer PDF pipeline foundation @@ -65,5 +66,5 @@ This repository implements the platform foundation milestone: ## Next roadmap candidates -- backup/restore workflow depth and support-oriented admin tooling +- backup verification checklist and restore drill guidance - deeper startup diagnostics and support export helpers diff --git a/README.md b/README.md index 5c59de7..aec72e1 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ Current foundation scope includes: - admin diagnostics with runtime footprint, record counts, and recent audit-trail visibility - admin user management with account creation, activation, role assignment, and role-permission editing - CRM and shipping audit coverage plus startup validation surfaced through the admin diagnostics page +- backup/restore guidance and exportable support snapshots in the admin diagnostics workflow - route-level code-splitting and vendor chunking for lighter initial client loads - file storage and PDF rendering @@ -50,13 +51,13 @@ Current completed foundation areas: Near-term priorities: -1. Backup/restore workflow documentation and support-oriented admin tooling +1. Backup verification checklist and restore drill guidance 2. Deeper startup diagnostics and support export helpers Revisit / deferred items: - local Windows Prisma migration reliability -- backup/restore workflow depth and support tooling +- backup verification checklist and restore drill depth - deeper startup diagnostics and support export helpers Dashboard direction: @@ -351,11 +352,12 @@ The current admin operations slice supports: - a dedicated user-management page for account creation, activation, role assignment, password reset-style updates, and role-permission administration - CRM customer/vendor changes and shipping mutations now flow into the shared audit trail - startup validation now checks storage paths, database connectivity, client bundle readiness, Chromium availability, and risky production defaults during server boot +- backup and restore guidance now surfaces directly in diagnostics, along with exportable support snapshot JSON for support handoff - operator-facing review of recent high-impact changes without direct database access Current follow-up direction: -- backup/restore workflow guidance and support-oriented admin tooling +- backup verification checklist and restore drill guidance - deeper startup diagnostics and support export helpers ## UI Notes diff --git a/ROADMAP.md b/ROADMAP.md index 54ddced..98e7c1a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -52,6 +52,7 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni - Dedicated user-management screen for account creation, activation, role assignment, and role-permission editing - CRM customer/vendor changes and shipping mutations covered by the shared audit trail - Startup validation during server boot with checks for storage paths, database connectivity, client bundle readiness, Chromium availability, and risky production defaults +- Backup/restore guidance and exportable support snapshots surfaced through the admin diagnostics workflow - Route-level frontend code-splitting and vendor chunking to keep the initial client payload lighter - SKU-searchable BOM component selection for inventory-scale datasets - Theme persistence fixes and denser responsive workspace layouts @@ -293,5 +294,5 @@ QOL subfeatures: ## Near-term priority order -1. Backup/restore workflow documentation and support-oriented admin tooling +1. Backup verification checklist and restore drill guidance 2. Deeper startup diagnostics and support export helpers diff --git a/client/src/lib/api.ts b/client/src/lib/api.ts index 5d4023c..645a1b3 100644 --- a/client/src/lib/api.ts +++ b/client/src/lib/api.ts @@ -1,8 +1,10 @@ import type { AdminDiagnosticsDto, + BackupGuidanceDto, AdminPermissionOptionDto, AdminRoleDto, AdminRoleInput, + SupportSnapshotDto, AdminUserDto, AdminUserInput, ApiResponse, @@ -136,6 +138,12 @@ export const api = { getAdminDiagnostics(token: string) { return request("/api/v1/admin/diagnostics", undefined, token); }, + getBackupGuidance(token: string) { + return request("/api/v1/admin/backup-guidance", undefined, token); + }, + getSupportSnapshot(token: string) { + return request("/api/v1/admin/support-snapshot", undefined, token); + }, getAdminPermissions(token: string) { return request("/api/v1/admin/permissions", undefined, token); }, diff --git a/client/src/modules/settings/AdminDiagnosticsPage.tsx b/client/src/modules/settings/AdminDiagnosticsPage.tsx index bab0542..30595dc 100644 --- a/client/src/modules/settings/AdminDiagnosticsPage.tsx +++ b/client/src/modules/settings/AdminDiagnosticsPage.tsx @@ -1,4 +1,4 @@ -import type { AdminDiagnosticsDto } from "@mrp/shared"; +import type { AdminDiagnosticsDto, BackupGuidanceDto } from "@mrp/shared"; import { Link } from "react-router-dom"; import { useEffect, useState } from "react"; @@ -20,6 +20,7 @@ function parseMetadata(metadataJson: string) { export function AdminDiagnosticsPage() { const { token } = useAuth(); const [diagnostics, setDiagnostics] = useState(null); + const [backupGuidance, setBackupGuidance] = useState(null); const [status, setStatus] = useState("Loading diagnostics..."); useEffect(() => { @@ -29,13 +30,13 @@ export function AdminDiagnosticsPage() { let active = true; - api - .getAdminDiagnostics(token) - .then((nextDiagnostics) => { + Promise.all([api.getAdminDiagnostics(token), api.getBackupGuidance(token)]) + .then(([nextDiagnostics, nextBackupGuidance]) => { if (!active) { return; } setDiagnostics(nextDiagnostics); + setBackupGuidance(nextBackupGuidance); setStatus("Diagnostics loaded."); }) .catch((error: Error) => { @@ -50,10 +51,26 @@ export function AdminDiagnosticsPage() { }; }, [token]); - if (!diagnostics) { + if (!diagnostics || !backupGuidance) { return
{status}
; } + async function handleExportSupportSnapshot() { + if (!token) { + return; + } + + const snapshot = await api.getSupportSnapshot(token); + const blob = new Blob([JSON.stringify(snapshot, null, 2)], { type: "application/json" }); + const objectUrl = window.URL.createObjectURL(blob); + const link = document.createElement("a"); + link.href = objectUrl; + link.download = `mrp-codex-support-snapshot-${new Date().toISOString().replace(/[:.]/g, "-")}.json`; + link.click(); + window.setTimeout(() => window.URL.revokeObjectURL(objectUrl), 60_000); + setStatus("Support snapshot exported."); + } + const summaryCards = [ ["Server time", formatDateTime(diagnostics.serverTime)], ["Node runtime", diagnostics.nodeVersion], @@ -97,6 +114,13 @@ export function AdminDiagnosticsPage() {

+ User management @@ -115,6 +139,47 @@ export function AdminDiagnosticsPage() {
+
+
+
+

Backup And Restore

+

Operational backup workflow

+

+ Use these paths and steps as the support baseline for manual backup and restore procedures. +

+
+
+
Data: {backupGuidance.dataPath}
+
DB: {backupGuidance.databasePath}
+
Uploads: {backupGuidance.uploadsPath}
+
+
+
+
+

Backup checklist

+
+ {backupGuidance.backupSteps.map((step) => ( +
+

{step.label}

+

{step.detail}

+
+ ))} +
+
+
+

Restore checklist

+
+ {backupGuidance.restoreSteps.map((step) => ( +
+

{step.label}

+

{step.detail}

+
+ ))} +
+
+
+
+
diff --git a/server/src/modules/admin/router.ts b/server/src/modules/admin/router.ts index bed0cf2..b01b060 100644 --- a/server/src/modules/admin/router.ts +++ b/server/src/modules/admin/router.ts @@ -7,7 +7,9 @@ import { requirePermissions } from "../../lib/rbac.js"; import { createAdminRole, createAdminUser, + getBackupGuidance, getAdminDiagnostics, + getSupportSnapshot, listAdminPermissions, listAdminRoles, listAdminUsers, @@ -40,6 +42,14 @@ adminRouter.get("/diagnostics", requirePermissions([permissions.adminManage]), a return ok(response, await getAdminDiagnostics()); }); +adminRouter.get("/backup-guidance", requirePermissions([permissions.adminManage]), async (_request, response) => { + return ok(response, getBackupGuidance()); +}); + +adminRouter.get("/support-snapshot", requirePermissions([permissions.adminManage]), async (_request, response) => { + return ok(response, await getSupportSnapshot()); +}); + adminRouter.get("/permissions", requirePermissions([permissions.adminManage]), async (_request, response) => { return ok(response, await listAdminPermissions()); }); diff --git a/server/src/modules/admin/service.ts b/server/src/modules/admin/service.ts index 1620786..b9c59cb 100644 --- a/server/src/modules/admin/service.ts +++ b/server/src/modules/admin/service.ts @@ -1,10 +1,12 @@ import type { AdminDiagnosticsDto, + BackupGuidanceDto, AdminPermissionOptionDto, AdminRoleDto, AdminRoleInput, AdminUserDto, AdminUserInput, + SupportSnapshotDto, AuditEventDto, } from "@mrp/shared"; import fs from "node:fs/promises"; @@ -547,3 +549,76 @@ export async function getAdminDiagnostics(): Promise { recentAuditEvents: recentAuditEvents.map(mapAuditEvent), }; } + +export function getBackupGuidance(): BackupGuidanceDto { + return { + dataPath: paths.dataDir, + databasePath: `${paths.prismaDir}/app.db`, + uploadsPath: paths.uploadsDir, + recommendedBackupTarget: "/mnt/user/backups/mrp-codex", + backupSteps: [ + { + id: "stop-app", + label: "Stop writes before copying data", + detail: "Stop the container or application process before copying the data directory so SQLite and attachments stay consistent.", + }, + { + id: "copy-data", + label: "Back up the full data directory", + detail: `Copy the full data directory at ${paths.dataDir}, not just the SQLite file, so uploads and attachments are preserved with the database.`, + }, + { + id: "retain-metadata", + label: "Keep timestamps and structure", + detail: "Preserve directory structure, filenames, and timestamps during backup so support recovery remains straightforward.", + }, + { + id: "record-build", + label: "Record image/version context", + detail: "Capture the deployed image tag or commit alongside the backup so schema and runtime expectations are clear during restore.", + }, + ], + restoreSteps: [ + { + id: "stop-target", + label: "Stop the target app before restore", + detail: "Do not restore into a running instance. Stop the target container or process before replacing the data directory.", + }, + { + id: "replace-data", + label: "Restore the full data directory", + detail: `Replace the target data directory with the backed-up copy so ${paths.prismaDir}/app.db and uploads come back together.`, + }, + { + id: "start-and-migrate", + label: "Start the app and let migrations run", + detail: "Restart the application after restore and allow the normal startup migration flow to complete before validation.", + }, + { + id: "validate-core", + label: "Validate login, files, and PDFs", + detail: "Confirm admin login, attachment access, and PDF generation after restore to verify the operational surface is healthy.", + }, + ], + }; +} + +export async function getSupportSnapshot(): Promise { + const diagnostics = await getAdminDiagnostics(); + const [users, roles] = await Promise.all([ + prisma.user.findMany({ + where: { isActive: true }, + select: { email: true }, + orderBy: [{ email: "asc" }], + }), + prisma.role.count(), + ]); + + return { + generatedAt: new Date().toISOString(), + diagnostics, + userCount: diagnostics.userCount, + roleCount: roles, + activeUserEmails: users.map((user) => user.email), + }; +} diff --git a/shared/src/admin/types.ts b/shared/src/admin/types.ts index e051566..0cc98b0 100644 --- a/shared/src/admin/types.ts +++ b/shared/src/admin/types.ts @@ -60,6 +60,29 @@ export interface StartupValidationCheckDto { message: string; } +export interface BackupChecklistItemDto { + id: string; + label: string; + detail: string; +} + +export interface BackupGuidanceDto { + dataPath: string; + databasePath: string; + uploadsPath: string; + recommendedBackupTarget: string; + backupSteps: BackupChecklistItemDto[]; + restoreSteps: BackupChecklistItemDto[]; +} + +export interface SupportSnapshotDto { + generatedAt: string; + diagnostics: AdminDiagnosticsDto; + userCount: number; + roleCount: number; + activeUserEmails: string[]; +} + export interface AdminDiagnosticsDto { serverTime: string; nodeVersion: string;