管理自己的卡组

本页接口都要求 Bearer API Key，并且路径中的 user_id 必须是 Key 所属账号的 UUID。

权限与端点

方法与路径	Scope	作用
GET /users/:user_id/decks	decks:read	列出自己的卡组
GET /users/:user_id/decks/:deck_id	decks:read	读取单个卡组
POST /users/:user_id/decks	decks:write	创建卡组
PATCH /users/:user_id/decks/:deck_id	decks:write	更新卡组
POST /users/:user_id/decks/validate	decks:write	校验但不保存
POST /users/:user_id/decks/replace	decks:write	替换卡牌并生成新代码
DELETE /users/:user_id/decks/:deck_id	decks:delete	删除卡组

表中路径都位于 https://1939.giaory.xyz/api/v1 下。

创建卡组

curl -X POST \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "deck_code": "%%...",
    "guide": {
      "system": "装甲控制",
      "description": "卡组说明",
      "reserve_recommendations": ["<card_id>"]
    },
    "tags": ["天梯"],
    "visibility": "private"
  }'

创建成功返回 201。deck_code 和 guide.system 必填；visibility 默认是 private，可取 public、private 或 unlisted。

服务端会解析卡组代码，并重新生成 name、阵营和 cards_snapshot。不要尝试直接提交这些派生字段。

先校验再保存

将与创建相同的正文发送到：

POST /api/v1/users/:user_id/decks/validate

响应会返回规范化后的卡组、攻略、档案和可见性，但不会写入数据库。这适合在编辑器保存前显示精确错误。

更新卡组

curl -X PATCH \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks/<deck_id>" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "visibility": "public",
    "tags": ["天梯", "控制"]
  }'

可以更新 deck_code、guide、archive、tags、visibility、featured_card_id 和 card_back_id。至少提供一个字段。

两个更新语义

• 提交新的 deck_code 时，如果当前卡组没有可用攻略，必须同时提交 guide。
• 一旦提交 guide，它会替换整份攻略对象，不会逐字段深度合并。更新备卡前应先读取旧值，再回传完整 guide。

替换卡牌并生成代码

curl -X POST \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks/replace" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "deck_code": "%%...",
    "replacements": [
      {
        "remove_card_id": "<旧-card_id>",
        "add_card_id": "<新-card_id>",
        "count": 1
      }
    ]
  }'

一次请求允许 1 至 20 项替换，每项 count 为 1 至 4。服务端会再次校验 39 张卡、盟军上限和稀有度副本限制。

删除卡组

删除请求需要一个空 JSON 对象作为正文：

curl -X DELETE \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks/<deck_id>" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{}'

成功响应的 data.deleted 为 true。删除不可由读取或写入 Scope 代替，必须显式拥有 decks:delete。