Generated by Claude Sonnet 4.6 with Copilot.
<!-- feishu-doc: YGQ6dTK8DocL1KxGLVmc4H6vn2d -->
<!-- feishu-url: https://www.feishu.cn/docx/YGQ6dTK8DocL1KxGLVmc4H6vn2d -->

# Product Spec: Cluster Detail Page — DM / Import / Backup / Restore Tabs

**Document ID:** 2026-04-23-cluster-detail-dm-import-br-tabs  
**Status:** Draft

---

## Table of Contents

1. [Background and Motivation](#1-background-and-motivation)
2. [Design Intent](#2-design-intent)
3. [Tools Tab on the Cluster Detail Page](#3-tools-tab-on-the-cluster-detail-page)
4. [Tools Page Layout](#4-tools-page-layout)
5. [DM Sub-tab](#5-dm-sub-tab)
6. [Import Sub-tab](#6-import-sub-tab)
7. [Backup Sub-tab (Dedicated Only)](#7-backup-sub-tab-dedicated-only)
8. [Restore Sub-tab (Dedicated Only)](#8-restore-sub-tab-dedicated-only)
9. [Milestones](#9-milestones)
10. [Open Questions](#10-open-questions)

---

## 1. Background and Motivation

The Management Portal provides cluster-level visibility for operations engineers and support staff. Currently, there is no unified, dedicated view for data migration, import, backup, and restore activities associated with a specific cluster. Operators must navigate multiple systems or use CLI tools to answer basic questions such as "What DM jobs are running on this cluster?", "Is the latest precheck passing?", or "When was the last successful backup?"

**Pain points addressed:**

- No centralized view of DM jobs, precheck history, import tasks, or backup/restore status per cluster in the Management Portal.
- Support engineers must use disparate tools and internal APIs to diagnose migration or data-load failures.
- No visibility into which DM version is active on a given cluster and how that version was determined (cluster-specific override vs. inherited default).
- Backup settings, backup history, and restore history for a cluster are not surfaced together in one place.

---

## 2. Design Intent

| Dimension | Goal |
|-----------|------|
| **Visibility** | Give operators a single place to monitor the current and historical state of DM, Import, Backup, and Restore for any cluster. |
| **Diagnosability** | Surface error messages, progress details, and precheck results inline -- no CLI or external tool required. |
| **Auditability** | Show historical records (past prechecks, completed imports, past backups, restore operations) to support root-cause analysis and incident review. |
| **Architecture awareness** | Adapt the displayed content based on cluster architecture (Dedicated vs. Premium), since the backend systems and available data differ between the two. |

---

## 3. Tools Tab on the Cluster Detail Page

Instead of adding multiple top-level tabs (DM, Import, Backup, Restore) on the cluster detail page, all data-plane operational tooling — including the **existing Changefeed** feature and the **newly added DM, Import, Backup, Restore** — is consolidated under a single new top-level tab named **Tools**.

**Behavior of the Tools tab:**

- The Tools tab behaves as an **external link**, not an inline panel. Clicking it **opens a new browser tab/window** and navigates to a dedicated **Tools page** for this cluster.
- The Tools page carries the cluster context (cluster ID, tenant ID, architecture) via URL parameters so it is bookmarkable and linkable.
- The existing Changefeed top-level tab is **removed** from the cluster detail page and relocated as a sub-tab on the Tools page. No functional or UX change to Changefeed itself; only its entry point moves.

**Rationale:**

- Keeps the cluster detail page compact — a single Tools entry point instead of five parallel tabs.
- Gives operational tooling its own full-screen working surface where tables, detail popups, and multi-step flows are not cramped by the surrounding cluster detail chrome.
- Provides a natural home for future tools without further crowding the cluster detail page.

---

## 4. Tools Page Layout

The Tools page uses a **top–bottom layout**:

- **Top: Overview panel** — a compact summary of cluster identity and at-a-glance tool health, always visible regardless of which sub-tab is active.
- **Bottom: Sub-tabs** — the full interactive surface for each tool. Sub-tabs: **Changefeed**, **DM**, **Import**, **Backup** (Dedicated only), **Restore** (Dedicated only).

For clusters where a sub-tab is not applicable (e.g., Backup / Restore on a Premium cluster), that sub-tab is hidden. Default sub-tab on initial load is **Changefeed** (preserving the existing entry behavior); deep-linking to a specific sub-tab via URL fragment (e.g., `#dm`, `#import`, `#backup`, `#restore`, `#changefeed`) is supported.

### 4.1 Overview Panel (Top)

The overview panel is a read-only header that summarizes who this cluster is and whether its tools are healthy. It is grouped into three blocks arranged horizontally.

**Block A — Cluster Identity**

| Field | Description |
|-------|-------------|
| Cluster Name | Display name of the cluster, with a link back to the cluster detail page. |
| Cluster ID | Internal cluster identifier. Copyable. |
| Tenant | Tenant / organization name, with tenant ID. |
| Architecture | `Dedicated` or `Premium`. Drives which sub-tabs are shown. |
| Cloud Provider / Region | e.g. `AWS / us-west-2`. |
| TiDB Version | Current TiDB version running on the cluster. |
| Cluster Status | Lifecycle status (e.g., `AVAILABLE`, `MAINTAINING`, `PAUSED`). |

**Block B — TiDB Tool Health Snapshot**

At-a-glance counters / status indicators per sub-tab. Clicking a counter jumps to the corresponding sub-tab with the matching filter pre-applied.

| Indicator | Description |
|-----------|-------------|
| Changefeed | Count of running changefeeds / count of failed changefeeds. |
| DM — Running Jobs | Count of active (non-finished) DM jobs. |
| DM — Latest Precheck | Status of the most recent precheck (`pass` / `warn` / `fail`) with its timestamp. |
| Import — Active Tasks | Count of import tasks in `PREPARING` or `IMPORTING` state. |
| Import — Recent Failures | Count of imports that ended in `FAILED` within the last 24 hours. |
| Backup — Last Successful Backup | Timestamp and age (e.g., “6 h ago”) of the most recent successful backup. *(Dedicated only)* |
| Backup — PiTR Checkpoint Lag | Difference between now and the log-backup checkpoint timestamp, when PiTR is enabled. *(Dedicated only)* |
| Restore — In-flight Restore | Status of the currently running restore, if any. *(Dedicated only)* |

**Block C — Quick Links**

| Link | Target |
|------|--------|
| Back to Cluster Detail | Returns to the originating cluster detail page. |
| Approval Center | Filtered view of approval requests scoped to this cluster (relevant in Milestone 2). |
| DM Version Config | Config-center page where the DM version override for this cluster can be inspected. |

The overview panel is collapsible. Its content is computed from the same backend APIs used by the sub-tabs; no new aggregate endpoint is required, but the frontend may issue parallel requests on page load and cache the results.

### 4.2 Sub-tab: Changefeed

**Unchanged from the existing Changefeed tab on the cluster detail page.** Only the entry point moves: instead of being a top-level tab on the cluster detail page, it is now a sub-tab on the Tools page. All columns, actions, and sub-views behave exactly as they do today. This section is a placeholder; the authoritative behavior is defined by the existing Changefeed spec.

The next four sections (§5–§8) describe each of the newly added sub-tabs in detail.

---

## 5. DM Sub-tab

The DM sub-tab provides visibility into the Data Migration (DM) service for this cluster. It applies to both Dedicated and Premium cluster architectures.

### 5.1 Overview Section

The top of the DM sub-tab shows a read-only summary of the DM component configuration for this cluster.

| Field | Description |
|-------|-------------|
| **DM Version** | The DM component image version currently active for this cluster, as tracked by the config-center. |
| **Version Source** | How the DM version was determined for this cluster. One of three values: **Cluster-locked** (an explicit version override is set for this specific cluster), **Tenant default** (the cluster inherits the tenant's configured default DM version), or **Global default** (the cluster inherits the platform-wide default DM version, because no tenant-level override exists). |

### 5.2 Sub-tab: Running DM Jobs

Lists all active (non-finished, non-deleted) DM migration jobs for this cluster. Each row represents one DM job.

**Job-level columns:**

| Column | Description |
|--------|-------------|
| Job ID | Unique identifier of the DM job. |
| Job Name | Human-readable name of the job. |
| Mode | Migration mode: `all` (full migration followed by incremental replication), `incremental` (incremental replication only), or `full` (full migration only). |
| Import Mode | Method used during the load phase (e.g., `logical`). |
| Created At | Job creation timestamp. |
| Cluster User | The TiDB user account used by this DM job to connect to the target cluster. |

**Sub-task details (expandable per job):**

Each DM job may have one or more sub-tasks, one per upstream source. The following are shown for each sub-task:

| Column | Description |
|--------|-------------|
| Source | The upstream data source identifier. |
| Current Step | The active migration phase: `Schema` / `Dump` / `Load` / `Sync`. |
| Stage | Current execution state: `Creating` / `Running` / `Pausing` / `Paused` / `Failed` / `Finished` / `Deleting` / `Scaling` / `Unknown`. |

When **Current Step = Dump**, these progress metrics are shown:

| Metric | Description |
|--------|-------------|
| Progress | Percentage of tables dumped (0-100%). |
| Tables | Completed tables out of total. |
| Finished Bytes | Volume of data exported so far. |
| Finished Rows | Number of rows exported so far. |
| Throughput | Export speed (bytes/sec). |
| Duration | Elapsed time for this step. |

When **Current Step = Load**, these metrics are shown:

| Metric | Description |
|--------|-------------|
| Progress | Percentage of data loaded (0-100%). |
| Finished Bytes | Volume of data loaded so far. |
| Total Bytes | Total data volume to load. |
| Throughput | Load speed (bytes/sec). |
| Duration | Elapsed time for this step. |

When **Current Step = Sync**, these metrics are shown:

| Metric | Description |
|--------|-------------|
| Latency | Current replication lag. |
| Rows per Second | Replication throughput (rows/sec). |
| Checkpoint | Current binlog position (the latest upstream event successfully replicated). |
| Duration | Elapsed time in incremental sync mode. |

When **Stage = Failed**, an error detail block is shown:

| Field | Description |
|-------|-------------|
| Error Code | Numeric or symbolic error code. |
| Error Message | Description of the failure. |
| Workaround | Suggested remediation steps, if available. |

### 5.3 Sub-tab: Precheck History

Lists all DM prechecks that have been run for this cluster, in reverse chronological order (most recent first). Precheck records are persisted in the backend database for both Dedicated and Premium architectures and are queryable by cluster.

**Columns:**

| Column | Description |
|--------|-------------|
| Precheck ID | Unique identifier of the precheck record. |
| Created At | Timestamp when the precheck was initiated. |
| Status | Execution state: `pending` / `running` / `finished` / `failed` / `canceled`. |
| Total | Total number of check items evaluated. |
| Failed | Number of check items that failed. |
| Warnings | Number of check items that produced a warning. |
| Passed | Number of check items that passed. |
| Full Instance Migrate | *(Dedicated only)* Whether this precheck was run for a full-instance migration. |
| Actions | **Detail** button that opens a popup showing all individual check items. |

**Precheck Detail Popup (opened via the Detail action):**

| Column | Description |
|--------|-------------|
| Check Type | The category of this check. Possible values: Dump Privilege, Replication Privilege, Version, Server ID, Binlog Enable, Binlog Format, Binlog Row Image, Table Schema, Binlog DB, Connection Number, Target DB Privilege, Meta Position, Lightning Table Empty, Primary Key. |
| Description | Human-readable description of what was checked. |
| Status | Result: `pass` / `warn` / `fail`. |
| Reason | The specific error or warning message, if the check did not pass. |
| Solution | Recommended remediation steps. |
| Documentation | Link to the relevant help document, if available. |

---

## 6. Import Sub-tab

The Import sub-tab shows all import tasks for this cluster. The display adapts based on cluster architecture.

### 6.1 Dedicated Import

Applies to Dedicated-architecture clusters.

**Columns:**

| Column | Description |
|--------|-------------|
| Import ID | Unique identifier of the import job. |
| Created At | Import creation timestamp. |
| Completed At | Import completion timestamp (empty if not yet completed). |
| State | `PREPARING` / `IMPORTING` / `COMPLETED` / `FAILED` / `CANCELING` / `CANCELED`. |
| Progress | Completion percentage (0-100%). |
| Data Size | Total data volume being imported. |
| Source Type | Cloud storage provider of the source data: `S3`, `GCS`, or `Azure Blob`. |
| File Type | Data format: `CSV`, `Parquet`, `SQL`, or `Aurora Snapshot`. |
| Creator | Email address of the user who initiated the import. |
| Message | Error message, shown when State = `FAILED`. |

### 6.2 Premium Import (IMPORT INTO)

Applies to Premium-architecture clusters. Uses the IMPORT INTO mechanism, which supports sub-task level granularity -- one sub-task per target table.

**Task-level columns:**

| Column | Description |
|--------|-------------|
| Import ID | Unique identifier of the import task. |
| Name | Optional display name for this import task. |
| Created At | Task creation timestamp. |
| Completed At | Task completion timestamp (empty if not yet completed). |
| State | `PREPARING` / `IMPORTING` / `COMPLETED` / `FAILED` / `CANCELING` / `CANCELED`. |
| Progress | Overall completion percentage (0-100%). |
| Data Size | Total data volume being imported. |
| Source Type | Cloud storage provider: `S3`, `OSS` (Alibaba Cloud), or `Azure Blob`. |
| Creator | Email address of the initiating user. |
| Message | Error message when State = `FAILED`. |

**Sub-task detail (expandable per task):**

| Column | Description |
|--------|-------------|
| Target Database | The target database name within TiDB. |
| Target Table | The target table name. |
| Files Pattern | Wildcard pattern matching the source files for this sub-task. |
| Status | `PENDING` / `RUNNING` / `CANCELED` / `FAILED` / `FINISHED`. |
| Current Step | Which processing phase is currently active. |
| Step Progress | Completion percentage for the current step (0-100%). |
| Step Speed | Data throughput for the current step. |
| ETA | Estimated time to completion for the current step. |
| Imported Rows | Number of rows successfully imported so far. |
| Data Size | Total size of source files for this sub-task. |
| Started At | Sub-task start timestamp. |
| Finished At | Sub-task completion timestamp (empty if still running). |
| Result Message | Completion summary or error message. |

---

## 7. Backup Sub-tab (Dedicated Only)

The Backup sub-tab is shown only for Dedicated-architecture clusters. It is divided into three sections: the Backup Settings panel at the top, the Backup List, and the Log Backup section (shown only when PiTR is enabled).

### 7.1 Backup Settings Panel

Displays the current backup configuration for this cluster. Authorized users can edit these settings.

| Field | Description |
|-------|-------------|
| Auto Backup | Whether automatic scheduled backup is enabled. Toggle: Enabled / Disabled. |
| Backup Cycle | Frequency of scheduled backups: `Daily` or `Weekly`. |
| Backup Time | Time of day for the scheduled backup, with timezone. |
| Days of Week | *(When Backup Cycle = Weekly)* Which days of the week the backup runs (multi-select). |
| Retention Period | Number of days that backup snapshots are retained before auto-deletion. |
| Point-in-Time Restore (PiTR) | Whether continuous log backup is enabled for this cluster. Toggle: Enabled / Disabled. |
| Dual Region Backup | Whether backup data is replicated to a secondary geographic region. Toggle: Enabled / Disabled. |
| Next Scheduled Backup | Computed display of the next scheduled backup time based on the current configuration. Read-only. |
| Status | Current backup setting status, 'creating' / 'editing_region' / 'normal' / 'deleted' Read-only. |
| Action | Current action of this backup setting , read BackupSetting.BackupSettingAction.CurrentActions, it's a list. Read-only. |


> Reference: See the attached Backup Settings UI screenshot for the visual layout of this panel.

### 7.2 Backup List

Shows all non-deleted backup snapshots for this cluster, sorted in reverse chronological order.

**Columns:**

| Column | Description |
|--------|-------------|
| Backup Name | Name of the backup snapshot. |
| Type | How the backup was triggered: `auto` (created by schedule) or `manual` (triggered on demand). |
| Status | `pending` / `running` / `success` / `failed` / `skipped` / `terminated`. |
| Created At | Backup start timestamp. |
| Finished At | Backup completion timestamp (empty if still running). |
| Start TSO | Start TSO of this backup (empty if still running). |
| Cluster Version | TiDB version of the cluster at the time this backup was taken. |
| Backup Size | Size of the backup snapshot. |
| Retention Policy | `delete` (auto-deleted when expired) or `retain` (kept indefinitely). |
| Protected | Whether this backup is protected from deletion. |

### 7.3 Log Backup (PiTR) Section

Shown only when Point-in-Time Restore is enabled for the cluster. Displays the current state of the continuous log backup stream.

| Field | Description |
|-------|-------------|
| Name | The name of the log backup stream. |
| Status | `scheduled` / `pending` / `running` / `stopping` / `stopped` / `pausing` / `paused` / `resuming` / `failed`. |
| Start Timestamp | When the log backup stream was started. |
| Checkpoint Timestamp | The latest timestamp up to which log data has been continuously and durably backed up. This is the earliest safe point-in-time recovery target. |
| Error Message | Shown when Status = `failed`. |

---

## 8. Restore Sub-tab (Dedicated Only)

The Restore sub-tab is shown only for Dedicated-architecture clusters. It lists all restore operations that have targeted this cluster.

> **Note:** In practice, only one restore operation can be active on a cluster at a time.

**Columns:**

| Column | Description |
|--------|-------------|
| Restore ID | Unique identifier of the restore operation. |
| Restore Name | Name of the restore task. |
| Mode | The restore method: `snapshot` (from a snapshot backup), `pitr` (to an arbitrary point in time using log backup data), or `volume-snapshot` (from a volume-level snapshot). |
| Status | `pending` / `running` / `success` / `failed` / `finished` / `deleting` / `deleted`. |
| Created At | Task creation timestamp. |
| Finished At | Task completion timestamp (empty if still in progress). |
| Source Backup ID | ID of the source backup used as the base for this restore. |
| Source Backup Name | Name of the source backup. |
| Target Cluster | Name of the cluster being restored to. |
| Target Region | Cloud region of the target cluster. |
| Progress | Restore completion percentage (0-100%). |
| Restore Timestamp | *(PiTR mode only)* The target point-in-time selected for this restore. |
| Error Message | Shown when Status = `failed`. |

---

## 9. Milestones

Delivery is split into two sequential milestones. The first establishes visibility and diagnostics without modifying any cluster state; the second adds gated write operations.

### Milestone 1 — Read-Only Visibility

**Scope:** Introduce the new **Tools** top-level tab on the cluster detail page, build the external **Tools page** with the top–bottom layout, relocate **Changefeed** as a sub-tab (no behavior change), and deliver the four newly added sub-tabs (DM, Import, Backup, Restore) strictly read-only.

**Included:**

- Cluster detail page: replace the existing Changefeed top-level tab with a new **Tools** top-level tab that opens the Tools page in a new browser tab.
- Tools page: top Overview panel (cluster identity, TiDB Tool Health Snapshot, quick links) + bottom sub-tabs area with deep-link support.
- Changefeed sub-tab: relocated, no UX change.
- DM sub-tab: Overview section (DM version + version source), Running DM Jobs sub-tab, Precheck History sub-tab (including the Detail popup).
- Import sub-tab: Dedicated Import list and Premium Import (IMPORT INTO) list, including sub-task details.
- Backup sub-tab: Backup Settings panel rendered as read-only, Backup List, Log Backup (PiTR) section.
- Restore sub-tab: Restore task list.

**Explicitly out of scope for Milestone 1:**

- No create / edit / cancel / retry / delete / pause / resume actions on any tab.
- No ability to modify backup settings, trigger a manual backup, cancel an in-progress task, or start a restore from this UI.
- The Backup Settings panel displays current values but provides no edit affordance.

**Goal:** Give operators and support engineers unified read access to Changefeed, DM, Import, Backup, and Restore state per cluster, removing the need for CLI or cross-system lookups during diagnosis.

### Milestone 2 — Write Operations (Approval-Gated)

**Scope:** Introduce write operations on the Tools page sub-tabs. **Every write operation must go through the approval workflow** — no direct-execute actions are introduced in this milestone. Changefeed write operations continue to follow its existing (pre-Tools-page) action model unless explicitly re-scoped.

**Proposed write operations:**

| Sub-tab | Operation | Notes |
|---------|-----------|-------|
| DM | Cancel a running DM job | Targets a specific job. |
| DM | Retry / re-run a precheck | Initiates a new precheck against the cluster. |
| Import | Cancel an in-progress import task | Resolves Open Question #3. |
| Backup | Edit backup settings | Including Auto Backup, Backup Cycle / Time, Retention, PiTR, Dual Region Backup. |
| Backup | Trigger a manual backup | On-demand snapshot. |
| Backup | Change retention policy (`delete` / `retain`) or protected flag on an existing backup | Per-backup override. |
| Restore | Start a restore operation | Snapshot / PiTR / volume-snapshot modes. |

**Approval workflow requirements:**

- Every write operation initiated from this UI must be submitted as an approval request; no operation is applied directly.
- Each request captures: initiating operator, target cluster, operation type, operation parameters (for settings edits, a diff of old vs. new values), and a mandatory reason / justification.
- The request enters the Management Portal's existing approval service and is not executed until approved by an authorized reviewer.
- Requested, in-flight, approved, rejected, and executed states must be visible to the initiator and reviewers.
- A full audit trail (request, approval decision, execution result) is retained and queryable.

**Explicitly out of scope for Milestone 2:**

- Direct-execute (bypass-approval) paths for any write operation, including "emergency" cancels.
- Bulk write operations across multiple clusters.
- Self-service approval (the initiator cannot approve their own request).

**Goal:** Enable operators to act on what they observe in Milestone 1, while preserving the auditability and dual-control guarantees required for production DBaaS operations.

---

## 10. Open Questions

All questions resolved on 2026-04-24. Resolutions are reflected in the BE / FE tech-design docs and the dataflow-service requirements doc.

| # | Question | Owner | Status | Resolution |
|---|----------|-------|--------|------------|
| 1 | For Dedicated DM, a new `ListPrechecks(cluster_id)` backend API endpoint is needed to support the Precheck History sub-tab. Precheck records exist in the database keyed by cluster, but no list-by-cluster API currently exists in the Dedicated DM gRPC service. Backend confirmation and implementation scope needed. | Backend | Resolved | **Approved.** A new `ListPrechecks(cluster_id)` RPC is added to both Dedicated DM (`dm.Service`) and Premium DM (`dataflow-service-ng`). Tracked as items D-5 and N-3 in the dataflow-service requirements doc. |
| 2 | The Backup Settings panel edit flow and intermediate states (`editing_region`, `editing_pitr`) are not covered here. A separate interaction design is needed for the settings edit UX, including validation rules and error handling. This applies to Milestone 2. | UX | Resolved | **Out of scope for M1.** M1 is read-only across every sub-tab; no modification operations are exposed. The Backup Settings panel renders the existing settings as read-only descriptions. The settings-edit UX will be designed under M2. |
| 3 | Should the Import sub-tab support a "Cancel" action for in-progress import tasks? If yes, it is delivered in Milestone 2 via the approval workflow. | PM | Resolved | **No.** No Cancel action on imports in M1 or M2. The Import sub-tab remains read-only. |
| 4 | Which role(s) are authorized to approve each class of write operation in Milestone 2 (e.g., backup-settings edits vs. restore vs. DM job cancels)? Needs alignment with the existing approval-service role model. | Security / PM | Resolved | **Same role model as Changefeed.** M2 write operations on the Tools page reuse the approval roles already defined for Changefeed write operations — no new role definitions, no new approval templates beyond what Changefeed already uses. Concrete per-operation mapping will be confirmed when M2 is scoped. |
| 5 | URL scheme and authentication for the external Tools page: does it live under the same Management Portal origin (sharing the existing session), or a dedicated subdomain? What URL parameters encode the cluster context, and are they validated server-side? | Frontend / Security | Resolved | **Same origin / same domain.** The Tools page is a new SPA route inside `management-portal-ui` at `/orgs/:org_id/clusters/:cluster_id/tools`, opened via `window.open(_, '_blank')`. It shares the existing portal session — no new auth, no subdomain. Cluster context comes from the path; backend handlers validate `cluster_id` via the existing `CheckClusterScope` check. |
| 6 | Should the overview panel's "TiDB Tool Health Snapshot" counters auto-refresh (e.g., every 30s), or only refresh on explicit user action / sub-tab switch? Affects backend request volume. | UX / Backend | Resolved | **No auto-refresh.** The TiDB Tool Health Snapshot refreshes only when the user switches sub-tabs (which invalidates the `['tools', cluster_id]` query prefix) or clicks the explicit refresh button. No timer-based polling on the Overview panel in M1. |