From a2849bf6b73b10114ba82327d3a929f200b10240 Mon Sep 17 00:00:00 2001
From: Yaojia Wang <yaojia.wang@billo.life>
Date: Mon, 29 Jun 2026 16:52:43 +0200
Subject: [PATCH] =?UTF-8?q?feat(web):=20Field=20=E6=A0=87=E7=AD=BE?=
 =?UTF-8?q?=E8=87=AA=E5=8A=A8=E5=85=B3=E8=81=94=E6=8E=A7=E4=BB=B6=20+=20?=
 =?UTF-8?q?=E5=85=A8=E5=B1=80=E5=A3=B3=E6=97=A0=E9=9A=9C=E7=A2=8D(skip=20l?=
 =?UTF-8?q?ink/=E8=AE=BE=E7=BD=AE=E5=8F=AF=E8=AE=BF=E9=97=AE=E5=90=8D/?=
 =?UTF-8?q?=E6=8A=BD=E5=B1=89=E7=84=A6=E7=82=B9=E5=BD=92=E8=BF=98)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/web/components/AppShell.tsx          | 19 +++++++++++++++++--
 apps/web/components/BackendDownNotice.tsx | 19 +++++++++++++++++++
 apps/web/components/NavDrawer.tsx         |  5 ++++-
 apps/web/components/ui/Field.tsx          | 15 ++++++++++++---
 4 files changed, 52 insertions(+), 6 deletions(-)
 create mode 100644 apps/web/components/BackendDownNotice.tsx

diff --git a/apps/web/components/AppShell.tsx b/apps/web/components/AppShell.tsx
index 8f6a39f..83ba601 100644
--- a/apps/web/components/AppShell.tsx
+++ b/apps/web/components/AppShell.tsx
@@ -33,6 +33,12 @@ export function AppShell({
       className="min-h-screen"
       style={{ ["--chrome" as string]: projectId ? "7rem" : "4rem" }}
     >
+      <a
+        href="#main"
+        className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-50 focus:rounded focus:border focus:border-line focus:bg-panel focus:px-3 focus:py-2 focus:text-sm focus:text-ink focus:shadow-paper"
+      >
+        跳到正文
+      </a>
       <header className="flex h-16 items-center gap-4 border-b border-line bg-panel px-4 sm:px-6">
         <NavDrawer projectId={projectId} activeNav={activeNav} />
         <Link
@@ -52,10 +58,15 @@ export function AppShell({
             {subtitle}
           </span>
         ) : null}
-        <nav className="ml-auto flex shrink-0 items-center gap-2 text-sm">
+        <nav
+          aria-label="快捷操作"
+          className="ml-auto flex shrink-0 items-center gap-2 text-sm"
+        >
           <ThemeToggle />
           <Link
             href="/settings/providers"
+            aria-label="设置"
+            title="设置"
             className={buttonClass({
               variant: "ghost",
               size: "sm",
@@ -72,7 +83,11 @@ export function AppShell({
       ) : null}
       <div className="flex">
         <LeftNav projectId={projectId} activeNav={activeNav} />
-        <main className="min-h-[calc(100vh-var(--chrome,4rem))] min-w-0 flex-1 bg-bg">
+        <main
+          id="main"
+          tabIndex={-1}
+          className="min-h-[calc(100vh-var(--chrome,4rem))] min-w-0 flex-1 bg-bg"
+        >
           {children}
         </main>
       </div>
diff --git a/apps/web/components/BackendDownNotice.tsx b/apps/web/components/BackendDownNotice.tsx
new file mode 100644
index 0000000..1a3d190
--- /dev/null
+++ b/apps/web/components/BackendDownNotice.tsx
@@ -0,0 +1,19 @@
+import { StatusNote } from "./ui/StatusNote";
+
+interface BackendDownNoticeProps {
+  className?: string;
+}
+
+// 后端不可达时的统一提示（多个页面 backend-down 分支复用）。
+export function BackendDownNotice({ className }: BackendDownNoticeProps) {
+  return (
+    <StatusNote
+      variant="danger"
+      title="无法连接后端服务"
+      role="alert"
+      className={className}
+    >
+      请确认后端 API 已启动后刷新本页。
+    </StatusNote>
+  );
+}
diff --git a/apps/web/components/NavDrawer.tsx b/apps/web/components/NavDrawer.tsx
index 9317dd8..e707ce2 100644
--- a/apps/web/components/NavDrawer.tsx
+++ b/apps/web/components/NavDrawer.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useRef, useState } from "react";
 import { Menu } from "lucide-react";
 
 import { Button } from "@/components/ui/Button";
@@ -16,10 +16,12 @@ interface NavDrawerProps {
 // 移动端导航：汉堡按钮 + 左侧抽屉（仅 <lg；桌面用 LeftNav 静态侧栏）。UX §5.1。
 export function NavDrawer({ projectId, activeNav }: NavDrawerProps) {
   const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
 
   return (
     <>
       <Button
+        ref={triggerRef}
         onClick={() => setOpen(true)}
         aria-label="打开导航"
         aria-expanded={open}
@@ -34,6 +36,7 @@ export function NavDrawer({ projectId, activeNav }: NavDrawerProps) {
         onClose={() => setOpen(false)}
         side="left"
         label="主导航"
+        triggerRef={triggerRef}
       >
         <NavItems
           projectId={projectId}
diff --git a/apps/web/components/ui/Field.tsx b/apps/web/components/ui/Field.tsx
index 5506222..3101044 100644
--- a/apps/web/components/ui/Field.tsx
+++ b/apps/web/components/ui/Field.tsx
@@ -1,4 +1,6 @@
-import type { ReactNode } from "react";
+"use client";
+
+import { cloneElement, isValidElement, useId, type ReactNode } from "react";
 
 import {
   cn,
@@ -26,13 +28,20 @@ export function Field({
   required = false,
   className,
 }: FieldProps) {
+  const autoId = useId();
+  const id = htmlFor ?? autoId;
   const labelText = required ? `${label} *` : label;
+  // 自动把 id 注入唯一子控件，建立 label↔控件关联（仅当子控件自身未带 id）。
+  const control =
+    isValidElement<{ id?: string }>(children) && children.props.id == null
+      ? cloneElement(children, { id })
+      : children;
   return (
     <div className={cn("space-y-1.5", className)}>
-      <label htmlFor={htmlFor} className={fieldLabelClass()}>
+      <label htmlFor={id} className={fieldLabelClass()}>
         {labelText}
       </label>
-      {children}
+      {control}
       {error ? <p className={fieldErrorClass()}>{error}</p> : null}
       {!error && help ? <p className={fieldHelpClass()}>{help}</p> : null}
     </div>