# 混合架构快速开发模板

## 🚀 5 分钟添加新功能

### 模板代码

复制下面的模板，替换 `YOUR_FEATURE` 为你的功能名称。

---

## 📝 Step 1: 后端 API（3 层）

**文件：** `Server/app/api/v1/jsx_demo.py`

```python
# ==================== 请求/响应模型 ====================
class YourFeatureRequest(BaseModel):
    """你的功能请求"""
    param1: str
    param2: int

class YourFeatureResult(BaseModel):
    """你的功能结果"""
    success: bool
    result_data: dict
    message: str

# ==================== API 端点 ====================
@router.post("/your-feature", response_model=YourFeatureResult)
async def your_feature_endpoint(
    request: YourFeatureRequest,
    x_api_key: Optional[str] = Header(None)
):
    """
    🔒 服务器端核心计算
    客户端只能拿到结果，看不到算法
    """
    
    # 📝 日志：记录请求
    logger.info("="*60)
    logger.info("📥 收到请求: YOUR_FEATURE")
    logger.info(f"   参数1: {request.param1}")
    logger.info(f"   参数2: {request.param2}")
    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")
    
    key_info = get_key_info(x_api_key)
    logger.info(f"✅ API Key 验证通过 | 名称: {key_info['name']}")
    
    try:
        # 🛡️ 输入验证
        logger.info("🛡️ 验证输入参数...")
        if not request.param1 or request.param2 < 0:
            logger.warning("❌ 参数验证失败")
            return YourFeatureResult(
                success=False,
                result_data={},
                message="参数无效"
            )
        logger.info("✅ 参数验证通过")
        
        # 🔒 核心算法（客户端看不到）
        logger.info("🔒 开始执行核心算法...")
        
        # ===== 在这里写你的核心逻辑 =====
        result = {
            "output1": f"处理结果: {request.param1}",
            "output2": request.param2 * 2
        }
        # ================================
        
        logger.info(f"✅ 计算完成: {result}")
        
        # 📤 返回结果
        logger.info("="*60)
        return YourFeatureResult(
            success=True,
            result_data=result,
            message="处理成功"
        )
        
    except Exception as e:
        logger.error(f"❌ 处理失败: {str(e)}")
        return YourFeatureResult(
            success=False,
            result_data={},
            message=f"处理失败: {str(e)}"
        )
```

---

## 📝 Step 2: 前端 API（2 层）

**文件：** `Designer/src/api/jsxApi/inline/your-feature.ts`

```typescript
/**
 * YOUR_FEATURE 功能
 * 混合方案：本地执行 + 服务器计算
 */

import { evalInlineJSX, JSXResponse } from './utils';
import { config } from '@/config';

export async function yourFeatureFunction(
    param1: string,
    param2: number
): Promise<JSXResponse> {
    try {
        // 1. 💻 【可选】本地获取 PS 数据
        const getDataJsx = `
            try {
                if (!$.global.JSXUtils.hasDocument()) {
                    return $.global.JSXUtils.stringify({ error: '没有打开的文档' });
                }
                
                var doc = $.global.JSXUtils.getDocument();
                
                // 获取你需要的数据
                var layerName = doc.activeLayer ? doc.activeLayer.name : '';
                
                return $.global.JSXUtils.stringify({ 
                    success: true,
                    layerName: layerName
                });
            } catch (error) {
                return $.global.JSXUtils.stringify({ error: error.toString() });
            }
        `;
        
        const psData = await evalInlineJSX(getDataJsx);
        
        if (psData.error) {
            return psData;
        }
        
        // 2. 🌐 发送到服务器计算（核心算法）
        const response = await fetch(`${config.apiBaseUrl}/jsx_demo/your-feature`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': 'demo_key_123'  // 🔐 API Key
            },
            body: JSON.stringify({
                param1: param1,
                param2: param2
            })
        });
        
        if (!response.ok) {
            return { error: '服务器错误' };
        }
        
        const serverResult = await response.json();
        
        if (!serverResult.success) {
            return { error: serverResult.message };
        }
        
        // 3. 💻 【可选】使用服务器结果执行 PS 操作
        const { output1, output2 } = serverResult.result_data;
        
        const applyJsx = `
            try {
                var doc = $.global.JSXUtils.getDocument();
                
                // 使用服务器计算的结果
                // 示例：创建文本图层显示结果
                var textLayer = doc.artLayers.add();
                textLayer.kind = LayerKind.TEXT;
                textLayer.name = "${output1}";
                
                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 3: UI 界面（2 层）

**文件：** `Designer/src/view/Home.vue`

```vue
<template>
  <a-button type="primary" @click="handleYourFeature">
    你的功能
  </a-button>
</template>

<script setup lang="ts">
import { yourFeatureFunction } from '@/api/jsxApi/inline/your-feature';
import { Message } from '@arco-design/web-vue';

const handleYourFeature = async () => {
  try {
    Message.loading('处理中...');
    
    // 调用混合 API
    const res = await yourFeatureFunction('测试参数', 100);
    
    if (res && res.success) {
      Message.success(res.message || '操作成功');
    } else {
      Message.error(res?.error || '执行失败');
    }
  } catch (e: any) {
    Message.error('调用失败: ' + e.message);
  }
};
</script>
```

---

## 🔄 开发流程

### 本地测试
```bash
# Terminal 1: 启动后端
cd Server
python -m uvicorn app.main:app --reload

# Terminal 2: 启动前端
cd Designer
npm run dev
```

### 发布新版本
```bash
# 自动构建、打包、发布
python auto_deploy_core.py
```

---

## 📋 检查清单

开发新功能时，确保：

- [ ] 后端添加了 API Key 验证
- [ ] 后端添加了详细日志
- [ ] 后端添加了输入验证
- [ ] 前端使用了正确的 API Key
- [ ] 前端添加了错误处理
- [ ] UI 有加载提示和错误提示
- [ ] 测试了成功和失败的情况
- [ ] 更新了版本号

---

## 🎯 三种常见模式

### 模式 1：纯服务器计算
```
前端输入 → 服务器计算 → 前端显示结果
（不涉及 PS 操作）
```

### 模式 2：服务器计算 + PS 应用
```
前端获取 PS 数据 → 服务器计算 → 前端应用到 PS
（当前示例）
```

### 模式 3：本地执行 + 服务器验证
```
前端执行操作 → 服务器验证权限 → 前端继续
（需要权限控制的操作）
```

---

## 💡 快速参考

### 后端日志模板
```python
logger.info("="*60)
logger.info("📥 收到请求")
logger.info("✅ 验证通过")
logger.info("🔒 开始计算")
logger.info("✅ 计算完成")
logger.info("="*60)
```

### 前端错误处理模板
```typescript
try {
    Message.loading('处理中...');
    const res = await yourFunction();
    if (res?.success) {
        Message.success(res.message);
    } else {
        Message.error(res?.error || '失败');
    }
} catch (e: any) {
    Message.error('调用失败: ' + e.message);
}
```

### JSX 模板
```typescript
const jsx = `
    try {
        if (!$.global.JSXUtils.hasDocument()) {
            return $.global.JSXUtils.stringify({ error: '没有打开的文档' });
        }
        
        var doc = $.global.JSXUtils.getDocument();
        
        // 你的 PS 操作代码
        
        return $.global.JSXUtils.stringify({ 
            success: true,
            message: '成功'
        });
    } catch (error) {
        return $.global.JSXUtils.stringify({ error: error.toString() });
    }
`;

return evalInlineJSX(jsx);
```

---

## 🎉 完成！

现在你可以：
1. 复制模板代码
2. 替换功能名称
3. 填写核心逻辑
4. 测试
5. 发布

**预计开发时间：5-15 分钟/功能** ⚡