@fz-firefly/taro 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @fz-firefly/taro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+萤火虫 SDK 的 Taro 平台适配层。负责 Taro 存储、请求、系统信息、全局错误、生命周期冲刷和页面上下文，**不直接依赖 `window`、`localStorage` 或 `fetch`**，因此同一份代码可以跑在 H5、微信小程序、支付宝小程序和 React Native。
+
+React / Vue 的组件错误处理是框架层的事，通过子路径引入：
+
+| 项目         | 平台入口           | 框架入口                 |
+| ------------ | ------------------ | ------------------------ |
+| Taro + React | `@fz-firefly/taro` | `@fz-firefly/taro/react` |
+| Taro + Vue 3 | `@fz-firefly/taro` | `@fz-firefly/taro/vue`   |
+
+## 安装
+
+```bash
+pnpm add @fz-firefly/taro
+```
+
+Taro 项目本身已经安装 `@tarojs/taro`，不需要重复安装。
+
+### 可选：注入 runtime
+
+默认使用 `@tarojs/taro`。如果 pnpm 等包管理器解析出多份 Taro，SDK 可能拿到未初始化的一份，表现为 `Taro.request` / 存储 API 不可用。此时可以把项目实际使用的运行时传给 `initFirefly`：
+
+```ts
+import Taro from '@tarojs/taro'
+import { initFirefly } from '@fz-firefly/taro'
+
+initFirefly({ runtime: Taro, dsn, endpoint })
+```
+
+H5 的 `request`、`getStorageSync` 等 API 位于 `@tarojs/taro-h5` 的命名导出上；测试台会把该模块作为 runtime 注入。
+
+## Taro + React
+
+```tsx
+// src/app.tsx
+import type { PropsWithChildren } from 'react'
+import { initFirefly } from '@fz-firefly/taro'
+import { FireflyErrorBoundary } from '@fz-firefly/taro/react'
+
+const firefly = initFirefly({
+  dsn: process.env.TARO_APP_FIREFLY_DSN,
+  endpoint: process.env.TARO_APP_FIREFLY_ENDPOINT,
+  environment:
+    process.env.NODE_ENV === 'production' ? 'production' : 'development',
+  release: process.env.TARO_APP_RELEASE,
+  // dist 不传时自动使用 Taro.getEnv()：h5 / mp-weixin / mp-alipay / rn
+})
+
+export default function App({ children }: PropsWithChildren) {
+  return (
+    <FireflyErrorBoundary client={firefly.client}>
+      {children}
+    </FireflyErrorBoundary>
+  )
+}
+```
+
+Taro React 的页面渲染由 Taro 运行时接管，通常不会自己调用 `createRoot`，所以错误边界是主要的组件错误捕获方式。
+
+## Taro + Vue 3
+
+```ts
+// src/app.ts
+import { createApp } from 'vue'
+import { initFirefly } from '@fz-firefly/taro'
+import { installVue } from '@fz-firefly/taro/vue'
+import App from './App.vue'
+
+const firefly = initFirefly({
+  dsn: process.env.TARO_APP_FIREFLY_DSN,
+  endpoint: process.env.TARO_APP_FIREFLY_ENDPOINT,
+  environment:
+    process.env.NODE_ENV === 'production' ? 'production' : 'development',
+  release: process.env.TARO_APP_RELEASE,
+})
+
+const app = createApp(App)
+installVue({ client: firefly.client, app })
+
+export default app
+```
+
+`installVue` 会接管 `app.config.errorHandler`，并把 client 挂到 `app.config.globalProperties.$firefly`。Taro 不使用 `vue-router`，页面面包屑由 SDK 包装的导航 API 负责（见下方限制）。
+
+## 手动上报
+
+```ts
+firefly.client.captureException(error, {
+  tags: { module: 'order' },
+})
+
+firefly.client.track('pay_click', { channel: 'wechat' })
+```
+
+## 平台识别
+
+`Taro.getEnv()` 的返回值会映射到上报协议的平台字段：
+
+| Taro 环境                   | platform    | 默认 dist                               |
+| --------------------------- | ----------- | --------------------------------------- |
+| `WEB` / `H5`                | `web`       | `h5`                                    |
+| `WEAPP`                     | `mp-weixin` | `mp-weixin`                             |
+| `ALIPAY`                    | `mp-alipay` | `mp-alipay`                             |
+| `RN`                        | `app`       | `rn`                                    |
+| `SWAN` / `TT` / `QQ` / `JD` | `app`       | `mp-swan` / `mp-tt` / `mp-qq` / `mp-jd` |
+
+协议目前只接受 `web` / `mp-weixin` / `mp-alipay` / `app`，所以未覆盖的小程序在 `platform` 上归为 `app`，真实平台保留在 `dist` 里，仍可按版本和 `dist` 区分。
+
+## 行为与限制
+
+- 应用隐藏、回到前台和 H5 `pagehide` 时冲刷队列。
+- 小程序切后台会触发 `onAppHide`，这是最后一次补发机会。
+- 页面上下文会带上 `ctx.page.route` 和 `ctx.page.query`。
+- 页面跳转面包屑通过包装 `Taro.navigateTo`、`redirectTo`、`switchTab`、`reLaunch`、`navigateBack` 记录。Taro 没有 uni-app 那样的统一路由拦截器，这是跨 React / Vue、跨 H5 / 小程序都能工作的折中方案。
+- 已知边界：在 `initFirefly` 之前解构了导航方法，或直接调用 `wx.navigateTo` 等平台原生 API，不会经过包装，需要手动 `client.addBreadcrumb()`。
+- 不传 `dist` 时根据 `Taro.getEnv()` 自动推断；上传 sourcemap 时必须使用相同的 `dist`。