@allbluecn/web-app 0.10.2 → 0.11.0

package/src/plugins/core/tags/__tests__/tags.test.ts

@@ -140,7 +140,7 @@ describe('listTagsFn', () => {
   it('未登录时抛 UnauthorizedError', async () => {
     mocks.getCurrentSession.mockResolvedValue(null)
 
-    await expect(listTagsFn()).rejects.toMatchObject({ message: expect.stringMatching(/UNAUTHORIZED/) })
+    await expect(listTagsFn()).rejects.toThrow(/UNAUTHORIZED/)
   })
 })
 
@@ -194,7 +194,7 @@ describe('createTagFn', () => {
   it('未登录时抛 UnauthorizedError', async () => {
     mocks.getCurrentSession.mockResolvedValue(null)
 
-    await expect(createTagFn({ data: { name: 'AI' } })).rejects.toMatchObject({ message: expect.stringMatching(/UNAUTHORIZED/) })
+    await expect(createTagFn({ data: { name: 'AI' } })).rejects.toThrow(/UNAUTHORIZED/)
   })
 })
 
@@ -227,7 +227,7 @@ describe('updateTagFn', () => {
     mocks.getCurrentSession.mockResolvedValue({ user: { id: 'user-1' } })
     mocks.findFirst.mockResolvedValue(null)
 
-    await expect(updateTagFn({ data: { id: 't-other', name: 'X' } })).rejects.toMatchObject({ message: expect.stringMatching(/FORBIDDEN/) })
+    await expect(updateTagFn({ data: { id: 't-other', name: 'X' } })).rejects.toThrow(/FORBIDDEN/)
     expect(mocks.update).not.toHaveBeenCalled()
   })
 
@@ -237,13 +237,13 @@ describe('updateTagFn', () => {
       .mockResolvedValueOnce({ id: 't1', name: 'AI', userId: 'user-1' })
       .mockResolvedValueOnce({ id: 't2', name: 'AI-New', userId: 'user-1' })
 
-    await expect(updateTagFn({ data: { id: 't1', name: 'AI-New' } })).rejects.toMatchObject({ message: expect.stringMatching(/TAG_NAME_CONFLICT/) })
+    await expect(updateTagFn({ data: { id: 't1', name: 'AI-New' } })).rejects.toThrow(/TAG_NAME_CONFLICT/)
   })
 
   it('未登录时抛 UnauthorizedError', async () => {
     mocks.getCurrentSession.mockResolvedValue(null)
 
-    await expect(updateTagFn({ data: { id: 't1', name: 'X' } })).rejects.toMatchObject({ message: expect.stringMatching(/UNAUTHORIZED/) })
+    await expect(updateTagFn({ data: { id: 't1', name: 'X' } })).rejects.toThrow(/UNAUTHORIZED/)
   })
 })
 
@@ -258,7 +258,7 @@ describe('deleteTagFn', () => {
     mocks.getCurrentSession.mockResolvedValue({ user: { id: 'user-1' } })
     mocks.findFirst.mockResolvedValue(null)
 
-    await expect(deleteTagFn({ data: { id: 't-other' } })).rejects.toMatchObject({ message: expect.stringMatching(/FORBIDDEN/) })
+    await expect(deleteTagFn({ data: { id: 't-other' } })).rejects.toThrow(/FORBIDDEN/)
     expect(mocks.update).not.toHaveBeenCalled()
   })
 
@@ -279,7 +279,7 @@ describe('deleteTagFn', () => {
   it('未登录时抛 UnauthorizedError', async () => {
     mocks.getCurrentSession.mockResolvedValue(null)
 
-    await expect(deleteTagFn({ data: { id: 't1' } })).rejects.toMatchObject({ message: expect.stringMatching(/UNAUTHORIZED/) })
+    await expect(deleteTagFn({ data: { id: 't1' } })).rejects.toThrow(/UNAUTHORIZED/)
   })
 })
 
@@ -329,7 +329,7 @@ describe('reorderTagsFn', () => {
   it('未登录时抛 UnauthorizedError', async () => {
     mocks.getCurrentSession.mockResolvedValue(null)
 
-    await expect(reorderTagsFn({ data: { orderedIds: ['t1'] } })).rejects.toMatchObject({ message: expect.stringMatching(/UNAUTHORIZED/) })
+    await expect(reorderTagsFn({ data: { orderedIds: ['t1'] } })).rejects.toThrow(/UNAUTHORIZED/)
   })
 })
 
@@ -342,7 +342,7 @@ describe('assignTagsToPrdFn', () => {
     mocks.getCurrentSession.mockResolvedValue({ user: { id: 'user-1' } })
     mocks.prdFindFirst.mockResolvedValue(null)
 
-    await expect(assignTagsToPrdFn({ data: { prdId: 'p1', tagIds: ['t1'] } })).rejects.toMatchObject({ message: expect.stringMatching(/FORBIDDEN/) })
+    await expect(assignTagsToPrdFn({ data: { prdId: 'p1', tagIds: ['t1'] } })).rejects.toThrow(/FORBIDDEN/)
   })
 
   it('校验 tagId 不属于自己时抛 FORBIDDEN', async () => {
@@ -350,7 +350,7 @@ describe('assignTagsToPrdFn', () => {
     mocks.prdFindFirst.mockResolvedValue({ id: 'p1' })
     mocks.findFirst.mockResolvedValue(null)
 
-    await expect(assignTagsToPrdFn({ data: { prdId: 'p1', tagIds: ['t-other'] } })).rejects.toMatchObject({ message: expect.stringMatching(/FORBIDDEN/) })
+    await expect(assignTagsToPrdFn({ data: { prdId: 'p1', tagIds: ['t-other'] } })).rejects.toThrow(/FORBIDDEN/)
   })
 
   it('事务内 diff 增删', async () => {

package/src/routeTree.gen.ts

@@ -14,6 +14,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as LoginRouteRouteImport } from './routes/_login/route'
 import { Route as NavRouteRouteImport } from './routes/_nav/route'
 import { Route as PublicRouteRouteImport } from './routes/_public/route'
+import { Route as DocsRouteImport } from './routes/docs'
 import { Route as ShareRouteRouteImport } from './routes/share/route'
 import { Route as WorkspaceRouteImport } from './routes/workspace'
 import { Route as _desktopOnboardingRouteRouteImport } from './routes/__desktop/onboarding/route'
@@ -46,11 +47,13 @@ import { Route as PublicPricingRouteRouteImport } from './routes/_public/pricing
 import { Route as ApiBillingWebhookRouteImport } from './routes/api/billing-webhook'
 import { Route as ApiChatRouteImport } from './routes/api/chat'
 import { Route as ApiHealthRouteImport } from './routes/api/health'
+import { Route as ApiSearchRouteImport } from './routes/api/search'
 import { Route as ApiStoryAiRouteImport } from './routes/api/story-ai'
 import { Route as InviteTokenRouteRouteImport } from './routes/invite/$token/route'
 import { Route as ServerAiStreamRouteImport } from './routes/server.ai-stream'
 import { Route as ServerWsRouteImport } from './routes/server.ws'
 import { Route as ShareVersionIdRouteRouteImport } from './routes/share/$versionId/route'
+import { Route as LangDocsSplatRouteRouteImport } from './routes/$lang/docs/$/route'
 import { Route as NavAppsAnyhubRouteRouteImport } from './routes/_nav/apps/anyhub/route'
 import { Route as NavChatThreadIdRouteImport } from './routes/_nav/chat/$threadId'
 import { Route as NavDesignIndexRouteImport } from './routes/_nav/design/index'
@@ -160,6 +163,11 @@ const PublicRouteRoute = PublicRouteRouteImport.update({
   id: '/_public',
   getParentRoute: () => rootRouteImport,
 } as any)
+const DocsRoute = DocsRouteImport.update({
+  id: '/docs',
+  path: '/docs',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ShareRouteRoute = ShareRouteRouteImport.update({
   id: '/share',
   path: '/share',
@@ -346,6 +354,11 @@ const ApiHealthRoute = ApiHealthRouteImport.update({
   path: '/api/health',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiSearchRoute = ApiSearchRouteImport.update({
+  id: '/api/search',
+  path: '/api/search',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiStoryAiRoute = ApiStoryAiRouteImport.update({
   id: '/api/story-ai',
   path: '/api/story-ai',
@@ -375,6 +388,13 @@ const ShareVersionIdRouteRoute = ShareVersionIdRouteRouteImport.update({
 } as any).lazy(() =>
   import('./routes/share/$versionId/route.lazy').then((d) => d.Route),
 )
+const LangDocsSplatRouteRoute = LangDocsSplatRouteRouteImport.update({
+  id: '/$lang/docs/$',
+  path: '/$lang/docs/$',
+  getParentRoute: () => rootRouteImport,
+} as any).lazy(() =>
+  import('./routes/$lang/docs/$/route.lazy').then((d) => d.Route),
+)
 const NavAppsAnyhubRouteRoute = NavAppsAnyhubRouteRouteImport.update({
   id: '/anyhub',
   path: '/anyhub',
@@ -878,6 +898,7 @@ const ApiSharePrdPrdIdEventsRoute = ApiSharePrdPrdIdEventsRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof PublicIndexRouteRoute
   '/share': typeof ShareRouteRouteWithChildren
+  '/docs': typeof DocsRoute
   '/workspace': typeof WorkspaceRoute
   '/onboarding': typeof _desktopOnboardingRouteRoute
   '/forgot-password': typeof LoginForgotPasswordRouteRoute
@@ -910,9 +931,11 @@ export interface FileRoutesByFullPath {
   '/api/billing-webhook': typeof ApiBillingWebhookRoute
   '/api/chat': typeof ApiChatRoute
   '/api/health': typeof ApiHealthRoute
+  '/api/search': typeof ApiSearchRoute
   '/api/story-ai': typeof ApiStoryAiRoute
   '/server/ai-stream': typeof ServerAiStreamRoute
   '/server/ws': typeof ServerWsRoute
+  '/$lang/docs/$': typeof LangDocsSplatRouteRoute
   '/apps/anyhub': typeof NavAppsAnyhubRouteRouteWithChildren
   '/design/$projectId': typeof NavDesignProjectIdRouteRouteWithChildren
   '/knowledge/$kbId': typeof NavKnowledgeKbIdRouteRouteWithChildren
@@ -987,6 +1010,7 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/': typeof PublicIndexRouteRoute
   '/share': typeof ShareRouteRouteWithChildren
+  '/docs': typeof DocsRoute
   '/workspace': typeof WorkspaceRoute
   '/onboarding': typeof _desktopOnboardingRouteRoute
   '/forgot-password': typeof LoginForgotPasswordRouteRoute
@@ -1013,9 +1037,11 @@ export interface FileRoutesByTo {
   '/api/billing-webhook': typeof ApiBillingWebhookRoute
   '/api/chat': typeof ApiChatRoute
   '/api/health': typeof ApiHealthRoute
+  '/api/search': typeof ApiSearchRoute
   '/api/story-ai': typeof ApiStoryAiRoute
   '/server/ai-stream': typeof ServerAiStreamRoute
   '/server/ws': typeof ServerWsRoute
+  '/$lang/docs/$': typeof LangDocsSplatRouteRoute
   '/apps/anyhub': typeof NavAppsAnyhubRouteRouteWithChildren
   '/design/$projectId': typeof NavDesignProjectIdRouteRouteWithChildren
   '/prd/$id': typeof NavPrdIdRouteRoute
@@ -1085,6 +1111,7 @@ export interface FileRoutesById {
   '/_nav': typeof NavRouteRouteWithChildren
   '/_public': typeof PublicRouteRouteWithChildren
   '/share': typeof ShareRouteRouteWithChildren
+  '/docs': typeof DocsRoute
   '/workspace': typeof WorkspaceRoute
   '/_public/': typeof PublicIndexRouteRoute
   '/__desktop/onboarding': typeof _desktopOnboardingRouteRoute
@@ -1118,9 +1145,11 @@ export interface FileRoutesById {
   '/api/billing-webhook': typeof ApiBillingWebhookRoute
   '/api/chat': typeof ApiChatRoute
   '/api/health': typeof ApiHealthRoute
+  '/api/search': typeof ApiSearchRoute
   '/api/story-ai': typeof ApiStoryAiRoute
   '/server/ai-stream': typeof ServerAiStreamRoute
   '/server/ws': typeof ServerWsRoute
+  '/$lang/docs/$': typeof LangDocsSplatRouteRoute
   '/_nav/apps/anyhub': typeof NavAppsAnyhubRouteRouteWithChildren
   '/_nav/design/$projectId': typeof NavDesignProjectIdRouteRouteWithChildren
   '/_nav/knowledge/$kbId': typeof NavKnowledgeKbIdRouteRouteWithChildren
@@ -1197,6 +1226,7 @@ export interface FileRouteTypes {
   fullPaths:
     | '/'
     | '/share'
+    | '/docs'
     | '/workspace'
     | '/onboarding'
     | '/forgot-password'
@@ -1229,9 +1259,11 @@ export interface FileRouteTypes {
     | '/api/billing-webhook'
     | '/api/chat'
     | '/api/health'
+    | '/api/search'
     | '/api/story-ai'
     | '/server/ai-stream'
     | '/server/ws'
+    | '/$lang/docs/$'
     | '/apps/anyhub'
     | '/design/$projectId'
     | '/knowledge/$kbId'
@@ -1306,6 +1338,7 @@ export interface FileRouteTypes {
   to:
     | '/'
     | '/share'
+    | '/docs'
     | '/workspace'
     | '/onboarding'
     | '/forgot-password'
@@ -1332,9 +1365,11 @@ export interface FileRouteTypes {
     | '/api/billing-webhook'
     | '/api/chat'
     | '/api/health'
+    | '/api/search'
     | '/api/story-ai'
     | '/server/ai-stream'
     | '/server/ws'
+    | '/$lang/docs/$'
     | '/apps/anyhub'
     | '/design/$projectId'
     | '/prd/$id'
@@ -1403,6 +1438,7 @@ export interface FileRouteTypes {
     | '/_nav'
     | '/_public'
     | '/share'
+    | '/docs'
     | '/workspace'
     | '/_public/'
     | '/__desktop/onboarding'
@@ -1436,9 +1472,11 @@ export interface FileRouteTypes {
     | '/api/billing-webhook'
     | '/api/chat'
     | '/api/health'
+    | '/api/search'
     | '/api/story-ai'
     | '/server/ai-stream'
     | '/server/ws'
+    | '/$lang/docs/$'
     | '/_nav/apps/anyhub'
     | '/_nav/design/$projectId'
     | '/_nav/knowledge/$kbId'
@@ -1516,15 +1554,18 @@ export interface RootRouteChildren {
   NavRouteRoute: typeof NavRouteRouteWithChildren
   PublicRouteRoute: typeof PublicRouteRouteWithChildren
   ShareRouteRoute: typeof ShareRouteRouteWithChildren
+  DocsRoute: typeof DocsRoute
   WorkspaceRoute: typeof WorkspaceRoute
   _desktopOnboardingRouteRoute: typeof _desktopOnboardingRouteRoute
   InviteTokenRouteRoute: typeof InviteTokenRouteRoute
   ApiBillingWebhookRoute: typeof ApiBillingWebhookRoute
   ApiChatRoute: typeof ApiChatRoute
   ApiHealthRoute: typeof ApiHealthRoute
+  ApiSearchRoute: typeof ApiSearchRoute
   ApiStoryAiRoute: typeof ApiStoryAiRoute
   ServerAiStreamRoute: typeof ServerAiStreamRoute
   ServerWsRoute: typeof ServerWsRoute
+  LangDocsSplatRouteRoute: typeof LangDocsSplatRouteRoute
   ApiLicenseActivateRouteRoute: typeof ApiLicenseActivateRouteRoute
   ApiLicenseHeartbeatRouteRoute: typeof ApiLicenseHeartbeatRouteRoute
   ApiAttachmentsUploadRoute: typeof ApiAttachmentsUploadRoute
@@ -1562,6 +1603,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof PublicRouteRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/docs': {
+      id: '/docs'
+      path: '/docs'
+      fullPath: '/docs'
+      preLoaderRoute: typeof DocsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/share': {
       id: '/share'
       path: '/share'
@@ -1786,6 +1834,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiHealthRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/search': {
+      id: '/api/search'
+      path: '/api/search'
+      fullPath: '/api/search'
+      preLoaderRoute: typeof ApiSearchRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/story-ai': {
       id: '/api/story-ai'
       path: '/api/story-ai'
@@ -1821,6 +1876,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ShareVersionIdRouteRouteImport
       parentRoute: typeof ShareRouteRoute
     }
+    '/$lang/docs/$': {
+      id: '/$lang/docs/$'
+      path: '/$lang/docs/$'
+      fullPath: '/$lang/docs/$'
+      preLoaderRoute: typeof LangDocsSplatRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/_nav/apps/anyhub': {
       id: '/_nav/apps/anyhub'
       path: '/anyhub'
@@ -2761,15 +2823,18 @@ const rootRouteChildren: RootRouteChildren = {
   NavRouteRoute: NavRouteRouteWithChildren,
   PublicRouteRoute: PublicRouteRouteWithChildren,
   ShareRouteRoute: ShareRouteRouteWithChildren,
+  DocsRoute: DocsRoute,
   WorkspaceRoute: WorkspaceRoute,
   _desktopOnboardingRouteRoute: _desktopOnboardingRouteRoute,
   InviteTokenRouteRoute: InviteTokenRouteRoute,
   ApiBillingWebhookRoute: ApiBillingWebhookRoute,
   ApiChatRoute: ApiChatRoute,
   ApiHealthRoute: ApiHealthRoute,
+  ApiSearchRoute: ApiSearchRoute,
   ApiStoryAiRoute: ApiStoryAiRoute,
   ServerAiStreamRoute: ServerAiStreamRoute,
   ServerWsRoute: ServerWsRoute,
+  LangDocsSplatRouteRoute: LangDocsSplatRouteRoute,
   ApiLicenseActivateRouteRoute: ApiLicenseActivateRouteRoute,
   ApiLicenseHeartbeatRouteRoute: ApiLicenseHeartbeatRouteRoute,
   ApiAttachmentsUploadRoute: ApiAttachmentsUploadRoute,

package/src/routes/$lang/docs/$/route.lazy.tsx

@@ -0,0 +1,62 @@
+import { createLazyFileRoute, Link } from '@tanstack/react-router'
+import { Suspense, useEffect } from 'react'
+import { DocsLayout } from 'fumadocs-ui/layouts/docs'
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/docs/page'
+import { useFumadocsLoader } from 'fumadocs-core/source/client'
+import { baseOptions, isDocsLang, type DocsLang } from '@/lib/layout.shared'
+import { getMDXComponents } from '@/components/mdx'
+import { docs } from '@/lib/source'
+import { setLocale } from '@/paraglide/runtime.js'
+
+export const Route = createLazyFileRoute('/$lang/docs/$')({
+  component: DocsRouteComponent,
+})
+
+function Content({ path, lang }: { path: string; lang: DocsLang }) {
+  const page = docs.getPage(path)
+  if (!page) throw new Error(`unknown page: ${path}`)
+
+  const { toc, body: MdxContent } = page
+
+  return (
+    <DocsPage toc={toc} className="pt-8">
+      <Link
+        to="/dashboard"
+        className="text-fd-muted-foreground hover:text-fd-foreground mb-2 inline-flex items-center gap-1 text-sm"
+      >
+        ← {lang === 'en' ? 'Back to App' : '返回应用'}
+      </Link>
+      <DocsTitle>{page.title}</DocsTitle>
+      <DocsDescription>{page.description}</DocsDescription>
+      <DocsBody>
+        <MdxContent components={getMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  )
+}
+
+function DocsRouteComponent() {
+  const { lang: rawLang } = Route.useParams()
+  const data = useFumadocsLoader(Route.useLoaderData())
+
+  useEffect(() => {
+    if (isDocsLang(rawLang)) setLocale(rawLang)
+  }, [rawLang])
+
+  if (!isDocsLang(rawLang)) return null
+
+  const lang: DocsLang = rawLang
+
+  return (
+    <DocsLayout {...baseOptions(lang)} tree={data.pageTree}>
+      <Suspense>
+        <Content path={data.path} lang={lang} />
+      </Suspense>
+    </DocsLayout>
+  )
+}

package/src/routes/$lang/docs/$/route.tsx

@@ -0,0 +1,52 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { docs, source } from '@/lib/source'
+
+// fumadocs-ui 16.15.8 的 getLayoutTabs 遍历 root/folder 的 children 时
+// 会 `for of child` 递归调用 next，但 page 节点（叶子）无 children 字段导致
+// `node.children is not iterable`。给每个无 children 的节点补 `children: []`。
+function fixPageTreeChildren<T extends { data: unknown }>(tree: T): T {
+  const patch = (node: { type?: string; children?: unknown[] }): void => {
+    if (!node || typeof node !== 'object') return
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) patch(child as Parameters<typeof patch>[0])
+    } else {
+      ;(node as { children: unknown[] }).children = []
+    }
+  }
+  patch(tree.data as { children?: unknown[] })
+  return tree
+}
+
+const loadDocsPage = createServerFn({ method: 'GET' })
+  .validator((data: { slugs: string[]; lang: string }) => data)
+  .handler(async ({ data: { slugs, lang } }) => {
+    const page = source.getPage(slugs, lang)
+    if (!page) return null
+
+    const pageTree = fixPageTreeChildren(await source.serializePageTree(source.getPageTree(lang)))
+    return {
+      path: page.path,
+      title: page.data.title,
+      description: page.data.description,
+      pageTree,
+    }
+  })
+
+export const Route = createFileRoute('/$lang/docs/$')({
+  loader: async ({ params }) => {
+    const slugs = params._splat?.split('/') ?? []
+    const data = await loadDocsPage({ data: { slugs, lang: params.lang } })
+    if (!data) throw notFound()
+    await docs.getPage(data.path)?.preload()
+    return data
+  },
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData ? `${loaderData.title} - AllBlue` : 'AllBlue' },
+      ...(loaderData?.description
+        ? [{ name: 'description', content: loaderData.description }]
+        : []),
+    ],
+  }),
+})

package/src/routes/-tests/docs-redirect.test.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/paraglide/runtime.js', () => ({
+  getLocale: vi.fn(() => 'zh'),
+}))
+
+import { getLocale } from '@/paraglide/runtime.js'
+import { Route } from '../docs'
+
+type BeforeLoadFn = (ctx: never) => unknown
+const beforeLoad = Route.options.beforeLoad as unknown as BeforeLoadFn
+
+async function catchRedirectTarget(fn: () => unknown): Promise<string> {
+  try {
+    await fn()
+    return ''
+  } catch (e) {
+    const err = e as {
+      href?: string
+      options?: { to?: string; params?: Record<string, string> }
+    }
+    if (err.href) return err.href
+    if (err.options?.to) {
+      const p = err.options.params ?? {}
+      return err.options.to.replace(/\$(\w+)/g, (_, name: string) => p[name] ?? `$${name}`)
+    }
+    return JSON.stringify(e)
+  }
+}
+
+describe('/docs redirect', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('zh locale 重定向到 /zh/docs', async () => {
+    vi.mocked(getLocale).mockReturnValue('zh')
+    await expect(catchRedirectTarget(() => beforeLoad({} as never))).resolves.toContain('/zh/docs')
+  })
+
+  it('en locale 重定向到 /en/docs', async () => {
+    vi.mocked(getLocale).mockReturnValue('en')
+    await expect(catchRedirectTarget(() => beforeLoad({} as never))).resolves.toContain('/en/docs')
+  })
+})

package/src/routes/__root.tsx

@@ -15,7 +15,7 @@
 // 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 { Link, Outlet, createRootRouteWithContext, HeadContent, Scripts } from '@tanstack/react-router'
+import { Link, Outlet, createRootRouteWithContext, HeadContent, Scripts, useParams } from '@tanstack/react-router'
 import { HotkeysProvider } from '@tanstack/react-hotkeys'
 import { ShortcutsPanel } from '@/components/hotkeys/shortcuts-panel'
 import { Analytics } from '@vercel/analytics/react'
@@ -23,6 +23,9 @@ import { SpeedInsights } from '@vercel/speed-insights/react'
 import globalsCss from '@/styles/globals.css?url'
 import type { RouterContext } from '@/lib/router-context'
 import { Providers } from '@/providers'
+import { RootProvider } from 'fumadocs-ui/provider/tanstack'
+import { i18nProvider } from 'fumadocs-ui/i18n'
+import { translations } from '@/lib/layout.shared'
 import { Toaster } from '@/components/ui/sonner'
 import { DevtoolsPanel } from '@/components/devtools'
 import { getSessionFn } from '@/server/serverFns/auth/session'
@@ -62,6 +65,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
 
 function RootComponent() {
   const session = Route.useRouteContext({ select: (c) => c.session }) as Session | null
+  const { lang } = useParams({ strict: false }) as { lang?: string | undefined }
   return (
     <html lang={getLocale()} suppressHydrationWarning>
       <head>
@@ -69,12 +73,14 @@ function RootComponent() {
       </head>
       <body className="w-full h-full min-h-screen antialiased">
         <Providers session={session}>
-          <HotkeysProvider>
-            <Outlet />
-            <ShortcutsPanel />
-            <Toaster position="top-center" />
-            {import.meta.env.DEV && <DevtoolsPanel />}
-          </HotkeysProvider>
+          <RootProvider i18n={i18nProvider(translations, lang)}>
+            <HotkeysProvider>
+              <Outlet />
+              <ShortcutsPanel />
+              <Toaster position="top-center" />
+              {import.meta.env.DEV && <DevtoolsPanel />}
+            </HotkeysProvider>
+          </RootProvider>
         </Providers>
         <Scripts />
         <Analytics />

package/src/routes/__tests__/-edition-routing.test.tsx

@@ -67,7 +67,7 @@ describe('_nav beforeLoad', () => {
     )
     expect(r?.to).toBe('/login')
     expect(r?.search?.redirect).toBe('/prd?x=1')
-  })
+  }, 20000)
 
   it('SaaS 已登录：放行', async () => {
     const { Route } = await importNavRoute({ profileId: 'saas', desktop: false })
@@ -76,21 +76,21 @@ describe('_nav beforeLoad', () => {
         Route.options.beforeLoad!({ context: { session: { user: { id: 'u1' } } }, location } as never),
       ),
     ).toBeNull()
-  })
+  }, 20000)
 
   it('OSS 未登录：放行（登录后置）', async () => {
     const { Route } = await importNavRoute({ profileId: 'oss', desktop: false })
     expect(
       catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
     ).toBeNull()
-  })
+  }, 20000)
 
   it('desktop：无条件放行', async () => {
     const { Route } = await importNavRoute({ profileId: 'saas', desktop: true })
     expect(
       catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
     ).toBeNull()
-  })
+  }, 20000)
 })
 
 describe('GlobalErrorBoundary', () => {

package/src/routes/__tests__/route-tree-structure.test.ts

@@ -0,0 +1,65 @@
+// @vitest-environment node
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { describe, expect, it } from "vitest"
+
+// routeTree.gen.ts 由 TanStack Router 插件生成，是路由结构的单一事实源。
+// 本测试锁定关键路由路径集合：误删路由文件 / 改名 path 未同步调用方时立即红灯。
+// 清单项均为已用 grep 校准的真实生成字面量（单引号 + 完整路径串）。
+const content = readFileSync(
+  resolve(import.meta.dirname, "../../routeTree.gen.ts"),
+  "utf-8"
+)
+
+const MUST_EXIST_PATHS: string[] = [
+  // 认证区（_login pathless layout）
+  "'/login'",
+  "'/register'",
+  "'/forgot-password'",
+  "'/reset-password'",
+  // 导航区（_nav pathless layout，登录后落地页）
+  "'/dashboard'",
+  "'/workspaces'",
+  "'/prd'",
+  "'/settings'",
+  "'/knowledge'",
+  "'/apps'",
+  // 公开 / 分享（_public layout + share 公开页）
+  "'/share/$versionId'",
+  "'/share/prd/$prdId'",
+  // API
+  "'/api/auth/$'",
+  "'/api/health'",
+  "'/api/chat'",
+]
+
+const DYNAMIC_PATH_PATTERNS: RegExp[] = [
+  /prd\/\$id/,
+  /workspaces\/\$workspaceId/,
+  /settings\/ai\/\$providerId/,
+]
+
+describe("routeTree 结构完整性", () => {
+  it.each(MUST_EXIST_PATHS)("关键路由 %s 存在", (p) => {
+    expect(content).toContain(p)
+  })
+
+  for (const re of DYNAMIC_PATH_PATTERNS) {
+    it(`动态路由 ${re} 存在`, () => {
+      expect(re.test(content)).toBe(true)
+    })
+  }
+
+  it("pathless 布局路由 _nav/_login/_public 存在", () => {
+    expect(content).toContain("_nav")
+    expect(content).toContain("_login")
+    expect(content).toContain("_public")
+  })
+
+  // 反向守卫（面向未来）：routeTree.gen.ts 由路由插件扫描 src/routes/** 生成，
+  // 若测试文件被误放进 routes 目录会被一并收录为路由。当前恒真，防未来回归。
+  it("测试文件本身未被路由插件收录（防误扫为路由）", () => {
+    expect(content).not.toContain("route-tree-structure")
+    expect(content).not.toContain("__tests__")
+  })
+})