表单校验与反馈：让用户知道下一步怎么做

// ❌ 坏做法：onChange 触发校验，每按一个键都报错
function EmailField() {
  const [value, setValue] = useState('')
  const [error, setError] = useState('')
 
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value)
    // 每次按键都校验，第一个字符就报错
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e.target.value)) {
      setError('请输入有效的邮箱地址')
    }
  }
 
  return (
    <div>
      <input value={value} onChange={handleChange} />
      {error && <span role="alert">{error}</span>}
    </div>
  )
}

// ✅ 好做法：onBlur 触发校验 + 已触碰后才显示
function EmailField() {
  const [value, setValue] = useState('')
  const [error, setError] = useState('')
  const [touched, setTouched] = useState(false)
 
  const validate = (v: string) => {
    if (!v) return '邮箱不能为空'
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return '请输入有效的邮箱地址，例如 [email protected]'
    return ''
  }
 
  const handleBlur = () => {
    setTouched(true)
    setError(validate(value))
  }
 
  return (
    <div>
      <input
        value={value}
        onChange={(e) => setValue(e.target.value)}
        onBlur={handleBlur}
        aria-invalid={touched && !!error}
        aria-describedby={error ? 'email-error' : undefined}
      />
      {/* 只在触碰过且有错误时显示 */}
      {touched && error && (
        <span id="email-error" role="alert">{error}</span>
      )}
    </div>
  )
}

// ❌ 坏做法：直接展示后端原始错误
async function handleSubmit(data: FormData) {
  try {
    await api.submit(data)
  } catch (err: any) {
    setGlobalError(err.response.data.message)
    // 可能显示: "UserAlreadyExists" 或 '{"code":409,"msg":"conflict"}'
  }
}

// ✅ 好做法：服务端错误码 → 用户可执行的文案
const ERROR_MESSAGE_MAP: Record<string, string> = {
  UserAlreadyExists: '该邮箱已注册，是否直接登录？',
  PasswordPolicyViolation: '密码至少 8 位，需包含大写字母和数字',
  EmailFormatInvalid: '请输入有效的邮箱地址，例如 [email protected]',
  AccountLocked: '账户已锁定，请 30 分钟后重试或联系客服',
  Default: '提交失败，请稍后重试。如果问题持续，请联系客服',
}
 
function mapServerError(code: string): string {
  return ERROR_MESSAGE_MAP[code] ?? ERROR_MESSAGE_MAP.Default
}
 
async function handleSubmit(data: FormData) {
  try {
    await api.submit(data)
  } catch (err: any) {
    const code = err.response?.data?.code ?? 'Default'
    setGlobalError(mapServerError(code))
  }
}

// ❌ 坏做法：只有防抖，没有竞态控制
function useUsernameCheck() {
  const [status, setStatus] = useState<'idle' | 'checking' | 'available' | 'taken'>('idle')
 
  const check = useCallback(
    debounce(async (username: string) => {
      setStatus('checking')
      const res = await api.checkUsername(username)
      // 如果请求返回顺序颠倒，这里会覆盖正确结果
      setStatus(res.available ? 'available' : 'taken')
    }, 500),
    []
  )
 
  return { status, check }
}

// ✅ 好做法：防抖 + AbortController 取消过期请求
function useUsernameCheck() {
  const [status, setStatus] = useState<'idle' | 'checking' | 'available' | 'taken'>('idle')
  const abortRef = useRef<AbortController | null>(null)
 
  const check = useCallback(
    debounce(async (username: string) => {
      // 取消上一次未完成的请求
      abortRef.current?.abort()
      const controller = new AbortController()
      abortRef.current = controller
 
      setStatus('checking')
      try {
        const res = await api.checkUsername(username, { signal: controller.signal })
        // 只有当前请求没被取消时才更新状态
        if (!controller.signal.aborted) {
          setStatus(res.available ? 'available' : 'taken')
        }
      } catch (err) {
        if (!controller.signal.aborted) {
          setStatus('idle')
        }
      }
    }, 500),
    []
  )
 
  return { status, check }
}

// ❌ 坏做法：提交失败后重置表单
async function onSubmit(data: FormData) {
  try {
    await api.submit(data)
    router.push('/success')
  } catch {
    reset() // 用户填的所有内容全部丢失
    setError('root', { message: '提交失败，请重试' })
  }
}

// ✅ 好做法：失败时保留表单值 + 定向错误
async function onSubmit(data: FormData) {
  try {
    await api.submit(data)
    // 成功后才清除草稿
    localStorage.removeItem(DRAFT_KEY)
    router.push('/success')
  } catch (err: any) {
    const code = err.response?.data?.code
    // 如果是字段级错误，定位到具体字段
    if (code === 'EmailAlreadyUsed') {
      setError('email', { message: '该邮箱已注册，是否直接登录？' })
    } else {
      setError('root', { message: mapServerError(code) })
    }
    // 不调用 reset()，用户输入的内容保留
  }
}

// 草稿自动保存 hook
function useFormDraft<T extends Record<string, unknown>>(key: string, defaultValues: T) {
  const storageKey = `draft:${key}`
 
  // 初始化时尝试恢复草稿
  const getInitialValues = (): T => {
    try {
      const saved = sessionStorage.getItem(storageKey)
      return saved ? { ...defaultValues, ...JSON.parse(saved) } : defaultValues
    } catch {
      return defaultValues
    }
  }
 
  const form = useForm<T>({ defaultValues: getInitialValues() })
 
  // 监听值变化，自动保存草稿
  useEffect(() => {
    const subscription = form.watch((values) => {
      sessionStorage.setItem(storageKey, JSON.stringify(values))
    })
    return () => subscription.unsubscribe()
  }, [form.watch])
 
  const submitAndClear = async (onSubmit: (data: T) => Promise<void>) => {
    await onSubmit(form.getValues())
    sessionStorage.removeItem(storageKey) // 成功后清除草稿
  }
 
  return { ...form, submitAndClear }
}

// ❌ 坏做法：没有 ARIA 属性，屏幕阅读器无法感知错误
<div className="field">
  <label>邮箱</label>
  <input value={value} onChange={handleChange} />
  {error && <span className="error-text">{error}</span>}
</div>

// ✅ 好做法：完整的 ARIA 关联
<div className="field">
  <label htmlFor="email">邮箱</label>
  <input
    id="email"
    name="email"
    value={value}
    onChange={handleChange}
    onBlur={handleBlur}
    aria-invalid={touched && !!error}
    aria-describedby={touched && error ? 'email-error' : undefined}
  />
  {touched && error && (
    <span id="email-error" role="alert">
      {error}
    </span>
  )}
</div>