# ZPT — Build tasks (Node.js + PostgreSQL) Goal: ship **Zettai Process Tracker** with **full feature parity** to [README.md](./README.md). Use this file as the delivery checklist. Do not mark a module done until RBAC, gates, and UX in [docs/UI_LAYOUT.md](./docs/UI_LAYOUT.md) are matched. --- ## Phase 0 — Foundation ### 0.1 Repository & tooling - [x] Scaffold Node.js project (API + web app or monorepo) - [x] TypeScript (recommended) or consistent JS lint/format - [x] Environment config (`.env`: `DATABASE_URL`, `JWT_SECRET` / session secret, `UPLOAD_DIR`, `PORT`) - [x] Scripts: `dev`, `build`, `start`, `migrate`, `seed`, `test` - [x] Single root `.env`; app under `server/`; product UI in `server/web` ### 0.2 PostgreSQL - [x] Create database and migration tooling (e.g. Prisma / Knex / node-pg-migrate) - [x] Migrations for all entities in README §5 - [x] Indexes: foreign keys, `work_date`, `stage`/`status`, `employee_id`, `project_id`, `task_id`, leave dates - [ ] Seed script mirroring demo users, projects, tasks, bugs, timesheets, leave, holidays, notifications - Partial: employees + projects + tasks/subtasks + bugs + timesheets + leave allocations/requests/holidays + notifications seeded ### 0.3 Auth & security - [x] Replace demo role switcher with real login (email/password or SSO as decided) - [x] Sessions or JWT; password hashing (bcrypt/argon2) - [x] Server-side RBAC middleware matching README §4 (`can(action, ctx)`) - [x] Project membership checks on every project-scoped route - [x] CSRF / CORS / helmet as appropriate - [x] Audit that inactive users cannot authenticate ### 0.4 Shared platform - [x] REST (or GraphQL) API layout by domain - [x] Error shape + validation (Zod/Joi) - [ ] Activity log writer for entity changes - [ ] Notification create/list/mark-read - [ ] File upload service (attachments, unit-test evidence, requirement docs) - [x] Date helpers: display **DD-MM-YYYY**; hours **HH:MM** ↔ decimal - [x] ID strategy: UUID PK + optional human codes (`ZPT-101`, `BUG-001`) --- ## Phase 1 — Core HR & projects ### 1.1 Employees - [x] CRUD API (Super Admin only) - [x] Activate / deactivate; warn when assigned to open work - [x] List filters/search - [x] Roles field matches system roles - [x] **UI parity with UI_LAYOUT** (see [docs/UI_LAYOUT.md](./docs/UI_LAYOUT.md) §4) - Control panel: New (left) + title + center search - Table columns: ID, Name+avatar, Email, Phone, Department, Designation, Role, Status, actions - Create/Edit via shared modal matching documented fields ### 1.1b Clients - [x] Super Admin CRUD (create, edit, activate/deactivate, delete when unmapped) - [x] Project maps to one client (required on save) - [x] Client filter on Projects, Tasks, Bugs, Activities, Timesheets, Reporting, Releases - [x] Task Customer shows the project's client ### 1.2 Projects - [x] CRUD API + clone default **internal statuses** on create - [x] Visibility by membership / SA - [x] API supports create/edit fields: code, name, description, dates, status, color, tags, flags, admin, members + roles - [x] **UI parity with UI_LAYOUT** (see [docs/UI_LAYOUT.md](./docs/UI_LAYOUT.md) §5–§7) - Shell: apps grid + Project app menus (Projects / Tasks / Bugs / …) - Control panel + cards/list toggle; card click → tasks; gear → settings - Project detail: stat strip, description, tasks-by-stage, members, internal statuses - Full-page New/Edit form (all documented fields + members picker) - [x] Navigate to Tasks filtered by project - Hash `#/tasks?project=` wired; Tasks board placeholder until Phase 2 --- ## Phase 2 — Tasks ### 2.1 Task list / kanban - [x] Parent-only kanban by stage - [x] Drag-and-drop / stage button only if `change_task_status` - [x] List view + group by stage / assignee / project / priority - [x] CSV export - [x] Quick create - [x] **Facet search**: My Tasks, Unassigned, Project, Stage, Assignees, Priority; Group By; Favorites (persist per user) - [x] **Lifecycle** Cancelled / Done on any stage (status pill, dimmed); hidden from list/kanban unless **Include Cancelled / Done**; bugs Closed/Cancelled same with **Include Cancelled / Closed** ### 2.2 Task detail & inline edit - [x] Stage chevron bar with **server-enforced** gates (README §6) - [x] Inline edit + dirty Save / Discard for: title, priority, internal status, project, tags, assignees, deadline, allocation, billing, description, AC - [x] Read-only Customer + Task ID - [x] No duplicate Internal status row in field grid - [x] Multi-assignee assignments + hours; allocation `(i)` modal - [x] Parent + subtask allocation consolidation - [x] Tabs: Description, Acceptance criteria, Timesheets, Sub-tasks, Bugs, Attachments, Workflow - Timesheets tab wired in Phase 4; Bugs tab shipped in Phase 3 - [x] Chatter: messages, notes (CRUD), schedule activity (types, due, assignee, mark done) - [x] Workflow tab toggles + evidence recording - [x] Subtasks CRUD (`parentId`, required flag) - [x] Reopen Done (reason); Return to In Progress from QA - [x] New task → Inbox; billing required ### 2.3 Workflow engine - [x] Implement Gate A / B / C exactly as README - [x] Reopen + return-to-In-Progress - [x] Auto-align internal status when stage changes if mismatched - [x] Log `stage_change` / `transition_blocked` - [ ] Unit tests for every gate pass/fail case - Stage helper tests added; full gate matrix integration tests still TODO --- ## Phase 3 — Bugs ### 3.1 Bug tracker - [x] Kanban by status + list + groupBy + CSV - [x] Facet search (My Bugs, Unassigned, Blocking, Project, Status, Severity, Assignees, Favorites) - [x] Create (PA / Tester); Open→Assigned when assignee set - [x] Detail status bar + retest shortcuts - [x] Inline dirty edit (UX parity) - [x] Unit-test evidence gate before Ready for Retest - [x] Blocking bugs block parent task Done - Gate C already enforced in workflow; seed BUG-001 is blocking on ZPT-105 - [x] Tester/QA limited Close/Reopen from Ready for Retest - [x] Attachments + Unit-test evidence tab (add/edit/paste/upload/download) - [x] Multi-assignee + HH:MM allocation on bugs - [x] Timer + timesheets tab deferred to Phase 4 — now shipped (see Phase 4) --- ## Phase 4 — Time tracking ### 4.1 Timesheets - [x] CRUD with HH:MM UI; decimal storage - [x] Inherit billing from task - [x] User grouping: Month→Date, Date, Month - [x] Admin grouping: Project, Task, Member, nested variants - [x] Filters: project, billing, employee, search - [x] Inline add/edit/delete; totals - [x] Embed on task/bug - [x] Optional: approval workflow for `Pending` / `Approved` - SA/PA `POST /api/timesheets/:id/approve` + Approve action on list rows ### 4.2 Timer - [x] One active timer per user - [x] Start / Pause / Resume / Stop / Discard on task & bug - [x] Stop → timesheet (`fromTimer`) - [x] Floating bar across app - [x] Heartbeat endpoint - [x] Auto-close on disconnect / stale heartbeat / overnight recovery (`autoClosed`) - [x] Category defaults: Development (task), Bug Fixing (bug) --- ## Phase 5 — Time Off ### 5.1 Leave module - [x] Leave types: CL, EL, SL, Comp Off, Unpaid - [x] Allocations per employee / year / type (SA) - [x] Apply request with balance validation + day period - [x] My Time dashboard + calendar + holidays + my requests - [x] Overview - [x] Management: approve/deny, allocations UI, holidays CRUD - [x] Notifications on apply / decide - `/api/notifications` + shell bell; Super Admins notified on apply, requester on decide - [x] Half-day rules (morning/afternoon only when single day) --- ## Phase 6 — Reporting & shell ### 6.1 Dashboards & reports - [x] SA / PA / My Work dashboards (metrics from README §7.8) - [x] All report types + filters + CSV export - [x] Configuration screen (non-destructive settings; seed reset only in non-prod; menu removed — `#/settings`) - [x] Release / Deadline Tracking (project → deadline date → task/subtask/bug; exclude Done·Released) - [x] Done-stage internal status **Released** (after Completed) in defaults + existing projects ### 6.2 Shell UX - [x] Apps grid + per-app menus (README §3 / [docs/UI_LAYOUT.md](./docs/UI_LAYOUT.md) §2) — Phase 1 shell live - [x] Notifications bell (list + mark-all-read; leave apply/decide wired; more event types later) - [x] Control panels + view toggles (UI_LAYOUT §3) — Employees & Projects - [x] Facet search component reusable for Tasks & Bugs (`ZPT.app.facetSearchBar`) - [x] Toasts + modal (shared dialog `#appModal`) - [x] Responsive layout UX parity CSS (`css/styles.css` reused by `server/web`) - [x] Product UI shell in `server/web` --- ## Phase 7 — Hardening - [x] API integration tests for RBAC matrix - [x] Workflow gate tests - [x] Timer race / double-stop tests - [x] Leave balance edge cases (half days, holidays) - [x] Performance: list/kanban pagination or limits - [x] Backup / migrate docs — [docs/BACKUP_MIGRATE.md](./docs/BACKUP_MIGRATE.md) - [x] Product UI only under `server/web` - [x] Acceptance walkthrough against README checklist with each role — [docs/ACCEPTANCE.md](./docs/ACCEPTANCE.md) --- ## Acceptance criteria (definition of done) 1. Every module in README §7 works for the correct roles in §4 2. Task gates A/B/C and bug Ready-for-Retest gate are **server-enforced** 3. Inline edit + facet search + stage bars + chatter + timer bar match UI_LAYOUT UX 4. Dates DD-MM-YYYY; hours HH:MM in UI 5. Seed data supports full demo of the workflow 6. No reliance on `localStorage` for business data --- ## Suggested order of delivery ``` 0 Foundation → 1 Employees/Projects → 2 Tasks+Workflow → 3 Bugs → 4 Timesheets+Timer → 5 Leave → 6 Reports+Shell polish → 7 Hardening ``` --- ## Reference - Requirements source of truth: [README.md](./README.md) - **UI layout contract:** [docs/UI_LAYOUT.md](./docs/UI_LAYOUT.md) - Product UI: `server/web` · API: `server/src` - Agent rules: [.cursorrules](./.cursorrules), [.cursor/rules/zpt-requirements.mdc](./.cursor/rules/zpt-requirements.mdc)