Article·  

构建以隐私优先的反馈小组件

一个轻量、注重隐私的小组件,用于收集 Nuxt 文档的反馈,基于 Drizzle、NuxtHub 数据库和 Motion Vue 构建。
Hugo Richard

Hugo Richard

@hugorcd__

Sébastien Chopin

Sébastien Chopin

@Atinux

文档是 Nuxt 开发者体验的核心。为了持续改进文档,我们需要一种简单有效的方式,能直接在每个页面收集用户反馈。以下是我们设计并实现反馈小组件的过程,灵感来自 Plausible 的隐私优先理念。

为什么需要反馈小组件?

当前,用户可以通过创建 GitHub issue 或直接联系我们来提供文档反馈。虽然这些渠道很有价值且依然重要,但它们要求用户离开当前上下文,需要经过多个步骤才能分享想法。

我们想要的是不同的方案:

  • 上下文相关:直接集成在每个文档页面中
  • 无障碍的:最多 2 次点击即可提交反馈
  • 尊重隐私:无个人追踪,设计上符合 GDPR

技术架构

我们的解决方案包含三个主要部分:

1. 结合 Motion 动画的前端

界面结合了 Vue 3 的 Composition API 与 Motion for Vue,打造引人入胜的用户体验。该小组件使用布局动画实现状态平滑过渡,并采用弹簧物理效果营造自然反馈。useFeedback 组合函数负责所有状态管理,并在用户切换页面时自动重置。

例如,以下是成功状态的动画:

<template>
  <!-- ... -->
  <motion.div
    v-if="isSubmitted"
    key="success"
    :initial="{ opacity: 0, scale: 0.95 }"
    :animate="{ opacity: 1, scale: 1 }"
    :transition="{ duration: 0.3 }"
    class="flex items-center gap-3 py-2"
    role="status"
    aria-live="polite"
    aria-label="反馈提交成功"
  >
    <motion.div
      :initial="{ scale: 0 }"
      :animate="{ scale: 1 }"
      :transition="{ delay: 0.1, type: 'spring', visualDuration: 0.4 }"
      class="text-xl"
      aria-hidden="true"
    >
    </motion.div>
    <motion.div
      :initial="{ opacity: 0, x: 10 }"
      :animate="{ opacity: 1, x: 0 }"
      :transition="{ delay: 0.2, duration: 0.3 }"
    >
      <div class="text-sm font-medium text-highlighted">
        感谢您的反馈!
      </div>
      <div class="text-xs text-muted mt-1">
        您的意见帮助我们改进文档。
      </div>
    </motion.div>
  </motion.div>
  <!-- ... -->
</template>

反馈小组件的源码可在此处查看。

2. 受 Plausible 启发的匿名化处理

难点在于如何在保护隐私的前提下检测重复(用户更改意见)。我们借鉴了 Plausible 关于无 Cookie 统计独立访客的思路。

export async function generateHash(
  today: string,
  ip: string,
  domain: string,
  userAgent: string
): Promise<string> {
  const data = `${today}+${domain}+${ip}+${userAgent}`

  const buffer = await crypto.subtle.digest(
    'SHA-1',
    new TextEncoder().encode(data)
  )

  return [...new Uint8Array(buffer)]
    .map(b => b.toString(16).padStart(2, '0'))
    .join('')
}

该方法通过结合以下信息生成每日唯一标识:

  • IP + User-Agent:由每个 HTTP 请求自然发送
  • 域名:实现环境隔离
  • 当前日期:确保标识每日更换

为何安全?

  • IP 和 User-Agent 从不存储于数据库
  • 哈希值每日变化,防止长期追踪
  • 几乎无法从哈希值反推原始数据
  • 设计符合 GDPR(无持久个人数据)

3. 具有冲突处理的数据库持久化

首先,我们定义反馈表的架构,并在 pathfingerprint 列上添加唯一约束。

export const feedback = sqliteTable('feedback', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  rating: text('rating').notNull(),
  feedback: text('feedback'),
  path: text('path').notNull(),
  title: text('title').notNull(),
  stem: text('stem').notNull(),
  country: text('country').notNull(),
  fingerprint: text('fingerprint').notNull(),
  createdAt: integer({ mode: 'timestamp' }).notNull(),
  updatedAt: integer({ mode: 'timestamp' }).notNull()
}, table => [uniqueIndex('path_fingerprint_idx').on(table.path, table.fingerprint)])

随后,服务器侧使用 Drizzle 结合 UPSERT 策略:

await drizzle.insert(tables.feedback).values({
  rating: data.rating,
  feedback: data.feedback || null,
  path: data.path,
  title: data.title,
  stem: data.stem,
  country: event.context.cf?.country || 'unknown',
  fingerprint,
  createdAt: new Date(),
  updatedAt: new Date()
}).onConflictDoUpdate({
  target: [tables.feedback.path, tables.feedback.fingerprint],
  set: {
    rating: data.rating,
    feedback: data.feedback || null,
    country,
    updatedAt: new Date()
  }
})

这种方法支持用户当天更改意见时更新数据,新反馈则创建,同时实现了每页每用户的自动去重。

服务器端源码可在此处查看。

共享类型确保一致性

我们使用 Zod 进行运行时校验及类型生成:

export const FEEDBACK_RATINGS = [
  'very-helpful',
  'helpful', 
  'not-helpful',
  'confusing'
] as const

export const feedbackSchema = z.object({
  rating: z.enum(FEEDBACK_RATINGS),
  feedback: z.string().optional(),
  path: z.string(),
  title: z.string(),
  stem: z.string()
})

export type FeedbackInput = z.infer<typeof feedbackSchema>

该做法确保前端、API 和数据库之间的类型一致。

下一步计划

该小组件现已在所有文档页面上线。我们的下一目标是在 nuxt.com 内部构建一个管理界面,分析反馈模式,识别需要改进的页面。这样可基于真实用户反馈,不断提升文档质量。

完整源码可在 GitHub 上获取,欢迎参考和贡献!