---
title: "タスク コア"
description: "タスク CRUD・カスタムステータス・担当者・ラベル・種別・マイルストーン・依存関係"
---

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

# タスク コア

## 概要

タスク管理の基盤となる機能で、他のタスク機能はこのページのテーブルと API の上に作る。タスク CRUD とプロジェクト内連番 ID（`KEY-N` 形式。例は `ENG-42`）、プロジェクト単位のカスタムステータス、担当者を扱う。優先順位・締切（Soft / Hard）・開始予定日・進捗率、親子タスクとブロッキング依存関係、プロジェクト単位のラベル（export / import を含む）、プロジェクト単位のタスク種別、マイルストーンも含む。他の機能への依存は無い。

## 振る舞い

### プロジェクトキー

プロジェクトの `key` はテナント内で一意の英大文字識別子（例は `ENG`、`BACK`、`WEB`）で、`KEY-N` 形式に使う。形式は `^[A-Z][A-Z0-9]{1,9}$`（制約 `projects_key_format`）、一意性は `projects_key_tenant_unique`（`tenant_id`, `key`）で保つ。

- プロジェクト作成 API で指定すれば、その値を検証して使う。重複はエラーになる
- 省略するとプロジェクト名の英数字を大文字にして先頭 10 文字を取る。例は "Backend API" から `BACKENDAPI`
- 英数字が足りないか形式に合わなければ `PROJ` にする
- 自動生成のキーが重複したら、先頭 6 文字とランダムな 4 文字に作り直す

### 連番 ID

`project_task_counters.last_seq` を `SELECT ... FOR UPDATE` でロックしてインクリメントする。行が無ければ `1` で作る。

### カスタムステータス

通常のプロジェクトを作ると `Backlog` / `Todo`（`is_default`）/ `In Progress` / `Done`（`is_done_state` と `is_default_done`）の 4 つを自動で挿入する。個人プロジェクトは `Todo`（`is_default`）と `Done` の 2 つである。タスク作成 API は `status_id` を必須としており、`is_default` を自動では補わない。既定値を使うのはクライアント側である。

完了ステータスは複数持てる（`Done` と `No Planning` のように）。そのうち 1 つに `is_default_done` を付け、CLI の `tasks complete`・タスク詳細の完了ボタン・GitHub Issue の close 同期・[担当者全員の完了](#担当者)で最後の 1 人が完了にしたときはここへ移す。`is_default_done` の付いたステータスが無いプロジェクトでは並び順で最初の完了ステータスを使う。

- `is_default_done` は完了ステータスにしか付けられず、付け替えると他からは自動で外れる。付いているものを直接 `false` にする更新は 400 になる
- 完了ステータスが 1 つも無い状態にはできない。最後の 1 つは `is_done_state` を外せず、削除もできない
- 完了ステータスを外したり削除したりして `is_default_done` の持ち主が消えると、並び順で最初の完了ステータスへ付け直す
- 完了を外したステータスにあるタスクは `completed_at` が消える
- 完了にしたステータスにあるタスクと、完了へ移したタスクには `completed_at` が入る。既に値があれば保つ
- `is_default` のステータスは削除できない（400）

### 種別

種別はタスクの種類（バグ・機能など）で、プロジェクトごとに定義する。1 つのタスクに付けられる種別は 0 個か 1 個で、既定の種別は無い。

- 新しいプロジェクト（個人プロジェクトを含む）には `タスク`（`#64748b`）、`バグ`（`#ef4444`）、`機能`（`#3b82f6`）の 3 つを入れる。種別が 1 つも無い既存のプロジェクトには、マイグレーションが同じ 3 つを入れる
- 作成と更新で指定できるのは同じプロジェクトの種別だけである。別のプロジェクトの種別と存在しない ID は 404 になる
- 種別を削除すると、付いていたタスクは残り、種別だけが未設定に戻る
- 定義の名前は同じプロジェクトの中で一意にする。重複は 409 になる
- 作成は並び順の末尾に付く。種別の作成・更新・並べ替え・削除は、プロジェクト単位の advisory lock で直列にするので、同時の作成でも `position` は重ならない。上限（32,767）に達した種別の作成は 400 になり、並べ替えで振り直すと再び追加できる
- 並べ替えはプロジェクトの全種別を過不足なく渡す。種別が 0 件のプロジェクトでは空の配列だけが通る
- タスクに付ける種別は書く前に確かめる。確認のあとに削除された種別は 404 になり、付いたあとに削除された種別は未設定に戻る
- 種別の変更はアクティビティ `task_type_changed` に名前で残る。同じ種別の再指定は記録しない
- タスクの応答は `task_type`（`id` / `name` / `color` など）を埋め込む。未設定なら `null` である
- ラベルとの違いは、種別が 1 つだけ選ぶ分類で、ラベルは複数付けられる横断の属性である点である。既存のラベルから種別への自動移行はしない

### 締切と開始予定日

API は Soft 締切 < Hard 締切を要求し、同時刻も 400 にする。DB の CHECK（`soft_before_hard`）は soft ≤ hard である。

開始予定日 `planned_start_on` は DATE で NULL にできる。更新は `planned_start_on` と `clear_planned_start_on` で行い、同時に指定すると解除が優先する（`clear_soft_deadline` と同じ）。Soft 締切との前後関係は DB の CHECK でもサーバーの検証でも見ない。変更は `planned_start_changed` の履歴に記録する。

### 説明文

`description` は Markdown で、上限は 100,000 文字である。バイトではなく文字で数える（`payload::tasks::MAX_DESCRIPTION_LEN`）。作成・更新で超過すると 400 になる。上限の導入前に保存された超過行は移行せず、本文を送らない更新はそのまま通る。タスク詳細の SSR は同じ値を超える本文を描画せずプレーン表示にする。

説明文に Markdown のタスクリスト（`- [ ]` / `- [x]`）があると、List 表示の行とタスク詳細の説明欄の見出しに「完了数 / 総数」を出す。ネストした項目も 1 件ずつ数え、コードブロックと HTML コメントの中は数えない（引用や箇条書きの中で開いたものは、その終わりで閉じる）。数えるのは画面（`lib/task-checklist.ts`）で、API は値を持たない。`progress_pct` とは独立で、互いに書き換えない。

タスク詳細の説明欄では、編集に入らず閲覧表示のままチェックボックスを押して切り替えられる。描画器が各チェックボックスに原文の位置を属性で付け、画面はその位置の 1 字だけを書き換えた説明文全体を、説明の編集と同じ更新で保存する（編集の保存は本文の前後の空白を削るが、切り替えでは削らない。字下げが変わるとリストの入れ子が変わるため）。保存中と、失敗した説明の編集を「編集を再開」で取り戻せる間は、チェックボックスが押せなくなる。更新に失敗するとチェックは元へ戻る。他の人の更新との版の照合は無く、後から保存した内容が残る（説明の編集と同じ）。コメントの本文は対象外で、チェックボックスは押せない。

本文中の http / https の絶対 URL のリンクの先頭には、リンク先サイトの favicon を出す。画像は `GET /v1/favicons/{host}` が取得して配信し、取れないときは汎用アイコンになる。段落が GitHub のパーマリンク（コミット SHA と行範囲つきの blob URL）だけのときは、連携リポジトリから取ったその行をコードの抜粋として出す。行は `GET /v1/github/snippet` が返し（[GitHub App 基盤](https://docs.koyori.app/dev/features/tasks/github-app)）、取れないときはリンクのままになる。コメント、ドキュメント、レビュー指摘の本文も同じ描画である。規則は [KFM の描画](https://docs.koyori.app/dev/frontend/kfm-phase1-implementation) に書く。

### 担当者

`role` は自由な文字列で、サーバーは値の種類を検証しない。画面は `primary` を、一括更新（[タスク拡張](https://docs.koyori.app/dev/features/tasks/extensions)のバルク操作）は `assignee` を入れるので、両方が混在する。

担当者ごとの完了は、タスクの設定 `require_all_assignees_done`（既定は off）で切り替える。on のタスクでは、担当者が自分の分を完了にし、全員がそろった時点でタスクが既定の完了ステータスへ移る。`role` は問わず、担当者全員が対象である。

- 自分の分を完了にする・取り消せるのは本人だけで、他人の分は 403 になる。担当者でない本人は 404、設定が off のタスクは 409（`completion-not-required`）である。同じ人の 2 回目の完了は何も変えずに 200 を返す
- 取り消せるのはタスクが未完了の間だけで、完了ステータスにいる間は 409（`task-already-done`）になる。先にステータスを戻す
- 最後の 1 人が完了にしたとき、必須カスタムフィールドが埋まっていなければ 400 で、その人の完了も記録されない。これは直接完了へ移すときと同じ条件である
- 未完了の担当者が残る間は、完了ステータスへ直接移せない。`PUT /tasks/{id}`・一括更新・作成が 409（`assignees-not-done`）になり、一括更新では失敗理由に同じ値が入る。担当者が 0 人のタスクは止めない
- タスクを完了から未完了へ戻すと、全員の完了を消す。設定を off にしたときも消す。完了済みのタスクで設定を on にしても、何も動かさない
- 担当者を足すと、その人は未完了で始まる。外すと、その人の完了は消える。外した結果として残りの全員が完了になっても、自動では完了にしない（直接完了へ移せるようになる）。完了済みのタスクは担当者の増減で動かさない
- PR のマージによる自動完了は、未完了の担当者が残るタスクを完了にせず、開いたままにする。PR は処理済みになり再処理されないので、そのタスクは手で完了にする
- レビュー指摘の繰り延べ先タスクも同じで、指摘を `open` へ戻すクローズは、未完了の担当者が残るタスクを完了にしない（[レビュー指摘](https://docs.koyori.app/dev/features/review-findings)の「繰り延べ」）。繰り延べで開き直すときは、完了から戻すので担当者の完了を全員分消す
- GitHub Issue の close 同期と、ステータスの削除・完了フラグ変更に伴う一括移行は、この制限の対象外で、そのまま完了になる。完了ステータスから外れるタスクの完了は消える。結果として、完了のタスクに未完了の担当者が残ることがある
- 担当者の行を書く経路は、タスク行を先にロックし、そのあとで担当者の行を更新する順に揃える。担当者の追加・削除・ロール変更と自分の分の完了・取り消しは、最初にタスク行を `FOR UPDATE` でロックする。完了を巻き戻す側（完了から未完了へ戻す更新、一括更新、Issue の reopen 同期、ステータスの完了フラグ解除、完了ステータスの削除）は、タスク行を更新・ロックしたあとで担当者の完了を消す。同時に走っても判定がずれず、この担当者行とタスク行の組ではデッドロックにならない。完了の途中で担当者が外されていれば 404 になる。ステータス操作が取る `project_statuses` の `FOR UPDATE` と、外部キーの検査が取る `FOR KEY SHARE` の順序は、この規則の対象外である

画面は、タスク詳細の「完了条件」の行に設定のチェックと、担当者ごとの完了・未完了、自分の分の操作を出す。作成ダイアログには設定を置かないので、作成 API で指定するか、作成後に詳細で切り替える。CLI は型を追従しただけで、自分の分を完了にする操作を持たない。対象のタスクで `tasks complete` を実行すると 409 の理由が出る。

担当者欄（タスク作成ダイアログ・タスク詳細・一覧の行）は、候補の後ろに部署・チームの行を出す。選ぶとその部署・チームの候補全員を担当者に加える。API は利用者ごとに送り、作成は `assignees` に全員を載せ、作成後は 1 人ずつ `POST` する。部署・チームは `tenant_members` の自由記述をそのまま使うので、表記が違えば別の行になる。

### 依存関係と親子

循環依存はリレーション追加時にサーバー側で BFS を行って検出し、`409 Conflict` を返す。トランザクションを SERIALIZABLE にして、逆向きの追加が同時に走って検出をすり抜けることを防ぐ。親子関係（`parent_task_id`）の循環も更新時に検出する。

親タスクは `PUT /tasks/{id}` の `parent_task_id`（設定・変更）と `clear_parent_task_id`（解除）で変える。

親を指定してタスクを作成すると、リクエストに無い Soft 締切・Hard 締切・開始予定日には親の値が入る。指定した項目はその値になる。片方の締切だけを指定して、親のもう片方と Soft < Hard にならないときは、親の側を入れない。値を写すのは作成時だけで、親を後から変えても子は変わらず、`PUT` で親を付けたり替えたりしても写さない。値なしで作りたいときは、作成後に `clear_soft_deadline` などで外す。単体作成・一括作成・CLI・画面のサブタスク作成で同じである。

### 削除

タスクの削除は `deleted_at` によるソフトデリートである。物理削除の API は無い。

## データ

### `project_task_counters`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `project_id` | UUID | PK, FK→projects CASCADE | |
| `last_seq` | INT | NOT NULL DEFAULT 0 | 最後に振った連番 |

### `project_statuses`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `project_id` | UUID | NOT NULL, FK→projects CASCADE | |
| `name` | VARCHAR(100) | NOT NULL, UNIQUE(project_id, name) | |
| `color` | VARCHAR(7) | NOT NULL | hex（`#3b82f6`） |
| `position` | SMALLINT | NOT NULL | 表示順 |
| `is_default` | BOOLEAN | NOT NULL DEFAULT false | 既定のステータス。プロジェクト内で 1 つ |
| `is_done_state` | BOOLEAN | NOT NULL DEFAULT false | このステータスを完了とみなす。複数可 |
| `is_default_done` | BOOLEAN | NOT NULL DEFAULT false | 「完了にする」操作の移動先。完了のうち 1 つのみ |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

### `tasks`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `project_id` | UUID | NOT NULL, FK→projects CASCADE | |
| `seq_id` | INT | NOT NULL, UNIQUE(project_id, seq_id) | プロジェクト内連番。`KEY-N` 形式で表示する（例は `ENG-42`） |
| `title` | VARCHAR(255) | NOT NULL | |
| `description` | TEXT | NULLABLE | Markdown。最大 100,000 文字 |
| `status_id` | UUID | NOT NULL, FK→project_statuses | |
| `priority` | VARCHAR | NOT NULL DEFAULT 'medium' | [優先順位 enum](https://docs.koyori.app/dev/features/tasks) の DB 値 |
| `progress_pct` | SMALLINT | NOT NULL DEFAULT 0 CHECK (0–100) | |
| `parent_task_id` | UUID | NULLABLE, FK→tasks SET NULL | |
| `milestone_id` | UUID | NULLABLE, FK→milestones SET NULL | |
| `task_type_id` | UUID | NULLABLE, FK→project_task_types SET NULL | [種別](#種別)。未設定は NULL |
| `sprint_id` | UUID | NULLABLE, FK→sprints SET NULL | [スプリント](https://docs.koyori.app/dev/features/tasks/sprints)への割り当て |
| `soft_deadline` | TIMESTAMPTZ | NULLABLE, CHECK `soft_before_hard` | |
| `hard_deadline` | TIMESTAMPTZ | NULLABLE, CHECK `soft_before_hard` | |
| `planned_start_on` | DATE | NULLABLE | 開始予定日 |
| `require_all_assignees_done` | BOOLEAN | NOT NULL DEFAULT false | true のとき、担当者全員が自分の分を完了にして初めてタスクが完了になる |
| `estimated_minutes` | INT | NULLABLE CHECK (> 0) | |
| `is_archived` | BOOLEAN | NOT NULL DEFAULT false | |
| `created_by` | UUID | NOT NULL, FK→users | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |
| `completed_at` | TIMESTAMPTZ | NULLABLE | 完了ステータスへ移した時刻 |
| `deleted_at` | TIMESTAMPTZ | NULLABLE | ソフトデリート |
| `search_vector` | TSVECTOR | 生成列 | [タスク拡張](https://docs.koyori.app/dev/features/tasks/extensions)の全文検索。`USE_PG_BIGM=true` の環境には無い |

### `task_assignees`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `task_id` | UUID | NOT NULL, FK→tasks CASCADE, UNIQUE(task_id, user_id) | |
| `user_id` | UUID | NOT NULL, FK→users CASCADE | |
| `role` | VARCHAR | NOT NULL DEFAULT 'secondary' | |
| `assigned_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |
| `completed_at` | TIMESTAMPTZ | NULLABLE | 担当者が自分の分を完了にした時刻。未完了は NULL |

### `task_relations`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `blocker_task_id` | UUID | NOT NULL, FK→tasks CASCADE, UNIQUE(blocker_task_id, blocked_task_id) | |
| `blocked_task_id` | UUID | NOT NULL, FK→tasks CASCADE, CHECK(blocker_task_id <> blocked_task_id) | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

### `milestones`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `project_id` | UUID | NOT NULL, FK→projects CASCADE | |
| `name` | VARCHAR(255) | NOT NULL | |
| `description` | TEXT | NULLABLE | |
| `due_date` | DATE | NOT NULL | |
| `created_by` | UUID | NOT NULL, FK→users | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

### `labels`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `name` | VARCHAR | NOT NULL, UNIQUE(project_id, name) | |
| `description` | TEXT | NOT NULL DEFAULT '' | |
| `color` | VARCHAR | NOT NULL | |
| `icon_url` | TEXT | NULLABLE | |
| `project_id` | UUID | NULLABLE, FK→projects CASCADE | |

### `project_task_types`

列の定義は[マイグレーション](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261116000000_task_types.rs)にある。

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `project_id` | UUID | NOT NULL, FK→projects CASCADE | |
| `name` | VARCHAR(100) | NOT NULL, UNIQUE(project_id, name) | |
| `color` | VARCHAR(7) | NOT NULL | hex（`#ef4444`） |
| `position` | SMALLINT | NOT NULL DEFAULT 0 | 表示順 |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

### `task_labels`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `task_id` | UUID | NOT NULL, FK→tasks CASCADE, PK(task_id, label_id) | |
| `label_id` | UUID | NOT NULL, FK→labels CASCADE, PK(task_id, label_id) | |

スキーマは [m20260520000000_initial_schema.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20260520000000_initial_schema.rs) にある。`is_default_done` は [m20260907000000_default_done_status.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20260907000000_default_done_status.rs) で足し、既存の完了ステータスにも付ける。`planned_start_on` は [m20261016000000_task_planned_start_on.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261016000000_task_planned_start_on.rs) で足す。`require_all_assignees_done` と `task_assignees.completed_at` は [m20261112000000_task_require_all_assignees_done.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261112000000_task_require_all_assignees_done.rs) で足す。

## API

一覧は `q` の条件式と `timezone` を受け取り、検索語があれば `matches` に一致箇所を返す。並び順には `updated_at_desc`、`key_asc`、`key_desc`、`status_asc`、`status_desc` も指定できる。ステータスは position 順である。条件式の文法は[拡張機能](https://docs.koyori.app/dev/features/tasks/extensions)に定義する。

URL 基底パスは `/v1/tenants/{tenant_id}/projects/{project_id}` である。

### タスク

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/tasks` | 一覧（フィルター・ソート・ページング） |
| `POST` | `/tasks` | 作成 |
| `GET` | `/tasks/{id}` | 取得（UUID または `KEY-N`、例は `ENG-42`） |
| `PUT` | `/tasks/{id}` | 更新（全フィールド optional） |
| `DELETE` | `/tasks/{id}` | ソフトデリート |
| `POST` | `/tasks/{id}/archive` | アーカイブ |
| `POST` | `/tasks/{id}/unarchive` | アーカイブ解除 |

`GET /tasks` のクエリは次のとおりである。

| パラメータ | 型 | 説明 |
|---|---|---|
| `status_id` | UUID? | |
| `priority` | string? | DB 値（`high` など）。不明な値は 400 |
| `assignee_id` | UUID? | |
| `unassigned` | bool | 既定 false。true で担当者が 1 人もいないタスクのみ（役割は問わない）。`assignee_id` と同時指定は 400 |
| `created_by` | UUID? | 指定した利用者が作成したタスクのみ |
| `label_id` | UUID? | 指定ラベルが付与されたタスクのみ |
| `milestone_id` | UUID? | |
| `task_type_id` | UUID? | 指定した種別のタスクのみ |
| `sprint_id` | UUID? | |
| `parent_task_id` | UUID? | サブタスク一覧 |
| `planned_start_from` | date? | 開始予定日がこの日以降（`YYYY-MM-DD`、両端含む） |
| `planned_start_to` | date? | 開始予定日がこの日以前（両端含む）。`from > to` は 400。どちらかを指定すると開始予定日が未設定のタスクは除外する |
| `root_only` | bool | 既定 false。親が同じ絞り込みの結果に含まれないタスクだけを返す（List 表示が使う） |
| `is_archived` | bool | 既定 false |
| `sort` | string | `created_at_desc`（既定）、または `title` / `assignee` / `priority` / `deadline` に `_asc` / `_desc` を付けた値 |
| `limit` | u32 | 既定 50、1〜200 に丸める |
| `offset` | u32 | ページ番号で飛ぶ一覧（表形式）が使う |
| `cursor` | string? | 前のページの `next_cursor`。`offset` と同時指定は 400。カーソルは `sort` ごとに別物である |

続きを読み足す一覧は `offset` ではなくカーソルを使う。応答の `total` は絞り込み後の総数で、件数の表示とページ番号の算出に使う。「まだ残っているか」の判断には `next_cursor` を使う。応答はステータスと利用者を ID または要約で返し、`subtask_count` は持たない。

`POST /tasks` は `title` と `status_id` が必須である。`parent_task_id` を指定したときの締切と開始予定日は、[依存関係と親子](#依存関係と親子)のとおりである。`priority` は JSON の値（`High` など。[優先順位 enum](https://docs.koyori.app/dev/features/tasks)）で送る。`task_type_id` は[種別](#種別)である。`custom_field_values` は[カスタムフィールド](https://docs.koyori.app/dev/features/tasks/custom-fields)の値である。作成と更新の応答は `GET /tasks/{id}` と同じ形（`TaskDetailResponse`）で、`TaskResponse` のフィールドに `custom_field_values`・`mentions`・`reactions`・`attachments`（[拡張](https://docs.koyori.app/dev/features/tasks/extensions)の添付の一覧と同じ要素）を足している。

`PUT /tasks/{id}` の規則は次のとおりである。

- 値をクリアするために `clear_description` / `clear_parent_task_id` / `clear_milestone_id` / `clear_sprint_id` / `clear_soft_deadline` / `clear_hard_deadline` / `clear_planned_start_on` / `clear_estimated_minutes` / `clear_task_type_id` を持つ。`task_type_id` と `clear_task_type_id` を同時に指定すると、外す指定が優先される
- `label_ids` は集合の置き換え、`add_label_ids` / `remove_label_ids` は差分である
- `assignees` は担当者集合の置き換えで、既存の担当者の役割は保つ
- `require_all_assignees_done` は[担当者全員の完了](#担当者)の切り替えである。作成 API でも指定でき、true のまま完了ステータスで作ると 409 になる。完了ステータスへ移す更新は、未完了の担当者が残るかぎり 409（`assignees-not-done`）になる。同じ要求で `assignees` を置き換えるときは、置き換え後の担当者で判定する
- 完了済みのスプリントへの割り当ては 409 になる

### 担当者

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/tasks/{id}/assignees` | 一覧 |
| `POST` | `/tasks/{id}/assignees` | 追加（`user_id` と `role`。例は `primary`） |
| `PUT` | `/tasks/{id}/assignees/{user_id}` | ロール変更 |
| `DELETE` | `/tasks/{id}/assignees/{user_id}` | 削除 |
| `POST` | `/tasks/{id}/assignees/{user_id}/complete` | 自分の分を完了にする（本人のみ。応答は `TaskDetailResponse`） |
| `POST` | `/tasks/{id}/assignees/{user_id}/reopen` | 自分の分の完了を取り消す（本人のみ。応答は `TaskDetailResponse`） |

### 依存関係

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/tasks/{id}/relations` | 一覧（`parent` / `subtasks` / `blocks` / `blocked_by`） |
| `POST` | `/tasks/{id}/relations` | 追加（`type` と `target_task_id`） |
| `DELETE` | `/tasks/{id}/relations/{relation_id}` | 削除 |

`POST` はどちらのタスクからでも設定できる。`blocks` と `blocked_by` で反対側から設定しても、結果は同一レコードである。

| `type` | 意味 |
|---|---|
| `"blocks"` | 現タスクが `target` をブロックする |
| `"blocked_by"` | 現タスクは `target` にブロックされている |

`target_task_id` は同じプロジェクトのタスクの UUID に限る。同じ関係の重複と循環は 409 になる。`GET` の応答の各要素は `TaskResponse` の全フィールドで、`blocks` と `blocked_by` にはさらに `relation_id` が付く。

### カスタムステータス

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/statuses` | 一覧（position 順） |
| `POST` | `/statuses` | 作成 |
| `PUT` | `/statuses/{id}` | 更新 |
| `PUT` | `/statuses/reorder` | 並び順一括更新（`ids` の配列）。プロジェクトの全ステータスを過不足なく渡す（違えば 400。空の配列も 400） |
| `DELETE` | `/statuses/{id}` | 削除（タスクが存在する場合はクエリ `migrate_to_status_id` 必須） |

### マイルストーン

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/milestones` | 一覧 |
| `POST` | `/milestones` | 作成 |
| `GET` | `/milestones/{id}` | 取得（`progress_pct` と `task_counts` の `total` / `done` を含む） |
| `PUT` | `/milestones/{id}` | 更新 |
| `DELETE` | `/milestones/{id}` | 削除（タスクの `milestone_id` は NULL に戻す） |

`progress_pct` は完了ステータスにあるタスクの割合を整数に切り捨てた値で、削除済みのタスクは数えない。

### ラベル

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/labels` | プロジェクトのラベル一覧 |
| `POST` | `/labels` | 作成 |
| `PUT` | `/labels/{id}` | 更新 |
| `DELETE` | `/labels/{id}` | 削除（`task_labels` も CASCADE） |
| `GET` | `/labels/export` | JSON エクスポート（`LabelExport`。`version` は 1） |
| `POST` | `/labels/import` | JSON インポート（`on_conflict` は `skip` / `overwrite`。1 回 500 件まで） |

### 種別

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/task-types` | プロジェクトの種別一覧（`position` 順） |
| `POST` | `/task-types` | 作成（`name` と `color`）。`position` は末尾に付く |
| `PUT` | `/task-types/{id}` | 更新（`name` と `color` は片方だけでもよい） |
| `PUT` | `/task-types/reorder` | 並び順一括更新（`ids` の配列）。プロジェクトの全種別を過不足なく渡す（違えば 400） |
| `DELETE` | `/task-types/{id}` | 削除（付いていたタスクの `task_type_id` は NULL に戻す） |

`name` は 1〜100 文字、`color` は `#RRGGBB` で、外れると 400 になる。

### リンクの favicon

説明文などの外部リンクに出す favicon の配信である。基底パスは上のプロジェクト配下ではなく `/v1` である。

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/v1/favicons/{host}` | `https://{host}/favicon.ico` を取得して返す。要認証（セッション、PAT、Device Token） |

- `host` は小文字、ドット必須、ラベル 63 文字以下、全長 253 文字以下。合わなければ 404 になる
- 取れた画像（ICO / PNG / JPEG / GIF / WebP）は `Cache-Control: private, max-age=86400` で返す。サーバー側は Redis に 7 日保存する
- 取れない時（画像でない、private 宛て、タイムアウト、64 KiB 超）は 200 で汎用アイコン（`image/svg+xml`、`private, max-age=3600`）を返し、サーバー側は 1 時間保存する。サーバーに残す画像は 64 KiB までで、超える応答は取れなかった扱いにする
- 取得は全ホップ合わせて 8 秒（1 ホップは 5 秒）で打ち切り、取れなかった扱いにする。同時取得が 16 件を超えた分は保存せず `no-store` で汎用アイコンを返す
- キャッシュに無い host を外へ取りに行く回数は、利用者ごとに 10 分で 30 回までである。超えた分は取りに行かず、保存せずに `no-store` で汎用アイコンを返す。キャッシュ済みの host は数えない
- 接続先は Webhook と同じ規則で検査する（private、link-local、メタデータ、loopback は拒否）。リダイレクトは 3 回まで追い、各ホップで検査する。接続先のポートは常に 443 で、リダイレクト先も 443 以外のポートは拒否する
- 認証を要するのは、無認証だと誰でもこのサーバーを任意ホストへの GET の踏み台にできるためである。認証済みの利用者による Redis の使い切りは、画像の上限と取得回数の上限で抑える

## 認可

| 操作 | 誰が | スコープ |
|---|---|---|
| タスク閲覧 / 作成 / 更新 / アーカイブ | プロジェクトに入れる人、またはテナントオーナー | `read:task` / `write:task` |
| タスク削除（ソフト） | 作成者、またはテナントオーナー | `write:task` |
| 自分の担当分の完了・取り消し | 担当者本人のみ | `write:task` |
| ステータス / ラベル / 種別管理 | プロジェクトに入れる人、またはテナントオーナー | `write:task` |
| マイルストーン管理 | プロジェクトに入れる人、またはテナントオーナー | `read:milestone` / `write:milestone` |

「プロジェクトに入れる人」は、テナントの所属を継承した人と、そのプロジェクトに明示 ACE（`project_members` の行）を持つ人である。

- プロジェクトにメンバーを 1 人も指定していなければテナントメンバー全員が入れる
- 指定があれば明示 ACE を持つ人だけが入れる
- 明示 ACE はテナント所属と独立に残るので、テナントに行が無い人でも明示 ACE のあるプロジェクトにはゲストとして入れる。テナント全体には入れない

判定の詳細は[テナント / プロジェクト認可](https://docs.koyori.app/dev/design/tenant-project-authz)に書く。

## 画面

ページの URL は次のとおりである。

| URL | 内容 |
|---|---|
| `/{tenant}` | ホーム（ダッシュボード） |
| `/{tenant}/my-tasks` | My Tasks |
| `/{tenant}/projects/{KEY}/tasks` | 一覧（List / Table 切替。`?view=table`） |
| `/{tenant}/projects/{KEY}/tasks/{KEY}-{N}` | 詳細 |
| `/{tenant}/projects/{KEY}/settings` | ワークフロー・ラベル・種別・カスタムフィールドの管理 |

一覧の List 表示はステータスごとにタスクをグループにして並べ、行をドラッグして別のグループへ落とすとステータスが変わる。落とし先はグループの全域（見出し・行の隙間・末尾の余白・空のグループ・折りたたんだグループの見出し）で、保存は落としたときに 1 回だけ行う。通過しただけのグループには保存しない。入力欄と行の中に開いた一覧からは掴まず、タッチでは長押しのあとに動かすと掴む。広い画面では一覧の右に詳細を開く。サブタスクは親の行の配下に描く。親行は既定では閉じていて、行の矢印で開く。環境設定「タスク一覧でサブタスクを最初から展開する」を有効にすると親行を開いた状態で描き、サブタスクが無い親行は閉じた見た目のままにする。矢印で個別に閉じた行はその画面を開いている間だけ閉じたままで、設定を切り替えると全行が設定に従う。

List 表示の行は、一覧の幅が 48rem 以上なら担当・期限・優先度を列で並べてその場で変更でき、タイトルの下の ID を押すとコピーできる。それより狭いときは 2 段に積み、担当・期限・優先度は表示だけにして詳細で変更する。ID のコピーは画面幅が 768px 以下では出さない。説明文にタスクリストがあれば、タイトルの下の ID の隣に達成率を出す（幅によらず出す）。

親タスクの変更はタスク詳細のサブタスク欄（ページ・オーバーレイ・右ペイン共通）で行う。同じプロジェクトのタスクをキーまたはタイトルで検索して選ぶ。自分自身・現在の親・直下の子は候補から除き、深い子孫を選ぶと backend の 409 を理由つきで表示する。

ブロック関係の設定と表示もタスク詳細のブロック関係の欄（ページ・オーバーレイ・右ペイン共通）で行う。`blocked_by` を先に、`blocks` を次に並べ、相手をキーまたはタイトルで検索して追加する。自分自身と既に関係のあるタスクは候補から除き、循環や重複は backend の 409 を理由つきで表示する。未完了のブロッカーが残っているときは欄の見出しに件数を出す。

マイルストーンは、カレンダーの最上段に期日のフラグとして出す。

タスク詳細の種別は、プロパティ欄の上にチップで出す。種別があれば色の点と名前、無ければ「種別」と薄く出し、押すと「種別なし」と各種別のメニューが開く。プロジェクトに種別が 0 件で、タスクにも種別が無いときは、チップを出さない。タスク作成ダイアログでは、チップ列の先頭に種別のチップを出し、選んだ種別は作成の本文に入る。種別の候補が 0 件のプロジェクトでは作成ダイアログのチップを出さない。設定の「種別」の節では、追加・名前と色の変更・上下への並べ替え・削除ができる。

### 主要コンポーネント

| 役割 | ファイル |
|---|---|
| タスク一覧 | `pages/@tenant/projects/@projectKey/tasks/+Page.vue` |
| List 表示 | `components/tasks/TaskGroupedList.vue` / `TaskGroupedRow.vue` |
| タスク詳細のページ | `pages/@tenant/projects/@projectKey/tasks/@taskId/+Page.vue` |
| タスク詳細の共通部分 | `components/tasks/TaskDetailHub.vue` |
| 一覧・カレンダーから開く詳細 | `components/tasks/TaskDetailPane.vue` / `TaskDetailOverlay.vue` |
| チェックリストの達成率 | `components/tasks/TaskChecklistProgress.vue` / `lib/task-checklist.ts` |
| チェックボックスの切り替え | `components/tasks/TaskDetailHub.vue` / `lib/task-checklist-toggle.ts` / `lib/rehype-kfm-task-offset/` |
| タスク作成 | `components/tasks/CreateTaskDialog.vue` |
| 担当者の選択 | `components/tasks/TaskAssigneePicker.vue` / `components/users/UserSelector.vue` |
| 完了条件（担当者ごとの完了） | `components/tasks/TaskCompletionRule.vue` |
| サブタスク | `components/tasks/TaskSubtaskPanel.vue` |
| ブロック関係 | `components/tasks/TaskBlockingPanel.vue` |
| ワークフロー（ステータス）の管理 | `components/projects/WorkflowStatusesEditor.vue` |
| ラベルの管理 | `components/projects/LabelsSection.vue` |
| 種別の管理 | `components/projects/TaskTypesSection.vue` / `TaskTypeFormDialog.vue` |
| My Tasks | `pages/@tenant/my-tasks/+Page.vue` |

### キーボードショートカット

修飾キー無しの単打キーで操作する（`composables/useKeyboardShortcuts.ts`）。Shift の有無は区別しない。

| キー | 画面 | 動作 |
|---|---|---|
| `T` | タスク一覧（`tasks/+Page.vue`） | タスク作成モーダルを開く。一覧本体が表示されていないとき（読み込み中・エラー・テナント／プロジェクト未解決）は何もしない |
| `T` | ホーム（`HomeDashboard.vue`） | タスク作成モーダルを開く。作成ボタンが押せないとき（プロジェクト 0 件・取得失敗）は何もしない |
| `T` | ドキュメント詳細（`DocumentDetail.vue`） | 選択範囲をタイトルにしてタスク作成ダイアログを開く。「タスクを作成」ボタンが出ていないとき（読み込み中・エラー・対象外・編集中）は何もしない |

次のときは発火しない。

- 入力中（`input` / `textarea` / `select` / `contenteditable` の中）
- IME 変換中（`isComposing` または `keyCode` 229）
- ダイアログが開いている（`[role="dialog"]` / `dialog[open]` がある）。タスク詳細オーバーレイや確認ダイアログの上に重ねない
- 修飾キー付き（Ctrl / ⌘ / Alt）。ブラウザ・OS・既存の ⌘B / ⌘S と衝突させない
- キーの押しっぱなし（`repeat`）・他の処理が既に `preventDefault` したもの

## 未実装と既知の制限

- カンバンボードの画面が無い。カスタムステータスを列にして、ドラッグでステータス変更と列の並び替えを行う案がある。保存済みビューの `view_type` には `board` があるが、それを描く画面は無い
- マイルストーンの管理画面が無い。マイルストーンは API で作成する
- 既定の種別の補完（マイグレーションの SQL）と、同じプロジェクトへの種別の作成が同時に走ると、`position` が重なることがある。新しい backend をマイグレーションより先に起動したときだけ起きる。並びは `position` と `id` の順で決まるので表示は壊れず、並べ替えを 1 回行うと連番に戻る
- 既定の種別の補完（マイグレーションの backfill）は、マイグレーションの時点で種別が 0 件のプロジェクトだけが対象で、再実行できる。マイグレーションのあとに古い backend が作ったプロジェクトや、マイグレーションの前に管理画面で種別を 1 件足したプロジェクトには入らない。古い backend を止めてから新しい backend を上げ、必要なら backfill の SQL をもう一度流す
- 種別でタスクを絞り込む画面と、一覧の行の種別の表示が無い。絞り込みは API（`task_type_id`）と CLI でできる
- 一括更新（`BulkUpdateFields`）で種別を変えられない。一括作成は各要素の `task_type_id` を受ける
- 依存関係のグラフ表示が無い。タスク詳細の欄で一覧できるだけで、図にして見せる画面は無い

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-05-29 | 削除はソフトデリート（`deleted_at`）とし、物理削除の API を持たない | 記録なし |
| 2026-05-29 | ステータスはプロジェクト単位のカスタムステータスとし、ハードコードしない | 記録なし |
| 2026-05-29 | 連番 ID は `SELECT FOR UPDATE` でアトミックに採番し、`KEY-N` 形式で表示する | 記録なし |
| 2026-05-29 | ラベルは `project_id` でプロジェクト単位にする | 記録なし |
| 2026-10-16 | `planned_start_on` と Soft 締切の前後関係を DB の CHECK でもサーバーの検証でも見ない | 計画用の値で前後が逆でも壊れるものがない。締切は TIMESTAMPTZ のため、日付との比較がタイムゾーン次第で正しい組を弾いてしまう |
| 2026-11-01 | 説明文の上限を 100,000 文字にする | タスク詳細の SSR は Markdown を同期で描画するため、長大な本文で server プロセスを塞がないようにする |
| 2026-11-03 | 親タスクの変更は `PUT /tasks/{id}` の `parent_task_id` / `clear_parent_task_id` で行い、UI はタスク詳細のサブタスク欄に置く | 記録なし |
| 2026-11-04 | 続きを読み足す一覧は `offset` ではなくカーソルを使う | 取得の間にタスクが増減すると `offset` の境界がずれ、境界の行がどちらのページにも出なくなる |
| 2026-11-04 | 「まだ残っているか」の判断に `total` を使わず `next_cursor` を使う | 総数は取得中に動くので、比較では終わらないことがある |
| 2026-11-12 | 担当者全員の完了が必要なタスクでは、未完了の担当者が残るまま完了ステータスへ直接移すのを 409 で止める | 全員がそろうまで完了にならないという題意に素直に合う。本人の移動を自分の分の完了として読む案は、応答でステータスが変わらない更新になり、一覧のドラッグや CLI が黙って戻る |
| 2026-11-12 | PR のマージによる自動完了は未完了の担当者が残るタスクを完了にせず、GitHub Issue の close 同期は対象外にする | マージを黙って通すと設定の意味が無くなる。Issue 側が正なので、止めると開閉が食い違い続ける |
| 2026-11-09 | ブロック関係の UI は既存の GET/POST/DELETE `/relations` をそのまま使い、タスク詳細のサブタスク欄の下に置く | API と仕様書は揃っていて、無かったのは画面だけ |
| 2026-11-09 | 設定で開いた親行は、サブタスクが 0 件なら作成欄を出さず描かない | 親行だけではサブタスクの有無が分からないので全行で取りに行く。0 件の行ごとに作成欄や読み込み中が並ぶと一覧が読めなくなる |
| 2026-11-09 | 設定で開いた親行のサブタスク取得は、フォーカス復帰では取り直さず 30 秒は新鮮として扱う。行の変更による取り直しは残す | 表示中の親行の数だけ取得が立つので、フォーカスのたびに全行を取ると多すぎる。子のステータスなどの反映は行の変更後の取り直しで足りる。ただし行の変更ごとに表示中の親行の数だけ再取得される。`has_subtasks` を API に足せば減らせる |
| 2026-11-09 | リンクの favicon の取得は `/favicon.ico` 固定にし、HTML の `<link rel="icon">` は解析しない | HTML の取得と解析にはサイズと時間の上限が別に要り、相対 URL の解決や候補の選別で実装が膨らむ。無いサイトは汎用アイコンで外部リンクだと分かる |
| 2026-11-09 | favicon の取得に全ホップ合わせた 8 秒の上限と、利用者ごとの取得回数の上限（10 分で 30 回）を置き、サーバーに残す画像を 64 KiB までにする | 認証済みの利用者なら誰でも任意の host を要求できる。1 ホップごとの上限だけではリダイレクトのたびに掛け直されて同時取得の枠を長く占有でき、ワイルドカード DNS の host を連番で叩けば Redis（セッションも載る）を埋められる。回数の上限は、初めて開いた長い文書の外部リンクが通り、連番の取得は 1 時間に 180 件ほどで止まる値にした。キャッシュ済みの host は数えない |
| 2026-11-09 | favicon のリダイレクト先は 443 だけを許す | 任意のポートを指せると、公開 IP のポートの開閉を応答時間から探れる |
| 2026-11-12 | サブタスクの作成時に、未指定の締切と開始予定日へ親の値を入れる。サーバーの作成処理で行い、作成後は追従させない | 画面のサブタスク作成はタイトルだけで、CLI と API も同じ経路を通る。1 か所で入れれば全経路で揃う。子の予定は親と別に動かせる必要がある |
| 2026-11-12 | 説明文のタスクリストの達成率は画面で `description` から数え、API に項目を足さない | 一覧のレスポンスが `description` を含むので足りる。描画器と同じ構文解析器を backend にも持つと、数え方が 2 箇所に分かれる |
| 2026-11-14 | 担当者なしの絞り込みは `assignee_id` の特別な値ではなく、別の bool `unassigned` にする。`assignee_id` との同時指定は 400 | `assignee_id` の型を UUID のまま保てる。両方を満たすタスクは無いので、空の一覧を返すより間違いとして返す |
| 2026-11-16 | 種別はプロジェクト単位の専用の表（`project_task_types`）と `tasks.task_type_id` の列で持つ。1 つのタスクに 0 か 1 つで、既定の種別は持たない | ステータス・ラベル・カスタムフィールドがすべてプロジェクト単位で、テナント単位の定義表とその管理画面は無い。任意にすれば既存タスクの移行が要らず、作成の経路（サブタスク、GitHub Issue の取り込み、レビューからの起票）を変えずに済む。テナント単位（GitHub の Issue types）は、テナント単位の定義表と認可と画面を新しく作ることになる。必須にして既定の種別を持つ案は、既存の全タスクへの埋め込みと全作成経路の対応が要る |
| 2026-11-16 | 種別を `project_custom_fields` の `select` 型の上には作らず、専用の表にする | カスタムフィールドの値は TEXT で、名前を変えると既存の値と切れる。一覧の絞り込みも応答への埋め込みも無い。種別は色・並び・絞り込みが要る |
| 2026-11-16 | 既定の種別（タスク / バグ / 機能）を新規と既存の全プロジェクトに入れ、既存のラベルからの自動移行はしない | ラベルは自由な名前で、どれが種別に当たるかを機械では決められない。1 つのタスクに「バグ」と「新機能」の両方のラベルが付くこともある。既定の 3 件が無いと、既存のプロジェクトで選べる種別が無い |
| 2026-11-16 | タスクの応答は `task_type` を埋め込み、別プロジェクトの種別の指定は 404 にする。定義を変えられる人はラベル・ステータスと同じにする | 一覧の行や CLI の出力で、定義の一覧を別に引かずに名前と色が分かる。単一の参照であるステータスとマイルストーンが 404 を返す。既存の定義の管理がすべてこの規則で、種別だけ規則を変えない |
| 2026-11-16 | 種別の定義の書き込み（作成・更新・並べ替え・削除）はプロジェクト単位の advisory lock で直列にし、プロジェクト行・種別の行・タスク側のロックは取らない。タスクに付ける種別は書く前に確かめるだけにして（`milestone_id` と同じ）、削除と重なったら FK の違反を 404 にする | プロジェクト行はタスクや通知の挿入の外部キーの検査が通る行で、ここを握るとタスクの更新との待ちが循環する。種別の行を握る案も、タスクの作成・更新にロックの順の規則を課し、経路が増えるたびに守り直すことになる。advisory lock は何も持たずに待つので、ほかのロックと輪にならない |

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