Merge pull request #259 from aliansoftwareteam/feat/relations-epics-enhancements

feat(tasks,epics): blocked-task warning + epic dates/owner/priority/progress

Author: parth0025

.claude/test-cases/BlockedTaskWarning.md

@@ -0,0 +1,23 @@
+# Blocked-Task Warning — Test Cases
+
+**Feature:** A task that is `blocked_by` one or more still-open tasks shows a clear "⚠ Blocked by N open task(s)" banner in its Linked Tasks panel. Makes AlianHub's blocked-task alert real.
+
+**Location:**
+- Frontend: Task detail → **Linked Tasks** panel — `frontend/src/components/organisms/LinkedTasks/LinkedTasks.vue` (computed `openBlockers`, banner).
+- Backend: `POST /api/v2/tasks/relations` action `openBlockers` → `getOpenBlockers` (`Modules/Tasks/helpers/taskMongo/relations.js`); pure helper `selectOpenBlockers` (`relationRules.js`). A blocker counts only while `statusType !== 'close'` and not soft-deleted.
+
+**Legend:** ✅ Pass · ❌ Fail · ⏳ Pending (not yet run in the app)
+
+| ID | Title | Precondition | Steps | Expected | Actual | Status |
+|----|-------|--------------|-------|----------|--------|--------|
+| BW_001 | Warning shows for an open blocker | Task B is `blocked_by` Task A; A is open | Open Task B → Linked Tasks panel | Amber banner: "⚠ Blocked by 1 open task(s): {A.key}" | | ⏳ Pending |
+| BW_002 | Warning clears when the blocker closes | As BW_001 | Move Task A to a Done/closed status; reopen Task B | Banner disappears (0 open blockers) | | ⏳ Pending |
+| BW_003 | Only `blocked_by` counts | Task B `blocks` Task A (B blocks, isn't blocked) | Open Task B | No banner on B | | ⏳ Pending |
+| BW_004 | Multiple open blockers listed | B `blocked_by` A and C, both open | Open Task B | Banner shows count 2 and both keys | | ⏳ Pending |
+| BW_005 | Soft-deleted blocker ignored | B `blocked_by` A; A soft-deleted | Open Task B | A not counted in the banner | | ⏳ Pending |
+| BW_006 | `openBlockers` API action | B `blocked_by` A (open) | POST /api/v2/tasks/relations {action:'openBlockers', taskId:B} | `{ status:true, data:[A summary] }` | | ⏳ Pending |
+| BW_007 | duplicates / relates_to never block | B `relates_to`/`duplicates` A | Open Task B | No banner | | ⏳ Pending |
+
+**Unit coverage:** `selectOpenBlockers` + `isClosedStatusType` fully covered in `tests/task-relations-rules.test.js` (open / closed / deleted / wrong-type / null / mixed).
+
+**Total:** 7 manual cases · pure logic unit-tested (green).

.claude/test-cases/EpicEnhancements.md

@@ -0,0 +1,24 @@
+# Epic Enhancements (dates / owner / priority / status / progress) — Test Cases
+
+**Feature:** Epics gain **start/due dates**, an **owner**, a **priority** (low/medium/high), an **in_progress** status (alongside open/done), and a visible **progress bar with %** — turning the thin v1 into a usable progress layer.
+
+**Location:**
+- Frontend: **Epics** panel — `frontend/src/components/molecules/Epics/EpicsPanel.vue` (create form fields, priority badge, status select, owner + dates, % label).
+- Backend: `Modules/Epics/controller.js` (create/update accept the new fields), `helpers/epicRules.js` (`EPIC_PRIORITIES`, `parseEpicDates`, extended `EPIC_STATUSES`), schema `utils/mongo-handler/schema.js` (epics: priority, ownerUserId, startDate, dueDate).
+
+**Legend:** ✅ Pass · ❌ Fail · ⏳ Pending (not yet run in the app)
+
+| ID | Title | Precondition | Steps | Expected | Actual | Status |
+|----|-------|--------------|-------|----------|--------|--------|
+| EE_001 | Create epic with priority + dates | Project open; Epics panel open | Enter name, pick priority **High**, set start + due, click Add | Epic created; owner defaults to creator | | ⏳ Pending |
+| EE_002 | Row renders new metadata | EE_001 done | View the epic row | Priority badge (High), owner name, due date all shown | | ⏳ Pending |
+| EE_003 | Progress bar + % label | Epic has 4 tasks, 1 closed | View epic row | Bar ≈25%, label "25% · 1/4" | | ⏳ Pending |
+| EE_004 | Set status In progress | Epic exists | Pick "In progress" in the row status select | Persists (PUT /epics/:id); chip tinted amber | | ⏳ Pending |
+| EE_005 | Set status Done | Epic exists | Pick "Done" | Persists; chip tinted green | | ⏳ Pending |
+| EE_006 | Invalid priority rejected (API) | — | PUT /api/v2/epics/:id {priority:'urgent'} | `{ status:false, "Invalid priority." }` | | ⏳ Pending |
+| EE_007 | start-after-due rejected (API) | — | POST /api/v2/epics {startDate:'2026-07-01', dueDate:'2026-06-01', …} | `{ status:false, "startDate must be on or before dueDate." }` | | ⏳ Pending |
+| EE_008 | Owner shows Unassigned when empty | Epic with no ownerUserId | View the row | Owner: "Unassigned" | | ⏳ Pending |
+
+**Unit coverage:** `validateEpicInput` (priority), `parseEpicDates` (valid / clear / partial / unparseable / start>due), and `EPIC_STATUSES`/`EPIC_PRIORITIES` covered in `tests/epic-rules.test.js`.
+
+**Total:** 8 manual cases · pure logic unit-tested (green).

Modules/Epics/controller.js

@@ -3,7 +3,7 @@ const { MongoDbCrudOpration } = require("../../utils/mongo-handler/mongoQueries"
 const mongoose = require("mongoose");
 const logger = require("../../Config/loggerConfig");
 const socketEmitter = require('../../event/socketEventEmitter');
-const { validateEpicInput, validateAssignInput, countDeltas, isObjectIdString, EPIC_STATUSES } = require('./helpers/epicRules');
+const { validateEpicInput, validateAssignInput, countDeltas, isObjectIdString, EPIC_STATUSES, EPIC_PRIORITIES, parseEpicDates } = require('./helpers/epicRules');
 
 // Epics: a grouping layer above tasks with progress roll-up. Tasks carry an
 // optional epicId; epics keep denormalised taskCount/completedCount which
@@ -13,11 +13,15 @@ const { validateEpicInput, validateAssignInput, countDeltas, isObjectIdString, E
 exports.createEpic = async (req, res) => {
     try {
         const companyId = req.headers['companyid'] || '';
-        const { name, description, color, projectId, userData } = req.body || {};
-        const check = validateEpicInput({ companyId, name, projectId, color });
+        const { name, description, color, projectId, priority, ownerUserId, startDate, dueDate, userData } = req.body || {};
+        const check = validateEpicInput({ companyId, name, projectId, color, priority });
         if (!check.valid) {
             return res.send({ status: false, statusText: check.reason });
         }
+        const dateCheck = parseEpicDates({ startDate, dueDate });
+        if (!dateCheck.valid) {
+            return res.send({ status: false, statusText: dateCheck.reason });
+        }
         const created = await MongoDbCrudOpration(companyId, {
             type: SCHEMA_TYPE.EPICS,
             data: {
@@ -26,6 +30,10 @@ exports.createEpic = async (req, res) => {
                 ProjectID: new mongoose.Types.ObjectId(projectId),
                 color: color || '#7b68ee',
                 status: 'open',
+                priority: priority ? String(priority) : 'medium',
+                ownerUserId: ownerUserId ? String(ownerUserId) : '',
+                startDate: dateCheck.startDate || null,
+                dueDate: dateCheck.dueDate || null,
                 createdBy: userData && (userData.id || userData._id) ? String(userData.id || userData._id) : '',
                 taskCount: 0,
                 completedCount: 0,
@@ -70,7 +78,7 @@ exports.updateEpic = async (req, res) => {
         if (!companyId || !isObjectIdString(id)) {
             return res.send({ status: false, statusText: 'companyId and a valid epic id are required.' });
         }
-        const { name, color, status, description } = req.body || {};
+        const { name, color, status, description, priority, ownerUserId, startDate, dueDate } = req.body || {};
         const update = {};
         if (name !== undefined) {
             if (!String(name).trim()) return res.send({ status: false, statusText: 'name cannot be empty.' });
@@ -82,6 +90,19 @@ exports.updateEpic = async (req, res) => {
             if (!EPIC_STATUSES.includes(status)) return res.send({ status: false, statusText: 'Invalid status.' });
             update.status = status;
         }
+        if (priority !== undefined) {
+            if (priority !== '' && priority !== null && !EPIC_PRIORITIES.includes(String(priority))) {
+                return res.send({ status: false, statusText: 'Invalid priority.' });
+            }
+            update.priority = priority ? String(priority) : '';
+        }
+        if (ownerUserId !== undefined) update.ownerUserId = ownerUserId ? String(ownerUserId) : '';
+        if (startDate !== undefined || dueDate !== undefined) {
+            const dateCheck = parseEpicDates({ startDate, dueDate });
+            if (!dateCheck.valid) return res.send({ status: false, statusText: dateCheck.reason });
+            if (startDate !== undefined) update.startDate = dateCheck.startDate || null;
+            if (dueDate !== undefined) update.dueDate = dateCheck.dueDate || null;
+        }
         if (!Object.keys(update).length) {
             return res.send({ status: false, statusText: 'Nothing to update.' });
         }

Modules/Epics/helpers/epicRules.js

@@ -3,12 +3,13 @@
 const OBJECT_ID_PATTERN = /^[0-9a-fA-F]{24}$/;
 const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
 const MAX_NAME_LENGTH = 120;
-const EPIC_STATUSES = Object.freeze(['open', 'done']);
+const EPIC_STATUSES = Object.freeze(['open', 'in_progress', 'done']);
+const EPIC_PRIORITIES = Object.freeze(['low', 'medium', 'high']);
 
 const isObjectIdString = (id) => OBJECT_ID_PATTERN.test(String(id || ''));
 
 /* Validate epic creation/update input. Returns { valid, reason }. */
-const validateEpicInput = ({ companyId, name, projectId, color }) => {
+const validateEpicInput = ({ companyId, name, projectId, color, priority }) => {
     if (!companyId) {
         return { valid: false, reason: 'companyId is required.' };
     }
@@ -21,6 +22,9 @@ const validateEpicInput = ({ companyId, name, projectId, color }) => {
     if (color !== undefined && color !== '' && !HEX_COLOR_PATTERN.test(String(color))) {
         return { valid: false, reason: 'color must be a #rrggbb hex value.' };
     }
+    if (priority !== undefined && priority !== '' && priority !== null && !EPIC_PRIORITIES.includes(String(priority))) {
+        return { valid: false, reason: `priority must be one of: ${EPIC_PRIORITIES.join(', ')}.` };
+    }
     return { valid: true, reason: '' };
 };
 
@@ -56,11 +60,39 @@ const countDeltas = ({ oldEpicId, newEpicId, isCompleted }) => {
     return deltas;
 };
 
+/* Parse + validate optional epic dates. Returns { valid, reason, startDate,
+ * dueDate } with Date objects (or null). Rejects unparseable dates, and a
+ * startDate later than dueDate when both are supplied in the same call. */
+const parseEpicDates = ({ startDate, dueDate }) => {
+    const toDate = (v) => {
+        if (v === null || v === '') return null;
+        const d = new Date(v);
+        return Number.isNaN(d.getTime()) ? false : d;
+    };
+    const out = { valid: true, reason: '', startDate: undefined, dueDate: undefined };
+    if (startDate !== undefined) {
+        const d = toDate(startDate);
+        if (d === false) return { valid: false, reason: 'startDate is not a valid date.' };
+        out.startDate = d;
+    }
+    if (dueDate !== undefined) {
+        const d = toDate(dueDate);
+        if (d === false) return { valid: false, reason: 'dueDate is not a valid date.' };
+        out.dueDate = d;
+    }
+    if (out.startDate && out.dueDate && out.startDate.getTime() > out.dueDate.getTime()) {
+        return { valid: false, reason: 'startDate must be on or before dueDate.' };
+    }
+    return out;
+};
+
 module.exports = {
     EPIC_STATUSES,
+    EPIC_PRIORITIES,
     MAX_NAME_LENGTH,
     isObjectIdString,
     validateEpicInput,
     validateAssignInput,
+    parseEpicDates,
     countDeltas,
 };

Modules/Tasks/helpers/taskMongo/relationRules.js

@@ -75,12 +75,31 @@ const validateRelationInput = ({ companyId, taskId, relatedTaskId, type }) => {
     return { valid: true, reason: '' };
 };
 
+// A task is complete when its statusType is 'close' — the same signal the epic
+// counters and /recount use. A blocker only "blocks" while it is still open.
+const isClosedStatusType = (statusType) => String(statusType || '') === 'close';
+
+/* From a task's relation-list entries (each `{ type, task }`, as returned by
+ * getTaskRelations), pick the OPEN blockers: `blocked_by` links whose blocking
+ * task still exists, isn't soft-deleted, and isn't closed. Pure — shared by the
+ * controller and the unit tests so "what counts as blocked" lives in one place. */
+const selectOpenBlockers = (relationItems) =>
+    (relationItems || []).filter((item) =>
+        item &&
+        item.type === RELATION_TYPES.BLOCKED_BY &&
+        item.task &&
+        item.task.deletedStatusKey !== 1 &&
+        !isClosedStatusType(item.task.statusType)
+    );
+
 module.exports = {
     RELATION_TYPES,
     RELATION_TYPE_LIST,
     INVERSE_RELATION,
     RELATION_LABELS,
     isObjectIdString,
+    isClosedStatusType,
+    selectOpenBlockers,
     validateTaskRef,
     validateRelationPair,
     validateRelationInput,

Modules/Tasks/helpers/taskMongo/relations.js

@@ -5,7 +5,7 @@ const { default: mongoose } = require("mongoose");
 const socketEmitter = require('../../../../event/socketEventEmitter');
 const { HandleHistory } = require("../mongo_helper");
 const { HandleBothNotification } = require("../handleNotification");
-const { INVERSE_RELATION, RELATION_LABELS, validateTaskRef, validateRelationPair, validateRelationInput } = require('./relationRules');
+const { INVERSE_RELATION, RELATION_LABELS, validateTaskRef, validateRelationPair, validateRelationInput, selectOpenBlockers } = require('./relationRules');
 
 // Task-to-task relations (blocks / blocked_by / duplicates / duplicated_by /
 // relates_to). A link is stored on BOTH task documents as an entry in the
@@ -176,6 +176,27 @@ module.exports = {
         })
     },
 
+    /* -------------- LIST OPEN BLOCKERS OF A TASK -----------------*/
+    // payload: { companyId, taskId }. Returns the `blocked_by` links whose
+    // blocking task is still open — i.e. why this task isn't unblocked yet.
+    // Drives the "blocked by N open task(s)" warning shown on the task.
+    getOpenBlockers({ companyId, taskId }) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const relationsResult = await this.getTaskRelations({ companyId, taskId });
+                const openBlockers = selectOpenBlockers(relationsResult.data || []);
+                resolve({
+                    status: true,
+                    statusText: openBlockers.length ? `${openBlockers.length} open blocker(s).` : 'No open blockers.',
+                    data: openBlockers,
+                });
+            } catch (error) {
+                logger.error(`ERROR in get open blockers: ${error.message}`);
+                reject(error);
+            }
+        })
+    },
+
     /* -------------- INTERNAL HELPERS (RELATIONS) -----------------*/
 
     findRelationTask(companyId, taskObjId) {

Modules/Tasks/routes.js

@@ -107,6 +107,7 @@ exports.init = (app) => {
                 add: 'addTaskRelation',
                 remove: 'removeTaskRelation',
                 list: 'getTaskRelations',
+                openBlockers: 'getOpenBlockers',
             };
             const method = RELATION_ACTIONS[req.body && req.body.action];
             if (!method) {