日志

日志（Logbook）

目录

• 日志与台站位置
• 端点
• 日志对象
• 列出日志
• 创建日志
• 更新日志
• 删除日志
• 集体台令牌
• 错误

Logbook 资源管理你的日志——它们是把台站位置归组在一起的容器。一个日志决定哪些位置作为一个日志显示：仪表盘、日志视图、奖项和统计都跟随当前活动的日志。

• 基础路径： /api/v2/logbook
• 作用域： logbook:read、logbook:write、logbook:delete
• 起始版本： 3.2.0

所有操作都限定在令牌所有者范围内。属于其他用户的日志会被视为未找到。

注意

请先阅读 API v2 概览，了解认证、响应封装与 错误码。

日志与台站位置

两者容易混淆，因此值得明确说明：

• 台站位置是记录 QSO 所针对的对象——呼号、网格、DXCC。QSO 属于它。
• 一个日志完全不拥有任何 QSO。它是一组具名的台站位置，存在的目的是让你能把其中几个（家中、便携、比赛呼号……）作为一个日志来查看——或者把它们分开。

因此，删除日志永远不会影响 QSO；而删除台站位置则会影响。

端点

列表端点不分页——用户通常只有少数几个日志。

日志对象

{
  "id": 3,
  "name": "Contest",
  "active": true,
  "station_ids": [1, 4]
}

active 是只读的，并且有自己专用于写入的对应键 set_active。两者故意使用不同的键，因此 GET 的结果可以直接通过 PATCH 回传，而不会悄悄改变你的活动日志。

列出日志

GET /api/v2/logbook

curl https://<WAVELOG_URL>/index.php/api/v2/logbook \
     -H "Authorization: Bearer wl2_your_token_here"

{
  "data": [
    { "id": 1, "name": "Home", "active": false, "station_ids": [1] },
    { "id": 3, "name": "Contest", "active": true, "station_ids": [1, 4] }
  ]
}

单个日志可通过 GET /api/v2/logbook/{id} 获取，返回相同的对象。

创建日志

POST /api/v2/logbook

必填字段： name。station_ids 是可选的——省略它即可创建一个空日志，之后再关联位置。

curl -X POST https://<WAVELOG_URL>/index.php/api/v2/logbook \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Portable", "station_ids": [4] }'

• 你的第一个日志会自动成为活动日志。
• 成功时，API 返回 201 Created、一个 Location 响应头，并在 data 中返回创建的对象。
• 使用已存在的名称会返回 409 conflict。
• 若 station_ids 中的条目不属你的台站位置，会返回 403 forbidden，并在 details.station_ids 中给出有问题的 id。他人的 id 会被拒绝，绝不会被悄悄丢弃。

更新日志

PATCH /api/v2/logbook/{id}——部分更新。请至少发送三个可写字段中的一个；若请求体不包含其中任何一个，会返回 400 validation_error。

curl -X PATCH https://<WAVELOG_URL>/index.php/api/v2/logbook/3 \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Contest 2026", "set_active": true }'

更新后的日志对象会在 data 中返回。

警告：station_ids 会替换整个列表

它不是「添加这些位置」的调用：你发送的列表就是最终存储的列表。 发送 [] 会解除所有位置的关联，而添加一个位置意味着发送该日志 已有的 id 再加上新的 id。请从 GET 取得 station_ids，修改后再 发回。

所有内容都会在首次写入之前完成校验，因此被拒绝的 PATCH 绝不会让日志处于半更新状态——一个错误的 station_ids 条目不会让你本不打算保留的重命名生效。

删除日志

DELETE /api/v2/logbook/{id}

curl -X DELETE https://<WAVELOG_URL>/index.php/api/v2/logbook/3 \
     -H "Authorization: Bearer wl2_your_token_here"

• 活动日志无法删除，会返回 409 conflict。请先通过 PATCH 上的 set_active 激活另一个日志。
• 成功时，API 返回 204 No Content。
• QSO 不会受到影响。 它们属于台站位置，而这些位置仍然存在——只是归组关系消失了。

集体台令牌

对于集体台令牌，本资源的每个动词——包括读取——都需要权限级别 9（干事）：

这与 Web 界面一致：整个日志管理页面仅限干事访问——低于该级别的成员在其中无法管理任何集体台日志，通过 API 同样无法管理。拒绝时返回 403 insufficient_club_permission，并带有 details.required_level。

在低于干事级别的集体台会话中创建令牌时，甚至不会提供 logbook:* 作用域——只能永远返回 403 的令牌不值得签发。

错误