概要
ストーリーポイントやバージョンのような、プロジェクト固有の属性をタスクに持たせる機能である。定義はプロジェクトごとに持ち、値はタスクごとに持つ。定義は 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 に値を設定する引数が無い
- 定義のドラッグでの並び替えが無い
