角色端点访问
本页记录 POS 工作流程中使用的三个默认角色各自可访问哪些 WCPOS REST 端点：
administratorshop_managercashier
面向用户的角色和能力配置请参阅访问 POS。
摘要
默认访问模型如下：
administrator—— 完整的 POS 和管理访问权限。shop_manager—— 完整的 POS 和管理访问权限，但需要插件安装能力的插件扩展操作除外。cashier—— 正常的 POS 销售工作流程访问权限，但没有管理、设置、日志或店铺管理的访问权限。
端点矩阵由集成测试验证，这些测试使用与 POS 应用相同的身份验证路径（WCPOS 持有者访问令牌，而不仅仅是 wp_set_current_user()）。允许端点的断言确认某个角色不会收到 401 或 403。当测试使用最小化的测试数据时，某些端点仍可能返回正常数据或业务错误，例如 400 或 404——这些响应仍然证明用户已通过身份验证/权限层。
免费插件端点访问矩阵
| 区域 | 端点示例 | Admin | Shop Manager | Cashier | 备注 |
|---|---|---|---|---|---|
| 设置索引 | GET /wcpos/v1/settings | ✅ | ✅ | ✅ | 公开/可读的 POS 设置索引 |
| 店铺 | GET /wcpos/v1/stores | ✅ | ✅ | ✅ | POS 启动数据 |
| 收银员资料 | GET /wcpos/v1/cashier/{id} | ✅ | ✅ | ✅ | 自己的收银员数据 |
| 收银员店铺 | GET /wcpos/v1/cashier/{id}/stores | ✅ | ✅ | ✅ | 当前收银员的店铺访问权限 |
| 产品 | GET /wcpos/v1/products | ✅ | ✅ | ✅ | 目录浏览 |
| 变体 | GET /wcpos/v1/products/variations | ✅ | ✅ | ✅ | 目录浏览 |
| 分类 | GET /wcpos/v1/products/categories | ✅ | ✅ | ✅ | 目录筛选 |
| 标签 | GET /wcpos/v1/products/tags | ✅ | ✅ | ✅ | 目录筛选 |
| 品牌 | GET /wcpos/v1/products/brands | ✅ | ✅ | ✅ | 目录筛选 |
| 优惠券 | GET /wcpos/v1/coupons | ✅ | ✅ | ✅ | POS 优惠券查询 |
| 订单读取 | GET /wcpos/v1/orders | ✅ | ✅ | ✅ | POS 订单历史 |
| 订单创建 | POST /wcpos/v1/orders | ✅ | ✅ | ✅ | 销售工作流程 |
| 订单更新 | PATCH /wcpos/v1/orders/{id} | ✅ | ✅ | ✅ | 完成/更新 POS 订单 |
| 结账读取/创建 | /wcpos/v1/orders/{id}/checkout | ✅ | ✅ | ✅ | 支付流程 |
| 收据 | GET /wcpos/v1/receipts/{order_id} | ✅ | ✅ | ✅ | 收据渲染 |
| 订单状态 | GET /wcpos/v1/data/order_statuses | ✅ | ✅ | ✅ | POS 状态数据 |
| 客户读取 | GET /wcpos/v1/customers | ✅ | ✅ | ✅ | 客户搜索/列表 |
| 客户创建 | POST /wcpos/v1/customers | ✅ | ✅ | ✅ | 在 POS 中创建客户 |
| 客户更新 | PATCH /wcpos/v1/customers/{id} | ✅ | ✅ | ✅ | 在 POS 中编辑客户 |
| 税费 | GET /wcpos/v1/taxes | ✅ | ✅ | ✅ | 结账/税务计算数据 |
| 税类 | GET /wcpos/v1/taxes/classes | ✅ | ✅ | ✅ | 结账/税务计算数据 |
| 配送方式 | GET /wcpos/v1/shipping_methods | ✅ | ✅ | ✅ | 结账/配送数据 |
| 支付网关 | GET /wcpos/v1/payment-gateways | ✅ | ✅ | ✅ | 支付选项 |
| 网关引导 | POST /wcpos/v1/payment-gateways/{id}/bootstrap | ✅ | ✅ | ✅ | 支付设置 |
| 模板 | GET /wcpos/v1/templates | ✅ | ✅ | ✅ | 收据/模板读取 |
| 当前模板 | GET /wcpos/v1/templates/active | ✅ | ✅ | ✅ | 收据/模板读取 |
| 模板库 | GET /wcpos/v1/templates/gallery | ✅ | ✅ | ✅ | 模板读取 |
| 常规设置 | GET /wcpos/v1/settings/general | ✅ | ✅ | ❌ | 仅管理 |
| 结账设置 | GET /wcpos/v1/settings/checkout | ✅ | ✅ | ❌ | 仅管理 |
| 税号设置 | GET /wcpos/v1/settings/tax_ids | ✅ | ✅ | ❌ | 仅管理 |
| 支付网关设置 | GET /wcpos/v1/settings/payment-gateways | ✅ | ✅ | ❌ | 仅管理 |
| 扩展目录/管理 | GET /wcpos/v1/extensions | ✅ | ✅ | ❌ | 仅管理 |
| 日志 | GET /wcpos/v1/logs | ✅ | ✅ | ❌ | 仅管理 |
Pro 插件端点访问矩阵
| 区域 | 端点示例 | Admin | Shop Manager | Cashier | 备注 |
|---|---|---|---|---|---|
| 店铺编辑数据 | GET /wcpos/v1/stores/{id}/edit | ✅ | ✅ | ❌ | 店铺管理 |
| 店铺创建 | POST /wcpos/v1/stores | ✅ | ✅ | ❌ | 店铺管理 |
| 店铺更新 | PATCH /wcpos/v1/stores/{id} | ✅ | ✅ | ❌ | 店铺管理 |
| 许可证设置更新 | POST /wcpos/v1/settings/license | ✅ | ✅ | ❌ | Pro 管理 |
| 扩展操作 | POST /wcpos/v1/extensions/action | ✅ | ❌ | ❌ | 需要插件安装/管理能力 |
| 订单退款 | POST /wcpos/v1/orders/{id}/refunds | ✅ | ✅ | ✅ | 被视为 POS 操作 |
令牌过期覆盖
| 场景 | Admin | Shop Manager | Cashier | 预期结果 |
|---|---|---|---|---|
| 有效的访问令牌 | ✅ 已测试 | ✅ 已测试 | ✅ 已测试 | 允许的端点不返回 401 或 403 |
| 过期的访问令牌 | ✅ 已测试 | ✅ 已测试 | ✅ 已测试 | 请求在 WCPOS 身份验证关卡处失败，用户为 0 |
| 访问令牌过期后使用有效的刷新令牌 | ✅ 已测试 | ✅ 已测试 | ✅ 已测试 | 签发新的访问令牌并恢复访问 |
| 过期的刷新令牌 | ✅ 已测试 | ✅ 已测试 | ✅ 已测试 | 无法铸造新的访问令牌 |
诊断失败
如果默认的 shop_manager 看到类似以下的错误：
Request still unauthorized after token refresh - please log in again
端点矩阵表明这不是因为默认的 shop_manager 角色从根本上缺少 POS 访问权限。需要调查的可能原因：
- 站点特定的角色/能力损坏。
- 矩阵未覆盖的某个端点。
- 客户端中陈旧或过期的访问令牌重试行为。
- 第三方安全或身份验证插件的干扰。
- Pro 或店铺特定的访问规则，或自定义代码。
权限失败 vs. 令牌失败
对于两种情况，POS 前端在收到 401 或 403、尝试刷新令牌、且重试仍未授权后，都可能显示相同的令牌刷新错误。这两种失败模式在服务器端看起来不同：
真正的角色/能力失败通常如下所示：
status: 403
current_user: <actual user id>
access token expired: false
令牌/身份验证失败通常如下所示：
status: 403
current_user: 0
access token expired: true or invalid
在分流 POS 访问问题时使用这一区别——非零的 current_user 指向能力问题，而 current_user: 0 指向身份验证/令牌层。