1ST

2025-08-29 16:25:46 +08:00
commit b0c86302ff
65 changed files with 19786 additions and 0 deletions
--- a/PRD.md
+++ b/PRD.md
@@ -0,0 +1,176 @@
+# 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`