# 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 插件开发
- 需要保护核心算法的应用
- 需要频繁更新的软件
- 需要鉴权和监控的服务

---

**现在你可以基于这个框架快速开发新功能了！** 🚀