PRD: DB Service Backup tab in Data Browser

[aimeritething]

Problem Statement

Users can inspect and browse a DB Service in Data Browser, but they cannot manage DB Service Backups from that same surface. They need a reliable way to create manual backups, configure automatic backups, see backup execution records, delete unneeded recovery points, and restore a completed backup into a new DB Service on the same Project Canvas. Without this, database recovery work is split away from the DB Service context and users cannot confidently protect or recover data from the Brain UI.

Solution

Add a DB Service-level Backup tab to Data Browser. When the user selects the DB Service root node, the main surface shows a service-level tab bar with Backup as the only v1 tab. The Backup tab lets users create named manual DB Service Backups, edit the DB Service Backup Policy, view recent DB Service Backups, delete completed or failed backups, and restore a completed backup into a new DB Service in the same Project Canvas and namespace.

The experience follows the verified Figma direction and the existing sealos dbprovider behavior where it fits, while respecting brainv2 domain language: backup and restore operate at the DB Service boundary, not on Logical Databases, schemas, tables, collections, or keys.

User Stories

1. As a project user, I want to open a DB Service in Data Browser, so that I can manage backups in the same place I inspect database objects.
2. As a project user, I want selecting the DB Service root to show a Backup service tab, so that backup management is scoped to the whole DB Service.
3. As a project user, I want the Backup tab to be separate from table and collection tabs, so that service management does not behave like an object editor.
4. As a project user, I want to create a manual DB Service Backup, so that I can capture a recovery point before risky changes.
5. As a project user, I want to enter a Backup Name, so that the backup has a user-visible identity I recognize later.
6. As a project user, I want Backup Name validation before submit, so that invalid Kubernetes resource names do not fail late.
7. As a project user, I want duplicate Backup Name conflicts to be clearly reported, so that I can choose another name.
8. As a project user, I want to enter an optional Description, so that I can record why the backup was created.
9. As a project user, I want Description to allow normal short prose up to 120 characters, so that I am not constrained by label-sized metadata.
10. As a project user, I want manual backup creation disabled when the source DB Service is not running, so that I do not start a backup that cannot succeed.
11. As a project user, I want feedback after starting a manual backup, so that I know the request was accepted and can watch progress.
12. As a project user, I want to configure a DB Service Backup Policy, so that backups happen automatically without manual work.
13. As a project user, I want each DB Service to have at most one current DB Service Backup Policy, so that the active automatic backup rule is unambiguous.
14. As a project user, I want to choose hourly, daily, or weekly automatic backup frequency, so that the policy matches my recovery needs.
15. As a project user, I want hourly policies to choose the start minute, so that hourly backups run at a predictable minute.
16. As a project user, I want daily policies to choose hour and minute, so that daily backups run at a predictable local time.
17. As a project user, I want weekly policies to choose weekdays plus hour and minute, so that weekly backups run on the right local schedule.
18. As a project user, I want the backup policy schedule displayed and edited in my local time, so that I do not need to mentally convert UTC.
19. As a project user, I want automatic backup retention to be expressed in days, so that backup expiry is easy to understand.
20. As a project user, I want common retention choices such as 1, 3, 7, 14, and 30 days, so that I can choose quickly.
21. As a project user, I want 7 days as the default retention period, so that the initial policy is safe and familiar.
22. As a project user, I want disabling the policy to stop future automatic backups, so that I can pause automation.
23. As a project user, I want disabling the policy to keep existing DB Service Backups, so that disabling automation does not destroy recovery points.
24. As a project user, I want to see a Backup List, so that I can review available recovery points.
25. As a project user, I want the Backup List to show Backup Name, Description, type, status, creation/start time, duration when available, size when available, and failure reason when available, so that I can choose the right recovery point.
26. As a project user, I want manual and automatic backups to be distinguished, so that I understand how each recovery point was created.
27. As a project user, I want the Backup List to refresh while backups are in progress, so that status changes appear without manual reload.
28. As a project user, I want manual refresh after backup actions, so that I can force the latest state.
29. As a project user, I want to delete a DB Service Backup, so that I can remove unneeded recovery points.
30. As a project user, I want deletion disabled while a backup is in progress, so that I do not race an active backup operation.
31. As a project user, I want delete confirmation, so that I do not accidentally remove a recovery point.
32. As a project user, I want delete to affect only the selected DB Service Backup, so that the source DB Service and any restored DB Services remain safe.
33. As a project user, I want to restore a completed DB Service Backup, so that I can recover data into a usable DB Service.
34. As a project user, I want restore to create a new DB Service instead of overwriting the source, so that live data is not destroyed.
35. As a project user, I want to enter the restored DB Service name, so that I can identify the restored service on the Project Canvas.
36. As a project user, I want restored DB Service name validation, so that invalid or duplicate DB Service names are caught before submit.
37. As a project user, I want the restored DB Service to appear on the same Project Canvas, so that it is easy to find and connect to APs.
38. As a project user, I want the restored DB Service to use the same namespace as the source, so that ownership and access remain consistent.
39. As a project user, I want restore to inherit the source DB Service database settings by default, so that restore is focused and does not become a deployment wizard.
40. As a project user, I want restore enabled only for completed backups, so that I do not restore from an incomplete recovery point.
41. As a project user, I want clear error messages for unsupported engines, so that I understand why Backup is unavailable.
42. As a project user, I want Backup v1 for PostgreSQL, MySQL, MongoDB, and Redis, so that the supported Data Browser engines have matching backup management.
43. As a project user, I want credentials and backup internals to remain server-side, so that the browser does not receive database secrets.
44. As an implementing agent, I want the issue to be fully specified, so that I can implement without re-opening product discovery.

Implementation Decisions

• Domain language is already captured in the glossary: DB Service Backup, DB Service Backup Policy, and DB Service Restore.
• DB Service Backup is a recovery point for the entire DB Service. It is not scoped to a Logical Database, schema, table, collection, or key.
• DB Service Backup has a Backup Name and optional Description.
• Backup Name is the user-visible identity and should directly map to the underlying backup resource name. It must be unique in the namespace and follow lowercase DNS-style Kubernetes naming rules.
• Description is non-identifying context, limited to 120 characters. Store it in metadata that does not inherit Kubernetes label byte limits.
• DB Service Backup may be manual or created by the DB Service Backup Policy. Do not model "Automatic Snapshot" as a domain type; that is presentation copy only.
• DB Service Backup deletion removes only that recovery point. It does not delete the source DB Service or any DB Service already restored from the backup.
• Manual DB Service Backup creation requires the source DB Service to be Running.
• DB Service Restore requires a completed DB Service Backup.
• Backup deletion is unavailable while the backup is in progress.
• DB Service Backup Policy is unique per DB Service. A DB Service has at most one current policy.
• DB Service Backup Policy supports hourly, daily, and weekly schedules.
• Schedule selection is shown and edited in the user's local time. Backend storage may use UTC cron, but the product semantics are local-time scheduling.
• Retention is expressed as a selected number of days. V1 should offer 1, 3, 7, 14, and 30 day choices, defaulting to 7 days.
• Disabling DB Service Backup Policy stops future automatic backups and preserves existing DB Service Backups.
• DB Service Restore creates a new DB Service instead of overwriting or rolling back the source DB Service.
• Restored DB Services appear in the same Project Canvas and namespace as the source DB Service.
• Restored DB Services inherit the source DB Service database settings unless restore-time overrides are explicitly introduced later.
• ADR 0017 records the restore-as-new-service decision and should be respected.
• The Data Browser DB Service root node should render a service-level surface. V1 includes a service-level tab bar with only Backup visible.
• Backup is a DB Service internal tab, not one of the existing closeable object tabs.
• ER Diagram and Import Data service tabs are out of scope for this PRD, though the layout should allow adding them later.
• The DB API remains the owner of backup routes because backup is a subordinate DB Service capability.
• Extend the existing manual backup endpoint rather than introducing a separate top-level backup API group.
• Add DB API capabilities for manual backup creation, backup deletion, restore-to-new-DB-Service, and backup policy update/disable.
• Continue using DB get/list as the source of the Backup List, but adapt raw backup resources into a UI-friendly backup summary.
• The backup summary should include stable fields for name, description, namespace, type, status, created/start time, duration when available, size when available, failure reason when available, restorable state, deletable state, and source DB Service identity.
• Add or refine server-side backup adapters so UI code does not understand raw KubeBlocks Backup shapes.
• Add a schedule codec deep module that converts between local-time policy form state and backend cron/policy representation.
• Add a backup name and description validator deep module shared by UI and API when feasible.
• Add a restore request builder or service module that takes source DB Service, selected backup, restored DB Service name, project identity, namespace, and inherited source settings, then renders the correct DB Service resources.
• Supported engines for v1 are PostgreSQL, MySQL, MongoDB, and Redis.
• Unsupported engines should not expose an active Backup tab or should render a clear unavailable state.
• Backup List should auto-refresh every 3 seconds while any backup is in progress, running, or deleting. It should refresh immediately after create, policy update, delete, and restore submissions.
• Manual backup, policy update, delete, and restore should use the current kubeconfig authorization model and keep credentials server-side.
• The feature should fit the current shadcn/Tailwind dark Data Browser surface and should not introduce a separate visual system.

Testing Decisions

• Good tests should verify external behavior and stable contracts: request validation, rendered resource shape, schedule conversion, summary adaptation, state gates, and user-visible interactions. Avoid tests that couple to component internals or raw implementation details.
• Add backend tests for manual backup request validation: required name, namespace resolution, Backup Name validation, Description length, unsupported engine behavior, duplicate name/conflict propagation, and created backup metadata.
• Add backend tests for backup deletion: completed/failed backups can be deleted, missing backups are handled idempotently when appropriate, and in-progress backups are rejected or protected by the API contract.
• Add backend tests for restore-to-new-DB-Service: restore requires a completed backup, creates resources for a new DB Service name, keeps source DB Service intact, uses the same Project Canvas identity and namespace, and inherits source settings.
• Add backend tests for backup policy update/disable: hourly, daily, and weekly forms produce the intended policy representation; retention days are validated; disabling preserves existing backups.
• Add unit tests for the schedule codec, especially local-time to UTC conversion and weekly day rollover.
• Add unit tests for backup summary adaptation from raw backup resources, including manual vs automatic detection, missing optional fields, failure reason, in-progress status, restorable/deletable flags, description extraction, and stable ordering by time.
• Add unit tests for Backup Name and Description validation.
• Add UI tests for selecting the DB Service root and seeing the Backup service tab surface.
• Add UI tests for manual backup form validation and submit behavior.
• Add UI tests for Backup Policy form frequency modes and retention options.
• Add UI tests for disabling policy while preserving list rows.
• Add UI tests for Backup List action availability: restore only for completed backups, delete disabled for in-progress backups.
• Add UI tests for Restore modal name validation and submit payload.
• Add UI tests for Delete confirmation flow.
• Prior art in the codebase includes DB route tests for lifecycle and patch behavior, orchestration render tests for DB OpsRequests/resources, Data Browser session and layout tests, Data Browser access adapter tests, and project canvas claim mapping tests. Follow those styles.
• Run focused Go tests for DB API/service/orchestration changes.
• Run focused TypeScript tests for data-browser state, backup adapters, schedule codec, and UI components.
• Before handoff completion, run the repo-standard checks: typecheck and code quality checks.

Out of Scope

• ER Diagram service tab.
• Import Data service tab.
• Backup or restore for engines outside PostgreSQL, MySQL, MongoDB, and Redis.
• Restoring over or rolling back the source DB Service.
• Cross-Project or cross-namespace restore.
• Restore-time editing of CPU, memory, storage, replicas, engine, version, backup policy, or other DB deployment settings.
• Table-level, collection-level, key-level, schema-level, or Logical Database-level backups.
• Custom cron expressions, monthly schedules, retention units other than days, or arbitrary retention text.
• Bulk backup deletion.
• Downloading backup artifacts.
• Backup cost/quota UX beyond surfacing backend errors.
• Statement-level audit or database-engine-level backup verification.
• Reworking the Project Canvas DB node pane to duplicate this UI.
• Implementing a separate top-level backup product area.

Further Notes

• Figma access was verified for the provided brain v2 node, and the target visual direction is a Data Browser DB Service surface with Backup as a service-level tab.
• The existing sealos dbprovider is useful prior art for manual backup, backup policy, backup list, delete, and restore flows, but brainv2 should preserve its stronger server-side credential posture.
• Existing brainv2 backend already has partial manual backup creation and backup listing through DB status. Expect implementation to extend, harden, and adapt those pieces rather than starting from scratch.
• ADR 0017 should be treated as part of the handoff context: restore creates a new DB Service.
• The CONTEXT.md glossary has been updated with the settled terms and should be read before implementation.