Automation Rules: Trigger → Condition → Action (TCA) Engine + In-App Notifications

# Automation Rules: Trigger → Condition → Action (TCA) Engine + In-App Notifications

**Summary**
Add a lightweight rules engine that lets users automate routine workflows (e.g., “When a task is moved to *Done* and priority is *High*, notify the *Project Managers* on Slack and assign a retrospective checklist”). Ships with in-app notifications, optional email/webhook actions, and RBAC-aware rule scoping.

---

## Goals

* Let workspace/project admins define **automation rules** using TCA:

* **Triggers:** task.created, task.updated, task.assigned, project.member_joined, schedule.cron
* **Conditions (optional):** field filters (status/priority/assignee/labels), expression builder
* **Actions:** create/update task, add comment, set labels/dates, in-app notification, email, Slack/Webhook, reassign, change status
* Provide **UI** to list, create, enable/disable, test, and reorder rules per project.
* Respect **RBAC** (only admins/PMs manage rules; members can view rules that affect them).
* Guarantee **idempotency** per event (avoid duplicate actions).
* Log **audit entries** for each rule execution (success/failure, latency).

---

## Non-Goals

* Full BPMN or multi-step long-running workflows.
* Third-party OAuth setups beyond generic webhooks & (optional) one Slack Incoming Webhook URL per project.

---

## UX / UI

* **Project Settings → Automations** tab:

* Rules table (name, trigger, actions, status, last run, failures)
* “New Rule” drawer with:

1. Trigger select (+ optional cron)
2. Conditions builder (simple AND of field ops; JSON preview)
3. Actions list (multi-select with action configs)
4. “Test with sample event” & “Create disabled” checkbox
* **Notifications** bell in navbar with unread count, list, pagination, “mark all read”.

---

## Data Model (MongoDB)

```ts
// collections
rules {
_id, projectId, createdBy, name, trigger: "task.updated" | ...,
conditions: { status?: ["Todo","Doing","Done"], priority?: ["High"...], assigneeId?: string, labels?: string[], expr?: string }, // optional
actions: [{ type: "notify"|"email"|"webhook"|"update_task"|"add_comment"|"reassign"|"set_status", config: {...} }],
enabled: boolean,
order: number,
createdAt, updatedAt
}

rule_runs {
_id, ruleId, projectId, eventId, status: "success"|"failed"|"skipped",
reason?: string, durationMs, createdAt
}

notifications {
_id, userId, projectId, type: "task"|"system",
title, body, href, read: boolean, createdAt
}

webhook_endpoints { _id, projectId, url, secretHash, enabled, createdAt }
```

**Idempotency**: store a short-ttl key `rule:{ruleId}:event:{eventId}` (Redis/Upstash) or a unique index on `(ruleId, eventId)` in `rule_runs`.

---

## API (Next.js Route Handlers)

* `POST /api/automation/rules` (admin only) — create rule
* `GET /api/automation/rules?projectId=` — list rules
* `PATCH /api/automation/rules/:id` — enable/disable/update
* `POST /api/automation/test` — dry-run with sample payload
* `GET /api/automation/runs?ruleId=` — recent executions
* `GET /api/notifications` — list for current user
* `PATCH /api/notifications/read` — mark read / mark all
* `POST /api/webhooks/:endpointId` — receive generic webhook (verifies secret)

**Event Bus**
Create a tiny internal dispatcher:

```ts
emitEvent("task.updated", { eventId, projectId, before, after, actorId })
```

Handlers fetch eligible rules (by trigger & project), filter by conditions, enforce idempotency, then execute actions.

---

## Auth0 / RBAC

* Only **Admin/Project Manager** can create/update rules.
* All users can **receive** notifications; only affected project members see rule-generated changes.
* Verify scopes/roles on all automation endpoints.

---

## Actions (v1)

* **notify** (in-app): create `notifications` doc per target (assignee, role, custom list)
* **email** (optional; use existing mailer or stub)
* **webhook**: POST JSON payload to configured URL with HMAC signature (secret)
* **update_task**: set fields (status, labels, dueDate, priority)
* **add_comment**: append comment to task
* **reassign**: change assignee
* **set_status**: quick status switch

---

## Scheduling

* **Cron trigger** via Next.js **cron job** (Vercel Cron or self-hosted scheduler).
Store last run cursor per rule to avoid re-runs.

---

## Telemetry & Safety

* Log run duration & outcome to `rule_runs`.
* Circuit-break action type if error rate > X% in Y min.
* Per-rule execution timeout (e.g., 5s) and global concurrency cap.

---

## Acceptance Criteria

* Create/list/update/disable rules via UI & API with RBAC enforcement.
* Events from task create/update reliably fire matching rules; conditions evaluated correctly.
* Idempotent execution: the same `eventId` never triggers duplicate actions for a rule.
* In-app notifications render with unread badge, pagination, and “mark all read”.
* Audit trail visible per rule (runs list with status and timestamps).
* Documentation added to README (Automations section) with examples.
* ≥ 90% unit coverage for evaluator + dispatcher; integration tests for common flows.

---

## Rollout Plan

1. Phase 1: in-app notifications + `task.updated` trigger, `notify|set_status|add_comment` actions.
2. Phase 2: webhook & email actions, cron trigger.
3. Phase 3: rule exports/imports, templates (e.g., “Auto-assign high-priority bugs to PM”).