# PANJIT｜To-Do List（Web UI）V1 產品需求文件（PRD）
**版本**：V1（定版）  
**最後更新**：2025-08-28  
**資料庫**：MySQL（所有資料表皆採前綴 `todo_`）  
**登入**：AD/LDAP（不限僅內網）  
**DueDate 精度**：到 **「日」**  
**Email 寄件者**：以**建立者的 AD Mail**發送（SMTP 需允許代寄或以 Envelope From 配合）  
  
**Excel 匯入**：提供正式模板（含下拉驗證、README）

---

## 1. 背景與目標
- 以 AD 帳號辨識使用者，提供個人/協作化的待辦管理。
- 除固定排程提醒外，提供「**Fire 一鍵提醒**」降低漏辦風險。
- 提供**正式 Excel 模板**以降低匯入錯誤率。

### 成功指標（示例）
- 90% 使用者在 2 週內完成首次建立/匯入待辦。
- 逾期數較導入前下降 30%。
- 主要操作 P95 < 1s；匯入任務成功率 99%。

---

## 2. 使用者與場景
- **建立者**：建立待辦者，預設可見/可編輯。
- **負責人（多人）**：可見/可編輯（與建立者同等）。
- **追蹤者（多人）**：可見但預設不可編輯；可收信。

主要場景：
1) 新增/編輯待辦（可設定多負責人、多追蹤者）。  
2) 清單/日曆檢視、篩選、批次操作。  
3) Fire 一鍵提醒：立即寄發、可寫附註、冷卻與限額管控。  
4) 排程提醒：到期前/當天/逾期 + 週摘要（可開關）。  
5) 匯入：下載模板→填寫→上傳驗證→導入。  

---

## 3. 功能需求

### 3.1 待辦 CRUD 與視圖
- 欄位：
  - 必填：`title`
  - 選填：`description`, `priority(LOW|MEDIUM|HIGH|URGENT)`, `status(NEW|DOING|BLOCKED|DONE)`, `due_date(YYYY-MM-DD)`, `starred`
  - 系統：`id(uuid)`, `created_at`, `completed_at`, `creator_ad`, `creator_display_name`, `creator_email`
- 視圖：列表 + 日曆；支援篩選（狀態、到期區間、加星）與批次操作（狀態、到期日）。
- 可見性：建立者/負責人/追蹤者可見；可編輯者為建立者與負責人。

### 3.2 多負責人/多追蹤者
- 以 AD 帳號多選加入；維護表 `todo_item_responsible`, `todo_item_follower`。

### 3.3 Email 通知
- **排程提醒**（可開關）：到期前 X 天、到期日、逾期 Y 天；週一 09:00 摘要（建議）。
- **Fire 一鍵提醒**：
  - 受信人預設：負責人 + 追蹤者 + 建立者（可調整/去重）。
  - 冷卻/限額：**同一待辦 2 分鐘冷卻**，**每人每日 20 封**。
  - 可附註；所有寄送寫入 `todo_mail_log`。

### 3.4 Excel 匯入
- 下載正式模板（含 README 與下拉驗證）。
- 驗證：必填、日期格式、AD 帳號存在性、重複（同標題 + 近日期）。
- 逐列錯誤報告與「問題列下載」。


---

## 4. 非功能需求
- 效能：一般操作 P95 < 1s；匯入以背景 Job 執行，提供進度查詢。
- 可用性：SMTP 故障不影響 CRUD；提供降級邏輯。
- 監控：`/healthz`（DB/SMTP）；寄送/匯入皆留 `todo_audit_log`。
- 備份：每日快照；保留 7/30 天。

---

## 5. 資料庫（MySQL，前綴 `todo_`）

- `todo_item`：主表（待辦）  
- `todo_item_responsible`：多負責人  
- `todo_item_follower`：多追蹤者  
- `todo_mail_log`：排程/Fire 寄信紀錄  
- `todo_audit_log`：稽核日誌  
- `todo_user_pref`：使用者偏好

```mermaid
erDiagram
  todo_item ||--o{ todo_item_responsible : has
  todo_item ||--o{ todo_item_follower : has
  todo_item ||--o{ todo_mail_log : logs
  todo_item ||--o{ todo_audit_log : audits

  todo_item {{
    char(36) id PK
    varchar title
    text description
    enum status
    enum priority
    date due_date
    datetime created_at
    datetime completed_at
    varchar creator_ad
    varchar creator_display_name
    varchar creator_email
    tinyint starred
  }}

  todo_item_responsible {{
    char(36) todo_id FK
    varchar ad_account
    datetime added_at
  }}

  todo_item_follower {{
    char(36) todo_id FK
    varchar ad_account
    datetime added_at
  }}

  todo_mail_log {{
    bigint id PK
    char(36) todo_id FK
    enum type
    varchar triggered_by_ad
    text recipients
    varchar subject
    enum status
    varchar provider_msg_id
    text error_text
    datetime created_at
    datetime sent_at
  }}

  todo_audit_log {{
    bigint id PK
    varchar actor_ad
    char(36) todo_id FK nullable
    enum action
    json detail
    datetime created_at
  }}

  todo_user_pref {{
    varchar ad_account PK
    varchar email
    datetime updated_at
  }}
```

---

## 6. API（摘要）
- `GET /api/todos`、`POST /api/todos`、`PATCH /api/todos/{{id}}`、`DELETE /api/todos/{{id}}`  
- `POST /api/todos/{{id}}/responsibles`、`POST /api/todos/{{id}}/followers`  
- `POST /api/todos/{{id}}/fire-email`  
- `GET /api/imports/template`、`POST /api/imports`、`GET /api/imports/{{job_id}}`  

---

## 7. 驗收標準
1) AD 登入成功；首登寫入個資。  
2) 多負責人/多追蹤者運作；可見/可編輯權限如預期。  
3) Fire 寄信：預設收件人、冷卻/限額、附註、寄送紀錄。  
4) 排程提醒、週摘要可開關且寄送正確。  
5) 匯入：模板下載、驗證逐列錯誤、成功導入。  
6) 稽核：CRUD/匯入/寄信皆可查。

---

## 8. 風險與對策
- SMTP 代寄受限 → 以系統 Envelope From + `Reply-To:` 建立者。  
  
- 匯入錯誤率高 → 強制模板、下拉驗證、逐列錯誤檔回饋。

---

## 9. 附件
- 正式 Excel 模板：`todo_import_template_v1_formal.xlsx`