mnote/design/05-editor-mainline/done/5-30-sidebar-starred-shortcuts-sqlite-scoped-explorer-v1.md

5-30 Sidebar 星标置顶快捷入口与 Scoped Explorer 设计 v1

状态：done Owner：05-editor-mainline / 03-rust-web / control-plane 背景：星标置顶需要对齐 Wolai 的 Sidebar 顶部快速访问体验，但 MNote 还需要支持把高频本地文件夹固定成 Explorer scoped root，避免每次进入大 workspace 时加载完整根目录。

目标

星标置顶不是文件或文件夹自身的属性，而是用户在 Sidebar 固定的一组快捷入口。

• 当前页面 .md 可以加入星标置顶，点击后直接打开该页面。
• FileTree 文件夹右键可以加入星标置顶，点击后切到 Explorer，并把该文件夹作为临时 scoped root 显示。
• 星标置顶按登录用户持久化到 SQLite control-plane；同一用户在不同设备登录时应看到同一组快捷入口。
• 顶栏“全网公开”不能默认误导显示；没有真实公开分享状态时隐藏。
• scoped Explorer 必须避免扫描完整大 workspace，例如 /mnt/Data1T/mnote 下只打开 design/ 时只加载 design/ 子树。

非目标

• 不把星标写入 Markdown frontmatter。
• 不写入 .mnote/starred-pins.json 作为长期真相。
• 不把文件夹变成 Resource Tree 的业务属性。
• 不在前端 localStorage 中持久化最终星标真相；前端最多做加载态/乐观态缓存。
• 不在本阶段实现跨设备文件内容同步；本设计只定义用户快捷入口在 control-plane 的一致性。

用户模型

星标置顶等价于“我的 Sidebar 快捷入口”：

• 页面快捷入口：kind=page，目标是某个 workspace 下的页面 identity。
• 文件夹快捷入口：kind=folder，目标是某个 workspace 下的相对路径 scope。
• 快捷入口属于用户，不属于文件夹，不影响其他用户。
• 如果某台设备没有对应 workspace 或没有该 folder 相对路径，星标项保留但显示失效态，允许移除或重新绑定。

SQLite 数据模型

新增 control-plane 表：sidebar_shortcuts。

建议字段：

CREATE TABLE sidebar_shortcuts (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  root_uri TEXT,
  kind TEXT NOT NULL, -- page | folder
  source_kind TEXT NOT NULL DEFAULT 'local_folder',
  target_id TEXT NOT NULL,
  relative_path TEXT,
  document_id TEXT,
  title TEXT NOT NULL,
  icon TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active',
  metadata_json TEXT NOT NULL DEFAULT '{}',
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  revision INTEGER NOT NULL DEFAULT 1,
  UNIQUE(user_id, workspace_id, kind, target_id)
);

target_id 规范：

• 页面：优先 document_id，例如 local-md:design%2FREADME.md。
• 文件夹：local-dir:<encoded relative path> 或稳定的 local:folder:<relative path> 归一化值。

relative_path 用于 scoped Explorer 与跨设备路径映射，必须保存 workspace 内相对路径，不保存绝对本机路径作为主键。

root_uri 必须作为显式字段保存和返回，而不是只塞在 metadata_json 中。原因：

• 星标文件夹点击必须直接消费保存时的 workspace root 上下文，不能从 workspace_id 字符串反推本机路径。
• local workspace id 是派生标识，不是路径编码协议；用它反推 file:///... 会把 UI fallback 变成事实源。
• metadata_json.rootUri 只作为兼容冗余字段，不能作为唯一来源。

长期跨设备映射仍以 workspace_id + relative_path 为主；当前设备打开本地 workspace 时必须把实际 root_uri 一起写入 shortcut，缺失时应显示失效/需重绑定状态，而不是自动猜测路径。

API / 命令面

新增最小 API：

• GET /api/sidebar/shortcuts?workspaceId=...
  • 返回当前用户当前 workspace 的星标快捷入口。
• POST /api/sidebar/shortcuts
  • upsert 快捷入口。
  • body 包含 workspaceId/rootUri/kind/sourceKind/targetId/relativePath/documentId/title/icon。
• DELETE /api/sidebar/shortcuts/:id
  • 移除当前用户自己的快捷入口。

实现边界：

• API 只操作 control-plane 用户快捷入口表。
• API 不写本地文件，不改 Markdown，不改 .mnote 元数据。
• 写操作要求真实登录用户；dev fallback 不应静默创建跨用户快捷入口。
• 每次写入追加 audit：sidebar.shortcut.created / sidebar.shortcut.removed。
• 后续需要实时同步时，通过 outbox_events 或现有 WS delta 广播 sidebar.shortcut.*。

Projection 与 Sidebar 渲染

WorkspaceShellProjection.starred_items 需要从 documents[].is_starred 迁移为 control-plane sidebar_shortcuts 投影。

投影项扩展：

• id
• title
• kind: page | folder
• href
• workspaceId
• sourceKind
• targetId
• relativePath
• rootUri
• documentId
• active
• unavailable

页面快捷入口：

• href 指向当前页面打开 URL。
• 点击后走现有 document open 主链。

文件夹快捷入口：

• href 可为当前页面 URL 加 query，例如 ?treeView=filetree&filetreeScope=design。
• 更推荐 runtime 拦截点击，调用 openScopedFileTree(relativePath)，避免不必要的页面跳转。
• 点击后切换到 Explorer tab，并显示 scoped Explorer。

Scoped Explorer 行为

文件夹星标点击后：

1. Sidebar 切到 Explorer tab。
2. Explorer 标题显示 scoped 状态，例如 Explorer / design。
3. FileTree root 只渲染该文件夹下的 children。
4. 子目录继续按需加载。
5. 提供“返回工作区根”入口；点击后恢复 root Explorer。

数据读取：

• scoped root 为 relativePath=design 时，调用现有 load_local_folder_file_tree_children_snapshot(rootUri, "design") 或对应 API。
• 不调用完整 root snapshot。
• 不预加载 scoped root 之外的兄弟目录。

URL / 状态：

• scoped 状态可以写入 URL query：treeView=filetree&filetreeScope=design。
• 刷新页面后恢复 scoped Explorer。
• 切回“我的页面”不清除 scope；点击“返回工作区根”才清除 scope。

顶栏星标与公开状态

顶栏星标按钮：

• 未星标：空心星；tooltip 对齐 Wolai：“点击 加入星标置顶，可在左侧边栏顶部快速访问”。
• 已星标：高亮星；tooltip “取消星标置顶”。
• 点击当前页面星标只操作 sidebar_shortcuts。

顶栏公开状态：

• wolai-public-pill 只有当当前页面存在 active share link / public permission 时显示。
• 没有公开状态时隐藏，不显示“全网公开”。
• 公开分享弹窗仍属于 share link / permission 领域，不与星标快捷入口混用。

FileTree 右键菜单

文件夹行增加：

• 未星标：加入星标置顶
• 已星标：取消星标置顶

启用条件：

• sourceKind == local_folder
• rowKind == folder | directory | index
• 当前用户对 workspace 有至少 read access；写入快捷入口只需要用户偏好写权限，不要求文件系统写权限。

不支持项：

• 普通附件文件暂不加入星标置顶。
• 多选批量星标暂不做。

失效与重命名处理

MVP 处理：

• 文件夹被删除：快捷入口保留，显示失效态；点击提示“文件夹不存在”，允许移除。
• 文件夹重命名：如果重命名由 MNote 发起，可同步更新对应 relative_path/title/target_id；如果外部重命名，先显示失效态。
• 页面被删除：页面快捷入口显示失效态，允许移除。

长期可选：

• 引入 local object stable id 后，星标目标可由 stable object id 跟随重命名。

验收标准

• 无公开分享状态时，顶栏不显示“全网公开”。
• 当前页面点击星标后，Sidebar 星标置顶出现该页面；再次点击移除。
• 右键 design/ 文件夹可加入星标置顶。
• 点击 design/ 星标后，切到 Explorer scoped root，只加载并显示 design/ 下内容，不显示 workspace root 的其他大目录。
• 刷新页面后，filetreeScope=design 能恢复 scoped Explorer。
• 同一用户重新登录后，星标快捷入口仍存在。
• 不同用户登录同一 workspace 时，星标列表互不污染。
• 文件夹不存在时，星标项显示失效态并可移除。

测试计划

Rust/control-plane：

• migration 创建 sidebar_shortcuts。
• store 可 upsert/list/delete 当前用户快捷入口。
• unique 约束防止同一用户同一 workspace 重复固定同一目标。
• 不同用户同一目标互不影响。

mnote-web：

• API 鉴权：只能读写当前用户自己的快捷入口。
• WorkspaceShellProjection 从 shortcuts 投影 starred rows。
• local folder scoped snapshot 不扫描完整 root。

浏览器 smoke：

• 顶栏公开 pill 隐藏断言。
• 顶栏星标页面 add/remove。
• FileTree 文件夹右键 add/remove。
• 点击星标文件夹进入 scoped Explorer，并断言 root siblings 不渲染。
• 刷新恢复 scoped Explorer。

实施顺序

1. control-plane migration / model / store：新增 sidebar_shortcuts。
2. mnote-web API：list/upsert/delete shortcuts。
3. workspace shell projection：星标区改读 shortcuts，并保留历史 is_starred fixture 兼容测试。
4. 顶栏：星标按钮接 API；公开 pill 改为条件显示。
5. FileTree 右键菜单：文件夹加入/取消星标置顶。
6. Scoped Explorer runtime：支持 filetreeScope，只加载 scoped children，并提供返回 root。
7. smoke 与 Rust 测试补齐。

决策记录

• 2026-05-26：星标置顶确定为用户级 Sidebar 快捷入口，不是文件夹/页面自身属性。
• 2026-05-26：星标快捷入口必须写入 SQLite control-plane，满足同一用户跨设备一致显示。
• 2026-05-26：文件夹星标点击进入 scoped Explorer，避免大 workspace root 扫描。
• 2026-06-01：只读复核确认 sidebar_shortcuts migration/store/API、显式 rootUri、scoped Explorer 与 task492-sidebar-starred-shortcuts-smoke.js 已覆盖本文主验收；本文归档到 done/。