177 lines
5.4 KiB
Markdown
177 lines
5.4 KiB
Markdown
# 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`
|