@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/{knowledge-public → knowledge/public}/knowledge-form-dialog.tsx

@@ -27,15 +27,15 @@ import { toast } from '@/components/ui/toast'
 import { MarkdownEditor } from './markdown-editor'
 import { NotionDocEditor } from '@/components/tiptap/notion-like'
 import { KnowledgeTagInput } from '@/components/knowledge/knowledge-tag-input'
-import { createLegalFn } from '@/server/serverFns/knowledge-public/legal/create'
-import { updateLegalFn } from '@/server/serverFns/knowledge-public/legal/update'
-import { getLegalDetailFn } from '@/server/serverFns/knowledge-public/legal/detail'
-import { createComplianceFn } from '@/server/serverFns/knowledge-public/compliance/create'
-import { updateComplianceFn } from '@/server/serverFns/knowledge-public/compliance/update'
-import { getComplianceDetailFn } from '@/server/serverFns/knowledge-public/compliance/detail'
-import { createDictionaryFn } from '@/server/serverFns/knowledge-public/dictionary/create'
-import { updateDictionaryFn } from '@/server/serverFns/knowledge-public/dictionary/update'
-import { getDictionaryDetailFn } from '@/server/serverFns/knowledge-public/dictionary/detail'
+import { createLegalFn } from '@/server/serverFns/knowledge/public/legal/create'
+import { updateLegalFn } from '@/server/serverFns/knowledge/public/legal/update'
+import { getLegalDetailFn } from '@/server/serverFns/knowledge/public/legal/detail'
+import { createComplianceFn } from '@/server/serverFns/knowledge/public/compliance/create'
+import { updateComplianceFn } from '@/server/serverFns/knowledge/public/compliance/update'
+import { getComplianceDetailFn } from '@/server/serverFns/knowledge/public/compliance/detail'
+import { createDictionaryFn } from '@/server/serverFns/knowledge/public/dictionary/create'
+import { updateDictionaryFn } from '@/server/serverFns/knowledge/public/dictionary/update'
+import { getDictionaryDetailFn } from '@/server/serverFns/knowledge/public/dictionary/detail'
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";
 

package/src/components/{knowledge-public → knowledge/public}/legal-compliance-editor.tsx

@@ -22,14 +22,18 @@ import { ArrowLeft } from 'lucide-react'
 import { KnowledgeDocEditor } from '@/components/knowledge/editor/knowledge-doc-editor'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import type { PropertyField, PropertyValues } from '@/components/knowledge/doc-properties'
-import { updateLegalFn } from '@/server/serverFns/knowledge-public/legal/update'
-import { getLegalDetailFn } from '@/server/serverFns/knowledge-public/legal/detail'
-import { deleteLegalFn } from '@/server/serverFns/knowledge-public/legal/delete'
-import { updateComplianceFn } from '@/server/serverFns/knowledge-public/compliance/update'
-import { getComplianceDetailFn } from '@/server/serverFns/knowledge-public/compliance/detail'
-import { deleteComplianceFn } from '@/server/serverFns/knowledge-public/compliance/delete'
+import { updateLegalFn } from '@/server/serverFns/knowledge/public/legal/update'
+import { getLegalDetailFn } from '@/server/serverFns/knowledge/public/legal/detail'
+import { deleteLegalFn } from '@/server/serverFns/knowledge/public/legal/delete'
+import { updateComplianceFn } from '@/server/serverFns/knowledge/public/compliance/update'
+import { getComplianceDetailFn } from '@/server/serverFns/knowledge/public/compliance/detail'
+import { deleteComplianceFn } from '@/server/serverFns/knowledge/public/compliance/delete'
 import { m } from "@/paraglide/messages.js";
 
+type LegalDetail = Awaited<ReturnType<typeof getLegalDetailFn>>
+type ComplianceDetail = Awaited<ReturnType<typeof getComplianceDetailFn>>
+type LegalOrComplianceDetail = LegalDetail | ComplianceDetail
+
 type EditorType = 'legal' | 'compliance'
 
 export const JURISDICTION_OPTS = [
@@ -82,25 +86,28 @@ function toDateStr(d: unknown): string {
   return dt.toISOString().slice(0, 10)
 }
 
-function mapRecordToProperties(record: any, type: EditorType): PropertyValues {
+function mapRecordToProperties(record: LegalOrComplianceDetail, type: EditorType): PropertyValues {
+  // code 非数据库列（仅参与 canonicalId 计算），detail 接口不返回，历史行为为空串展示
   if (type === 'legal') {
+    const r = record as LegalDetail & { code?: string }
     return {
-      code: record.code ?? '',
-      category: record.category ?? '',
-      jurisdiction: record.jurisdiction ?? '',
-      region: record.region ?? '',
-      country: record.country ?? '',
-      issuingAuthority: record.issuingAuthority ?? '',
-      effectiveDate: toDateStr(record.effectiveDate),
-      sourceUrl: record.sourceUrl ?? '',
+      code: r.code ?? '',
+      category: r.category ?? '',
+      jurisdiction: r.jurisdiction ?? '',
+      region: r.region ?? '',
+      country: r.country ?? '',
+      issuingAuthority: r.issuingAuthority ?? '',
+      effectiveDate: toDateStr(r.effectiveDate),
+      sourceUrl: r.sourceUrl ?? '',
     }
   }
+  const r = record as ComplianceDetail & { code?: string }
   return {
-    code: record.code ?? '',
-    industry: record.industry ?? '',
-    regulatoryBody: record.regulatoryBody ?? '',
-    region: record.region ?? '',
-    sourceUrl: record.sourceUrl ?? '',
+    code: r.code ?? '',
+    industry: r.industry ?? '',
+    regulatoryBody: r.regulatoryBody ?? '',
+    region: r.region ?? '',
+    sourceUrl: r.sourceUrl ?? '',
   }
 }
 
@@ -108,7 +115,7 @@ function mapPropsToLegalTable(vals: PropertyValues) {
   return {
     code: (vals.code as string) ?? '',
     category: (vals.category as string) ?? '',
-    jurisdiction: (vals.jurisdiction as string) || undefined,
+    jurisdiction: (vals.jurisdiction as 'CN_NATIONAL' | 'CN_LOCAL' | 'OVERSEAS') || undefined,
     region: (vals.region as string) || null,
     country: (vals.country as string) || null,
     issuingAuthority: (vals.issuingAuthority as string) || null,
@@ -145,7 +152,7 @@ export function LegalComplianceEditor({ type, editingId }: Props) {
 
   const detailQuery = useQuery({
     queryKey: [`${type}-detail`, editingId],
-    queryFn: async (): Promise<any> => {
+    queryFn: async (): Promise<LegalOrComplianceDetail> => {
       return type === 'legal'
         ? getLegalDetailFn({ data: { id: editingId! } })
         : getComplianceDetailFn({ data: { id: editingId! } })
@@ -191,7 +198,10 @@ export function LegalComplianceEditor({ type, editingId }: Props) {
   const saveField = useCallback(
     async (field: 'content' | 'title' | 'tags', value: unknown): Promise<void> => {
       if (!editingId) return
-      const payload: any = { id: editingId, [field]: value }
+      const payload =
+        field === 'content' ? { id: editingId, content: value as string | null }
+        : field === 'title' ? { id: editingId, title: value as string }
+        : { id: editingId, tags: value as string[] }
       if (type === 'legal') {
         await updateLegalFn({ data: payload })
       } else {
@@ -228,15 +238,12 @@ export function LegalComplianceEditor({ type, editingId }: Props) {
     () => ({
       content: (c: { html: string; markdown: string }) => saveField('content', c.html),
       title: (t: string) => saveField('title', t),
-      tags: (t: string[]) => saveField('tags', t),
       properties: async (vals: PropertyValues) => {
         if (!editingId) return
-        const mapped = type === 'legal' ? mapPropsToLegalTable(vals) : mapPropsToComplianceTable(vals)
-        const payload: any = { id: editingId, ...mapped }
         if (type === 'legal') {
-          await updateLegalFn({ data: payload })
+          await updateLegalFn({ data: { id: editingId, ...mapPropsToLegalTable(vals) } })
         } else {
-          await updateComplianceFn({ data: payload })
+          await updateComplianceFn({ data: { id: editingId, ...mapPropsToComplianceTable(vals) } })
         }
         qc.invalidateQueries({ queryKey: [type] })
       },

package/src/components/{knowledge-public → knowledge/public}/sharers-avatar-group.tsx

@@ -19,6 +19,7 @@ import { UserAvatar } from '@/components/shared-kit'
 import { AvatarGroup, AvatarGroupTooltip } from '@/components/magicui/components/animate/avatar-group'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { cn } from '@/lib/utils'
+import type { AvatarConfig } from '@allbluecn/kernel'
 import { m } from "@/paraglide/messages.js";
 
 interface Sharer {
@@ -51,8 +52,8 @@ export function SharersAvatarGroup({
             <div key={s.id} className="ring-2 ring-background rounded-full">
               <UserAvatar
                 name={s.username}
-                avatarConfig={s.avatarConfig as any}
-                bgShape={(s.bgShape ?? undefined) as any}
+                avatarConfig={s.avatarConfig as AvatarConfig | null | undefined}
+                bgShape={s.bgShape}
                 bgColor={s.bgColor ?? undefined}
                 size="sm"
               />

package/src/components/layout/layout-responsive-provider.tsx

@@ -0,0 +1,79 @@
+// 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.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// 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 { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import {
+  computeLayout,
+  DEFAULT_LAYOUT_STATE,
+  LayoutResponsiveContext,
+  type LayoutResponsiveContextValue,
+  type LayoutState,
+} from "@/lib/layout-responsive";
+
+/**
+ * 布局窄屏渐进降级的测量与状态源。
+ *
+ * 只测量**最外层容器宽度**（= 视口宽度，`sidebar-03` 经 `setOuterEl` 注册）：它不随
+ * 侧栏收放动画变化，故开关判定不会被动画中间态反馈引发翻转。面板宽度由 CSS flex 同帧计算。
+ */
+export function LayoutResponsiveProvider({ children }: { children: ReactNode }) {
+  const outerRef = useRef<HTMLElement | null>(null);
+  const roRef = useRef<ResizeObserver | null>(null);
+  const [outerWidth, setOuterWidth] = useState(0);
+  const [dockPresent, setDockPresent] = useState(false);
+  const [aiDocked, setAiDocked] = useState(false);
+
+  const measure = useCallback(() => {
+    const w = outerRef.current?.clientWidth ?? 0;
+    setOuterWidth((prev) => (prev === w ? prev : w));
+  }, []);
+
+  useEffect(() => {
+    if (typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(measure);
+    roRef.current = ro;
+    if (outerRef.current) ro.observe(outerRef.current);
+    measure();
+    return () => {
+      ro.disconnect();
+      roRef.current = null;
+    };
+  }, [measure]);
+
+  const setOuterEl = useCallback(
+    (el: HTMLElement | null) => {
+      const ro = roRef.current;
+      if (ro && outerRef.current) ro.unobserve(outerRef.current);
+      outerRef.current = el;
+      if (ro && el) ro.observe(el);
+      measure();
+    },
+    [measure],
+  );
+
+  // 同步计算（用 ref 保存上一帧做阈值回差）：避免经 effect 更新带来的「一帧延迟」抖动
+  const prevLayoutRef = useRef<LayoutState>(DEFAULT_LAYOUT_STATE);
+  const layout = computeLayout({ outerWidth, dockPresent, aiDocked }, prevLayoutRef.current);
+  prevLayoutRef.current = layout;
+
+  const value = useMemo<LayoutResponsiveContextValue>(
+    () => ({ layout, setOuterEl, setDockPresent, setAiDocked }),
+    [layout, setOuterEl],
+  );
+
+  return <LayoutResponsiveContext.Provider value={value}>{children}</LayoutResponsiveContext.Provider>;
+}

package/src/components/layout/sidebar-03/__tests__/presence-avatar-stack.test.tsx

@@ -0,0 +1,148 @@
+// 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.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// 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/>.
+
+// PresenceAvatarStack 单元测试（§8.2 / 简报步骤 1）：
+//   ① module 有成员 → 渲染对应头像组与 tooltip（"{name} 正在查看 {title}"）
+//   ② entityTitle 为空 → 降级「{name} 正在浏览」
+//   ③ >3 人折叠 +N
+//   ④ 本人头像不渲染（excludeSelf）
+//   ⑤ 空 module 渲染 null（不占位）
+//   ⑥ 其他 module 的成员不串扰
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import { overwriteGetLocale } from "@/paraglide/runtime.js";
+
+overwriteGetLocale(() => "zh");
+
+const mockUseSession = vi.fn();
+
+vi.mock("@/lib/auth/auth-client", () => ({
+  useSession: () => mockUseSession(),
+}));
+
+import {
+  __resetPresenceStoreForTests,
+  presenceActions,
+} from "@/lib/collab/presence-store";
+import { PresenceAvatarStack } from "../presence-avatar-stack";
+
+function teammate(
+  id: string,
+  username: string,
+  module: string,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    user: { id, username, bgShape: "circle", bgColor: "#fff" },
+    module,
+    route: "/stories",
+    ts: Date.now(),
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  cleanup();
+  __resetPresenceStoreForTests();
+  mockUseSession.mockReturnValue({ data: { user: { id: "self-1" } } });
+});
+
+describe("PresenceAvatarStack", () => {
+  it("module 有成员 → 渲染头像组，hover 显示「{name} 正在查看 {title}」", async () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", {
+        entityTitle: "需求 A",
+        route: "/stories/1",
+      }),
+    );
+    const { container } = render(<PresenceAvatarStack module="stories" />);
+
+    // 头像组渲染（UserAvatar 首字母 fallback；AvatarGroup 内每头像一个 tooltip trigger）
+    expect(screen.getByText("A")).toBeDefined();
+    expect(
+      container.querySelectorAll('[data-slot="tooltip-trigger"]').length,
+    ).toBe(1);
+
+    // hover 头像 → magicui AvatarGroupTooltip 出 tooltip 文案
+    fireEvent.mouseOver(screen.getByText("A"));
+    await waitFor(() => {
+      expect(screen.getByText("alice 正在查看 需求 A")).toBeDefined();
+    });
+  });
+
+  it("entityTitle 为空 → 降级「{name} 正在浏览」", async () => {
+    presenceActions.applyRemote(teammate("u2", "bob", "stories"));
+    render(<PresenceAvatarStack module="stories" />);
+
+    fireEvent.mouseOver(screen.getByText("B"));
+    await waitFor(() => {
+      expect(screen.getByText("bob 正在浏览")).toBeDefined();
+    });
+  });
+
+  it("超过 3 人折叠 +N（仅显示前 3 个头像）", () => {
+    ["alice", "bob", "carol", "dave", "eve"].forEach((name, i) => {
+      presenceActions.applyRemote(teammate(`u${i}`, name, "stories"));
+    });
+    const { container } = render(<PresenceAvatarStack module="stories" />);
+
+    // avatar-group 容器内仅 3 个头像触发器（+N pill 的触发器在其外）
+    expect(
+      container
+        .querySelector('[data-slot="avatar-group"]')!
+        .querySelectorAll('[data-slot="tooltip-trigger"]').length,
+    ).toBe(3);
+    expect(screen.getByText("+2")).toBeDefined();
+    // 未展示成员的首字母不出现
+    expect(screen.queryByText("D")).toBeNull();
+    expect(screen.queryByText("E")).toBeNull();
+  });
+
+  it("本人头像不渲染（excludeSelf）", () => {
+    presenceActions.applyRemote(teammate("self-1", "selfie", "stories"));
+    presenceActions.applyRemote(teammate("u9", "zoe", "stories"));
+    render(<PresenceAvatarStack module="stories" />);
+
+    expect(screen.queryByText("S")).toBeNull();
+    expect(screen.getByText("Z")).toBeDefined();
+  });
+
+  it("空 module 渲染 null（不占位）", () => {
+    const { container } = render(<PresenceAvatarStack module="empty-module" />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("其他 module 的成员不串扰", () => {
+    presenceActions.applyRemote(teammate("u1", "alice", "bugs"));
+    const { container } = render(<PresenceAvatarStack module="stories" />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("session 未就绪（data 为 null）时不过滤、正常渲染他人", () => {
+    mockUseSession.mockReturnValue({ data: null });
+    presenceActions.applyRemote(teammate("u1", "alice", "stories"));
+    render(<PresenceAvatarStack module="stories" />);
+    expect(screen.getByText("A")).toBeDefined();
+  });
+});

package/src/components/layout/sidebar-03/app-sidebar.tsx

@@ -32,15 +32,22 @@ import { NavWorkspace } from "@/components/layout/sidebar-03/nav-workspace";
 import { UserMenu } from "@/components/layout/sidebar-03/user-menu";
 import { AnimatedThemeToggler } from '@/components/magicui/animated-theme-toggler'
 import { workspaceRoutes } from "@/config/sidebar-routes";
+import type { Route } from "@/config/sidebar-routes";
+import { PresenceAvatarStack } from "@/components/layout/sidebar-03/presence-avatar-stack";
 import { SidebarSearchTrigger } from "@/components/layout/sidebar-03/nav-search-trigger"
 import { NavSecondary } from "@/components/layout/sidebar-03/nav-secondary"
 import { PluginNavItems } from '@/components/plugin-slots/plugin-nav-items'
-import { NavTag } from '@/components/tags/nav-tag'
+
+// presence 渲染工厂（§8.2 消费者两文件之一）：nav-main 按 route.id 查
+// MODULE_ROUTES 得 module key 后回调；module 级单例 map，identity 稳定。
+const routes: Route[] = workspaceRoutes.map((route) => ({
+  ...route,
+  presence: (module: string) => <PresenceAvatarStack module={module} />,
+}));
 
 export function DashboardSidebar() {
   const { state } = useSidebar();
   const isCollapsed = state === "collapsed";
-  const routes = workspaceRoutes;
 
   return (
     <Sidebar variant="floating" collapsible="icon">
@@ -96,7 +103,6 @@ export function DashboardSidebar() {
         <DashboardNavigation routes={routes} />
         <NavWorkspace />
         <NavKnowledge />
-        <NavTag />
         <PluginNavItems />
         <NavAnyHub />
       </SidebarContent>

package/src/components/layout/sidebar-03/index.tsx

@@ -18,6 +18,8 @@
 import { useEffect, useState } from "react";
 import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
 import { DashboardSidebar } from "@/components/layout/sidebar-03/app-sidebar";
+import { PEEK_DOCK_SLOT_ID } from "@/lib/peek-dock";
+import { useLayoutResponsive, useLayoutResponsiveSetters } from "@/lib/layout-responsive";
 import type { ReactNode } from "react";
 
 type Sidebar03Props = {
@@ -28,6 +30,8 @@ type Sidebar03Props = {
 export default function Sidebar03({ children, initialOpen = true }: Sidebar03Props) {
   const [sidebarVisible, setSidebarVisible] = useState(true);
   const [sidebarOpen, setSidebarOpen] = useState(initialOpen);
+  const layout = useLayoutResponsive();
+  const layoutSetters = useLayoutResponsiveSetters();
 
   useEffect(() => {
     const handlePageShow = (event: PageTransitionEvent) => {
@@ -51,13 +55,24 @@ export default function Sidebar03({ children, initialOpen = true }: Sidebar03Pro
   }, []);
 
   return (
-    <SidebarProvider open={sidebarOpen} onOpenChange={setSidebarOpen}>
-      <div className="relative flex h-dvh w-full" >
+    <SidebarProvider open={layout.sidebarCollapsed ? false : sidebarOpen} onOpenChange={setSidebarOpen}>
+      {/* overflow-hidden：杜绝窄屏下内容横向溢出引发窗口滚动条（滚动条出现/消失会让
+          视口宽度跳变，进而与响应式测量互相反馈产生抖动）。 */}
+      <div ref={layoutSetters?.setOuterEl} className="relative flex h-dvh w-full overflow-hidden" >
         {sidebarVisible && <DashboardSidebar />}
-        <div className={`flex flex-1 min-w-0 gap-2 mt-2 pr-2 pb-2 ${sidebarVisible ? 'ml-1' : ''}`}>
-          <SidebarInset className="h-full min-w-0 flex-1 rounded-xl border border-sidebar-border bg-background">
+        <div className={`flex flex-1 min-w-0 gap-2 mt-2 pr-2 pb-2 overflow-hidden ${sidebarVisible ? 'ml-1' : ''}`}>
+          {/* min-w-120(=480)：内容区最小宽，低于它时 flex 收缩侧边面板槽（见下）。
+              侧边面板已覆盖内容（dockOverlay）时内容被盖住，无需再保最小宽 → 放开为 min-w-0，
+              好让 AI 助手仍能在右侧停靠、直到最窄处（连 AI 自身都放不下）才转浮层。 */}
+          <SidebarInset className={`h-full flex-1 rounded-xl border border-sidebar-border bg-background ${layout.dockOverlay ? "min-w-0" : "min-w-120"}`}>
             {children}
           </SidebarInset>
+          {/* 侧边面板（side-dock）态的布局级挂载点：位于右侧内容父容器之外，
+              AI 助手全屏槽之前 → AI 未展开全屏时侧边面板处于最右侧。
+              宽度由 CSS flex 在同帧内计算：basis-300(=1200) + shrink + min-w-120(=480)，
+              内容区到 480 后页面板收缩（避免 JS 用上一帧行宽算 px 造成的逐帧抖动）。
+              浮层态面板不 portal 到此槽（空槽由 globals.css 的 :not(:has(> *)) 隐藏）。 */}
+          <div id={PEEK_DOCK_SLOT_ID} className="min-h-0 basis-300 min-w-120" />
           {/* 全局 AI 助手 full 态的布局级挂载点：portal 注入内容后自动占位
               （globals.css 的 :not(:has(> *)) 规则在空槽时隐藏），与主内容、侧边栏三级同级 */}
           <div id="global-ai-panel-slot" className="w-120 shrink-0" />

package/src/components/layout/sidebar-03/nav-main.tsx

@@ -49,6 +49,7 @@ import { useState } from "react";
 import { useLocation } from "@tanstack/react-router";
 import type { Route } from "@/config/sidebar-routes";
 import { isParentActive } from "@/lib/sidebar-utils";
+import { MODULE_ROUTES } from "@/lib/collab/module-map";
 
 import { AnimatedGradientText } from "@/components/magicui/animated-gradient-text";
 
@@ -117,6 +118,10 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
           const active = hasSubRoutes
             ? isParentActive(pathname, route.link)
             : isActive(route.link);
+          // route.id ≠ presence module key（home→dashboard 等），MODULE_ROUTES 查表（§8.2 交接锚点 F）
+          const presenceModule = MODULE_ROUTES.find(
+            (mr) => mr.id === route.id,
+          )?.module;
 
           return (
             <SidebarMenuItem key={route.id}>
@@ -181,6 +186,9 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
                             )}
                           </span>
                         )}
+                        {presenceModule && route.presence && (
+                          route.presence(presenceModule)
+                        )}
                       </span>
                     )}
                   </div>
@@ -210,18 +218,28 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
                   )}
                 </Collapsible>
               ) : (
-                <SidebarMenuButton render={<Link to={route.link}
-                    className={cn(
-                      "flex items-center rounded-lg px-2",
-                      isCollapsed && "justify-center"
-                    )} />} tooltip={route.title()} isActive={active}>
-                    {route.icon}
-                    {!isCollapsed && (
+                <>
+                  <SidebarMenuButton render={<Link to={route.link}
+                      className={cn(
+                        "flex items-center rounded-lg px-2",
+                        !isCollapsed && presenceModule && route.presence && "pr-12",
+                        isCollapsed && "justify-center"
+                      )} />} tooltip={route.title()} isActive={active}>
+                      {route.icon}
+                      {!isCollapsed && (
 <span className="ml-2 text-sm font-medium">
-                         {route.title()}
-                       </span>
-                    )}
+                           {route.title()}
+                         </span>
+                      )}
                   </SidebarMenuButton>
+                  {/* 普通行 presence 右侧节点（§8.2：absolute 定位 + pr-12 预留；
+                      SidebarMenuItem 自带 relative；折叠图标态不渲染） */}
+                  {!isCollapsed && presenceModule && route.presence && (
+                    <span className="absolute right-1 top-1/2 z-10 flex -translate-y-1/2 items-center">
+                      {route.presence(presenceModule)}
+                    </span>
+                  )}
+                </>
               )}
             </SidebarMenuItem>
           );

package/src/components/layout/sidebar-03/presence-avatar-stack.tsx

@@ -0,0 +1,112 @@
+// 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.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// 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/>.
+
+// 侧边栏模块级成员位置头像组（R3，§8.2）——复用 sharers-avatar-group 模式
+// （UserAvatar + AvatarGroup/Tooltip + +N 折叠）。由 app-sidebar 经
+// Route.presence(module) 工厂接线进 nav-main 各菜单行；props 收 module key，
+// 内部 useTeammates(byModule(module)) + 登录态 selfId 排除本人。
+//
+// 降级：协同不可用 / 离线时 presence-store 已清空 teammates（§8.2「不显示」
+// 而非展示过期位置），空数组渲染 null 不占位。entityTitle（详情页标题）P1
+// 期尚未上报（P3/P4 实体协同接入后出现），为空时 tooltip 降级「正在浏览」。
+
+import { UserAvatar } from "@/components/shared-kit";
+import {
+  AvatarGroup,
+  AvatarGroupTooltip,
+} from "@/components/magicui/components/animate/avatar-group";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import type { AvatarConfig } from "@allbluecn/kernel";
+import { useSession } from "@/lib/auth/auth-client";
+import { byModule, useTeammates } from "@/lib/collab/presence-store";
+import type { PresenceState } from "@/lib/collab/presence-store";
+import { m } from "@/paraglide/messages.js";
+
+/** 展开态最多直接展示的头像数，超出折叠 +N（§8.2） */
+const MAX_VISIBLE = 3;
+
+export function PresenceAvatarStack({
+  module,
+  max = MAX_VISIBLE,
+}: {
+  /** 一级模块 key（§8.1，MODULE_ROUTES 口径） */
+  module: string;
+  max?: number;
+}) {
+  const { data: session } = useSession();
+  const teammates = useTeammates(byModule(module), session?.user?.id ?? null);
+
+  if (teammates.length === 0) return null;
+  const shown = teammates.slice(0, max);
+  const rest = teammates.length - shown.length;
+
+  const entryLabel = (state: PresenceState) =>
+    state.entityTitle
+      ? m.presence_sidebar_tooltipEntry({
+          name: state.user.username,
+          title: state.entityTitle,
+        })
+      : m.presence_sidebar_tooltipEntryNoTitle({ name: state.user.username });
+
+  return (
+    <div
+      className="flex items-center -space-x-1.5"
+      data-slot="presence-avatar-stack"
+    >
+      <AvatarGroup
+        className="h-5 -space-x-1.5"
+        invertOverlap
+        translate="-22%"
+        sideOffset={14}
+      >
+        {shown.map((state) => (
+          <div
+            key={state.user.id}
+            className="rounded-full ring-2 ring-background"
+          >
+            <UserAvatar
+              name={state.user.username}
+              avatarConfig={state.user.avatarConfig as AvatarConfig | null | undefined}
+              bgShape={state.user.bgShape}
+              bgColor={state.user.bgColor ?? undefined}
+              size="xs"
+            />
+            <AvatarGroupTooltip>{entryLabel(state)}</AvatarGroupTooltip>
+          </div>
+        ))}
+      </AvatarGroup>
+      {rest > 0 && (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <div className="flex h-5 w-5 cursor-default items-center justify-center rounded-full bg-muted text-[10px] font-medium ring-2 ring-background">
+                +{rest}
+              </div>
+            }
+          />
+          <TooltipContent>
+            {m.presence_sidebar_overflowCount({ count: rest })}
+          </TooltipContent>
+        </Tooltip>
+      )}
+    </div>
+  );
+}