@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/knowledge/editor/__tests__/knowledge-doc-editor-collab.test.tsx

@@ -0,0 +1,542 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// knowledge-doc-editor 协同态改造测试（Yjs 多人协作任务 15，规格 §5.2/§6/§7.1）。
+//
+// 覆盖面（简报步骤 1 逐项）：
+//   ① collab=true：扩展含 Collaboration（fragment 默认 'default'）与
+//      CollaborationCaret（user=会话 brief+色板色）；immediatelyRender:false；
+//      SSR 快照预水合进 provider doc。
+//   ② 三通道保存短路：协同态下 2s 防抖 / 5s 轮询 / beforeunload 全部
+//      不触发 updateDocumentFn（Y 是唯一写手，双写炸弹审查重点 #3）。
+//   ③ collab=false 回归：三通道行为与现状一致（扩展无 Collaboration、
+//      三通道各自产生一次 DB 保存）。
+//   ④ 降级模式（规格「风险与回退」）：provider offline → 旧保存链路恢复 +
+//      顶部「离线单机模式」提示条（i18n）；synced → 自动切回协同（提示条
+//      消失、DB 链路再短路、未落库意图被取消——任一时刻仅一条保存链路）。
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { render, fireEvent, act } from '@testing-library/react'
+import { Suspense } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import * as Y from 'yjs'
+
+// 整编辑器挂载重（TipTap 全扩展 + 协同插件），全量并行负载下默认 5s 会超时
+vi.setConfig({ testTimeout: 60_000 })
+
+// ---------------------------------------------------------------------------
+// mock（vi.mock 提升：真实 serverFn / provider / session 均不参与）
+// ---------------------------------------------------------------------------
+
+const mocks = vi.hoisted(() => ({
+  updateDocumentFn: vi.fn(),
+  getDocumentFn: vi.fn(),
+  listDocumentsFn: vi.fn(),
+  getOrCreateProvider: vi.fn(),
+  useSession: vi.fn(),
+}))
+const mockUpdateDocumentFn = mocks.updateDocumentFn
+const mockGetDocumentFn = mocks.getDocumentFn
+const mockListDocumentsFn = mocks.listDocumentsFn
+const mockGetOrCreateProvider = mocks.getOrCreateProvider
+const mockUseSession = mocks.useSession
+
+vi.mock('@/server/serverFns/knowledge', () => ({
+  updateDocumentFn: mocks.updateDocumentFn,
+  getDocumentFn: mocks.getDocumentFn,
+  listDocumentsFn: mocks.listDocumentsFn,
+}))
+
+
+// 可外部驱动状态的假 provider handle（getOrCreateProvider 返回值）。
+// ⚠ 类型派生自真实 CollabProviderHandle 契约（C1 修复）：真实 buildHandle
+// 新增成员时本文件 tsc 编译即失败，杜绝「替身偏离契约」的假绿。
+let fakeProvider: FakeProviderHandle | null = null
+type FakeProviderHandle = CollabProviderHandle & {
+  __setStatus: (s: CollabConnectionStatus) => void
+}
+
+function buildFakeProvider(init: CollabConnectionStatus = 'connecting'): FakeProviderHandle {
+  let status: CollabConnectionStatus = init
+  const listeners = new Set<(s: CollabConnectionStatus) => void>()
+  const handle: FakeProviderHandle = {
+    roomName: 'doc:knowledge:doc-1',
+    doc: new Y.Doc(),
+    // CollaborationCaret/y-tiptap cursor-plugin 消费的 y-protocols Awareness
+    // API 面（states/setLocalState/setLocalStateField/getLocalState/on/off）
+    awareness: {
+      states: new Map(),
+      setLocalState: vi.fn(),
+      setLocalStateField: vi.fn(),
+      getLocalState: () => null,
+      getStates: () => new Map(),
+      on: vi.fn(),
+      off: vi.fn(),
+    } as unknown as CollabAwareness,
+    getStatus: () => status,
+    onStatusChange: (listener) => {
+      listeners.add(listener)
+      listener(status)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    // UniqueID 协同态监听 'synced'（provider.on/off 契约，C1）
+    on: vi.fn(() => () => {}),
+    off: vi.fn(),
+    destroy: vi.fn(),
+    __setStatus: (next) => {
+      status = next
+      for (const listener of [...listeners]) listener(next)
+    },
+  }
+  return handle
+}
+
+vi.mock('@/lib/collab/provider', () => ({
+  // 惰性转发（工厂执行早于模块体，直接引用会 TDZ）
+  getOrCreateProvider: (roomName: string) => mockGetOrCreateProvider(roomName),
+}))
+
+vi.mock('@/components/shared-kit/auth/auth-client', () => ({
+  useSession: mocks.useSession,
+}))
+
+// 预热 lazy 的 NotionDocEditor 动态 import（模块图大，渲染前先解析完）
+const notionLikeReady = import('@/components/tiptap/notion-like')
+
+// 被测组件（mock 声明之后 import，保证 mock 生效）
+import { KnowledgeDocEditor } from '../knowledge-doc-editor'
+import { getUserColor } from '@/lib/collab/user-color'
+// 真实契约类型（vi.mock 只替换运行时，类型仍取自真实模块 → 替身受契约约束）
+import type {
+  CollabAwareness,
+  CollabConnectionStatus,
+  CollabProviderHandle,
+} from '@/lib/collab/provider'
+
+// ---------------------------------------------------------------------------
+// 夹具
+// ---------------------------------------------------------------------------
+
+function base64Encode(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+/** 造一份带内容的协同快照（XmlFragment 'default'，与 COLLAB_XML_FRAGMENT 一致） */
+function buildSnapshotBase64(text: string): { base64: string; source: Y.Doc } {
+  const source = new Y.Doc()
+  const fragment = source.getXmlFragment('default')
+  const paragraph = new Y.XmlElement('paragraph')
+  const xmlText = new Y.XmlText()
+  xmlText.insert(0, text)
+  paragraph.insert(0, [xmlText])
+  fragment.insert(0, [paragraph])
+  return { base64: base64Encode(Y.encodeStateAsUpdate(source)), source }
+}
+
+const DOCUMENT = {
+  id: 'doc-1',
+  kbId: 'kb-1',
+  title: '协同测试文档',
+  content: { html: '<p>初始内容</p>', markdown: '初始内容' },
+  type: 'doc',
+  creator: null,
+}
+
+function renderEditor(options: {
+  collab?: boolean
+  collabSnapshot?: string | null
+  onEditorReady?: (editor: { commands: { insertContent: (x: string) => void }; getHTML: () => string } & Record<string, unknown>) => void
+}) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <Suspense fallback={null}>
+        <KnowledgeDocEditor
+          document={DOCUMENT}
+          collab={options.collab}
+          collabSnapshot={options.collabSnapshot}
+          onEditorReady={options.onEditorReady as never}
+        />
+      </Suspense>
+    </QueryClientProvider>,
+  )
+}
+
+/** 等 lazy 的 NotionDocEditor 装载并返回编辑器实例（轮询至就绪，抗全量并行负载） */
+async function renderUntilEditorReady(options: Parameters<typeof renderEditor>[0]) {
+  await notionLikeReady
+  const editorRef: { current: unknown } = { current: null }
+  const onEditorReady = (editor: unknown) => {
+    editorRef.current = editor
+  }
+  const view = renderEditor({ ...options, onEditorReady })
+  await act(async () => {
+    for (let i = 0; i < 60 && !editorRef.current; i++) {
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(50)
+    }
+  })
+  const editor = editorRef.current as {
+    options: { immediatelyRender: boolean }
+    commands: { insertContent: (x: string) => void }
+    getHTML: () => string
+    getJSON: () => unknown
+    storage: Record<string, { manager?: { serialize?: (json: unknown) => string } }>
+    extensionManager: { extensions: { name: string; options: Record<string, unknown> }[] }
+    isDestroyed: boolean
+  } | null
+  return { view, editor }
+}
+
+async function insertText(
+  editor: NonNullable<Awaited<ReturnType<typeof renderUntilEditorReady>>['editor']>,
+  text: string,
+) {
+  await act(async () => {
+    editor.commands.insertContent(text)
+    await Promise.resolve()
+  })
+}
+
+beforeEach(() => {
+  // jsdom 无 matchMedia（编辑器 use-is-breakpoint hook 需要）
+  if (typeof window.matchMedia !== 'function') {
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: (query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      }),
+    })
+  }
+  // jsdom 的 Range 无 getClientRects（prosemirror-view 布局量测路径需要）
+  if (typeof Range !== 'undefined' && typeof Range.prototype.getClientRects !== 'function') {
+    const emptyRectList = () => {
+      const list = { length: 0, item: () => null, [Symbol.iterator]: [][Symbol.iterator] }
+      return list as unknown as DOMRectList
+    }
+    Range.prototype.getClientRects = emptyRectList as unknown as typeof Range.prototype.getClientRects
+    Range.prototype.getBoundingClientRect = (() => ({
+      x: 0, y: 0, top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0,
+      toJSON: () => ({}),
+    })) as unknown as typeof Range.prototype.getBoundingClientRect
+  }
+  vi.useFakeTimers()
+  fakeProvider = null
+  mockGetOrCreateProvider.mockImplementation(() => {
+    if (!fakeProvider) throw new Error('测试未初始化 fakeProvider')
+    return fakeProvider
+  })
+  mockUpdateDocumentFn.mockResolvedValue(undefined)
+  mockGetDocumentFn.mockResolvedValue({ ...DOCUMENT, updatedAt: new Date().toISOString() })
+  mockListDocumentsFn.mockResolvedValue([])
+  mockUseSession.mockReturnValue({
+    data: { user: { id: 'user-1', name: '测试用户' } },
+    isPending: false,
+  })
+})
+
+afterEach(() => {
+  fakeProvider = null
+  vi.useRealTimers()
+  vi.clearAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// ① 协同态装配
+// ---------------------------------------------------------------------------
+
+describe('collab=true 装配', () => {
+  it('扩展含 Collaboration（fragment 默认 default）与 CollaborationCaret（user=会话 brief+色板色）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor).not.toBeNull()
+    const names = editor!.extensionManager.extensions.map((e) => e.name)
+
+    const collabExt = editor!.extensionManager.extensions.find((e) => e.name === 'collaboration')
+    expect(collabExt).toBeTruthy()
+    expect(collabExt!.options.document).toBe(fakeProvider!.doc)
+    // fragment 默认：不传 fragment/field，ySyncPlugin 用 'default'——与种子化一致
+    expect(collabExt!.options.fragment ?? null).toBeNull()
+    expect(collabExt!.options.field ?? 'default').toBe('default')
+
+    const caretExt = editor!.extensionManager.extensions.find((e) => e.name === 'collaborationCaret')
+    expect(caretExt).toBeTruthy()
+    expect(caretExt!.options.user).toEqual({
+      name: '测试用户',
+      color: getUserColor('user-1'),
+    })
+    expect(names).toContain('collaboration')
+    expect(names).toContain('collaborationCaret')
+  })
+
+  it('协同态停用内置 undoRedo（Collaboration 自带 Yjs 历史，两者不兼容）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    const names = editor!.extensionManager.extensions.map((e) => e.name)
+    expect(names).not.toContain('undoRedo')
+  })
+
+  it('immediatelyRender:false（既有惯例，SSR 水合安全）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor!.options.immediatelyRender).toBe(false)
+  })
+
+  it('UniqueID 经真实 handle 契约监听 synced（C1：provider.on/off 是装配硬依赖）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor).not.toBeNull()
+    // UniqueID onCreate 在协同态执行 provider.on('synced', createIds)——
+    // handle 缺 on/off 时编辑器创建即抛（live 协同必崩路径的契约钉）
+    expect(fakeProvider!.on).toHaveBeenCalledWith('synced', expect.any(Function))
+    // 卸载路径：onDestroy off 退订（此处不卸载，仅断言订阅已建立）
+  })
+
+  it('SSR 快照预水合：snapshot applyUpdate 进 provider doc，编辑器内容来自 Y', async () => {
+    fakeProvider = buildFakeProvider('connecting')
+    const { base64 } = buildSnapshotBase64('协同快照内容')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: base64 })
+
+    // 快照进了 provider doc（hook 水合目标就是连接 doc，不是旁路副本）
+    expect(fakeProvider!.doc.getXmlFragment('default').toString()).toContain('协同快照内容')
+    // 编辑器初始渲染读 Y（而非 content prop 的「初始内容」）
+    await act(async () => {})
+    expect(editor!.getHTML()).toContain('协同快照内容')
+    expect(editor!.getHTML()).not.toContain('初始内容')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② 三通道保存短路（协同态）
+// ---------------------------------------------------------------------------
+
+describe('collab=true 三通道保存短路', () => {
+  it('2s 防抖 / 5s 轮询 / beforeunload 全部不触发 updateDocumentFn', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor).not.toBeNull()
+
+    await insertText(editor!, '协同编辑内容')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500) // NotionDocEditor 500ms change 防抖
+    })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000) // 2s 防抖通道窗口
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000) // 5s 轮询通道两个周期
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+
+    await act(async () => {
+      fireEvent(window, new Event('beforeunload')) // beforeunload 通道
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+  })
+
+  it('远端更新同样不触发 DB 保存（onChange 对 Y 远端事务短路）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+
+    // 模拟远端协同者写入（直接写 Y，等价远端 update 应用）
+    await act(async () => {
+      const fragment = fakeProvider!.doc.getXmlFragment('default')
+      const paragraph = new Y.XmlElement('paragraph')
+      const xmlText = new Y.XmlText()
+      xmlText.insert(0, '远端写入')
+      paragraph.insert(0, [xmlText])
+      fragment.insert(fragment.length, [paragraph])
+    })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000 + 5000)
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+    expect(editor!.getHTML()).toContain('远端写入')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ collab=false 回归（现状逐项一致）
+// ---------------------------------------------------------------------------
+
+describe('collab=false 回归（现状保存链路原样）', () => {
+  it('扩展清单无 Collaboration / CollaborationCaret，undoRedo 保留', async () => {
+    const { editor } = await renderUntilEditorReady({})
+    const names = editor!.extensionManager.extensions.map((e) => e.name)
+    expect(names).not.toContain('collaboration')
+    expect(names).not.toContain('collaborationCaret')
+    expect(names).toContain('undoRedo')
+    // provider 不得被创建（零开销）
+    expect(mockGetOrCreateProvider).not.toHaveBeenCalled()
+  })
+
+  it('初始内容仍走 content prop（非 Y 水合）', async () => {
+    const { editor } = await renderUntilEditorReady({})
+    expect(editor!.getHTML()).toContain('初始内容')
+  })
+
+  it('三通道各自触发 DB 保存：2s 防抖 → 失败后 5s 轮询接管 → beforeunload 兜底', async () => {
+    const { editor } = await renderUntilEditorReady({})
+    expect(editor).not.toBeNull()
+
+    // 通道一：2s 防抖保存
+    await insertText(editor!, '本地编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500) // change 防抖 → dirty + 2s 保存调度
+      await vi.advanceTimersByTimeAsync(2000) // 2s 防抖保存
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(1)
+    expect(mockUpdateDocumentFn.mock.calls[0]![0]).toMatchObject({
+      data: { id: 'doc-1' },
+    })
+
+    // 通道二：5s 轮询——轮询只在 dirty 存活时跑（保存成功即清脏、轮询随之
+    // 拆除；真实触发路径是保存失败后 dirty 滞留），失败模拟钉住该语义
+    mockUpdateDocumentFn.mockRejectedValueOnce(new Error('network down'))
+    await insertText(editor!, '第二次编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000) // 保存失败（call#2），dirty 滞留
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(2)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000) // 5s 轮询重试（call#3，成功）
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(3)
+
+    // 通道三：beforeunload（再编辑置脏后关页，不等 2s 防抖到期）
+    await insertText(editor!, '关闭前编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+    })
+    fireEvent(window, new Event('beforeunload'))
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(4)
+    const lastSaved = mockUpdateDocumentFn.mock.calls[3]![0].data.content as { html: string }
+    expect(lastSaved.html).toContain('关闭前编辑')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 降级模式（「风险与回退」承诺）
+// ---------------------------------------------------------------------------
+
+describe('connecting 建连窗口（I2：轻提示 + 短路显式钉住）', () => {
+  it('connecting 期三通道同样短路（Y 唯一写手），提示条显示且 synced 后消失', async () => {
+    fakeProvider = buildFakeProvider('connecting')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor).not.toBeNull()
+    expect(connectingBannerText()).toBeTruthy()
+
+    await insertText(editor!, '建连窗口编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000) // 2s 防抖通道窗口
+      await vi.advanceTimersByTimeAsync(10_000) // 5s 轮询通道两个周期
+      fireEvent(window, new Event('beforeunload')) // beforeunload 通道
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+
+    // 建连成功 → 提示条消失（Y 继续独占，语义不变）
+    await act(async () => {
+      fakeProvider!.__setStatus('synced')
+    })
+    expect(connectingBannerText()).toBeNull()
+  })
+})
+
+describe('降级模式（offline → 旧链路 + 提示条；synced → 切回协同）', () => {
+  it('offline：提示条出现 + 旧保存链路恢复（含降级前 Y 独占期内容补存）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+
+    // 协同期编辑不落库
+    await insertText(editor!, '协同期编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000)
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+
+    // 连接断开 → 提示条 + 旧链路恢复（种子含降级前内容）
+    await act(async () => {
+      fakeProvider!.__setStatus('offline')
+    })
+    expect(screenBannerText()).toBeTruthy()
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000) // 降级种子走 2s 防抖通道
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(1)
+    const savedContent = mockUpdateDocumentFn.mock.calls[0]![0].data.content as { html: string }
+    expect(savedContent.html).toContain('协同期编辑')
+
+    // 降级期继续编辑 → 继续走 DB 链路
+    await insertText(editor!, '离线编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000)
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalledTimes(2)
+    const offlineSaved = mockUpdateDocumentFn.mock.calls[1]![0].data.content as { html: string }
+    expect(offlineSaved.html).toContain('离线编辑')
+  })
+
+  it('synced 恢复：提示条消失 + DB 链路再短路（未落库意图被取消，不再双写）', async () => {
+    fakeProvider = buildFakeProvider('synced')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+
+    await act(async () => {
+      fakeProvider!.__setStatus('offline')
+    })
+    expect(screenBannerText()).toBeTruthy()
+    await insertText(editor!, '离线期编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500) // change 防抖已过、2s 保存未到期
+    })
+
+    // 恢复连接：切回协同
+    await act(async () => {
+      fakeProvider!.__setStatus('synced')
+    })
+    expect(screenBannerText()).toBeNull()
+
+    // 已调度的 2s 保存到期 → 被协同态短路（不产生 DB 双写）
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000 + 5000)
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+
+    // 恢复后的编辑继续只进 Y
+    await insertText(editor!, '恢复后编辑')
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500 + 2000 + 5000)
+    })
+    expect(mockUpdateDocumentFn).not.toHaveBeenCalled()
+    expect(editor!.getHTML()).toContain('恢复后编辑')
+  })
+})
+
+/** 取当前渲染树中的提示条文案（无则 null） */
+function bannerText(testId: string): string | null {
+  const node = document.body.querySelector(`[data-testid="${testId}"]`)
+  return node?.textContent ?? null
+}
+const screenBannerText = () => bannerText('collab-offline-banner')
+const connectingBannerText = () => bannerText('collab-connecting-banner')

package/src/components/knowledge/editor/doc-header.tsx

@@ -15,18 +15,16 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import { useState, useRef, useEffect, type ReactNode } from 'react'
+import { useState, useRef, type ReactNode } from 'react'
 import { BookOpen, Clock, Dot, Plus } from 'lucide-react'
+import type { AvatarConfig } from '@allbluecn/kernel'
 import { cn } from '@/lib/utils'
 import { formatSaveTime } from '@/lib/time-format'
 import { useTimezone } from '@/providers/timezone-provider'
 import { UserAvatar } from '@/components/shared-kit'
-import { TagSelector } from '@/components/tags/tag-selector'
-import { TagBadge } from '@/components/tags/tag-badge'
-import { listTagsFn } from '@/server/serverFns/tags'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { type PropertyField, PropertyIcon } from '@/components/knowledge/doc-properties'
-import { m } from "@/paraglide/messages.js";
+import { m } from "@/paraglide/messages.js"
 
 interface DocHeaderProps {
   title: string
@@ -34,14 +32,12 @@ interface DocHeaderProps {
   onTitleChange?: (title: string) => void
   creator?: {
     username?: string | null
-    avatarConfig?: any
+    avatarConfig?: unknown
     bgShape?: string | null
     bgColor?: string | null
   } | null
   kbName?: string | null
   savedAt?: Date | null
-  tags?: string[]
-  onTagsChange?: (tags: string[]) => void
   className?: string
   readOnly?: boolean
   addablePropertyFields?: PropertyField[]
@@ -50,8 +46,6 @@ interface DocHeaderProps {
   actions?: ReactNode
 }
 
-type TagItem = { id: string; name: string; color: number }
-
 export function DocHeader({
   title,
   titlePlaceholder,
@@ -59,8 +53,6 @@ export function DocHeader({
   creator,
   kbName,
   savedAt,
-  tags = [],
-  onTagsChange,
   className,
   readOnly = false,
   addablePropertyFields,
@@ -74,27 +66,8 @@ export function DocHeader({
   const [addPropOpen, setAddPropOpen] = useState(false)
   const resolvedTitlePlaceholder = titlePlaceholder ?? m.knowledge_docHeader_titlePlaceholder()
 
-  const [allTags, setAllTags] = useState<TagItem[]>([])
-
   const timezone = useTimezone()
 
-  useEffect(() => {
-    listTagsFn().then(setAllTags).catch(() => setAllTags([]))
-  }, [])
-
-  const tagIdToName = Object.fromEntries(allTags.map((t) => [t.id, t.name]))
-  const tagNameToId = Object.fromEntries(allTags.map((t) => [t.name, t.id]))
-  const tagNameToTag = Object.fromEntries(allTags.map((t) => [t.name, t]))
-  const selectedTagIds = tags.map((n) => tagNameToId[n]).filter(Boolean)
-
-  const handleTagChange = async (tagIds: string[]) => {
-    const freshTags = await listTagsFn().catch(() => allTags)
-    setAllTags(freshTags)
-    const freshIdToName = Object.fromEntries(freshTags.map((t) => [t.id, t.name]))
-    const names = tagIds.map((id) => freshIdToName[id]).filter(Boolean)
-    onTagsChange?.(names)
-  }
-
   const handleTitleSubmit = () => {
     const val = editValue.trim()
     if (!val || val === title) {
@@ -122,8 +95,8 @@ export function DocHeader({
     metaItems.push(
       <div key="creator" className="flex items-center gap-1.5 text-base text-muted-foreground">
         <UserAvatar
-          avatarConfig={creator.avatarConfig ?? null}
-          bgShape={(creator.bgShape as any) ?? null}
+          avatarConfig={(creator.avatarConfig ?? null) as AvatarConfig | null}
+          bgShape={creator.bgShape}
           bgColor={creator.bgColor ?? null}
           name={creator.username}
           size="sm"
@@ -192,25 +165,10 @@ export function DocHeader({
         {metaItems.map((item, i) => (
           <span key={i} className="flex items-center gap-3">
             {item}
-            {(i < metaItems.length - 1 || !readOnly || tags.length > 0) && <Dot className="size-4 text-muted-foreground" />}
+            {(i < metaItems.length - 1 || !readOnly) && <Dot className="size-4 text-muted-foreground" />}
           </span>
         ))}
 
-        {!readOnly ? (
-          <TagSelector
-            value={selectedTagIds}
-            onChange={handleTagChange}
-            placeholder={m.knowledge_docHeader_selectTags()}
-          />
-        ) : (
-          <div className="flex items-center gap-1.5 flex-wrap">
-            {tags.map((tag) => {
-              const t = tagNameToTag[tag]
-              return <TagBadge key={tag} tag={{ name: tag, color: t?.color ?? 0 }} icon />
-            })}
-          </div>
-        )}
-
         {!readOnly && onAddProperty && addablePropertyFields && addablePropertyFields.length > 0 && (
           <>
           <Dot className="size-4 text-muted-foreground" />