feat: implement audit trail alignment (soft delete & permission audit)

- Task Soft Delete: - Add is_deleted, deleted_at, deleted_by fields to Task model - Convert DELETE to soft delete with cascade to subtasks - Add include_deleted query param (admin only) - Add POST /api/tasks/{id}/restore endpoint - Exclude deleted tasks from subtask_count - Permission Change Audit: - Add user.role_change event (high sensitivity) - Add user.admin_change event (critical, triggers alert) - Add PATCH /api/users/{id}/admin endpoint - Add role.permission_change event type - Append-Only Enforcement: - Add DB triggers for audit_logs immutability (manual for production) - Migration 008 with graceful trigger failure handling - Tests: 11 new soft delete tests (153 total passing) - OpenSpec: fix-audit-trail archived, fix-realtime-notifications & fix-weekly-report proposals added 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-30 06:58:30 +08:00
parent 95c281d8e1
commit 10db2c9d1f
18 changed files with 1455 additions and 12 deletions
--- a/openspec/changes/fix-weekly-report/design.md
+++ b/openspec/changes/fix-weekly-report/design.md
@@ -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 |
--- a/openspec/changes/fix-weekly-report/proposal.md
+++ b/openspec/changes/fix-weekly-report/proposal.md
@@ -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 在下週一至週日為準
--- a/openspec/changes/fix-weekly-report/specs/automation/spec.md
+++ b/openspec/changes/fix-weekly-report/specs/automation/spec.md
@@ -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 天為範圍
--- a/openspec/changes/fix-weekly-report/tasks.md
+++ b/openspec/changes/fix-weekly-report/tasks.md
@@ -0,0 +1,38 @@
+## Phase 1: Backend Report Enhancement
+
+### 1.1 ReportService 擴充
+- [ ] 1.1.1 移除 completed_tasks/overdue_tasks 的 5 筆限制
+- [ ] 1.1.2 新增 in_progress_tasks 完整清單
+- [ ] 1.1.3 新增 blocked_tasks 查詢與清單
+- [ ] 1.1.4 新增 next_week_tasks 查詢與清單
+- [ ] 1.1.5 擴充 summary 包含 blocked_count 與 next_week_count
+
+### 1.2 任務明細欄位
+- [ ] 1.2.1 completed_tasks 加入 completed_at, assignee_name
+- [ ] 1.2.2 in_progress_tasks 加入 assignee_name, due_date
+- [ ] 1.2.3 overdue_tasks 加入 days_overdue 計算
+- [ ] 1.2.4 blocked_tasks 加入 blocker_reason, blocked_since
+- [ ] 1.2.5 next_week_tasks 加入 due_date, assignee_name
+
+### 1.3 Testing - Phase 1
+- [ ] 1.3.1 週報內容結構測試
+- [ ] 1.3.2 阻礙任務查詢測試
+- [ ] 1.3.3 下週預計任務測試
+
+## Phase 2: Frontend Display
+
+### 2.1 WeeklyReportPreview 更新
+- [ ] 2.1.1 新增 BlockedTasksSection 元件
+- [ ] 2.1.2 新增 NextWeekTasksSection 元件
+- [ ] 2.1.3 更新 CompletedTasksSection 顯示完整清單
+- [ ] 2.1.4 更新 InProgressTasksSection 顯示完整清單
+- [ ] 2.1.5 更新 OverdueTasksSection 顯示 days_overdue
+
+### 2.2 UI 改善
+- [ ] 2.2.1 可摺疊區塊設計
+- [ ] 2.2.2 任務項目樣式統一
+- [ ] 2.2.3 逾期/阻礙 highlight 樣式
+
+### 2.3 Testing - Phase 2
+- [ ] 2.3.1 前端週報顯示測試
+- [ ] 2.3.2 空清單狀態測試