huace-aigc-auth-client 1.1.6__tar.gz → 1.1.8__tar.gz

{huace_aigc_auth_client-1.1.6/huace_aigc_auth_client.egg-info → huace_aigc_auth_client-1.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huace-aigc-auth-client
-Version: 1.1.6
+Version: 1.1.8
 Summary: 华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能
 Author-email: Huace <support@huace.com>
 License: MIT
@@ -45,7 +45,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：http://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -328,21 +328,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -357,7 +357,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -407,7 +407,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -486,18 +486,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -515,6 +591,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -635,10 +719,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8}/README.md

@@ -20,7 +20,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：http://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -303,21 +303,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -332,7 +332,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -382,7 +382,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -461,18 +461,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -490,6 +566,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -610,10 +694,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8}/huace_aigc_auth_client/__init__.py

@@ -98,4 +98,4 @@ __all__ = [
     "register_webhook_router",
     "verify_webhook_signature",
 ]
-__version__ = "1.1.6"
+__version__ = "1.1.8"

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8}/huace_aigc_auth_client/legacy_adapter.py

@@ -147,6 +147,7 @@ class LegacySystemAdapter(ABC):
         Returns:
             Optional[LegacyUserData]: 用户数据，不存在返回 None
         """
+        logger.info(f"Fetching user by username asynchronously: {username}")
         raise NotImplementedError("Subclass must implement get_user_by_username_async method")
     
     @abstractmethod
@@ -159,6 +160,7 @@ class LegacySystemAdapter(ABC):
         Returns:
             Optional[Any]: 创建的用户 ID 或其他标识
         """
+        logger.info(f"Creating user with data: {user_data}")
         raise NotImplementedError("Subclass must implement _create_user_async method")
     
     @abstractmethod
@@ -172,6 +174,7 @@ class LegacySystemAdapter(ABC):
         Returns:
             bool: 更新成功返回 True
         """
+        logger.info(f"Updating user: {username} with data: {user_data}")
         raise NotImplementedError("Subclass must implement _update_user_async method")
     
     @abstractmethod
@@ -184,6 +187,7 @@ class LegacySystemAdapter(ABC):
         Returns:
             bool: 删除成功返回 True
         """
+        logger.info(f"Deleting user: {username}")
         raise NotImplementedError("Subclass must implement _delete_user_async method")
     
     @abstractmethod
@@ -193,6 +197,7 @@ class LegacySystemAdapter(ABC):
         Returns:
             List[LegacyUserData]: 所有用户数据列表
         """
+        logger.info("Fetching all users from legacy system asynchronously")
         raise NotImplementedError("Subclass must implement get_all_users_async method")
     
     async def upsert_user_async(self, user_data: Dict[str, Any], auth_data: Dict[str, Any] = None) -> Dict[str, Any]:
@@ -208,6 +213,7 @@ class LegacySystemAdapter(ABC):
         """
         username = user_data.get("username")
         if not username:
+            logger.error("username is required for upsert operation")
             raise ValueError("username is required for upsert operation")
         
         # 检查用户是否存在
@@ -216,6 +222,7 @@ class LegacySystemAdapter(ABC):
         if existing:
             # 用户存在，执行更新
             if not auth_data or auth_data.get("updatedFields") is None or len(auth_data.get("updatedFields")) == 0:
+                logger.info(f"No updatedFields provided for user: {username}, skipping update")
                 # 如果没有提供 auth_data 或 updatedFields，则不更新
                 return {"created": False, "user_id": existing.get("id")}
             await self._update_user_async(username, user_data)
@@ -234,8 +241,10 @@ class LegacySystemAdapter(ABC):
             Dict: 同步结果统计
         """
         if not self.auth_client:
+            logger.error("auth_client is required for batch_sync_to_auth")
             raise ValueError("auth_client is required for batch_sync_to_auth. Please provide it in constructor.")
         
+        logger.info("Starting batch sync from legacy system to aigc-auth")
         users = await self.get_all_users_async()
         
         results = {
@@ -264,6 +273,7 @@ class LegacySystemAdapter(ABC):
                     auth_data["password"] = password
                 
                 result = self.auth_client.sync_user_to_auth(auth_data)
+                logger.info(f"Sync result for user {user.get('username')}: {result}")
                 
                 if result.get("success"):
                     if result.get("created"):
@@ -277,6 +287,7 @@ class LegacySystemAdapter(ABC):
                         "error": result.get("message")
                     })
             except Exception as e:
+                logger.error(f"Error syncing user {user.get('username')}: {e}")
                 results["failed"] += 1
                 results["errors"].append({
                     "user": user.get("username"),
@@ -311,6 +322,7 @@ class LegacySystemAdapter(ABC):
             legacy_data["password"] = password
             
             # 创建或更新用户
+            logger.info(f"Handling {event} event for user: {legacy_data}")
             result = await self.upsert_user_async(legacy_data)
             
             return {
@@ -321,18 +333,23 @@ class LegacySystemAdapter(ABC):
             }
         
         elif event == "user.deleted":
+            logger.info("Handling user.deleted event")
             # 禁用用户而不是删除
             username = data.get("username")
             if not username:
+                logger.error("username is required for user.deleted event")
                 logger.error("username is required for user.deleted event")
                 return {"success": False, "message": "username is required for user.deleted event"}
+            logger.info(f"Disabling user: {username}")
             await self._delete_user_async(username)
             
             return {"success": True, "message": "User disabled"}
         
         elif event == "user.init_sync_auth":
+            logger.info("Handling user.init_sync_auth event")
             # 初始化同步：批量同步旧系统用户到 aigc-auth
             if not self.auth_client:
+                logger.error("auth_client is required for init_sync_auth event")
                 return {"success": False, "message": "auth_client is required for init_sync_auth event. Please provide it in constructor."}
             
             results = await self.batch_sync_to_auth()
@@ -362,7 +379,7 @@ class LegacySystemAdapter(ABC):
             
             if auth_value is not None:
                 result[mapping.legacy_field] = auth_value
-        
+        logger.info(f"Transformed auth user({auth_user}) to legacy format: {result}")
         return result
     
     def transform_legacy_to_auth(self, legacy_user: LegacyUserData) -> Dict[str, Any]:
@@ -382,7 +399,7 @@ class LegacySystemAdapter(ABC):
             
             if legacy_value is not None:
                 result[mapping.auth_field] = legacy_value
-        
+        logger.info(f"Transformed legacy user({legacy_user}) to auth format: {result}")
         return result
     
     def get_password_for_sync(self, legacy_user: Optional[LegacyUserData] = None) -> tuple:

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8}/huace_aigc_auth_client/sdk.py

@@ -92,7 +92,7 @@ class AigcAuthClient:
         client = AigcAuthClient(
             app_id="your_app_id",
             app_secret="your_app_secret",
-            base_url="https://aigc-auth.huacemedia.com/aigc-auth/api/v1"  # 可选
+            base_url="https://aigc-auth.huacemedia.com/aigc-auth/api/v1"
         )
 
         # 验证 token
@@ -271,6 +271,7 @@ class AigcAuthClient:
             result = response.json()
 
             if result.get("code") != 0:
+                logger.error(f"AigcAuthClient 请求错误: {result}")
                 raise AigcAuthError(
                     result.get("code", -1),
                     result.get("message", "未知错误")
@@ -285,6 +286,7 @@ class AigcAuthClient:
             return response_data
 
         except requests.exceptions.RequestException as e:
+            logger.error(f"AigcAuthClient 请求失败: {str(e)}")
             raise AigcAuthError(-1, f"请求失败: {str(e)}")
 
     def verify_token(self, token: str) -> TokenVerifyResult:
@@ -599,6 +601,7 @@ class AuthMiddleware:
         token = self._extract_token(authorization)
 
         if not token:
+            logger.warning("AuthMiddleware未提供认证信息")
             return JSONResponse(
                 status_code=401,
                 content={"code": 401, "message": "未提供认证信息", "data": None}
@@ -616,6 +619,7 @@ class AuthMiddleware:
             if user_info_callback:
                 await user_info_callback(request, user_info)
         except AigcAuthError as e:
+            logger.error(f"AuthMiddleware认证失败: {e.message}")
             return JSONResponse(
                 status_code=401,
                 content={"code": e.code, "message": e.message, "data": None}
@@ -644,6 +648,7 @@ class AuthMiddleware:
         token = self._extract_token(authorization)
 
         if not token:
+            logger.warning("AuthMiddleware未提供认证信息")
             return jsonify({
                 "code": 401,
                 "message": "未提供认证信息",
@@ -658,6 +663,7 @@ class AuthMiddleware:
             if user_info_callback:
                 user_info_callback(request, user_info)
         except AigcAuthError as e:
+            logger.error(f"AuthMiddleware认证失败: {e.message}")
             return jsonify({
                 "code": e.code,
                 "message": e.message,
@@ -712,6 +718,7 @@ def create_fastapi_auth_dependency(client: AigcAuthClient):
         user_info = client.get_user_info_from_header(authorization)
 
         if user_info is None:
+            logger.warning("FastAPI依赖未登录或Token已过期")
             raise HTTPException(status_code=401, detail="未登录或 Token 已过期")
 
         return user_info

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8/huace_aigc_auth_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huace-aigc-auth-client
-Version: 1.1.6
+Version: 1.1.8
 Summary: 华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能
 Author-email: Huace <support@huace.com>
 License: MIT
@@ -45,7 +45,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：http://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -328,21 +328,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -357,7 +357,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -407,7 +407,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -486,18 +486,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -515,6 +591,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -635,10 +719,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.6 → huace_aigc_auth_client-1.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "huace-aigc-auth-client"
-version = "1.1.6"
+version = "1.1.8"
 description = "华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能"
 readme = "README.md"
 requires-python = ">=3.7"