概要
テナントカレンダー(タイムライン)とガントチャートが、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 は期間に重なるタスクを返す口で、期間の無いタスクを混ぜると並びとカーソルの決まりが崩れる。済んだタスクに日付を入れる手間は要らない |
