device-voice-h5/openspec/changes/add-personal-notifications/specs/personal-notifications/spec.md

ADDED Requirements

Requirement: Personal customers SHALL be able to query notifications

The system SHALL provide GET /api/c/v1/notifications for authenticated personal customers. The endpoint SHALL return only visible, unexpired business notifications for the current customer, ordered by creation time descending and notification ID descending.

Scenario: Query the first notification page

• WHEN an authenticated customer requests the notification list without pagination parameters
• THEN the system SHALL return page 1 with up to 20 notifications
• AND the response SHALL include items, page, size, and total

Scenario: Apply valid pagination

• WHEN the request includes page from 1 to 10000 and page_size from 1 to 50
• THEN the system SHALL return the requested page and page size

Scenario: Reject invalid pagination

• WHEN page or page_size is outside its allowed range
• THEN the system SHALL return a parameter validation error

Requirement: Notification items SHALL expose client-readable status and metadata

Each notification item SHALL include id, title, body, type, category, severity, ref_type, ref_id, ref_key, is_read, created_at, and nullable read_at.

Scenario: Return an unread notification

• WHEN a visible notification has not been read by the current customer
• THEN the system SHALL return is_read: false and read_at: null

Requirement: Personal customers SHALL be able to mark one notification as read

The system SHALL provide PUT /api/c/v1/notifications/{id}/read for authenticated personal customers. The operation SHALL be idempotent and SHALL only update a notification visible to the current customer.

Scenario: Mark a visible unread notification

• WHEN the customer marks a visible unread notification as read
• THEN the system SHALL set its read state and return { "success": true }

Scenario: Mark an unavailable or already-read notification

• WHEN the notification does not exist, belongs to another customer, or is already read
• THEN the system SHALL return { "success": true } without exposing ownership information

Requirement: Personal customers SHALL be able to mark all notifications as read

The system SHALL provide PUT /api/c/v1/notifications/read-all to mark all visible, unexpired, unread business notifications for the current customer as read.

Scenario: Mark all unread notifications

• WHEN the customer calls the mark-all-read endpoint
• THEN the system SHALL return the number of notifications actually updated in updated_count
• AND repeated calls SHALL remain successful and return zero when nothing needs updating

Requirement: Personal customers SHALL be able to query unread count

The system SHALL provide GET /api/c/v1/notifications/unread-count. The count SHALL include only visible, unexpired business notifications and SHALL exclude platform sync and system operations notifications.

Scenario: Return unread count and badge text

• WHEN an authenticated customer queries the unread count
• THEN the system SHALL return numeric count and string display_count
• AND display_count SHALL be 99+ when count exceeds 99