# Proposal: Add Custom Fields

**Change ID:** `add-custom-fields`
**Issue Reference:** `FEAT-001` (issues.md)
**Status:** Draft
**Author:** Claude
**Date:** 2026-01-05

## Summary

實作自定義欄位功能，允許專案管理者為任務新增自定義欄位，包含文字、數字、下拉選單、日期、人員標籤和公式等類型。

## Motivation

目前系統僅支援固定的任務欄位（標題、描述、狀態、優先級等）。不同專案可能需要追蹤特定資料，例如：
- 半導體製程：封裝類型、機台編號、預計良率
- 軟體開發：Sprint 編號、Story Points、影響版本
- 行銷活動：活動代碼、預算類別、目標受眾

自定義欄位讓專案管理者可以根據需求彈性擴展任務資料結構。

## Scope

### In Scope
- Backend: CustomField 和 TaskCustomValue models
- Backend: Custom fields CRUD API endpoints
- Backend: Formula field 計算引擎
- Frontend: Custom fields 管理 UI（專案設定頁面）
- Frontend: Task form 動態渲染自定義欄位
- Frontend: Task list/kanban 顯示自定義欄位值

### Out of Scope
- 跨專案共用欄位定義
- 自定義欄位匯入/匯出
- 複雜公式函數（僅支援基本數學運算）

## Design Decisions

### 欄位類型
| Type | 說明 | 儲存格式 |
|------|------|----------|
| text | 單行文字 | VARCHAR |
| number | 數字 | DECIMAL |
| dropdown | 下拉選單 | VARCHAR (選項儲存於 options JSON) |
| date | 日期 | DATE |
| person | 人員標籤 | UUID (FK -> users) |
| formula | 公式計算 | DECIMAL (計算結果) |

### 公式欄位
- 支援基本數學運算：`+`, `-`, `*`, `/`
- 可引用其他數字欄位：`{field_name}`
- 可引用任務內建欄位：`{original_estimate}`, `{time_spent}`
- 範例公式：`{time_spent} / {original_estimate} * 100`

### API 設計
```
POST   /api/projects/{project_id}/custom-fields     # 新增欄位定義
GET    /api/projects/{project_id}/custom-fields     # 列出所有欄位
PUT    /api/custom-fields/{field_id}                # 更新欄位定義
DELETE /api/custom-fields/{field_id}                # 刪除欄位（含所有值）

# 欄位值透過現有 task API 操作
PUT    /api/tasks/{task_id}                         # body 包含 custom_values
```

## Affected Specs

| Spec | Change Type |
|------|-------------|
| task-management | MODIFIED (Custom Fields requirement 實作細節) |

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| 公式欄位循環引用 | 建立欄位時驗證公式不引用自己或形成循環 |
| 大量自定義欄位影響效能 | 限制每專案最多 20 個自定義欄位 |
| 刪除欄位遺失資料 | 刪除前顯示確認對話框，說明將刪除所有相關值 |

## Dependencies

- 無外部依賴
- 需要現有 tasks API 支援