Headless WooCommerce API（headless-woocommerce-api）
编排指南，用于配置、查询和保护 WooCommerce 后端 API（WPGraphQL 和 REST），以支持解耦的前端应用（Next.js、Remix、移动端）。
前提条件
- 已安装 WordPress 并激活 WooCommerce 插件。
- 可访问的 GraphQL 端点（默认：
https://your-store.com/graphql）。 - 对于深入查询和技术示例，请参考 headless-api-reference.md。
- 对于前端客户端设置，请查看 storefront-client.ts。
分步执行清单
flowchart TD
S1["1. 安装WPGraphQL & WooGraphQL"] --> S2["2. 种子模拟/实时目录数据"]
S2 --> S3["3. 配置认证（JWT / OAuth）"]
S3 --> S4["4. 使用GraphiQL验证Schema"]
S4 --> S5["5. 在Next.js中编写客户端查询"]
阶段 1：后端插件部署
- 安装 WPGraphQL Core：
- 从 WordPress 插件目录安装并激活
wp-graphql。 - 验证端点是否可用：
GET/POST /graphql。
- 从 WordPress 插件目录安装并激活
- 安装 WooGraphQL 扩展：
- 下载并安装 wp-graphql-woocommerce。
- 验证类型（
Product、ProductCategory、Cart、Customer）是否出现在 GraphQL schema 中。
- 种子测试数据：
- 通过
工具 → 导入 → WooCommerce 产品（CSV）使用sample-data/sample_products.csv运行 CSV 导入器。
- 通过
阶段 2：配置无头认证
- 选项 A：JWT 认证（
wp-graphql-jwt-authentication）：- 上传并激活
wp-graphql-jwt-authentication。 - 生成一个 64 字符的密钥（
openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64或 PowerShell 等效命令）。 - 注入到容器（
docker exec -it <container> sed -i ... /var/www/html/wp-config.php），添加到.env（GRAPHQL_JWT_AUTH_SECRET_KEY），或直接添加到wp-config.php：define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'your-strong-random-secret' );
- 上传并激活
- 选项 B：无头登录（
wp-graphql-headless-login）：- 如果需要外部 OAuth 2.0 / 社交登录（Google、GitHub），则使用此选项。
- 通过过滤器或管理员设置配置提供商。
阶段 3：查询商店数据
- 公共目录：使用联合类型片段（
... on SimpleProduct、... on VariableProduct）查询分类和产品。 - 客户会话：在进行购物车变更时捕获
woocommerce-session头，并在后续请求中传递它。 - 受保护的个人资料：传递
Authorization: Bearer <authToken>以获取客户订单和地址更新。
阶段 4：前端集成（Next.js）
- 使用公共 GraphQL 查询为静态产品页面实现 SSG/ISR。
- 在客户端状态（Zustand / LocalStorage）中维护购物车令牌，使 Next.js 页面保持可缓存性。
- 实现原生结账桥接：重定向到 WordPress
/checkout以利用本地支付网关并遵守 e-Namad 合规要求。
边缘情况与已知 AI 陷阱
- 产品查询中的联合类型：WooCommerce 产品是多态的。永远不要直接在
products { nodes { price } }上查询price；你必须使用类型条件（... on SimpleProduct { price }、... on VariableProduct { price }）。 - 缺少会话头：如果服务器返回的
woocommerce-session令牌未由前端客户端存储并重新发送，购物车物品将在下个请求中消失。 - 管理端 React 不兼容：如果使用严格的内核 WordPress 且没有自定义构建步骤，请避免使用具有旧版 Gutenberg 管理捆绑包的插件（如
wp-graphql-headless-login设置面板）；坚持使用常量驱动型插件，如wp-graphql-jwt-authentication。 - CORS 头：确保 WordPress 通过配置头或反向代理允许来自你前端域的请求。
验证与自检
- 对
/graphql执行测试查询，确认productCategories和products返回节点。 - 执行
login变更，确认生成了有效的authToken。 - 确认向购物车添加商品时返回了
woocommerce-session头。