@ploykit/ui 0.6.0 → 0.6.2

package/src/layouts/SettingsShell.tsx

@@ -0,0 +1,129 @@
+
+import { Link, useLocation, useNavigate } from 'react-router'
+import type { ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import { roleSatisfies, type Perm } from '@ploykit/hooks'
+import { useWorkspace } from '@ploykit/hooks'
+import { buttonVariants } from '../components/ui/button'
+import { Separator } from '../components/ui/separator'
+import {
+  Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue,
+} from '../components/ui/select'
+
+export interface SettingsNavItem {
+  path: string
+  label: string
+  
+  icon?: ReactNode
+  
+  perm?: Perm
+}
+
+export interface SettingsNavGroup {
+  
+  group: string
+  items: SettingsNavItem[]
+}
+
+export interface SettingsShellProps {
+  
+  nav?: SettingsNavGroup[]
+  children: ReactNode
+  title?: string
+  description?: string
+}
+
+export function SettingsShell({ nav, children, title = '设置', description }: SettingsShellProps) {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const role = useWorkspace().current?.role
+
+  const isActive = (path: string) =>
+    location.pathname === path || location.pathname.startsWith(path + '/')
+
+  
+  const visibleNav = (nav ?? [])
+    .map((g) => ({ ...g, items: g.items.filter((i) => roleSatisfies(role, i.perm)) }))
+    .filter((g) => g.items.length > 0)
+
+  const flatItems = visibleNav.flatMap((g) => g.items)
+  const activeItem = flatItems.find((i) => isActive(i.path))
+  const hasNav = visibleNav.length > 0
+
+  return (
+    <div className="mx-auto w-full max-w-6xl">
+      <div>
+        {/* G7.1（双 H1，9 页复现）：壳标题降为非 heading 的品牌区——页内 PageHeader
+            的 h1 是全页唯一一级标题（审计建议二选一降级，此处让位）。
+            视觉保持 text-2xl md:text-3xl 字重不变，仅去掉 heading 语义。 */}
+        <div className="text-2xl md:text-3xl font-bold tracking-tight">{title}</div>
+        {description && <p className="mt-1 text-base text-muted-foreground">{description}</p>}
+      </div>
+      <Separator className="my-4 lg:my-6" />
+
+      <div className={cn('flex flex-col gap-6', hasNav && 'lg:flex-row lg:gap-0 lg:space-x-12')}>
+        {/* 窄屏：分组导航降级为 Select（仅页内导航模式） */}
+        {hasNav && (
+        <div className="lg:hidden">
+          <Select
+            value={activeItem?.path ?? null}
+            onValueChange={(v) => typeof v === 'string' && v && navigate(v)}
+          >
+            <SelectTrigger className="w-full" aria-label="设置导航">
+              <SelectValue>{activeItem?.label ?? '跳转设置页'}</SelectValue>
+            </SelectTrigger>
+            <SelectContent align="start">
+              {visibleNav.map((group) => (
+                <SelectGroup key={group.group}>
+                  <SelectLabel>{group.group}</SelectLabel>
+                  {group.items.map((item) => (
+                    <SelectItem key={item.path} value={item.path}>{item.label}</SelectItem>
+                  ))}
+                </SelectGroup>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        )}
+
+        {/* 宽屏：左侧分组导航（sticky——长设置页滚动时导航常驻；仅页内导航模式）。
+            self-start 是 sticky 生效前提（flex 行内 item 默认 stretch 拉满高度后
+            无滚动余量）；top-0 相对 AppShell 内容区滚动容器（P3-23 起该容器为
+            div（overflow-auto），地标 main 在 SidebarInset——滚动责任未变）。 */}
+        {hasNav && (
+        <aside className="hidden lg:block lg:w-1/5 lg:self-start lg:sticky lg:top-0">
+          <nav aria-label="设置导航">
+            {visibleNav.map((group) => (
+              <div key={group.group} className="mb-6">
+                <p className="mb-2 px-2 text-xs uppercase tracking-wider text-muted-foreground">
+                  {group.group}
+                </p>
+                <ul className="space-y-1">
+                  {group.items.map((item) => (
+                    <li key={item.path}>
+                      <Link
+                        to={item.path}
+                        aria-current={isActive(item.path) ? 'page' : undefined}
+                        className={cn(
+                          buttonVariants({ variant: 'ghost' }),
+                          'w-full justify-start',
+                          isActive(item.path) && 'bg-muted',
+                        )}
+                      >
+                        {item.icon}
+                        {item.label}
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </nav>
+        </aside>
+        )}
+
+        <div className="min-w-0 flex-1">{children}</div>
+      </div>
+    </div>
+  )
+}

package/src/layouts/__tests__/AppShell.test.tsx

@@ -0,0 +1,163 @@
+import '@testing-library/jest-dom/vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { MemoryRouter, Routes, Route } from 'react-router'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { AppShell } from '../AppShell'
+
+
+
+const mocks = vi.hoisted(() => ({ impersonatedBy: undefined as string | undefined }))
+vi.mock('../../../../hooks/src/hooks/useAuth', () => ({
+  useAuth: () => ({
+    user: {
+      email: 'alice@example.com',
+      display_name: 'Alice',
+      impersonated_by: mocks.impersonatedBy,
+    },
+    workspaces: [],
+    loading: false,
+    refresh: vi.fn(),
+    logout: vi.fn(async () => {}),
+  }),
+}))
+
+const nav = [
+  { path: '/app', label: '概览' },
+  { path: '/realtime', label: '实时' },
+]
+
+
+function settingsContent() {
+  return (
+    <nav aria-label="设置导航侧栏">
+      <a href="/app">返回产品</a>
+      <ul>
+        <li><a href="/settings/workspace/general">概况</a></li>
+      </ul>
+    </nav>
+  )
+}
+
+function renderAt(path: string, withSettingsContent = true) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route
+          path="*"
+          element={(
+            <AppShell
+              brand="MyProduct"
+              nav={nav}
+              settingsContent={withSettingsContent ? settingsContent() : undefined}
+            >
+              <div>page-body</div>
+            </AppShell>
+          )}
+        />
+      </Routes>
+    </MemoryRouter>,
+  )
+}
+
+describe('AppShell 设置模式（IA v2）', () => {
+  beforeEach(() => {
+    mocks.impersonatedBy = undefined
+  })
+
+  it('产品路径：渲染产品 nav 项，不渲染 settingsContent', () => {
+    renderAt('/app')
+    expect(screen.queryByRole('link', { name: '返回产品' })).not.toBeInTheDocument()
+    
+    expect(screen.getAllByText('概览').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('实时').length).toBeGreaterThan(0)
+  })
+
+  it('/settings/*：侧栏切换为 settingsContent，产品 nav 隐藏，品牌保留', () => {
+    renderAt('/settings/workspace/general')
+    expect(screen.getByRole('link', { name: '返回产品' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: '概况' })).toBeInTheDocument()
+    expect(screen.queryByText('实时')).not.toBeInTheDocument()
+    expect(screen.getByText('MyProduct')).toBeInTheDocument()
+  })
+
+  it('/account/*：同样进入设置模式', () => {
+    renderAt('/account/profile')
+    expect(screen.getByRole('link', { name: '返回产品' })).toBeInTheDocument()
+    expect(screen.queryByText('实时')).not.toBeInTheDocument()
+  })
+
+  it('未传 settingsContent 时设置路径回退产品 nav', () => {
+    renderAt('/settings/workspace/general', false)
+    expect(screen.queryByRole('link', { name: '返回产品' })).not.toBeInTheDocument()
+
+    expect(screen.getAllByText('实时').length).toBeGreaterThan(0)
+  })
+})
+
+describe('AppShell 模拟会话横幅（ADR 0008）', () => {
+  beforeEach(() => {
+    mocks.impersonatedBy = undefined
+  })
+
+  it('impersonated_by 非空：内容区顶部持久显示警示条（顶栏之上）', () => {
+    mocks.impersonatedBy = '11111111-2222-3333-4444-555555555555'
+    const { container } = renderAt('/app')
+    const banner = screen.getByText('您正处于管理员模拟会话')
+    expect(banner).toBeInTheDocument()
+    
+    const bannerSlot = banner.closest('[data-slot="impersonation-banner"]')
+    const header = container.querySelector('header')
+    expect(bannerSlot).not.toBeNull()
+    expect(header).not.toBeNull()
+    expect(bannerSlot!.compareDocumentPosition(header!)).toBe(Node.DOCUMENT_POSITION_FOLLOWING)
+  })
+
+  it('普通会话（impersonated_by 缺省）：不渲染警示条', () => {
+    renderAt('/app')
+    expect(screen.queryByText('您正处于管理员模拟会话')).not.toBeInTheDocument()
+  })
+})
+
+describe('AppShell 地标结构（P3-23）', () => {
+  it('全树唯一 <main> 地标（SidebarInset 承担），内容区滚动容器不再嵌套 main', () => {
+    const { container } = renderAt('/app')
+    
+    expect(screen.getAllByRole('main')).toHaveLength(1)
+    
+    const scrollContainer = container.querySelector('main > div.flex-1.overflow-auto, [data-slot="sidebar-inset"] > div.overflow-auto')
+    expect(scrollContainer).not.toBeNull()
+    expect(scrollContainer!.textContent).toContain('page-body')
+  })
+})
+
+
+describe('AppShell 侧栏增强（自 stock 镜像化后上提至组合层）', () => {
+  const sidebarState = () => document.querySelector('[data-slot="sidebar"]')?.getAttribute('data-state')
+
+  it('P2-17：sidebar_state=false cookie → 初值折叠（stock provider 只写不读，回读在组合层）', () => {
+    document.cookie = 'sidebar_state=false; path=/'
+    renderAt('/app', false)
+    expect(sidebarState()).toBe('collapsed')
+    document.cookie = 'sidebar_state=; path=/; max-age=0'
+  })
+
+  it('P2-17：无 cookie → 默认展开', () => {
+    document.cookie = 'sidebar_state=; path=/; max-age=0'
+    renderAt('/app', false)
+    expect(sidebarState()).toBe('expanded')
+  })
+
+  it('P3-1：输入焦点时 Ctrl+B 不折叠侧栏（捕获阶段拦截 stock 全局监听）', () => {
+    render(
+      <MemoryRouter initialEntries={['/app']}>
+        <AppShell brand="MyProduct" nav={nav}>
+          <input aria-label="输入框" />
+        </AppShell>
+      </MemoryRouter>,
+    )
+    expect(sidebarState()).toBe('expanded')
+    const input = screen.getByRole('textbox', { name: '输入框' })
+    fireEvent.keyDown(input, { key: 'b', ctrlKey: true })
+    expect(sidebarState()).toBe('expanded')
+  })
+})

package/src/layouts/__tests__/SettingsShell.test.tsx

@@ -0,0 +1,146 @@
+import '@testing-library/jest-dom/vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { MemoryRouter, Routes, Route } from 'react-router'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { SettingsShell, type SettingsNavGroup } from '../SettingsShell'
+
+
+const mocks = vi.hoisted(() => ({ role: undefined as string | undefined }))
+vi.mock('../../../../hooks/src/hooks/useWorkspace', () => ({
+  useWorkspace: () => ({
+    current: mocks.role ? { id: 'ws-1', name: 'Acme', slug: 'acme', role: mocks.role } : null,
+    switchTo: vi.fn(),
+    clear: vi.fn(),
+  }),
+}))
+
+const nav: SettingsNavGroup[] = [
+  {
+    group: '账户',
+    items: [
+      { path: '/settings/profile', label: '个人资料' },
+      { path: '/settings/notifications', label: '通知偏好' },
+    ],
+  },
+  {
+    group: '工作区',
+    items: [
+      { path: '/settings/workspace/general', label: '概况' },
+      { path: '/settings/workspace/members', label: '成员' },
+    ],
+  },
+]
+
+function Page({ title }: { title: string }) {
+  return (
+    <SettingsShell nav={nav} title="设置" description="desc">
+      <div>{title}</div>
+    </SettingsShell>
+  )
+}
+
+function renderAt(path: string) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route path="/settings/profile" element={<Page title="profile-content" />} />
+        <Route path="/settings/notifications" element={<Page title="notifications-content" />} />
+        <Route path="/settings/workspace/members" element={<Page title="members-content" />} />
+      </Routes>
+    </MemoryRouter>,
+  )
+}
+
+describe('SettingsShell', () => {
+  beforeEach(() => { mocks.role = undefined })
+
+  it('渲染标题/描述/全部分组与条目（URL 驱动激活态）', () => {
+    renderAt('/settings/profile')
+    
+    expect(screen.getByText('设置')).toBeInTheDocument()
+    expect(screen.queryByRole('heading', { name: '设置' })).not.toBeInTheDocument()
+    expect(screen.getByText('desc')).toBeInTheDocument()
+    expect(screen.getByText('账户')).toBeInTheDocument()
+    expect(screen.getByText('工作区')).toBeInTheDocument()
+
+    const active = screen.getByRole('link', { name: '个人资料' })
+    expect(active).toHaveAttribute('aria-current', 'page')
+    expect(screen.getByRole('link', { name: '通知偏好' })).not.toHaveAttribute('aria-current')
+    expect(screen.getByText('profile-content')).toBeInTheDocument()
+  })
+
+  it('点击导航项切换激活与内容（无内部 tab state）', () => {
+    renderAt('/settings/profile')
+    fireEvent.click(screen.getByRole('link', { name: '成员' }))
+    expect(screen.getByText('members-content')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: '成员' })).toHaveAttribute('aria-current', 'page')
+    expect(screen.getByRole('link', { name: '个人资料' })).not.toHaveAttribute('aria-current')
+  })
+})
+
+describe('SettingsShell 角色门控（IA v2 hidden 语义）', () => {
+  const gatedNav: SettingsNavGroup[] = [
+    {
+      group: '工作区',
+      items: [
+        { path: '/settings/workspace/general', label: '概况' },
+        { path: '/settings/workspace/members', label: '成员' },
+        { path: '/settings/workspace/audit', label: '审计', perm: 'admin' },
+        { path: '/settings/workspace/billing', label: '计费', perm: 'owner' },
+      ],
+    },
+  ]
+
+  function renderGated() {
+    return render(
+      <MemoryRouter initialEntries={['/settings/workspace/general']}>
+        <SettingsShell nav={gatedNav}>
+          <div>page-body</div>
+        </SettingsShell>
+      </MemoryRouter>,
+    )
+  }
+
+  beforeEach(() => { mocks.role = 'member' })
+
+  it('member：无 perm 项可见，perm=admin（审计）隐藏', () => {
+    renderGated()
+    expect(screen.getByRole('link', { name: '概况' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: '成员' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: '审计' })).not.toBeInTheDocument()
+  })
+
+  it('admin：可见 admin 项（审计），仍隐藏 owner 项（计费）', () => {
+    mocks.role = 'admin'
+    renderGated()
+    expect(screen.getByRole('link', { name: '审计' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: '计费' })).not.toBeInTheDocument()
+  })
+
+  it('owner：全部可见', () => {
+    mocks.role = 'owner'
+    renderGated()
+    expect(screen.getByRole('link', { name: '审计' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: '计费' })).toBeInTheDocument()
+  })
+
+  it('角色未加载（无工作区）：管理项按最小权限隐藏', () => {
+    mocks.role = undefined
+    renderGated()
+    expect(screen.getByRole('link', { name: '概况' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: '审计' })).not.toBeInTheDocument()
+  })
+
+  it('整组过滤后为空则不渲染分组标题', () => {
+    render(
+      <MemoryRouter initialEntries={['/account/profile']}>
+        <SettingsShell
+          nav={[{ group: '仅管理', items: [{ path: '/settings/workspace/audit', label: '审计', perm: 'admin' }] }]}
+        >
+          <div>page-body</div>
+        </SettingsShell>
+      </MemoryRouter>,
+    )
+    expect(screen.queryByText('仅管理')).not.toBeInTheDocument()
+  })
+})

package/src/lib/__tests__/api-error.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest'
+import { ApiError } from '@ploykit/client'
+import { apiErrorMessage } from '../api-error'
+
+
+
+describe('apiErrorMessage', () => {
+  it('已知英文文案 → 中文可行动文案（email already registered / slug already taken）', () => {
+    expect(apiErrorMessage(new ApiError(409, 'E_CONFLICT', 'email already registered')))
+      .toBe('该邮箱已注册，可直接登录或换个邮箱重试')
+    expect(apiErrorMessage(new ApiError(409, 'E_CONFLICT', 'slug already taken')))
+      .toBe('该标识已被占用，请换个工作区名称重试')
+    
+    expect(apiErrorMessage(new ApiError(409, 'E_CONFLICT', '  Email Already Registered ')))
+      .toBe('该邮箱已注册，可直接登录或换个邮箱重试')
+  })
+
+  it('E_QUOTA_EXCEEDED 错误码 → 配额用尽 + 升级指引（优先于 message）', () => {
+    expect(apiErrorMessage(new ApiError(402, 'E_QUOTA_EXCEEDED', 'quota exceeded for workspaces')))
+      .toBe('配额已用尽，可在 设置→计费 升级套餐后重试')
+  })
+
+  it('X4：超时/中止/渠道不支持/畸形响应码 → 中文可行动文案', () => {
+    expect(apiErrorMessage(new ApiError(0, 'E_TIMEOUT', 'request timed out after 15000ms')))
+      .toBe('请求超时，网络可能较慢，请稍后重试')
+    expect(apiErrorMessage(new ApiError(0, 'E_ABORTED', 'request aborted by caller')))
+      .toBe('请求已取消')
+    expect(apiErrorMessage(new ApiError(400, 'E_CHANNEL_TEST_UNSUPPORTED', 'manual channel cannot be tested')))
+      .toContain('不支持测试连接')
+    expect(apiErrorMessage(new ApiError(502, 'E_MALFORMED_RESPONSE', 'non-JSON response (502)')))
+      .toContain('无法识别的响应')
+  })
+
+  it('X4/B-settings-2：服务端中文 details 优先于英文 message', () => {
+    expect(apiErrorMessage(new ApiError(400, 'E_VALIDATION', 'invalid settings key/value', '必须是 0..100000 的整数（0 = 关闭限流）')))
+      .toBe('必须是 0..100000 的整数（0 = 关闭限流）')
+    
+    expect(apiErrorMessage(new ApiError(409, 'E_CONFLICT', 'email already registered', { field: 'email' })))
+      .toBe('该邮箱已注册，可直接登录或换个邮箱重试')
+  })
+
+  it('402（无已知码）→ 需要升级（details 并入）；404 → 不存在；403 → 权限不足', () => {
+    expect(apiErrorMessage(new ApiError(402, 'E_PLAN_LIMIT', 'seats limit')))
+      .toContain('当前套餐不支持此操作')
+    expect(apiErrorMessage(new ApiError(402, 'E_PLAN_LIMIT', 'seats limit', '成员数超出当前套餐上限')))
+      .toContain('成员数超出当前套餐上限')
+    expect(apiErrorMessage(new ApiError(404, 'E_NOT_FOUND', 'workspace not found')))
+      .toBe('不存在或无权访问')
+    expect(apiErrorMessage(new ApiError(403, 'E_FORBIDDEN', 'forbidden'))).toBe('权限不足')
+  })
+
+  it('X4：401/429 给中文兜底（429 带 Retry-After 秒数提示）', () => {
+    expect(apiErrorMessage(new ApiError(401, 'E_UNAUTHENTICATED', 'unauthenticated')))
+      .toBe('登录已过期或未登录，请重新登录后再试')
+    expect(apiErrorMessage(new ApiError(429, 'E_RATE_LIMITED', 'too many requests')))
+      .toBe('请求过于频繁，请稍后再试')
+    expect(apiErrorMessage(new ApiError(429, 'E_RATE_LIMITED', 'too many requests', undefined, 30)))
+      .toBe('请求过于频繁，请稍后再试（约 30 秒后可重试）')
+  })
+
+  it('X4/B-users-5：5xx 不再透传英文原文，统一中文兜底', () => {
+    expect(apiErrorMessage(new ApiError(500, 'E_INTERNAL', 'internal error')))
+      .toBe('服务暂时不可用，请稍后重试；若持续出现请联系平台管理员')
+  })
+
+  it('4xx 未知 ApiError 保留原始 message；网络异常给可重试文案；其余走 fallback', () => {
+    
+    expect(apiErrorMessage(new ApiError(400, 'E_BAD_JSON', 'boom'))).toBe('boom')
+    expect(apiErrorMessage(new TypeError('fetch failed'))).toBe('网络连接失败，请检查网络后重试')
+    expect(apiErrorMessage({}, '兜底文案')).toBe('兜底文案')
+  })
+
+  
+  
+  describe('G7.4 域映射补齐', () => {
+    type Case = { name: string; err: ApiError; expect: string | RegExp }
+    const cases: Case[] = [
+      {
+        name: "E_UNAUTHENTICATED 'current password incorrect' → 改密域文案（压过 401 兜底）",
+        err: new ApiError(401, 'E_UNAUTHENTICATED', 'current password incorrect'),
+        expect: /当前密码不正确，请确认后重新输入/,
+      },
+      {
+        name: "E_VALIDATION 'name required (<=64 chars)' → 名称约束（字节口径）",
+        err: new ApiError(400, 'E_VALIDATION', 'name required (<=64 chars)'),
+        expect: /64 字节/,
+      },
+      {
+        name: "E_VALIDATION 'name required' → 精确子类优先于通用兜底",
+        err: new ApiError(400, 'E_VALIDATION', 'name required'),
+        expect: /名称不能为空$/,
+      },
+      {
+        name: 'E_VALIDATION 未知文案（无 details）→ 通用校验兜底，不再直出英文',
+        err: new ApiError(400, 'E_VALIDATION', 'meter display_name required'),
+        expect: /请求参数有误/,
+      },
+      {
+        name: "前缀匹配：'slug must be 4-40 chars of [a-z0-9-]…' → 标识约束中文",
+        err: new ApiError(400, 'E_VALIDATION', "slug must be 4-40 chars of [a-z0-9-], not starting/ending with '-'"),
+        expect: /标识格式有误/,
+      },
+      {
+        name: '前缀匹配：egress 预检拒绝（含 ADR 编号原文）→ 公网 https 指引',
+        err: new ApiError(400, 'E_VALIDATION', 'egress: "hook.internal" resolves to a private/reserved address 10.0.0.8 — outbound blocked by the SSRF guard'),
+        expect: '回调地址不可达私网/被安全策略拦截，请改用公网 https 地址',
+      },
+      {
+        name: '前缀匹配：egressx: 前缀（引擎配置侧）同文案',
+        err: new ApiError(400, 'E_VALIDATION', 'egressx: URL parse failed'),
+        expect: '回调地址不可达私网/被安全策略拦截，请改用公网 https 地址',
+      },
+      {
+        name: 'E_INVALID_CRON → cron 中文格式指引',
+        err: new ApiError(400, 'E_INVALID_CRON', 'invalid cron expression (expect 5 fields: minute hour day month weekday)'),
+        expect: /Cron 表达式格式有误/,
+      },
+      {
+        name: 'E_INVALID_TZ → 时区中文指引',
+        err: new ApiError(400, 'E_INVALID_TZ', 'invalid timezone (expect IANA name, e.g. Asia/Shanghai)'),
+        expect: /时区无效/,
+      },
+      {
+        name: 'E_CONFLICT 未知冲突（order is not pending）→ 通用冲突兜底',
+        err: new ApiError(409, 'E_CONFLICT', 'order is not pending'),
+        expect: /操作与当前状态冲突/,
+      },
+      {
+        name: 'E_CONFLICT 已有精确映射（last owner）不被通用兜底吞掉',
+        err: new ApiError(409, 'E_CONFLICT', 'last owner cannot leave'),
+        expect: '最后一个所有者不能离开工作区，请先转移所有权或删除工作区',
+      },
+      {
+        name: "E_CONFLICT 'target is already an owner'（成员转让）→ 域文案",
+        err: new ApiError(409, 'E_CONFLICT', 'target is already an owner'),
+        expect: '对方已是所有者，无需重复转让所有权',
+      },
+      {
+        name: "前缀匹配：'workspace cannot be deleted: open orders exist'（删除前置拦截）→ 域文案",
+        err: new ApiError(409, 'E_CONFLICT', 'workspace cannot be deleted: open orders exist'),
+        expect: '工作区暂时无法删除：存在未满足的前置条件（如未完结订单或活跃资源），请先处理后再试',
+      },
+    ]
+
+    it.each(cases)('$name', ({ err, expect: expected }) => {
+      const got = apiErrorMessage(err)
+      if (expected instanceof RegExp) expect(got).toMatch(expected)
+      else expect(got).toBe(expected)
+    })
+
+    it('优先级回归：消息级 > details > 码级（同一错误三种来源层层兜底）', () => {
+      
+      expect(apiErrorMessage(new ApiError(400, 'E_VALIDATION', 'bad value', '限流值必须是 0..100000 的整数')))
+        .toBe('限流值必须是 0..100000 的整数')
+      
+      expect(apiErrorMessage(new ApiError(402, 'E_QUOTA_EXCEEDED', 'quota exceeded')))
+        .toBe('配额已用尽，可在 设置→计费 升级套餐后重试')
+      
+      expect(apiErrorMessage(new ApiError(401, 'E_UNAUTHENTICATED', 'session expired')))
+        .toBe('登录已过期或未登录，请重新登录后再试')
+    })
+  })
+})

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

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest'
+import { browserTzLabel, formatDateTime, formatDateTimeTz } from '../utils'
+
+
+describe('时区口径标注（B1）', () => {
+  it('browserTzLabel 恒有非空标签（shortOffset→short→"本地时区"逐档兜底）', () => {
+    const label = browserTzLabel()
+    expect(label.length).toBeGreaterThan(0)
+    
+    expect(label).toMatch(/^(GMT|UTC|本地时区)/)
+  })
+
+  it('formatDateTimeTz = 本地时间 + " (标签)" 口径后缀', () => {
+    const iso = '2026-10-12T01:00:00Z'
+    expect(formatDateTimeTz(iso)).toBe(`${formatDateTime(iso)} (${browserTzLabel()})`)
+  })
+
+  it('非法时间不抛异常（与 formatDateTime 同一容错口径）', () => {
+    expect(typeof formatDateTimeTz('not-a-date')).toBe('string')
+  })
+})