# Proposal: Add Kanban Real-time Sync

## Change ID
add-kanban-realtime-sync

## Status
PROPOSED

## Summary
實作看板 (Kanban) 多人即時同步功能，讓多位使用者同時查看同一專案看板時能即時看到任務狀態變更。

## Problem Statement
目前系統的 WebSocket 僅用於通知推播 (`/ws/notifications`)，看板頁面沒有即時同步機制：
- 當使用者 A 拖曳任務改變狀態時，使用者 B 需要手動重新整理才能看到更新
- 這導致協作效率降低，可能造成衝突或重複操作
- 不符合 `project.md` 中「Real-time Sync: WebSocket for live collaboration」的要求

## Proposed Solution
擴展現有 WebSocket 基礎架構，新增專案房間訂閱 (Project Room Subscription) 機制：

### 核心功能
1. **專案房間訂閱**：使用者進入專案看板時自動訂閱該專案的即時更新
2. **任務變更廣播**：任務狀態變更時，透過 Redis Pub/Sub 廣播給同一專案的所有訂閱者
3. **增量更新**：僅推送變更的任務資料，而非整個看板重載

### 技術架構
```
Frontend (KanbanBoard)
    │
    ▼ WebSocket: /ws/projects/{project_id}
Backend (WebSocket Router)
    │
    ▼ Redis Pub/Sub: channel:project:{project_id}:tasks
Backend (Tasks API)
```

### 訊息類型
- `task_created`: 新任務建立
- `task_updated`: 任務更新（含欄位變更）
- `task_status_changed`: 任務狀態變更（拖曳看板）
- `task_deleted`: 任務刪除
- `task_assigned`: 任務指派變更

## Scope

### In Scope
- 專案級 WebSocket 連線端點
- 任務 CRUD 事件廣播
- 前端看板即時更新
- 樂觀更新 (Optimistic Update) 搭配衝突回滾

### Out of Scope
- 任務欄位鎖定 (Field Locking) - 未來可擴展
- 離線編輯同步 - 未來可擴展
- 多專案同時訂閱 - 目前一次訂閱一個專案

## Impact Analysis

### Affected Components
- `backend/app/api/websocket/router.py` - 新增專案 WebSocket 端點
- `backend/app/services/websocket_manager.py` - 新增專案房間管理
- `backend/app/api/tasks/router.py` - 任務變更時發送事件
- `frontend/src/components/KanbanBoard.tsx` - 接收即時更新
- `frontend/src/contexts/NotificationContext.tsx` - 可能需要擴展或新增專案同步 Context

### Performance Considerations
- Redis Pub/Sub 已用於通知系統，可直接復用
- 每專案一個 channel，避免全域廣播
- 增量更新減少資料傳輸量

### Security Considerations
- WebSocket 連線需驗證 JWT Token
- 確認使用者有權限存取該專案
- 防止未授權的專案訂閱

## Dependencies
- 現有 WebSocket 基礎架構 (collaboration spec)
- Redis Pub/Sub (已實作)
- JWT Token 驗證 (user-auth spec)
- 專案權限檢查 (resource-management spec)

## Related Specs
- `collaboration` - 擴展 Real-time Notifications requirement
- `task-management` - 任務 CRUD 操作

## Author
Claude Code