Agile Sprints - Epics, Story Points & Burndown (Boards + Reports)

### 🔎 Summary

Introduce first-class **Agile Sprint** support to Collabify:

* **Epics** to group work
* **Sprints** with start/end, capacity, and goals
* **Story points** & **WIP limits**
* **Drag-and-drop** sprint board
* **Burndown/Burnup**, **Velocity**, **Throughput**, and **Workload heatmap**
* **Role-gated** actions via Auth0 RBAC
* **i18n-ready** UI strings (EN, VI)

This turns Collabify into a credible Jira/Trello alternative for scrum/kanban teams.

---

#### 💡 Why

* Teams need planning, execution and **evidence** of delivery (reports) in one place.
* Current tasks & charts are good, but **no sprint ritual support** (goals, commit, forecast, burndown).
* Adds stickiness for teams migrating off Jira/Trello.

---

#### ✅ Acceptance Criteria

* **Epics**

* Create/rename/archive epics per project.
* Assign tasks to epics; view epic progress (% SP complete, tasks done).
* **Sprints**

* Create sprint with **name, goal, start, end, capacity (SP)**.
* Move tasks from backlog → sprint; lock scope at start (configurable flag).
* WIP limits per column (To Do, In Progress, Review, Done).
* Sprint board supports drag-drop, keyboard shortcuts, multi-select.
* **Estimation**

* Task supports `storyPoints` (0, 1, 2, 3, 5, 8, 13…).
* Inline quick-estimate menu, bulk estimate from backlog.
* **Reports**

* **Burndown** (remaining SP/day vs ideal), **Burnup**, **Velocity** (avg last 3 sprints), **Throughput** (tasks/week).
* **Workload heatmap**: SP assigned per assignee for current sprint + capacity warning.
* **Auth / Roles**

* Only `project_manager`/`admin` can create/close sprints, edit WIP limits, and set capacity.
* Members can move tasks and estimate (configurable).
* **i18n**

* All strings under `public/locales/*` with English + Vietnamese keys.
* **Perf & UX**

* Optimistic updates on drag/estimate; React Query cache invalidation.
* Empty & loading states; accessible ARIA labels.

---

#### 🗄 Data Model (MongoDB)

Update existing `projects`, `tasks`; add `sprints`, `epics`.

* **Collection: `epics`**

* `_id`, `projectId`, `name`, `description`, `status` (`active|archived`), `createdAt`, `updatedAt`
* Indexes: `{ projectId: 1, status: 1 }`
* **Collection: `sprints`**

* `_id`, `projectId`, `name`, `goal`, `startAt`, `endAt`, `capacitySP` (number), `status` (`planned|active|completed|cancelled`), `wipLimits` (per column), `createdAt`, `updatedAt`
* Indexes: `{ projectId: 1, status: 1, startAt: 1, endAt: 1 }`
* **Collection: `tasks`** (augment)

* add fields: `epicId?`, `sprintId?`, `storyPoints?` (number), `status` (`todo|in_progress|review|done`), `startedAt?`, `completedAt?`
* Indexes: `{ projectId: 1, sprintId: 1, status: 1 }`
* **Auditing** (optional now): append minimal `activity` entries for sprint scope changes.

> AuthZ: All write ops must validate **project membership** and **Auth0 roles** on the API layer.

---

#### 🛤 API Design (Next.js API routes)

All routes **JWT-protected**; check `req.user` roles/permissions.

* **Epics**

* `GET /api/projects/:projectId/epics`
* `POST /api/projects/:projectId/epics`
* `PATCH /api/projects/:projectId/epics/:epicId`
* `DELETE /api/projects/:projectId/epics/:epicId` (archive)
* **Sprints**

* `GET /api/projects/:projectId/sprints`
* `POST /api/projects/:projectId/sprints` (manager/admin only)
* `PATCH /api/projects/:projectId/sprints/:sprintId` (rename, goal, capacity, WIP limits)
* `POST /api/projects/:projectId/sprints/:sprintId/start` (locks scope if enabled)
* `POST /api/projects/:projectId/sprints/:sprintId/complete`
* **Tasks**

* `PATCH /api/projects/:projectId/tasks/:taskId/estimate` → `{ storyPoints }`
* `PATCH /api/projects/:projectId/tasks/:taskId/move` → `{ sprintId?, status }`
* Bulk ops: `POST /api/projects/:projectId/tasks/bulk` with `{ addToSprint, estimate }`
* **Reports**

* `GET /api/projects/:projectId/sprints/:sprintId/reports/burndown`
* `GET /api/projects/:projectId/sprints/:sprintId/reports/burnup`
* `GET /api/projects/:projectId/sprints/:sprintId/reports/workload`
* `GET /api/projects/:projectId/reports/velocity?window=3`

> Aggregations compute daily SP remaining from `storyPoints` and `completedAt`; cache in memory or Mongo TTL collection for 5–15 min.

---

#### 🎨 UI/UX

* **Backlog**

* Epic badge filter; quick estimate menu; add to sprint.
* **Sprint Board**

* Columns: To Do / In Progress / Review / Done (configurable later).
* Drag-drop (multi-select), inline estimate, context menu for move/assign.
* Column headers show WIP & count; capacity bar at top (SP used vs capacity).
* **Reports**

* Tabbed: Burndown, Burnup, Velocity, Workload heatmap (Chart.js).
* Tooltips + export PNG.
* **Epic View**

* Progress ring (SP done / total), list of tasks by status.
* **i18n**

* Add keys: `sprints.*`, `epics.*`, `reports.*`, `estimate.*`, `capacity.*`.

---

#### 🔐 Auth0 / RBAC

* Gate sprint create/start/complete & WIP/Capacity edits to `project_manager` or `admin`.
* Members can move tasks and estimate (feature toggle under project settings).
* Validate via access token roles/permissions; deny with 403 + localized message.

---

#### 🤖 (Optional) AI Assist Hooks

* **Estimate helper:** Suggest SP based on task title/description (user can accept/override).
* **Scope suggestion:** Given sprint length + capacity, propose top N backlog items to fit.

*(Wire the above to existing assistant plumbing; behind a project-level toggle.)*

---

#### 🧪 Testing

* **Unit (Jest):** aggregation functions (burndown/velocity), WIP rules, role guards.
* **API Integration:** sprint lifecycle, scope lock, permission checks, bulk task updates.
* **E2E (Playwright):** drag-drop on board, inline estimate, start→complete sprint, reports render with correct data.
* **i18n:** snapshot keys exist for EN/VI.

---

#### 🧱 Implementation Plan

1. **Schemas & Indexes** (Mongoose) + migrations script.
2. **API routes** with RBAC guards + validation (Zod).
3. **Aggregations** for reports + lightweight cache.
4. **UI components**

* Backlog: epic filters, estimate controls
* Sprint Board: DnD, WIP counters, capacity bar
* Reports: Chart.js views
* Epic View: progress + listing
5. **React Query** cache keys & optimistic updates.
6. **i18n** strings & VI translations.
7. **Docs**: README sections + screenshots.
8. **CI**: add tests to workflow, typecheck, lint.

---

#### 🧩 Tasks Checklist

* [ ] Mongoose models: `Epic`, `Sprint` (+ indexes)
* [ ] Extend `Task` with `epicId`, `sprintId`, `storyPoints`, timestamps
* [ ] API: CRUD epics, sprints lifecycle (start/complete), task estimate/move
* [ ] Reports endpoints (burndown/burnup/velocity/workload)
* [ ] UI: Backlog epic filter + estimate
* [ ] UI: Sprint Board (DnD, WIP, capacity)
* [ ] UI: Reports tabs (Chart.js)
* [ ] i18n: EN/VI keys & translations
* [ ] Auth0 guards (server) + friendly 403 UI
* [ ] Tests: unit/integration/E2E
* [ ] Docs: user guide + screenshots

---

#### ⚠️ Risks & Mitigations

* **Scope creep:** Keep v1 focused (no custom workflows yet).
* **Perf on large boards:** Pagination/virtualize columns; server-side aggregation & caching.
* **RBAC gaps:** Centralize permission check helper; add test coverage.
* **Timezones in reports:** Normalize to project TZ; document assumption.

---

#### 🧭 Out of Scope (follow-ups)

* Custom board columns/workflows
* Cross-project dependencies & roadmap timeline
* Calendar/ICS sync & sprint events
* SLA/lead-time analytics

---