# 角色端点访问

本页记录 POS 工作流程中使用的三个默认角色各自可访问哪些 WCPOS REST 端点：

* `administrator`
* `shop_manager`
* `cashier`

面向用户的角色和能力配置请参阅[访问 POS](/zh-CN/settings/wp-admin/access.md)。

## 摘要[​](#summary "直接链接到 摘要")

默认访问模型如下：

* **`administrator`** —— 完整的 POS 和管理访问权限。
* **`shop_manager`** —— 完整的 POS 和管理访问权限，但需要插件安装能力的插件扩展操作除外。
* **`cashier`** —— 正常的 POS 销售工作流程访问权限，但没有管理、设置、日志或店铺管理的访问权限。

端点矩阵由集成测试验证，这些测试使用与 POS 应用相同的身份验证路径（WCPOS 持有者访问令牌，而不仅仅是 `wp_set_current_user()`）。允许端点的断言确认某个角色不会收到 `401` 或 `403`。当测试使用最小化的测试数据时，某些端点仍可能返回正常数据或业务错误，例如 `400` 或 `404`——这些响应仍然证明用户已通过身份验证/权限层。

## 免费插件端点访问矩阵[​](#free-plugin-endpoint-access-matrix "直接链接到 免费插件端点访问矩阵")

| 区域          | 端点示例                                         | 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 插件端点访问矩阵[​](#pro-plugin-endpoint-access-matrix "直接链接到 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 操作       |

## 令牌过期覆盖[​](#token-expiry-coverage "直接链接到 令牌过期覆盖")

| 场景                             | Admin     | Shop Manager | Cashier   | 预期结果                                    |
| -------------------------------- | --------- | ------------ | --------- | ------------------------------------------- |
| 有效的访问令牌                   | ✅ 已测试 | ✅ 已测试    | ✅ 已测试 | 允许的端点不返回 `401` 或 `403`             |
| 过期的访问令牌                   | ✅ 已测试 | ✅ 已测试    | ✅ 已测试 | 请求在 WCPOS 身份验证关卡处失败，用户为 `0` |
| 访问令牌过期后使用有效的刷新令牌 | ✅ 已测试 | ✅ 已测试    | ✅ 已测试 | 签发新的访问令牌并恢复访问                  |
| 过期的刷新令牌                   | ✅ 已测试 | ✅ 已测试    | ✅ 已测试 | 无法铸造新的访问令牌                        |

## 诊断失败[​](#diagnosing-failures "直接链接到 诊断失败")

如果默认的 `shop_manager` 看到类似以下的错误：

> Request still unauthorized after token refresh - please log in again

端点矩阵表明这**不是**因为默认的 `shop_manager` 角色从根本上缺少 POS 访问权限。需要调查的可能原因：

1. 站点特定的角色/能力损坏。
2. 矩阵未覆盖的某个端点。
3. 客户端中陈旧或过期的访问令牌重试行为。
4. 第三方安全或身份验证插件的干扰。
5. Pro 或店铺特定的访问规则，或自定义代码。

### 权限失败 vs. 令牌失败[​](#permission-failure-vs-token-failure "直接链接到 权限失败 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` 指向身份验证/令牌层。