Web Work Order System

Project: Auto-Accept Work Orders Bot
1) Goal & Summary
Build a reliable, secure bot that monitors a client’s vendor portal webpage, detects newly posted work orders, and accepts them instantly according to configurable rules. The bot should run unattended, refresh intelligently (not aggressively), and provide audit logs and notifications of every action it takes.
2) Primary User Story
As a service vendor, I want a bot that keeps an active session on my client’s work-order portal and automatically accepts eligible orders the moment they appear, so I don’t miss assignments and don’t have to watch the screen.
3) Key Outcomes / Success Metrics
Acceptance speed: Accept eligible orders within ≤1 second of them appearing in the DOM (subject to site latency).

Reliability: ≥99% successful acceptance on eligible orders over a 7-day test.

Safety: Zero account lockouts; zero ToS violations; no CAPTCHAs triggered by bot behavior during testing.

Traceability: 100% of actions logged with timestamps, order IDs, and outcomes.

4) Scope & Features
Must-haves
Headless browser automation (Playwright or Puppeteer) that:

Logs in using stored credentials (via secure env vars).

Navigates to the work-orders list.

Monitors the page via DOM watchers or server events (WebSocket/XHR interception) and accepts a new order as soon as it matches rules.

Refresh strategy: smart refresh or long-polling; avoid tight loops. Backoff & jitter to prevent rate-limit flags.

Rule engine: accept only if criteria match (e.g., zip codes, service types, price threshold, SLA window).

Conflict handling: detect if an order was accepted by someone else; gracefully continue.

Retry logic: configurable retries for transient failures (network, 5xx, timeout).

Session resilience: auto-relogin on session expiration; handle CSRF tokens/hidden fields.

Selectors management: centralize CSS/XPath selectors with comments and robust fallback strategies.

Observability & Ops

Structured logging (JSON) for login, page navigation, detection, click events, success/failure.

Notifications: Slack/Email on successful acceptance, errors, lockouts.

Health checks: simple /health endpoint and periodic heartbeat log.

Configuration

.env driven: credentials, portal base URL, polling interval, rules, headless/headful mode.

Multi-client readiness: support profiles for different portals (separate creds/rules).

Packaging

Dockerized runtime; docker compose up starts the bot + optional watchdog.

Makefile or npm/yarn scripts for dev/test/run.

Security

No hard-coded credentials. Secrets via env vars or secrets manager.

Respect site Terms of Service; throttle requests; human-like delays where needed.

Do not bypass CAPTCHAs or other anti-bot protections.

Nice-to-haves
Web dashboard to view live status, last 50 events, and update rules without redeploy.

Metrics export (Prometheus) and Grafana dashboard.

Pluggable notifier (Slack, Teams, Email, SMS).

Basic anomaly detection (sudden DOM/schema change alert).

5) Non-Goals
Building an interface to edit client data within the portal beyond accepting orders.
Circumventing anti-bot defenses or CAPTCHAs.
Screen scraping for downstream databases beyond minimal fields required for acceptance and logs.


6) Technical Requirements
Language/Stack: Node.js (Playwright preferred) or Python (Playwright/Pyppeteer). Justify choice.
Runtime: Linux container; compatible with a small VPS.
State: Stateless where possible; small SQLite/JSON file (or Redis) acceptable for idempotency (remember recently seen order IDs).
Tests:

Unit tests for rules & utilities.

Integration “dry-run” mode that simulates accept clicks without submitting.

Error Handling: Centralized handler with categories (auth, navigation, selector-not-found, network, rate-limit).
Idempotency: Prevent double-accept on the same order.
7) Inputs the Coder Needs From Us
Portal URL(s) and a test login with limited permissions.
Example “new order” page(s) and acceptance workflow steps.
Acceptance criteria (service areas, price floors, SLAs, exclusions).
Preferred notification channel(s).
Any known rate-limit or ToS guidance from the client.
8) Deliverables
Source code repo with:

README.md (setup, .env template, runbook, troubleshooting).

CONFIG.md (rules, selectors, how to update them).

Tests and CI workflow (lint, unit tests).

Dockerfile + docker-compose.

Example Grafana dashboard JSON (if metrics implemented).

Short operational runbook (start/stop, rotate creds, update selectors).

Demo script: runs in headful mode and shows a simulated acceptance.

9) Acceptance Criteria (Definition of Done)
Can log in, remain authenticated for ≥8 hours, and reauthenticate on expiry.

Detects a newly posted test order and accepts it within the target time.

Logs include: timestamp, order ID, action, outcome, response status, latency.

Notification sent within 5 seconds of acceptance.

Handles site or DOM change by surfacing a clear error and does not crash silently.

Passes dry-run mode in CI; headless mode works in prod.

10) Milestones & Estimates
M1 – Discovery (selectors, flows, constraints): DOM map, network call map, login/session notes.

M2 – Prototype: Login + page watcher + dry-run accept + logs.

M3 – Production Bot: Real accept, retries, rules, notifications, Docker.

M4 – Hardening: Tests, health checks, metrics, runbook.

M5 – Handover: Demo, documentation walkthrough.

11) Legal & Compliance Notes
Bot must comply with the portal’s Terms of Service and any vendor agreements.

No CAPTCHA bypassing; if CAPTCHA appears, pause and alert.

Respect robots, rate limits, and avoid behavior that could be construed as abusive access.