# 队列接口 v1

状态：P1 已实现创建与查询。更新、暂停、实际派发并发与速率控制随 P2–P3 实现；当前参数是后续执行所需的持久化配置。

## POST /v1/queues

需要 queues:manage 和当前命名空间内全部队列范围。鉴权、请求体、幂等键及错误信封与 [任务接口](tasks.md) 一致。

| 字段 | 类型 | 要求 |
| --- | --- | --- |
| name | string | 1–128 字符，以 ASCII 字母/数字开头，其后允许字母、数字、`_ . : -`；命名空间内唯一 |
| max_concurrency | uint32 | 必填，1–100000 |
| rate_per_second | uint32 | 必填，1–1000000 |

```sh
curl "$ORBIT_URL/v1/queues" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: queue-images-v1' \
  --data '{"name":"images","max_concurrency":8,"rate_per_second":100}'
```

首次 201：

```json
{
  "request_id":"44444444444444444444444444444444",
  "data":{
    "deduplicated":false,
    "queue":{
      "id":"11111111111111111111111111111111",
      "namespace_id":"33333333333333333333333333333333",
      "name":"images","paused":false,"max_concurrency":8,"rate_per_second":100,"revision":"1"
    }
  }
}
```

同键同内容返回 200、deduplicated=true。同键不同内容返回 409 IDEMPOTENCY_CONFLICT；换键创建同名队列返回 409 STATE_CONFLICT。创建、幂等记录和管理审计同事务提交。

SDK：`Client.CreateQueue(ctx, key, orbit.CreateQueueRequest{...})`。

## GET /v1/queues/{queue_id}

权限：queues:read 和对应队列范围。200 的 data 直接为上方 queue 对象；资源不存在或单资源范围不匹配返回 404。

```sh
curl "$ORBIT_URL/v1/queues/$ORBIT_QUEUE_ID" -H "Authorization: Bearer $ORBIT_TOKEN"
```

SDK：`Client.GetQueue(ctx, queueID)`。范围限制、重复创建和同名冲突已纳入 [P1 回归](../reports/phase-1.md)。这些配置上限不是生产容量承诺。