Skip to content

カスタムフィールド

プロジェクト固有の属性(ストーリーポイント・バージョン等)

概要

ストーリーポイントやバージョンのような、プロジェクト固有の属性をタスクに持たせる機能である。定義はプロジェクトごとに持ち、値はタスクごとに持つ。定義は API とプロジェクト設定の画面で管理し、値は API で読み書きする。コアの機能に依存する。

振る舞い

値の形式

全型を文字列で保持し、型ごとの形式はアプリ層で検証する。形式に合わない値は 400 になる。

field_type value の形式 例
text 任意文字列 "メモ"
number 有限の数値として読める文字列 "5"
select options の value のいずれか "s"
date YYYY-MM-DD "2026-06-01"
url http または https の URL "https://..."
checkbox "true" / "false" "true"

定義の検証

  • select 型は options が必須である
  • 空の配列・空の label / value・前後に空白のある value・value の重複は 400 になる
  • select 以外の型に options を渡しても 400 になる
  • field_type は作成後に変えられない

値の更新

値の専用エンドポイントは無い。タスクの作成・更新・取得の custom_field_values で読み書きする。

  • 渡したフィールドだけを UPSERT する
  • null または空文字はその値を消す
  • 同じ field_id の重複と、プロジェクトに無い field_id は 400 になる

必須フィールド

is_required=true のフィールドの扱いは次のとおりである。

  • 値を null や空文字にする入力は、ステータスに関係なく 400 になる
  • タスクのステータスを is_done_state=true へ変更する・完了ステータスで作成するときに、既存の値と同じリクエストの値を合わせて未入力があれば 400 になる
  • 未完了のまま作成・更新するだけなら、必須フィールドが未入力でも通る

値の読み取り

GET /tasks/{id} の custom_field_values は、プロジェクトの全フィールドを position 順に返す。値が無ければ value と display_value は null である。display_value は select 型なら選択肢の label、他の型なら value そのものである。

データ

project_custom_fields

列 型 制約 説明
id UUID PK
project_id UUID NOT NULL, FK→projects CASCADE
name VARCHAR(100) NOT NULL, UNIQUE(project_id, name) 例は “Story Points”, “バージョン”
field_type VARCHAR NOT NULL CHECK text / number / select / date / url / checkbox
options JSONB NULLABLE select 型のみ使用。[{"label":"S","value":"s"},...]
is_required BOOLEAN NOT NULL DEFAULT false
position SMALLINT NOT NULL 表示順
created_at TIMESTAMPTZ NOT NULL DEFAULT now()

task_custom_field_values

列 型 制約 説明
task_id UUID NOT NULL, FK→tasks CASCADE, PK(task_id, field_id)
field_id UUID NOT NULL, FK→project_custom_fields CASCADE, PK(task_id, field_id)
value TEXT NULLABLE 全型を文字列で保持する

列の定義は m20260520000000_initial_schema.rs にある。

API

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

メソッド パス 説明
GET /custom-fields 定義一覧(fields の配列。position 順)
POST /custom-fields 作成
PATCH /custom-fields/{field_id} 更新(name / options / is_required / position)
DELETE /custom-fields/{field_id} 削除(値も CASCADE)

並び順を一括で更新する API は無く、position を 1 件ずつ更新する。POST で position を省略すると、既存の最大値の次になる。

認可

操作 誰が スコープ
定義の取得 プロジェクトに入れる人(テナントオーナーに限らない) read:task
定義の作成・更新・削除 プロジェクトに入れる人(テナントオーナーに限らない) write:task

画面

項目 値
URL /{tenant}/projects/{KEY}/settings
入口 プロジェクト設定の「カスタムフィールド」
コンポーネント components/projects/CustomFieldsSection.vue

定義の一覧・作成・編集・削除を行う。select 型は選択肢を編集できる。

未実装と既知の制限

  • タスク詳細にカスタムフィールドの欄が無く、値の表示も入力もできない。値を読み書きできるのは API だけである。計画では、タスク詳細の右ペインに型ごとの入力欄を並べる
  • CLI に値を設定する引数が無い
  • 定義のドラッグでの並び替えが無い

Type to search…

↑↓ navigate↵ selectEsc close