[SIP-223] Add hierarchical dashboard folders

## [SIP] Proposal for hierarchical dashboard folders

### Motivation

Large Superset deployments can contain hundreds or thousands of dashboards. The current flat dashboard list relies mainly on search, editorship, status, and tags, which makes repeated navigation and delegated organization difficult. This proposal adds an optional hierarchical folder structure to the dashboard list while keeping existing dashboards uncategorized by default.

### Proposed Change

Add hierarchical dashboard folders to the dashboard list. Users with the corresponding permissions can create, rename, move, and delete folders, and move dashboards into an editable folder or back to the uncategorized root. The folder tree is collapsible and synchronized with the existing Folder list filter. Selecting a folder filters the dashboard list, while selecting a Folder filter expands and selects the matching tree path.

Folder authorization follows Superset's unified `Subject` model rather than a user-only ownership table. A folder has independent `editors` and `viewers` relations backed by Subjects, so access can be assigned consistently to users, roles, or groups:

- Folder editors may mutate the folder when they also have the corresponding `DashboardFolder` action permission.
- Folder viewers may see and use the folder for navigation, but cannot mutate it or select it as a write target.
- Administrators can manage all folders.
- Creating a folder without an explicit editor list assigns the current user's Subject as an editor, following the existing asset-editorship behavior.
- Folder access does not grant access to dashboards inside the folder. Dashboard visibility continues to use the existing dashboard access rules.
- Returning an ancestor folder for wayfinding does not implicitly grant editorship on that ancestor.

For non-administrators, the visible tree contains folders for which one of the current principal's Subjects is an editor or viewer, folders containing dashboards the principal can access, and the ancestor paths required to render those folders. Read-only folders remain usable for navigation but cannot be selected as write targets. Folder names are trimmed and compared case-insensitively; duplicate names within the same parent and a child matching its parent name are rejected. The navigation tree does not display dashboard counts, keeping the narrow sidebar focused on folder wayfinding.

Deleting an authorized folder subtree preserves dashboards by moving them to the uncategorized root before removing the folders. This avoids destructive dashboard deletion.

### New or Changed Public Interfaces

- Add the `DashboardFolder` metadata model.
- Add `dashboard_folder_editors` and `dashboard_folder_viewers` Subject association tables, following the existing asset editor/viewer model.
- Add nullable `Dashboard.folder_id`.
- Add `GET /api/v1/dashboard_folder/` for the visible folder tree and access-scoped counts. Folder data exposes compact `editors` and `viewers` Subject representations.
- Add `POST /api/v1/dashboard_folder/` to create a folder. Optional `editors` and `viewers` fields contain Subject IDs.
- Add `PUT /api/v1/dashboard_folder/` to rename or move a folder and update its editor/viewer Subjects.
- Add `DELETE /api/v1/dashboard_folder/` to delete an authorized folder subtree and uncategorize its dashboards.
- Add `PUT /api/v1/dashboard_folder/dashboard/` to move a dashboard or return it to the uncategorized root.
- Add `DashboardFolder` permissions for read, create, rename, delete, and move-dashboard operations.
- Extend the dashboard list filter contract with an optional folder filter.
- Add a collapsible folder tree and dashboard move workflow to the dashboard list UI.

No existing dashboard URL, chart URL, CLI command, or deployment interface changes.

### Relationship to SIP-219

The folder panel is a natural candidate for a Dashboard List contribution point under [SIP-219](https://github.com/apache/superset/issues/41779). The initial implementation keeps the folder panel isolated as a built-in component so that it can be registered and resolved through the uniform extension architecture after SIP-219 is accepted and the Dashboard List contribution contract is defined.

This proposal does not introduce a provisional extension registry or define a competing public extension API. SIP-219 alignment affects how the Dashboard List loads the folder panel; it does not replace the folder metadata model, Subject-based authorization, migration, or REST API described here. The extension registration work will be tracked as a follow-up against the accepted SIP-219 architecture.

### New Dependencies

None. The implementation uses existing Superset backend, frontend, Subject authorization, and UI dependencies.

### Migration Plan and Compatibility

The migration creates `dashboard_folders`, `dashboard_folder_editors`, and `dashboard_folder_viewers`; adds the nullable `dashboards.folder_id` foreign key and index; and uses `ON DELETE SET NULL` for dashboard-folder associations. The editor and viewer association tables reference `subjects.id` with cascading deletion and enforce uniqueness for each Subject/folder pair.

Existing dashboards remain valid and uncategorized because `folder_id` defaults to `NULL`. Because the folder schema has not been released, the proposal creates the Subject association tables directly and does not introduce a legacy `dashboard_folder_user` table or a compatibility migration for it.

The downgrade removes the dashboard index, foreign key, and column before dropping the new Subject association and folder tables. The implementation uses the existing Superset migration helpers and batch-alter pattern. No data rewrite or service downtime is expected beyond the normal metadata schema migration window. Upgrade and downgrade behavior will be validated on Superset-supported database engines during review and CI, and the migration will be rebased onto the current migration head before merge.

### Rejected Alternatives

- **User-only folder owners:** This would duplicate the legacy ownership pattern and exclude role/group authorization. Subject-based editors and viewers are consistent with current Superset asset permissions.
- **Tags only:** Tags support cross-cutting classification but do not provide an opinionated navigational hierarchy or parent-child operations.
- **Client-only folders:** They cannot provide shared organization, server-side filtering, or access-scoped navigation.
- **Encoding folder paths in dashboard titles or metadata:** This is fragile, difficult to authorize, and creates rename and move consistency problems.
- **Deleting dashboards with folders:** Folder cleanup should not destroy dashboard content.
- **Defining an extension registry in this SIP:** SIP-219 owns the uniform extension contract. This proposal should integrate with that contract after it is accepted rather than introduce a competing design.

---

## [SIP] 分层仪表盘文件夹提案

### 动机

大型 Superset 部署可能包含数百甚至数千个仪表盘。当前扁平化仪表盘列表主要依赖搜索、编辑者、状态和标签，难以满足重复导航和委托式组织管理的需求。本提案为仪表盘列表增加可选的分层文件夹结构，同时让现有仪表盘默认保持“未分类”状态。

### 提议的变更

在仪表盘列表中增加分层仪表盘文件夹。具有相应权限的用户可以创建、重命名、移动和删除文件夹，并可将仪表盘移动到可编辑文件夹或移回未分类根目录。文件夹树支持折叠，并与现有的 Folder 列表筛选器同步：选择文件夹会筛选仪表盘列表，选择 Folder 筛选条件会展开并选中匹配的文件夹路径。

文件夹授权采用 Superset 统一的 `Subject` 模型，而不是仅支持用户的所有者关联表。每个文件夹分别具有由 Subject 支持的 `editors` 和 `viewers` 关系，因此可将权限一致地分配给用户、角色或用户组：

- 文件夹编辑者同时拥有对应 `DashboardFolder` 操作权限时，可以修改文件夹。
- 文件夹查看者可以查看文件夹并用于导航，但不能修改文件夹，也不能将其选作写入目标。
- 管理员可以管理所有文件夹。
- 创建文件夹时如果没有显式指定编辑者列表，则按照现有资源编辑权限行为，将当前用户对应的 Subject 设为编辑者。
- 文件夹访问权限不会授予其中仪表盘的访问权限；仪表盘可见性仍遵循现有仪表盘访问规则。
- 为了导航而返回祖先文件夹，不会隐式授予该祖先文件夹的编辑权限。

对于非管理员，可见文件夹树包括：当前主体任一 Subject 作为编辑者或查看者的文件夹、包含当前主体可访问仪表盘的文件夹，以及渲染这些文件夹所必需的祖先路径。只读文件夹仍可用于导航，但不能作为写入目标。文件夹名称会去除首尾空格并进行不区分大小写的比较；同一父文件夹下不允许重名，子文件夹名称也不能与其父文件夹相同。导航树不显示仪表盘数量，使窄侧边栏专注于文件夹导航。

删除经过授权的文件夹子树时，会先将其中仪表盘移动到未分类根目录，再删除文件夹，从而避免破坏性删除仪表盘。

### 新增或变更的公共接口

- 新增 `DashboardFolder` 元数据模型。
- 新增 `dashboard_folder_editors` 和 `dashboard_folder_viewers` Subject 关联表，与现有资源编辑者/查看者模型保持一致。
- 为 `Dashboard` 新增可空的 `folder_id`。
- 新增 `GET /api/v1/dashboard_folder/`，返回可见文件夹树和按访问权限过滤的统计数据；文件夹数据包含精简的 `editors` 和 `viewers` Subject 表示。
- 新增 `POST /api/v1/dashboard_folder/` 创建文件夹；可选的 `editors` 和 `viewers` 字段包含 Subject ID。
- 新增 `PUT /api/v1/dashboard_folder/`，用于重命名或移动文件夹，以及更新其编辑者/查看者 Subject。
- 新增 `DELETE /api/v1/dashboard_folder/`，删除经过授权的文件夹子树，并将其中仪表盘移至未分类状态。
- 新增 `PUT /api/v1/dashboard_folder/dashboard/`，移动仪表盘或将其移回未分类根目录。
- 新增 `DashboardFolder` 的读取、创建、重命名、删除和移动仪表盘权限。
- 扩展仪表盘列表筛选契约，增加可选的文件夹筛选条件。
- 在仪表盘列表 UI 中新增可折叠文件夹树和仪表盘移动流程。

现有仪表盘 URL、图表 URL、CLI 命令和部署接口均不变。

### 与 SIP-219 的关系

根据 [SIP-219](https://github.com/apache/superset/issues/41779)，文件夹面板是 Dashboard List 扩展贡献点的自然候选。初始实现将文件夹面板保持为独立的内置组件；在 SIP-219 获得接受且 Dashboard List 的贡献契约确定后，可以通过统一扩展架构对其进行注册和解析。

本提案不会引入临时扩展注册表，也不会定义与 SIP-219 竞争的公共扩展 API。与 SIP-219 对齐所影响的是 Dashboard List 加载文件夹面板的方式，并不会替代本提案描述的文件夹元数据模型、基于 Subject 的授权、数据库迁移或 REST API。扩展注册工作将作为后续任务，按照最终通过的 SIP-219 架构进行跟踪。

### 新增依赖

无。实现使用 Superset 现有的后端、前端、Subject 授权和 UI 依赖。

### 迁移计划与兼容性

迁移将创建 `dashboard_folders`、`dashboard_folder_editors` 和 `dashboard_folder_viewers`；为 `dashboards` 增加可空的 `folder_id` 外键及索引；仪表盘与文件夹的关联采用 `ON DELETE SET NULL`。编辑者和查看者关联表引用 `subjects.id`，使用级联删除，并确保每个 Subject/文件夹组合唯一。

由于 `folder_id` 默认为 `NULL`，现有仪表盘仍然有效并保持未分类。因为文件夹模式尚未发布，本提案将直接创建 Subject 关联表，不引入旧式 `dashboard_folder_user` 表，也不为其增加兼容迁移。

降级操作会先移除仪表盘索引、外键和字段，再删除新的 Subject 关联表和文件夹表。实现沿用 Superset 现有迁移辅助函数和 batch-alter 模式。除正常的元数据模式迁移窗口外，不预计需要数据重写或服务停机。评审和 CI 期间会在 Superset 支持的数据库引擎上验证升级与降级，并在合并前将迁移重新基于最新 migration head。

### 已拒绝的替代方案

- **仅支持用户的文件夹所有者：** 这会重复旧式所有权模式，并排除角色/用户组授权。基于 Subject 的编辑者和查看者与当前 Superset 资源权限保持一致。
- **仅使用标签：** 标签适合横向分类，但无法提供明确的导航层级或父子操作。
- **仅客户端文件夹：** 无法提供共享组织、服务端筛选或按访问权限过滤的导航。
- **在仪表盘标题或元数据中编码文件夹路径：** 这种方式脆弱、难以授权，并会产生重命名和移动的一致性问题。
- **删除文件夹时同时删除仪表盘：** 清理文件夹不应破坏仪表盘内容。
- **在本 SIP 中定义扩展注册表：** 统一扩展契约属于 SIP-219。本提案应在 SIP-219 获得接受后与其集成，而不是引入竞争性设计。

No implementation files or tests are named. Start by reading the existing dashboard list, Subject-based asset authorization, and migration patterns, then trace the proposed DashboardFolder REST endpoints and UI workflow; done means folders, permissions, filtering, dashboard moves, migrations, and upgrade/downgrade behavior are implemented and validated.

Written by the indexing model from the issue text.