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

# カスタムフィールド

## 概要

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

## 振る舞い

### 値の形式

全型を文字列で保持し、型ごとの形式はアプリ層で検証する。形式に合わない値は 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` は作成後に変えられない

### 値の更新

値の専用エンドポイントは無い。[タスクの作成・更新・取得](https://docs.koyori.app/dev/features/tasks/core)の `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](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/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 に値を設定する引数が無い
- 定義のドラッグでの並び替えが無い

Source: https://docs.koyori.app/dev/features/tasks/custom-fields/index.mdx
