# toSentrySetup

Sentry 统一初始化工具集，支持 Vue 3、Vue 2、React 和纯浏览器环境。通过 sub-path exports 实现模块隔离，主入口 `xn-fe-tools` 不包含任何 Sentry 代码，Sentry SDK 已内置打包，**无需单独安装任何 Sentry 包**。

## 引入方式

根据框架选择对应的子路径入口：

```ts
// Vue 3
import { toVue3SentrySetup } from 'xn-fe-tools/sentry/vue3'

// Vue 2
import { toVue2SentrySetup } from 'xn-fe-tools/sentry/vue2'

// React
import { toReactSentrySetup } from 'xn-fe-tools/sentry/react'

// 纯浏览器（无框架）
import { toSentrySetup } from 'xn-fe-tools/sentry/browser'
```

## 基础用法

### Vue 3

```ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { toVue3SentrySetup } from 'xn-fe-tools/sentry/vue3'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({ history: createWebHistory(), routes: [] })

const { isInitialized, captureException } = toVue3SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  app,
  router, // 可选，提供后自动启用路由级性能追踪
})

app.use(router).mount('#app')
```

### Vue 2

```ts
import Vue from 'vue'
import Router from 'vue-router'
import { toVue2SentrySetup } from 'xn-fe-tools/sentry/vue2'

const router = new Router({ routes: [] })

toVue2SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  Vue,
  router, // 可选
})
```

### React

```ts
import { toReactSentrySetup } from 'xn-fe-tools/sentry/react'

toReactSentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
})
```

### 纯浏览器

```ts
import { toSentrySetup } from 'xn-fe-tools/sentry/browser'

const { isInitialized, captureException, captureMessage, setUser } = toSentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
})
```

## API 参数说明

### 通用基础配置（SentryBaseOptions）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `dsn` | `string` | **必填** | Sentry DSN |
| `environment` | `string` | `'production'` | 运行环境标识 |
| `enabled` | `boolean` | `true` | 是否启用 Sentry；`false` 时跳过初始化 |
| `tracesSampleRate` | `number` | `0.1` | 性能追踪采样率（0~1） |
| `replaysSessionSampleRate` | `number` | `0.1` | 会话回放采样率（0~1） |
| `replaysOnErrorSampleRate` | `number` | `1.0` | 错误回放采样率（0~1） |
| `enableTracing` | `boolean` | `true` | 是否启用 `browserTracingIntegration` |
| `enableReplay` | `boolean` | `true` | 是否启用 `replayIntegration` |
| `breadcrumbs` | `BreadcrumbsConfig` | `undefined` | 面包屑配置，见下方说明 |
| `beforeSend` | `(event) => event \| null` | — | 事件上报前的回调，可过滤或修改事件 |
| `integrations` | `array` | — | 自定义集成数组，与默认集成合并 |

**配置优先级**：`enableTracing` / `enableReplay` / `breadcrumbs`（简化参数）> `integrations` 数组 > 默认配置

### BreadcrumbsConfig

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `console` | `boolean` | `true` | 是否记录 console 输出 |
| `dom` | `boolean` | `true` | 是否记录 DOM 交互事件 |
| `fetch` | `boolean` | `true` | 是否记录 fetch 请求 |
| `xhr` | `boolean` | `true` | 是否记录 XMLHttpRequest 请求 |
| `history` | `boolean` | `true` | 是否记录浏览器导航历史 |

### Vue 3 专有参数（Vue3SentryOptions）

| 参数 | 类型 | 说明 |
|------|------|------|
| `app` | `App` | **必填**，Vue 3 应用实例 |
| `router` | `Router` | 可选，Vue Router 实例；提供后启用路由级性能追踪 |

### Vue 2 专有参数（Vue2SentryOptions）

| 参数 | 类型 | 说明 |
|------|------|------|
| `Vue` | `VueConstructor` | **必填**，Vue 2 构造函数 |
| `router` | `VueRouter` | 可选，Vue Router 实例；提供后启用路由级性能追踪 |

### React 专有参数（ReactSentryOptions）

| 参数 | 类型 | 说明 |
|------|------|------|
| `reactRouter` | `object` | 可选，React Router 配置；提供后启用路由级性能追踪 |

## 返回值（SentrySetupReturn）

所有 4 个入口函数返回相同的结构：

| 字段 | 类型 | 说明 |
|------|------|------|
| `isInitialized` | `boolean` | Sentry 是否成功初始化 |
| `captureException` | `(error) => string \| undefined` | 手动上报异常，返回 event ID |
| `captureMessage` | `(message) => string \| undefined` | 手动上报消息，返回 event ID |
| `setUser` | `(user \| null) => void` | 设置/清除当前用户信息 |

当 DSN 无效或 `enabled=false` 时，`isInitialized` 为 `false`，其余方法均为安全的空操作（不抛出异常）。

## 简化配置示例

```ts
toVue3SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  app,
  // 简化配置（推荐）
  enableTracing: true,
  enableReplay: false, // 关闭会话录制
  breadcrumbs: {
    console: false, // 不记录 console 输出
    fetch: true,
  },
})
```

## 高级用法

使用重新导出的集成函数进行自定义配置（无需单独安装 `@sentry/vue`）：

```ts
import { toVue3SentrySetup, replayIntegration, breadcrumbsIntegration } from 'xn-fe-tools/sentry/vue3'

toVue3SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  app,
  enableReplay: false, // 关闭默认 replay
  integrations: [
    replayIntegration({ maskAllText: false }), // 自定义 replay 配置
    breadcrumbsIntegration({ console: false }),
  ],
})
```

各子路径入口均重新导出以下集成函数：
- `breadcrumbsIntegration`
- `browserTracingIntegration`
- `replayIntegration`
- `feedbackIntegration`
- `httpClientIntegration`
- `captureConsoleIntegration`
- `contextLinesIntegration`
- `extraErrorDataIntegration`
- `reportingObserverIntegration`

## getSentryViteConfig

用于生成 `@sentry/vite-plugin` 的配置对象，简化 Source Map 上传配置。

```ts
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin' // 需单独安装为 devDependency
import { getSentryViteConfig } from 'xn-fe-tools/sentry/browser' // 任意子路径均可导入

export default defineConfig({
  plugins: [
    sentryVitePlugin(getSentryViteConfig({
      org: 'my-org',
      project: 'my-project',
      authToken: process.env.SENTRY_AUTH_TOKEN,
    })),
  ],
  build: { sourcemap: true },
})
```

`getSentryViteConfig` 参数：

| 参数 | 类型 | 说明 |
|------|------|------|
| `org` | `string` | **必填**，Sentry 组织 slug |
| `project` | `string` | **必填**，Sentry 项目 slug |
| `authToken` | `string` | **必填**，Sentry Auth Token |
| `sourcemaps.filesToDeleteAfterUpload` | `string[]` | 上传后自动删除的文件，默认 `['./dist/**/*.map']` |

## 注意事项

- DSN 为空字符串或 `undefined` 时，会在控制台输出 `[xn-fe-tools] Sentry DSN is not provided` 警告
- `enabled=false` 时静默跳过，不输出任何警告
- `@sentry/vite-plugin` 需用户自行安装为 `devDependency`，`getSentryViteConfig` 仅生成配置对象
- Vue 2 和 Vue 3 共用 `@sentry/vue`（Sentry v8+ 同时支持两个版本）
- 其他 Sentry 原生 `init` 配置项均可透传（如 `release`、`dist`、`ignoreErrors` 等）