Skip to content

スケジュール

期間に重なるタスク・スプリント・マイルストーンをテナント横断で返す API

概要

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

振る舞い

含める条件

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

  • アーカイブ済み・削除済みは除く
  • 始点 <= 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 より前で未完了のもの)も返す。山積みで締切超過の残工数を今日に積むために使う
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 側で集計する。山積みの残工数に使う
  • 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 仕様に書く
データ この 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 仕様に書く。

タイムライン

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

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

帯

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

開始予定日の入力

開始予定日はタスク作成ダイアログと詳細で入力するほか、カレンダーの帯をドラッグ・キーボードで動かして変える。帯の操作は山積みの手動の山崩しに書く。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 は期間に重なるタスクを返す口で、期間の無いタスクを混ぜると並びとカーソルの決まりが崩れる。済んだタスクに日付を入れる手間は要らない

Type to search…

↑↓ navigate↵ selectEsc close