82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# Web Console: Notifications & Human-Attention Routing (#648)
|
|
|
|
- **Status:** Phase 3 Live
|
|
- **Tracking Issue:** [#648](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/648)
|
|
- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/631)
|
|
- **Attention Boundary Reference:** [#628](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/628)
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
The **Notifications & Human-Attention Console** (`/notifications`, `/api/v1/notifications`) provides intelligent event classification and human-attention routing for autonomous workflow operations.
|
|
|
|
To prevent alert fatigue while ensuring critical escalation boundaries are never missed, events are classified into three distinct **Attention Classes**:
|
|
|
|
1. **`human-required`** (Urgent Escalation Boundary):
|
|
- Items requiring immediate human intervention or business decisions.
|
|
- Triggers: Auth failures, hard stops, irrecoverable state, decision locks, failed report validations, critical probe errors.
|
|
- Display: Highlighted in red (`badge-blocked`) with a `HUMAN REQUIRED` badge.
|
|
|
|
2. **`operator`** (Operational Inbox):
|
|
- Items requiring controller or operator review/triage during routine execution.
|
|
- Triggers: Blocked PRs (merge conflicts), stale leases, duplicate PRs on issues, unassigned ready work.
|
|
- Display: Displayed in orange/yellow (`badge-claimed`).
|
|
|
|
3. **`routine`** (Background Workflow Transitions):
|
|
- Normal, healthy workflow transitions and state progressions.
|
|
- Triggers: Active PRs/issues in standard state, clean branch creation, routine heartbeats.
|
|
- Display: Filtered out of default inbox views to eliminate notification spam; viewable on demand via the "Routine" or "All" tab.
|
|
|
|
---
|
|
|
|
## 2. API Endpoints
|
|
|
|
### `GET /api/v1/notifications`
|
|
*Compatibility Alias:* `GET /api/notifications`
|
|
|
|
#### Query Parameters:
|
|
- `project_id` (optional): Filter notifications by project ID.
|
|
- `attention_class` (optional): `inbox` (default: human-required + operator), `human-required`, `operator`, `routine`, `all`.
|
|
|
|
#### Example JSON Response:
|
|
```json
|
|
{
|
|
"project_id": "gitea-tools",
|
|
"repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
|
|
"human_required_count": 0,
|
|
"operator_count": 2,
|
|
"routine_count": 5,
|
|
"total_count": 7,
|
|
"fetch_error": null,
|
|
"inbox_items": [
|
|
{
|
|
"id": "notif-pr-block-742",
|
|
"attention_class": "operator",
|
|
"category": "blocker",
|
|
"title": "Blocked PR #742",
|
|
"summary": "PR #742 requires merge conflict resolution.",
|
|
"work_kind": "pr",
|
|
"work_number": 742,
|
|
"project_id": "gitea-tools",
|
|
"repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
|
|
"created_at": "2026-07-25T16:39:47Z",
|
|
"deep_link": "/traffic",
|
|
"requires_human": false,
|
|
"extra": {}
|
|
}
|
|
],
|
|
"all_items": [...]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. UI Navigation
|
|
|
|
- Access via the **Traffic** navigation menu: **Traffic → Notifications**.
|
|
- The main view displays:
|
|
- **Metrics Summary Bar**: Highlighting counts for Human Required, Operator Inbox, and Routine items.
|
|
- **Attention Filter Tabs**: Toggle between Inbox (Human + Operator), Human Required, Operator, Routine, and All.
|
|
- **Structured Event Table**: Displays category, title, summary, work item links, and timestamps.
|