---
title: "スケジュール"
description: "期間に重なるタスク・スプリント・マイルストーンをテナント横断で返す API"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# スケジュール

## 概要

テナントカレンダー（タイムライン）とガントチャートが、1 回の呼び出しで描画に足りるデータを取るための読み取り専用 API である。指定した期間に重なるタスクと、同じ期間に重なるスプリント・マイルストーン、ページ内タスクの担当者をまとめて返す。セッションに限らず PAT・Device Token でも呼べる。開始予定日（`planned_start_on`）は[コア](https://docs.koyori.app/dev/features/tasks/core)、スプリントは[スプリント](https://docs.koyori.app/dev/features/tasks/sprints)の機能に依存する。画面は[画面](#画面)の節に、残工数の積み方は[山積み](https://docs.koyori.app/dev/features/tasks/workload)に書く。

## 振る舞い

### 含める条件

タスクは次の条件で選ぶ。

- アーカイブ済み・削除済みは除く
- 始点 <= `to` かつ 終点 >= `from` のものを返す
- `include_overdue=true` なら、終点 < `from` でも Soft 締切・開始予定日・見積があり未完了のものを足す。これらは山積みの材料になるタスクである

始点と終点は次のとおりに決める。

- 締切は `timezone` で日付に落とす。変換は DB 側の `AT TIME ZONE` で行う
- 始点は `planned_start_on`・Soft 締切の日付・Hard 締切の日付のうち最も早い日、終点は最も遅い日である。1 つしか無ければ両端ともその日になる
- Soft と Hard の両方があれば Hard の日まで含める。Soft ≤ Hard は DB の CHECK が保証する
- `planned_start_on` が締切より後のタスクはコアが許しており、締切の日〜開始予定日として扱う
- 3 つとも無いタスクは含めない

スプリントは `start_date <= to AND end_date >= from`、マイルストーンは `due_date` が `from`〜`to` に入るものを返す。いずれも[認可](#認可)の節の可視プロジェクトに限り、`project_id` を指定したときはその積に限る。`user_id` / `include_done` が絞るのはタスクだけである。

## API

| メソッド | パス | 説明 |
|---|---|---|
| GET | `/v1/tenants/{tenant_id}/schedule` | 期間に重なるタスク・スプリント・マイルストーンと、ページ内タスクの担当者を返す |
| GET | `/v1/tenants/{tenant_id}/schedule/unscheduled` | 日付を一つも持たないタスク（期間なし）の件数と一覧を返す。ガントの「期間なし N 件」に使う |

クエリは次のとおりである。

| クエリ | 内容 |
|---|---|
| `from` / `to` | 必須。日付（`YYYY-MM-DD`）。両端含む。`from > to` または `to - from > 92 日` は 400 |
| `timezone` | IANA 名。既定 `UTC`。100 文字超・Postgres が知らない名前は 400 |
| `project_id` | 繰り返し指定可（`?project_id=a&project_id=b`）。可視プロジェクトとの積。見えない ID は黙って落とす |
| `user_id` | 繰り返し指定可。担当者（`task_assignees.user_id`）のいずれかに当たるタスクに絞る |
| `include_done` | 既定 true。false なら完了ステータス（`is_done_state = true`）のタスクを除く |
| `include_overdue` | 既定 false。true なら締切超過のタスク（Soft 締切・開始予定日・見積があり、終点が `from` より前で未完了のもの）も返す。[山積み](https://docs.koyori.app/dev/features/tasks/workload)で締切超過の残工数を今日に積むために使う |
| `cursor` / `limit` | タスクのページング。`limit` 既定 200、1〜500（範囲外は 400）。壊れたカーソルは 400 |

応答の最上位の項目は次のとおりである。各項目の形は `openapi.json` の `ScheduleResponse` にある。

| 項目 | 内容 |
|---|---|
| `range` | `from` / `to` / `timezone` |
| `tasks` | 期間に重なるタスク。並びは始点 ASC、`id` ASC で固定し、カーソルは `(始点, id)` の keyset である |
| `sprints` | プロジェクト単体の API と同じ形（`SprintResponse`）。ページングせず、全ページに同じものを載せる |
| `milestones` | プロジェクト単体の API と同じ形（`MilestoneResponse`）。ページングせず、全ページに同じものを載せる |
| `members` | そのページの `tasks` の担当者を重複なく集めたもの |
| `next_cursor` | 次ページがあるときだけ入る |

### 期間なしのタスク

`GET /schedule/unscheduled` は、開始予定日・Soft 締切・Hard 締切がどれも無いタスクを返す。
`/schedule` は期間に重なるタスクだけを返すので、日付を持たないタスクはそこに出ない。
削除済み・アーカイブ済みのタスクは返さない。

| クエリ | 内容 |
|---|---|
| `project_id` | `/schedule` と同じ。繰り返し指定可で、可視プロジェクトとの積。見えない ID は黙って落とす |
| `user_id` | `/schedule` と同じ。担当者のいずれかに当たるタスクに絞る |
| `include_done` | 既定 false（`/schedule` と逆）。true なら完了ステータスのタスクも返す |
| `cursor` / `limit` | タスクのページング。`limit` 既定 200、1〜500（範囲外は 400）。壊れたカーソルは 400 |

応答の最上位の項目は次のとおりである。形は `openapi.json` の `UnscheduledResponse` にある。

| 項目 | 内容 |
|---|---|
| `total` | 絞りに合うタスクの件数。全ページの合計で、ページングに関わらず同じ値を返す |
| `tasks` | `/schedule` の `tasks` と同じ形（`ScheduleTask`）。並びは `id` ASC で固定し、カーソルは `id` の keyset である |
| `members` | そのページの `tasks` の担当者を重複なく集めたもの |
| `next_cursor` | 次ページがあるときだけ入る |

`/schedule` との違いは次の三つである。

- `include_done` の既定が逆で、完了したタスクを既定で除く。済んだタスクに日付を入れる手間は要らないためである
- `total` を返す。ガントは件数だけを先に出し、一覧は押したときに開くためである
- 期間が無いので `from` / `to` / `timezone` を取らず、並びとカーソルは `id` だけで決める

`tasks` の項目のうち、形だけでは読めない規則は次のとおりである。

- `project` / `status` / `members` の要素は My Tasks・利用者の要約と同じ型（`MyTaskProjectInfo` / `MyTaskStatusInfo` / `UserSummary`）である
- `logged_minutes` は整数で、そのタスクの作業記録（`time_logs.logged_minutes`）の合計である。担当者以外の記録も含み、記録が無ければ 0 になる
- `logged_minutes` は `GET /tasks/{id}/time-logs/summary` の `actual_minutes` と同じ定義で、SQL 側で集計する。[山積み](https://docs.koyori.app/dev/features/tasks/workload)の残工数に使う
- `assignees.role` は保存されている文字列をそのまま返す。`primary` と `assignee` が混在する

## 認可

| 操作 | 誰が | スコープ |
|---|---|---|
| schedule の取得 | テナントに入れる利用者（`ensure_tenant_access_or_guest_scope`）。テナントに入れないゲストは明示メンバーのプロジェクトだけに絞る | `read:task` |
| schedule の取得 | プロジェクト束縛付き PAT（`allowed_project_ids` あり）は不可で、403 を返す（My Tasks と同じ） | `read:task` があっても通らない |
| 期間なしのタスクの取得 | schedule の取得と同じ（同じ検めと同じ可視プロジェクトの決め方を通る） | `read:task` |

`read:task` はセッション・PAT・Device Token のいずれでも通る。

可視プロジェクトは次のとおりに決める。期間なしのタスクの取得も同じ決め方を使うので、ガントの棒と期間なしの件数で範囲がずれない。

- 候補はテナントの個人プロジェクト以外の全プロジェクトである
- テナントオーナーは候補の全件を見る
- それ以外の利用者は `visible_project_ids` で絞る。メンバー指定のあるプロジェクトは指定された人だけが見る
- 個人プロジェクト（自分の Inbox を含む）のタスクは返さない

## 画面

| 項目 | 値 |
|---|---|
| URL | `/{tenant}/calendar`。詳細は [URL 仕様](https://docs.koyori.app/dev/frontend/url-spec)に書く |
| データ | この API だけから作る。`limit=500` で `next_cursor` を辿って全件を取る |
| ガントチャート | `/{tenant}/gantt` と `/{tenant}/projects/{key}/gantt`。同じ API と期間なしのエンドポイントを使う実験的な画面で、サイドバーの入口は実験的機能の「ガントチャート」（`koyoriArcIntegration`）を有効にしたときだけ出る。構成は[ガントチャート](#ガントチャート)に書く |

### ガントチャート

テナントのガントとプロジェクトのガントは同じ部品（`components/gantt/ScheduleGantt.vue`）で描く。プロジェクトのガントは `project_id` でそのプロジェクトに絞る。図は arc（`@koyori-app/arc-vue`）が描き、行の組み立てと切り替えは task の側が持つ。

| 区画 | 内容 |
|---|---|
| 上の段 | 前・今日・次の送り、日・週・月の目盛り、群れの切り替え（既定はプロジェクト、担当者も選べる）、担当者の絞り、「期間なし N 件」 |
| 凡例 | 一行で、棒・厳守の期限・目安を過ぎた行・今日の線を示す。稲妻線の切り替えもここに置く |
| 左の一覧 | 広い画面（1024px 以上）だけに出す。キー・題・担当・厳守の期限の列で、行の高さは図と同じ。群れの見出しは件数つきで、押すと畳める |
| 図 | 日ごとの数字と曜日、土日の地、今日の線。予定開始から目安の期限までの棒（濃い所が進み）と、厳守の期限の菱形 |

行の表示は次のとおりである。

- 完了の行は完了の色で描く
- 完了していないのに目安の期限を過ぎた行は、赤い縁と「目安 M/D を過ぎた」の字で示す
- 予定開始の無いタスクは、期間の最後の日に点を描く
- 範囲の外へ続く棒には、範囲の端に「← M/D」「→ M/D」を添える

稲妻線（今日の時点の進みを結ぶ線）の既定は切れである。点けた形は URL（`line`）と環境設定（`ganttProgressLine`）に覚え、URL があれば URL が勝つ。
進みのある行は進みの位置へ尖り、0% で予定開始を過ぎた行は予定開始へ尖る。完了・未着手・群れの見出しの行は今日の線のままで、今日が範囲の外なら描かない。

範囲は目盛りごとに決め、予定の API の 92 日の上限に収める。

| 目盛り | 広い画面 | 狭い画面 |
|---|---|---|
| 日 | 3 週 | 1 週 |
| 週 | 8 週 | 4 週 |
| 月 | 13 週 | 9 週 |

日付を持たないタスクは予定の API に出ないので、[期間なしのタスク](#期間なしのタスク)のエンドポイントで引き、「期間なし N 件」に数える。押すと一覧を開き、行を押すとタスクを開く。
期間なしだけが読めない時は、図を出したまま「期間なしを読み込めませんでした（再試行）」を出す。
タスクの更新・完了・削除と SSE の変更通知では、予定と期間なしの両方の query を取り直す。

URL のクエリは [URL 仕様](https://docs.koyori.app/dev/frontend/url-spec)に書く。

### タイムライン

カレンダーは、行がメンバー、横軸が日付の 2 週間のタイムラインである。

- 月曜始まり・土日非稼働・1 日の上限 6 時間・祝日なしで描く
- `timezone` はブラウザのタイムゾーンである。締切の日付への落とし方は[含める条件](#含める条件)と同じである
- 行の見出しは担当者のアバター（`members[].avatar_url`。無ければ頭文字）と名前である。担当者なしの行は人のアイコンにする
- 最上段に期間に重なるスプリントとマイルストーンを出す。マイルストーンは期日にフラグのアイコンを出し、重なるものは段を分ける
- メンバー・プロジェクトの絞り込みはクライアント側で行う。候補は応答の `members` / `tasks[].project` である
- 各メンバー行の最上段に、日ごとの残工数（見積 − 実績）を棒で出し、6 時間を超えた日は「超過」を出す。積む対象・配分・担当者の分け方は[山積みの振る舞い](https://docs.koyori.app/dev/features/tasks/workload#振る舞い)に書く

### 帯

- 始点〜終点（[含める条件](#含める条件)）を帯にする
- 開始予定日が無く、締切が 1 日に収まるタスクは締切の点（菱形）にする
- 範囲外は端で切り詰めて矢印アイコンを出す
- 主担当（`role = primary`）は塗り、それ以外は薄い枠線である
- 完了はグレー、Soft 締切を過ぎた未完了は警告色で描く
- 帯のクリックで、タスク一覧の List 表示と同じ詳細のオーバーレイを開く。子タスク・説明の `KEY-N` もオーバーレイ内で開き、閉じると元のタスクへ戻る
- 狭い画面（`1024px` 未満）と修飾キー付きのクリックは詳細ページへ移動する

### 開始予定日の入力

開始予定日はタスク作成ダイアログと詳細で入力するほか、カレンダーの帯をドラッグ・キーボードで動かして変える。帯の操作は[山積みの手動の山崩し](https://docs.koyori.app/dev/features/tasks/workload#手動の山崩し)に書く。Soft 締切より後の日付は送らずに警告する。サーバーは前後関係を検証しない。

## 未実装と既知の制限

- CLI に schedule 専用のコマンドが無い
- カレンダーの週ビュー・月ビューが無い
- 月曜始まり・土日非稼働・1 日の上限 6 時間・祝日なしは MVP の固定値で、変えられない

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-10-16 | 期間の上限は 92 日（約 3 か月）とする | タイムライン 1 画面ぶんに収め、1 回の問い合わせを有界にする |
| 2026-10-16 | 期間判定とタイムゾーン変換は SQL 側で行い、Rust 側で全件を取って絞らない | 旧版の決定事項に理由の記載が無い |
| 2026-10-16 | ページングはタスクだけにする。スプリント・マイルストーン・担当者は毎ページに載せる | スプリント・マイルストーン・担当者は期間あたりの件数が小さい。毎ページに載せると、クライアントがページを継いでも描画に要る周辺データが揃う |
| 2026-10-16 | `read:task` だけでスプリント・マイルストーンも返す。プロジェクト単体の API の `read:sprint` / `read:milestone` は変えない | タスクの文脈（属するスプリント・期日）として表示するため |
| 2026-10-16 | 個人プロジェクトはテナントの共有カレンダーに混ぜない | 自分の Inbox は My Tasks で見る |
| 2026-10-16 | テナントオーナーは全プロジェクトを見る | dashboard・プロジェクト一覧と同じ扱いに揃える |
| 2026-10-16 | 担当者の `role` の正規化（`primary` / `assignee` の混在）はこの API ではやらない | 旧版の決定事項に理由の記載が無い |
| 2026-11-03 | タスクの範囲は Hard 締切まで含める | Soft を優先すると、Hard だけが期間に入るタスクがカレンダーに出ない |
| 2026-11-08 | 日付を持たないタスクは `/schedule` に混ぜず、`/schedule/unscheduled` で別に返す。完了は既定で除く | `/schedule` は期間に重なるタスクを返す口で、期間の無いタスクを混ぜると並びとカーソルの決まりが崩れる。済んだタスクに日付を入れる手間は要らない |

Source: https://docs.koyori.app/dev/features/tasks/schedule/index.mdx
