newrun

temp_backup/Server_redundant/tempdocs/混合架构开发框架指南.md

@@ -0,0 +1,442 @@
+# DesignerCEP 混合架构开发框架指南
+
+## 🎯 框架概述
+
+这是一个**三层混合架构框架**，专为 Adobe CEP 插件设计，实现了：
+- **核心算法保护**（服务器端计算）
+- **动态更新**（Shell + Core 分离）
+- **安全鉴权**（API Key + 详细日志）
+
+---
+
+## 🏗️ 架构层次
+
+```
+┌──────────────────────────────────────────────────┐
+│  Layer 1: Shell（壳/启动器）                      │
+│  职责: 登录、更新、加载 Core                      │
+│  更新频率: 极低                                   │
+│  位置: 本地安装（PS 扩展目录）                     │
+└──────────────────────────────────────────────────┘
+                      ↓
+┌──────────────────────────────────────────────────┐
+│  Layer 2: Core（业务核）                          │
+│  职责: UI 界面、简单 JSX 执行                     │
+│  更新频率: 高（随时发布新功能）                    │
+│  位置: 远程服务器 → 下载到本地缓存                │
+└──────────────────────────────────────────────────┘
+                      ↓
+┌──────────────────────────────────────────────────┐
+│  Layer 3: Server（后端服务器）                    │
+│  职责: 核心算法、数据处理、鉴权                   │
+│  更新频率: 随时                                   │
+│  位置: 远程服务器                                 │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## 📝 如何添加新功能
+
+### 示例：添加一个"智能滤镜"功能
+
+#### Step 1: 设计功能流程
+
+```
+用户点击按钮 
+  → Core 获取图层信息
+  → Core 发送到 Server（带 API Key）
+  → Server 计算最佳滤镜参数（🔒核心算法）
+  → Server 返回参数
+  → Core 应用滤镜到图层
+```
+
+---
+
+#### Step 2: 后端实现（Server 层）
+
+**文件：** `Server/app/api/v1/jsx_demo.py`
+
+```python
+class FilterRequest(BaseModel):
+    """滤镜计算请求"""
+    layer_id: str
+    image_data: str  # Base64 编码的图层预览
+
+class FilterResult(BaseModel):
+    """滤镜计算结果"""
+    success: bool
+    blur_radius: float
+    sharpen_amount: float
+    saturation: float
+    message: str
+
+@router.post("/calculate-filter", response_model=FilterResult)
+async def calculate_filter(
+    request: FilterRequest,
+    x_api_key: Optional[str] = Header(None)
+):
+    """
+    🔒 服务器端智能滤镜计算
+    客户端只能拿到参数，看不到算法
+    """
+    
+    # 日志
+    logger.info("="*60)
+    logger.info("📥 收到滤镜计算请求")
+    logger.info(f"   图层ID: {request.layer_id}")
+    logger.info(f"   API Key: {x_api_key}")
+    logger.info("="*60)
+    
+    # API Key 验证
+    if not validate_api_key(x_api_key):
+        logger.warning(f"❌ API Key 验证失败")
+        raise HTTPException(status_code=403, detail="无效的 API Key")
+    
+    logger.info("✅ API Key 验证通过")
+    
+    try:
+        # 🔒 核心算法在这里（客户端看不到）
+        # 可以是 AI 模型、图像分析等
+        
+        # 示例：根据图层 ID 计算参数
+        layer_hash = sum(ord(c) for c in request.layer_id)
+        
+        blur_radius = 2.0 + (layer_hash % 10) / 10
+        sharpen_amount = 0.5 + (layer_hash % 5) / 10
+        saturation = 1.0 + (layer_hash % 3) / 10
+        
+        logger.info(f"✅ 计算完成: blur={blur_radius}, sharpen={sharpen_amount}")
+        
+        return FilterResult(
+            success=True,
+            blur_radius=blur_radius,
+            sharpen_amount=sharpen_amount,
+            saturation=saturation,
+            message="滤镜参数计算成功"
+        )
+        
+    except Exception as e:
+        logger.error(f"❌ 计算失败: {str(e)}")
+        return FilterResult(
+            success=False,
+            blur_radius=0,
+            sharpen_amount=0,
+            saturation=1.0,
+            message=f"计算失败: {str(e)}"
+        )
+```
+
+---
+
+#### Step 3: 前端实现（Core 层）
+
+**文件：** `Designer/src/api/jsxApi/inline/smart-filter.ts`
+
+```typescript
+import { evalInlineJSX, JSXResponse } from './utils';
+import { config } from '@/config';
+
+/**
+ * 智能滤镜：混合方案
+ * 1. 本地获取图层信息
+ * 2. 服务器计算最佳参数
+ * 3. 本地应用滤镜
+ */
+export async function applySmartFilter(): Promise<JSXResponse> {
+    try {
+        // 1. 💻 本地获取图层信息
+        const jsx = `
+            try {
+                if (!$.global.JSXUtils.hasDocument()) {
+                    return $.global.JSXUtils.stringify({ error: '没有打开的文档' });
+                }
+                
+                var doc = $.global.JSXUtils.getDocument();
+                var layer = doc.activeLayer;
+                
+                return $.global.JSXUtils.stringify({ 
+                    success: true,
+                    layerId: layer.id,
+                    layerName: layer.name
+                });
+            } catch (error) {
+                return $.global.JSXUtils.stringify({ error: error.toString() });
+            }
+        `;
+        
+        const layerResult = await evalInlineJSX(jsx);
+        
+        if (layerResult.error || !layerResult.success) {
+            return layerResult;
+        }
+        
+        // 2. 🌐 发送到服务器计算（核心算法）
+        const response = await fetch(`${config.apiBaseUrl}/jsx_demo/calculate-filter`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': 'demo_key_123'  // 🔐 API Key
+            },
+            body: JSON.stringify({
+                layer_id: layerResult.layerId,
+                image_data: ''  // 可选：发送图层预览
+            })
+        });
+        
+        if (!response.ok) {
+            return { error: '服务器错误' };
+        }
+        
+        const filterResult = await response.json();
+        
+        if (!filterResult.success) {
+            return { error: filterResult.message };
+        }
+        
+        // 3. 💻 本地应用滤镜参数
+        const { blur_radius, sharpen_amount, saturation } = filterResult;
+        
+        const applyJsx = `
+            try {
+                var doc = $.global.JSXUtils.getDocument();
+                var layer = doc.activeLayer;
+                
+                // 应用服务器计算的滤镜参数
+                // 高斯模糊
+                layer.applyGaussianBlur(${blur_radius});
+                
+                // 锐化
+                layer.applySharpen();
+                
+                return $.global.JSXUtils.stringify({ 
+                    success: true,
+                    message: '智能滤镜应用成功'
+                });
+            } catch (error) {
+                return $.global.JSXUtils.stringify({ error: error.toString() });
+            }
+        `;
+        
+        return evalInlineJSX(applyJsx);
+        
+    } catch (error) {
+        return { error: String(error) };
+    }
+}
+```
+
+---
+
+#### Step 4: UI 界面（Core 层）
+
+**文件：** `Designer/src/view/Home.vue`
+
+```vue
+<template>
+  <a-button @click="handleSmartFilter">智能滤镜</a-button>
+</template>
+
+<script setup lang="ts">
+import { applySmartFilter } from '@/api/jsxApi/inline/smart-filter';
+import { Message } from '@arco-design/web-vue';
+
+const handleSmartFilter = async () => {
+  try {
+    Message.loading('正在计算最佳滤镜参数...');
+    
+    const res = await applySmartFilter();
+    
+    if (res && res.success) {
+      Message.success(res.message);
+    } else {
+      Message.error(res?.error || '执行失败');
+    }
+  } catch (e: any) {
+    Message.error('调用失败: ' + e.message);
+  }
+};
+</script>
+```
+
+---
+
+#### Step 5: 部署新功能
+
+```bash
+# 1. 构建 Core
+cd Designer
+npm run build:core
+
+# 2. 发布新版本（使用自动部署脚本）
+cd ..
+python auto_deploy_core.py
+
+# 3. 用户登录后会自动下载新版本
+```
+
+---
+
+## 🔐 API Key 管理
+
+### 添加新的 API Key
+
+**文件：** `Server/app/core/api_keys.py`
+
+```python
+VALID_KEYS: Dict[str, dict] = {
+    "demo_key_123": {
+        "name": "测试密钥",
+        "permissions": ["calculate", "filter"],  # 添加权限
+        "rate_limit": 100
+    },
+    "customer_abc_456": {  # 新客户
+        "name": "客户 A",
+        "permissions": ["calculate"],
+        "rate_limit": 200
+    }
+}
+```
+
+### 权限检查
+
+```python
+@router.post("/calculate-filter")
+async def calculate_filter(request, x_api_key: Optional[str] = Header(None)):
+    # 验证 Key
+    if not validate_api_key(x_api_key):
+        raise HTTPException(403, "无效的 API Key")
+    
+    # 检查权限
+    if not APIKeyManager.check_permission(x_api_key, "filter"):
+        raise HTTPException(403, "没有滤镜功能权限")
+    
+    # 继续处理...
+```
+
+---
+
+## 📊 日志监控
+
+所有请求都会自动记录：
+
+```
+============================================================
+📥 收到滤镜计算请求
+   图层ID: Layer_123
+   API Key: demo_key_123
+============================================================
+✅ API Key 验证通过 | 名称: 测试密钥 | 权限: ['calculate', 'filter']
+🔒 开始执行核心算法...
+✅ 计算完成: blur=2.3, sharpen=0.7
+============================================================
+```
+
+---
+
+## 🚀 扩展方向
+
+### 1. AI 功能
+```python
+# Server 端
+@router.post("/ai-enhance")
+async def ai_enhance(image: str, x_api_key: str):
+    # 调用 TensorFlow/PyTorch 模型
+    result = ai_model.predict(image)
+    return result
+```
+
+### 2. 批量处理
+```python
+@router.post("/batch-process")
+async def batch_process(layers: List[str], x_api_key: str):
+    results = []
+    for layer_id in layers:
+        result = process_layer(layer_id)
+        results.append(result)
+    return results
+```
+
+### 3. 数据分析
+```python
+@router.post("/analyze-design")
+async def analyze_design(doc_info: dict, x_api_key: str):
+    # 分析设计质量、配色方案等
+    analysis = analyze_composition(doc_info)
+    return analysis
+```
+
+### 4. 实时协作
+```python
+@router.websocket("/ws/collaborate")
+async def collaborate(websocket: WebSocket, x_api_key: str):
+    # WebSocket 实时同步
+    await websocket.accept()
+    # 多用户协作编辑
+```
+
+---
+
+## 🛡️ 安全最佳实践
+
+### ✅ 已实现
+- API Key 鉴权
+- 输入验证
+- 详细日志
+- 核心算法保护
+
+### ⚠️ 生产环境建议
+- 启用 HTTPS
+- 添加限流（Rate Limiting）
+- IP 白名单
+- 定期更换 API Key
+- 数据库存储 Key（而非配置文件）
+
+---
+
+## 📚 开发流程总结
+
+```mermaid
+graph TD
+    A[设计新功能] --> B[后端实现核心算法]
+    B --> C[前端调用 API]
+    C --> D[UI 界面集成]
+    D --> E[测试]
+    E --> F[构建 Core]
+    F --> G[自动部署]
+    G --> H[用户自动更新]
+```
+
+---
+
+## 🎯 框架优势
+
+| 特性 | 传统方案 | 本框架 |
+|------|---------|--------|
+| 核心算法保护 | ❌ 暴露在前端 | ✅ 服务器端执行 |
+| 动态更新 | ❌ 需重装插件 | ✅ 自动下载更新 |
+| 安全鉴权 | ❌ 无验证 | ✅ API Key + 日志 |
+| 可扩展性 | ⚠️ 受限 | ✅ 易于添加功能 |
+| 开发效率 | ⚠️ 中等 | ✅ 模板化开发 |
+
+---
+
+## 🎉 总结
+
+这个框架提供了：
+1. **完整的三层架构**（Shell → Core → Server）
+2. **安全的算法保护**（服务器端计算）
+3. **灵活的更新机制**（动态加载 Core）
+4. **标准的开发模式**（模板化添加功能）
+5. **完善的监控日志**（追踪所有请求）
+
+**适用场景：**
+- Adobe CEP 插件开发
+- 需要保护核心算法的应用
+- 需要频繁更新的软件
+- 需要鉴权和监控的服务
+
+---
+
+**现在你可以基于这个框架快速开发新功能了！** 🚀
+