feat: enhance weekly report and realtime notifications
Weekly Report (fix-weekly-report): - Remove 5-task limit, show all tasks per category - Add blocked tasks with blocker_reason and blocked_since - Add next week tasks (due in coming week) - Add assignee_name, completed_at, days_overdue to task details - Frontend collapsible sections for each task category - 8 new tests for enhanced report content Realtime Notifications (fix-realtime-notifications): - SQLAlchemy event-based notification publishing - Redis Pub/Sub for multi-process broadcast - Fix soft rollback handler stacking issue - Fix ping scheduling drift (send immediately when interval expires) - Frontend NotificationContext with WebSocket reconnection Spec Fixes: - Add missing ## Purpose sections to 5 specs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
beabigegg
119
openspec/changes/archive/2025-12-30-fix-weekly-report/design.md
Normal file
119
openspec/changes/archive/2025-12-30-fix-weekly-report/design.md
Normal file
@@ -0,0 +1,119 @@
|
||||
## Context
|
||||
|
||||
automation spec 定義週報須包含：已完成、進行中、逾期、阻礙中、下週預計任務清單。現行實作僅提供數量統計與部分摘要。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 週報內容包含完整任務清單
|
||||
- 新增阻礙中任務清單
|
||||
- 新增下週預計完成任務清單
|
||||
|
||||
**Non-Goals:**
|
||||
- 不實作週報自訂欄位篩選
|
||||
- 不實作週報匯出 PDF/Excel
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 週報內容結構
|
||||
|
||||
**Decision:** 擴充 content JSON 結構
|
||||
|
||||
**Current:**
|
||||
```json
|
||||
{
|
||||
"summary": { "completed_count": 5, "in_progress_count": 3, ... },
|
||||
"projects": [
|
||||
{
|
||||
"completed_tasks": [{"id": "...", "title": "..."}], // 限制 5 筆
|
||||
"overdue_tasks": [...] // 限制 5 筆
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Proposed:**
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"completed_count": 5,
|
||||
"in_progress_count": 3,
|
||||
"overdue_count": 2,
|
||||
"blocked_count": 1,
|
||||
"next_week_count": 4,
|
||||
"total_tasks": 15
|
||||
},
|
||||
"projects": [
|
||||
{
|
||||
"project_id": "uuid",
|
||||
"project_title": "Project Name",
|
||||
"completed_tasks": [
|
||||
{"id": "...", "title": "...", "completed_at": "ISO8601", "assignee_name": "..."}
|
||||
],
|
||||
"in_progress_tasks": [
|
||||
{"id": "...", "title": "...", "assignee_name": "...", "due_date": "ISO8601"}
|
||||
],
|
||||
"overdue_tasks": [
|
||||
{"id": "...", "title": "...", "due_date": "ISO8601", "days_overdue": 3}
|
||||
],
|
||||
"blocked_tasks": [
|
||||
{"id": "...", "title": "...", "blocker_reason": "...", "blocked_since": "ISO8601"}
|
||||
],
|
||||
"next_week_tasks": [
|
||||
{"id": "...", "title": "...", "due_date": "ISO8601", "assignee_name": "..."}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 阻礙任務識別
|
||||
|
||||
**Decision:** 查詢 Blocker 表關聯
|
||||
|
||||
```python
|
||||
# 取得有未解除阻礙的任務
|
||||
blocked_task_ids = db.query(Blocker.task_id).filter(
|
||||
Blocker.resolved_at.is_(None)
|
||||
).subquery()
|
||||
|
||||
blocked_tasks = db.query(Task).filter(
|
||||
Task.project_id.in_(project_ids),
|
||||
Task.id.in_(blocked_task_ids)
|
||||
).all()
|
||||
```
|
||||
|
||||
### 3. 下週預計任務
|
||||
|
||||
**Decision:** due_date 在下週一至週日
|
||||
|
||||
```python
|
||||
next_week_start = week_end # 本週末 = 下週初
|
||||
next_week_end = next_week_start + timedelta(days=7)
|
||||
|
||||
next_week_tasks = db.query(Task).filter(
|
||||
Task.project_id.in_(project_ids),
|
||||
Task.due_date >= next_week_start,
|
||||
Task.due_date < next_week_end,
|
||||
Task.status.not_in(["done", "completed"])
|
||||
).all()
|
||||
```
|
||||
|
||||
### 4. 任務明細欄位
|
||||
|
||||
**Decision:** 包含以下欄位供顯示
|
||||
|
||||
| 任務類型 | 額外欄位 |
|
||||
|---------|---------|
|
||||
| completed | completed_at (updated_at), assignee_name |
|
||||
| in_progress | assignee_name, due_date |
|
||||
| overdue | due_date, days_overdue |
|
||||
| blocked | blocker_reason, blocked_since |
|
||||
| next_week | due_date, assignee_name |
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| 大量任務導致 content JSON 過大 | 評估後續加入分頁或限制 |
|
||||
| 阻礙查詢需 JOIN | 使用 subquery 減少 N+1 |
|
||||
@@ -0,0 +1,37 @@
|
||||
# Change: Fix Weekly Report Content Alignment
|
||||
|
||||
## Why
|
||||
現行 ReportService.get_weekly_stats 與 automation spec 的週報內容要求有差距：
|
||||
1. 任務清單僅顯示 5 筆摘要，spec 要求完整清單
|
||||
2. 未包含阻礙中任務清單 (blocker_flag = true)
|
||||
3. 未包含下週預計完成任務 (due_date 在下週)
|
||||
|
||||
## What Changes
|
||||
- **ReportService** - 擴充 get_weekly_stats 回傳完整任務明細
|
||||
- **Report Content** - 新增 blocked_tasks 與 next_week_tasks 欄位
|
||||
- **ReportHistory** - content JSON 結構擴充
|
||||
|
||||
## Impact
|
||||
- Affected specs: `automation`
|
||||
- Affected code:
|
||||
- `backend/app/services/report_service.py` - 擴充週報內容
|
||||
- `frontend/src/components/WeeklyReportPreview.tsx` - 顯示完整清單
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Backend Report Enhancement
|
||||
- 擴充 get_weekly_stats 回傳完整任務清單
|
||||
- 新增 blocked_tasks 欄位
|
||||
- 新增 next_week_tasks 欄位
|
||||
|
||||
### Phase 2: Frontend Display
|
||||
- 更新 WeeklyReportPreview 顯示完整清單
|
||||
- 可摺疊/展開的任務分類區塊
|
||||
|
||||
## Dependencies
|
||||
- automation (已完成)
|
||||
- collaboration (blocker 功能)
|
||||
|
||||
## Technical Decisions
|
||||
- 任務清單不設上限，由前端分頁或摺疊處理
|
||||
- 下週預計任務以 due_date 在下週一至週日為準
|
||||
@@ -0,0 +1,38 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Automated Weekly Report
|
||||
系統 SHALL 每週五下午 4:00 自動彙整完整任務清單發送給主管。
|
||||
|
||||
#### Scenario: 週報內容完整清單
|
||||
- **GIVEN** 週報生成中
|
||||
- **WHEN** 系統彙整資料
|
||||
- **THEN** 週報包含各專案的：
|
||||
- 本週已完成任務清單（含 completed_at, assignee_name）
|
||||
- 進行中任務清單（含 assignee_name, due_date）
|
||||
- 逾期任務警示（含 due_date, days_overdue）
|
||||
- 阻礙中任務清單（含 blocker_reason, blocked_since）
|
||||
- 下週預計完成任務（含 due_date, assignee_name）
|
||||
- **AND** 不設任務數量上限
|
||||
|
||||
#### Scenario: 阻礙任務識別
|
||||
- **GIVEN** 任務有未解除的 Blocker 記錄
|
||||
- **WHEN** 週報查詢阻礙任務
|
||||
- **THEN** 系統查詢 Blocker 表 resolved_at IS NULL 的任務
|
||||
- **AND** 顯示阻礙原因與開始時間
|
||||
|
||||
#### Scenario: 下週預計任務
|
||||
- **GIVEN** 任務的 due_date 在下週範圍內
|
||||
- **WHEN** 週報查詢下週預計任務
|
||||
- **THEN** 系統篩選 due_date >= 下週一 且 < 下週日
|
||||
- **AND** 排除已完成狀態的任務
|
||||
|
||||
## MODIFIED Technical Notes
|
||||
|
||||
- 週報 content JSON 結構擴充：
|
||||
- summary: 包含 blocked_count, next_week_count
|
||||
- projects[].completed_tasks: 無數量限制，含 completed_at, assignee_name
|
||||
- projects[].in_progress_tasks: 新增欄位
|
||||
- projects[].blocked_tasks: 新增欄位，含 blocker_reason, blocked_since
|
||||
- projects[].next_week_tasks: 新增欄位，含 due_date, assignee_name
|
||||
- 阻礙任務透過 Blocker 表 subquery 查詢
|
||||
- 下週計算以本週結束後 7 天為範圍
|
||||
@@ -0,0 +1,38 @@
|
||||
## Phase 1: Backend Report Enhancement
|
||||
|
||||
### 1.1 ReportService 擴充
|
||||
- [x] 1.1.1 移除 completed_tasks/overdue_tasks 的 5 筆限制
|
||||
- [x] 1.1.2 新增 in_progress_tasks 完整清單
|
||||
- [x] 1.1.3 新增 blocked_tasks 查詢與清單
|
||||
- [x] 1.1.4 新增 next_week_tasks 查詢與清單
|
||||
- [x] 1.1.5 擴充 summary 包含 blocked_count 與 next_week_count
|
||||
|
||||
### 1.2 任務明細欄位
|
||||
- [x] 1.2.1 completed_tasks 加入 completed_at, assignee_name
|
||||
- [x] 1.2.2 in_progress_tasks 加入 assignee_name, due_date
|
||||
- [x] 1.2.3 overdue_tasks 加入 days_overdue 計算
|
||||
- [x] 1.2.4 blocked_tasks 加入 blocker_reason, blocked_since
|
||||
- [x] 1.2.5 next_week_tasks 加入 due_date, assignee_name
|
||||
|
||||
### 1.3 Testing - Phase 1
|
||||
- [x] 1.3.1 週報內容結構測試
|
||||
- [x] 1.3.2 阻礙任務查詢測試
|
||||
- [x] 1.3.3 下週預計任務測試
|
||||
|
||||
## Phase 2: Frontend Display
|
||||
|
||||
### 2.1 WeeklyReportPreview 更新
|
||||
- [x] 2.1.1 新增 BlockedTasksSection 元件
|
||||
- [x] 2.1.2 新增 NextWeekTasksSection 元件
|
||||
- [x] 2.1.3 更新 CompletedTasksSection 顯示完整清單
|
||||
- [x] 2.1.4 更新 InProgressTasksSection 顯示完整清單
|
||||
- [x] 2.1.5 更新 OverdueTasksSection 顯示 days_overdue
|
||||
|
||||
### 2.2 UI 改善
|
||||
- [x] 2.2.1 可摺疊區塊設計
|
||||
- [x] 2.2.2 任務項目樣式統一
|
||||
- [x] 2.2.3 逾期/阻礙 highlight 樣式
|
||||
|
||||
### 2.3 Testing - Phase 2
|
||||
- [x] 2.3.1 前端週報顯示測試
|
||||
- [x] 2.3.2 空清單狀態測試
|
||||
Reference in New Issue
Block a user