Headless Storefront API v1

The API contract for headless storefronts (Hydrogen, Next.js and other custom storefronts). Create API keys in the CustomersSay app (Headless page). The document is shown as plain Markdown text.

# CustomersSay Headless Storefront API v1(契约)

> 面向 Shopify headless 店面(Hydrogen / Oxygen、Next.js 等自建前端,以及关闭了 Online Store 的店铺)。
> 本文是 v1 路由、嵌入脚本与 React/Hydrogen 组件包三方共同遵守的契约;响应示例见 `fixtures/headless-v1/*.json`
> (路由测试与组件包测试都读取这些文件,结构漂移会在两边同时失败)。

- 基础地址:`https://<应用域名>/api/storefront/v1`(生产:`https://app-next.customerssay.ai/api/storefront/v1`)
- 所有接口返回 JSON(`embed.js` / `embed.css` 除外)。
- **与主题店接口一致**:v1 的读写接口复用 App Proxy 接口(`/apps/customerssay/...`)的同一套处理逻辑,
  请求参数与响应结构相同,区别只在鉴权方式。主题 JS 在 headless 模式下改用 v1 基础地址即可工作。

## 1. 鉴权

商家在后台「Headless」页面创建密钥:

| 密钥 | 前缀 | 放在哪里 | 能做什么 |
|---|---|---|---|
| 公钥 | `pk_live_` | 浏览器(可公开) | 读;在后台登记过的 Origin 下写入(提交评论 / 点赞 / 提问 / 上传媒体) |
| 私钥 | `sk_live_` | 只放在商家服务端 | 读写;可代访客提交并传入可信的访客 IP 与已登录顾客 ID |

### 公钥(浏览器)
- 请求头 `X-CustomersSay-Key: pk_live_...`;**GET 请求**也可以用查询参数 `?key=pk_live_...`(不触发 CORS 预检)。
- 浏览器请求的 `Origin` 必须在该公钥登记的允许列表中(精确匹配 `scheme://host[:port]`,只接受 https,本地开发可用 `http://localhost`)。
- **创建或编辑公钥时必须至少登记 1 个 Origin**(每个公钥最多 20 个):空列表的公钥在浏览器里不可用,后台会拒绝保存;
  服务端调用请使用私钥。后台「Headless」页的接入说明会预填最新创建的、未吊销且已登记 Origin 的公钥。
- **写请求(POST)只接受请求头里的公钥,且必须带已登记的 Origin**;没有 Origin(服务端调用)的公钥写入一律 403——服务端写入请用私钥。
- 公钥请求中的 `X-CustomersSay-Client-IP` / `X-CustomersSay-Client-UA` / `X-CustomersSay-Customer-Id` 会被忽略。
- 公钥提交的评论**不会自动标记"已验证购买"**(浏览器无法证明顾客身份),可由商家在后台手动标记。

### 私钥(商家服务端)
- 请求头 `Authorization: Bearer sk_live_...`。
- **请求带 `Origin` 头(说明来自浏览器)一律 403**;预检也不放行 `Authorization`,浏览器无法跨域发出私钥请求。
- 可选可信请求头:
  - `X-CustomersSay-Client-IP`:真实访客 IP(用于点赞去重与限流;不传则所有访客会被视为你的服务器 IP)。
  - `X-CustomersSay-Client-UA`:访客浏览器的 `User-Agent`(原样转发入站请求的 `User-Agent`,最长 1024 字符,超过视为未提供)。
    商品评论 / 问答的点赞、点踩按指纹 `md5("{访客IP}:{浏览器UA}")` 识别访客;SSR 取 `/reviews`、`/questions` 时同时传它和
    `X-CustomersSay-Client-IP`,响应里的 `userReaction` 才能对上访客之前在浏览器里的反应
    (不传时按你服务器自身的 `User-Agent` 计算,对不上,`userReaction` 为 `null`)。代访客调用三个 `*-reactions` 接口时同样适用。
  - `X-CustomersSay-Customer-Id`:经 Shopify Customer Account API 确认的已登录顾客 ID(纯数字或 `gid://shopify/Customer/123`)。
    传入后,评论按"顾客身份"核对订单来判定"已验证购买";不传则不自动判定。

### 通用规则
- 店铺由密钥决定;请求中的 `shop` 可省略,若提供必须与密钥所属店铺一致(大小写不敏感),否则 403。店铺须处于已安装状态。
  - 查询参数 `shop` 不一致:鉴权层 403 `shop_mismatch`;
  - 请求体里的 `shop`(JSON 字段或表单字段;所有写接口:`/reviews`、`/questions`、`/store-reviews`、三个 `*-reactions`、
    `/media-upload`、`/store-media-upload`)不一致:业务层 403 `{ "success": false, "error": "Shop mismatch" }`,不写库、不上传。
- 限流:每个(密钥 + 访客 IP)读 120 次/分钟、写 20 次/分钟;超出返回 429 `rate_limited` 与 `Retry-After`。
  不设每把密钥共用的总量硬上限,避免公开密钥额度被第三方耗尽,以及不同 SSR 访客共享额度。写入接口自身的限流仍然有效。
  私钥 SSR 应转发可信访客 IP;缺失时所有访客会共用服务端出口 IP 的额度。分布式滥用需在可信边缘部署 WAF / 风险控制。
  各接口另有与主题店相同额度的业务限流(如评论 / 问答 / 店铺评论点赞每分钟 30 次、提问每 10 分钟 5 次、
  同一邮箱提交评论间隔 4 秒、上传每 10 秒约 10 次),
  v1 请求按(店铺 + 访客 IP)单独计数,不与主题店访客、其它店铺共用。
- 访客 IP(用于上述按 IP 的限流、点赞去重与用户资料里的 IP / 国家):
  - 私钥请求:取 `X-CustomersSay-Client-IP`(须为合法 IP);没带或不合法时按下一条取(即你服务器的出口 IP);
  - 公钥请求(以及没带可信头的私钥请求):服务端取 `X-Forwarded-For` **从右数第 N 项**,N 为 CustomersSay 部署配置的可信代理跳数
    (见下);客户端自己填写的最左侧项一律不读,伪造 `X-Forwarded-For` 不能换到别的限流桶。
    `X-Forwarded-For` 缺失、项数不足或该项不是合法 IP(去掉部分负载均衡追加的端口后用 `net.isIP` 校验)时取 `X-Real-IP`(同样校验);
    仍拿不到时记为 `unknown`,这类请求共用同一个按 IP 的限流桶。
  - **部署配置 `STOREFRONT_TRUSTED_PROXY_HOPS`**(CustomersSay 服务端环境变量,正整数,默认 `1`):应用前面有几层**自己控制**、
    会向 `X-Forwarded-For` 追加对端地址的反向代理 / 负载均衡就填几。只有一层 nginx(`$proxy_add_x_forwarded_for`)或负载均衡时为 `1`
    (默认);前面再加一层 Cloudflare(Cloudflare 追加访客 IP,nginx 再追加 Cloudflare 边缘节点 IP)时为 `2`。
    填小了会把最近一层代理的地址当作访客(所有访客共用一个桶),填大了会读到客户端可伪造的项;缺失、`0`、负数、小数或非数字按 `1` 处理。
    多层时内层代理应只接受来自外层的连接(例如 nginx 只放行 Cloudflare 的 IP 段),否则绕过外层直连内层的请求仍可伪造被信任的那一项。
- CORS:`OPTIONS` 预检返回 204;实际响应只对已登记 Origin 返回 `Access-Control-Allow-Origin`(回显该 Origin),
  v1 的 JSON 接口**绝不返回** `Access-Control-Allow-Origin: *`。
  例外:`/embed.js`、`/embed.css` 是无需密钥的公开静态资源,成功响应(200,以及 `If-None-Match` 命中时的 304)返回
  `Access-Control-Allow-Origin: *`(另有 `Cross-Origin-Resource-Policy: cross-origin`、`Cache-Control: public, max-age=300` 与 `ETag`);
  资源暂时不可用时返回 503(`Cache-Control: no-store`、`Retry-After: 60`),**不带** `Access-Control-Allow-Origin`
  ——`<script>` / `<link>` 引用照常按加载失败处理,不受影响。
- 请求方法:只写接口(`/review-reactions`、`/question-reactions`、`/store-review-reactions`、`/media-upload`、`/store-media-upload`)
  只接受 `POST`(`Allow: POST, OPTIONS`),读写接口(`/reviews`、`/questions`、`/store-reviews`)接受 `GET` / `POST`
  (`Allow: GET, POST, OPTIONS`),只读接口(`/rating-summary`、`/featured`、`/widget-settings`、`/json-ld`)只接受 `GET`
  (`Allow: GET, OPTIONS`);其它方法(含只写接口上的 `GET`、只读接口上的 `POST` / `PUT` / `DELETE`)
  返回 405 + `Allow` 头,业务错误格式 `{ "success": false, "error": "Method not allowed" }`,不需要密钥。

### 请求体大小与 Content-Length(写接口)
- 写接口(multipart 与 JSON)**可以带 `Content-Length`,也可以分块传输**(`Transfer-Encoding: chunked`,或经关闭请求缓冲的反向代理、
  HTTP/2 → HTTP/1.1 负载均衡、隧道等转发后不再带 `Content-Length`),读取表单 / 解析 JSON 之前按下表上限限制请求体:
  - 带合法 `Content-Length` 且超过上限:**立即**返回 413 `{ "success": false, "error": "Request body too large" }`,不解析请求体;
    不超过上限则照常处理;
  - 不带 `Content-Length`(或分块传输):服务端按上限**边读边计**,未超过则照常处理;累计超过上限即停止缓冲并立即返回同样的 413。
    分块数量另有上限 **65,536 块**(每次读取计一块,含空块):超过同样立即 413——正常客户端、代理转发的块远大于 512 字节,
    31 MB 的上限按 TCP 报文段计也只有约 2.3 万块,只有逐字节分块之类的异常发送方式才会触发;
  - **超限返回 413,服务端随后读完并丢弃剩余请求体**:413 不带 `Connection: close`,连接保持 keep-alive;
    返回 413 之后,服务端在后台继续读取并丢弃剩余请求体(不缓冲、不解析),**最多 32 MB、最多 65,536 块、最多 10 秒**:
    - 剩余部分在这个范围内读完(例如声明 22 MB 的上传超过 21 MB 上限):连接照常复用,客户端可靠收到 413,
      同一连接上的下一个请求正常处理;
    - 剩余超过 32 MB(分块传输时才会出现,声明长度超过 32 MB 的见下一条)、读取超过 65,536 块(逐字节发送之类的异常方式),
      或发送过慢(10 秒内发不完):服务端在 413 已发出后停止读取并关闭连接,
      客户端**可能在收到 413 之后、甚至尚未读到 413 时看到连接重置**(`ECONNRESET` / `EPIPE` / 上游 502;浏览器表现为 `Failed to fetch`)。
      上传大文件时遇到这类连接错误,应按"请求体过大"处理,不要原样重发同一个请求体;
  - **例外:声明的 `Content-Length` 超过 32 MB**(例如声明 40 MB 传到 21 MB 上限):剩余部分注定读不完,413 **带 `Connection: close`**,
    服务端不读取请求体,写完 413 即关闭连接。读到 413 的客户端不会再复用这条连接(下一个请求走新连接);
    同样可能在读到 413 之前就看到连接重置,按"请求体过大"处理即可;
  - 同样的"读完并丢弃"也适用于其它不读请求体就返回的写请求(鉴权失败 401 / 403 / 429、缺参数 400、上传限流 429 等),
    keep-alive 连接上的后续请求不受影响;
  - **客户端(尤其浏览器)应在发送前先在本地按下表校验文件 / 请求体大小**:浏览器在上传途中收到 413 时能否把响应交给页面
    取决于浏览器实现与超出的大小,本地预检是唯一可靠的方式;收到 413 后应停止发送;
  - `Content-Length` 不是十进制非负整数(如 `abc`、`-1`):400 `{ "success": false, "error": "Invalid Content-Length header" }`,不解析请求体。
- 上限:

  | 接口 | 上限 | 说明 |
  |---|---|---|
  | `POST /media-upload`、`POST /store-media-upload` | 21 MB | 单文件上限(视频 20 MB / 图片 2 MB,读表单前无法区分,取较大值)+ 1 MB 表单余量;类型对应的大小限制在读表单后另行校验(超出 400) |
  | `POST /reviews` | 31 MB | 直传媒体累计上限 30 MB + 1 MB 表单余量(通常先预上传,请求体只有文本字段) |
  | `POST /questions`、`POST /store-reviews`、`POST /review-reactions`、`POST /question-reactions`、`POST /store-review-reactions`(JSON) | 256 KB | 问题 / 店铺评论正文最多 65,535 字节(数据库 TEXT 列),JSON 转义最多翻倍,加标题、昵称、邮箱、`tempIds` 等字段最大约 131 KB,留约 2 倍余量;反应接口的请求体通常不到 1 KB。超限 413 时不解析 JSON、不写库 |

- 浏览器 `fetch` / `XMLHttpRequest` 发送 `FormData` 或 JSON 字符串时会自动带 `Content-Length`;商家服务端(BFF)把收到的请求体以流的形式
  原样转发(`duplex: "half"`,分块传输)也可以,无需先缓冲。超过上限的请求都会被拒绝(见上),客户端应先在本地校验文件大小。

### 缓存与 Vary
- 鉴权通过后的 v1 响应(含业务错误)都带 `Vary: Origin, Authorization, X-CustomersSay-Key`(与处理逻辑原有的 `Vary` 合并,不覆盖);
  鉴权层错误(401/403/429)与 `OPTIONS` 预检只带 `Vary: Origin`,且不带 `Cache-Control`。
- 部分读接口带 `Cache-Control`(`/rating-summary`、`/featured`、`/json-ld` 为 `max-age=300`):
  - 私钥请求(`Authorization`)或公钥放在请求头 `X-CustomersSay-Key` 时:改为 `private, max-age=300`(只允许浏览器 / 调用方私有缓存,
    CDN / 反向代理等共享缓存不得复用——这类请求的 URL 不含密钥,共享缓存可能把响应交给不带密钥的请求);
  - 公钥走查询参数 `?key=` 时:密钥本身就在 URL(缓存键)里,保持 `public, max-age=300`,可放心交给 CDN 缓存。
- 处理函数未指定 `Cache-Control` 时,私钥请求或请求头公钥的已鉴权响应会补 `private, no-store`;查询参数公钥保持原策略。SSR 场景如需在自己的 CDN 上缓存,建议使用 `?key=` 形式的公钥读请求。

### 错误格式
- 鉴权层错误(401/403/429):`{ "success": false, "error": { "code": "...", "message": "..." } }`(见 `fixtures/headless-v1/error.auth.json`)。
  `code` 取值:`missing_key`、`invalid_key`、`secret_key_in_browser`、`origin_not_allowed`、`origin_required`、
  `shop_unavailable`、`shop_mismatch`、`rate_limited`。
- 业务处理错误(400/403/404/405/413/429/500 等)沿用现有接口格式:`{ "success": false, "error": "..." }`(见 `error.handler.json`)。
  例外:`/featured` 沿用主题店写法 `{ "error": true, "message": "..." }`(400 / 500)。
- 状态码可信:处理逻辑沿用主题店"200 + `{ success: false }`"的软失败(例如评论列表查询异常)在 v1 一律改为 **500**,响应体不变;
  v1 的 200 响应不会出现 `success: false`。
- 客户端应同时兼容两种 `error` 形态(字符串或 `{code,message}` 对象)。

## 2. 接口

| 方法 | 路径 | 对应现有接口(处理逻辑相同) | 访问 | 响应示例 |
|---|---|---|---|---|
| GET | `/reviews` | `publicreviews` loader | 读 | `reviews.list.json` |
| POST | `/reviews` | `publicreviews` action | 写 | `review.submit.json` |
| GET | `/rating-summary` | `product-rating-summary` | 读 | `rating-summary.json` |
| GET | `/featured` | `publicfeatured`(忽略 `shopId` 参数,店铺由密钥决定;**文本为 HTML 实体转义后的**,见下文) | 读 | `featured.list.json` |
| GET / POST | `/questions` | `publicquestions` | 读 / 写 | `questions.list.json` |
| GET / POST | `/store-reviews` | `publicstorereviews` | 读 / 写 | GET:`store-reviews.list.json`;POST 见下文 |
| POST | `/review-reactions` | `publicreviewreactions` | 写 | 见下文 |
| POST | `/question-reactions` | `publicquestionreactions` | 写 | 见下文 |
| POST | `/store-review-reactions` | `publicstorereviewreactions` | 写 | 见下文 |
| POST | `/media-upload` | `mediaupload`(查询参数带 `productId`,或缺省时带 `product_handle`) | 写 | 见下文 |
| POST | `/store-media-upload` | `storemediaupload` | 写 | 见下文 |
| GET | `/widget-settings` | `widget-settings` | 读 | — |
| GET | `/json-ld` | 新增:商品 Product + AggregateRating + Review 结构化数据,供 SSR 输出 | 读 | `json-ld.json` |
| GET | `/embed.js`、`/embed.css` | 新增:可嵌入任意站点的评论组件脚本与样式(无需密钥;200 / 304 带 `Access-Control-Allow-Origin: *`、`max-age=300` + `ETag`;503 不带 CORS 头) | 公开 | — |

### 参数要点(读接口)
- 商品(读接口查询参数):`product_id`(纯数字或 `gid://shopify/Product/123`,也接受 `productId`)或 `product_handle`。
- 列表分页:`page`、`limit`(有上限);评论星级筛选用 `rating_filter`(1–5)。**GET `/reviews` 上的 `rating` 参数不用于筛选**。
- `GET /store-reviews`:`page`(默认 1)、`limit`(默认 5,最大 50)、`sortBy`(`recent` 默认 / `oldest` / `highest` / `lowest`)、
  `rating`(1–5,只返回该星级;注意这里的星级筛选参数叫 `rating`,与 `/reviews` 的 `rating_filter` 不同)。
  响应见 `store-reviews.list.json`:`title`、`user`、`reply` 可能为 `null`;`userReaction` 按访客 IP 匹配(`like` / `dislike` / `null`);
  `summary.average` 与 `summary.total` 随 `rating` 筛选变化,`summary.distribution`(键为星级,只含有评论的星级)始终统计全部已发布店铺评论;
  `allReviewMedia` 为最近 20 个媒体(供画廊使用)。
- `GET /featured`:`mode`(`featured` / `five-star` / `with-pictures` / `all`)、`limit`(1–50);**忽略 `shopId` 参数**,店铺由密钥决定。
  响应见 `featured.list.json`:`title`、`user.country`、`product.mainImageUrl`、`response` 可能为 `null`;`timestamp` 为秒级 Unix 时间。
  - **文本是 HTML 实体转义后的,不是纯文本**(与 `/reviews`、`/questions` 不同;主题店渲染依赖此行为,v1 保持不变):
    `content`、`title`、`user.nickname`、`product.name`、`response.content` 中的 `<` `>` `"` `'` `/` `` ` `` `\` 分别替换为
    `&lt;` `&gt;` `&quot;` `&#x27;` `&#x2F;` `&#96;` `&#92;`(`&` 本身不转义),并删除 `javascript:` 与 `on…=` 子串。
    自建 UI 用 React / `textContent` 等按纯文本渲染时,需先把这些实体解码(如 `It&#x27;s` → `It's`),否则会原样显示实体。
  - `reviews[].product.url` 按店铺在后台「Headless」页的设置生成:启用 headless 且配置了店面地址(Storefront base URL)时为绝对 URL
    (店面地址 + 商品路径模板,如 `https://shop.example.com/en-us/products/linen-shirt`);否则按商品路径模板(Product URL template,
    默认 `/products/{handle}`)生成相对路径;handle 经 URL 编码。商品没有 handle 时不返回该字段。
- `GET /json-ld`:`product_id` 或 `product_handle`,可选 `limit`(最近评论条数 1–10,默认 5,非法值回落默认,超过 10 按 10)。
  响应 `{ success, productId, jsonLd }`,`jsonLd` 是完整的 schema.org Product,**自带 `"@context": "https://schema.org"`**,
  可直接写进 `<script type="application/ld+json">`;只统计该商品自己的已发布评论,**没有已发布评论时不输出 `aggregateRating` 与 `review`**
  (Google 要求评分对应页面可见评论);文本已转纯文本并截断,不含 `<` `>`。
- 公开响应**不回传**任何购买验证结果。

### 写接口请求体
请求体大小上限与超限时的 413 见上文"请求体大小"。所有写接口都可带可选的 `shop`(字符串),只做一致性比对(不一致 403 `Shop mismatch`)。
字段缺失或不合法时返回 400 `{ "success": false, "error": "..." }`(`POST /reviews` 缺必填字段时另带 `fields`,见下)。

#### `POST /reviews`(`multipart/form-data`)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `rating` | 是 | 字符串,整数 `1`–`5` | 缺失或不是严格整数(如 `4.5`、`5abc`)400(`error` 为提示文案,不保证稳定) |
| `email` | 是 | 字符串 | 合法邮箱;格式非法 400 `Invalid email address` |
| `content` | 视店铺表单配置(默认必填) | 字符串 | |
| `nickname` | 视店铺表单配置(默认选填) | 字符串 | 缺省显示为 `Anonymous` |
| `title` | 否 | 字符串 | |
| `productId` / `product_id` | 与 `product_handle` 二选一 | 字符串,纯数字或 Product GID | 不是密钥所属店铺的商品(或不存在)404 `Product not found for this shop` |
| `product_handle` | 与上一项二选一 | 字符串 | 只在没有 `productId` / `product_id` 时使用,在密钥所属店铺内解析;找不到按缺少商品处理:400 `Missing required fields`(`fields.productId` 为 `"required"`) |
| `recommended` | 否 | 字符串 | `"true"` 表示推荐,其它值视为不推荐 |
| `mediaUrls[]` / `mediaTypes[]` / `mediaThumbnails[]` | 否 | 字符串(可重复,按顺序一一对应) | 预上传(`/media-upload`)返回的 `file.url` / `file.type`(`image` / `video`)/ `file.thumbnailUrl`(图片传空串);`mediaUrls[]` 与 `mediaTypes[]` 条数不一致时整体忽略;只接受本应用媒体存储域名的地址,其余丢弃;每条评论最多 6 张图片 + 1 个视频 |
| `media` | 否 | 文件(可重复) | 遗留直传兜底(预上传失败时),校验规则同 `/media-upload`;通常不要使用 |

缺少必填字段:400 `{ "success": false, "error": "Missing required fields", "fields": { "productId", "rating", "content", "nickname", "email" } }`
(`fields` 中缺失的字段为 `"required"`,其余为 `null`;缺 `rating` 会先按上表返回评分错误,因此 `fields.rating` 实际总为 `null`)。同一访客 IP + 邮箱 4 秒内只能提交一次(429)。响应见 `review.submit.json`。

#### `POST /questions`(JSON)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `productId` | 与 `productHandle` 二选一 | 字符串或数字,纯数字或 Product GID | |
| `productHandle` | 与上一项二选一 | 字符串 | 注意 JSON 字段名是 `productHandle`(驼峰) |
| `content` | 是 | 字符串 | 缺失 400 `Question content is required` |
| `email` | 是 | 字符串 | 缺失 400 `Email is required` |
| `nickname` | 否 | 字符串 | 缺省 `Anonymous` |

问题需商家审核后才会出现在列表。响应 `{ "success": true, "message": "Question submitted successfully and is pending approval", "questionId": 55 }`。
同一访客 IP 10 分钟内最多 5 个问题(429);商品找不到 404 `Product not found for this shop`。

#### `POST /store-reviews`(JSON)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `rating` | 是 | 整数 1–5(数字或数字字符串) | 非法 400 `Invalid rating` |
| `content` | 是 | 字符串 | 缺失 400 `Content is required` |
| `user_name` | 是 | 字符串 | 缺失 400 `Nickname is required`(注意字段名与商品评论的 `nickname` 不同) |
| `user_email` | 否 | 字符串 | 注意字段名与商品评论的 `email` 不同 |
| `title` | 否 | 字符串 | |
| `tempIds` | 否 | 字符串数组 | `/store-media-upload` 返回的 `file.tempId`;只接受 `[A-Za-z0-9_-]`、最长 64 的值,去重后最多 7 个(图片 6 + 视频 1),只认领本店铺上传且未被认领的文件 |

是否直接发布取决于店铺的自动发布设置。响应:
`{ "success": true, "review": { "id", "rating", "title", "content", "created_at", "user": { "nickname" }, "media": [{ "id", "url", "thumbnailUrl", "mediaType" }], "likesCount": 0, "dislikesCount": 0, "userReaction": null } }`。

#### `POST /review-reactions`、`POST /question-reactions`、`POST /store-review-reactions`(JSON)
| 接口 | 字段 | 必填 | 类型 / 取值 |
|---|---|---|---|
| `/review-reactions` | `reviewId` | 是 | 正整数(数字或数字字符串),商品评论 ID |
| `/question-reactions` | `questionId` 或 `answerId` | 恰好其一 | 正整数,问题 ID 或商家回复 ID;两者都带 400 |
| `/store-review-reactions` | `reviewId` | 是 | 正整数,店铺评论 ID |
| 三者 | `reaction` | 是 | `like` / `dislike` / `none`(`none` 取消已有反应) |

同一访客对同一条内容只保留一个反应(再次 `like` 不重复计数,`like` 改 `dislike` 会切换)。访客按指纹 `md5("{访客IP}:{UA}")` 识别
(UA 为请求自身的 `User-Agent`;私钥请求带 `X-CustomersSay-Client-UA` 时改用它,见第 1 节),找不到时按访客 IP 兜底;每个访客 IP 每分钟最多 30 次(429)。内容不属于密钥所属店铺时 404。
响应:`/review-reactions`、`/store-review-reactions` 为 `{ "success": true, "message": "...", "likesCount", "dislikesCount" }`
(`message` 为展示用文案,不保证稳定);`/question-reactions` 为 `{ "success": true, "likesCount", "dislikesCount" }`。

#### `POST /media-upload`、`POST /store-media-upload`(`multipart/form-data`)
- `POST /media-upload?productId=…`:商品用查询参数 `productId`(也接受 `product_id`)指定;
  缺少时可改用 `product_handle`(也接受 `productHandle`),服务端在密钥所属店铺内解析为商品,找不到 404 `Product not found for this shop`;
  两者都缺 400 `Missing productId parameter`。`/store-media-upload` 不需要商品参数。
- 表单字段:

  | 字段 | 必填 | 类型 | 说明 |
  |---|---|---|---|
  | `type` | 是 | `image` / `video` | 其它值 400 |
  | `file` | 是 | 文件 | 图片最大 2 MB、视频最大 20 MB;校验 MIME、扩展名与文件头,文件名含可疑代码 400 |
  | `tempId` | 否 | 字符串 | 同一次评论的多个文件共用一个 `tempId`(按它统计每次最多 6 张图片 + 1 个视频、累计 30 MB);只接受 `[A-Za-z0-9_-]`、最长 64,**缺省或不合法时由服务端生成**(16 位十六进制)并在响应里返回,后续文件请沿用响应里的值 |

- 响应 `{ "success": true, "file": { "url", "thumbnailUrl", "type", "tempId" } }`(视频的 `thumbnailUrl` 为截帧地址,图片为 `null`)。
  商品评论:提交时把 `file.url` / `file.type` / `file.thumbnailUrl` 放进 `POST /reviews` 的 `mediaUrls[]` / `mediaTypes[]` / `mediaThumbnails[]`;
  店铺评论:把 `file.tempId` 放进 `POST /store-reviews` 的 `tempIds`,临时文件按密钥所属店铺隔离。
- 上传限流:每个访客 IP 每 10 秒约 10 次(429)。

## 3. 嵌入脚本(任意 headless 站点)

```html
<link rel="stylesheet" href="https://<应用域名>/api/storefront/v1/embed.css">
<script>
  window.CustomersSayConfig = {
    apiBase: "https://<应用域名>/api/storefront/v1",
    publicKey: "pk_live_...",
    shop: "your-store.myshopify.com"
  };
</script>
<script src="https://<应用域名>/api/storefront/v1/embed.js" defer></script>

<div data-customerssay-reviews data-product-id="8123456789"></div>
```

单页应用切换商品时调用 `window.CustomersSay.mount(element, { productId })` / `unmount(element)`。
内容安全策略(CSP)需放行应用域名(script/style/connect)及媒体存储域名(img/media)。Swiper 的脚本与样式均由应用域名的 `/api/widget-assets/swiper-bundle.min.js` / `.css` 提供,无需放行 jsDelivr。
嵌入脚本不依赖内联事件处理器或动态注入的 style 标签;配置脚本应带站点 nonce。标记中仍有 style 属性,需要 `style-src-attr 'unsafe-inline'`(旧浏览器可在 style-src 放行内联样式)。React 包默认不输出 style 属性。
星级挂载每次初始化仅请求一次 rating-summary;请求失败时隐藏,不显示成 0 分。商品列表卡片推荐读取第 5 节评分字段。

## 4. React / Hydrogen

见仓库 `packages/customerssay-react/README.md`:服务端取数函数(loader 中调用,SSR 首屏与 JSON-LD)+ 客户端组件。

## 5. 商品评分元字段(Shopify Storefront API 直接读取)

除 v1 接口外,应用还把每个商品的评论汇总写进 Shopify 商品元字段。headless 店可以在自己的 Shopify Storefront API
(GraphQL)查询里直接读取(适合 SSR 首屏、商品列表卡片的星级),不经过 v1、不占用 v1 的限流额度。
评论提交、发布 / 取消发布、删除、导入后由应用自动同步(异步,可能有短暂延迟);只统计该商品自己的已发布评论。

| 元字段 | 类型 | 值 | 何时写入 |
|---|---|---|---|
| `customerssay.reviews_summary` | `json` | `{"average_rating": 4.58, "total_reviews": 12}`(平均分保留两位小数) | 始终写入 |
| `customerssay.recent_reviews` | `json` | 最近 5 条已发布评论的数组:`rating`、`title`、`content`、`author_name`、`created_at`、`verified_purchase` | 始终写入 |
| `reviews.rating` | `rating`(Shopify 标准定义 Product rating) | `{"value":"4.58","scale_min":"1.0","scale_max":"5.0"}` | 标准定义已启用,且有已发布评论(没有时删除) |
| `reviews.rating_count` | `number_integer`(Shopify 标准定义 Product rating count) | 已发布评论数。**没有评论的商品可能没有该元字段(查询为 `null`)**;有过评论、之后全部删除 / 取消发布时同步为 `0` | 标准定义已启用 |

- 元字段只在该商品发生过同步(评论提交、发布 / 取消发布、删除、导入)后才存在:从未有过评论的商品查询这些元字段都为 `null`,按“没有评论”处理。
- `customerssay.*` 两个定义由应用创建并开启 Storefront 只读(`PUBLIC_READ`)。
- `reviews.rating` / `reviews.rating_count` 是 Shopify 的标准评分元字段(Shopify 搜索、Google 等渠道也读取)。
  应用在安装 / 重新授权时与定时任务中自动启用这两个标准定义(开启 Storefront 只读,幂等,失败会重试),
  **确认启用之后才写入**;未启用期间只写 `customerssay.*` 汇总,不写 `reviews.*`。
  若标准定义此前已由商家或其它应用启用,应用直接沿用、不修改其设置,请在 Shopify 后台确认该定义开启了 Storefront 访问。

```graphql
query ProductRating($handle: String!) {
  product(handle: $handle) {
    rating: metafield(namespace: "reviews", key: "rating") { value }
    ratingCount: metafield(namespace: "reviews", key: "rating_count") { value }
    reviewsSummary: metafield(namespace: "customerssay", key: "reviews_summary") { value }
  }
}
```

建议优先读 `reviews.rating` / `reviews.rating_count`;为 `null`(标准定义尚未启用或商品没有评论)时回落到 `customerssay.reviews_summary`,
仍为 `null` 时按没有评论处理。

### 标准评分元字段未启用(UNSTRUCTURED_ALREADY_EXISTS)
如果店铺的商品上**已有同名但没有定义**的 `reviews.rating` / `reviews.rating_count` 元字段(例如旧版本应用或其它评论应用写过),
Shopify 不允许在其上启用标准定义(返回 `UNSTRUCTURED_ALREADY_EXISTS`),应用会持续只写 `customerssay.*` 汇总,
后台「Headless」页会显示"Shopify standard rating metafields are not enabled"提示。需要商家手动处理:

1. 在 Shopify 后台打开 设置 → 元字段和元对象(Metafields and metaobjects,旧称 Custom data)→ 产品(Products)→
   无定义的元字段(Metafields without a definition);
2. 打开 `reviews.rating`,使用标准定义 Product rating 添加定义;`reviews.rating_count` 同样选择 Product rating count。现有值会保留;
3. 回到应用后台「Headless」页点"重新检查"(Check again)。确认启用后,后续同步即开始写入 `reviews.*`。

## 6. 已验证购买规则(摘要)

详见 `app/lib/verification/verificationPolicy.ts`:
- 私钥 + `X-CustomersSay-Customer-Id`:只认该顾客自己的订单;
- 私钥不带顾客 ID、或公钥提交:不自动判定,可由商家手动标记;
- 邀评邮件托管页(带可信 token):按邮箱判定。


## 6. 商家入口与部署

- 公开接入文档:应用域名下 `/headless/docs`;React 包文档:`/headless/docs/react`,无需后台登录。
- 后台 Headless 页管理密钥、可信 Origin、店面 URL,并展示 Google Shopping feed 地址。feed 的币种和库存状态仍有固定值,上线前必须对照实际目录核验。
- 后台 Manage Reviews 的单条评论菜单提供 Mark as verified purchase / Remove verified purchase。人工标记保留来源;取消会清除来源,email / customer_id 策略后续自动检查可能重新标记,操作提示会说明。
- 评论保存提交时的署名;同邮箱的公开提交不能覆盖已有用户资料。历史评论没有快照时沿用原署名,GDPR 删除同时清除快照。
- 新增迁移 `20261104010000_add_review_submitter_name` 仅增加可空列,不回填历史全表;部署前先应用迁移,再启动新代码。
- 按实际代理拓扑配置 `STOREFRONT_TRUSTED_PROXY_HOPS`,并禁止绕过可信代理直连应用。边缘必须覆盖 X-Real-IP,正确追加 X-Forwarded-For。
- 代理需转发 Content-Length 或先缓冲请求体;不要注入 `Access-Control-Allow-Origin: *`;尊重 Vary 和 Cache-Control: private。
- 部署主题扩展资源时运行 `shopify app deploy`,避免主题资源与 embed.js 版本不一致。React 包仍为仓库内交付,不自动发布 npm。
- 邀评托管页的感谢邮件链接不受 emailLinkMode 控制。