HU-CORE-14B-transaction-notification-integration-for-HU-MKT-13

[victortelles]

HU-CORE-14B-transaction-notification-integration-for-HU-MKT-13

Domain: Core

User Story

As an authenticated Marketplace user, I want to receive transaction status notifications so I can react on time (accept, cancel, confirm delivery) without manually checking the transactions panel.

Detailed Description

HU-MKT-13 already supports request creation, accept/cancel actions, and completion with dual confirmation. What is still missing is the real integration with Core notifications for transaction events. Right now, the frontend only shows placeholder messages such as "Notification pending".

This story adds the Core integration layer so buyer and seller receive in-app notifications based on transaction status and actor role.

Acceptance Criteria

• When a transaction request is created, the seller receives a new request notification.
• When a request is accepted or canceled, the buyer receives a status update notification.
• When one side confirms delivery, the counterpart receives a pending-confirmation notification.
• When both sides confirm delivery and the transaction is completed, both users receive a completion notification.
• Notifications include transaction id and related product id.
• Notifications are visible from the Core notification center.
• Messages remain consistent with production status values: pendiente, confirmada, completada, cancelada.

Implementation Details

Backend

• Publish a stable notification contract from Marketplace to Core.
• Consume transaction events from the following points:
  • create_transaction_request
  • update_transaction_status -> confirmada
  • update_transaction_status -> cancelada
  • update_transaction_status -> completada (partial confirmation and final completion)
• Define minimum payload:
  • transaction_id
  • product_id
  • actor_id
  • recipient_id
  • previous_status
  • current_status
  • event_type
  • created_at
• Add idempotency by event_id to prevent duplicate notifications on retries.

Frontend

• Replace temporary "Notification pending" messages with real notification feedback.
• Keep navbar badge/unread count in sync after transaction actions.

Database

• Persist notification records in Core with transaction_id reference.
• Recommended indexes: recipient_id, is_read, created_at, event_type.

Testing Notes

• Verify notification creation on request creation.
• Verify notification delivery on accept/cancel/completion events.
• Verify no duplicate notifications on retries.
• Verify visibility is limited to intended recipient.
• Verify expired transactions do not emit incorrect notifications.

Test Data Required

• Two authenticated users (buyer and seller).
• One available product.
• One transaction path: pendiente -> confirmada -> completada.
• Alternate scenarios: cancellation and expiration.

Potential Mocks

• Marketplace event emitter mock.
• Notification transport mock (queue/broker if used).
• Frontend notification read/unread service mock.

Dependencies & Duplication Check (GitHub MCP Cross-check)

Dependencies:

• HU-MKT-13 transaction flow: HU-MKT-13-transaction-flow #99
• HU-CORE-14 notifications baseline: HU-CORE-14: User can receive and view notifications #96

Duplication assessment:

• Not a duplicate of HU-CORE-14: User can receive and view notifications #96.
• HU-CORE-14: User can receive and view notifications #96 is the platform-wide notifications foundation.
• This story is a transaction-specific integration slice required by HU-MKT-13-transaction-flow #99.

Assumptions

• Core already owns notification persistence and read/unread APIs.
• Marketplace can publish events or call Core notification services without changing current transaction model constraints.
• Scope is in-app notifications only (no email/push/websocket requirement in this story).

Warnings

• Without idempotency, duplicate notifications can occur in retry scenarios.
• If Core and Marketplace status catalogs diverge, users will receive inconsistent messages.
• This story must not alter transaction business rules; it only integrates Core notification delivery.