React / Hydrogen components (@customerssay/react)

The @customerssay/react package is not published to npm. Contact CustomersSay support (support@customerssay.ai) to get the package; this README explains how to install and use it. The document is shown as plain Markdown text.

# @customerssay/react

CustomersSay 商品评论的 React 组件与 **Headless Storefront API v1** 客户端,供 Shopify headless 店面使用:
Hydrogen / Oxygen、Next.js(App Router)以及其它自建 React 前端。接口契约见仓库 `docs/headless-api-v1.md`。

- **服务端取数**(`@customerssay/react/server`):在 Hydrogen loader / Next.js 服务端组件里用**私钥**取评论首屏、统计与 JSON-LD,SSR 直出,利于 SEO。
- **组件**:`StarRating`、`ReviewSummary`、`ReviewList`、`ReviewForm`、`ProductJsonLd`,以及开箱即用的完整评论区 `ProductReviews`。
- **客户端**:`createCustomersSayClient`,浏览器用**公钥**,服务端用**私钥**;错误统一为 `CustomersSayApiError`。
  除商品评论外也覆盖问答、店铺评论(含媒体上传)与精选评论,均返回带类型的规范化结果(接入示例见 8.5)。
- **已验证购买**:评论经商家服务端(私钥 + 已登录顾客 ID)提交时,按顾客身份核对订单;`handleReviewSubmission` 一行接好。
- 只依赖 `react >= 18`(peerDependency),无其它运行时依赖;源码 TypeScript / ESM。

---

## 目录

1. [后台准备:密钥与 Origin](#1-后台准备密钥与-origin)
2. [构建、打包与安装](#2-构建打包与安装)
3. [密钥安全与环境变量](#3-密钥安全与环境变量)
4. [Hydrogen 示例](#4-hydrogen-示例)
5. [Next.js(App Router)示例](#5-nextjsapp-router示例)
6. [内容安全策略(CSP)](#6-内容安全策略csp)
7. [已验证购买](#7-已验证购买)
8. [API 参考](#8-api-参考)
9. [样式与定制](#9-样式与定制)
10. [错误处理](#10-错误处理)
11. [开发与测试](#11-开发与测试)

---

## 1. 后台准备:密钥与 Origin

在 CustomersSay 应用后台「Headless」页面:

| 密钥 | 前缀 | 放在哪里 | 用途 |
|---|---|---|---|
| 公钥 | `pk_live_` | 浏览器(可公开) | 读取;在**已登记 Origin** 下写入(提交评论、点赞、上传媒体) |
| 私钥 | `sk_live_` | **只放商家服务端** | 读写;可传可信的访客 IP 与已登录顾客 ID(已验证购买) |

- 为公钥登记店面 Origin(精确匹配 `scheme://host[:port]`,生产只接受 https),例如 `https://www.example.com`;
  本地开发登记 `http://localhost:3000`(Hydrogen / Next.js 默认端口)。
- 私钥明文只在创建时显示一次,请立即存入服务端环境变量。

## 2. 构建、打包与安装

本包不发布到公共 npm,以源码交付。`package.json` 的入口指向 `dist/`,使用前需先构建一次。

### 2.1 构建与打包(在本仓库内)

```bash
cd packages/customerssay-react
# 构建工具只在本目录临时安装,不写入 package.json、不影响仓库根依赖
npm install --no-save --no-package-lock typescript@5 @types/react@18
npm run build        # tsc -p tsconfig.build.json → dist/(ESM + .d.ts,保留 "use client" 指令)
npm pack             # 生成 customerssay-react-0.1.0.tgz(包含 dist、src、styles.css、README.md)
```

### 2.2 在店面项目中安装

任选其一:

```bash
# a) 安装 tarball(推荐,与发布到 npm 的效果一致)
npm install ./vendor/customerssay-react-0.1.0.tgz
```

```jsonc
// b) package.json 中用 file: 指向 tarball 或已构建的目录
{
  "dependencies": {
    "@customerssay/react": "file:./vendor/customerssay-react-0.1.0.tgz"
    // 或 "file:../reviews-app/packages/customerssay-react"(目录需先 npm run build)
  }
}
```

> 使用目录 `file:`(软链接)时如出现 “Invalid hook call”,说明加载了两份 React,请改用 tarball 安装。

### 2.3 发布到 npm / 私有 registry(可选)

1. 把 `package.json` 的 `name` 改成你拥有的作用域(如 `@your-org/customerssay-react`),按需修改 `license`;
2. `npm version patch`(或 minor / major);
3. 按 2.1 构建后执行 `npm publish --access restricted`(私有)或 `--access public`;私有 registry 加 `--registry <url>`。

## 3. 密钥安全与环境变量

- **私钥只能出现在服务端代码与服务端环境变量中**:
  - Hydrogen / Oxygen:`PRIVATE_CUSTOMERSSAY_SECRET_KEY`(Oxygen 后台环境变量 / 本地 `.env`),只在 loader / action 里通过 `context.env` 读取;
  - Next.js:`CUSTOMERSSAY_SECRET_KEY`,**不要**加 `NEXT_PUBLIC_` 前缀;读取私钥的模块建议 `import "server-only"`。
- 服务端入口 `@customerssay/react/server` 只能在服务端导入。
- 防呆:浏览器环境里创建 / 使用私钥客户端会直接抛 `CustomersSayConfigError("secret_key_in_browser")`;
  `CustomersSayProvider` 只接受公钥客户端;服务端也会拒绝带 `Origin` 头的私钥请求(403)。
- 公钥可以公开(会出现在页面源码里),访问控制靠后台登记的 Origin 与限流。

建议的环境变量:

| 变量 | 示例 | 位置 |
|---|---|---|
| `CUSTOMERSSAY_API_BASE` | `https://app-next.customerssay.ai/api/storefront/v1` | 服务端读取;值本身可公开,由 loader / 服务端组件作为 prop 传给浏览器端组件 |
| `PUBLIC_CUSTOMERSSAY_KEY`(Hydrogen)/ `NEXT_PUBLIC_CUSTOMERSSAY_KEY`(Next.js) | `pk_live_...` | 可公开 |
| `PRIVATE_CUSTOMERSSAY_SECRET_KEY`(Hydrogen)/ `CUSTOMERSSAY_SECRET_KEY`(Next.js) | `sk_live_...` | **仅服务端** |

浏览器端组件(`CustomersSayProvider`)需要的 `apiBase` 与公钥,统一由服务端(Hydrogen loader、Next.js 服务端组件)读环境变量后
作为 prop 传下去(见 4.1、5.1),不需要额外配置 `NEXT_PUBLIC_CUSTOMERSSAY_API_BASE`。

## 4. Hydrogen 示例

以下按 Hydrogen(React Router 7)写法;旧版 Remix 版 Hydrogen 只需把类型从 `@shopify/remix-oxygen` 引入,逻辑相同。

### 4.1 商品页:loader 取数 + SSR 组件

```tsx
// app/routes/products.$handle.tsx
import {useLoaderData} from 'react-router';
import type {Route} from './+types/products.$handle';
import {getProductReviewsForSsr, getVisitorIp} from '@customerssay/react/server';
import {
  CustomersSayProvider,
  ProductJsonLd,
  ProductReviews,
  StarRating,
  createProxyReviewSubmitter,
} from '@customerssay/react';
import '@customerssay/react/styles.css'; // 可选的最小样式

export async function loader({params, context, request}: Route.LoaderArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {variables: {handle: params.handle}});
  if (!product) throw new Response(null, {status: 404});

  // 私钥只在服务端使用;访客 IP 只读 Oxygen 提供的 oxygen-buyer-ip(必须显式指定平台,见 4.2)
  const customersSay = await getProductReviewsForSsr({
    apiBase: context.env.CUSTOMERSSAY_API_BASE,
    secretKey: context.env.PRIVATE_CUSTOMERSSAY_SECRET_KEY,
    productId: product.id, // gid://shopify/Product/123 或纯数字均可
    clientIp: getVisitorIp(request, {platform: 'oxygen'}),
    // 访客浏览器的 User-Agent:与 clientIp 一起构成访客指纹,两者都传,首屏的 userReaction(访客点过的有帮助)才对得上
    userAgent: request.headers.get('user-agent'),
  });
  // 评论服务异常不会让商品页 500:对应字段为 null,错误摘要在 errors 里
  if (customersSay.errors.length) console.warn('[CustomersSay]', customersSay.errors);

  return {
    product,
    customersSay,
    // 公钥本身可公开,经 loader 传给浏览器端组件
    customersSayConfig: {
      apiBase: context.env.CUSTOMERSSAY_API_BASE,
      publicKey: context.env.PUBLIC_CUSTOMERSSAY_KEY,
    },
  };
}

// 评论提交走本站 /api/reviews(见 4.2),由服务端带上已登录顾客身份 → 已验证购买
const submitReview = createProxyReviewSubmitter('/api/reviews');

export default function Product() {
  const {product, customersSay, customersSayConfig} = useLoaderData<typeof loader>();
  const summary = customersSay.reviews?.summary;

  return (
    <div className="product">
      <h1>{product.title}</h1>
      {summary ? <StarRating rating={summary.averageRating} count={summary.totalReviews} /> : null}

      {/* 结构化数据:合并店面已知字段,页面只保留这一个 Product 节点;name 必填(评论服务失败时的回退节点只含这些字段) */}
      <ProductJsonLd
        data={customersSay.jsonLd}
        product={{
          name: product.title,
          url: `https://www.example.com/products/${product.handle}`,
          image: product.featuredImage?.url ?? null,
          offers: {
            '@type': 'Offer',
            price: product.selectedOrFirstAvailableVariant?.price.amount ?? null,
            priceCurrency: product.selectedOrFirstAvailableVariant?.price.currencyCode ?? null,
            availability: 'https://schema.org/InStock',
          },
        }}
      />

      <CustomersSayProvider apiBase={customersSayConfig.apiBase} publicKey={customersSayConfig.publicKey}>
        {/* key:同一路由切换商品时重建整个评论区(见下方说明) */}
        <ProductReviews
          key={product.id}
          productId={product.id}
          initialData={customersSay.reviews}
          formProps={{submit: submitReview, allowMedia: true}}
        />
      </CustomersSayProvider>
    </div>
  );
}
```

> `ProductReviews` 首屏完全使用 `initialData` 渲染(SSR 与水合一致);“加载更多 / 点赞 / 上传媒体”在浏览器用公钥调用 v1。
>
> **为什么要 `key={product.id}`**:从一个商品页点到另一个商品页时 Hydrogen 不会卸载路由组件,只换 loader 数据,
> React 会复用 `ProductReviews` 实例。加上 `key` 后评论区随商品整体重建(列表、排序 / 筛选、展开的表单、未提交的草稿都回到初始状态)。
> 即使不加,`useProductReviews` 也会检测商品(`productId` / `productHandle`)变化:有新的 `initialData` 直接使用、不在浏览器重取,
> 不会先闪现上一个商品的评论,表单草稿也会清空;同一商品的 loader 重新验证(加购、切换规格)带来新的 `initialData` 时,
> 若访客仍停在默认排序的第一页(且没有进行中的“加载更多”),或已切回默认排序但列表还没换回来(正在重取 / 重取失败)则采用新数据;
> 当前是其它排序 / 筛选、默认排序下加载了更多页或“加载更多”仍在进行时则保留访客当前的列表。
> 只要展示、不需要交互时,可以只用 `ReviewSummary` + `ReviewList`(无需 Provider)。
> 评论服务失败(`customersSay.jsonLd` 为 `null`)时,`ProductJsonLd` 仍用 `product` 输出 Product 节点(不带评分),
> 页面不会因此丢失 Product;`@context` 始终为 `https://schema.org`。这个回退节点**只含 `product` 里给的字段**,
> 所以 `product` 至少要带 `name`(上例的 `product.title`);`product` 没有 `name` 时不输出任何节点——
> 没有 `name` 的 Product 会被 Search Console 判为无效,比不输出更糟。

### 4.2 评论提交路由(已验证购买)

```ts
// app/routes/api.reviews.tsx
import type {Route} from './+types/api.reviews';
import {getVisitorIp, handleReviewSubmission} from '@customerssay/react/server';

export async function action({request, context}: Route.ActionArgs) {
  // 顾客身份只能来自服务端会话(Customer Account API),绝不能取自请求体
  let customerId: string | null = null;
  if (await context.customerAccount.isLoggedIn()) {
    const {data} = await context.customerAccount.query(`#graphql
      query CustomersSayCurrentCustomer { customer { id } }
    `);
    customerId = data?.customer?.id ?? null; // gid://shopify/Customer/123
  }

  return handleReviewSubmission({
    request,
    apiBase: context.env.CUSTOMERSSAY_API_BASE,
    secretKey: context.env.PRIVATE_CUSTOMERSSAY_SECRET_KEY,
    customerId, // 未登录为 null:评论照常提交,只是不自动判定已验证购买
    // 访客 IP 必须显式按平台读取;不传则不发送访客 IP(不会自动从请求头猜测)
    clientIp: getVisitorIp(request, {platform: 'oxygen'}),
    userAgent: request.headers.get('user-agent'), // 访客指纹的另一半,同样需要显式传入
  });
}
```

`createProxyReviewSubmitter` 的地址必须与店面**同源**(如相对路径 `/api/reviews`):fetch 默认只在同源请求中携带 Cookie,跨域的提交路由拿不到顾客会话,已验证购买会静默失效。

`handleReviewSubmission` 只接受 `POST` + `Content-Type: application/json`(跨站请求必须先过 CORS 预检,天然防 CSRF),
请求体中的 `customerId` / `clientIp` 等字段会被忽略。不用 `handleReviewSubmission`、自己写路由时同样只解析 JSON:
`parseSubmitReviewInput` 不接受 `FormData`——普通 `<form>` 可以被任意第三方站点无预检地提交并带上顾客 Cookie(CSRF)。
如确需接收表单提交,请先自行校验 `Origin` / CSRF token,再把字段转成普通对象传入。

**访客 IP(`getVisitorIp`)必须显式指定部署平台**,只读取该平台会覆盖、访客无法伪造的请求头。
第二个参数与其中的 `platform` 在类型上都是**必填**的,旧写法 `getVisitorIp(request)` 会在编译期报错:

| `platform` | 读取的请求头 | 说明 |
|---|---|---|
| `'oxygen'` | `oxygen-buyer-ip` | Hydrogen 部署在 Shopify Oxygen |
| `'cloudflare'` | `cf-connecting-ip` | Cloudflare Workers / Pages;若是“Cloudflare 代理 → 你的源站”,源站须只接受 Cloudflare 的回源流量 |
| `'vercel'` | `x-real-ip`,其次 `x-vercel-forwarded-for` | Vercel(含 Next.js) |
| `{trustedXffHops: N}` | `X-Forwarded-For` 从右往左第 N 项 | 自建反向代理 / 负载均衡:你控制的 N 层代理各自追加一项(只有一层时 N = 1);项数不足返回 `null` |
| `null` | 不读取任何请求头 | 显式表示“不信任任何头”,始终返回 `null`(如本地开发、平台不在表中且你另有可信来源) |

> 运行时漏传 `platform`(例如纯 JS 调用方仍写 `getVisitorIp(request)`)同样返回 `null`,并在非生产环境 `console.warn` 一次。
> 返回 `null` 意味着不发送访客 IP:v1 会把你服务器的出口 IP 当作访客,**你店铺的所有访客共用同一个按 IP 的限流桶与点赞去重键**。

> 不要用错平台:托管层只会覆盖**自己的**请求头,别的平台的头(例如在 Oxygen 上的 `cf-connecting-ip`、`x-forwarded-for` 最左项)
> 访客可以随意伪造,用它们作为 `X-CustomersSay-Client-IP` 会让按 IP 的写限流与点赞去重被绕过。
> 本包早期版本会按 `oxygen-buyer-ip → cf-connecting-ip → x-real-ip → x-forwarded-for` 自动猜测,`handleReviewSubmission`
> 也会默认这样取值;现已移除,升级时请在 `getVisitorIp` 调用处补上 `platform`(TypeScript 项目会在编译期指出漏传的调用),
> 并给 `handleReviewSubmission` 显式传 `clientIp`。

**访客 User-Agent(`userAgent`)与 `userReaction`**:v1 按 `md5(访客 IP:浏览器 User-Agent)` 识别访客(点赞去重、列表里每条评论 /
问题 / 回答的 `userReaction`)。服务端代访客请求时,请求自带的 User-Agent 是你服务器的,所以要用 `userAgent` 转发访客浏览器的原值
(`request.headers.get('user-agent')`,发送为请求头 `X-CustomersSay-Client-UA`,仅私钥请求生效)。
**需要同时传 `clientIp` 与 `userAgent`**:只传 `clientIp` 时 SSR 首屏的 `userReaction` 恒为 `null`,访客刷新后看不到自己点过的“有帮助”,
再点同一按钮计数也不会变化。User-Agent 本来就由访客浏览器决定,原样转发即可(不同于 IP,不需要可信来源);
含换行 / 控制字符或超过 1024 字符的值不会发送。

### 4.3 CSP(Hydrogen)

```ts
// app/entry.server.tsx
const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  shop: {checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN, storeDomain: context.env.PUBLIC_STORE_DOMAIN},
  // connectSrc 是 Hydrogen 的默认指令之一:传入的值追加在默认值之后
  connectSrc: ['https://app-next.customerssay.ai'],
  // imgSrc / mediaSrc 不在默认指令里:传入的值就是最终的 img-src / media-src(不再回落到 default-src),
  // 必须自己带上 'self'、data: 与店面商品图片 / 视频所在的 cdn.shopify.com,否则整站商品图片会被拦截
  imgSrc: ["'self'", 'data:', 'https://cdn.shopify.com', 'https://<评论媒体域名>'],
  mediaSrc: ["'self'", 'https://cdn.shopify.com', 'https://<评论媒体域名>'],
});
```

> **Hydrogen 只对部分默认指令做追加合并**:`createContentSecurityPolicy` 只把你传入的值追加到它自带默认值的那几个指令上
> (`defaultSrc`、`styleSrc`、`connectSrc` 等,`default-src` 里含 `'self'` 与 `https://cdn.shopify.com`);
> 其它指令(`imgSrc`、`mediaSrc`、`fontSrc` …)是**整体覆盖**——一旦传入,浏览器就只按你给的列表放行,
> 不再回落到 `default-src`。所以上例的 `imgSrc` / `mediaSrc` 要写全店面自己需要的来源。
> 合并规则以所用 Hydrogen 版本的 `createContentSecurityPolicy` 文档为准,域名说明见第 6 节。

## 5. Next.js(App Router)示例

### 5.1 服务端组件取数 + SSR

```tsx
// app/products/[handle]/page.tsx(服务端组件)
import {headers} from 'next/headers';
import {notFound} from 'next/navigation';
import {getProductReviewsForSsr, getVisitorIp} from '@customerssay/react/server';
import {ProductJsonLd, ReviewSummary} from '@customerssay/react';
import {getProduct} from '@/lib/shopify'; // 你自己的 Storefront API 商品查询
import {ProductReviewsClient} from './product-reviews-client';

export default async function ProductPage({params}: {params: Promise<{handle: string}>}) {
  const {handle} = await params;
  const product = await getProduct(handle); // {title, ...};JSON-LD 的 name 取自这里
  if (!product) notFound();
  const requestHeaders = await headers();
  const customersSay = await getProductReviewsForSsr({
    apiBase: process.env.CUSTOMERSSAY_API_BASE!,
    secretKey: process.env.CUSTOMERSSAY_SECRET_KEY!, // 仅服务端变量,不加 NEXT_PUBLIC_
    productHandle: handle,
    clientIp: getVisitorIp(requestHeaders, {platform: 'vercel'}), // 按你的部署平台选择,见 5.2
    userAgent: requestHeaders.get('user-agent'), // 与 clientIp 一起构成访客指纹(userReaction 需要两者)
    // 请求带访客 IP 与 User-Agent(影响 userReaction 与限流),不要跨访客缓存
    fetch: (url, init) => fetch(url, {...init, cache: 'no-store'}),
  });

  return (
    <main>
      {/* 纯展示组件可直接在服务端组件中使用 */}
      {customersSay.reviews ? <ReviewSummary summary={customersSay.reviews.summary} showDistribution={false} /> : null}
      {/* name 必填:评论服务失败时回退节点只含 product 里的字段,没有 name 则不输出(见 4.1 的说明) */}
      <ProductJsonLd data={customersSay.jsonLd} product={{name: product.title, url: `https://www.example.com/products/${handle}`}} />
      {/* key:切换商品时重建评论区(同 4.1 的说明) */}
      <ProductReviewsClient
        key={handle}
        // 与 Hydrogen 经 loader 传递一致:服务端组件读环境变量(第 3 节的表格),作为 prop 传给客户端组件。
        // 公钥本身可公开;apiBase 不需要再配一个 NEXT_PUBLIC_ 变量
        config={{apiBase: process.env.CUSTOMERSSAY_API_BASE!, publicKey: process.env.NEXT_PUBLIC_CUSTOMERSSAY_KEY!}}
        productHandle={handle}
        productId={customersSay.reviews?.product.id ?? undefined}
        initialData={customersSay.reviews}
      />
    </main>
  );
}
```

```tsx
// app/products/[handle]/product-reviews-client.tsx
'use client';
import {CustomersSayProvider, ProductReviews, createProxyReviewSubmitter, type ReviewListResult} from '@customerssay/react';
import '@customerssay/react/styles.css';

const submit = createProxyReviewSubmitter('/api/reviews');

export function ProductReviewsClient({config, ...props}: {
  config: {apiBase: string; publicKey: string};
  productHandle: string;
  productId?: string;
  initialData: ReviewListResult | null;
}) {
  return (
    // 不要在客户端组件里读 process.env.CUSTOMERSSAY_API_BASE:Next.js 只把 NEXT_PUBLIC_ 前缀的变量内联进浏览器包,
    // 读到 undefined 时 Provider 在渲染期抛 CustomersSayConfigError,整页报错
    <CustomersSayProvider apiBase={config.apiBase} publicKey={config.publicKey}>
      {/* 上传媒体需要 productId;只有 handle 时自动隐藏上传入口 */}
      <ProductReviews {...props} formProps={{submit, allowMedia: true}} />
    </CustomersSayProvider>
  );
}
```

### 5.2 评论提交 Route Handler(已验证购买)

```ts
// app/api/reviews/route.ts
import 'server-only';
import {getVisitorIp, handleReviewSubmission} from '@customerssay/react/server';
import {getShopifyCustomerId} from '@/lib/customer-account'; // 你自己的 Customer Account API 会话逻辑

export async function POST(request: Request) {
  return handleReviewSubmission({
    request,
    apiBase: process.env.CUSTOMERSSAY_API_BASE!,
    secretKey: process.env.CUSTOMERSSAY_SECRET_KEY!,
    customerId: await getShopifyCustomerId(request), // 未登录返回 null
    // 部署在 Vercel;Cloudflare 用 'cloudflare',自建 Nginx / 负载均衡用 {trustedXffHops: 1}
    clientIp: getVisitorIp(request, {platform: 'vercel'}),
    userAgent: request.headers.get('user-agent'),
  });
}
```

`getVisitorIp` 不再自动猜测请求头,**必须按部署平台显式指定 `platform`**(类型上必填;取值与各平台读取的请求头见 4.2 节的表格),
显式传 `{platform: null}` 表示不信任任何头、返回 `null`;运行时漏传同样返回 `null` 并在非生产环境告警一次。
`handleReviewSubmission` 不传 `clientIp` 时也不会自动取值、不发送访客 IP。
如果你的平台不在表中,请自行从可信来源取得访客 IP 后传给 `clientIp`。

### 5.3 CSP(Next.js)

Next.js 自身对 CSP 有要求:App Router 的水合引导脚本是内联脚本,框架的样式注入也需要放行,
**只写 `default-src 'self'` 会挡掉 Next.js 自己的水合脚本**。请以 Next.js 官方指南为准
([Content Security Policy](https://nextjs.org/docs/app/guides/content-security-policy)),再加上 CustomersSay 需要的域名(第 6 节)。
下例按官方指南的“不使用 nonce”写法:

```js
// next.config.js
const isDev = process.env.NODE_ENV === 'development';
const csp = [
  "default-src 'self'",
  // Next.js 的内联引导脚本需要 'unsafe-inline';开发模式另需 'unsafe-eval'(改用 nonce 的写法见官方指南)
  `script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ''}`,
  // Next.js 自身需要;CustomersSay 组件不输出 style 属性,改用 nonce 写法时组件不需要 'unsafe-inline'
  "style-src 'self' 'unsafe-inline'",
  "connect-src 'self' https://app-next.customerssay.ai",
  "img-src 'self' data: https://cdn.shopify.com https://<评论媒体域名>",
  "media-src 'self' https://cdn.shopify.com https://<评论媒体域名>",
  "font-src 'self'",
  "object-src 'none'",
  "base-uri 'self'",
  "form-action 'self'",
  "frame-ancestors 'none'",
].join('; ');
module.exports = {
  async headers() {
    return [{source: '/(.*)', headers: [{key: 'Content-Security-Policy', value: csp}]}];
  },
};
```

使用官方指南的 nonce 写法(在 middleware 里生成 `script-src 'self' 'nonce-…' 'strict-dynamic'`、`style-src 'self' 'nonce-…'`)时,
CustomersSay 组件同样可用:组件的 SSR 输出不含 style 属性与内联脚本,`ProductJsonLd` 也接受 `nonce`。

## 6. 内容安全策略(CSP)

| 指令 | 需放行 | 原因 |
|---|---|---|
| `connect-src` | 应用域名(生产 `https://app-next.customerssay.ai`) | 浏览器用公钥加载更多、点赞、提交、上传媒体 |
| `img-src` | 评论媒体域名 | 评论图片 / 视频封面 |
| `media-src` | 评论媒体域名 | 评论视频 |
| `script-src` / `style-src` | **组件本身不需要额外放行**(不需要 `'unsafe-inline'`) | 组件随你的 JS 包打包;SSR 输出**不含 style 属性**、不含内联脚本(见下)。框架自身的要求另计(Next.js 见 5.3,Hydrogen 由 `createContentSecurityPolicy` 处理)。改用 `embed.js` / `embed.css` 时才需放行应用域名(含 `/api/widget-assets/` 资源) |

- 评论媒体域名以接口返回的 `media[].url` 为准(应用配置的 COS CDN 域名,例如 `https://media.customerssay.ai`)。
- 服务端取数(loader / 服务端组件)发生在你的服务器上,不受浏览器 CSP 约束。
- **为什么组件不需要 `style-src 'unsafe-inline'`**:SSR 输出里的 `style="…"` 属性受 `style-src` 约束,而且 nonce 对 style 属性无效,
  被拦截后水合也不会补上。因此组件不输出 style 属性:星级与分布条用 SVG 绘制,尺寸、部分填充的裁切、兜底颜色都是 SVG 表现属性
  (`width`、`overflow`、`fill`,不受 `style-src` 约束),排列与 CSS 变量换肤在 `styles.css` 的类里。
  只有你**显式传给 `StarRating` 的 `style`**、或在 `render*` 回调里自己输出的 style 属性才需要 `'unsafe-inline'`,严格 CSP 下请改用 `className`。
- `styles.css` 由你的构建工具和店面其它 CSS 一起打包成样式表(`<link>`),与店面自己的 CSS 走同一条 `style-src` 规则,无需单独放行。
- `ProductJsonLd` 输出的是 `application/ld+json` 数据块,浏览器不会执行,严格 CSP 下如需也可传 `nonce`。

## 7. 已验证购买

| 提交方式 | 是否自动判定“已验证购买” |
|---|---|
| 浏览器公钥直接提交(`ReviewForm` 默认) | 否(浏览器无法证明顾客身份),可由商家在后台手动标记 |
| 商家服务端私钥提交,不带顾客 ID | 否 |
| 商家服务端私钥提交 + `X-CustomersSay-Customer-Id`(`handleReviewSubmission` 的 `customerId`) | 是:只认该顾客自己的订单 |

因此要获得自动“已验证购买”,请使用 `ReviewForm` 的 `submit={createProxyReviewSubmitter('/api/reviews')}`,
并在该路由里用 `handleReviewSubmission` + 服务端会话中的顾客 ID(第 4.2 / 5.2 节)。公开接口不会回传任何购买验证结果。

## 8. API 参考

### 8.1 客户端 `createCustomersSayClient(options)`

| 选项 | 说明 |
|---|---|
| `apiBase` | v1 基础地址(必填) |
| `publicKey` | 公钥(浏览器) |
| `secretKey` | 私钥(服务端;浏览器环境直接抛错) |
| `shop` | 可选,`xxx.myshopify.com`,服务端校验与密钥店铺一致 |
| `fetch` | 自定义 fetch(测试或框架缓存控制) |
| `clientIp` / `customerId` / `userAgent` | 仅私钥:默认的可信访客 IP / 顾客 ID / 访客浏览器 User-Agent(一般按请求传) |

鉴权方式(严格按契约):公钥 GET 用 `?key=`(不加自定义头、不触发预检),公钥 POST 用 `X-CustomersSay-Key` 头;
私钥一律 `Authorization: Bearer`,并可附带 `X-CustomersSay-Client-IP` / `X-CustomersSay-Client-UA` / `X-CustomersSay-Customer-Id`。

| 方法 | 接口 | 返回 |
|---|---|---|
| `getReviews({productId \| productHandle, page, limit, sort, ratingFilter, withMedia})` | `GET /reviews` | `ReviewListResult` |
| `getRatingSummary({productId \| productHandle})` | `GET /rating-summary` | `RatingSummary` |
| `getQuestions({productId \| productHandle, page, limit, sort})` | `GET /questions` | `QuestionListResult` |
| `getJsonLd({productId \| productHandle})` | `GET /json-ld` | `ProductJsonLdData` |
| `submitReview(input)` | `POST /reviews`(multipart) | `SubmitReviewResult` |
| `reactToReview({reviewId, reaction})` | `POST /review-reactions` | `ReactionResult` |
| `submitQuestion({productId \| productHandle, content, email, nickname})` | `POST /questions` | `SubmitQuestionResult` |
| `reactToQuestion({questionId \| answerId, reaction})` | `POST /question-reactions` | `ReactionResult` |
| `uploadMedia({file, type, productId, tempId?})` | `POST /media-upload` | `UploadMediaResult` |
| `getStoreReviews({page, limit, sort, ratingFilter})` | `GET /store-reviews`(`sort` 发送为 `sortBy`:`recent` / `oldest` / `highest` / `lowest`;`ratingFilter` 发送为 `rating`) | `StoreReviewListResult` |
| `submitStoreReview({rating, content, nickname, email?, title?, tempIds?})` | `POST /store-reviews`(JSON;`nickname` / `email` 发送为 `user_name` / `user_email`) | `SubmitStoreReviewResult` |
| `uploadStoreMedia({file, type, fileName?})` | `POST /store-media-upload`(multipart,不需要 `productId`) | `UploadStoreMediaResult`(`tempId` 放进 `submitStoreReview` 的 `tempIds`) |
| `reactToStoreReview({reviewId, reaction})` | `POST /store-review-reactions` | `ReactionResult` |
| `getFeaturedReviews({mode?, limit?})` | `GET /featured`(`mode`:`featured` / `five-star` / `with-pictures` / `all`) | `FeaturedReviewsResult`(文本已解码为纯文本,见 8.4) |
| `getWidgetSettings` | `/widget-settings` | 原始响应 |
| `request({method, path, query, json, formData})` | 任意 v1 路径 | 原始 JSON |

所有方法的第二个参数为 `{ signal?, clientIp?, customerId?, userAgent? }`(后三者仅私钥;公钥客户端传入直接抛 `server_only_option`)。
`reaction` 取 `'like' | 'dislike' | 'none'`(none = 取消)。星级筛选统一用 `ratingFilter`:`getReviews` 发送 `rating_filter`(不会发送 `rating`),
`getStoreReviews` 发送店铺评论接口自己的筛选参数 `rating`。问答与店铺评论的接入示例见 8.5。

### 8.2 服务端 `@customerssay/react/server`

| 函数 | 说明 |
|---|---|
| `getProductReviewsForSsr({apiBase, secretKey, productId \| productHandle, clientIp?, userAgent?, customerId?, page?, limit?, sort?, ratingFilter?, includeJsonLd = true, includeQuestions = false, throwOnError = false})` | 并行取 `{ reviews, jsonLd, questions, errors }`,可 JSON 序列化;默认失败不抛错。要得到 `userReaction` 须同时传 `clientIp` 与 `userAgent`(见 4.2) |
| `createCustomersSayServerClient({apiBase, secretKey, clientIp?, userAgent?, customerId?, ...})` | 私钥客户端(校验私钥存在且前缀正确) |
| `getVisitorIp(request \| headers, {platform})` | 按部署平台(`'oxygen'` / `'cloudflare'` / `'vercel'` / `{trustedXffHops: N}`)只读可信请求头取访客 IP;`platform` 必填,传 `null` 表示不信任任何头(返回 `null`);运行时漏传返回 `null` 并在非生产环境告警一次 |
| `handleReviewSubmission({request, apiBase, secretKey, customerId, clientIp?, userAgent?})` | 一站式评论提交路由(返回 `Response`);`clientIp` / `userAgent` 都需显式传入,不从请求头自动取值 |
| `parseSubmitReviewInput(json)` | 校验浏览器提交的评论(只接受已解析的 JSON 对象,不接受 `FormData`),只挑选已知字段 |
| `customersSayErrorResponse(error)` | 把异常转成 JSON 错误 `Response`(不泄露内部细节) |

### 8.3 组件

| 组件 | 类型 | 主要 props |
|---|---|---|
| `CustomersSayProvider` | 客户端 | `apiBase` + `publicKey`(或 `client`)、`shop`、`labels`、`onError` |
| `StarRating` | 纯展示 | `rating`、`max`、`size`(星星 SVG 的宽高,数字按 px,默认 `1em`)、`showValue`、`count`、`label`、`renderStar` |
| `ReviewSummary` | 纯展示 | `summary`、`showDistribution`、`showRecommendation`、`renderDistributionRow`、`children`(动作插槽) |
| `ReviewList` / `ReviewCard` | 纯展示 | `reviews`、`dateFormat`、`showReactions`、`renderReview`、`renderActions`、`renderMedia`、`renderEmpty`、`footer` |
| `ReviewReactions` | 客户端 | `review`、`showDislike`、`onChange` |
| `ReviewForm` | 客户端 | `productId` / `productHandle`、`submit`、`fields`、`allowMedia`、`maxFiles`、`requireTitle/Nickname/Content/Email`(`requireEmail` 默认 `fields.email !== false`)、`defaultValues`、`renderSuccess`、`onSuccess`、`onError` |
| `ProductReviews` | 客户端 | `productId` / `productHandle`、`initialData`、`pageSize`、`showForm`、`showReactions`、`formProps`、`listProps`、`toolbar` |
| `ProductJsonLd` | 纯展示 | `data`、`product`(合并的店面字段,至少带 `name`;`data` 为空时回退节点只含这些字段,无 `name` 不输出)、`nonce` |

Hooks:`useReviewForm`(自定义表单 UI)、`useProductReviews`(自定义列表 / 排序 / 筛选 UI)、`useCustomersSay`。
`useProductReviews` 会随商品变化自动重置;单独使用 `ReviewForm` / `useReviewForm` 时请给表单(或其所在组件)加 `key={商品 ID}`,
否则同一路由切换商品时草稿会被带到新商品。

“纯展示”组件不含 hooks 与事件处理,可作为 Next.js 服务端组件使用;“客户端”组件所在文件带 `"use client"`。

### 8.4 数据规范化

`normalizeReviewList`、`normalizeRatingSummary`、`normalizeQuestionList`、`normalizeJsonLd` 等把 v1 原始响应
(结构见 `fixtures/headless-v1/*.json`)转为干净的 TS 类型;字段缺失时回落到安全默认值,不抛错。客户端方法已自动调用。
规范化结果里的文本一律是**纯文本**,直接写进 JSX(`{review.content}`)即可,React 会自动转义;不要用 `dangerouslySetInnerHTML`。

> **`/featured` 的文本是 HTML 实体转义过的**:v1 `/featured` 沿用主题店接口的写法,服务端把 `content`、`title`、昵称、商品名、
> 商家回复转成了 HTML 实体(`It&#x27;s`、`&lt;3`、`&#x2F;` …;`&` 本身不转义),并删除了文本里的 `javascript:` 与 `on…=` 子串。
> 其它接口(`/reviews`、`/questions` …)返回的是原始纯文本。`getFeaturedReviews` / `normalizeFeaturedReviews` 已把这些实体
> **解码回纯文本**,页面不会显示 `&#x27;` 之类的字面量;自己用 `request()` 取 `/featured` 原始响应时,可用导出的
> `decodeHtmlEntities` 解码(单遍解码,`&amp;lt;` 只还原一层)。被服务端删除的子串无法还原;原文里本来就写着实体字样
> (如 `&lt;`)的评论会被显示为对应字符。

### 8.5 问答与店铺评论:最小接入示例

本包没有现成的问答 / 店铺评论组件,用客户端方法 + 自己的 UI 即可。以下两个客户端组件都放在 `CustomersSayProvider`(公钥)之下;
`StarRating` 等纯展示组件可以直接复用。错误一律是 `CustomersSayApiError`(第 10 节),示例只做了最简单的处理。

**商品问答**:首屏用 `getProductReviewsForSsr({..., includeQuestions: true})` 在服务端取(结果在 `questions`,取数参数同 4.1 / 5.1),
浏览器里翻页、提问、点赞:

```tsx
'use client';
import {useState, type FormEvent} from 'react';
import {useCustomersSay, type Question, type QuestionListResult} from '@customerssay/react';

export function ProductQuestions({productId, initialData}: {productId: string; initialData: QuestionListResult | null}) {
  const {client} = useCustomersSay();
  const [data, setData] = useState(initialData);
  const [notice, setNotice] = useState<string | null>(null);

  // 加载下一页(追加到当前列表)
  async function loadMore() {
    if (!data?.pagination.hasNextPage) return;
    const next = await client.getQuestions({productId, page: data.pagination.page + 1});
    setData({questions: [...data.questions, ...next.questions], pagination: next.pagination});
  }

  // 点“有帮助”;再点一次取消(reaction: 'none'),计数以接口返回为准
  async function toggleLike(question: Question) {
    const reaction = question.userReaction === 'like' ? 'none' : 'like';
    const counts = await client.reactToQuestion({questionId: question.id, reaction});
    setData((current) => current && {
      ...current,
      questions: current.questions.map((item) => item.id === question.id
        ? {...item, likesCount: counts.likesCount, dislikesCount: counts.dislikesCount, userReaction: reaction === 'none' ? null : reaction}
        : item),
    });
  }

  // 提问:邮箱必填;新问题需商家审核后才会出现在列表里,所以只提示、不插入列表
  async function ask(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const formElement = event.currentTarget; // await 之后 React 会清空 event.currentTarget,先保存
    const form = new FormData(formElement);
    try {
      await client.submitQuestion({
        productId,
        content: String(form.get('content') ?? ''),
        email: String(form.get('email') ?? ''),
        nickname: String(form.get('nickname') ?? '') || undefined,
      });
      formElement.reset();
      setNotice('感谢提问,审核通过后展示');
    } catch (error) {
      setNotice(error instanceof Error ? error.message : '提交失败,请稍后再试');
    }
  }

  return (
    <section>
      {data?.questions.map((question) => (
        <article key={question.id}>
          <p><strong>{question.authorName}</strong>:{question.content}</p>
          {question.answer ? <p>商家回复:{question.answer.content}</p> : null}
          <button type="button" aria-pressed={question.userReaction === 'like'} onClick={() => void toggleLike(question)}>
            有帮助({question.likesCount})
          </button>
        </article>
      ))}
      {data?.pagination.hasNextPage ? <button type="button" onClick={() => void loadMore()}>更多问题</button> : null}
      <form onSubmit={ask}>
        <textarea name="content" required />
        <input name="nickname" placeholder="昵称(可选)" />
        <input name="email" type="email" required />
        <button type="submit">提问</button>
        {notice ? <p role="status">{notice}</p> : null}
      </form>
    </section>
  );
}
```

回答的点赞用 `client.reactToQuestion({answerId: question.answer.id, reaction})`。

**店铺评论**(对整个店铺的评价,不属于某个商品):列表、统计与画廊来自 `getStoreReviews`;提交前每个文件单独 `uploadStoreMedia`,
各自得到一个 `tempId`(不要让多个文件共用 `tempId`,后上传的会覆盖先上传的),再一起放进 `submitStoreReview` 的 `tempIds`:

```tsx
'use client';
import {useEffect, useState, type FormEvent} from 'react';
import {StarRating, useCustomersSay, type StoreReviewListResult} from '@customerssay/react';

export function StoreReviews({initialData = null}: {initialData?: StoreReviewListResult | null}) {
  const {client} = useCustomersSay();
  const [data, setData] = useState(initialData);
  const [notice, setNotice] = useState<string | null>(null);

  // 没有服务端首屏数据时在浏览器取第一页;卸载时取消请求
  useEffect(() => {
    if (initialData) return;
    const controller = new AbortController();
    client.getStoreReviews({limit: 10}, {signal: controller.signal}).then(setData, () => {});
    return () => controller.abort();
  }, [client, initialData]);

  // 先逐个上传媒体拿 tempId,再提交评论;是否立即展示取决于商家后台的自动发布设置
  async function submit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const formElement = event.currentTarget;
    const form = new FormData(formElement);
    try {
      const files = form.getAll('media').filter((file): file is File => file instanceof File && file.size > 0);
      const tempIds: string[] = [];
      for (const file of files) {
        const uploaded = await client.uploadStoreMedia({file, type: file.type.startsWith('video/') ? 'video' : 'image'});
        tempIds.push(uploaded.tempId);
      }
      await client.submitStoreReview({
        rating: Number(form.get('rating')),
        content: String(form.get('content') ?? ''),
        nickname: String(form.get('nickname') ?? ''), // 必填
        email: String(form.get('email') ?? '') || undefined,
        tempIds,
      });
      formElement.reset();
      setNotice('感谢评价!');
    } catch (error) {
      setNotice(error instanceof Error ? error.message : '提交失败,请稍后再试');
    }
  }

  return (
    <section>
      {data ? <StarRating rating={data.summary.averageRating} count={data.summary.totalReviews} showValue /> : null}
      {data?.reviews.map((review) => (
        <article key={review.id}>
          <StarRating rating={review.rating} />
          <p><strong>{review.author.name}</strong>:{review.content}</p>
          {review.media.map((media) => (media.type === 'image' ? <img key={media.id} src={media.url} alt="" /> : null))}
          {review.reply ? <p>商家回复:{review.reply.content}</p> : null}
        </article>
      ))}
      <form onSubmit={submit}>
        <select name="rating" defaultValue="5">{[5, 4, 3, 2, 1].map((n) => <option key={n} value={n}>{n} 星</option>)}</select>
        <textarea name="content" required />
        <input name="nickname" required />
        <input name="email" type="email" placeholder="邮箱(可选)" />
        <input name="media" type="file" accept="image/*,video/*" multiple />
        <button type="submit">提交</button>
        {notice ? <p role="status">{notice}</p> : null}
      </form>
    </section>
  );
}
```

- 翻页:`getStoreReviews({page: data.pagination.page + 1, limit: 10})`,用法同上面的问答;排序 `sort`、星级筛选 `ratingFilter` 见 8.1。
  `summary.averageRating` / `totalReviews` 受星级筛选影响,`summary.distribution` 与 `gallery`(最近 20 个媒体)不受影响。
- 点赞:`client.reactToStoreReview({reviewId: review.id, reaction})`,返回最新计数。
- 服务端首屏(可选):用 `createCustomersSayServerClient({apiBase, secretKey}).getStoreReviews({limit: 10}, {clientIp, userAgent})`
  取数后作为 `initialData` 传入(`clientIp` / `userAgent` 的取法同 4.1 / 5.1);店铺评论列表的 `userReaction` 按访客 IP 匹配。
- 媒体上限与商品评论一致:图片每张 ≤ 2 MB、最多 6 张,视频 ≤ 20 MB、最多 1 个,合计 ≤ 30 MB。单个文件超限时上传即返回 400;
  数量或合计大小超出的文件提交时不会被认领(评论照常创建,只是不带这些媒体),请在界面上先按上限限制选择。
- 提交返回 `{ review }`(新评论的规范化结果),但响应不含发布状态:商家开启自动发布时它已在列表里,否则需审核后才展示,
  界面上请按“已提交”提示,不要直接插入列表。

## 9. 样式与定制

- 可选最小样式:`import '@customerssay/react/styles.css'`(选择器包在 `:where()` 中,特异性为 0,店面样式总能覆盖)。
- CSS 变量:`--cs-star-color`、`--cs-star-empty-color`、`--cs-muted-color`、`--cs-border-color`、`--cs-bar-track-color`、
  `--cs-verified-color`、`--cs-error-color`、`--cs-radius`、`--cs-gap`(由 `styles.css` 应用;不引入 `styles.css` 时星级与分布条
  使用内置的默认颜色)。
- 星级(`.cs-star`)与分布条(`.cs-review-summary__bar`)是 SVG,组件不输出 style 属性(见第 6 节):自定义颜色请写 CSS 的 `fill`
  (如 `.cs-star__fill { fill: #111 }`、`.cs-review-summary__fill { fill: #111 }`、`.cs-review-summary__track { fill: #eee }`),
  不是 `color` / `background`。
- 每个组件接受 `className`,多数接受 `classNames`(按部位追加类名),以及 `render*` 渲染函数替换局部或整卡。
- 文案:`labels` 覆盖默认英文文案(如 `{ noReviews: '暂无评论', basedOnReviewsOther: '共 {count} 条评论' }`),
  Provider 上设置的 `labels` 对其下所有客户端组件生效;文案均为字符串模板,可跨 RSC 边界传递。
- 日期按商家后台配置的 DMY / YMD / MDY 以 UTC 格式化,服务端渲染与浏览器水合输出一致。

## 10. 错误处理

`ReviewForm` / `useReviewForm` 提交失败时保留草稿。对同一客户端、商品和同一组 File 对象,30 分钟内重试会复用已经上传成功的图片/视频;部分文件上传失败时只重传失败的文件。修改文件集合、切换商品/客户端、重置表单、提交成功或缓存过期后会重新上传,避免复用其它提交上下文的文件。缓存仅存在当前表单内存中,不写入 localStorage,也不会自动重试写请求。

- 接口失败统一抛 `CustomersSayApiError`:`status`(0 = 网络错误)、`code`、`message`、`endpoint`、`fields`、`retryAfter`。
  - 鉴权层错误 `{error: {code, message}}`:`code` 为 `missing_key`、`invalid_key`、`secret_key_in_browser`、`origin_not_allowed`、
    `origin_required`、`shop_unavailable`、`shop_mismatch`、`rate_limited`;
  - 业务错误 `{error: "..."}`:`code` 按状态推导(`bad_request`、`not_found`、`payload_too_large`、`rate_limited`、`server_error` …)。
- 配置错误(私钥进浏览器、密钥前缀不对、缺商品引用等)抛 `CustomersSayConfigError`,不会发出请求。
- 跨包副本判断请用 `isCustomersSayApiError(e)` / `isCustomersSayConfigError(e)`。
- `ReviewForm` 只向顾客展示 400 / 413 / 429 的服务端信息,其它错误显示通用文案,详细错误经 `onError` 获取。
- 用 `fields` 隐藏的字段若有错误(本地必填校验或服务端 `fields` 明细),会以“字段名: 错误”并入表单的通用错误区,
  不会出现“点提交没反应”。自定义 UI 时可给 `useReviewForm` 传 `hiddenFields` 获得同样效果。
- 隐藏邮箱(`fields={{email: false}}`)时本地不再强制必填,但 v1 接口要求邮箱:请用 `defaultValues.email` 预填
  (如已登录顾客的邮箱)。开发环境下,“字段隐藏但必填”“隐藏邮箱却没有预填”“`allowMedia` 缺 `productId`”
  “既无 Provider 也无 `submit`”等矛盾配置会在浏览器控制台 `console.warn`(生产构建不输出)。

常见问题:

| 现象 | 原因 |
|---|---|
| 浏览器里报 `network_error`(Network 面板可见 403 `origin_not_allowed`) | 当前站点 Origin 未在公钥下登记(注意协议、端口、www)。未登记 Origin 的响应不带 `Access-Control-Allow-Origin`,浏览器读不到响应体,客户端只能报网络错误 |
| 403 `origin_required` | 在服务端用公钥做写操作;服务端写入请用私钥 |
| 403 `secret_key_in_browser` | 私钥请求带了 Origin 头(例如把浏览器请求头原样转发给 v1);`handleReviewSubmission` 不会转发 |
| 所有访客共用点赞 / 被限流 | 服务端调用时没有传 `clientIp`,或 `getVisitorIp` 漏传 `platform` / 传了 `{platform: null}`(返回 `null`;漏传时开发环境控制台会有以 `[CustomersSay] getVisitorIp() was called without` 开头的警告) |
| SSR 首屏的 `userReaction` 恒为 `null`(刷新后看不到自己点过的“有帮助”) | 服务端取数时只传了 `clientIp`,没有传 `userAgent`(访客指纹是 IP + 浏览器 User-Agent,见 4.2) |

## 11. 开发与测试

测试由仓库根的 vitest 收集(只用 `react-dom/server` 的 `renderToString`,不依赖 jsdom):

```bash
# 在仓库根目录
npx vitest run packages/customerssay-react
```

测试读取共享的 `fixtures/headless-v1/*.json`:v1 接口结构变化会让路由测试与本包测试同时失败。

公开文档:`/headless/docs/react`。嵌入脚本的 Swiper 也由应用域名提供,不需放行 jsDelivr;嵌入脚本仍需 `style-src-attr 'unsafe-inline'`,React 组件默认不输出 style 属性。