管理自己的卡组

本页接口都要求 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.kardsdecker.com/api/v1 下。

创建卡组

curl -X POST \
  "https://1939.kardsdecker.com/api/v1/users/<user_id>/decks" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "deck_code": "%%...",
    "guide": {
      "system": "装甲控制",
      "description": "卡组说明"
    },
    "archive": {
      "key_components": {
        "enabled": true,
        "items": [
          { "card_id": "<deck_card_id>", "reason": "这张牌在卡组中的关键作用" }
        ]
      },
      "alternatives": {
        "enabled": true,
        "items": [
          { "card_id": "<optional_card_id>", "reason": "针对当前环境可选带入" }
        ]
      }
    },
    "tags": ["天梯"],
    "visibility": "private"
  }'

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

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

攻略与档案字段

guide 保存卡组攻略，archive 保存必备组件、备卡等档案展示设置。需要引用卡牌时使用 GET /api/v1/cards 返回的 card_id：

字段	写入规则
guide.system	必填，最多 40 字符
guide.core_cards	最多 30 个唯一 card_id，不得是衍生卡，且必须属于主卡组
guide.reserve_recommendations	已废弃的 v1 兼容字段；最多 30 个已知非衍生 card_id，不与 archive.alternatives 自动同步；新客户端不要使用
archive.key_components.enabled	是否启用必备组件（必备卡）板块；启用时必须至少有 1 项
archive.key_components.items	至多 8 项；每项 card_id 必须是当前卡组中的非衍生卡；启用板块时每项 reason 必填且去除首尾空白后不得为空
archive.alternatives.enabled	是否启用备选卡牌（备卡）板块；启用时必须至少有 1 项
archive.alternatives.items	至多 10 项；备卡不必属于当前卡组，但必须是可供主阵营或盟军阵营使用的已知非总部、非衍生卡；启用板块时每项 reason 必填且不得为空
archive.chart_settings.otkConfig.items	网站 OTK 概率图表配置；每项可用至多 39 个当前卡组内的 card_ids 表示“这些卡任取其一”的 OR 卡池，并用 required 表示至少摸到的数量
featured_card_id	必须属于主卡组，写在请求正文顶层
card_back_id	卡背资源 ID，写在请求正文顶层；它只控制卡背展示

写入 archive 时，各子板块必须是对象；不要用 null 清空。新记录未提交备卡时，数据库通常返回 {"enabled":false,"items":[]}；旧记录或显式空值也可能返回 null，客户端应兼容两者。要停用必备组件或备卡板块，请为相应字段提交 {"enabled":false,"items":[]}。

读取单个卡组时，攻略字段位于 data.guide，必备组件与备卡分别位于 data.archive.key_components 和 data.archive.alternatives，展示卡和卡背位于 data.display。完整字段表见卡组字段。

先校验再保存

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

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

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

更新卡组

curl -X PATCH \
  "https://1939.kardsdecker.com/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。
• 提交新的 deck_code 时，服务端会针对新卡组重新校验已有档案。必备组件、平替原卡和图表组件仍须位于新卡组；备卡不必位于新卡组，但必须继续符合新卡组的主阵营或盟军阵营范围。若不再符合，请在同一请求中提交修正后的 archive。
• 一旦提交 guide，它会替换整份攻略对象，不会逐字段深度合并。更新其中任意字段前应先读取旧值，再回传完整 guide。

替换卡牌并生成代码

curl -X POST \
  "https://1939.kardsdecker.com/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.kardsdecker.com/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。