add-analytics

为检测到的 Web 技术栈添加事件跟踪、错误监控和状态端点。

阶段 1：检测技术栈

读取项目并确定要安装的内容。

1.1 框架

• next.config.* → Next.js（检查是 App Router 还是 Pages Router）
• vite.config.* → Vite / React SPA
• astro.config.* → Astro
• nuxt.config.* → Nuxt
• Python 后端（main.py、app.py、manage.py）→ FastAPI / Django / Flask

1.2 现有分析工具

检查是否已安装分析或监控工具：

• posthog-js 或 posthog-node → 已有 PostHog
• @sentry/nextjs 或 @sentry/react 或 sentry-sdk → 已有 Sentry
• @vercel/analytics → 已有 Vercel Analytics
• @google-analytics 或 gtag → 已有 GA

如果已经安装，请审核现有配置，而不是重新安装。检查是否存在缺漏（缺少错误边界、没有服务端跟踪、没有健康端点）。

1.3 询问用户

Detected: [framework]
Existing analytics: [what's already there, or "none"]

I'll set up:
1. PostHog — event tracking, user identification, feature flags
2. Sentry — error tracking with source maps
3. Health endpoint — /api/status for uptime monitoring

Need your project keys:
- PostHog API key (get from app.posthog.com → Project Settings)
- Sentry DSN (get from sentry.io → Project Settings → Client Keys)

Or I can set up the code and you add the keys later.

阶段 2：实现可观测性

仅加载此项目所需的实现参考：

• PostHog 分析： 添加客户端或服务端跟踪、页面浏览、身份识别或类型化事件前，请先阅读 references/posthog.md。
• Sentry 错误跟踪： 配置 Sentry、错误边界或结构化日志前，请先阅读 references/sentry.md。
• 健康端点： 添加 Next.js 或 FastAPI 状态路由及运行时间监控前，请先阅读 references/health-endpoint.md。

保留现有集成。如果系统已经存在，请使用相应参考审核缺漏，而不是重新安装。所有示例都应与检测到的框架和身份验证模型相匹配。

阶段 3：环境变量

添加到 .env.local（或 .env）：

# PostHog
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_API_KEY=phc_...  # Same key, used server-side

# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/456
SENTRY_AUTH_TOKEN=sntrys_...  # For source map uploads
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

确认这些内容均未提交到 git。检查 .gitignore 是否包含 .env*。

阶段 4：验证

完成所有接线后，测试每个系统：

PostHog:
[ ] Open the app → check PostHog dashboard for a pageview event
[ ] Navigate between pages → each page triggers a pageview
[ ] Log in → user appears in PostHog with email/name (identified)
[ ] Track a custom event → appears in PostHog events
[ ] Log out → posthog.reset() called, new anonymous session

Sentry:
[ ] Add a temporary `throw new Error('sentry test')` to a page
[ ] Load the page → error appears in Sentry dashboard
[ ] Check that source maps resolve (you see your actual code, not minified)
[ ] Remove the test error
[ ] Error boundary renders fallback UI (not a white screen)

Health Endpoint:
[ ] GET /api/status returns 200 with uptime and database status
[ ] If database is down, returns 503
[ ] Set up monitoring service to ping it every 5 minutes

告知用户哪些系统已启用并正常工作。

重要说明

• PostHog 免费套餐： 每月最多 1M 个事件。依赖这些限额前，请确认当前套餐的限制。
• Sentry 免费套餐： 每月最多 5K 个错误。依赖这些限额前，请确认当前套餐的限制。
• 不要在 PostHog 事件中跟踪 PII（不要跟踪密码、信用卡号）。用户 ID 和电子邮件地址可以跟踪。
• 采样率很重要。 生产环境中采用 10% 的跟踪采样率，成本几乎为零。仅在调试特定问题时提高采样率。
• 源映射 对 Sentry 至关重要。没有源映射，错误堆栈跟踪将显示压缩后的代码。对于 Next.js，Sentry 向导会处理此事。对于其他框架，请在构建期间上传映射文件。