From 065c082aa7dfbd07b46b95c5c3da7c8ba174ee90 Mon Sep 17 00:00:00 2001
From: YuehuCao <taniacao223@gmail.com>
Date: Fri, 19 Sep 2025 12:15:05 +0800
Subject: [PATCH] feat(guide): guide to use tenant middleware

---
 apps/notification/webapi/middleware/README.md | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 apps/notification/webapi/middleware/README.md

diff --git a/apps/notification/webapi/middleware/README.md b/apps/notification/webapi/middleware/README.md
new file mode 100644
index 0000000..a01f1ce
--- /dev/null
+++ b/apps/notification/webapi/middleware/README.md
@@ -0,0 +1,130 @@
+# Notification Service Middleware Guide
+
+This guide explains how to use and test the middleware system of the notification service.
+
+## Middleware Architecture
+
+### Middleware Execution Order
+```
+Client Request → FreeleapsAuthMiddleware → TenantDBConnectionMiddleware → Business Logic
+```
+
+1. **FreeleapsAuthMiddleware**: API Key validation and path skipping
+2. **TenantDBConnectionMiddleware**: Tenant database switching (based on product_id)
+
+## 1. Setup API Key
+
+### 1.1 Register API Key via freeleaps-auth service
+
+Ensure the freeleaps-auth service is running on port 9000, then execute the following commands:
+
+```bash
+# Register API KEY for magicleaps tenant
+curl -X POST "http://localhost:9000/api/v1/keys/register_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_name": "magicleaps",
+    "product_id": "68a3f19119cfaf36316f6d14",
+    "scopes": ["notify.send_notification"],
+    "expires_at": "2099-12-31T23:59:59Z"
+  }'
+
+# Register API KEY for test-a tenant  
+curl -X POST "http://localhost:9000/api/v1/keys/register_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_name": "test-a",
+    "product_id": "68a3f19119cfaf36316f6d15",
+    "scopes": ["notify.send_notification"],
+    "expires_at": "2099-12-31T23:59:59Z"
+  }'
+
+# Register API KEY for test-b tenant
+curl -X POST "http://localhost:9000/api/v1/keys/register_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_name": "test-b",
+    "product_id": "68a3f19119cfaf36316f6d16",
+    "scopes": ["notify.send_notification"],
+    "expires_at": "2099-12-31T23:59:59Z"
+  }'
+```
+
+### 1.2 Record the returned API KEY
+
+Example successful response:
+```json
+{
+  "success": true,
+  "data": {
+    "tenant_name": "magicleaps",
+    "product_id": "68a3f19119cfaf36316f6d14",
+    "api_key": {
+      "key_id": "ak_live_UkIcMxwBXIw",
+      "api_key": "ak_live_UkIcMxwBXIw.J7qWirjL0IJkmvqktjEh3ViveP8dgiturxyy0KJ5sKk",
+      "status": "active"
+    }
+  }
+}
+```
+
+## 2. Configure Tenant Database
+
+Create tenant documents in the `tenant_doc` collection of the main database:
+
+```json
+[
+  {
+    "tenant_name": "magicleaps",
+    "product_id": "68a3f19119cfaf36316f6d14",
+    "mongodb_uri": "mongodb://localhost:27017/interview",
+    "status": "active"
+  },
+  {
+    "tenant_name": "test-a", 
+    "product_id": "68a3f19119cfaf36316f6d15",
+    "mongodb_uri": "mongodb://localhost:27017/test-a",
+    "status": "active"
+  },
+  {
+    "tenant_name": "test-b",
+    "product_id": "68a3f19119cfaf36316f6d16",
+    "mongodb_uri": "mongodb://localhost:27017/test-b",
+    "status": "active"
+  }
+]
+```
+
+## 3. Test Middleware Functionality
+
+### 3.1 Test System Endpoints (Skip Validation)
+
+```bash
+# Health check endpoints - should return 200, skip all validation
+curl -v "http://localhost:8104/api/_/healthz"
+curl -v "http://localhost:8104/api/_/readyz"
+curl -v "http://localhost:8104/api/_/livez"
+
+# Documentation and monitoring endpoints - should return 200, skip all validation
+curl -v "http://localhost:8104/docs"
+curl -v "http://localhost:8104/metrics"
+```
+
+### 3.2 Test API Key Validation
+
+```bash
+# No API Key - should return 200 (compatibility mode)
+curl -v "http://localhost:8104/api/notification/global_templates/list?region=1"
+
+# Invalid API Key - should return 400/401
+curl -v "http://localhost:8104/api/notification/global_templates/list?region=1" \
+  -H "X-API-KEY: invalid_key"
+
+# Valid API Key - should return 200 and switch to tenant database
+curl -v "http://localhost:8104/api/notification/global_templates/list?region=1" \
+  -H "X-API-KEY: ak_live_UkIcMxwBXIw.J7qWirjL0IJkmvqktjEh3ViveP8dgiturxyy0KJ5sKk"
+```
+
+### 3.3 Check Log Output
+
+View logs in `/apps/notification/log/notification-activity.log`: