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

[hoangsonww]

🔎 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

---