概要
タスクの基本操作を補う機能をまとめたページである。プロジェクト内の全文検索と類似タスク候補、一括操作、保存済みビュー、Drive のファイルの添付、テナント内を横断するマイタスクを扱う。コアに依存し、ファイル添付は Drive にも依存する。
振る舞い
全文検索
検索条件は次の OR である。件数と一覧で同じ条件を使う。
search_vector @@ plainto_tsquery('pg_catalog.simple', q)(語の一致)title/descriptionのILIKE '%q%'(部分一致。日本語の中間一致・2 文字の語もここで拾う)q <% title(word_similarity。typo などの表記ゆれ)
対象は削除されていないタスクで、アーカイブ済みも含む。コメントの本文は検索しない。検索範囲はプロジェクト内である。
エンジンは pg_trgm を標準とする。PostgreSQL 同梱の contrib で、PG13 以降は trusted extension なので DB への CREATE 権限で導入できる。DB の lc_ctype が C だと pg_trgm は日本語の trigram を作らないので、マイグレーションは show_trgm('日本語テスト') が空なら止まる。
USE_PG_BIGM=true で pg_bigm の任意の経路へ切り替えられる。拡張は運用側で別途導入する。この経路は次のとおりに動く。
title/descriptionの ILIKE だけで当てる。tsvectorとword_similarityは使わない- 更新日時の新しい順に返し、
scoreは常に 1.0 になる
設計はタスク類似検索に書く。
検索語の中のメンション
説明文のメンションはメンションのマーカー(<@利用者ID>)で保存され、本文に名前は入らない。検索語の中の @名 は、その名の者をメンションした説明文にも当たる。名前は検索のときに引くので改名に追従する。範囲・同名の扱い・抜粋はコメント・アクティビティの検索に書く。
検索結果の抜粋とスコア
- 並びは title に一致する行が先で、次にスコアの降順、同点は id 順である
highlightは title + description から検索語の最初の一致(大文字小文字を無視)を<em>で囲んだ抜粋である。前後の文字は HTML エスケープする- 表記ゆれでのみ一致した行は
<em>なしの先頭抜粋になる scoreはts_rankとword_similarityの大きい方で、ILIKE のみで一致した行は 0 になりうる
類似タスク候補
タスク作成時の重複候補とタスク詳細の「似ているタスク」に使う。title 同士の trigram 類似度(title % $title、pg_trgm.similarity_threshold 既定 0.3)で候補を取る。候補は同一プロジェクト内の削除されていないタスクに限り、同じテナントの他プロジェクトは出さない。並びは similarity(title, $title) の降順で、同点は id 順である。
バルク操作
task_ids は 1〜100 件で、重複は 1 件にまとめる。タスクごとに別のトランザクションで処理するので、1 件の失敗は他のタスクに影響しない。アクティビティはタスクごとに記録し、GitHub 連携のあるタスクは書き戻しを積む。
単体の更新 API と違って、次のことは行わない。
status_changed・assignedの通知の送信とウォッチャーの追加- 完了ステータスへ移すときの必須カスタムフィールドの確認
- 完了済みスプリントへの割り当ての拒否
一括作成
POST /tasks/bulk-create は、単体作成と同じ形のタスクを 1〜100 件まとめて作る。認可(write:task スコープとプロジェクトへのアクセス)と検証は単体作成と同じ関数を通すので、担当者の確認・ラベル・カスタムフィールド・メンション通知・アクティビティ・Webhook も単体作成と同じ規則で働く。
- 全件を 1 つのトランザクションで処理する。全件作られるか、1 件も作られないかのどちらかで、バルク操作と違い部分成功は無い
- 要素の失敗は 400 になり、メッセージは
tasks[i]: 理由の形である(iは 0 始まり。理由はnot-found/forbidden/conflict/bad-requestか、検証の詳細文)。直して丸ごと再送する - 通知・アクティビティ・Webhook は件数分出る(
task.createdが 100 件なら 100 回届く) - 同じリクエスト内のタスクは互いに参照できない。
parent_task_idなどは既存のタスクの ID だけを受け付ける。親子にするときは親を先に作り、次のリクエストで子を作る - 採番のためにプロジェクトの採番行をロックするので、処理中は同じプロジェクトの他の作成が待たされる
- ロック順は単体作成と同じ「採番行 → スプリント」である。要素のスプリントは UUID 昇順にまとめてロックするので、入力の並びにかかわらずスプリント完了処理(UUID 昇順)とデッドロックしない
- 再送の重複防止(冪等キー)は無い。応答が得られなかったときは一覧で確かめてから再送する
保存済みビュー
サーバーは filters と sort の中身を検証せず、受け取った JSON をそのまま保存して返す。想定している filters の形は次のとおりである。
{
"status_ids": ["uuid"],
"priority": ["high", "critical"],
"assignee_ids": ["uuid"],
"label_ids": ["uuid"],
"sprint_id": "uuid",
"milestone_id": "uuid",
"deadline_before": "2026-07-01",
"is_archived": false,
"has_no_assignee": false
}ファイル添付
添付は Drive の drive_files をタスクへ紐付ける中間テーブルである。同じ (task_id, drive_file_id) は 1 行だけで、source はその行の由来を表す。
body の行は Drive の Markdown ファイルを保存したときに自動で作られ、本文から参照が消えると自動で消える(Drive の本文からのタスク参照)。結び付け先は手動添付と同じ範囲で、プロジェクトファイルから別プロジェクトのタスクへの参照はリンクにならない。
手動と自動(source)の優先規則は次のとおりである。
| 操作 | 既存の行 | 結果 |
|---|---|---|
POST(手動添付) |
なし | manual で作成(201) |
POST |
body |
manual に昇格(200)。解除できるのは昇格させた利用者とテナントオーナー |
POST |
manual |
409 Conflict |
| 本文に参照あり | なし | body で作成 |
| 本文に参照あり | manual |
そのまま。body に書き換えない |
| 本文から参照が消えた | body |
削除 |
| 本文から参照が消えた | manual |
そのまま |
DELETE |
body |
409 Conflict。本文から抽出した参照は本文を編集して外す |
DELETE |
manual |
204 |
タスク詳細(GET /tasks/{id}。作成・更新・一括作成の応答も同じ形)は attachments に添付の一覧と同じ要素を新しい順で埋め込む。タスク一覧(GET /tasks)には載せない(件数が増えると重くなる)。認可は添付の一覧と同じで、詳細を読める利用者は添付の名前とコンテンツ URL も読める。
プレビューはサーバーで生成しない。API はコンテンツ URL と MIME タイプを返し、画面がブラウザで表示する。
マイタスク
テナントの中で、プロジェクトを横断して自分が担当のタスクを返す。アーカイブ済みと削除済みは除き、期限の近い順に並べる。期限の無いタスクは最後に置く。プロジェクトだけのゲストには、明示メンバーのプロジェクトの分だけを返す。
一覧の条件式
一覧 API の q はプロジェクト内の条件式を解釈する。空白で並べた項は AND、同じ条件のカンマは OR、先頭の - は除外、二重引用符は一続きの語を表す。未知のキーは検索語になる。検索語はタイトル・説明・削除されていないコメントに部分一致する。説明とコメントは、メンションのマーカー(<@利用者ID>)を語に含まれない区切りに置き換えた本文に当てるので、16 進の文字だけの語(42、add など)がマーカーの中の UUID に当たることはなく、マーカーをはさんだ前後の文字をつないだ語(確認<@ID>お願い に対する「確認お願い」)にも当たらない。@名 の検索語だけがマーカーに当たる。/tasks/search の全文検索は従来どおりタイトルと説明だけを対象にする。
| キー | 値 |
|---|---|
status |
ステータス名 |
assignee、author |
利用者名、@me |
label |
ラベル名 |
priority |
critical_fire、critical、high、medium、low、trivial |
due |
overdue、<Nd。N は 1〜365 |
no |
assignee、label |
is |
archived、subtask |
in |
title、comment |
sort |
created、updated、key、status、title、assignee、priority、due。末尾の -asc、-desc で向きを指定する。作成日時と更新日時は降順のみ |
in と sort は除外できない。条件式は 1,000 文字、30 項までとする。既知のキーの不正値は 400 とし、invalid-task-query とエラー配列を返す。エラーコードは unknown-value、invalid-value、empty-value、not-negatable、duplicate-sort、conflicting-sort、too-long である。
一致箇所は matches にタスク ID ごとに返す。タイトル全体と、説明・最新の一致コメント各 1 件を文字列区間の配列にする。コメントは投稿者と日時も返す。HTML は返さない。GET /tasks/facets はアーカイブされていないタスクの候補件数を返し、一覧と同じ read:task の認可を使う。
データ
tasks の検索用の列とインデックスは次のとおりである。
| 列・インデックス | 内容 |
|---|---|
search_vector |
tsvector の生成列(STORED)。to_tsvector('pg_catalog.simple', coalesce(title, '') || ' ' || coalesce(description, '')) |
idx_tasks_search_vector |
search_vector の GIN |
idx_tasks_title_trgm |
title の GIN(gin_trgm_ops)。部分一致・表記ゆれ用で、title のみ |
USE_PG_BIGM=true の環境では、この生成列の代わりに title と description の gin_bigm_ops を張る。
project_task_views の列は次のとおりである。idx_project_task_views_project(project_id)と idx_project_task_views_project_created_by(project_id, created_by)を張る。
| 列 | 型 | 制約 |
|---|---|---|
id |
UUID | PK |
project_id |
UUID | NOT NULL, FK→projects CASCADE |
created_by |
UUID | NOT NULL, FK→users CASCADE |
name |
VARCHAR(100) | NOT NULL |
is_shared |
BOOLEAN | NOT NULL DEFAULT false |
filters |
JSONB | NOT NULL DEFAULT '{}' |
sort |
JSONB | NOT NULL DEFAULT '{}' |
view_type |
VARCHAR | NOT NULL DEFAULT 'list'。board / list / table |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() |
updated_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() |
task_attachments の列は次のとおりである。UNIQUE (task_id, drive_file_id) と idx_task_attachments_task(task_id)を張る。
| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
id |
UUID | PK | |
task_id |
UUID | NOT NULL, FK→tasks CASCADE | |
drive_file_id |
UUID | NOT NULL, FK→drive_files CASCADE | |
created_by |
UUID | NOT NULL, FK→users CASCADE | |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() | |
source |
VARCHAR(16) | NOT NULL DEFAULT 'manual' |
manual(手動添付)または body(Drive の Markdown 本文から抽出) |
定義は次の migration にある。
- m20260520000000_initial_schema.rs:
search_vector、project_task_views、task_attachments - m20261016010000_task_attachments_source.rs:
task_attachments.source - m20261020000000_tasks_title_trgm.rs:
idx_tasks_title_trgm
API
マイタスク以外のパスはプロジェクト配下(/v1/tenants/{tenant_id}/projects/{project_id})の相対で書く。
| メソッド | パス | 説明 |
|---|---|---|
| GET | /tasks?q=通知 |
通常一覧の条件式による絞り込み |
| GET | /tasks/facets |
条件候補の件数 |
| GET | /tasks/search?q=OAuth&limit=20&offset=0 |
全文検索 |
| GET | /tasks/similar?title=ログイン画面&exclude_task_id=<uuid>&limit=5 |
類似タスク候補 |
| POST | /tasks/bulk |
一括操作 |
| POST | /tasks/bulk-create |
一括作成 |
| GET | /task-views |
一覧。自分のビューと共有ビューを名前順で返す({ "views": [...] }) |
| POST | /task-views |
作成。view_type は board / list / table のいずれか |
| PATCH | /task-views/{view_id} |
更新 |
| DELETE | /task-views/{view_id} |
削除 |
| GET | /tasks/{id}/attachments |
添付の一覧({ "attachments": [...] })。新しい順。タスク詳細の attachments と同じ要素 |
| POST | /tasks/{id}/attachments |
Drive ファイルを紐付ける。先に Drive API でアップロードして drive_file_id を取得し、{ "drive_file_id": "uuid" } を送る |
| DELETE | /tasks/{id}/attachments/{attachment_id} |
紐付けを解除する。Drive 本体は残る |
| GET | /v1/tenants/{tenant_id}/users/me/tasks?filter=today&limit=50 |
マイタスク |
| GET | /v1/tenants/{tenant_id}/users/me/personal-project |
個人プロジェクトを返す。無ければ自動で作る |
/tasks/search の規則は次のとおりである。応答は tasks(id / seq_id / title / highlight / score)と total を持つ。
qは trim 後に空なら 400 を返すlimitは既定 20、上限 100 で、超過は丸める
/tasks/similar のパラメータは次のとおりである。応答は tasks(id / seq_id / title / score)を持つ。
| パラメータ | 必須 | 既定 | 制約 |
|---|---|---|---|
title |
○ | trim 後に空、または 255 文字(文字数)を超えたら 400 | |
exclude_task_id |
なし | 候補から除くタスク。詳細画面で自分自身を除く | |
limit |
5 | 上限 20。超過は 20 に丸める |
/tasks/bulk の update のフィールドは次のとおりである。どれも省略できる。
| フィールド | 動作 |
|---|---|
status_id |
ステータスを変える。同じステータスなら何もしない |
assignee_id |
担当者を 1 人追加する。役割は assignee で、既に担当なら何もしない。プロジェクトに入れない利用者はそのタスクの失敗になる |
add_label_ids |
ラベルを追加する。上書きではない。プロジェクトに無いラベルはそのタスクの失敗になる |
remove_label_ids |
ラベルを外す。未付与・プロジェクト外の ID は無視する。add_label_ids と同じ ID を含むとリクエスト全体が 400 になる |
sprint_id / clear_sprint_id |
スプリントを設定する / 解除する。両方あれば解除を優先する |
応答は updated(件数)と failed(task_id と reason の配列)を持つ。reason は not-found / forbidden / conflict / bad-request などである。担当者全員の完了が必要なタスクを、未完了の担当者が残るまま完了ステータスへ移そうとしたときは assignees-not-done になる(コア)。同じ要求で assignee_id を足すときは、足した担当者を含めて判定する。
/tasks/bulk-create のリクエストは tasks の配列で、各要素は単体作成(POST /tasks)のリクエストと同じ形である。件数が 1〜100 の範囲外なら 400 を返す。
{
"tasks": [
{ "title": "1 件目", "status_id": "uuid" },
{ "title": "2 件目", "status_id": "uuid", "assignees": [{ "user_id": "uuid", "role": "assignee" }] }
]
}応答は 201 Created で、tasks に作成したタスクを入力と同じ順で返す。各要素は単体作成の応答と同じ形である。
POST /tasks/{id}/attachments は、別のテナントのファイルと別のプロジェクトに属するファイルに 403 を返す。応答は id / drive_file_id / name / mime_type / size / url(コンテンツ URL)/ created_at / created_by(添付した利用者)/ source を持つ。created_by は、画面が解除を出す相手を決めるために返す。この欄を返さない古いサーバーの応答は、CLI が欠けたまま読める。
マイタスクのパラメータは次のとおりである。応答は { "tasks": [...], "total": N } で、各タスクは seq_key(KEY-N)と project・status の要約を持つ。
| パラメータ | 既定 | 内容 |
|---|---|---|
filter |
all |
all / today(締切が今日)/ week(締切が今週、月〜日)/ overdue(締切が今日より前)/ no_due_date(締切なし)。それ以外は 400。締切は COALESCE(soft_deadline, hard_deadline) で、ホームと同じ判定である。today / week / overdue は完了済みを除く |
timezone |
UTC |
「今日」「今週」を決める IANA タイムゾーン名。不正な名前は 400 |
include_personal |
true | 個人プロジェクトのタスクを含めるか |
project_id |
なし | プロジェクトで絞る |
done |
なし | false で未完了(完了ステータスでない)だけ、true で完了済みだけを返す。未指定なら絞らない。total も絞り込み後の件数になる。today / week / overdue は元から未完了だけなので、done=true と組み合わせると 0 件になる |
limit / offset |
50 / 0 | limit の上限は 200 |
認可
| 操作 | 誰が | スコープ |
|---|---|---|
| 検索・類似タスク候補 | プロジェクトにアクセスできる利用者 | read:task |
| 一括操作 | プロジェクトにアクセスできる利用者 | write:task |
| 一括作成 | プロジェクトにアクセスできる利用者(要素ごとの認可は単体作成と同じ) | write:task |
| ビューの一覧 | プロジェクトにアクセスできる利用者 | read:task |
| ビューの作成 | プロジェクトにアクセスできる利用者 | write:task |
| ビューの更新・削除 | 作成者またはテナントオーナー | write:task |
添付の一覧(タスク詳細の attachments も同じ) |
プロジェクトにアクセスできる利用者 | read:task |
| 添付の紐付け | プロジェクトにアクセスできる利用者 | write:task |
| 添付の解除 | 添付の作成者またはテナントオーナー | write:task |
| マイタスク | テナントの利用者。プロジェクトだけのゲストは明示メンバーのプロジェクトの分だけ | read:task |
画面
検索
タスク一覧の検索欄は条件式を Enter で確定し、通常の一覧 API に q として送る。絞り込み中もステータスのグループと担当・期限・優先度を表示し、サブタスクは平らに並べる。条件は灰色のチップと絞り込みボタンから変更でき、URL の ?q= に保存する。ボタンは、選ばれている値を大小と @ の違いに関わらず見分け、同じキーの項が複数あっても、その値を持つ項から外す。旧 URL の ?label= はラベル名の条件へ移すが、ラベル一覧の取得に失敗したときは移さずに URL から落とす。一致したタイトルは灰色で塗り、説明とコメントは出所付きの抜粋を行の下に表示する。入力中は候補と件数を示す。Enter は入力をそのまま確定し、部分一致の候補は矢印キーかポインターで選んだ場合だけ入力を置き換える(ポインターで触れただけの候補も選んだものとして扱う)。確定したあとは、次の入力・↑↓ キー・入力欄のクリック・入力欄への再フォーカスまで候補を出さない。未設定の候補は自動選択しない。? から書き方を確認できる。
類似タスク
タスク作成ダイアログと詳細に、/tasks/similar の結果を出す(CreateTaskDialog・SimilarTasksList)。
添付のプレビュー
タスク詳細の TaskAttachments が添付の一覧・アップロードしての添付・解除を行う。解除の × は、添付の作成者とテナントオーナーにだけ出し、押すと確認のダイアログを挟む。解除してもファイルは Drive に残る。プレビューはダイアログで表示し、MIME タイプで出し分ける。
| MIME タイプ | 表示 |
|---|---|
image/png・jpeg・gif・webp・avif(25MB まで) |
画像を表示 |
application/pdf(25MB まで) |
PDF を表示 |
text/*・application/json(1MB まで) |
テキストを表示 |
| その他 | ファイル名とダウンロードリンク |
My Tasks
/{tenant}/my-tasks(pages/@tenant/my-tasks/+Page.vue)がマイタスクの API を使う。行にはステータスを表示する。完了にする操作は持たず、完了はホームから行う。タブと読み込んだ件数は URL(?tab=・?shown=)に持ち、タスクを開いて戻っても同じタブと件数で開き直す。
コンポーネント
| 役割 | ファイル |
|---|---|
| タスク一覧の検索 | pages/@tenant/projects/@projectKey/tasks/+Page.vue、components/tasks/query/、lib/task-query/ |
| 類似タスク | components/tasks/SimilarTasksList.vue / composables/useSimilarTasks.ts |
| 添付 | components/tasks/TaskAttachments.vue |
| My Tasks | pages/@tenant/my-tasks/+Page.vue |
未実装と既知の制限
- 一括操作に優先度・マイルストーンの変更、担当者の削除、アーカイブ、削除が無い
- 保存済みビューの適用(
GET /tasks?view_id=uuid)が無い。GET /tasksはview_idを受け取らないので、ビューのfiltersを読んで一覧のクエリへ変換するのはクライアントの仕事である - グローバルサーチ(Cmd+K / Ctrl+K でタスクを横断検索する画面)が無い
- バルク操作の画面が無い。タスク一覧でチェックボックスを選択するとツールバーが出現し、ステータス・ラベル等を一括変更する案がある
- 保存済みビューの画面が無い。左サイドバーに一覧を表示し、現在のフィルター条件から「ビューとして保存」する案がある
- サムネイルの生成が無い。画像は
imagecrate でのリサイズ、動画はffprobe+ffmpegによるバックグラウンドジョブでの抽出を想定している。動画サムネイルの生成にはffprobe/ffmpegのサーバーへのインストールが要る - サムネイルの表示と動画のインラインプレーヤーが無い
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-10-16 | プロジェクトファイルから別プロジェクトのタスクへの参照はリンクにしない | 別プロジェクトのタスクの添付一覧からファイル名が、元のプロジェクトに入れない人に見えてしまう |
| 2026-10-20 | 日本語全文検索のエンジンは pg_trgm を標準とする |
PostgreSQL 標準の tsvector(pg_catalog.simple)は空白・記号でしか語を切らず、日本語の部分一致は取れない |
| 2026-10-20 | pg_bigm は USE_PG_BIGM の任意の経路として残す |
記録なし |
| 2026-10-20 | Meilisearch 等の外部検索エンジンは導入しない | 横断検索や意味的な類似が必要になった時点で再検討する |
| 2026-11-11 | タスク詳細の応答に添付を埋め込み、一覧には載せない | 詳細を読むだけで本文が前提にする添付が分かるようにする。一覧は件数が増えると重くなる |
| 2026-11-14 | マイタスクの未完了だけの絞り込みは done パラメータで行い、filter=all の既定は変えない |
既定を変えると Web の My Tasks と my complete の検索が完了済みを見失う。名前と意味はタスク一覧に足す予定の done に揃える |
| 2026-11-15 | 一覧の検索を条件式に統合し、式は backend で解釈する。コメントも検索し、既存の /tasks/search は残す |
通常の一覧の状態と操作を保つ。コメントは既存索引でタスクごとに調べ、マイグレーションは追加しない |
