# 内容 QA：一次检查 JSON-LD、FAQ 和 raw-md


# 内容 QA：一次检查 JSON-LD、FAQ 和 raw-md

## 这篇帮你解决什么

发布前你不知道内容对不对：JSON-LD 有没有缺字段、FAQ 和页面是不是对得上、raw-md 能不能被 AI 读到。
内容 QA 就是发布前的"体检"：**同一份内容，三个视图一起对**。

## 三步跑一次

1. 打开「内容 QA」，选类型（商品 / 页面 / 集合 / 文章）。
2. 填页面路径（如 `/products/xxx`），点「运行」。
3. 看结果：PASS / WARN / FAIL，每条都带原因和证据位置。

## 结果怎么读

- **PASS**：三个视图一致，可以发布；
- **WARN**：有风险（如 raw-md 未部署），不阻断；
- **FAIL**：有硬错误（如 JSON-LD 缺 Product），先修再发。

> 我们不把"没测到"算成"通过"：未测量会明确标出来。

**想深入规则？** 看高手版：[[content-qa.expert]]


---


# 内容 QA（高手版）：校验规则、模板差异与自动化

## 第一章：校验规则与模板差异

### 1.1 三个视图

| 视图 | 来源 | 校验重点 |
|---|---|---|
| 页面 DOM | 真实渲染 | FAQ 数量/锚点、可见文本 |
| JSON-LD | 页面 `<script type=ld+json>` | Product/Offer 必填、FAQPage mainEntity、@id/url |
| raw-md | `?view=raw-md` | 与页面同锚点、价格/规格一致、无空值 |

### 1.2 模板感知

- product：要求 `Product` + `Offer`（价格/币种/库存）；
- page/collection/article：要求页面类型 Schema（`FAQPage` / `CollectionPage` / `Article` / `Organization`），不再套用商品规则；
- raw-md 缺失 → `RAWMD_FETCH_UNAVAILABLE`（未测量，不伪造 PASS）。

### 1.3 结果模型

`PASS / WARN / FAIL` + `reasons[]` + `evidence`（字段位置/原文片段/hash）。同一输入两次运行结果应可复现（时间戳/版本除外）。

## 第二章：自动化与排障

### 2.1 API

- 单条：`POST /api/v1/content-qa/run`（`type` + `path`）
- 批量：`content-qa/batches`（按类型枚举，入队）
- 结果落 `content_qa_runs`（`mode` / `target_type`）

### 2.2 常见 FAIL

| 原因 | 处理 |
|---|---|
| `JSONLD_PRODUCT_REQUIRED` | 补 Product/Offer，或检查主题是否移除 JSON-LD |
| FAQ 数不一致 | 页面 FAQ 数 = raw-md Q 数 = JSON-LD mainEntity 数 |
| raw-md 空值 | 检查 `custom.specs` / variant 数据源 |
| 整页主题 HTML | raw-md 模板未部署或返回回退 HTML |

### 2.3 与交付流程的关系

内容 QA 是交付 DAG 的**前置闸门**：FAIL 阻断发布；WARN 需人工确认；PASS 才允许进入审批/发布/读回/回滚。

**回新手版：** [[content-qa.novice]]