@allbluecn/web-app 0.6.2 → 0.7.0

package/src/i18n/locales/zh/tags.json

@@ -0,0 +1,42 @@
+{
+  "title": "标签",
+  "description": "标签管理正在开发中，敬请期待",
+  "detail": {
+    "title": "标签详情",
+    "description": "标签详情页正在开发中"
+  },
+  "settings": {
+    "title": "标签设置",
+    "description": "管理你的标签：增删改色、拖拽排序"
+  },
+  "emptyTitle": "暂无标签",
+  "emptyDesc": "创建你的第一个标签来组织 PRD",
+  "createTag": "新建标签",
+  "editTag": "编辑标签",
+  "nameLabel": "名称",
+  "colorLabel": "颜色",
+  "nameRequired": "请输入名称",
+  "nameConflict": "该名称已存在",
+  "saveFailed": "保存失败",
+  "saving": "保存中...",
+  "save": "保存",
+  "cancel": "取消",
+  "delete": "删除",
+  "deleted": "已删除",
+  "deleteFailed": "删除失败",
+  "updated": "已更新",
+  "created": "已创建",
+  "sortFailed": "排序失败",
+  "confirmDeleteTitle": "删除标签「{{name}}」？",
+  "confirmDeleteDesc": "已关联的 PRD 仍会保留此标签，恢复后自动重新可见。",
+  "selector": {
+    "placeholder": "选择标签",
+    "searchPlaceholder": "搜索或创建...",
+    "createTag": "创建「{{name}}」"
+  },
+  "colorPicker": {
+    "selectColor": "选择颜色 {{color}}"
+  },
+  "edit": "编辑",
+  "removeTag": "移除 {{name}}"
+}

package/src/i18n/locales/zh/workspace.json

@@ -0,0 +1,90 @@
+{
+  "title": "工作台",
+  "list": {
+    "title": "工作空间",
+    "subtitle": "管理你的项目、团队协作与需求",
+    "create": "新建工作空间",
+    "emptyTitle": "暂无工作空间",
+    "emptyDescription": "创建第一个工作空间，开始团队协作",
+    "noDescription": "暂无介绍",
+    "projects": "项目",
+    "members": "成员"
+  },
+  "createWorkspace": {
+    "title": "新建工作空间",
+    "description": "创建一个工作空间，管理项目、需求和团队成员",
+    "nameLabel": "工作空间名称 *",
+    "namePlaceholder": "输入工作空间名称",
+    "nameRequired": "请输入工作空间名称",
+    "descriptionLabel": "介绍",
+    "descriptionPlaceholder": "简短介绍（可选）",
+    "cancel": "取消",
+    "creating": "创建中...",
+    "create": "创建",
+    "createFailed": "创建失败",
+    "upgradeTitle": "已达工作区上限",
+    "upgradeDescription": "Free 账号最多创建 1 个工作区。升级 Pro 后不限数量，并可解锁全部高级功能。",
+    "upgradeAction": "升级 Pro"
+  },
+  "detail": {
+    "noDescription": "暂无介绍",
+    "projects": "项目",
+    "members": "成员",
+    "createProject": "新建项目",
+    "emptyProjectsTitle": "暂无项目",
+    "emptyProjectsDescription": "在此工作空间创建第一个项目"
+  },
+  "settings": {
+    "back": "返回工作空间",
+    "title": "工作空间设置",
+    "basicInfo": "基本信息",
+    "icon": "工作空间图标",
+    "nameLabel": "工作空间名称 *",
+    "nameRequired": "请输入工作空间名称",
+    "descriptionLabel": "介绍",
+    "descriptionPlaceholder": "简短介绍工作空间目标与范围",
+    "saveChanges": "保存修改",
+    "updateSuccess": "工作空间已更新",
+    "saveFailed": "保存失败",
+    "members": "成员管理",
+    "inviteEmailPlaceholder": "输入成员邮箱",
+    "inviteEmailRequired": "请输入邮箱",
+    "inviteSuccess": "邀请已发送",
+    "inviteFailed": "邀请失败",
+    "inviteLoading": "邀请中...",
+    "invite": "邀请",
+    "seatsExceeded": "Pro 计划最多 {{max}} 位成员（当前 {{current}}/{{max}}）。请联系工作空间所有者升级 Enterprise。",
+    "memberRemoved": "成员已移除",
+    "removeFailed": "移除失败",
+    "roleUpdated": "角色已更新",
+    "operationFailed": "操作失败",
+    "workspaceDeleted": "工作空间已删除",
+    "deleteFailed": "删除失败",
+    "roles": {
+      "owner": "所有者",
+      "admin": "管理员",
+      "member": "成员",
+      "viewer": "访客"
+    },
+    "unknownUser": "未知用户",
+    "self": "（你）",
+    "pending": "待接受",
+    "dangerZone": "危险操作",
+    "deleteDescription": "删除工作空间将永久移除工作空间及其所有成员关系，此操作不可恢复。",
+    "hasProjects": "此工作空间还有 {{count}} 个项目，请先选择处理方式",
+    "deleteClear": "清空项目并删除工作空间",
+    "deleteTransfer": "转移项目后删除工作空间",
+    "deleteWorkspace": "删除工作空间",
+    "confirmDelete": "确认删除",
+    "confirmDeleteDescription": "此操作将永久删除「{{name}}」及其所有关联数据，无法恢复。",
+    "projectHandling": "处理项目方式",
+    "clearProjects": "清空项目（不可恢复）",
+    "clearProjectsDesc": "工作空间下所有项目将被永久删除。",
+    "transferProjects": "转移到其他工作空间",
+    "transferProjectsDesc": "选择目标工作空间，保留项目数据。",
+    "confirmRemoveMember": "确认移除成员",
+    "confirmRemoveMemberDesc": "确定要移除该成员吗？该成员将立即失去工作空间访问权限。",
+    "cancel": "取消",
+    "confirmRemove": "确认移除"
+  }
+}

package/src/i18n/server.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import i18next, { type i18n } from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import { resources, fallbackLng, defaultNs, type AppLocale } from './config'
+
+export function createServerI18n(locale: AppLocale): i18n {
+  const i18n = i18next.createInstance()
+  i18n.use(initReactI18next)
+  i18n.init({
+    lng: locale,
+    fallbackLng,
+    defaultNS: defaultNs,
+    resources,
+    interpolation: { escapeValue: false },
+    react: { useSuspense: false },
+  })
+  return i18n
+}

package/src/i18n/types.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { i18n as I18nInstance } from 'i18next'
+import type { AppLocale, NamespaceKey } from './config'
+
+export type { AppLocale, NamespaceKey, I18nInstance }

package/src/lib/__tests__/ai-adapter.test.ts

@@ -23,18 +23,18 @@ describe('getActiveAgent / switchAgent', () => {
   })
 
   it('returns null when no agent is active', async () => {
-    const { getActiveAgent } = await import('@allbluecn/shared/infrastructure/ai/adapter')
+    const { getActiveAgent } = await import('@/shared/ai-cli/adapter')
     expect(getActiveAgent()).toBeNull()
   })
 
   it('switchAgent sets active agent', async () => {
-    const { switchAgent, getActiveAgent } = await import('@allbluecn/shared/infrastructure/ai/adapter')
+    const { switchAgent, getActiveAgent } = await import('@/shared/ai-cli/adapter')
     switchAgent('openai-api')
     expect(getActiveAgent()).toBe('openai-api')
   })
 
   it('switchAgent overwrites previous agent', async () => {
-    const { switchAgent, getActiveAgent } = await import('@allbluecn/shared/infrastructure/ai/adapter')
+    const { switchAgent, getActiveAgent } = await import('@/shared/ai-cli/adapter')
     switchAgent('claude-code')
     switchAgent('ollama')
     expect(getActiveAgent()).toBe('ollama')
@@ -54,7 +54,7 @@ describe('executeViaAgent', () => {
     process.env.OPENAI_API_KEY = 'sk-test'
     process.env.AI_BASE_URL = 'https://test.api.com/v1'
 
-    const { executeViaAgent } = await import('@allbluecn/shared/infrastructure/ai/adapter')
+    const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
     const result = await executeViaAgent(
       { id: 'openai-api', name: 'OpenAI', binary: 'api', version: 'v1', available: true },
       'Say hello',
@@ -79,7 +79,7 @@ describe('executeViaAgent', () => {
     vi.stubGlobal('fetch', mockFetch)
     process.env.OPENAI_API_KEY = 'sk-test'
 
-    const { executeViaAgent } = await import('@allbluecn/shared/infrastructure/ai/adapter')
+    const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
     const result = await executeViaAgent(
       { id: 'openai-api', name: 'OpenAI', binary: 'api', version: 'v1', available: true },
       'Say hello',

package/src/lib/__tests__/cli-detector.test.ts

@@ -25,19 +25,19 @@ describe('getApiAgent', () => {
   })
 
   it('returns undefined when no API key set', async () => {
-    const { getApiAgent } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { getApiAgent } = await import('@/shared/ai-cli/cli-detector')
     expect(getApiAgent()).toBeUndefined()
   })
 
   it('returns undefined when API key is placeholder', async () => {
     process.env.OPENAI_API_KEY = 'sk-your-api-key-here'
-    const { getApiAgent } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { getApiAgent } = await import('@/shared/ai-cli/cli-detector')
     expect(getApiAgent()).toBeUndefined()
   })
 
   it('returns agent info when API key is valid', async () => {
     process.env.OPENAI_API_KEY = 'sk-real-key'
-    const { getApiAgent } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { getApiAgent } = await import('@/shared/ai-cli/cli-detector')
     const agent = getApiAgent()
     expect(agent).toBeDefined()
     expect(agent?.id).toBe('openai-api')
@@ -47,7 +47,7 @@ describe('getApiAgent', () => {
   it('uses AI_MODEL env in display name', async () => {
     process.env.OPENAI_API_KEY = 'sk-real-key'
     process.env.AI_MODEL = 'gpt-4'
-    const { getApiAgent } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { getApiAgent } = await import('@/shared/ai-cli/cli-detector')
     expect(getApiAgent()?.name).toContain('gpt-4')
   })
 })
@@ -58,7 +58,7 @@ describe('detectAgents', () => {
   })
 
   it('returns 16 known agents with executable check', async () => {
-    const { detectAgents } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { detectAgents } = await import('@/shared/ai-cli/cli-detector')
     const agents = await detectAgents()
     expect(agents).toHaveLength(16)
     agents.forEach(a => {
@@ -72,7 +72,7 @@ describe('detectAgents', () => {
       execSync: vi.fn(() => { throw new Error('not found') }),
     }))
 
-    const { detectAgents } = await import('@allbluecn/shared/infrastructure/ai/cli-detector')
+    const { detectAgents } = await import('@/shared/ai-cli/cli-detector')
     const agents = await detectAgents()
     expect(agents).toHaveLength(16)
     agents.forEach(a => expect(a.available).toBe(false))

package/src/lib/__tests__/embedding.test.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { describe, it, expect } from 'vitest'
-import { chunkText } from '@allbluecn/ai-gateway'
+import { chunkText } from '@/server/ai-gateway'
 
 describe('chunkText', () => {
   it('splits text by sentence boundaries', () => {

package/src/lib/__tests__/module-registry.test.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { describe, it, expect, beforeEach } from 'vitest'
-import type { AllBlueModule } from '@allbluecn/shared'
+import type { AllBlueModule } from '@allbluecn/kernel'
 
 describe('ModuleRegistry', () => {
   let registry: typeof import('@allbluecn/shared')['moduleRegistry']

package/src/lib/__tests__/provider-router.test.ts

@@ -35,7 +35,7 @@ vi.mock("@/lib/crypto/api-key-cipher", () => ({
 
 beforeEach(async () => {
   vi.clearAllMocks()
-  const { registerGatewayPorts, resetGatewayPortsForTest } = await import("@allbluecn/ai-gateway")
+  const { registerGatewayPorts, resetGatewayPortsForTest } = await import("@/server/ai-gateway")
   resetGatewayPortsForTest()
   registerGatewayPorts({
     keyCipher: {
@@ -67,7 +67,7 @@ beforeAll(() => {
 import {
   resolveDefaultProviderConfig,
   resolveAiConfigForModel,
-} from '@allbluecn/ai-gateway'
+} from '@/server/ai-gateway'
 import { encryptApiKey } from "@/lib/crypto/api-key-cipher"
 
 const provider = {

package/src/lib/__tests__/rag.test.ts

@@ -26,7 +26,7 @@ const mockInsertEmbedding = vi.hoisted(() => vi.fn())
 const mockSearchByVector = vi.hoisted(() => vi.fn())
 const mockRerankCandidates = vi.hoisted(() => vi.fn().mockResolvedValue(null))
 
-vi.mock('@allbluecn/ai-gateway', () => ({
+vi.mock('@/server/ai-gateway', () => ({
   generateEmbedding: mockGenerateEmbedding,
   chunkText: mockChunkText,
   rerankCandidates: mockRerankCandidates,

package/src/lib/ai/__tests__/story-prompt.test.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { describe, it, expect } from "vitest"
-import { buildStorySystemPrompt } from '@allbluecn/ai-gateway'
+import { buildStorySystemPrompt } from '@/server/ai-gateway'
 
 describe("buildStorySystemPrompt", () => {
   it("基础 prompt 包含 JSONL 输出约束", () => {

package/src/lib/annotation-template.ts

@@ -1 +1,33 @@
-export * from '@allbluecn/shared/lib/annotation-template'
+// 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 { DOMParser } from "@tiptap/pm/model";
+import type { Editor } from "@tiptap/react";
+
+/**
+ * 将 HTML 字符串转为 ProseMirror content 节点数组（用于 insertContent 的 content 字段）。
+ * 客户端调用（onAnnotate 事件触发），document 可用。
+ */
+export function htmlToPmContent(editor: Editor, html: string): any[] {
+  if (typeof document === "undefined" || !html) return [{ type: "paragraph" }];
+  const wrapper = document.createElement("div");
+  wrapper.innerHTML = html;
+  const parser = DOMParser.fromSchema(editor.schema);
+  const parsed = parser.parse(wrapper);
+  const json = parsed.toJSON();
+  return (json as any).content ?? [{ type: "paragraph" }];
+}

package/src/lib/auth/auth-client.ts

@@ -1 +1 @@
-export * from '@allbluecn/ui/auth-client'
+export * from '@/components/ui-shared/auth-client'

package/src/lib/auth/auth.config.ts

@@ -22,7 +22,7 @@ import GoogleProvider from '@auth/core/providers/google'
 import { prisma } from '@allbluecn/database'
 import bcrypt from 'bcryptjs'
 import { getRandomConfig, presetBgColors } from '@/components/settings/personal-team/account/avatar/avatar-config'
-import { resolveIpLocation, getClientIp } from '@allbluecn/shared'
+import { resolveIpLocation, getClientIp } from '@allbluecn/kernel'
 
 type CachedProfile = {
   username: string

package/src/lib/changelog/sdk-versions.ts

@@ -95,7 +95,7 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.6.2",
+        "version": "v0.7.0",
         "lastUpdate": "Sep 3, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"
@@ -148,13 +148,6 @@ export const SDK_GROUPS: SdkGroup[] = [
         "lastUpdate": "Sep 3, 2026",
         "source": "packages/shared/package.json#devDependencies",
         "docsUrl": "https://tiptap.dev/"
-      },
-      {
-        "name": "Lucide React",
-        "version": "v1.27.0",
-        "lastUpdate": "Sep 3, 2026",
-        "source": "packages/ui/package.json#dependencies",
-        "docsUrl": "https://lucide.dev/"
       }
     ]
   }

package/src/lib/collections/index.ts

@@ -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/>.
 
-export { getTagsCollection } from '@allbluecn/plugins-core/tags/tags-collection'
+export { getTagsCollection } from '@/plugins/core/tags/tags-collection'
 export { projectsCollection } from './reference/projects-collection'
 export { usersBriefCollection } from './reference/users-brief-collection'
 export { labelsCollection } from './reference/labels-collection'

package/src/lib/collections/knowledge/knowledge-bases-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listKnowledgeFn } from '@/server/serverFns/knowledge'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const knowledgeBasesCollection = createCollection(
   queryCollectionOptions({

package/src/lib/collections/reference/bookmark-categories-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listBookmarkCategoriesFn } from '@/server/serverFns/knowledge-public/bookmarks/categories'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const bookmarkCategoriesCollection = createCollection(
   queryCollectionOptions({

package/src/lib/collections/reference/labels-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listLabelsFn } from '@/server/serverFns/story/story-crud/labels'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const labelsCollection = createCollection(
   queryCollectionOptions({

package/src/lib/collections/reference/projects-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listProjectsBriefFn } from '@/server/serverFns/project'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const projectsCollection = createCollection(
   queryCollectionOptions({

package/src/lib/collections/reference/users-brief-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listUsersBriefFn } from '@/server/serverFns/story/story-crud/labels'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const usersBriefCollection = createCollection(
   queryCollectionOptions({

package/src/lib/collections/reference/workspaces-collection.ts

@@ -18,7 +18,7 @@
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
 import { listWorkspacesBriefFn } from '@/server/serverFns/workspace'
-import { getQueryClient } from '@allbluecn/shared/lib/query-client-seam'
+import { getQueryClient } from '@/lib/query-client-seam'
 
 export const workspacesCollection = createCollection(
   queryCollectionOptions({

package/src/lib/comment-utils.ts

@@ -1 +1,47 @@
-export * from '@allbluecn/shared/lib/comment-utils'
+// 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/>.
+
+export function maskEmail(email?: string | null): string {
+  if (!email) return "未知用户";
+  const [local, domain] = email.split("@");
+  if (!domain) return email;
+  const prefix = local.length > 3 ? local.slice(0, 3) : local;
+  return `${prefix}***@${domain}`;
+}
+
+export function formatTime(date: Date | string): string {
+  const d = new Date(date);
+  const now = new Date();
+  const diff = now.getTime() - d.getTime();
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return "刚刚";
+  if (minutes < 60) return `${minutes}分钟前`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}小时前`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}天前`;
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+export function formatEditedTime(date: Date | string): string {
+  const time = formatTime(date);
+  return `修改于${time}`;
+}
+
+export function getUserInitial(username: string): string {
+  return (username || "?").charAt(0).toUpperCase();
+}

package/src/lib/crypto/api-key-cipher.ts

@@ -1 +1 @@
-export * from '@allbluecn/plugins-core/server/api-key-cipher'
+export * from '@/plugins/core/server/api-key-cipher'

package/src/lib/datetime.ts

@@ -1,7 +1,130 @@
-export {
-  resolveTimezone,
-  formatDate,
-  formatChatDate,
-  formatRelative,
-  formatTimestamp,
-} from '@allbluecn/shared/lib/datetime'
+// 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 { formatInTimeZone, toZonedTime, fromZonedTime } from 'date-fns-tz'
+import { startOfDay, subDays } from 'date-fns'
+
+const FALLBACK_TIMEZONE = 'Asia/Shanghai'
+
+/**
+ * 解析生效时区：项目时区 > 用户时区 > 浏览器时区 > Asia/Shanghai
+ */
+export function resolveTimezone(
+  projectTz?: string | null,
+  userTz?: string | null,
+): string {
+  const browserTz =
+    typeof Intl !== 'undefined'
+      ? Intl.DateTimeFormat().resolvedOptions().timeZone
+      : FALLBACK_TIMEZONE
+  return projectTz || userTz || browserTz || FALLBACK_TIMEZONE
+}
+
+/**
+ * 时区感知的时间格式化。
+ * @param date UTC Date 对象（来自 DB）
+ * @param timezone IANA 时区，如 "Asia/Shanghai"
+ * @param fmt date-fns 格式，默认 "yyyy-MM-dd HH:mm"
+ */
+export function formatDate(
+  date: Date,
+  timezone: string,
+  fmt = 'yyyy-MM-dd HH:mm',
+): string {
+  try {
+    return formatInTimeZone(date, timezone, fmt)
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, fmt)
+  }
+}
+
+/**
+ * 确定性时间戳格式化：固定时区 + date-fns 数字格式，不依赖运行环境 locale/时区。
+ * SSR 与客户端输出字节级一致，专治 toLocaleString() 引发的 hydration mismatch。
+ * @param date Date 对象或 ISO 字符串
+ * @param fmt date-fns 格式，默认 "yyyy-MM-dd HH:mm"
+ */
+export function formatTimestamp(
+  date: Date | string,
+  fmt = 'yyyy-MM-dd HH:mm',
+): string {
+  const d = typeof date === 'string' ? new Date(date) : date
+  if (Number.isNaN(d.getTime())) return '-'
+  return formatDate(d, FALLBACK_TIMEZONE, fmt)
+}
+
+/**
+ * 相对时间（今天/昨天/具体日期），基于时区计算「今天的 0 点」。
+ * @param now 当前时间（测试注入；生产用默认 new Date()）
+ */
+export function formatRelative(
+  date: Date,
+  timezone: string,
+  now: Date = new Date(),
+): string {
+  try {
+    const todayStart = startOfDayInTimeZone(now, timezone)
+    const yesterdayStart = new Date(todayStart)
+    yesterdayStart.setDate(yesterdayStart.getDate() - 1)
+
+    const dateStart = startOfDayInTimeZone(date, timezone)
+
+    if (dateStart.getTime() === todayStart.getTime()) return '今天'
+    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
+    return formatInTimeZone(date, timezone, 'yyyy-MM-dd')
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
+  }
+}
+
+/**
+ * 获取指定时区下某天的 0 点（UTC Date 对象）。
+ */
+function startOfDayInTimeZone(date: Date, timezone: string): Date {
+  const zoned = toZonedTime(date, timezone)
+  const dayStart = startOfDay(zoned)
+  return fromZonedTime(dayStart, timezone)
+}
+
+/**
+ * 对话历史日期分组标签（今天/昨天/本周/具体日期）。
+ * @param date UTC Date 对象
+ * @param timezone IANA 时区
+ */
+export function formatChatDate(date: Date, timezone: string): string {
+  try {
+    const now = new Date()
+    const todayStart = startOfDayInTimeZone(now, timezone)
+    const yesterdayStart = subDays(todayStart, 1)
+    const weekStart = subDays(todayStart, 7)
+
+    const dateStart = startOfDayInTimeZone(date, timezone)
+
+    if (dateStart.getTime() === todayStart.getTime()) return '今天'
+    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
+    if (dateStart.getTime() >= weekStart.getTime()) return '本周'
+
+    const currentYear = Number(formatInTimeZone(now, timezone, 'yyyy'))
+    const dateYear = Number(formatInTimeZone(date, timezone, 'yyyy'))
+    if (dateYear === currentYear) {
+      return formatInTimeZone(date, timezone, 'M月d日')
+    }
+    return formatInTimeZone(date, timezone, 'yyyy年M月d日')
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
+  }
+}