feat: 菜单管理（侧边栏覆盖层）

管理员可对一/二/三级菜单（含注入的 iframe 轻应用节点）改名、停用/启用、排序、跨层级移动。静态菜单仍是图标/路由来源，后端只存每节点覆盖项。后端: /api/menu-overrides（全局共享；开放读、admin 原子替换；≤3 级校验），新增 persistence/menu_overrides 持久化层（create_all 自动建表）。前端: 合并逻辑 menu-overrides.ts、MenuManagementPage（@dnd-kit 拖拽+移动到父级选择器+上下箭头+改名/停用）、左下角设置入口、Header/侧边栏自动生效。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 23:34:12 +08:00
1 parent 8d0759123a
commit 1c8b5b23a1
@@ -252,6 +252,7 @@ FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWA
 | **HTML Page Favorites** (`/api/html-page-favorites`) | Bookmarked generated HTML pages, owner-scoped. `GET /` - list; `POST /` `{page_id, title?, description?, tags?}` - bookmark a `scheduled_html_pages` row (extracts a reusable style/layout summary via GLM5 at favorite time); a page can only be favorited once per user (`DuplicateFavoriteError` ? HTTP 409). `GET/DELETE /{id}` - read/delete (the create-task reference picker deletes favorites here). A favorite can be selected as a style reference when creating a new `html_page` task. |
 | **Public Scheduled Tasks** (`/api/public/scheduled-tasks`) | **Unauthenticated** mirror for embedding. Adds `GET /runs/{rid}/html` and `GET /{task_id}/latest-html` for the `html_page` preview; the run result keeps `result.html` (only file paths are redacted). |
 | **Light Apps** (`/api/light-apps`) | Light-app registry (????? / ????), **global/shared** (no user scoping; `created_by`/`updated_by` audit-only). Two kinds: `window_open` (launched in a new tab from the ???? card grid) and `iframe` (embedded under a parent sidebar menu via `mount_location` and dynamically injected into the sidebar). Both carry `route_params` ? a list of `{key, paramType: login\|theme, source, customValue, themeValue}` descriptors the **frontend** resolves at launch time (login params read from `localStorage.userInfo`; theme params use a literal value) and appends to `url` as query string. `GET /` - list (filters `app_type`/`mount_location`/`enabled_only`/`search`); `GET /{app_id}` - read one (both open to any authenticated user); `POST /`, `PUT /{app_id}`, `DELETE /{app_id}` - **admin only**; iframe apps must carry a `mount_location` (400 otherwise); the unique `name` collides as HTTP 409. Backed by `deerflow.persistence.light_apps` (table `light_apps`, auto-created by `create_all`); store wired in `deps.py` as `app.state.light_app_store`. Tests: `tests/test_light_apps.py`. |
+| **Menu Overrides** (`/api/menu-overrides`) | Sidebar-menu overrides (菜单管理), **global/shared** (no user scoping; `updated_by` audit-only). The static menu tree (icons/routes/`adminOnly`) lives in the **frontend** code (`core/page-layout/sidebar-menu.ts`); iframe light-apps are injected at render time. This router persists a per-node **overlay** the frontend merges onto that tree: `parent_id` (re-parent, moves the whole subtree; NULL = top level), `sort_order` (reorder among siblings), `label` (rename; NULL keeps code label), `disabled` (停用 — hides the node **and its subtree**). A node with no row renders exactly as code defines it, so new code menus / newly-registered iframe apps appear automatically and are immediately configurable. `GET /` - list all overrides (open to any authenticated user); `PUT /` - **admin only**, atomically **replaces the whole set** (`{overrides: [...]}`); rejects re-parenting that would exceed **3 levels** or form a cycle (`_validate_depth`, HTTP 400). Backed by `deerflow.persistence.menu_overrides` (table `menu_overrides`, auto-created by `create_all`); store wired in `deps.py` as `app.state.menu_override_store`. Frontend: merge logic `core/page-layout/menu-overrides.ts` (`applyMenuOverrides` in `use-sidebar-menu.ts`), client `strategy-components/api/menu-overrides.ts`, admin page `pages/MenuManagementPage.tsx` (@dnd-kit drag-reorder/re-parent + 「移动到」parent selector + ↑↓ arrows + 改名/停用), entry in the bottom-left settings dropdown (`components/page-sidebar.tsx`, admin-only). Tests: `tests/test_menu_overrides.py`, `frontend-web/src/core/page-layout/menu-overrides.test.ts`. |
 | **Knowledge** (`/api/knowledge`) | Product knowledge base, **global/shared** (no user isolation; writes record `created_by`/`updated_by` for audit). `POST /ingest/thread/{thread_id}` - sediment one thread into a note (reads messages from the checkpointer, `threads:read` owner-checked); `POST /ingest/threads/batch` - batch-sediment the caller's recent threads (`skip_existing` via `.manifest.json` dedup). **Defaults to `background=true`**: the slow per-thread extraction loop is deferred to a FastAPI background task and the endpoint returns `{queued:true, processed:N}` immediately (each thread's transcript is truncated to `max_input_chars` before the LLM call). Running the loop inline for a large batch outlives the nginx gateway timeout (504), which the frontend's `parseResponse` surfaces as a generic "Request failed"; `background=false` keeps the blocking path (full per-thread `created/skipped/failed` tally) for small batches/scripts. Shared loop: `_run_batch_ingest`. **Optional model selection**: both ingest endpoints accept `model_name` (overrides `knowledge.extract_model_name` for that capture; threaded through `KnowledgeService.capture_thread` ? `extract_thread_llm_multi`). **Model-error surfacing**: when the chosen model produces nothing usable (timeout / API error / non-JSON) capture still **falls back to rule-based extraction and lands a draft** (`llm_fallback:true`); the single-thread (non-background) response and the batch response (`llm_fallback` count) carry this so the UI tells the user "???????". The "??????" chat button stays background/fire-and-forget (passes `model_name`, no per-save error toast); the batch-import dialog is synchronous and shows the fallback count. `POST /ingest/file` - **import an uploaded file** (multipart: `file` + optional `title`/`tags`/`status`/`model_name`) into wiki note(s): the file is converted to Markdown (md/txt read directly, pdf/word/ppt/excel via `convert_file_to_markdown`), distilled by the same wiki-capture LLM pipeline as thread capture (`source_type="file"`), and falls back to a verbatim **draft** note when the model returns nothing usable (`llm_fallback:true`); `POST /ingest/search` - sediment search/tool results as a reference note; `POST /notes` - manual note; `GET /notes` (keyword/tag/source_type/status + pagination); `GET/PUT/DELETE /notes/{id}` (DELETE is soft = archive, `?hard=true` removes the vault file); `POST /search` - `mode=keyword\|vector\|hybrid` (vector?keyword fallback when no embedding endpoint); `GET /notes/{id}/versions` - edit history; `GET /duplicates` + `POST /merge` - dedup; `POST /reindex` - rebuild vector index; `GET /graph` - product graph data (notes + entities, graph-blacklist filtered); `GET/POST /graph/blacklist` + `DELETE /graph/blacklist/{id}` - graph node blacklist (labels = entity names / note titles, case-insensitive match; blacklisted nodes and their edges are dropped from `/graph` and the wiki-export artifacts; table `knowledge_graph_blacklist`, auto-created); `POST /export/graph` + `GET /export/files/{graph.json\|graph.html\|graph.graphml\|cypher.txt}` - obsidian-wiki `wiki-export` artifacts (self-contained `graph.html` for iframe); `POST /resolve` `{targets:[?]}` + `GET /notes/{id}/wikilinks` - resolve `[[wikilink]]` targets to a note id / vault page / missing (powers clickable wikilinks); `GET /vault-page?path=` - read a raw vault meta/hub Markdown page (no DB note). `GET/POST /folders` + `PUT/DELETE /folders/{id}` - user-managed directories (notes carry a `folder` path; `GET /notes?folder=` filters a dir + sub-dirs); `GET/POST /extract-templates` + `GET/PUT/DELETE /extract-templates/{id}` - editable extraction-prompt templates (thread/document ingest accept `template_id`; capture/PUT-note accept `folder`). Backed by the `deerflow.knowledge` module (see below). |

 Proxied through nginx: `/api/langgraph/*` ? LangGraph, all other `/api/*` ? Gateway.
@@ -45,6 +45,7 @@ from app.gateway.routers import (
    llm_metrics,
    mcp,
    memory,
+    menu_overrides,
    models,
    multi_agent,
    notifications,
@@ -1339,6 +1340,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
    # Light-app registry (?????) at /api/light-apps
    app.include_router(light_apps.router)

+    # Sidebar-menu overrides (菜单管理) at /api/menu-overrides
+    app.include_router(menu_overrides.router)
+
    # Standalone parallel multi-agent panel: fan-out streaming + saved tasks
    app.include_router(parallel_agents.router)
    app.include_router(parallel_agent_tasks.router)
@@ -239,6 +239,10 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:

        app.state.light_app_store = make_light_app_store(sf)

+        from deerflow.persistence.menu_overrides import make_menu_override_store
+
+        app.state.menu_override_store = make_menu_override_store(sf)
+
        from deerflow.persistence.parallel_agent_tasks import make_parallel_agent_task_store

        app.state.parallel_agent_task_store = make_parallel_agent_task_store(sf)
@@ -0,0 +1,123 @@
+"""Sidebar-menu override API (菜单管理).
+
+The static sidebar menu tree (icons / routes / adminOnly) is defined in the
+frontend code; iframe light-apps are injected into it at render time. This
+router persists a **global / shared** set of per-node overrides that the
+frontend merges onto that tree: rename (``label``), 停用/启用 (``disabled``),
+reorder (``sort_order``) and re-parent (``parent_id``, moving a node's whole
+subtree). A node with no override renders exactly as the code defines it.
+
+Reads are open to any authenticated user (the sidebar needs them); the whole
+override set is replaced atomically and only by an admin.
+
+Routes (prefix ``/api/menu-overrides``):
+    GET ""   list all overrides
+    PUT ""   replace the entire override set (admin)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_current_user, get_optional_user_from_request
+from deerflow.persistence.menu_overrides import MenuOverrideStore
+
+router = APIRouter(prefix="/api/menu-overrides", tags=["menu-overrides"])
+
+# Hard cap mirroring the sidebar's 一级 → 二级 → 三级 rendering depth.
+_MAX_DEPTH = 3
+
+
+# ── schemas ──────────────────────────────────────────────────────────────
+
+
+class MenuOverride(BaseModel):
+    node_id: str = Field(..., min_length=1, max_length=128)
+    parent_id: str | None = Field(default=None, max_length=128)
+    sort_order: int = 0
+    label: str | None = Field(default=None, max_length=255)
+    disabled: bool = False
+
+
+class MenuOverrideResponse(MenuOverride):
+    updated_by: str | None = None
+    updated_at: datetime | str | None = None
+
+
+class MenuOverrideListResponse(BaseModel):
+    overrides: list[MenuOverrideResponse]
+
+
+class MenuOverrideReplaceRequest(BaseModel):
+    overrides: list[MenuOverride] = Field(default_factory=list)
+
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+
+def _get_store(request: Request) -> MenuOverrideStore:
+    store = getattr(request.app.state, "menu_override_store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="Menu override store not available")
+    return store
+
+
+async def _require_admin(request: Request) -> None:
+    """Reject non-admins. Lets the call through when auth is disabled."""
+    user = await get_optional_user_from_request(request)
+    if user is None:
+        return
+    if getattr(user, "system_role", None) != "admin":
+        raise HTTPException(status_code=403, detail="菜单管理仅限管理员")
+
+
+def _validate_depth(overrides: list[MenuOverride]) -> None:
+    """Reject cycles and any node whose effective depth exceeds 3 levels.
+
+    Only nodes that appear in the override set carry an explicit ``parent_id``;
+    a node absent from the set keeps its code-defined parent (which is at most
+    3 levels deep by construction). So validating the override graph alone is
+    sufficient to stop an admin from pushing a 4th level via re-parenting.
+    """
+    parent_of = {o.node_id: o.parent_id for o in overrides}
+
+    for node_id in parent_of:
+        depth = 1
+        seen = {node_id}
+        cursor = parent_of[node_id]
+        while cursor:
+            depth += 1
+            if depth > _MAX_DEPTH:
+                raise HTTPException(status_code=400, detail=f"菜单「{node_id}」层级超过 {_MAX_DEPTH} 级")
+            if cursor in seen:
+                raise HTTPException(status_code=400, detail=f"菜单「{node_id}」存在循环引用")
+            seen.add(cursor)
+            # A parent that is not itself in the override set is a code node at a
+            # known depth ≤ 3, so the chain terminates there.
+            cursor = parent_of.get(cursor)
+
+
+# ── routes ───────────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=MenuOverrideListResponse)
+async def list_menu_overrides(request: Request) -> MenuOverrideListResponse:
+    store = _get_store(request)
+    rows = await store.list_overrides()
+    return MenuOverrideListResponse(overrides=[MenuOverrideResponse(**r) for r in rows])
+
+
+@router.put("", response_model=MenuOverrideListResponse)
+async def replace_menu_overrides(request: Request, body: MenuOverrideReplaceRequest) -> MenuOverrideListResponse:
+    await _require_admin(request)
+    _validate_depth(body.overrides)
+    store = _get_store(request)
+    user_id = await get_current_user(request)
+    rows = await store.replace_all(
+        [o.model_dump() for o in body.overrides],
+        updated_by=user_id,
+    )
+    return MenuOverrideListResponse(overrides=[MenuOverrideResponse(**r) for r in rows])
@@ -0,0 +1,22 @@
+"""Sidebar-menu override persistence (菜单管理)."""
+
+from __future__ import annotations
+
+from deerflow.persistence.menu_overrides.base import MenuOverrideStore
+from deerflow.persistence.menu_overrides.memory import MemoryMenuOverrideStore
+from deerflow.persistence.menu_overrides.model import MenuOverrideRow
+from deerflow.persistence.menu_overrides.sql import MenuOverrideRepository
+
+__all__ = [
+    "MemoryMenuOverrideStore",
+    "MenuOverrideRepository",
+    "MenuOverrideRow",
+    "MenuOverrideStore",
+    "make_menu_override_store",
+]
+
+
+def make_menu_override_store(session_factory):
+    if session_factory is None:
+        return MemoryMenuOverrideStore()
+    return MenuOverrideRepository(session_factory)
@@ -0,0 +1,30 @@
+"""Abstract sidebar-menu override persistence API.
+
+Global / shared store: no ``user_id`` scoping. Reads are open to any caller; the
+router gates writes behind admin. ``updated_by`` is audit-only.
+
+The whole override set is treated as one document: the editor computes the full
+desired layout and replaces every row atomically via :meth:`replace_all`, so the
+stored set never drifts out of sync with what the admin sees.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class MenuOverrideStore(ABC):
+    @abstractmethod
+    async def list_overrides(self) -> list[dict[str, Any]]:
+        """Return every stored override row (order unspecified)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def replace_all(self, rows: list[dict[str, Any]], *, updated_by: str | None = None) -> list[dict[str, Any]]:
+        """Atomically replace the entire override set with ``rows``.
+
+        Each row is ``{node_id, parent_id, sort_order, label, disabled}``.
+        Returns the persisted rows.
+        """
+        raise NotImplementedError
@@ -0,0 +1,37 @@
+"""In-memory sidebar-menu override store (used when no DB is configured / tests)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from deerflow.persistence.menu_overrides.base import MenuOverrideStore
+
+
+def _normalize(data: dict[str, Any], updated_by: str | None) -> dict[str, Any]:
+    return {
+        "node_id": str(data["node_id"]),
+        "parent_id": (str(data["parent_id"]) if data.get("parent_id") not in (None, "") else None),
+        "sort_order": int(data.get("sort_order", 0)),
+        "label": (data.get("label") or None),
+        "disabled": bool(data.get("disabled", False)),
+        "updated_by": updated_by,
+        "updated_at": datetime.now(UTC).isoformat(),
+    }
+
+
+class MemoryMenuOverrideStore(MenuOverrideStore):
+    def __init__(self) -> None:
+        self._rows: dict[str, dict[str, Any]] = {}
+
+    async def list_overrides(self) -> list[dict[str, Any]]:
+        return [dict(r) for r in sorted(self._rows.values(), key=lambda r: r.get("sort_order", 0))]
+
+    async def replace_all(self, rows: list[dict[str, Any]], *, updated_by: str | None = None) -> list[dict[str, Any]]:
+        self._rows = {}
+        for r in rows:
+            node_id = r.get("node_id")
+            if not node_id:
+                continue
+            self._rows[str(node_id)] = _normalize(r, updated_by)
+        return [dict(r) for r in self._rows.values()]
@@ -0,0 +1,42 @@
+"""ORM model for sidebar-menu overrides (菜单管理).
+
+Global / shared — there is no ``user_id`` scoping; every account sees the same
+menu layout. The static menu tree (icons / routes / adminOnly) lives in the
+frontend code; this table only stores per-node **overrides** keyed by the static
+node id (or an injected iframe light-app node id ``light-app-<appId>``):
+
+- ``parent_id`` — the effective parent node id (NULL = top level). Re-parenting
+  a node moves its whole subtree.
+- ``sort_order`` — position among siblings under the effective parent.
+- ``label`` — rename; NULL keeps the code-defined label.
+- ``disabled`` — hide the node (and its subtree) from the sidebar.
+
+A node with no row here renders exactly as the code defines it. ``updated_by``
+is audit-only.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Boolean, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+from deerflow.persistence.types import BeijingDateTime
+
+
+class MenuOverrideRow(Base):
+    __tablename__ = "menu_overrides"
+
+    node_id: Mapped[str] = mapped_column(String(128), primary_key=True)
+    # Effective parent node id; NULL = top-level menu.
+    parent_id: Mapped[str | None] = mapped_column(String(128), index=True)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+    # Rename override; NULL keeps the code-defined label.
+    label: Mapped[str | None] = mapped_column(String(255))
+    disabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    updated_by: Mapped[str | None] = mapped_column(String(64))
+    updated_at: Mapped[datetime] = mapped_column(
+        BeijingDateTime(), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+    )
@@ -0,0 +1,58 @@
+"""SQLAlchemy-backed sidebar-menu override store (global / shared)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from deerflow.persistence.menu_overrides.base import MenuOverrideStore
+from deerflow.persistence.menu_overrides.model import MenuOverrideRow
+
+
+def _to_dict(row: MenuOverrideRow) -> dict[str, Any]:
+    data = row.to_dict()
+    value = data.get("updated_at")
+    if isinstance(value, datetime):
+        data["updated_at"] = value.isoformat()
+    return data
+
+
+def _row_from(data: dict[str, Any], updated_by: str | None) -> MenuOverrideRow:
+    return MenuOverrideRow(
+        node_id=str(data["node_id"]),
+        parent_id=(str(data["parent_id"]) if data.get("parent_id") not in (None, "") else None),
+        sort_order=int(data.get("sort_order", 0)),
+        label=(data.get("label") or None),
+        disabled=bool(data.get("disabled", False)),
+        updated_by=updated_by,
+    )
+
+
+class MenuOverrideRepository(MenuOverrideStore):
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+
+    async def list_overrides(self) -> list[dict[str, Any]]:
+        stmt = select(MenuOverrideRow).order_by(MenuOverrideRow.sort_order.asc())
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [_to_dict(row) for row in result.scalars()]
+
+    async def replace_all(self, rows: list[dict[str, Any]], *, updated_by: str | None = None) -> list[dict[str, Any]]:
+        # De-dupe by node_id (last wins) so a malformed payload can't violate the PK.
+        by_id: dict[str, dict[str, Any]] = {}
+        for r in rows:
+            node_id = r.get("node_id")
+            if node_id:
+                by_id[str(node_id)] = r
+        async with self._sf() as session:
+            await session.execute(delete(MenuOverrideRow))
+            new_rows = [_row_from(r, updated_by) for r in by_id.values()]
+            session.add_all(new_rows)
+            await session.commit()
+            for row in new_rows:
+                await session.refresh(row)
+            return [_to_dict(row) for row in new_rows]
@@ -40,6 +40,7 @@ from deerflow.knowledge.models import (
 )
 from deerflow.persistence.light_apps.model import LightAppRow
 from deerflow.persistence.llm_metrics.model import LlmCallMetricRow
+from deerflow.persistence.menu_overrides.model import MenuOverrideRow
 from deerflow.persistence.models.run_event import RunEventRow
 from deerflow.persistence.notifications.model import NotificationRow
 from deerflow.persistence.parallel_agent_tasks.model import ParallelAgentTaskRow
@@ -92,6 +93,7 @@ __all__ = [
    "KnowledgeTagRow",
    "LightAppRow",
    "LlmCallMetricRow",
+    "MenuOverrideRow",
    "NotificationRow",
    "ParallelAgentTaskRow",
    "PositionRow",