where_woof/openspec/changes/scan-limits-gating/specs/alert-limits/spec.md

ADDED Requirements

Requirement: Paid-order gating

When a tag has a linked order (order_id not null) whose status is not paid, scans SHALL be recorded but no alert SMS SHALL be sent. Tags without a linked order SHALL still alert (transitional).

Scenario: Lapsed order

• WHEN a scan arrives on a tag whose order status is lapsed or pending
• THEN the scan is recorded with alert_sent = false and no SMS is sent

Scenario: Paid order

• WHEN a scan arrives on a tag whose order is paid
• THEN normal alert rules apply

Scenario: No order yet

• WHEN a scan arrives on a tag with no linked order
• THEN normal alert rules apply (transitional behaviour)

Requirement: Per-tag daily alert cap

A tag SHALL alert at most N times in any 24-hour window (N configurable, default 5). Excess scans are recorded without alerts.

Scenario: Cap reached

• WHEN a tag has already alerted N times in the last 24 h
• THEN further scans are recorded but no SMS is sent

Requirement: Per-IP hourly rate limit

A scanner IP SHALL trigger at most M alerts per hour (M configurable, default 10). Excess alerts from the same IP are suppressed.

Scenario: Rate exceeded

• WHEN an IP has triggered M alerts in the last hour
• THEN further scan alerts from that IP are suppressed (scans still recorded)