# EPIC-002 — Panel Tự Động Nhận Nhiệm Vụ Mới (Real-time Ticket Notification)

**ID:** EPIC-002
**Trạng thái:** In Progress
**Pipeline:** feature-sdlc
**Ngày tạo:** 2026-05-15
**Owner:** Nghĩa (Tech Lead + PO)

---

## Problem Statement

Khi tổ trưởng giao nhiệm vụ mới (Ticket) cho công nhân, **panel của công nhân không tự động cập nhật** — công nhân phải reload trang thủ công mới thấy nhiệm vụ mới. Điều này gây ra:

- Công nhân bỏ lỡ nhiệm vụ → trễ deadline ca sản xuất
- Tổ trưởng không biết công nhân đã nhận được nhiệm vụ hay chưa
- Gián đoạn luồng làm việc tại xưởng

---

## Business Value

| Người hưởng lợi | Lợi ích | Đo lường |
|-----------------|---------|----------|
| Công nhân | Biết ngay nhiệm vụ mới, không cần reload | Giảm thời gian chờ nhận nhiệm vụ |
| Tổ trưởng | Phân công chắc chắn được nhận | Giảm lần phải nhắc thủ công |
| Quản lý sản xuất | Luồng MES trơn tru, đúng tiến độ | Giảm delay giữa "giao" và "bắt đầu" |

---

## Target User

**Công nhân xưởng** — người dùng panel web/mobile tại xưởng sản xuất, thao tác chủ yếu trên màn hình lớn hoặc tablet, kỹ năng IT thấp, không quen reload trang.

---

## Scope

### Trong scope

- Tự động hiển thị Ticket mới khi được assign cho công nhân (không cần reload)
- Hiển thị badge / thông báo trực quan trên panel khi có nhiệm vụ mới
- Cập nhật real-time trạng thái Ticket trên panel (PLANNED → TODO → IN_PROGRESS...)
- Hỗ trợ web panel (web-kingston) — ưu tiên trước
- Hỗ trợ mobile panel (app-kingston) — phase sau (nếu cần)

### Ngoài scope

- Push notification native (iOS/Android) — riêng epic khác
- Real-time cập nhật cho tổ trưởng / quản lý (dashboard admin) — riêng epic khác
- Thay đổi logic assign ticket hiện tại
- Offline mode / background sync

---

## User Stories

| ID | Story | AC cao cấp | Priority |
|----|-------|------------|----------|
| US-001 | Là công nhân, tôi muốn thấy ngay nhiệm vụ mới khi tổ trưởng giao, không cần reload trang | Panel tự cập nhật trong ≤ 3 giây sau khi ticket được assign | Must Have |
| US-002 | Là công nhân, tôi muốn có dấu hiệu trực quan (badge, highlight) khi có nhiệm vụ mới chưa xem | Ticket mới hiển thị badge "Mới" hoặc highlight màu đến khi công nhân click vào | Must Have |
| US-003 | Là công nhân, tôi muốn trạng thái nhiệm vụ trên panel cập nhật tự động khi có thay đổi từ tổ trưởng | Trạng thái Ticket thay đổi phản ánh ngay trên panel (VD: PLANNED → TODO) | Should Have |
| US-004 | Là công nhân, tôi muốn kết nối được khôi phục tự động nếu mất mạng tạm thời | Panel tự reconnect và đồng bộ lại trạng thái trong ≤ 10 giây sau khi có mạng | Should Have |
| US-005 | Là tổ trưởng, tôi muốn biết công nhân đã nhận được nhiệm vụ (online/offline trên panel) | Hiển thị trạng thái "đang online" của công nhân trên panel quản lý | Could Have |

---

## Affected Areas

| Module | Surface | Mô tả thay đổi |
|--------|---------|----------------|
| `api-kingston` | WebSocket / SSE gateway | Thêm real-time channel cho Ticket events |
| `api-kingston` | MES — AssignEmployee usecase | Emit event khi assign ticket cho employee |
| `web-kingston` | Worker Panel page | Subscribe real-time, cập nhật danh sách ticket |
| `web-kingston` | Ticket list component | Hiển thị badge "Mới", highlight state |
| `app-kingston` | Worker Panel (Flutter) | Phase 2 — subscribe real-time |

---

## Dependencies

| Dependency | Trạng thái | Owner | Ghi chú |
|------------|------------|-------|---------|
| Cơ chế real-time (WebSocket hoặc SSE) | Chưa có | Nghĩa | Cần quyết định technology (xem Risks) |
| `AssignEmployeeUsecase` đang hoạt động | Đã có | api-kingston | Cần emit domain event sau assign |
| Auth token cho WebSocket connection | Đã có (JWT) | api-kingston | Reuse JWT hiện tại |
| Worker Panel page trên web-kingston | Đã có | web-kingston | Cần refactor để subscribe |

---

## Epic Phases

```
Phase 1: Planning
  ├── PRD (AC chi tiết, user flows)         [/prd EPIC-002]
  └── Tech Design (WebSocket vs SSE, schema) [/tech-design EPIC-002]

Phase 2: Implementation
  ├── API: Real-time gateway + emit event sau assign
  └── Web: Subscribe + cập nhật panel UI

Phase 3: Testing
  └── Test plan: unit + integration + E2E real-time

Phase 4: Execute-Test
  └── QA tại xưởng (tablet, mạng wifi thực tế)

Phase 5: Release
  └── Deploy + smoke test trên prod panel

Phase 6: Doc-Sync
  └── Cập nhật topics/phan-mem/api-kingston-mes.md
```

---

## Risks & Mitigations

| Rủi ro | Khả năng | Ảnh hưởng | Mitigation |
|--------|----------|-----------|------------|
| WebSocket scale kém khi nhiều công nhân online cùng lúc | Trung bình | Cao | Dùng SSE (unidirectional, nhẹ hơn) hoặc Redis pub/sub nếu scale > 50 connections |
| Mạng wifi xưởng không ổn định → reconnect loop | Cao | Trung bình | Implement exponential backoff + reconnect UI indicator |
| Công nhân dùng tab nhiều → duplicate connection | Thấp | Thấp | Server track per-user, không per-tab |
| Token JWT hết hạn khi đang kết nối | Trung bình | Trung bình | Refresh token trước khi reconnect hoặc dùng long-lived token cho panel |
| Flutter (app-kingston) cần port riêng | Trung bình | Thấp | Scope phase 2, không block phase 1 |

---

## Links

- [[topics/phan-mem/api-kingston-mes|MES Architecture]]
- [[topics/san-xuat/_index|Quy trình sản xuất xưởng]]
- EPIC-001 (nếu có dependency)