レポートテンプレート

レポートテンプレート（report template） は表示フォーマットです。ワークスペース・プロジェクト・ユーザー・期間のいずれにも結び付かない Liquid ドキュメントです。レポートは、レンダリング時に任意のテンプレートと任意のスコープ・日付範囲を自由に組み合わせます。テンプレートはインスタンススコープで、すべての認証済みユーザーがレポート作成のために読み取れますが、作成・編集・無効化・削除は制限されています。

権限

テンプレートの読み取りには read スコープと認証済みセッションがあれば十分です。管理操作 — POST、PATCH、 PATCH …/state、DELETE — には、インスタンス管理者 または template-author 権限を持つユーザー（user.canManageTemplates）が必要で、ワークスペースロールではありません。

テンプレートオブジェクト

フィールド	型	説明
`id`	string	一意の識別子。
`name`	string	表示名（1〜100 文字）。
`description`	string \| null	任意の説明（1000 文字以下）。
`body`	string	Liquid のテンプレート本文（1〜50000 文字）。
`enabled`	boolean	新規/編集レポートの土台にできるか。無効なテンプレートはレポートのタブから隠されます。
`isDefault`	boolean	インスタンスの既定かどうか — 作成フォームが最初に選ぶテンプレート。常にちょうど 1 つが持ちます。
`nameTemplate`	string \| null	新規レポートの初期名を生成する Liquid（プレビューの `suggestedName`）。
`noteTemplate`	string \| null	新規レポートの初期ノートを生成する Liquid（`suggestedNote`）。
`defaultDateRange`	string \| null	新規レポートが始まる期間（`today`・`yesterday`・`this_week`・`last_week`・`this_month`・`last_month`）。`null` の場合は今日にフォールバック。
`createdBy`	string \| null	作成したユーザー。遅延シードされたスターターテンプレートは `null`。
`createdAt`	string \| null	ISO 8601 の作成時刻。
`updatedAt`	string \| null	ISO 8601 の最終更新時刻。

テンプレートの一覧

GET /api/v1/report-templates scope: read

すべてのテンプレートを返します。インスタンスにテンプレートが 1 つもない場合（新規またはアップグレード後のインスタンス）、スターターカタログ（日報・週報・月報。@spantail/templates から、リクエストの Accept-Language で）が遅延シードされ、レポートを常に構成可能にします。日報がインスタンスの既定になります。シードは冪等（固定 ID + 不在時のみ挿入）なので、同時の初回読み取りはテンプレートごとに 1 行へ収束します。

curl
Response

curl "https://<your-instance>/api/v1/report-templates" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

[
  {
    "id": "tpl_weekly",
    "name": "Weekly summary",
    "description": "Totals and per-project breakdown for a week.",
    "body": "# {{ report.name }}\n\n...",
    "enabled": true,
    "createdBy": "usr_ana",
    "createdAt": "2026-06-01T08:00:00.000Z",
    "updatedAt": "2026-06-01T08:00:00.000Z"
  }
]

テンプレートの作成

POST /api/v1/report-templates scope: write

インスタンス管理者または template-author 権限が必要です。作成されたテンプレートは有効状態です。

リクエストボディ

フィールド	型	必須	説明
`name`	string	はい	表示名（1〜100 文字）。
`body`	string	はい	Liquid のテンプレート本文（1〜50000 文字）。
`description`	string	いいえ	任意の説明（1000 文字以下）。
`nameTemplate`	string	いいえ	新規レポートの初期名を生成する Liquid。
`noteTemplate`	string	いいえ	新規レポートの初期ノートを生成する Liquid。
`defaultDateRange`	string	いいえ	新規レポートの既定の期間（`today`・`yesterday`・`this_week`・`last_week`・`this_month`・`last_month`）。

curl
Response

curl -X POST "https://<your-instance>/api/v1/report-templates" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly summary",
    "description": "Totals and per-project breakdown for a week.",
    "body": "# {{ report.name }}\n\nTotal: {{ period.from }} – {{ period.to }}"
  }'

{
  "id": "tpl_weekly",
  "name": "Weekly summary",
  "description": "Totals and per-project breakdown for a week.",
  "body": "# {{ report.name }}\n\nTotal: {{ period.from }} – {{ period.to }}",
  "enabled": true,
  "createdBy": "usr_ana",
  "createdAt": "2026-06-01T08:00:00.000Z",
  "updatedAt": "2026-06-01T08:00:00.000Z"
}

201 Created を返します。

テンプレートの取得

GET /api/v1/report-templates/:id scope: read

単一のテンプレートを返します。不明な ID は 404 を返します。

テンプレートの更新

PATCH /api/v1/report-templates/:id scope: write

インスタンス管理者または template-author 権限が必要です。ボディの各フィールドは任意で、変更分だけを送ります。有効/無効の切り替えは代わりにテンプレート状態の設定を使います。

リクエストボディ

フィールド	型	必須	説明
`name`	string	いいえ	表示名（1〜100 文字）。
`description`	string \| null	いいえ	説明（1000 文字以下）。`null` でクリア。
`body`	string	いいえ	Liquid のテンプレート本文（1〜50000 文字）。
`nameTemplate`	string \| null	いいえ	新規レポートの初期名の Liquid。`null` でクリア。
`noteTemplate`	string \| null	いいえ	新規レポートの初期ノートの Liquid。`null` でクリア。
`defaultDateRange`	string \| null	いいえ	既定の期間。`null` で今日にフォールバック。

curl -X PATCH "https://<your-instance>/api/v1/report-templates/tpl_weekly" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Weekly totals, per project and per person." }'

テンプレート状態の設定

PATCH /api/v1/report-templates/:id/state scope: write

インスタンス管理者または template-author 権限が必要です。本文の編集とは別に、テンプレートを有効/無効にします。無効化（アーカイブ）したテンプレートは新規/編集レポートの土台にできなくなりますが、既存のレポートは引き続き閲覧・共有できます。フラグを持っている間はインスタンスの既定を無効化できません — 409 conflict を返します。先に別のテンプレートを既定に設定してください。

リクエストボディ

フィールド	型	必須	説明
`enabled`	boolean	はい	有効化は `true`、無効化は `false`。

curl -X PATCH "https://<your-instance>/api/v1/report-templates/tpl_weekly/state" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

既定に設定

PATCH /api/v1/report-templates/:id/default scope: write

インスタンス管理者または template-author 権限が必要です。このテンプレートをインスタンスの唯一の既定（作成フォームが最初に選ぶもの）にし、それまで持っていたテンプレートのフラグを外します。無効なテンプレートは既定にできません（409 conflict）。更新後のテンプレートを返します。

curl -X PATCH "https://<your-instance>/api/v1/report-templates/tpl_weekly/default" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

テンプレートの削除

DELETE /api/v1/report-templates/:id scope: write

インスタンス管理者または template-author 権限が必要です。409 conflict を返すガードが 2 つあります。保存済みレポートから参照されているテンプレートは削除できません（代わりに無効化してください）。また、フラグを持っている間はインスタンスの既定を削除できません（先に別のテンプレートを既定に設定してください）。成功時は 204 No Content を返します。