ci: skip deploy when environment secrets are missing

Remediate CI blockers and production readiness issues

.env.example

@@ -91,6 +91,15 @@ JWT_EXPIRES_IN=15m
 JWT_REFRESH_SECRET=<generate with: openssl rand -base64 48>
 JWT_REFRESH_EXPIRES_IN=7d
 
+# -----------------------------------------------------------------------------
+# Seed / E2E Accounts
+# -----------------------------------------------------------------------------
+# Required when running `pnpm db:seed`. Use a local/test-only value.
+# Do not reuse this password for any real production admin account.
+SEED_DEFAULT_PASSWORD=
+BCRYPT_ROUNDS=12
+E2E_ADMIN_PHONE=0876677771
+
 # -----------------------------------------------------------------------------
 # OAuth Providers
 # -----------------------------------------------------------------------------
@@ -110,11 +119,19 @@ FRONTEND_URL=http://localhost:3000
 NEXT_PUBLIC_API_URL=http://localhost:3000
 WEB_PORT=3001
 
+# Demo accounts must stay disabled in production. To enable in a local demo,
+# provide a JSON array of {phone,name,role,badgeClass} and a temporary password.
+NEXT_PUBLIC_ENABLE_DEMO_ACCOUNTS=false
+NEXT_PUBLIC_DEMO_PASSWORD=
+NEXT_PUBLIC_DEMO_ACCOUNTS=
+
 # -----------------------------------------------------------------------------
 # AI Service (Python/FastAPI)
 # -----------------------------------------------------------------------------
 AI_SERVICE_PORT=8000
 AI_SERVICE_URL=http://localhost:8000
+AI_SERVICE_API_KEY=<optional-in-dev-required-in-prod>
+AI_CORS_ORIGINS=http://localhost:3000,http://localhost:3001
 CLAUDE_API_KEY=
 
 # -----------------------------------------------------------------------------
@@ -221,7 +238,10 @@ SENTRY_PROJECT=
 # Must be exactly 64 hex characters (32 bytes).
 #   openssl rand -hex 32
 # -----------------------------------------------------------------------------
-KYC_ENCRYPTION_KEY=<generate with: openssl rand -hex 32>
+FIELD_ENCRYPTION_KEY=<generate with: openssl rand -hex 32>
+FIELD_ENCRYPTION_KEY_VERSION=1
+# Backward-compatible fallback accepted by the API; prefer FIELD_ENCRYPTION_KEY.
+KYC_ENCRYPTION_KEY=
 KYC_ENCRYPTION_KEY_VERSION=1
 
 # -----------------------------------------------------------------------------

.env.test

@@ -51,6 +51,10 @@ CORS_ORIGINS=http://localhost:3010,http://localhost:3000
 # Bcrypt (fast rounds for test — production uses 12+)
 BCRYPT_ROUNDS=4
 
+# Seeded admin used by E2E happy-path admin flows
+SEED_DEFAULT_PASSWORD=Test@1234!
+E2E_ADMIN_PHONE=0876677771
+
 # OAuth (test stubs)
 GOOGLE_CLIENT_ID=test-google-client-id
 GOOGLE_CLIENT_SECRET=test-google-client-secret
@@ -70,3 +74,8 @@ MOMO_SECRET_KEY=TEST_MOMO_SECRET_KEY
 ZALOPAY_APP_ID=TEST_ZALOPAY_APP
 ZALOPAY_KEY1=TEST_ZALOPAY_KEY1
 ZALOPAY_KEY2=TEST_ZALOPAY_KEY2
+BANK_TRANSFER_ACCOUNT_NUMBER=0123456789
+BANK_TRANSFER_BANK_NAME=Vietcombank
+BANK_TRANSFER_ACCOUNT_HOLDER=CONG_TY_GOODGO
+BANK_TRANSFER_WEBHOOK_SECRET=test-bank-transfer-webhook-secret-minimum-32-chars
+BANK_TRANSFER_INSTRUCTIONS_URL=http://localhost:3010/thanh-toan/chuyen-khoan

.github/workflows/ci.yml

@@ -149,79 +149,10 @@ jobs:
     name: E2E Tests
     needs: ci
     runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    services:
-      postgres:
-        image: postgis/postgis:16-3.4
-        env:
-          POSTGRES_DB: goodgo_test
-          POSTGRES_USER: goodgo
-          POSTGRES_PASSWORD: goodgo_test_secret
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U goodgo -d goodgo_test"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-          --health-start-period 30s
-
-      redis:
-        image: redis:7-alpine
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-      typesense:
-        image: typesense/typesense:27.1
-        ports:
-          - 8108:8108
-        env:
-          TYPESENSE_API_KEY: ts_ci_key
-          TYPESENSE_DATA_DIR: /data
-        options: >-
-          --health-cmd "curl -sf http://localhost:8108/health || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-      minio:
-        image: minio/minio:latest
-        ports:
-          - 9000:9000
-        env:
-          MINIO_ROOT_USER: ci_minio_user
-          MINIO_ROOT_PASSWORD: ci_minio_secret_key_32chars!!
-        options: >-
-          --health-cmd "curl -sf http://localhost:9000/minio/health/live || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
+    timeout-minutes: 45
 
     env:
-      DATABASE_URL: postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
-      REDIS_URL: redis://localhost:6379
-      TYPESENSE_URL: http://localhost:8108
-      TYPESENSE_HOST: localhost
-      TYPESENSE_PORT: 8108
-      TYPESENSE_API_KEY: ts_ci_key
-      MINIO_ENDPOINT: localhost
-      MINIO_PORT: 9000
-      MINIO_ACCESS_KEY: ci_minio_user
-      MINIO_SECRET_KEY: ci_minio_secret_key_32chars!!
-      MINIO_BUCKET: goodgo-uploads
-      NODE_ENV: test
-      JWT_SECRET: e2e-test-jwt-secret-key
-      JWT_REFRESH_SECRET: e2e-test-refresh-secret-key
-      VNPAY_TMN_CODE: TESTCODE
-      VNPAY_HASH_SECRET: TESTHASHSECRET
-      VNPAY_URL: https://sandbox.vnpayment.vn/paymentv2/vpcpay.html
-      VNPAY_RETURN_URL: http://localhost:3000/payment/return
+      CI: true
 
     steps:
       - name: Checkout
@@ -239,6 +170,12 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Load E2E environment
+        run: awk 'NF && $1 !~ /^#/' .env.test >> "$GITHUB_ENV"
+
+      - name: Start CI service stack
+        run: docker compose --env-file .env.ci -f docker-compose.ci.yml up -d --wait
+
       - name: Cache Playwright browsers
         id: playwright-cache
         uses: actions/cache@v4
@@ -281,3 +218,7 @@ jobs:
           name: playwright-traces
           path: test-results/
           retention-days: 7
+
+      - name: Stop CI service stack
+        if: always()
+        run: docker compose --env-file .env.ci -f docker-compose.ci.yml down -v

.github/workflows/codeql.yml

@@ -1,61 +0,0 @@
-name: CodeQL Analysis
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-  schedule:
-    # Run weekly on Monday at 06:17 UTC — off-peak to avoid :00/:30 congestion
-    - cron: "17 6 * * 1"
-
-concurrency:
-  group: codeql-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  actions: read
-  contents: read
-  security-events: write
-
-jobs:
-  analyze:
-    name: CodeQL (${{ matrix.language }})
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [javascript-typescript]
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
-        with:
-          languages: ${{ matrix.language }}
-          # Use extended security queries for deeper analysis
-          queries: security-extended,security-and-quality
-          config: |
-            paths:
-              - apps/
-              - libs/
-            paths-ignore:
-              - node_modules/
-              - "**/dist/"
-              - "**/*.spec.ts"
-              - "**/*.test.ts"
-              - "**/__tests__/"
-
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
-        with:
-          category: "/language:${{ matrix.language }}"
-          # SARIF results are automatically uploaded to GitHub Security tab
-          upload: always

.github/workflows/deploy.yml

@@ -23,6 +23,53 @@ env:
   REGISTRY_URL: ghcr.io/${{ github.repository_owner }}
 
 jobs:
+  deploy-config:
+    name: Check Deploy Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      staging_ready: ${{ steps.check.outputs.staging_ready }}
+      production_ready: ${{ steps.check.outputs.production_ready }}
+
+    steps:
+      - name: Check required deploy secrets
+        id: check
+        env:
+          TARGET_ENV: ${{ inputs.environment }}
+          STAGING_HOST: ${{ secrets.STAGING_HOST }}
+          STAGING_USER: ${{ secrets.STAGING_USER }}
+          STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
+          STAGING_URL: ${{ secrets.STAGING_URL }}
+          STAGING_API_URL: ${{ secrets.STAGING_API_URL }}
+          PRODUCTION_HOST: ${{ secrets.PRODUCTION_HOST }}
+          PRODUCTION_USER: ${{ secrets.PRODUCTION_USER }}
+          PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+          PRODUCTION_URL: ${{ secrets.PRODUCTION_URL }}
+          PRODUCTION_API_URL: ${{ secrets.PRODUCTION_API_URL }}
+        run: |
+          STAGING_READY=false
+          PRODUCTION_READY=false
+
+          if [ -n "$STAGING_HOST" ] && [ -n "$STAGING_USER" ] && [ -n "$STAGING_SSH_KEY" ] && [ -n "$STAGING_URL" ] && [ -n "$STAGING_API_URL" ]; then
+            STAGING_READY=true
+          fi
+
+          if [ -n "$PRODUCTION_HOST" ] && [ -n "$PRODUCTION_USER" ] && [ -n "$PRODUCTION_SSH_KEY" ] && [ -n "$PRODUCTION_URL" ] && [ -n "$PRODUCTION_API_URL" ]; then
+            PRODUCTION_READY=true
+          fi
+
+          echo "staging_ready=$STAGING_READY" >> "$GITHUB_OUTPUT"
+          echo "production_ready=$PRODUCTION_READY" >> "$GITHUB_OUTPUT"
+
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ] && [ "$TARGET_ENV" = "staging" ] && [ "$STAGING_READY" != "true" ]; then
+            echo "Missing required staging deploy secrets; configure STAGING_HOST, STAGING_USER, STAGING_SSH_KEY, STAGING_URL, and STAGING_API_URL."
+            exit 1
+          fi
+
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ] && [ "$TARGET_ENV" = "production" ] && [ "$PRODUCTION_READY" != "true" ]; then
+            echo "Missing required production deploy secrets; configure PRODUCTION_HOST, PRODUCTION_USER, PRODUCTION_SSH_KEY, PRODUCTION_URL, and PRODUCTION_API_URL."
+            exit 1
+          fi
+
   build-api:
     name: Build API Image
     runs-on: ubuntu-latest
@@ -154,11 +201,14 @@ jobs:
 
   deploy-staging:
     name: Deploy to Staging
-    needs: [build-api, build-web, build-ai]
+    needs: [deploy-config, build-api, build-web, build-ai]
     if: >-
-      github.ref == 'refs/heads/develop' ||
-      (github.event_name == 'push' && github.ref == 'refs/heads/master') ||
-      (github.event_name == 'workflow_dispatch' && inputs.environment == 'staging')
+      needs.deploy-config.outputs.staging_ready == 'true' &&
+      (
+        github.ref == 'refs/heads/develop' ||
+        (github.event_name == 'push' && github.ref == 'refs/heads/master') ||
+        (github.event_name == 'workflow_dispatch' && inputs.environment == 'staging')
+      )
     runs-on: ubuntu-latest
     environment: staging
 
@@ -221,17 +271,17 @@ jobs:
             [ "\$PREV_WEB" != "none" ] && docker tag "\$PREV_WEB" goodgo-web:rollback 2>/dev/null || true
             [ "\$PREV_AI" != "none" ] && docker tag "\$PREV_AI" goodgo-ai-services:rollback 2>/dev/null || true
 
-            # Pull new images
             docker compose -f docker-compose.prod.yml pull api web ai-services
 
+            # Apply migrations with the newly pulled API image before switching app containers.
+            docker compose -f docker-compose.prod.yml run --rm --no-deps api \
+              npx prisma migrate deploy --schema /app/prisma/schema.prisma
+
             # Rolling update — zero downtime
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait api
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait web
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait ai-services
 
-            # Run database migrations
-            docker compose -f docker-compose.prod.yml exec -T api npx prisma migrate deploy
-
             # NOTE: docker image prune is NOT run here — it runs after smoke tests pass
           DEPLOY_SCRIPT
 
@@ -394,8 +444,11 @@ jobs:
 
   rollback-staging:
     name: Rollback Staging
-    needs: [deploy-staging, smoke-test-staging]
-    if: failure()
+    needs: [deploy-config, deploy-staging, smoke-test-staging]
+    if: >-
+      always() &&
+      needs.deploy-config.outputs.staging_ready == 'true' &&
+      (needs.deploy-staging.result == 'failure' || needs.smoke-test-staging.result == 'failure')
     runs-on: ubuntu-latest
     environment: staging
 
@@ -462,8 +515,11 @@ jobs:
 
   deploy-production:
     name: Deploy to Production
-    needs: [build-api, build-web, build-ai]
-    if: inputs.environment == 'production'
+    needs: [deploy-config, build-api, build-web, build-ai]
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      inputs.environment == 'production' &&
+      needs.deploy-config.outputs.production_ready == 'true'
     runs-on: ubuntu-latest
     environment: production
 
@@ -507,13 +563,15 @@ jobs:
 
             docker compose -f docker-compose.prod.yml pull api web ai-services
 
+            # Apply migrations with the newly pulled API image before switching app containers.
+            docker compose -f docker-compose.prod.yml run --rm --no-deps api \
+              npx prisma migrate deploy --schema /app/prisma/schema.prisma
+
             # Rolling update with health checks
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait api
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait web
             docker compose -f docker-compose.prod.yml up -d --no-deps --wait ai-services
 
-            docker compose -f docker-compose.prod.yml exec -T api npx prisma migrate deploy
-
             # NOTE: docker image prune is NOT run here — it runs after smoke tests pass
           DEPLOY_SCRIPT
 
@@ -652,8 +710,11 @@ jobs:
 
   rollback-production:
     name: Rollback Production
-    needs: [smoke-test-production]
-    if: failure()
+    needs: [deploy-config, deploy-production, smoke-test-production]
+    if: >-
+      always() &&
+      needs.deploy-config.outputs.production_ready == 'true' &&
+      (needs.deploy-production.result == 'failure' || needs.smoke-test-production.result == 'failure')
     runs-on: ubuntu-latest
     environment: production
 

.github/workflows/e2e.yml

@@ -14,98 +14,10 @@ jobs:
   e2e:
     name: Playwright E2E
     runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    services:
-      postgres:
-        image: postgis/postgis:16-3.4
-        env:
-          POSTGRES_DB: goodgo_test
-          POSTGRES_USER: goodgo
-          POSTGRES_PASSWORD: goodgo_test_secret
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U goodgo -d goodgo_test"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-          --health-start-period 30s
-
-      redis:
-        image: redis:7-alpine
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-      typesense:
-        image: typesense/typesense:27.1
-        ports:
-          - 8108:8108
-        env:
-          TYPESENSE_API_KEY: ts_ci_key
-          TYPESENSE_DATA_DIR: /data
-        options: >-
-          --health-cmd "curl -sf http://localhost:8108/health || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-      minio:
-        image: minio/minio:latest
-        ports:
-          - 9000:9000
-        env:
-          MINIO_ROOT_USER: ${{ vars.CI_MINIO_ACCESS_KEY || 'ci_minio_user' }}
-          MINIO_ROOT_PASSWORD: ${{ vars.CI_MINIO_SECRET_KEY || 'ci_minio_secret_key_32chars!!' }}
-        options: >-
-          --health-cmd "curl -sf http://localhost:9000/minio/health/live || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
+    timeout-minutes: 45
 
     env:
-      DATABASE_URL: postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
-      REDIS_URL: redis://localhost:6379
-      REDIS_HOST: localhost
-      REDIS_PORT: 6379
-      TYPESENSE_URL: http://localhost:8108
-      TYPESENSE_HOST: localhost
-      TYPESENSE_PORT: 8108
-      TYPESENSE_PROTOCOL: http
-      TYPESENSE_API_KEY: ts_ci_key
-      MINIO_ENDPOINT: localhost
-      MINIO_PORT: 9000
-      MINIO_ACCESS_KEY: ${{ vars.CI_MINIO_ACCESS_KEY || 'ci_minio_user' }}
-      MINIO_SECRET_KEY: ${{ vars.CI_MINIO_SECRET_KEY || 'ci_minio_secret_key_32chars!!' }}
-      MINIO_BUCKET: goodgo-uploads
-      NODE_ENV: test
       CI: true
-      # API and Web ports for Playwright webServer
-      API_PORT: 3001
-      WEB_PORT: 3000
-      API_BASE_URL: http://localhost:3001/api/v1/
-      WEB_BASE_URL: http://localhost:3000
-      NEXT_PUBLIC_API_URL: http://localhost:3001/api/v1
-      JWT_SECRET: e2e-test-jwt-secret-key-minimum-32-chars-long-enough
-      JWT_REFRESH_SECRET: e2e-test-refresh-secret-key-minimum-32-chars-ok
-      JWT_EXPIRES_IN: 15m
-      JWT_REFRESH_EXPIRES_IN: 7d
-      BCRYPT_ROUNDS: 4
-      VNPAY_TMN_CODE: TESTCODE
-      VNPAY_HASH_SECRET: TESTHASHSECRETTESTHASHSECRETTEST
-      VNPAY_URL: https://sandbox.vnpayment.vn/paymentv2/vpcpay.html
-      VNPAY_RETURN_URL: http://localhost:3000/payment/return
-      GOOGLE_CLIENT_ID: test-google-client-id
-      GOOGLE_CLIENT_SECRET: test-google-client-secret
-      GOOGLE_CALLBACK_URL: http://localhost:3001/api/v1/auth/google/callback
-      ZALO_APP_ID: test-zalo-app-id
-      ZALO_APP_SECRET: test-zalo-app-secret
-      ZALO_CALLBACK_URL: http://localhost:3001/api/v1/auth/zalo/callback
 
     steps:
       - name: Checkout
@@ -123,6 +35,12 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Load E2E environment
+        run: awk 'NF && $1 !~ /^#/' .env.test >> "$GITHUB_ENV"
+
+      - name: Start CI service stack
+        run: docker compose --env-file .env.ci -f docker-compose.ci.yml up -d --wait
+
       - name: Cache Playwright browsers
         id: playwright-cache
         uses: actions/cache@v4
@@ -165,3 +83,7 @@ jobs:
           name: playwright-traces
           path: test-results/
           retention-days: 7
+
+      - name: Stop CI service stack
+        if: always()
+        run: docker compose --env-file .env.ci -f docker-compose.ci.yml down -v

.github/workflows/security.yml

@@ -15,7 +15,6 @@ concurrency:
 
 permissions:
   contents: read
-  security-events: write
 
 jobs:
   # ── Dependency Audit ─────────────────────────────────────────────
@@ -96,25 +95,8 @@ jobs:
           cache-from: type=gha,scope=api-scan
           cache-to: type=gha,mode=max,scope=api-scan
 
-      - name: Run Trivy vulnerability scanner (API)
-        uses: aquasecurity/trivy-action@0.28.0
-        with:
-          image-ref: "goodgo-api:scan"
-          format: "sarif"
-          output: "trivy-api-results.sarif"
-          severity: "CRITICAL,HIGH"
-          # Ignore unfixed vulns to reduce noise
-          ignore-unfixed: true
-
-      - name: Upload Trivy SARIF (API)
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: "trivy-api-results.sarif"
-          category: "trivy-api"
-
       - name: Trivy table output (API)
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@v0.36.0
         with:
           image-ref: "goodgo-api:scan"
           format: "table"
@@ -144,24 +126,8 @@ jobs:
           cache-from: type=gha,scope=web-scan
           cache-to: type=gha,mode=max,scope=web-scan
 
-      - name: Run Trivy vulnerability scanner (Web)
-        uses: aquasecurity/trivy-action@0.28.0
-        with:
-          image-ref: "goodgo-web:scan"
-          format: "sarif"
-          output: "trivy-web-results.sarif"
-          severity: "CRITICAL,HIGH"
-          ignore-unfixed: true
-
-      - name: Upload Trivy SARIF (Web)
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: "trivy-web-results.sarif"
-          category: "trivy-web"
-
       - name: Trivy table output (Web)
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@v0.36.0
         with:
           image-ref: "goodgo-web:scan"
           format: "table"
@@ -191,24 +157,8 @@ jobs:
           cache-from: type=gha,scope=ai-scan
           cache-to: type=gha,mode=max,scope=ai-scan
 
-      - name: Run Trivy vulnerability scanner (AI)
-        uses: aquasecurity/trivy-action@0.28.0
-        with:
-          image-ref: "goodgo-ai:scan"
-          format: "sarif"
-          output: "trivy-ai-results.sarif"
-          severity: "CRITICAL,HIGH"
-          ignore-unfixed: true
-
-      - name: Upload Trivy SARIF (AI)
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: "trivy-ai-results.sarif"
-          category: "trivy-ai"
-
       - name: Trivy table output (AI)
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@v0.36.0
         with:
           image-ref: "goodgo-ai:scan"
           format: "table"
@@ -225,26 +175,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Run Trivy filesystem scanner
-        uses: aquasecurity/trivy-action@0.28.0
-        with:
-          scan-type: "fs"
-          scan-ref: "."
-          format: "sarif"
-          output: "trivy-fs-results.sarif"
-          severity: "CRITICAL,HIGH"
-          ignore-unfixed: true
-          scanners: "vuln,secret,misconfig"
-
-      - name: Upload Trivy SARIF (filesystem)
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: "trivy-fs-results.sarif"
-          category: "trivy-filesystem"
-
       - name: Trivy filesystem table output
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@v0.36.0
         with:
           scan-type: "fs"
           scan-ref: "."

.gitignore

@@ -36,6 +36,9 @@ load-tests/results/*.json
 npm-debug.log*
 pnpm-debug.log*
 
+# Redis dump (created when running redis locally without persistence config)
+*.rdb
+
 # personal notes / Obsidian
 .obsidian/
 TEC/

AGENTS.md

@@ -0,0 +1,97 @@
+# GoodGo Platform
+
+Vietnamese real estate platform — monorepo powered by pnpm workspaces + Turborepo.
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm db:generate        # Generate Prisma client
+pnpm db:migrate:dev     # Run migrations (needs PostgreSQL 16 + PostGIS)
+pnpm db:seed            # Seed sample data (users, listings, districts)
+pnpm dev                # Start all apps (API :3001, Web :3000)
+```
+
+## Architecture
+
+- **apps/api** — NestJS backend (CQRS, DDD, clean architecture)
+- **apps/web** — Next.js 15 frontend (App Router, Tailwind, Zustand)
+- **libs/ai-services** — Python FastAPI AI/ML services (AVM, content moderation, NLP)
+- **libs/mcp-servers** — MCP tool server library (property search, analytics, valuation)
+- **prisma/** — Schema, migrations, seed scripts
+- **e2e/** — Playwright E2E tests (API + Web projects)
+
+## Key Commands
+
+| Command | Description |
+|---------|-------------|
+| `pnpm lint` | ESLint (auto-fixable with `--fix`) |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm test` | Unit tests via Vitest (API only) |
+| `pnpm build` | Production build (all packages) |
+| `pnpm test:e2e` | Playwright E2E tests |
+| `pnpm db:studio` | Prisma Studio GUI |
+
+## Tech Stack
+
+- **Runtime**: Node.js >= 22, pnpm 10
+- **Backend**: NestJS, Prisma ORM, PostgreSQL 16 + PostGIS, Redis
+- **Frontend**: Next.js 15, React 18, Tailwind CSS 3, Zustand, Mapbox GL
+- **Testing**: Vitest (unit), Playwright (E2E)
+- **CI**: GitHub Actions (lint → typecheck → test → build)
+
+## Project Structure (API)
+
+```
+apps/api/src/modules/
+  auth/          — Authentication (JWT, OAuth, refresh tokens, CSRF)
+  listings/      — Property listings CRUD
+  payments/      — VNPay, MoMo, ZaloPay payment integration
+  subscriptions/ — Plans, quotas, usage tracking
+  admin/         — Moderation, KYC, user management, audit logs
+  analytics/     — Market data, heatmaps, price trends, AVM
+  search/        — Geo search, full-text search (Typesense), saved searches
+  notifications/ — Email, in-app notifications
+  agents/        — Agent profiles, quality scores
+  inquiries/     — Property inquiry management
+  leads/         — Lead tracking and conversion
+  reviews/       — Property reviews and ratings
+  health/        — Liveness and readiness probes
+  metrics/       — Prometheus metrics, web vitals
+  mcp/           — MCP tool server endpoints
+  shared/        — Domain primitives, guards, pipes, logging
+```
+
+Each module follows DDD layers: `domain/` → `application/` → `infrastructure/` → `presentation/`.
+
+## Project Structure (Libs)
+
+```
+libs/
+  ai-services/     — Python FastAPI AI/ML services (AVM, content moderation, NLP)
+  mcp-servers/     — MCP tool server library (property search, analytics, valuation)
+```
+
+## Database
+
+- PostgreSQL 16 with PostGIS extension for geospatial queries
+- 22 models (User, Property, Listing, Payment, Subscription, etc.)
+- Migrations in `prisma/migrations/`
+- Seed data covers: users, agents, Ho Chi Minh City districts/wards, sample properties, subscription plans
+
+## Environment Variables
+
+Required in `.env`:
+- `DATABASE_URL` — PostgreSQL connection string
+- `JWT_SECRET`, `JWT_REFRESH_SECRET` — Auth tokens
+- `VNPAY_*` — Payment gateway config
+- `MAPBOX_TOKEN` — Map rendering (frontend)
+- `REDIS_URL` — Cache layer (optional for dev)
+
+## Conventions
+
+- Import order enforced by eslint-plugin-import-x (external → internal → relative)
+- Path aliases: `@modules/*` in API, `@/*` in Web
+- Vietnamese UI text throughout (property types, districts, currency in VND)
+- All handlers return typed `Result<T>` or throw `DomainException`
+- Commit messages follow conventional commits

apps/api/docker-entrypoint.sh

@@ -11,7 +11,7 @@ set -e
 
 if [ "${RUN_MIGRATIONS}" = "true" ]; then
   echo "[entrypoint] Running Prisma migrations..."
-  npx prisma migrate deploy --schema ./prisma/schema.prisma
+  npx prisma migrate deploy --schema /app/prisma/schema.prisma
   echo "[entrypoint] Migrations complete."
 fi
 

apps/api/src/app.module.ts

@@ -20,7 +20,9 @@ import { McpIntegrationModule } from '@modules/mcp';
 import { MessagingModule } from '@modules/messaging';
 import { HttpMetricsInterceptor, MetricsModule } from '@modules/metrics';
 import { NotificationsModule } from '@modules/notifications';
+import { OsmSyncModule } from '@modules/osm-sync/osm-sync.module';
 import { PaymentsModule } from '@modules/payments';
+import { PoiModule } from '@modules/poi/poi.module';
 import { ProjectsModule } from '@modules/projects';
 import { QueuesModule } from '@modules/queues/queues.module';
 import { ReportsModule } from '@modules/reports';
@@ -58,7 +60,9 @@ import { AppController } from './app.controller';
     FavoritesModule,
     SearchModule,
     NotificationsModule,
+    OsmSyncModule,
     PaymentsModule,
+    PoiModule,
     SubscriptionsModule,
     AdminModule,
     AnalyticsModule,

apps/api/src/instrument.ts

@@ -8,7 +8,7 @@ const isTest = process.env['NODE_ENV'] === 'test';
 const integrations: any[] = [];
 if (!isTest) {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/consistent-type-imports
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { nodeProfilingIntegration } = require('@sentry/profiling-node') as typeof import('@sentry/profiling-node');
     integrations.push(nodeProfilingIntegration());
   } catch {

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

@@ -33,10 +33,10 @@ import { SystemSettingsService } from './application/services/system-settings.se
 import { ADMIN_QUERY_REPOSITORY } from './domain/repositories/admin-query.repository';
 import { AUDIT_LOG_REPOSITORY } from './domain/repositories/audit-log.repository';
 import { MODERATION_AUDIT_LOG_REPOSITORY } from './domain/repositories/moderation-audit-log.repository';
+import { SystemSettingsAiConfigProvider } from './infrastructure/adapters/system-settings-ai-config.provider';
 import { PrismaAdminQueryRepository } from './infrastructure/repositories/prisma-admin-query.repository';
 import { PrismaAuditLogRepository } from './infrastructure/repositories/prisma-audit-log.repository';
 import { PrismaModerationAuditLogRepository } from './infrastructure/repositories/prisma-moderation-audit-log.repository';
-import { SystemSettingsAiConfigProvider } from './infrastructure/adapters/system-settings-ai-config.provider';
 import { AdminModerationAuditController } from './presentation/controllers/admin-moderation-audit.controller';
 import { AdminModerationController } from './presentation/controllers/admin-moderation.controller';
 import { AdminController } from './presentation/controllers/admin.controller';

apps/api/src/modules/admin/application/commands/provision-developer/provision-developer.handler.ts

@@ -2,8 +2,8 @@ import { ConflictException, Inject } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
 import { createId } from '@paralleldrive/cuid2';
 import { PrismaService, ValidationException } from '@modules/shared';
-import { USER_REPOSITORY, type IUserRepository } from '../../../../auth/domain/repositories/user.repository';
 import { UserEntity } from '../../../../auth/domain/entities/user.entity';
+import { USER_REPOSITORY, type IUserRepository } from '../../../../auth/domain/repositories/user.repository';
 import { Email } from '../../../../auth/domain/value-objects/email.vo';
 import { HashedPassword } from '../../../../auth/domain/value-objects/hashed-password.vo';
 import { Phone } from '../../../../auth/domain/value-objects/phone.vo';

apps/api/src/modules/admin/application/commands/provision-park-operator/provision-park-operator.handler.ts

@@ -2,8 +2,8 @@ import { ConflictException, Inject } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
 import { createId } from '@paralleldrive/cuid2';
 import { PrismaService, ValidationException } from '@modules/shared';
-import { USER_REPOSITORY, type IUserRepository } from '../../../../auth/domain/repositories/user.repository';
 import { UserEntity } from '../../../../auth/domain/entities/user.entity';
+import { USER_REPOSITORY, type IUserRepository } from '../../../../auth/domain/repositories/user.repository';
 import { Email } from '../../../../auth/domain/value-objects/email.vo';
 import { HashedPassword } from '../../../../auth/domain/value-objects/hashed-password.vo';
 import { Phone } from '../../../../auth/domain/value-objects/phone.vo';

apps/api/src/modules/admin/infrastructure/repositories/admin-stats.queries.ts

@@ -1,3 +1,4 @@
+import { Prisma } from '@prisma/client';
 import { type PrismaService } from '@modules/shared';
 import {
   type DashboardStats,
@@ -80,7 +81,12 @@ export async function getRevenueStats(
     return cached.data;
   }
 
-  const truncUnit = groupBy === 'day' ? 'day' : 'month';
+  // Postgres can't prove that `DATE_TRUNC($n, ...)` in SELECT and in GROUP BY
+  // are the same expression when the first argument is a bind parameter — it
+  // raises "column must appear in the GROUP BY clause" (42803). Inline the
+  // unit as a raw fragment instead. `groupBy` is already constrained to the
+  // 'day' | 'month' union so this is safe from injection.
+  const truncUnit = groupBy === 'day' ? Prisma.sql`'day'` : Prisma.sql`'month'`;
 
   const rows = await prisma.$queryRaw<RevenueRawRow[]>`
     SELECT

apps/api/src/modules/admin/presentation/controllers/admin-moderation.controller.ts

@@ -25,6 +25,8 @@ import { RejectKycCommand } from '../../application/commands/reject-kyc/reject-k
 import { type RejectKycResult } from '../../application/commands/reject-kyc/reject-kyc.handler';
 import { RejectListingCommand } from '../../application/commands/reject-listing/reject-listing.command';
 import { type RejectListingResult } from '../../application/commands/reject-listing/reject-listing.handler';
+import type { FlaggedListingsResult } from '../../application/queries/get-flagged-listings/get-flagged-listings.handler';
+import { GetFlaggedListingsQuery } from '../../application/queries/get-flagged-listings/get-flagged-listings.query';
 import { GetKycQueueQuery } from '../../application/queries/get-kyc-queue/get-kyc-queue.query';
 import { GetModerationQueueQuery } from '../../application/queries/get-moderation-queue/get-moderation-queue.query';
 import {
@@ -37,8 +39,6 @@ import { ApproveListingDto } from '../dto/approve-listing.dto';
 import { BulkModerateDto } from '../dto/bulk-moderate.dto';
 import { RejectKycDto } from '../dto/reject-kyc.dto';
 import { RejectListingDto } from '../dto/reject-listing.dto';
-import { GetFlaggedListingsQuery } from '../../application/queries/get-flagged-listings/get-flagged-listings.query';
-import type { FlaggedListingsResult } from '../../application/queries/get-flagged-listings/get-flagged-listings.handler';
 
 @ApiTags('admin')
 @ApiBearerAuth('JWT')

apps/api/src/modules/admin/presentation/controllers/admin.controller.ts

@@ -22,8 +22,8 @@ import { type ProvisionParkOperatorResult } from '../../application/commands/pro
 import { UpdateAiSettingsCommand } from '../../application/commands/update-ai-settings/update-ai-settings.command';
 import { UpdateUserStatusCommand } from '../../application/commands/update-user-status/update-user-status.command';
 import { type UpdateUserStatusResult } from '../../application/commands/update-user-status/update-user-status.handler';
-import { GetAiSettingsQuery } from '../../application/queries/get-ai-settings/get-ai-settings.query';
 import { type AiSettingsDto } from '../../application/queries/get-ai-settings/get-ai-settings.handler';
+import { GetAiSettingsQuery } from '../../application/queries/get-ai-settings/get-ai-settings.query';
 import { GetAuditLogsQuery } from '../../application/queries/get-audit-logs/get-audit-logs.query';
 import { GetDashboardStatsQuery } from '../../application/queries/get-dashboard-stats/get-dashboard-stats.query';
 import { GetRevenueStatsQuery } from '../../application/queries/get-revenue-stats/get-revenue-stats.query';

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

@@ -1,6 +1,7 @@
 import { forwardRef, Module } from '@nestjs/common';
 import { CqrsModule } from '@nestjs/cqrs';
 import { makeCounterProvider, makeHistogramProvider } from '@willsoto/nestjs-prometheus';
+import { AdminModule } from '@modules/admin';
 import { ListingsModule } from '@modules/listings';
 import { ProjectsModule } from '@modules/projects';
 import { GenerateReportHandler } from './application/commands/generate-report/generate-report.handler';
@@ -8,21 +9,21 @@ import { TrackEventHandler } from './application/commands/track-event/track-even
 import { UpdateMarketIndexHandler } from './application/commands/update-market-index/update-market-index.handler';
 import { ListingCreatedModerationHandler } from './application/event-handlers/listing-created-moderation.handler';
 import { BatchValuationHandler } from './application/queries/batch-valuation/batch-valuation.handler';
-import { IndustrialValuationHandler } from './application/queries/industrial-valuation/industrial-valuation.handler';
 import { GetDistrictStatsHandler } from './application/queries/get-district-stats/get-district-stats.handler';
 import { GetHeatmapHandler } from './application/queries/get-heatmap/get-heatmap.handler';
 import { GetListingAiAdviceHandler } from './application/queries/get-listing-ai-advice/get-listing-ai-advice.handler';
 import { GetListingVolumeWardHandler } from './application/queries/get-listing-volume-ward/get-listing-volume-ward.handler';
-import { GetMarketReportHandler } from './application/queries/get-market-report/get-market-report.handler';
 import { GetMarketHistoryHandler } from './application/queries/get-market-history/get-market-history.handler';
+import { GetMarketReportHandler } from './application/queries/get-market-report/get-market-report.handler';
 import { GetMarketSnapshotHandler } from './application/queries/get-market-snapshot/get-market-snapshot.handler';
-import { GetPriceMoversHandler } from './application/queries/get-price-movers/get-price-movers.handler';
-import { GetTrendingAreasHandler } from './application/queries/get-trending-areas/get-trending-areas.handler';
-import { GetProjectAiAdviceHandler } from './application/queries/get-project-ai-advice/get-project-ai-advice.handler';
 import { GetNearbyPOIsHandler } from './application/queries/get-nearby-pois/get-nearby-pois.handler';
 import { GetNeighborhoodScoreHandler } from './application/queries/get-neighborhood-score/get-neighborhood-score.handler';
+import { GetPriceMoversHandler } from './application/queries/get-price-movers/get-price-movers.handler';
 import { GetPriceTrendHandler } from './application/queries/get-price-trend/get-price-trend.handler';
+import { GetProjectAiAdviceHandler } from './application/queries/get-project-ai-advice/get-project-ai-advice.handler';
+import { GetTrendingAreasHandler } from './application/queries/get-trending-areas/get-trending-areas.handler';
 import { GetValuationHandler } from './application/queries/get-valuation/get-valuation.handler';
+import { IndustrialValuationHandler } from './application/queries/industrial-valuation/industrial-valuation.handler';
 import { PredictValuationHandler } from './application/queries/predict-valuation/predict-valuation.handler';
 import { ValuationComparisonHandler } from './application/queries/valuation-comparison/valuation-comparison.handler';
 import { ValuationExplanationHandler } from './application/queries/valuation-explanation/valuation-explanation.handler';
@@ -36,17 +37,17 @@ import { PrismaValuationRepository } from './infrastructure/repositories/prisma-
 import { AI_SERVICE_CLIENT, AiServiceClient } from './infrastructure/services/ai-service.client';
 import { HttpAVMService } from './infrastructure/services/http-avm.service';
 import { MarketIndexCronService } from './infrastructure/services/market-index-cron.service';
+import {
+  HttpNeighborhoodScoreService,
+  PrismaNeighborhoodScoreService,
+} from './infrastructure/services/neighborhood-score.service';
+import { PrismaAVMService } from './infrastructure/services/prisma-avm.service';
 import {
   RefreshMaterializedViewCronService,
   MATVIEW_REFRESH_TOTAL,
   MATVIEW_REFRESH_DURATION,
   MATVIEW_REFRESH_ERRORS,
 } from './infrastructure/services/refresh-materialized-view-cron.service';
-import {
-  HttpNeighborhoodScoreService,
-  PrismaNeighborhoodScoreService,
-} from './infrastructure/services/neighborhood-score.service';
-import { PrismaAVMService } from './infrastructure/services/prisma-avm.service';
 import { AnalyticsController } from './presentation/controllers/analytics.controller';
 import { AvmController } from './presentation/controllers/avm.controller';
 
@@ -84,7 +85,12 @@ const EventHandlers = [
 ];
 
 @Module({
-  imports: [CqrsModule, forwardRef(() => ListingsModule), ProjectsModule],
+  imports: [
+    CqrsModule,
+    forwardRef(() => ListingsModule),
+    ProjectsModule,
+    forwardRef(() => AdminModule), // for AI_CONFIG_PROVIDER (used by AI advice handlers)
+  ],
   controllers: [AnalyticsController, AvmController],
   providers: [
     // AI service client

apps/api/src/modules/analytics/application/__tests__/batch-valuation.handler.spec.ts

@@ -1,6 +1,6 @@
 import { InternalServerErrorException } from '@nestjs/common';
-import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { DomainException } from '@modules/shared';
+import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import {
   type IAVMService,
   type BatchValuationResult,

apps/api/src/modules/analytics/application/__tests__/get-market-snapshot.handler.spec.ts

@@ -1,6 +1,6 @@
 import { InternalServerErrorException } from '@nestjs/common';
-import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { type PrismaService } from '@modules/shared';
+import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { GetMarketSnapshotHandler } from '../queries/get-market-snapshot/get-market-snapshot.handler';
 import { GetMarketSnapshotQuery } from '../queries/get-market-snapshot/get-market-snapshot.query';
 

apps/api/src/modules/analytics/application/__tests__/get-neighborhood-score.handler.spec.ts

@@ -1,5 +1,5 @@
-import { type INeighborhoodScoreService, type NeighborhoodScoreResult } from '../../domain/services/neighborhood-score.service';
 import { type CacheService } from '@modules/shared/infrastructure/cache.service';
+import { type INeighborhoodScoreService, type NeighborhoodScoreResult } from '../../domain/services/neighborhood-score.service';
 import { GetNeighborhoodScoreHandler } from '../queries/get-neighborhood-score/get-neighborhood-score.handler';
 import { GetNeighborhoodScoreQuery } from '../queries/get-neighborhood-score/get-neighborhood-score.query';
 

apps/api/src/modules/analytics/application/__tests__/valuation-comparison.handler.spec.ts

@@ -1,6 +1,5 @@
 import { InternalServerErrorException } from '@nestjs/common';
-import { type CacheService, type PrismaService } from '@modules/shared';
-import { DomainException } from '@modules/shared';
+import { type CacheService, type PrismaService, DomainException  } from '@modules/shared';
 import { type IAVMService, type ValuationResult } from '../../domain/services/avm-service';
 import { ValuationComparisonHandler } from '../queries/valuation-comparison/valuation-comparison.handler';
 import { ValuationComparisonQuery } from '../queries/valuation-comparison/valuation-comparison.query';

apps/api/src/modules/analytics/application/__tests__/valuation-explanation.handler.spec.ts

@@ -1,6 +1,6 @@
 import { InternalServerErrorException } from '@nestjs/common';
-import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { DomainException, NotFoundException } from '@modules/shared';
+import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { ValuationEntity } from '../../domain/entities/valuation.entity';
 import { type IValuationRepository } from '../../domain/repositories/valuation.repository';
 import { ValuationExplanationHandler } from '../queries/valuation-explanation/valuation-explanation.handler';

apps/api/src/modules/analytics/application/__tests__/valuation-history.handler.spec.ts

@@ -1,6 +1,6 @@
 import { InternalServerErrorException } from '@nestjs/common';
-import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { DomainException } from '@modules/shared';
+import { type CacheService } from '@modules/shared/infrastructure/cache.service';
 import { ValuationEntity } from '../../domain/entities/valuation.entity';
 import { type IValuationRepository } from '../../domain/repositories/valuation.repository';
 import { ValuationHistoryHandler } from '../queries/valuation-history/valuation-history.handler';

apps/api/src/modules/analytics/application/event-handlers/listing-created-moderation.handler.ts

@@ -1,7 +1,7 @@
 import { Inject } from '@nestjs/common';
 import { EventsHandler, type IEventHandler, CommandBus } from '@nestjs/cqrs';
+import { ModerateListingCommand } from '@modules/listings';
 import { ListingCreatedEvent } from '@modules/listings/domain/events/listing-created.event';
-import { ModerateListingCommand } from '@modules/listings/application/commands/moderate-listing/moderate-listing.command';
 import { PrismaService, LoggerService } from '@modules/shared';
 import {
   AI_SERVICE_CLIENT,

apps/api/src/modules/analytics/application/queries/get-listing-ai-advice/get-listing-ai-advice.handler.ts

@@ -1,5 +1,14 @@
 import { HttpStatus, Inject } from '@nestjs/common';
 import { QueryBus, QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+// Direct internal path: barrel `@modules/listings` exports `ListingsModule`
+// first, which transitively imports the analytics handler back here. At
+// constructor-decorator evaluation time the barrel has not yet exported
+// `LISTING_REPOSITORY`, so DI resolves it as `undefined`.
+// eslint-disable-next-line no-restricted-imports -- circular-import workaround; see comment above
+import {
+  LISTING_REPOSITORY,
+  type IListingRepository,
+} from '@modules/listings/domain/repositories/listing.repository';
 import {
   AI_CONFIG_PROVIDER,
   DomainException,
@@ -7,18 +16,8 @@ import {
   type IAIConfigProvider,
   LoggerService,
 } from '@modules/shared';
-import {
-  LISTING_REPOSITORY,
-  type IListingRepository,
-} from '@modules/listings/domain/repositories/listing.repository';
 import { type ListingDetailData } from '../../../../listings/domain/repositories/listing-read.dto';
-import {
-  type NearbyPOIDto,
-  type NearbyPOIsResultDto,
-} from '../get-nearby-pois/get-nearby-pois.handler';
-import { GetNearbyPOIsQuery } from '../get-nearby-pois/get-nearby-pois.query';
 import { type NeighborhoodScoreResult } from '../../../domain/services/neighborhood-score.service';
-import { GetNeighborhoodScoreQuery } from '../get-neighborhood-score/get-neighborhood-score.query';
 import {
   asInt,
   asString,
@@ -28,6 +27,12 @@ import {
   jsonShapeError,
   parseJsonObject,
 } from '../_shared/ai-json-client';
+import {
+  type NearbyPOIDto,
+  type NearbyPOIsResultDto,
+} from '../get-nearby-pois/get-nearby-pois.handler';
+import { GetNearbyPOIsQuery } from '../get-nearby-pois/get-nearby-pois.query';
+import { GetNeighborhoodScoreQuery } from '../get-neighborhood-score/get-neighborhood-score.query';
 import { GetListingAiAdviceQuery } from './get-listing-ai-advice.query';
 
 /** Shape returned by Anthropic (parsed from first content block). */

apps/api/src/modules/analytics/application/queries/get-market-snapshot/get-market-snapshot.handler.ts

@@ -1,7 +1,7 @@
 import { InternalServerErrorException } from '@nestjs/common';
 import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
-import { DomainException, CacheService, CachePrefix, CacheTTL, LoggerService, PrismaService } from '@modules/shared';
 import { type PropertyType, ListingStatus, Prisma } from '@prisma/client';
+import { DomainException, CacheService, CachePrefix, CacheTTL, LoggerService, PrismaService } from '@modules/shared';
 import { GetMarketSnapshotQuery } from './get-market-snapshot.query';
 
 export interface PriceChangePct {

apps/api/src/modules/analytics/application/queries/get-project-ai-advice/get-project-ai-advice.handler.ts

@@ -1,5 +1,10 @@
 import { HttpStatus, Inject } from '@nestjs/common';
 import { QueryBus, QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import {
+  PROJECT_REPOSITORY,
+  type IProjectRepository,
+  type ProjectDetailData,
+} from '@modules/projects';
 import {
   AI_CONFIG_PROVIDER,
   DomainException,
@@ -7,26 +12,19 @@ import {
   type IAIConfigProvider,
   LoggerService,
 } from '@modules/shared';
-import {
-  PROJECT_REPOSITORY,
-  type IProjectRepository,
-  type ProjectDetailData,
-} from '@modules/projects';
-import { type AnthropicUsage } from '../_shared/ai-json-client';
-import {
+import { type NeighborhoodScoreResult } from '../../../domain/services/neighborhood-score.service';
+import { type AnthropicUsage,
   asString,
   asStringArray,
   callAnthropicJson,
   isRecord,
   jsonShapeError,
-  parseJsonObject,
-} from '../_shared/ai-json-client';
+  parseJsonObject } from '../_shared/ai-json-client';
 import {
   type NearbyPOIDto,
   type NearbyPOIsResultDto,
 } from '../get-nearby-pois/get-nearby-pois.handler';
 import { GetNearbyPOIsQuery } from '../get-nearby-pois/get-nearby-pois.query';
-import { type NeighborhoodScoreResult } from '../../../domain/services/neighborhood-score.service';
 import { GetNeighborhoodScoreQuery } from '../get-neighborhood-score/get-neighborhood-score.query';
 import { GetProjectAiAdviceQuery } from './get-project-ai-advice.query';
 

apps/api/src/modules/analytics/application/queries/get-trending-areas/get-trending-areas.handler.ts

@@ -1,4 +1,4 @@
-import { Inject, InternalServerErrorException } from '@nestjs/common';
+import { InternalServerErrorException } from '@nestjs/common';
 import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
 import { DomainException, CacheService, CachePrefix, CacheTTL, Cacheable, LoggerService, PrismaService } from '@modules/shared';
 import { GetTrendingAreasQuery } from './get-trending-areas.query';

apps/api/src/modules/analytics/infrastructure/services/avm-retrain-cron.service.ts

@@ -280,7 +280,7 @@ interface RawTrainingRow {
   price_vnd: number;
 }
 
-interface TrainingRow extends RawTrainingRow {}
+type TrainingRow = RawTrainingRow;
 
 interface RetrainResult {
   model_version: string;

apps/api/src/modules/analytics/infrastructure/services/http-avm.service.ts

@@ -14,6 +14,7 @@ import {
   type AiPredictRequest,
   type AiPredictV2Request,
 } from './ai-service.client';
+import { PrismaAVMService } from './prisma-avm.service';
 
 /** Map string risk buckets to the 0..1 float the Python service expects. */
 const FLOOD_RISK_TO_SCORE: Record<string, number> = {
@@ -22,7 +23,6 @@ const FLOOD_RISK_TO_SCORE: Record<string, number> = {
   MEDIUM: 0.66,
   HIGH: 1,
 };
-import { PrismaAVMService } from './prisma-avm.service';
 
 /** Max concurrency for batch AI calls to avoid overloading the Python service. */
 const BATCH_CONCURRENCY = 5;

apps/api/src/modules/analytics/infrastructure/services/refresh-materialized-view-cron.service.ts

@@ -2,7 +2,6 @@ import { Injectable, type OnModuleDestroy } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Cron } from '@nestjs/schedule';
 import { InjectMetric } from '@willsoto/nestjs-prometheus';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { Counter, Histogram } from 'prom-client';
 import { PrismaService, RedisService, LoggerService } from '@modules/shared';
 

apps/api/src/modules/analytics/presentation/__tests__/cache-meta.interceptor.spec.ts

@@ -1,6 +1,5 @@
 import { type ExecutionContext, type CallHandler } from '@nestjs/common';
-import { of } from 'rxjs';
-import { lastValueFrom } from 'rxjs';
+import { of, lastValueFrom  } from 'rxjs';
 import { cacheMetaStorage } from '@modules/shared';
 import { CacheMetaInterceptor, type WithCacheMeta } from '../interceptors/cache-meta.interceptor';
 

apps/api/src/modules/analytics/presentation/controllers/analytics.controller.ts

@@ -13,38 +13,37 @@ import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiBody, ApiParam }
 import { JwtAuthGuard } from '@modules/auth';
 import { EndpointRateLimit, EndpointRateLimitGuard } from '@modules/shared';
 import { RequireQuota, QuotaGuard } from '@modules/subscriptions';
-import { CacheMetaInterceptor } from '../interceptors/cache-meta.interceptor';
 import { type BatchValuationDto as BatchValuationQueryDto } from '../../application/queries/batch-valuation/batch-valuation.handler';
 import { BatchValuationQuery } from '../../application/queries/batch-valuation/batch-valuation.query';
 import { type DistrictStatsDto } from '../../application/queries/get-district-stats/get-district-stats.handler';
 import { GetDistrictStatsQuery } from '../../application/queries/get-district-stats/get-district-stats.query';
 import { type HeatmapDto } from '../../application/queries/get-heatmap/get-heatmap.handler';
 import { GetHeatmapQuery } from '../../application/queries/get-heatmap/get-heatmap.query';
-import { type ListingVolumeWardDto } from '../../application/queries/get-listing-volume-ward/get-listing-volume-ward.handler';
-import { GetListingVolumeWardQuery } from '../../application/queries/get-listing-volume-ward/get-listing-volume-ward.query';
 import {
   type ListingAiAdviceResponse,
 } from '../../application/queries/get-listing-ai-advice/get-listing-ai-advice.handler';
 import { GetListingAiAdviceQuery } from '../../application/queries/get-listing-ai-advice/get-listing-ai-advice.query';
+import { type ListingVolumeWardDto } from '../../application/queries/get-listing-volume-ward/get-listing-volume-ward.handler';
+import { GetListingVolumeWardQuery } from '../../application/queries/get-listing-volume-ward/get-listing-volume-ward.query';
+import { type MarketHistoryDto } from '../../application/queries/get-market-history/get-market-history.handler';
+import { GetMarketHistoryQuery } from '../../application/queries/get-market-history/get-market-history.query';
+import { type MarketReportDto } from '../../application/queries/get-market-report/get-market-report.handler';
+import { GetMarketReportQuery } from '../../application/queries/get-market-report/get-market-report.query';
+import { type MarketSnapshotDto } from '../../application/queries/get-market-snapshot/get-market-snapshot.handler';
+import { GetMarketSnapshotQuery } from '../../application/queries/get-market-snapshot/get-market-snapshot.query';
+import { type NearbyPOIsResultDto } from '../../application/queries/get-nearby-pois/get-nearby-pois.handler';
+import { GetNearbyPOIsQuery } from '../../application/queries/get-nearby-pois/get-nearby-pois.query';
+import { GetNeighborhoodScoreQuery } from '../../application/queries/get-neighborhood-score/get-neighborhood-score.query';
+import { type PriceMoversDto } from '../../application/queries/get-price-movers/get-price-movers.handler';
+import { GetPriceMoversQuery } from '../../application/queries/get-price-movers/get-price-movers.query';
+import { type PriceTrendDto } from '../../application/queries/get-price-trend/get-price-trend.handler';
+import { GetPriceTrendQuery } from '../../application/queries/get-price-trend/get-price-trend.query';
 import {
   type ProjectAiAdviceResponse,
 } from '../../application/queries/get-project-ai-advice/get-project-ai-advice.handler';
 import { GetProjectAiAdviceQuery } from '../../application/queries/get-project-ai-advice/get-project-ai-advice.query';
-import { type MarketReportDto } from '../../application/queries/get-market-report/get-market-report.handler';
-import { GetMarketReportQuery } from '../../application/queries/get-market-report/get-market-report.query';
-import { type MarketHistoryDto } from '../../application/queries/get-market-history/get-market-history.handler';
-import { GetMarketHistoryQuery } from '../../application/queries/get-market-history/get-market-history.query';
-import { type MarketSnapshotDto } from '../../application/queries/get-market-snapshot/get-market-snapshot.handler';
-import { GetMarketSnapshotQuery } from '../../application/queries/get-market-snapshot/get-market-snapshot.query';
-import { type PriceMoversDto } from '../../application/queries/get-price-movers/get-price-movers.handler';
-import { GetPriceMoversQuery } from '../../application/queries/get-price-movers/get-price-movers.query';
 import { type TrendingAreasDto } from '../../application/queries/get-trending-areas/get-trending-areas.handler';
 import { GetTrendingAreasQuery } from '../../application/queries/get-trending-areas/get-trending-areas.query';
-import { type NearbyPOIsResultDto } from '../../application/queries/get-nearby-pois/get-nearby-pois.handler';
-import { GetNearbyPOIsQuery } from '../../application/queries/get-nearby-pois/get-nearby-pois.query';
-import { GetNeighborhoodScoreQuery } from '../../application/queries/get-neighborhood-score/get-neighborhood-score.query';
-import { type PriceTrendDto } from '../../application/queries/get-price-trend/get-price-trend.handler';
-import { GetPriceTrendQuery } from '../../application/queries/get-price-trend/get-price-trend.query';
 import { type ValuationDto } from '../../application/queries/get-valuation/get-valuation.handler';
 import { GetValuationQuery } from '../../application/queries/get-valuation/get-valuation.query';
 import { type PredictValuationDto } from '../../application/queries/predict-valuation/predict-valuation.handler';
@@ -58,17 +57,18 @@ import { BatchValuationDto } from '../dto/batch-valuation.dto';
 import { GetDistrictStatsDto } from '../dto/get-district-stats.dto';
 import { GetHeatmapDto } from '../dto/get-heatmap.dto';
 import { GetListingVolumeWardDto } from '../dto/get-listing-volume-ward.dto';
-import { GetMarketReportDto } from '../dto/get-market-report.dto';
 import { GetMarketHistoryDto } from '../dto/get-market-history.dto';
+import { GetMarketReportDto } from '../dto/get-market-report.dto';
 import { GetMarketSnapshotDto } from '../dto/get-market-snapshot.dto';
-import { GetPriceMoversDto } from '../dto/get-price-movers.dto';
-import { GetTrendingAreasDto } from '../dto/get-trending-areas.dto';
 import { GetNearbyPOIsDto } from '../dto/get-nearby-pois.dto';
+import { GetPriceMoversDto } from '../dto/get-price-movers.dto';
 import { GetPriceTrendDto } from '../dto/get-price-trend.dto';
+import { GetTrendingAreasDto } from '../dto/get-trending-areas.dto';
 import { GetValuationDto } from '../dto/get-valuation.dto';
 import { PredictValuationDto as PredictValuationBodyDto } from '../dto/predict-valuation.dto';
 import { ValuationComparisonDto } from '../dto/valuation-comparison.dto';
 import { ValuationHistoryDto } from '../dto/valuation-history.dto';
+import { CacheMetaInterceptor } from '../interceptors/cache-meta.interceptor';
 
 @ApiTags('analytics')
 @UseInterceptors(CacheMetaInterceptor)

apps/api/src/modules/analytics/presentation/controllers/avm.controller.ts

@@ -27,8 +27,8 @@ import { AvmCompareQueryDto } from '../dto/avm-compare-query.dto';
 import { AvmExplainQueryDto } from '../dto/avm-explain-query.dto';
 import { BatchValuationDto } from '../dto/batch-valuation.dto';
 import { IndustrialValuationDto } from '../dto/industrial-valuation.dto';
-import { CacheMetaInterceptor } from '../interceptors/cache-meta.interceptor';
 import { ValuationHistoryDto } from '../dto/valuation-history.dto';
+import { CacheMetaInterceptor } from '../interceptors/cache-meta.interceptor';
 
 @ApiTags('avm')
 @UseInterceptors(CacheMetaInterceptor)

apps/api/src/modules/analytics/presentation/dto/get-price-movers.dto.ts

@@ -43,5 +43,5 @@ export class GetPriceMoversDto {
   })
   @IsOptional()
   @IsIn(['district'])
-  level: 'district' = 'district';
+  level = 'district' as const;
 }

apps/api/src/modules/analytics/presentation/dto/get-trending-areas.dto.ts

@@ -37,5 +37,5 @@ export class GetTrendingAreasDto {
   })
   @IsOptional()
   @IsIn(['district'])
-  level: 'district' = 'district';
+  level = 'district' as const;
 }

apps/api/src/modules/auth/application/commands/export-user-data/export-user-data.handler.ts

@@ -1,6 +1,6 @@
+import { Readable } from 'node:stream';
 import { HttpException, InternalServerErrorException, PayloadTooLargeException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
-import { Readable } from 'node:stream';
 import { LoggerService, PrismaService, DomainException, NotFoundException } from '@modules/shared';
 import { ExportUserDataCommand } from './export-user-data.command';
 

apps/api/src/modules/auth/application/commands/login-user/login-user.handler.ts

@@ -1,7 +1,7 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
-import { type UserRole } from '@prisma/client';
 import { createId } from '@paralleldrive/cuid2';
+import { type UserRole } from '@prisma/client';
 import { LoggerService, DomainException } from '@modules/shared';
 import { MFA_GRACE_PERIOD_DAYS, MFA_REQUIRED_ROLES } from '../../../domain/mfa-policy';
 import {

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

@@ -14,12 +14,12 @@ import { ForceDeleteUserHandler } from './application/commands/force-delete-user
 import { ForgotPasswordHandler } from './application/commands/forgot-password/forgot-password.handler';
 import { GenerateKycUploadUrlsHandler } from './application/commands/generate-kyc-upload-urls/generate-kyc-upload-urls.handler';
 import { LoginUserHandler } from './application/commands/login-user/login-user.handler';
-import { ResetPasswordHandler } from './application/commands/reset-password/reset-password.handler';
 import { ProcessScheduledDeletionsHandler } from './application/commands/process-scheduled-deletions/process-scheduled-deletions.handler';
 import { RefreshTokenHandler } from './application/commands/refresh-token/refresh-token.handler';
 import { RegisterUserHandler } from './application/commands/register-user/register-user.handler';
 import { RequestUserDeletionHandler } from './application/commands/request-user-deletion/request-user-deletion.handler';
 import { ResendOtpHandler } from './application/commands/resend-otp/resend-otp.handler';
+import { ResetPasswordHandler } from './application/commands/reset-password/reset-password.handler';
 import { SetupMfaHandler } from './application/commands/setup-mfa/setup-mfa.handler';
 import { SubmitKycHandler } from './application/commands/submit-kyc/submit-kyc.handler';
 import { UpdateProfileHandler } from './application/commands/update-profile/update-profile.handler';

apps/api/src/modules/auth/index.ts

@@ -17,3 +17,4 @@ export { PhoneChangeRequestedEvent } from './domain/events/phone-change-requeste
 export { EmailChangedEvent } from './domain/events/email-changed.event';
 export { PhoneChangedEvent } from './domain/events/phone-changed.event';
 export { USER_REPOSITORY, IUserRepository } from './domain/repositories/user.repository';
+export { PasswordResetRequestedEvent } from './domain/events/password-reset-requested.event';

apps/api/src/modules/auth/infrastructure/strategies/jwt.strategy.ts

@@ -2,7 +2,6 @@ import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { type Request } from 'express';
 import { ExtractJwt, Strategy } from 'passport-jwt';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { PrismaService, RedisService } from '@modules/shared';
 import { type JwtPayload } from '../services/token.service';
 import { makeSecretOrKeyProvider } from '../utils/jwt-rotation';

apps/api/src/modules/auth/presentation/controllers/auth.controller.ts

@@ -62,7 +62,23 @@ import { RolesGuard } from '../guards/roles.guard';
 
 const IS_PRODUCTION = process.env['NODE_ENV'] === 'production';
 const IS_TEST = process.env['NODE_ENV'] === 'test';
-const AUTH_RATE_LIMIT = IS_TEST ? 10_000 : 5;
+/**
+ * Hourly rate limit for auth endpoints. Default 5 is the production
+ * safety threshold; raise via env in dev/staging when exercising flows
+ * (e.g. `AUTH_RATE_LIMIT=200` in the cluster ConfigMap so testers
+ * don't lock themselves out after a few attempts).
+ */
+const AUTH_RATE_LIMIT = (() => {
+  if (IS_TEST) return 10_000;
+  const fromEnv = Number(process.env['AUTH_RATE_LIMIT']);
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 5;
+})();
+/** Per-IP burst limit for the login / register endpoints (per minute). */
+const AUTH_PER_IP_LIMIT = (() => {
+  if (IS_TEST) return 10_000;
+  const fromEnv = Number(process.env['AUTH_PER_IP_LIMIT']);
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 5;
+})();
 const ACCESS_TOKEN_MAX_AGE = 15 * 60 * 1000; // 15 minutes
 const REFRESH_TOKEN_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
 const AUTH_COOKIE_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -109,7 +125,7 @@ export class AuthController {
   ) {}
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 3, windowSeconds: 60, keyStrategy: 'ip' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'ip' })
   @UseGuards(EndpointRateLimitGuard)
   @Post('register')
   @ApiOperation({ summary: 'Register a new user' })
@@ -132,7 +148,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 5, windowSeconds: 60, keyStrategy: 'ip' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'ip' })
   @UseGuards(EndpointRateLimitGuard, LocalAuthGuard)
   @Post('login')
   @ApiOperation({ summary: 'Login with phone and password' })
@@ -198,7 +214,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 3, windowSeconds: 60, keyStrategy: 'ip' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'ip' })
   @UseGuards(EndpointRateLimitGuard)
   @Post('forgot-password')
   @ApiOperation({
@@ -215,7 +231,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 5, windowSeconds: 60, keyStrategy: 'ip' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'ip' })
   @UseGuards(EndpointRateLimitGuard)
   @Post('reset-password')
   @ApiOperation({ summary: 'Reset password using OTP code' })
@@ -231,7 +247,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: 20 } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 5, windowSeconds: 60, keyStrategy: 'ip' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'ip' })
   @UseGuards(EndpointRateLimitGuard)
   @Post('exchange-token')
   @ApiOperation({ summary: 'Exchange OAuth token pair for httpOnly cookies' })
@@ -286,7 +302,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 5, windowSeconds: 60, keyStrategy: 'user' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'user' })
   @UseGuards(JwtAuthGuard, EndpointRateLimitGuard)
   @Post('profile/verify-phone')
   @ApiBearerAuth('JWT')
@@ -307,7 +323,7 @@ export class AuthController {
   }
 
   @Throttle({ default: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT }, auth: { ttl: 3_600_000, limit: AUTH_RATE_LIMIT } })
-  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : 5, windowSeconds: 60, keyStrategy: 'user' })
+  @EndpointRateLimit({ limit: IS_TEST ? 10_000 : AUTH_PER_IP_LIMIT, windowSeconds: 60, keyStrategy: 'user' })
   @UseGuards(JwtAuthGuard, EndpointRateLimitGuard)
   @Post('profile/verify-email')
   @ApiBearerAuth('JWT')

apps/api/src/modules/documents/application/commands/approve-document/approve-document.handler.ts

@@ -1,6 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- PrismaService & LoggerService are constructor-injected (NestJS DI)
 import { DomainException, LoggerService, NotFoundException, PrismaService, ValidationException } from '@modules/shared';
 import { PROPERTY_DOCUMENT_REPOSITORY, type IPropertyDocumentRepository } from '../../../domain/repositories/property-document.repository';
 import { ApproveDocumentCommand } from './approve-document.command';

apps/api/src/modules/documents/application/commands/reject-document/reject-document.handler.ts

@@ -1,6 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- LoggerService is constructor-injected (NestJS DI)
 import { DomainException, LoggerService, NotFoundException, ValidationException } from '@modules/shared';
 import { PROPERTY_DOCUMENT_REPOSITORY, type IPropertyDocumentRepository } from '../../../domain/repositories/property-document.repository';
 import { RejectDocumentCommand } from './reject-document.command';

apps/api/src/modules/documents/application/commands/upload-document/upload-document.handler.ts

@@ -2,7 +2,6 @@ import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
 import { createId } from '@paralleldrive/cuid2';
 import { PROPERTY_REPOSITORY, type IPropertyRepository, MEDIA_STORAGE_SERVICE, type IMediaStorageService } from '@modules/listings';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- LoggerService is constructor-injected (NestJS DI requires runtime reference)
 import { DomainException, LoggerService, NotFoundException, ValidationException } from '@modules/shared';
 import { PropertyDocumentEntity } from '../../../domain/entities/property-document.entity';
 import { PROPERTY_DOCUMENT_REPOSITORY, type IPropertyDocumentRepository } from '../../../domain/repositories/property-document.repository';

apps/api/src/modules/documents/infrastructure/repositories/prisma-property-document.repository.ts

@@ -1,6 +1,5 @@
 import { Injectable } from '@nestjs/common';
 import { type PropertyDocument as PrismaPropertyDocument, type DocumentType, type DocumentVerificationStatus } from '@prisma/client';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- PrismaService is constructor-injected (NestJS DI)
 import { PrismaService } from '@modules/shared';
 import { PropertyDocumentEntity, type PropertyDocumentProps } from '../../domain/entities/property-document.entity';
 import { type IPropertyDocumentRepository } from '../../domain/repositories/property-document.repository';

apps/api/src/modules/documents/presentation/controllers/property-documents.controller.ts

@@ -9,7 +9,6 @@ import {
   UseGuards,
   UseInterceptors,
 } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- CommandBus & QueryBus are constructor-injected (NestJS DI)
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { FileInterceptor } from '@nestjs/platform-express';
 import {
@@ -33,7 +32,6 @@ import { type PendingDocumentsResult } from '../../application/queries/get-pendi
 import { GetPendingDocumentsQuery } from '../../application/queries/get-pending-documents/get-pending-documents.query';
 import { type PropertyDocumentDto } from '../../application/queries/get-property-documents/get-property-documents.handler';
 import { GetPropertyDocumentsQuery } from '../../application/queries/get-property-documents/get-property-documents.query';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- DTOs are used at runtime by class-validator via @Body()
 import { UploadDocumentDto, ApproveDocumentDto, RejectDocumentDto } from '../dto/upload-document.dto';
 
 @ApiTags('documents')

apps/api/src/modules/favorites/application/commands/add-favorite/add-favorite.handler.ts

@@ -1,7 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { DomainException, LoggerService } from '@modules/shared';
 import {
   SAVED_LISTING_REPOSITORY,

apps/api/src/modules/favorites/application/commands/remove-favorite/remove-favorite.handler.ts

@@ -1,7 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { DomainException, LoggerService } from '@modules/shared';
 import {
   SAVED_LISTING_REPOSITORY,

apps/api/src/modules/favorites/application/queries/is-favorited/is-favorited.handler.ts

@@ -1,7 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { DomainException, LoggerService } from '@modules/shared';
 import {
   SAVED_LISTING_REPOSITORY,

apps/api/src/modules/favorites/application/queries/list-favorites/list-favorites.handler.ts

@@ -1,7 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { DomainException, LoggerService } from '@modules/shared';
 import {
   SAVED_LISTING_REPOSITORY,

apps/api/src/modules/favorites/infrastructure/repositories/prisma-saved-listing.repository.ts

@@ -1,6 +1,5 @@
 import { Injectable } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { ConflictException, NotFoundException, PrismaService } from '@modules/shared';
 import {
   type FavoriteItem,

apps/api/src/modules/favorites/presentation/controllers/favorites.controller.ts

@@ -7,7 +7,6 @@ import {
   Query,
   UseGuards,
 } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import {
   ApiBearerAuth,
@@ -16,15 +15,14 @@ import {
   ApiResponse,
   ApiTags,
 } from '@nestjs/swagger';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports for emitDecoratorMetadata
 import { CurrentUser, JwtAuthGuard, type JwtPayload } from '@modules/auth';
 import { AddFavoriteCommand } from '../../application/commands/add-favorite/add-favorite.command';
 import { type AddFavoriteResult } from '../../application/commands/add-favorite/add-favorite.handler';
 import { RemoveFavoriteCommand } from '../../application/commands/remove-favorite/remove-favorite.command';
-import { IsFavoritedQuery } from '../../application/queries/is-favorited/is-favorited.query';
 import { type IsFavoritedResult } from '../../application/queries/is-favorited/is-favorited.handler';
-import { ListFavoritesQuery } from '../../application/queries/list-favorites/list-favorites.query';
+import { IsFavoritedQuery } from '../../application/queries/is-favorited/is-favorited.query';
 import { type ListFavoritesResult } from '../../application/queries/list-favorites/list-favorites.handler';
+import { ListFavoritesQuery } from '../../application/queries/list-favorites/list-favorites.query';
 import { ListFavoritesDto } from '../dto/list-favorites.dto';
 
 @ApiTags('favorites')

apps/api/src/modules/health/health.controller.ts

@@ -1,9 +1,6 @@
 import { Controller, Get } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { HealthCheck, HealthCheckService } from '@nestjs/terminus';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { PrismaHealthIndicator } from './infrastructure/prisma.health';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { RedisHealthIndicator } from './infrastructure/redis.health';
 
 @Controller('health')

apps/api/src/modules/health/infrastructure/prisma.health.ts

@@ -1,6 +1,5 @@
 import { Injectable } from '@nestjs/common';
 import { HealthCheckError, HealthIndicator, type HealthIndicatorResult } from '@nestjs/terminus';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { PrismaService } from '@modules/shared';
 
 @Injectable()

apps/api/src/modules/health/infrastructure/redis.health.ts

@@ -1,6 +1,5 @@
 import { Injectable } from '@nestjs/common';
 import { HealthCheckError, HealthIndicator, type HealthIndicatorResult } from '@nestjs/terminus';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { RedisService } from '@modules/shared';
 
 @Injectable()

apps/api/src/modules/industrial/application/commands/lock-osm-park/lock-osm-park.command.ts

@@ -0,0 +1,11 @@
+/**
+ * Toggle the `osmLocked` flag on a park. When locked, the OSM sync cron
+ * skips this row entirely — useful when admin has curated values that
+ * conflict with what OSM contributors keep changing.
+ */
+export class LockOsmParkCommand {
+  constructor(
+    public readonly parkId: string,
+    public readonly locked: boolean,
+  ) {}
+}

apps/api/src/modules/industrial/application/commands/lock-osm-park/lock-osm-park.handler.ts

@@ -0,0 +1,24 @@
+import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
+import { LoggerService, PrismaService } from '@modules/shared';
+import { LockOsmParkCommand } from './lock-osm-park.command';
+
+@CommandHandler(LockOsmParkCommand)
+export class LockOsmParkHandler implements ICommandHandler<LockOsmParkCommand> {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(cmd: LockOsmParkCommand): Promise<{ id: string; locked: boolean }> {
+    const park = await this.prisma.industrialPark.update({
+      where: { id: cmd.parkId },
+      data: { osmLocked: cmd.locked },
+      select: { id: true, osmLocked: true },
+    });
+    this.logger.log(
+      `Park ${park.id} osmLocked → ${park.osmLocked}`,
+      this.constructor.name,
+    );
+    return { id: park.id, locked: park.osmLocked };
+  }
+}

apps/api/src/modules/industrial/application/commands/promote-osm-park/promote-osm-park.command.ts

@@ -0,0 +1,15 @@
+/**
+ * Promote a raw OSM-imported industrial park to the public catalogue.
+ *
+ * - Flips `dataSource` from `OSM` → `OSM_PROMOTED`
+ * - Sets `isPublic = true`
+ * - Optionally locks fields the admin has just curated so the next OSM
+ *   sync doesn't overwrite them.
+ */
+export class PromoteOsmParkCommand {
+  constructor(
+    public readonly parkId: string,
+    /** Field names to add to `lockedFields`. Empty array = no lock. */
+    public readonly lockFields: string[] = [],
+  ) {}
+}

apps/api/src/modules/industrial/application/commands/promote-osm-park/promote-osm-park.handler.ts

@@ -0,0 +1,44 @@
+import { HttpStatus } from '@nestjs/common';
+import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
+import { DomainException, ErrorCode, LoggerService, PrismaService } from '@modules/shared';
+import { PromoteOsmParkCommand } from './promote-osm-park.command';
+
+@CommandHandler(PromoteOsmParkCommand)
+export class PromoteOsmParkHandler implements ICommandHandler<PromoteOsmParkCommand> {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(cmd: PromoteOsmParkCommand): Promise<{ id: string }> {
+    const park = await this.prisma.industrialPark.findUnique({
+      where: { id: cmd.parkId },
+      select: { id: true, dataSource: true, lockedFields: true },
+    });
+    if (!park) {
+      throw new DomainException(
+        ErrorCode.NOT_FOUND,
+        `Không tìm thấy KCN ${cmd.parkId}`,
+        HttpStatus.NOT_FOUND,
+      );
+    }
+    if (park.dataSource === 'MANUAL') {
+      // Already in the public catalog as a manual seed; nothing to promote.
+      return { id: park.id };
+    }
+    const newLocked = Array.from(new Set([...park.lockedFields, ...cmd.lockFields]));
+    await this.prisma.industrialPark.update({
+      where: { id: cmd.parkId },
+      data: {
+        dataSource: 'OSM_PROMOTED',
+        isPublic: true,
+        lockedFields: newLocked,
+      },
+    });
+    this.logger.log(
+      `Promoted park ${cmd.parkId} from OSM → OSM_PROMOTED (locked: ${newLocked.join(', ')})`,
+      this.constructor.name,
+    );
+    return { id: park.id };
+  }
+}

apps/api/src/modules/industrial/application/queries/estimate-industrial-rent/estimate-industrial-rent.handler.ts

@@ -41,7 +41,7 @@ export class EstimateIndustrialRentHandler
     });
 
     // If specific park requested, try to find it
-    let specificPark = parkName
+    const specificPark = parkName
       ? provinceParks.find((p) => p.name.toLowerCase().includes(parkName.toLowerCase()))
       : null;
 

apps/api/src/modules/industrial/application/queries/get-industrial-parks-by-bbox/get-industrial-parks-by-bbox.handler.ts

@@ -0,0 +1,145 @@
+import { InternalServerErrorException } from '@nestjs/common';
+import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import type { Feature, FeatureCollection } from 'geojson';
+import { LoggerService, PrismaService } from '@modules/shared';
+import { GetIndustrialParksByBboxQuery } from './get-industrial-parks-by-bbox.query';
+
+interface BboxRow {
+  id: string;
+  slug: string;
+  name: string;
+  status: string;
+  province: string;
+  data_source: string;
+  occupancy_rate: number;
+  total_area_ha: number;
+  tenant_count: number;
+  point: string; // GeoJSON Point as text (ST_AsGeoJSON)
+  polygon: string | null; // GeoJSON MultiPolygon, only when zoom >= 12
+}
+
+export interface IndustrialParksGeoCollection extends FeatureCollection {
+  /** Quick metadata so the client can show "showing N of M parks" */
+  meta: {
+    count: number;
+    truncated: boolean;
+    zoom: number;
+  };
+}
+
+/** Zoom threshold above which the boundary polygon is included. Below this
+ *  we send only the centroid Point — enough to cluster + render dots. */
+const BOUNDARY_ZOOM = 12;
+
+@QueryHandler(GetIndustrialParksByBboxQuery)
+export class GetIndustrialParksByBboxHandler
+  implements IQueryHandler<GetIndustrialParksByBboxQuery, IndustrialParksGeoCollection>
+{
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(
+    q: GetIndustrialParksByBboxQuery,
+  ): Promise<IndustrialParksGeoCollection> {
+    try {
+      const { south, west, north, east } = q.bbox;
+      const includeBoundary = q.zoom >= BOUNDARY_ZOOM;
+      const limit = Math.min(Math.max(q.limit, 1), 5000);
+      // Visibility logic:
+      //   - Public callers: only `isPublic = true` rows (MANUAL + OSM_PROMOTED).
+      //   - Admin callers (`includeOsmRaw=true`): also include OSM raw rows
+      //     regardless of `isPublic`, so the admin map can preview the
+      //     review queue. Other rows still respect `isPublic`.
+      const visibilityClause = q.includeOsmRaw
+        ? `(
+            ("isPublic" = true AND "dataSource"::text IN ('MANUAL', 'OSM_PROMOTED'))
+            OR "dataSource"::text = 'OSM'
+          )`
+        : `("isPublic" = true AND "dataSource"::text IN ('MANUAL', 'OSM_PROMOTED'))`;
+
+      // Single PostGIS query: bbox filter + optional polygon column.
+      // && is the bbox-intersect operator and uses the GiST index.
+      const rows = await this.prisma.$queryRawUnsafe<BboxRow[]>(
+        `
+        SELECT
+          id,
+          slug,
+          name,
+          status::text,
+          province,
+          "dataSource"::text AS data_source,
+          "occupancyRate" AS occupancy_rate,
+          "totalAreaHa"   AS total_area_ha,
+          "tenantCount"   AS tenant_count,
+          ST_AsGeoJSON(location) AS point,
+          ${includeBoundary ? `ST_AsGeoJSON(boundary)` : `NULL::text`} AS polygon
+        FROM "IndustrialPark"
+        WHERE ${visibilityClause}
+          AND location && ST_MakeEnvelope($1, $2, $3, $4, 4326)
+        ORDER BY "totalAreaHa" DESC NULLS LAST
+        LIMIT ${limit + 1}
+        `,
+        west,
+        south,
+        east,
+        north,
+      );
+
+      const truncated = rows.length > limit;
+      const trimmed = truncated ? rows.slice(0, limit) : rows;
+
+      const features: Feature[] = trimmed.flatMap((r) => {
+        const properties = {
+          id: r.id,
+          slug: r.slug,
+          name: r.name,
+          status: r.status,
+          province: r.province,
+          dataSource: r.data_source,
+          occupancyRate: Number(r.occupancy_rate),
+          totalAreaHa: Number(r.total_area_ha),
+          tenantCount: Number(r.tenant_count),
+        };
+        const out: Feature[] = [];
+        if (r.point) {
+          out.push({
+            type: 'Feature',
+            id: `${r.id}:point`,
+            geometry: JSON.parse(r.point),
+            properties: { ...properties, _kind: 'point' },
+          });
+        }
+        if (r.polygon) {
+          out.push({
+            type: 'Feature',
+            id: `${r.id}:polygon`,
+            geometry: JSON.parse(r.polygon),
+            properties: { ...properties, _kind: 'polygon' },
+          });
+        }
+        return out;
+      });
+
+      return {
+        type: 'FeatureCollection',
+        features,
+        meta: {
+          count: trimmed.length,
+          truncated,
+          zoom: q.zoom,
+        },
+      };
+    } catch (err) {
+      this.logger.error(
+        `Failed to query parks by bbox: ${err instanceof Error ? err.message : err}`,
+        err instanceof Error ? err.stack : undefined,
+        this.constructor.name,
+      );
+      throw new InternalServerErrorException(
+        'Không thể tải KCN theo khu vực. Vui lòng thử lại sau.',
+      );
+    }
+  }
+}

apps/api/src/modules/industrial/application/queries/get-industrial-parks-by-bbox/get-industrial-parks-by-bbox.query.ts

@@ -0,0 +1,20 @@
+/**
+ * Spatial bbox query for the public KCN map. Returns a GeoJSON
+ * FeatureCollection of industrial parks intersecting the given viewport.
+ *
+ * - At low zoom we return Point centroids only (cluster on the client).
+ * - At high zoom (>= 12) we also include the MultiPolygon `boundary`
+ *   so Mapbox can render the park outline.
+ *
+ * Visibility is filtered to MANUAL + OSM_PROMOTED rows by default
+ * (`includeOsmRaw=false`); admin tooling can pass `true` to see the raw
+ * OSM-imported parks awaiting review.
+ */
+export class GetIndustrialParksByBboxQuery {
+  constructor(
+    public readonly bbox: { south: number; west: number; north: number; east: number },
+    public readonly zoom: number,
+    public readonly includeOsmRaw: boolean = false,
+    public readonly limit: number = 1000,
+  ) {}
+}

apps/api/src/modules/industrial/application/queries/list-osm-pending/list-osm-pending.handler.ts

@@ -0,0 +1,143 @@
+import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import { LoggerService, PrismaService } from '@modules/shared';
+import { ListOsmPendingQuery } from './list-osm-pending.query';
+
+export interface OsmPendingItem {
+  id: string;
+  slug: string;
+  name: string;
+  nameEn: string | null;
+  province: string;
+  district: string;
+  region: string;
+  status: string;
+  osmId: string;
+  osmType: string | null;
+  osmTags: unknown;
+  totalAreaHa: number;
+  developer: string;
+  operator: string | null;
+  osmLocked: boolean;
+  lastSyncedAt: Date | null;
+  latitude: number | null;
+  longitude: number | null;
+}
+
+export interface ListOsmPendingResult {
+  data: OsmPendingItem[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+@QueryHandler(ListOsmPendingQuery)
+export class ListOsmPendingHandler implements IQueryHandler<ListOsmPendingQuery> {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(q: ListOsmPendingQuery): Promise<ListOsmPendingResult> {
+    const limit = Math.min(Math.max(q.limit, 1), 200);
+    const offset = (Math.max(q.page, 1) - 1) * limit;
+
+    const conditions: string[] = [`"dataSource"::text = 'OSM'`];
+    const values: unknown[] = [];
+    let p = 1;
+
+    if (q.province) {
+      conditions.push(`province = $${p++}`);
+      values.push(q.province);
+    }
+    if (q.region) {
+      conditions.push(`region::text = $${p++}`);
+      values.push(q.region);
+    }
+    if (q.query) {
+      conditions.push(
+        `(name ILIKE $${p} OR "nameEn" ILIKE $${p} OR developer ILIKE $${p})`,
+      );
+      values.push(`%${q.query}%`);
+      p += 1;
+    }
+    if (q.minAreaHa > 0) {
+      // Use COALESCE so rows whose area we couldn't compute (NODE-only
+      // imports) only show up when the admin explicitly drops the floor
+      // to 0.
+      conditions.push(`COALESCE("totalAreaHa", 0) >= $${p++}`);
+      values.push(q.minAreaHa);
+    }
+    const where = conditions.join(' AND ');
+
+    const [{ count }] = await this.prisma.$queryRawUnsafe<[{ count: bigint }]>(
+      `SELECT COUNT(*)::bigint AS count FROM "IndustrialPark" WHERE ${where}`,
+      ...values,
+    );
+    const total = Number(count);
+
+    const rows = await this.prisma.$queryRawUnsafe<
+      Array<{
+        id: string;
+        slug: string;
+        name: string;
+        nameEn: string | null;
+        province: string;
+        district: string;
+        region: string;
+        status: string;
+        osmId: bigint;
+        osmType: string | null;
+        osmTags: unknown;
+        totalAreaHa: number;
+        developer: string;
+        operator: string | null;
+        osmLocked: boolean;
+        lastSyncedAt: Date | null;
+        lat: number | null;
+        lng: number | null;
+      }>
+    >(
+      `SELECT
+        id, slug, name, "nameEn", province, district,
+        region::text AS region, status::text AS status,
+        "osmId", "osmType"::text AS "osmType", "osmTags",
+        "totalAreaHa", developer, operator, "osmLocked", "lastSyncedAt",
+        ST_Y(location::geometry) AS lat, ST_X(location::geometry) AS lng
+       FROM "IndustrialPark"
+       WHERE ${where}
+       ORDER BY "totalAreaHa" DESC NULLS LAST, "lastSyncedAt" DESC NULLS LAST
+       LIMIT $${p++} OFFSET $${p}`,
+      ...values,
+      limit,
+      offset,
+    );
+
+    return {
+      data: rows.map((r) => ({
+        id: r.id,
+        slug: r.slug,
+        name: r.name,
+        nameEn: r.nameEn,
+        province: r.province,
+        district: r.district,
+        region: r.region,
+        status: r.status,
+        osmId: r.osmId.toString(),
+        osmType: r.osmType,
+        osmTags: r.osmTags,
+        totalAreaHa: Number(r.totalAreaHa),
+        developer: r.developer,
+        operator: r.operator,
+        osmLocked: r.osmLocked,
+        lastSyncedAt: r.lastSyncedAt,
+        latitude: r.lat,
+        longitude: r.lng,
+      })),
+      total,
+      page: q.page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+    };
+  }
+}

apps/api/src/modules/industrial/application/queries/list-osm-pending/list-osm-pending.query.ts

@@ -0,0 +1,19 @@
+/**
+ * Admin OSM review queue — list raw OSM-imported parks that haven't yet
+ * been promoted to the public catalogue.
+ *
+ * `minAreaHa` lets admins skip the long tail of `landuse=industrial`
+ * features OSM tags that turn out to be single factories or warehouses
+ * (typically < 5 ha). The default of 50 ha surfaces "real" KCN first; pass
+ * `0` to see everything.
+ */
+export class ListOsmPendingQuery {
+  constructor(
+    public readonly page: number = 1,
+    public readonly limit: number = 50,
+    public readonly query?: string,
+    public readonly province?: string,
+    public readonly minAreaHa: number = 50,
+    public readonly region?: string,
+  ) {}
+}

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

@@ -5,6 +5,8 @@ import { CreateIndustrialListingHandler } from './application/commands/create-in
 import { CreateIndustrialParkHandler } from './application/commands/create-industrial-park/create-industrial-park.handler';
 import { DeleteIndustrialListingHandler } from './application/commands/delete-industrial-listing/delete-industrial-listing.handler';
 import { DeleteIndustrialParkHandler } from './application/commands/delete-industrial-park/delete-industrial-park.handler';
+import { LockOsmParkHandler } from './application/commands/lock-osm-park/lock-osm-park.handler';
+import { PromoteOsmParkHandler } from './application/commands/promote-osm-park/promote-osm-park.handler';
 import { UpdateIndustrialListingHandler } from './application/commands/update-industrial-listing/update-industrial-listing.handler';
 import { UpdateIndustrialParkHandler } from './application/commands/update-industrial-park/update-industrial-park.handler';
 import { AnalyzeIndustrialLocationHandler } from './application/queries/analyze-industrial-location/analyze-industrial-location.handler';
@@ -12,12 +14,15 @@ import { CompareIndustrialParksHandler } from './application/queries/compare-ind
 import { EstimateIndustrialRentHandler } from './application/queries/estimate-industrial-rent/estimate-industrial-rent.handler';
 import { GetIndustrialListingHandler } from './application/queries/get-industrial-listing/get-industrial-listing.handler';
 import { GetIndustrialParkHandler } from './application/queries/get-industrial-park/get-industrial-park.handler';
+import { GetIndustrialParksByBboxHandler } from './application/queries/get-industrial-parks-by-bbox/get-industrial-parks-by-bbox.handler';
 import { IndustrialMarketHandler } from './application/queries/industrial-market/industrial-market.handler';
 import { IndustrialParkStatsHandler } from './application/queries/industrial-park-stats/industrial-park-stats.handler';
 import { ListIndustrialListingsHandler } from './application/queries/list-industrial-listings/list-industrial-listings.handler';
 import { ListIndustrialParksHandler } from './application/queries/list-industrial-parks/list-industrial-parks.handler';
+import { ListOsmPendingHandler } from './application/queries/list-osm-pending/list-osm-pending.handler';
 import { INDUSTRIAL_LISTING_REPOSITORY } from './domain/repositories/industrial-listing.repository';
 import { INDUSTRIAL_PARK_REPOSITORY } from './domain/repositories/industrial-park.repository';
+import { OsmSyncCronService } from './infrastructure/cron/osm-sync-cron.service';
 import { PrismaIndustrialListingRepository } from './infrastructure/repositories/prisma-industrial-listing.repository';
 import { PrismaIndustrialParkRepository } from './infrastructure/repositories/prisma-industrial-park.repository';
 import { TypesenseIndustrialService } from './infrastructure/services/typesense-industrial.service';
@@ -31,18 +36,22 @@ const CommandHandlers = [
   CreateIndustrialListingHandler,
   UpdateIndustrialListingHandler,
   DeleteIndustrialListingHandler,
+  PromoteOsmParkHandler,
+  LockOsmParkHandler,
 ];
 
 const QueryHandlers = [
   AnalyzeIndustrialLocationHandler,
   EstimateIndustrialRentHandler,
   GetIndustrialParkHandler,
+  GetIndustrialParksByBboxHandler,
   ListIndustrialParksHandler,
   CompareIndustrialParksHandler,
   IndustrialParkStatsHandler,
   IndustrialMarketHandler,
   GetIndustrialListingHandler,
   ListIndustrialListingsHandler,
+  ListOsmPendingHandler,
 ];
 
 @Module({
@@ -52,6 +61,7 @@ const QueryHandlers = [
     { provide: INDUSTRIAL_PARK_REPOSITORY, useClass: PrismaIndustrialParkRepository },
     { provide: INDUSTRIAL_LISTING_REPOSITORY, useClass: PrismaIndustrialListingRepository },
     TypesenseIndustrialService,
+    OsmSyncCronService,
     ...CommandHandlers,
     ...QueryHandlers,
   ],

apps/api/src/modules/industrial/infrastructure/cron/osm-sync-cron.service.ts

@@ -0,0 +1,96 @@
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import { Injectable } from '@nestjs/common';
+import { Cron } from '@nestjs/schedule';
+import { LoggerService } from '@modules/shared';
+
+/**
+ * Monthly OSM industrial-park reconciliation. Schedules the same script
+ * we run manually for the bulk import (`scripts/sync-osm-industrial-parks.ts`)
+ * — this keeps the import logic in one place. The cron is a thin
+ * orchestrator that:
+ *
+ *   • Spawns the sync script (one chunk at a time to avoid Overpass 504s)
+ *   • Logs stdout/stderr line-by-line into the application logger
+ *   • Skips entirely if `OSM_SYNC_ENABLED !== 'true'` so dev environments
+ *     don't accidentally call Overpass
+ *
+ * Because the script uses upsert keyed on `osmId` and respects the
+ * `osmLocked` / `lockedFields` columns from PR 1, replays are safe — new
+ * OSM entities are added, removed entities stay in the DB (admin can
+ * delete them via the review UI), and admin-edited fields are preserved.
+ */
+@Injectable()
+export class OsmSyncCronService {
+  constructor(private readonly logger: LoggerService) {}
+
+  /** Run on the 1st of each month at 02:00 ICT. */
+  @Cron('0 2 1 * *', { timeZone: 'Asia/Ho_Chi_Minh' })
+  async monthlySync(): Promise<void> {
+    if (process.env['OSM_SYNC_ENABLED'] !== 'true') {
+      this.logger.log(
+        'OSM_SYNC_ENABLED != true — skipping monthly sync.',
+        'OsmSyncCronService',
+      );
+      return;
+    }
+    this.logger.log('Starting monthly OSM sync…', 'OsmSyncCronService');
+
+    const chunks = ['north', 'northCentral', 'southCentral', 'south'];
+    for (const chunk of chunks) {
+      try {
+        await this.runChunk(chunk);
+      } catch (err) {
+        this.logger.error(
+          `OSM sync chunk "${chunk}" failed: ${err instanceof Error ? err.message : err}`,
+          err instanceof Error ? err.stack : undefined,
+          'OsmSyncCronService',
+        );
+        // Continue with the next chunk — partial success is better than
+        // failing the whole pass.
+      }
+    }
+    this.logger.log('Monthly OSM sync complete.', 'OsmSyncCronService');
+  }
+
+  private runChunk(chunk: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const scriptPath = path.resolve(
+        __dirname,
+        '../../../../../../..',
+        'scripts/sync-osm-industrial-parks.ts',
+      );
+      const child = spawn(
+        'pnpm',
+        ['tsx', scriptPath, `--chunk=${chunk}`],
+        {
+          cwd: path.resolve(__dirname, '../../../../../../..'),
+          env: {
+            ...process.env,
+            NODE_OPTIONS: '-r dotenv/config',
+            DOTENV_CONFIG_PATH: '.env',
+          },
+        },
+      );
+      child.stdout?.on('data', (b) => {
+        for (const line of b.toString().split('\n')) {
+          if (line.trim()) {
+            this.logger.log(`[${chunk}] ${line.trim()}`, 'OsmSyncCronService');
+          }
+        }
+      });
+      child.stderr?.on('data', (b) => {
+        for (const line of b.toString().split('\n')) {
+          if (line.trim()) {
+            this.logger.warn(`[${chunk}] ${line.trim()}`, 'OsmSyncCronService');
+          }
+        }
+      });
+      child.on('error', reject);
+      child.on('exit', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`sync-osm-industrial-parks exited ${code}`));
+      });
+    });
+  }
+}

apps/api/src/modules/industrial/infrastructure/repositories/prisma-industrial-park.repository.ts

@@ -160,6 +160,11 @@ export class PrismaIndustrialParkRepository implements IIndustrialParkRepository
     if (params.ownerId) {
       conditions.push(`"ownerId" = $${paramIndex++}`);
       values.push(params.ownerId);
+    } else {
+      // Public list: hide raw OSM imports until an admin reviews + promotes
+      // them. MANUAL rows + OSM_PROMOTED rows stay visible.
+      conditions.push(`"isPublic" = true`);
+      conditions.push(`"dataSource"::text IN ('MANUAL', 'OSM_PROMOTED')`);
     }
     if (params.query) {
       conditions.push(`(name ILIKE $${paramIndex} OR "nameEn" ILIKE $${paramIndex} OR developer ILIKE $${paramIndex} OR province ILIKE $${paramIndex})`);
@@ -175,10 +180,14 @@ export class PrismaIndustrialParkRepository implements IIndustrialParkRepository
     );
     const total = Number(countResult[0].count);
 
+    // Sort by area DESC primarily — the public catalog now contains ~2k
+    // OSM_PROMOTED rows, many of which are small factory polygons. Putting
+    // the largest KCN first surfaces the meaningful entries; occupancy
+    // rate is a tiebreaker for curated rows where it's actually filled in.
     const rows = await this.prisma.$queryRawUnsafe<RawPark[]>(
       `SELECT *, ST_Y(location::geometry) as lat, ST_X(location::geometry) as lng
        FROM "IndustrialPark" WHERE ${where}
-       ORDER BY "occupancyRate" DESC, "createdAt" DESC
+       ORDER BY "totalAreaHa" DESC NULLS LAST, "occupancyRate" DESC, "createdAt" DESC
        LIMIT $${paramIndex++} OFFSET $${paramIndex}`,
       ...values, limit, offset,
     );

apps/api/src/modules/industrial/presentation/controllers/industrial-parks.controller.ts

@@ -2,23 +2,27 @@ import { Body, Controller, Delete, Get, Param, Patch, Post, Query, UseGuards } f
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { ApiBearerAuth, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { UserRole } from '@prisma/client';
-import { CurrentUser, JwtAuthGuard, Roles, RolesGuard } from '@modules/auth';
-import type { JwtPayload } from '@modules/auth';
+import { CurrentUser, JwtAuthGuard, Roles, RolesGuard, type JwtPayload  } from '@modules/auth';
 import { NotFoundException } from '@modules/shared';
-import { AnalyzeIndustrialLocationQuery } from '../../application/queries/analyze-industrial-location/analyze-industrial-location.query';
 import { CreateIndustrialParkCommand } from '../../application/commands/create-industrial-park/create-industrial-park.command';
 import { DeleteIndustrialParkCommand } from '../../application/commands/delete-industrial-park/delete-industrial-park.command';
-import { EstimateIndustrialRentQuery } from '../../application/queries/estimate-industrial-rent/estimate-industrial-rent.query';
+import { LockOsmParkCommand } from '../../application/commands/lock-osm-park/lock-osm-park.command';
+import { PromoteOsmParkCommand } from '../../application/commands/promote-osm-park/promote-osm-park.command';
 import { UpdateIndustrialParkCommand } from '../../application/commands/update-industrial-park/update-industrial-park.command';
+import { AnalyzeIndustrialLocationQuery } from '../../application/queries/analyze-industrial-location/analyze-industrial-location.query';
 import { CompareIndustrialParksQuery } from '../../application/queries/compare-industrial-parks/compare-industrial-parks.query';
+import { EstimateIndustrialRentQuery } from '../../application/queries/estimate-industrial-rent/estimate-industrial-rent.query';
 import { GetIndustrialParkQuery } from '../../application/queries/get-industrial-park/get-industrial-park.query';
+import { GetIndustrialParksByBboxQuery } from '../../application/queries/get-industrial-parks-by-bbox/get-industrial-parks-by-bbox.query';
 import { IndustrialMarketQuery } from '../../application/queries/industrial-market/industrial-market.query';
 import { IndustrialParkStatsQuery } from '../../application/queries/industrial-park-stats/industrial-park-stats.query';
 import { ListIndustrialParksQuery } from '../../application/queries/list-industrial-parks/list-industrial-parks.query';
+import { ListOsmPendingQuery } from '../../application/queries/list-osm-pending/list-osm-pending.query';
 import { AnalyzeIndustrialLocationDto } from '../dto/analyze-industrial-location.dto';
 import { CompareIndustrialParksDto } from '../dto/compare-industrial-parks.dto';
 import { CreateIndustrialParkDto } from '../dto/create-industrial-park.dto';
 import { EstimateIndustrialRentDto } from '../dto/estimate-industrial-rent.dto';
+import { IndustrialParksBboxDto } from '../dto/parks-bbox.dto';
 import { SearchIndustrialParksDto } from '../dto/search-industrial-parks.dto';
 import { UpdateIndustrialParkDto } from '../dto/update-industrial-park.dto';
 
@@ -51,6 +55,24 @@ export class IndustrialParksController {
     );
   }
 
+  @ApiOperation({
+    summary: 'KCN trong viewport bản đồ',
+    description:
+      'Trả về GeoJSON FeatureCollection của KCN nằm trong bbox. Zoom < 12 chỉ trả centroid Point, zoom >= 12 kèm MultiPolygon outline.',
+  })
+  @ApiResponse({ status: 200, description: 'GeoJSON FeatureCollection + meta' })
+  @Get('parks/by-bbox')
+  async parksByBbox(@Query() dto: IndustrialParksBboxDto) {
+    return this.queryBus.execute(
+      new GetIndustrialParksByBboxQuery(
+        { south: dto.south, west: dto.west, north: dto.north, east: dto.east },
+        dto.zoom,
+        dto.includeOsmRaw ?? false,
+        dto.limit ?? 1000,
+      ),
+    );
+  }
+
   // ── Park Operator endpoints ───────────────────────────────────────
 
   @ApiOperation({
@@ -262,4 +284,72 @@ export class IndustrialParksController {
     );
     return { success: true };
   }
+
+  // ── OSM review & promote (admin only) ────────────────────────────────
+
+  @ApiOperation({
+    summary: 'Hàng đợi review OSM (admin)',
+    description:
+      'Liệt kê các KCN có dataSource=OSM (chưa được duyệt). Admin có thể promote → public hoặc lock để bảo vệ.',
+  })
+  @ApiResponse({ status: 200, description: 'Danh sách KCN đang chờ review' })
+  @ApiBearerAuth('JWT')
+  @UseGuards(JwtAuthGuard, RolesGuard)
+  @Roles(UserRole.ADMIN)
+  @Get('parks/osm/pending')
+  async listOsmPending(
+    @Query('page') page?: string,
+    @Query('limit') limit?: string,
+    @Query('q') q?: string,
+    @Query('province') province?: string,
+    @Query('minAreaHa') minAreaHa?: string,
+    @Query('region') region?: string,
+  ) {
+    return this.queryBus.execute(
+      new ListOsmPendingQuery(
+        page ? parseInt(page, 10) : 1,
+        limit ? parseInt(limit, 10) : 50,
+        q,
+        province,
+        minAreaHa !== undefined ? Number(minAreaHa) : 50,
+        region,
+      ),
+    );
+  }
+
+  @ApiOperation({
+    summary: 'Promote KCN từ OSM (admin)',
+    description:
+      'Chuyển dataSource OSM → OSM_PROMOTED và set isPublic=true. Có thể lock các field admin vừa edit.',
+  })
+  @ApiResponse({ status: 200, description: 'Đã promote' })
+  @ApiResponse({ status: 404, description: 'Không tìm thấy KCN' })
+  @ApiBearerAuth('JWT')
+  @UseGuards(JwtAuthGuard, RolesGuard)
+  @Roles(UserRole.ADMIN)
+  @Post('parks/:id/osm/promote')
+  async promoteOsm(
+    @Param('id') id: string,
+    @Body() body: { lockFields?: string[] },
+  ) {
+    return this.commandBus.execute(
+      new PromoteOsmParkCommand(id, body.lockFields ?? []),
+    );
+  }
+
+  @ApiOperation({
+    summary: 'Lock/unlock OSM sync cho KCN (admin)',
+    description: 'Khi locked=true, sync cron sẽ bỏ qua row này hoàn toàn.',
+  })
+  @ApiResponse({ status: 200, description: 'Đã cập nhật trạng thái lock' })
+  @ApiBearerAuth('JWT')
+  @UseGuards(JwtAuthGuard, RolesGuard)
+  @Roles(UserRole.ADMIN)
+  @Post('parks/:id/osm/lock')
+  async lockOsm(
+    @Param('id') id: string,
+    @Body() body: { locked: boolean },
+  ) {
+    return this.commandBus.execute(new LockOsmParkCommand(id, body.locked));
+  }
 }

apps/api/src/modules/industrial/presentation/dto/analyze-industrial-location.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 import { Type } from 'class-transformer';
+import { IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 
 export class AnalyzeIndustrialLocationDto {
   @ApiProperty({ example: 10.9, description: 'Vĩ độ' })

apps/api/src/modules/industrial/presentation/dto/estimate-industrial-rent.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsBoolean, IsEnum, IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 import { Type } from 'class-transformer';
+import { IsBoolean, IsEnum, IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 
 const INDUSTRIAL_PROPERTY_TYPES = [
   'industrial_land',

apps/api/src/modules/industrial/presentation/dto/parks-bbox.dto.ts

@@ -0,0 +1,68 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Transform, Type } from 'class-transformer';
+import { IsBoolean, IsInt, IsNumber, Max, Min } from 'class-validator';
+
+/**
+ * Query params for `GET /industrial/parks/by-bbox`.
+ *
+ * The bbox covers the user's current Mapbox viewport. `zoom` controls
+ * whether the response includes polygon boundaries (zoom >= 12) or just
+ * Point centroids.
+ */
+export class IndustrialParksBboxDto {
+  @ApiProperty({ example: 8.0, description: 'Southern (min) latitude of the viewport' })
+  @Type(() => Number)
+  @IsNumber()
+  @Min(-90)
+  @Max(90)
+  south!: number;
+
+  @ApiProperty({ example: 102.0, description: 'Western (min) longitude of the viewport' })
+  @Type(() => Number)
+  @IsNumber()
+  @Min(-180)
+  @Max(180)
+  west!: number;
+
+  @ApiProperty({ example: 23.5, description: 'Northern (max) latitude of the viewport' })
+  @Type(() => Number)
+  @IsNumber()
+  @Min(-90)
+  @Max(90)
+  north!: number;
+
+  @ApiProperty({ example: 110.0, description: 'Eastern (max) longitude of the viewport' })
+  @Type(() => Number)
+  @IsNumber()
+  @Min(-180)
+  @Max(180)
+  east!: number;
+
+  @ApiProperty({ example: 8, description: 'Mapbox zoom level (0-22)' })
+  @Type(() => Number)
+  @IsInt()
+  @Min(0)
+  @Max(22)
+  zoom!: number;
+
+  @ApiProperty({
+    required: false,
+    default: false,
+    description: 'Include raw OSM imports (admin only). Default: false.',
+  })
+  @Transform(({ value }) => value === 'true' || value === true)
+  @IsBoolean()
+  includeOsmRaw?: boolean = false;
+
+  @ApiProperty({
+    required: false,
+    default: 3000,
+    description:
+      'Max features to return. Default 3000 covers the entire promoted KCN catalog at country zoom; raise to 5000 if you also include raw OSM imports.',
+  })
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(5000)
+  limit?: number = 3000;
+}

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

@@ -1,9 +1,9 @@
 import { Module } from '@nestjs/common';
 import { CqrsModule } from '@nestjs/cqrs';
-import { InquiryCreatedToLeadListener } from './application/event-handlers/inquiry-created-to-lead.listener';
 import { CreateLeadHandler } from './application/commands/create-lead/create-lead.handler';
 import { DeleteLeadHandler } from './application/commands/delete-lead/delete-lead.handler';
 import { UpdateLeadStatusHandler } from './application/commands/update-lead-status/update-lead-status.handler';
+import { InquiryCreatedToLeadListener } from './application/event-handlers/inquiry-created-to-lead.listener';
 import { GetLeadStatsHandler } from './application/queries/get-lead-stats/get-lead-stats.handler';
 import { GetLeadsByAgentHandler } from './application/queries/get-leads-by-agent/get-leads-by-agent.handler';
 import { LEAD_REPOSITORY } from './domain/repositories/lead.repository';

apps/api/src/modules/listings/application/__tests__/commands.spec.ts

@@ -146,12 +146,14 @@ describe('UpdateListingStatusCommand', () => {
       'listing-1',
       'ACTIVE',
       'user-1',
+      'ADMIN',
       'Đã xác minh thông tin',
     );
 
     expect(command.listingId).toBe('listing-1');
     expect(command.newStatus).toBe('ACTIVE');
     expect(command.userId).toBe('user-1');
+    expect(command.userRole).toBe('ADMIN');
     expect(command.moderationNotes).toBe('Đã xác minh thông tin');
   });
 

apps/api/src/modules/listings/application/__tests__/record-price-history.handler.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { RecordPriceHistoryHandler } from '../event-handlers/record-price-history.handler';
 import { ListingPriceChangedEvent } from '../../domain/events/listing-price-changed.event';
+import { RecordPriceHistoryHandler } from '../event-handlers/record-price-history.handler';
 
 describe('RecordPriceHistoryHandler', () => {
   let handler: RecordPriceHistoryHandler;

apps/api/src/modules/listings/application/__tests__/update-listing-status.handler.spec.ts

@@ -52,7 +52,7 @@ describe('UpdateListingStatusHandler', () => {
     const listing = createListing('listing-1', 'PENDING_REVIEW');
     mockListingRepo.findById.mockResolvedValue(listing);
 
-    const command = new UpdateListingStatusCommand('listing-1', 'ACTIVE', 'admin-1');
+    const command = new UpdateListingStatusCommand('listing-1', 'ACTIVE', 'admin-1', 'ADMIN');
     const result = await handler.execute(command);
 
     expect(result.status).toBe('ACTIVE');
@@ -64,7 +64,7 @@ describe('UpdateListingStatusHandler', () => {
     const listing = createListing('listing-1', 'PENDING_REVIEW');
     mockListingRepo.findById.mockResolvedValue(listing);
 
-    const command = new UpdateListingStatusCommand('listing-1', 'REJECTED', 'admin-1', 'Vi phạm chính sách');
+    const command = new UpdateListingStatusCommand('listing-1', 'REJECTED', 'admin-1', 'ADMIN', 'Vi phạm chính sách');
     const result = await handler.execute(command);
 
     expect(result.status).toBe('REJECTED');
@@ -74,7 +74,7 @@ describe('UpdateListingStatusHandler', () => {
     const listing = createListing('listing-1', 'ACTIVE');
     mockListingRepo.findById.mockResolvedValue(listing);
 
-    const command = new UpdateListingStatusCommand('listing-1', 'SOLD', 'seller-1');
+    const command = new UpdateListingStatusCommand('listing-1', 'SOLD', 'seller-1', 'SELLER');
     const result = await handler.execute(command);
 
     expect(result.status).toBe('SOLD');
@@ -83,7 +83,7 @@ describe('UpdateListingStatusHandler', () => {
   it('throws NotFoundException for non-existent listing', async () => {
     mockListingRepo.findById.mockResolvedValue(null);
 
-    const command = new UpdateListingStatusCommand('nonexistent', 'ACTIVE', 'admin-1');
+    const command = new UpdateListingStatusCommand('nonexistent', 'ACTIVE', 'admin-1', 'ADMIN');
 
     await expect(handler.execute(command)).rejects.toThrow('Listing');
   });
@@ -92,8 +92,28 @@ describe('UpdateListingStatusHandler', () => {
     const listing = createListing('listing-1', 'DRAFT');
     mockListingRepo.findById.mockResolvedValue(listing);
 
-    const command = new UpdateListingStatusCommand('listing-1', 'SOLD', 'seller-1');
+    const command = new UpdateListingStatusCommand('listing-1', 'SOLD', 'seller-1', 'SELLER');
 
     await expect(handler.execute(command)).rejects.toThrow(/trạng thái/);
   });
+
+  it('rejects moderation transitions from non-admin users', async () => {
+    const listing = createListing('listing-1', 'PENDING_REVIEW');
+    mockListingRepo.findById.mockResolvedValue(listing);
+
+    const command = new UpdateListingStatusCommand('listing-1', 'ACTIVE', 'seller-1', 'SELLER');
+
+    await expect(handler.execute(command)).rejects.toThrow(/quản trị viên/);
+    expect(mockListingRepo.update).not.toHaveBeenCalled();
+  });
+
+  it('rejects status updates from non-owner users', async () => {
+    const listing = createListing('listing-1', 'ACTIVE');
+    mockListingRepo.findById.mockResolvedValue(listing);
+
+    const command = new UpdateListingStatusCommand('listing-1', 'SOLD', 'other-user', 'SELLER');
+
+    await expect(handler.execute(command)).rejects.toThrow(/người bán/);
+    expect(mockListingRepo.update).not.toHaveBeenCalled();
+  });
 });

apps/api/src/modules/listings/application/commands/moderate-listing/moderate-listing.handler.ts

@@ -2,7 +2,6 @@ import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, EventBus, type ICommandHandler } from '@nestjs/cqrs';
 import { DomainException, NotFoundException, CacheService, CachePrefix, LoggerService } from '@modules/shared';
 import { LISTING_REPOSITORY, type IListingRepository } from '../../../domain/repositories/listing.repository';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI needs runtime reference
 import { ModerationService } from '../../../domain/services/moderation.service';
 import { ModerateListingCommand } from './moderate-listing.command';
 

apps/api/src/modules/listings/application/commands/update-listing-status/update-listing-status.command.ts

@@ -5,6 +5,7 @@ export class UpdateListingStatusCommand {
     public readonly listingId: string,
     public readonly newStatus: ListingStatus,
     public readonly userId: string,
+    public readonly userRole?: string,
     public readonly moderationNotes?: string,
   ) {}
 }

apps/api/src/modules/listings/application/commands/update-listing-status/update-listing-status.handler.ts

@@ -1,8 +1,7 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, EventBus, type ICommandHandler } from '@nestjs/cqrs';
-import { DomainException, NotFoundException, CacheService, CachePrefix, LoggerService } from '@modules/shared';
+import { DomainException, ForbiddenException, NotFoundException, CacheService, CachePrefix, LoggerService } from '@modules/shared';
 import { LISTING_REPOSITORY, type IListingRepository } from '../../../domain/repositories/listing.repository';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI needs runtime reference
 import { ModerationService } from '../../../domain/services/moderation.service';
 import { UpdateListingStatusCommand } from './update-listing-status.command';
 
@@ -23,6 +22,23 @@ export class UpdateListingStatusHandler implements ICommandHandler<UpdateListing
         throw new NotFoundException('Listing', command.listingId);
       }
 
+      const isAdmin = command.userRole === 'ADMIN';
+      const isOwner = listing.sellerId === command.userId;
+      const isAssignedAgent = listing.agentId !== null && listing.agentId === command.userId;
+      const isModerationTransition =
+        (listing.status === 'PENDING_REVIEW' && command.newStatus === 'ACTIVE') ||
+        command.newStatus === 'REJECTED';
+
+      if (isModerationTransition && !isAdmin) {
+        throw new ForbiddenException('Chỉ quản trị viên mới có thể duyệt hoặc từ chối tin đăng');
+      }
+
+      if (!isAdmin && !isOwner && !isAssignedAgent) {
+        throw new ForbiddenException(
+          'Chỉ người bán, môi giới được giao hoặc quản trị viên mới có thể cập nhật trạng thái tin đăng',
+        );
+      }
+
       this.moderationService.applyStatusTransition(
         listing,
         command.newStatus,

apps/api/src/modules/listings/application/queries/get-listing/get-listing.handler.ts

@@ -1,7 +1,7 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
-import { DomainException, CacheService, CachePrefix, CacheTTL, LoggerService } from '@modules/shared';
 import { AVM_SERVICE, type IAVMService } from '@modules/analytics';
+import { DomainException, CacheService, CachePrefix, CacheTTL, LoggerService } from '@modules/shared';
 import { type ListingDetailData } from '../../../domain/repositories/listing-read.dto';
 import { LISTING_REPOSITORY, type IListingRepository } from '../../../domain/repositories/listing.repository';
 import { GetListingQuery } from './get-listing.query';

apps/api/src/modules/listings/index.ts

@@ -23,3 +23,10 @@ export { ListingOwnershipTransferredEvent } from './domain/events/listing-owners
 export { ListingFeaturedExpiredEvent } from './domain/events/listing-featured-expired.event';
 export { ListingExpiringEvent } from './domain/events/listing-expiring.event';
 export { Price } from './domain/value-objects/price.vo';
+export { Address } from './domain/value-objects/address.vo';
+export {
+  MEDIA_STORAGE_SERVICE,
+  type IMediaStorageService,
+  type PresignedUploadResult,
+  MinioMediaStorageService,
+} from './infrastructure/services/media-storage.service';

apps/api/src/modules/listings/infrastructure/__tests__/listing-read.queries.spec.ts

@@ -206,7 +206,6 @@ describe('listing-read.queries', () => {
 });
 
 
-import { findSimilarListingsQuery } from '../repositories/listing-read.queries';
 
 describe('findSimilarListingsQuery', () => {
   let mockPrisma: {

apps/api/src/modules/listings/infrastructure/cron/listing-expiry-cron.service.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
 import { EventBus } from '@nestjs/cqrs';
-import { Cron, CronExpression } from '@nestjs/schedule';
+import { Cron } from '@nestjs/schedule';
 import { ListingStatus } from '@prisma/client';
 import { PrismaService, LoggerService } from '@modules/shared';
 import { ListingExpiringEvent } from '../../domain/events/listing-expiring.event';

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

@@ -2,6 +2,7 @@ import { forwardRef, Module } from '@nestjs/common';
 import { CqrsModule } from '@nestjs/cqrs';
 import { MulterModule } from '@nestjs/platform-express';
 import { AnalyticsModule } from '@modules/analytics';
+import { PaymentsModule } from '@modules/payments';
 import { FeatureListingThrottlerGuard } from '@modules/shared';
 import { AdminFeatureListingHandler } from './application/commands/admin-feature-listing/admin-feature-listing.handler';
 import { BulkUpdateListingsHandler } from './application/commands/bulk-update-listings/bulk-update-listings.handler';
@@ -68,6 +69,7 @@ const EventHandlers = [
   imports: [
     CqrsModule,
     forwardRef(() => AnalyticsModule),
+    PaymentsModule, // for PAYMENT_INITIATOR (used by FeatureListingHandler)
     MulterModule.register({
       limits: { fileSize: 100 * 1024 * 1024 }, // 100 MB — per-type limits enforced by FileValidationPipe
     }),

apps/api/src/modules/listings/presentation/controllers/listings.controller.ts

@@ -43,6 +43,8 @@ import type { FeatureListingResult } from '../../application/commands/feature-li
 import { ModerateListingCommand } from '../../application/commands/moderate-listing/moderate-listing.command';
 import { PromoteFeaturedListingCommand } from '../../application/commands/promote-featured-listing/promote-featured-listing.command';
 import type { PromoteFeaturedListingResult } from '../../application/commands/promote-featured-listing/promote-featured-listing.handler';
+import { ReportListingCommand } from '../../application/commands/report-listing/report-listing.command';
+import type { ReportListingResult } from '../../application/commands/report-listing/report-listing.handler';
 import { UpdateListingCommand } from '../../application/commands/update-listing/update-listing.command';
 import type { UpdateListingResult } from '../../application/commands/update-listing/update-listing.handler';
 import { UpdateListingStatusCommand } from '../../application/commands/update-listing-status/update-listing-status.command';
@@ -62,12 +64,10 @@ import { CreateListingDto } from '../dto/create-listing.dto';
 import { FeatureListingDto } from '../dto/feature-listing.dto';
 import { ModerateListingDto } from '../dto/moderate-listing.dto';
 import { PromoteFeaturedListingDto } from '../dto/promote-featured-listing.dto';
+import { ReportListingDto } from '../dto/report-listing.dto';
 import { SearchListingsDto } from '../dto/search-listings.dto';
 import { UpdateListingStatusDto } from '../dto/update-listing-status.dto';
 import { UpdateListingDto } from '../dto/update-listing.dto';
-import { ReportListingDto } from '../dto/report-listing.dto';
-import { ReportListingCommand } from '../../application/commands/report-listing/report-listing.command';
-import type { ReportListingResult } from '../../application/commands/report-listing/report-listing.handler';
 
 @ApiTags('listings')
 @Controller('listings')
@@ -132,7 +132,6 @@ export class ListingsController {
           petFriendly: dto.petFriendly,
           suitableFor: dto.suitableFor,
           whyThisLocation: dto.whyThisLocation,
-          certificateVerified: dto.certificateVerified,
         },
       ),
     );
@@ -338,7 +337,6 @@ export class ListingsController {
           petFriendly: dto.petFriendly,
           suitableFor: dto.suitableFor,
           whyThisLocation: dto.whyThisLocation,
-          certificateVerified: dto.certificateVerified,
         },
         dto.agentId,
       ),
@@ -389,7 +387,7 @@ export class ListingsController {
     @CurrentUser() user: JwtPayload,
   ): Promise<{ status: string }> {
     return this.commandBus.execute(
-      new UpdateListingStatusCommand(id, dto.status, user.sub, dto.moderationNotes),
+      new UpdateListingStatusCommand(id, dto.status, user.sub, user.role, dto.moderationNotes),
     );
   }
 

apps/api/src/modules/messaging/application/commands/mark-read/mark-read.handler.ts

@@ -1,6 +1,5 @@
 import { Inject, InternalServerErrorException } from '@nestjs/common';
 import { CommandHandler, type ICommandHandler } from '@nestjs/cqrs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports
 import { DomainException, ForbiddenException, NotFoundException, EventBusService, LoggerService } from '@modules/shared';
 import { ConversationReadEvent } from '../../../domain/events/conversation-read.event';
 import {

apps/api/src/modules/messaging/presentation/controllers/messaging.controller.ts

@@ -12,7 +12,6 @@ import {
   HttpCode,
   HttpStatus,
 } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { AuthGuard } from '@nestjs/passport';
 import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiQuery, ApiProperty } from '@nestjs/swagger';

apps/api/src/modules/messaging/presentation/gateways/messaging.gateway.ts

@@ -1,5 +1,4 @@
 import { Inject } from '@nestjs/common';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports
 import { CommandBus } from '@nestjs/cqrs';
 import { OnEvent } from '@nestjs/event-emitter';
 import {
@@ -13,14 +12,12 @@ import {
   type OnGatewayInit,
 } from '@nestjs/websockets';
 import type { Server, Socket } from 'socket.io';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports
 import { TokenService, type JwtPayload } from '@modules/auth';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- NestJS DI requires value imports
 import { LoggerService } from '@modules/shared';
 import { MarkConversationReadCommand } from '../../application/commands/mark-read/mark-read.command';
 import { SendMessageCommand } from '../../application/commands/send-message/send-message.command';
-import type { MessageSentEvent } from '../../domain/events/message-sent.event';
 import type { ConversationReadEvent } from '../../domain/events/conversation-read.event';
+import type { MessageSentEvent } from '../../domain/events/message-sent.event';
 import {
   CONVERSATION_REPOSITORY,
   type IConversationRepository,

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

@@ -31,6 +31,9 @@ import {
   SEARCH_QUERY_DURATION,
   GOODGO_WS_CONNECTED_CLIENTS,
   GOODGO_WS_MESSAGES_TOTAL,
+  READ_MODEL_PROJECTOR_LAG_SECONDS,
+  READ_MODEL_REFRESH_DURATION_SECONDS,
+  READ_MODEL_RECONCILIATION_DRIFT_TOTAL,
   WEB_VITALS_LCP,
   WEB_VITALS_FCP,
   WEB_VITALS_CLS,
@@ -111,6 +114,24 @@ import { HttpMetricsInterceptor } from './presentation/interceptors/http-metrics
       labelNames: ['namespace', 'event', 'direction'],
     }),
 
+    // ── Read-Model Metrics (RFC-003) ──
+    makeGaugeProvider({
+      name: READ_MODEL_PROJECTOR_LAG_SECONDS,
+      help: 'Projector replication lag in seconds, by read model',
+      labelNames: ['read_model'],
+    }),
+    makeHistogramProvider({
+      name: READ_MODEL_REFRESH_DURATION_SECONDS,
+      help: 'Materialized-view refresh duration in seconds',
+      labelNames: ['read_model'],
+      buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60],
+    }),
+    makeCounterProvider({
+      name: READ_MODEL_RECONCILIATION_DRIFT_TOTAL,
+      help: 'Drift events detected during read-model reconciliation',
+      labelNames: ['read_model', 'severity'],
+    }),
+
     // ── Services & Interceptors ──
     MetricsService,
     HttpMetricsInterceptor,

apps/api/src/modules/metrics/presentation/interceptors/http-metrics.interceptor.ts

@@ -6,7 +6,6 @@ import {
 } from '@nestjs/common';
 import { type Request, type Response } from 'express';
 import { type Observable, tap } from 'rxjs';
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { MetricsService } from '../../infrastructure/metrics.service';
 
 @Injectable()

apps/api/src/modules/notifications/application/listeners/listing-expiring.listener.ts

@@ -1,8 +1,8 @@
 import { Injectable } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
 import { OnEvent } from '@nestjs/event-emitter';
-import { LoggerService, PrismaService } from '@modules/shared';
 import { ListingExpiringEvent } from '@modules/listings';
+import { LoggerService, PrismaService } from '@modules/shared';
 import { SendNotificationCommand } from '../commands/send-notification/send-notification.command';
 
 /**

apps/api/src/modules/notifications/application/listeners/password-reset-requested.listener.ts

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
 import { OnEvent } from '@nestjs/event-emitter';
-import { type PasswordResetRequestedEvent } from '@modules/auth/domain/events/password-reset-requested.event';
+import { type PasswordResetRequestedEvent } from '@modules/auth';
 import { LoggerService } from '@modules/shared';
 import { SendNotificationCommand } from '../commands/send-notification/send-notification.command';
 

apps/api/src/modules/notifications/application/listeners/phone-login-otp-requested.listener.ts

@@ -2,8 +2,8 @@ import { Injectable } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
 import { OnEvent } from '@nestjs/event-emitter';
 import { LoggerService } from '@modules/shared';
-import { SendNotificationCommand } from '../commands/send-notification/send-notification.command';
 import type { PhoneLoginOtpRequestedEvent } from '../../../auth/domain/events/phone-login-otp-requested.event';
+import { SendNotificationCommand } from '../commands/send-notification/send-notification.command';
 
 @Injectable()
 export class PhoneLoginOtpRequestedListener {
@@ -20,15 +20,13 @@ export class PhoneLoginOtpRequestedListener {
     );
 
     await this.commandBus.execute(
-      new SendNotificationCommand({
-        userId: event.aggregateId,
-        channel: 'sms',
-        template: 'phone_login_otp',
-        context: {
-          phone: event.phone,
-          otpCode: event.otpCode,
-        },
-      }),
+      new SendNotificationCommand(
+        event.aggregateId,
+        'SMS',
+        'phone_login_otp',
+        { otpCode: event.otpCode },
+        event.phone,
+      ),
     );
   }
 }

apps/api/src/modules/notifications/application/listeners/residential-events.listener.ts

@@ -106,6 +106,7 @@ export class ResidentialPriceDropListener
 
         cursor = batch[batch.length - 1]!.createdAt;
         if (batch.length < ALERT_BATCH_SIZE) break;
+        // eslint-disable-next-line no-constant-condition -- exit via `break` above
       } while (true);
 
       if (matchCount > 0) {
@@ -189,6 +190,7 @@ export class ResidentialNewListingInProjectListener
 
         cursor = batch[batch.length - 1]!.createdAt;
         if (batch.length < ALERT_BATCH_SIZE) break;
+        // eslint-disable-next-line no-constant-condition -- exit via `break` above
       } while (true);
 
       if (matchCount > 0) {

apps/api/src/modules/notifications/infrastructure/__tests__/zalo-oa.service.spec.ts

@@ -401,7 +401,7 @@ describe('ZaloOaService', () => {
     });
 
     it('sends ZNS message when link exists and user is within interaction window', async () => {
-      const { service, prisma } = makeOAuthService();
+      const { service: _service, prisma: _prisma } = makeOAuthService();
 
       // Build a valid encrypted token using our known key
       // We need to pre-encrypt; instead mock ensureFreshToken indirectly by
@@ -431,8 +431,8 @@ describe('ZaloOaService', () => {
       // a link, then spy on fetch to see what access_token value was sent.
 
       // The most pragmatic approach here: spy on fetch and verify call count & structure.
-      const recentInteract = new Date(Date.now() - 5 * 60 * 1_000); // 5 min ago
-      const futureExpiry = new Date(Date.now() + 60 * 60 * 1_000);
+      const _recentInteract = new Date(Date.now() - 5 * 60 * 1_000); // 5 min ago
+      const _futureExpiry = new Date(Date.now() + 60 * 60 * 1_000);
 
       // We need a real encrypted token. Produce one using the service's own round-trip:
       // We'll test that the encryption/decryption is symmetric separately.

apps/api/src/modules/notifications/infrastructure/services/zalo-oa.service.ts

@@ -1,5 +1,5 @@
-import { Injectable, type OnModuleInit } from '@nestjs/common';
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { Injectable, type OnModuleInit } from '@nestjs/common';
 import { LoggerService, PrismaService } from '@modules/shared';
 
 // ─── DTOs ────────────────────────────────────────────────────────────────────

apps/api/src/modules/notifications/presentation/controllers/zalo-oa-link.controller.ts

@@ -11,9 +11,7 @@ import {
 import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { Throttle } from '@nestjs/throttler';
 import { type Response } from 'express';
-import { JwtAuthGuard } from '@modules/auth/presentation/guards/jwt-auth.guard';
-import { CurrentUser } from '@modules/auth/presentation/decorators/current-user.decorator';
-import { type JwtPayload } from '@modules/auth/infrastructure/services/token.service';
+import { type JwtPayload, CurrentUser , JwtAuthGuard  } from '@modules/auth';
 import { ZaloOaService } from '../../infrastructure/services/zalo-oa.service';
 
 const FRONTEND_URL = process.env['FRONTEND_URL'] ?? 'http://localhost:3000';

apps/api/src/modules/notifications/presentation/controllers/zalo-oa-webhook.controller.ts

@@ -51,7 +51,7 @@ export class ZaloOaWebhookController {
   @HttpCode(200)
   async handleEvent(
     @Body() payload: ZaloOaWebhookPayload,
-    @Req() req: RawBodyRequest<Request>,
+    @Req() _req: RawBodyRequest<Request>,
   ): Promise<{ received: true }> {
     const { event_name, sender, timestamp } = payload;