feat(notifications): wire publisher + async feature flag (GOO-173)

Phase 1 step 3 — make NotificationsPublisher available via DI and
introduce the NOTIFICATIONS_ASYNC_ENABLED flag that will gate the
listener cutover.

- NotificationsAsyncConfig: tiny injectable that reads
  NOTIFICATIONS_ASYNC_ENABLED (truthy: 1/true/yes/on, default disabled).
  Callers don't touch process.env directly; per-category rollout can be
  added later without churn in listeners.
- NotificationsModule providers/exports now include NotificationsPublisher
  and NotificationsAsyncConfig so listeners/handlers can inject them.
- Tests (14 specs on the flag + 4 on the publisher = 18 total green):
  * default disabled when unset
  * truthy parsing (1, true, TRUE, yes, on, padded)
  * falsy parsing (false, 0, no, off, empty, unknown)
  * describe() reports human-readable state

No call sites updated yet — next commit migrates the first listener
(PaymentCompletedListener pilot) onto the publisher with the flag check.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/src/modules/notifications/infrastructure/__tests__/notifications-async.config.spec.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { NotificationsAsyncConfig } from '../services/notifications-async.config';
+
+const FLAG = 'NOTIFICATIONS_ASYNC_ENABLED';
+
+describe('NotificationsAsyncConfig', () => {
+  const originalValue = process.env[FLAG];
+
+  afterEach(() => {
+    if (originalValue === undefined) {
+      delete process.env[FLAG];
+    } else {
+      process.env[FLAG] = originalValue;
+    }
+  });
+
+  it('defaults to disabled when the env var is unset', () => {
+    delete process.env[FLAG];
+    expect(new NotificationsAsyncConfig().asyncEnabled).toBe(false);
+  });
+
+  it.each(['true', 'TRUE', '1', 'yes', 'on', '  true  '])(
+    'treats %j as enabled',
+    (value) => {
+      process.env[FLAG] = value;
+      expect(new NotificationsAsyncConfig().asyncEnabled).toBe(true);
+    },
+  );
+
+  it.each(['false', '0', 'no', 'off', '', 'maybe'])(
+    'treats %j as disabled',
+    (value) => {
+      process.env[FLAG] = value;
+      expect(new NotificationsAsyncConfig().asyncEnabled).toBe(false);
+    },
+  );
+
+  it('describe() reports the human-readable state', () => {
+    process.env[FLAG] = 'true';
+    expect(new NotificationsAsyncConfig().describe()).toBe(
+      'NOTIFICATIONS_ASYNC_ENABLED=enabled',
+    );
+    process.env[FLAG] = 'false';
+    expect(new NotificationsAsyncConfig().describe()).toBe(
+      'NOTIFICATIONS_ASYNC_ENABLED=disabled',
+    );
+  });
+});

apps/api/src/modules/notifications/infrastructure/services/notifications-async.config.ts

@@ -0,0 +1,33 @@
+/**
+ * Feature-flag config for the Phase 1 async notifications path (RFC-004 / GOO-173).
+ *
+ * When NOTIFICATIONS_ASYNC_ENABLED is `true`, producers route through
+ * `NotificationsPublisher` → outbox → Redis Streams → BullMQ consumer.
+ * When `false` (default until parity is confirmed in production), producers
+ * continue to execute `SendNotificationCommand` directly in-process.
+ *
+ * Kept as a tiny injectable so:
+ *   - callers don't read process.env directly (testability)
+ *   - we have one place to evolve the flag shape (per-category rollout,
+ *     percentage shadowing, etc.) without ripping through listeners again
+ */
+
+import { Injectable } from '@nestjs/common';
+
+const FLAG_ENV = 'NOTIFICATIONS_ASYNC_ENABLED';
+
+@Injectable()
+export class NotificationsAsyncConfig {
+  /** True when the async outbox path should be used for new notifications. */
+  get asyncEnabled(): boolean {
+    const raw = process.env[FLAG_ENV];
+    if (raw === undefined) return false;
+    const v = raw.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+  }
+
+  /** Exposed for observability / startup logs. */
+  describe(): string {
+    return `${FLAG_ENV}=${this.asyncEnabled ? 'enabled' : 'disabled'}`;
+  }
+}

apps/api/src/modules/notifications/notifications.module.ts

@@ -34,6 +34,8 @@ import { PrismaNotificationPreferenceRepository } from './infrastructure/reposit
 import { PrismaNotificationRepository } from './infrastructure/repositories/prisma-notification.repository';
 import { EmailService } from './infrastructure/services/email.service';
 import { FcmService } from './infrastructure/services/fcm.service';
+import { NotificationsAsyncConfig } from './infrastructure/services/notifications-async.config';
+import { NotificationsPublisher } from './infrastructure/services/notifications-publisher.service';
 import { SmsRateLimiterService } from './infrastructure/services/sms-rate-limiter.service';
 import { StringeeSmsService } from './infrastructure/services/stringee-sms.service';
 import { TemplateService } from './infrastructure/services/template.service';
@@ -87,6 +89,10 @@ const EventListeners = [
     ZaloOaService,
     TemplateService,
 
+    // RFC-004 Phase 1 — async notifications (GOO-173)
+    NotificationsAsyncConfig,
+    NotificationsPublisher,
+
     // WebSocket Gateway
     NotificationsGateway,
 
@@ -104,6 +110,8 @@ const EventListeners = [
     SMS_NOTIFICATION_CHANNEL,
     ZaloOaService,
     TemplateService,
+    NotificationsAsyncConfig,
+    NotificationsPublisher,
     NotificationsGateway,
   ],
 })

apps/web/app/[locale]/(admin)/loading.tsx

@@ -1,6 +1,6 @@
 export default function AdminLoading() {
   return (
-    <div className="space-y-6">
+    <div className="space-y-6" aria-busy="true" aria-label="Đang tải trang quản trị">
       {/* Header skeleton */}
       <div className="flex items-center justify-between">
         <div>

apps/web/app/[locale]/(auth)/loading.tsx

@@ -1,6 +1,6 @@
 export default function AuthLoading() {
   return (
-    <div className="rounded-lg border bg-card p-8 shadow-sm">
+    <div className="rounded-lg border bg-card p-8 shadow-sm" aria-busy="true" aria-label="Đang tải trang đăng nhập">
       <div className="space-y-6">
         {/* Logo / title skeleton */}
         <div className="text-center">

apps/web/app/[locale]/(dashboard)/loading.tsx

@@ -1,6 +1,6 @@
 export default function DashboardLoading() {
   return (
-    <div className="space-y-8">
+    <div className="space-y-8" aria-busy="true" aria-label="Đang tải bảng điều khiển">
       {/* Header skeleton */}
       <div className="flex items-center justify-between">
         <div>

apps/web/app/[locale]/(public)/search/loading.tsx

@@ -1,6 +1,6 @@
 export default function SearchLoading() {
   return (
-    <div className="mx-auto max-w-7xl px-4 py-6">
+    <div className="mx-auto max-w-7xl px-4 py-6" aria-busy="true" aria-label="Đang tải kết quả tìm kiếm">
       {/* Header skeleton */}
       <div className="mb-6">
         <div className="h-8 w-64 animate-pulse rounded bg-muted" />

apps/web/app/[locale]/loading.tsx

@@ -1,6 +1,6 @@
 export default function RootLoading() {
   return (
-    <div className="flex min-h-screen flex-col bg-background">
+    <div className="flex min-h-screen flex-col bg-background" aria-busy="true" aria-label="Đang tải trang">
       {/* Header skeleton */}
       <div className="border-b">
         <div className="mx-auto flex h-16 max-w-7xl items-center justify-between px-4">

apps/web/app/globals.css

@@ -117,6 +117,18 @@
   [data-numeric] {
     font-variant-numeric: tabular-nums;
   }
+
+  /* Consistent focus-visible ring for all interactive elements */
+  :focus-visible {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+    border-radius: var(--radius);
+  }
+
+  /* Remove outline for mouse users; keep it for keyboard navigation */
+  :focus:not(:focus-visible) {
+    outline: none;
+  }
 }
 
 /* Mapbox popup theming */

apps/web/components/agents/agent-profile-client.tsx

@@ -267,7 +267,7 @@ export function AgentProfileClient({
   return (
     <div className="mx-auto max-w-7xl px-4 py-6 space-y-6">
       {/* ── Breadcrumb ── */}
-      <nav className="flex items-center gap-1.5 text-xs text-foreground-muted">
+      <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-xs text-foreground-muted">
         <Link href="/" className="hover:text-foreground transition-colors">Trang chủ</Link>
         <span>/</span>
         <Link href="/agents" className="hover:text-foreground transition-colors">Môi giới</Link>

apps/web/components/listings/listing-detail-client.tsx

@@ -459,7 +459,7 @@ export function ListingDetailClient({ listing }: ListingDetailClientProps) {
     /* pb-28 reserves space for the sticky action bar on mobile */
     <div className="mx-auto max-w-6xl px-4 pb-28 pt-4 lg:pb-6">
       {/* ── Breadcrumb + header strip ─────────────────────────── */}
-      <nav className="mb-3 flex items-center gap-1.5 text-xs text-[hsl(var(--foreground-muted))]">
+      <nav aria-label="Breadcrumb" className="mb-3 flex items-center gap-1.5 text-xs text-[hsl(var(--foreground-muted))]">
         <Link href="/" className="hover:text-foreground">Trang chủ</Link>
         <span>/</span>
         <Link href="/search" className="hover:text-foreground">Tìm kiếm</Link>