[BE-66] Implement WebSocket gateway for real-time asset events and live notifications

[yusuftomilola]

Overview

The existing notification system dispatches records to the database, but there is no push mechanism to inform connected clients instantly. Users must refresh the page to see new notifications, asset status changes, or incoming maintenance alerts. This issue adds a WebSocket gateway to push events to clients in real time.

Context

• @nestjs/websockets and socket.io are already installed (referenced in recent BullMQ PR)
• The notification entity (from BE-53 or BE-54) is the source of truth — the gateway emits after a notification is persisted
• Clients should authenticate the WebSocket connection using the same JWT access token used for HTTP

Acceptance Criteria

• Create src/gateway/events.gateway.ts extending WebSocketGateway with CORS configured from ConfigService
• On client connection: validate the JWT from the handshake query/header, reject unauthenticated connections with a WsException
• Join the authenticated user to a private room keyed by user.id
• Emit notification.new event when a notification is created for a user
• Emit asset.status_changed event to the asset's department room when an asset status changes
• Emit maintenance.due event when a maintenance job processor detects an upcoming due date
• Create GatewayModule and register it in AppModule
• Document the event schema for each emitted event in src/gateway/events.gateway.ts JSDoc

[otobongdev]

@otobongdev has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello maintainer, I can fix this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @otobongdev to this issue.

[Mkalbani]

@Mkalbani has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi maintainers, can I work on this. I've worked on a similar work. Thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mkalbani to this issue.

[drips-wave]

Congratulations, @Mkalbani! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Mkalbani: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Mkalbani's PR #1248 was approved and merged by @yusuftomilola.

🏆 @Mkalbani: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (799 total points). Track your full progress on GrantFox.

👏 Great work, @Mkalbani! Keep contributing to DistinctCodes.

[drips-wave]

This issue has been completed by @Mkalbani as part of the Stellar Wave Program's 7th Wave 🥳

😎 @Mkalbani: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.