---
title: "山積み・手動の山崩し"
description: "メンバーごと・日ごとの残工数を棒で出し、カレンダー上で開始予定日を動かして山を崩す"
---

> 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.

# 山積み・手動の山崩し

## 概要

テナントカレンダーに、メンバーごと・日ごとの作業量を棒（山）で出す機能である。積む量は見積ではなく残工数（見積 − 実績）で、複数の担当者がいるタスクは担当者で分ける。カレンダー上で帯の始点を動かして開始予定日を変えられるので、山を見ながら手で崩せる。[スケジュール](https://docs.koyori.app/dev/features/tasks/schedule)の schedule API とカレンダー画面、[コア](https://docs.koyori.app/dev/features/tasks/core)の `planned_start_on` / `estimated_minutes`、[作業時間追跡](https://docs.koyori.app/dev/features/tasks/time-tracking)の `time_logs` の上に作る。範囲外のものは[未実装と既知の制限](#未実装と既知の制限)の節に書く。

## 用語

| 語 | 意味 |
|---|---|
| 山積み | メンバーごと・日ごとに積んだ作業時間の棒 |
| 残工数 | `max(estimated_minutes − logged_minutes, 0)`。タスク単位 |
| 配分期間 | 残工数を均等に割って積む平日の集合。決め方は[配分期間](#配分期間)の小節に書く |
| 上限 | 1 日に積める時間。固定 6 時間 |
| 超過 | ある日の山が上限を超えた状態 |
| 山崩し | 開始予定日を変えて山の形を変える操作 |

## 振る舞い

計算はすべてクライアント側（`lib/calendar/load.ts`）で行う。サーバーは [API](#api) の節の 1 項目と 1 引数で材料を渡すだけである。

### 積む対象

次をすべて満たすタスクを積む。

- アーカイブ済み・削除済みでない（schedule API が返すもの）
- 完了ステータス（`is_done_state = true`）でない
- `planned_start_on` がある
- Soft 締切がある。Hard 締切だけのタスクは積まない
- `estimated_minutes` があり、残工数が 1 分以上

### 配分期間

配分期間は次の式で決める。

```text
始点 = max(今日, min(planned_start_on, Soft 締切の日付))
終点 = max(planned_start_on, Soft 締切の日付)
配分期間 = 始点〜終点（両端含む）の平日
```

- 今日より前の日には積まない
- 「今日」は表示タイムゾーン（ブラウザ）での日付である。Soft 締切の日付への落とし方は[スケジュールの含める条件](https://docs.koyori.app/dev/features/tasks/schedule#含める条件)と同じである
- 配分期間が空のときは 1 日に全部積む。締切を過ぎているなら今日に積む
- 始点〜終点が土日だけなら、その直前の平日に全部積む。直前の平日が今日より前なら今日に積む
- 開始予定日が締切より後のタスクは、[スケジュールの含める条件](https://docs.koyori.app/dev/features/tasks/schedule#含める条件)と同じく両端を入れ替えて扱う

### 担当者ごと・日ごとの時間

1 人が 1 日に受け持つ時間は次の式で決める。

```text
1 日あたり = 残工数 / 60 ÷ 配分期間の日数
1 人あたり = 1 日あたり ÷ 担当者数
```

- 担当者数は `task_assignees` の件数である。`role` は見ず、`primary` と `assignee` を区別しない
- 担当者がいないタスクは積まない。「担当者なし」行に山は出さない

### 超過

メンバーの 1 日の合計が上限（6 時間）を超えた日を超過とする。ちょうど 6 時間は超過でない。

## API

専用のエンドポイントは無い。既存のエンドポイントを次のように使う。

| メソッド | パス | 説明 |
|---|---|---|
| GET | `/v1/tenants/{tenant_id}/schedule` | 山の材料を取る。山積みのためにある項目は `tasks[].logged_minutes`、クエリは `include_overdue` である |
| PUT | `/v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}` | 山崩しの確定。`planned_start_on` だけを載せて送る |

`logged_minutes` と `include_overdue` は `handler::handlers::schedule` にあり、`openapi.json` にも反映している。項目の定義は[スケジュールの API](https://docs.koyori.app/dev/features/tasks/schedule#api)に書く。

`logged_minutes` の規則は次のとおりである。

- 集計は SQL 側の相関サブクエリで行う。Rust 側で `time_logs` を全件取って足さない
- 定義は `GET /tasks/{id}/time-logs/summary` の `actual_minutes` と同じで、乖離させない
- `ScheduleTask` は CLI が読むので `Deserialize` を維持する

`include_overdue` の規則は次のとおりである。

- `include_overdue` により期間外から追加する対象は、Soft 締切・開始予定日・見積があり未完了のタスクに限る。期間に重なるタスクはこの条件に関わらず通常どおり返す
- [積む対象](#積む対象)のうち残工数と担当者は、追加する対象を選ぶときにも見ない
- 表示期間より前に締切を過ぎたタスクは期間判定で返らないので、このクエリが無いと「今日に全部積む」の材料が揃わない
- 画面は表示期間が今日を含むときにだけ `include_overdue=true` を付ける
- 締切超過のタスクは期間外なので帯には出ず、山（今日の棒）にだけ積む。期間外のタスクのうち山に積めないものは、画面が受け取った後で捨てる

## 認可

| 操作 | 誰が | スコープ |
|---|---|---|
| schedule API の取得 | [スケジュールの認可](https://docs.koyori.app/dev/features/tasks/schedule#認可)と同じ | `read:task` |
| 山崩しの更新 | タスク更新と同じ。プロジェクトの書き込み権限が要る | `write:task` |

カレンダーに見えていても更新できないタスクはある。その場合の 403 は画面で処理する（[失敗時](#失敗時)の小節）。

## 画面

| 項目 | 値 |
|---|---|
| URL | `/{tenant}/calendar` |

### 山の表示

- 各メンバー行の最上段に、棒と数字を出す。棒の高さは上限 6 時間を段の高さとする比率である。超過分は上限の線を越えて描き、警告色にする
- 棒にマウスを乗せると、その日のタスク内訳（`KEY-N`、1 人あたりの時間）を出す
- 読み上げ文言は `2026-10-14 の残り 7h（上限 6h を超過）` の形である
- 「担当者なし」行には棒を出さない
- メンバー・プロジェクトの絞り込みはクライアント側で行う。絞り込んでも、山は絞り込み前の全タスクで計算する

### 手動の山崩し

- 帯（開始予定日のあるタスク）を横にドラッグすると、始点だけが日単位で動く。終点は締切なので動かない
- タッチの横スワイプはスクロールに使うので、タッチではキーボード操作かタスク詳細で変える
- キーボードでは、帯にフォーカスして `←` / `→` で 1 日ずつ動かし、`Enter` で確定、`Esc` で取消する
- ドラッグ中は山をローカルで再計算して追従させる。確定前に結果が見える
- 確定時に `planned_start_on` だけを送る。成功したら schedule のクエリを無効化して再取得する
- 新しい開始予定日が Soft 締切の日付より後になる位置へは置けず、タスク作成ダイアログと同じ警告を出す。サーバーは検証しないので画面で止める
- Soft 締切の日付への落とし方は、帯の終点と同じく[スケジュールの含める条件](https://docs.koyori.app/dev/features/tasks/schedule#含める条件)（表示タイムゾーン）に従う
- 開始予定日の無いタスク（締切の点と Soft〜Hard の帯）は動かせない。開始予定日の設定はタスク詳細から行う
- 開始予定日を元の位置より表示範囲の外へは動かさず、帯が範囲から外れる位置にも置かない。帯が消えると確定も取消もできないためである
- 確定前の移動は、フォーカスを外す・別の帯をドラッグする・ドラッグが途中で切れると取り消す
- 送信中は確定も取消も受け付けない
- 変更は `planned_start_changed` 履歴に記録される

### 失敗時

- 403 / 404 は、帯を元の位置に戻し、「このタスクは変更できません」を出す
- その他の失敗は、帯を元の位置に戻し、エラー内容を出す
- 楽観更新はしない。ドラッグ中の追従は見た目だけで、確定前の状態に戻せる

### コンポーネント

| 内容 | 場所 |
|---|---|
| 山の計算規則 | `lib/calendar/load.ts` |
| 棒の表示とドラッグ・キーボードの操作 | `components/calendar/CalendarTimeline.vue` |
| `today` の受け渡し・`include_overdue` の付与・期間外タスクの間引き | `pages/@tenant/calendar/+Page.vue` |

## 未実装と既知の制限

この機能の対象外としているものは次のとおりである。

- 人ごとの稼働時間・テナントの休日。上限は 1 日 6 時間・土日非稼働・祝日なしの固定である
- 自動の山崩し（並べ替えの探索）
- 過去の日に実績を描くこと

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-10-20 | 積む量は残工数にする | 見積の均等割りは「残り何時間か」の近似にすぎないので、作業記録の分を引く |
| 2026-10-20 | `logged_minutes` は担当者以外の記録も含むタスク単位の合計にする | 残工数はタスクの性質であり、サマリー API の `actual_minutes` と定義を揃える |
| 2026-10-20 | 過去の日には積まない | 過去に実績を描くには日別の記録が要り、schedule API の応答が膨らむ |
| 2026-10-20 | 締切超過の残工数は今日に全部積む。表示期間より前に締切を過ぎたものは `include_overdue` で取る | 消すと超過が見えなくなる。表示期間より前に締切を過ぎたものは schedule API が返さない。取得期間を広げる案は 92 日の上限で漏れが残る |
| 2026-10-20 | `include_overdue` で期間外から追加する対象を、Soft 締切・開始予定日・見積があり未完了のタスクに限る | 締切超過のタスクを毎回すべて取らない |
| 2026-10-20 | 土日だけの期間は直前の平日に積む | 今日に積むと、表示期間より後の土日のタスク（schedule API が返さない）だけが漏れ、見ている週によって今日の山が変わる。表示期間は月曜始まりなので、直前の平日は期間内か期間より後に収まる |
| 2026-10-20 | 開始予定日の無いタスクは積まない | 今日から積むと未着手の全タスクが今日に乗り、山が意味を失う。開始予定日は「いつやるか」の意思表示として入れてもらう |
| 2026-10-20 | 担当者の分け方は均等割りにする。`role` の正規化もしない | 比率を持つには `task_assignees` に列が要り、入力の手間に見合う根拠がまだ無い |
| 2026-10-20 | 上限は 6 時間固定を維持する | 人別の稼働時間と休日は別の仕様で扱う |
| 2026-10-20 | 山崩しで動かすのは開始予定日だけにする | 締切をカレンダーから動かすと通知や期限超過の判定に波及する |
| 2026-10-20 | 計算はクライアントに置く | 92 日・500 件の上限内で足り、サーバーに集計エンドポイントを足す理由がまだ無い |
| 2026-10-20 | 山は絞り込み前の全タスクで計算する | プロジェクトで絞ったときに他プロジェクトの負荷が消えると、超過を見落とす |
| 2026-10-20 | 見積を期間で均等に割って積む最初の規則を、現在の規則に置き換える | 最初の規則は積む量が `estimated_minutes`、期間が開始予定日〜Soft 締切で、過去の日にも積み、締切超過は期間なしとして積まず、`primary` だけに全額を積んでいた。現在は残工数を今日〜Soft 締切に切り詰めて積み、過去の日には積まず、締切超過は今日に全部積み、全担当者で均等に割る |
| 2026-10-20 | 棒の見た目と数字の規則を分けて置く | 規則を変えると数字が変わるので、見た目の変更と混ぜるとテストで切り分けられない |

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