# SDK 调用示例

本目录包含完整的 SDK 调用示例，展示了两种不同的集成方式。

## 📁 文件说明

### 完整 Demo（推荐）
- `demo-module.html` - **ES Module 方式完整示例**（推荐）
- `demo-global.html` - **全局脚本方式完整示例**
- `app-global.js` - 全局脚本方式的业务逻辑文件

### 简单示例
- `example-module.html` - ES Module 方式简单示例
- `example-global.html` - 全局脚本方式简单示例

## 🎯 核心设计理念

### 业务逻辑与 SDK 解耦

根目录的 `index.js` 是一个**通用的业务逻辑层**，通过 `initApp(kernel)` 接收外部传入的 kernel 实例，实现了：

✅ **SDK 调用方式无关** - 同一套业务逻辑，适配两种 SDK 引入方式  
✅ **代码复用** - 避免重复编写业务逻辑  
✅ **易于维护** - 业务逻辑集中管理，修改一处即可  

**架构图：**
```
┌─────────────────────────────────────────┐
│         应用层 (HTML)                    │
│  ┌─────────────┐    ┌─────────────┐    │
│  │ ES Module   │    │ 全局脚本     │    │
│  │ 方式引入     │    │ 方式引入     │    │
│  └──────┬──────┘    └──────┬──────┘    │
│         │                  │            │
│         ▼                  ▼            │
│  ┌─────────────────────────────────┐   │
│  │   通用业务逻辑 (index.js)        │   │
│  │   - initApp(kernel)              │   │
│  │   - init()                       │   │
│  │   - getAutoLoadModelList()       │   │
│  │   - getHotspot()                 │   │
│  │   - getProductConfig()           │   │
│  └──────────────┬──────────────────┘   │
│                 │                       │
│                 ▼                       │
│  ┌─────────────────────────────────┐   │
│  │      SDK Kernel                  │   │
│  │   (从外部注入)                    │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

---

## 🚀 快速开始

### 方式 1: ES Module（推荐）

**文件：** `demo-module.html`

```html
<script type="module">
  // 1. 从 CDN 导入 SDK
  import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js';
  
  // 2. 导入业务逻辑
  import { initApp, init, getAutoLoadModelList } from '../index.js';
  
  // 3. 注入 kernel 实例
  initApp(kernel);
  
  // 4. 初始化应用
  await init();
  await getAutoLoadModelList();
</script>
```

**特点：**
- ✅ 现代化模块化开发
- ✅ 直接引用根目录的 `index.js`
- ✅ 支持 async/await
- ✅ 更好的 IDE 智能提示

---

### 方式 2: 全局脚本

**文件：** `demo-global.html` + `app-global.js`

```html
<!-- 1. 引入 SDK -->
<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>

<!-- 2. 引入业务逻辑 -->
<script src="./app-global.js"></script>

<script>
  // 3. 获取 SDK kernel
  var kernel = window.faceSDK.kernel;
  
  // 4. 注入 kernel 实例
  window.AppLogic.initApp(kernel);
  
  // 5. 初始化应用
  (async function() {
    await window.AppLogic.init();
    await window.AppLogic.getAutoLoadModelList();
  })();
</script>
```

**特点：**
- ✅ 兼容所有浏览器
- ✅ 无需构建工具
- ✅ 使用 `app-global.js`（根目录 `index.js` 的全局脚本版本）
- ⚠️ 需要维护两份业务逻辑文件

---

## 📖 业务逻辑 API

### 初始化

```javascript
// 注入 kernel 实例（必须首先调用）
initApp(kernel)

// 初始化 SDK 配置
await init(customConfig?)

// 加载模型列表
await getAutoLoadModelList()
```

### 产品配置

```javascript
// 获取产品配置并应用
await getProductConfig(sku)

// 获取放置区域
await getPlacementZone(sku)
```

### 热点管理

```javascript
// 加载并渲染热点
await getHotspot()
```

### 事件处理

```javascript
// 执行放置区域事件
await getEvent(dropzone_data, sku)

// 执行产品切换事件
await executeEvent2(result)
```

---

## 🎨 完整 Demo 功能

两个完整 demo（`demo-module.html` 和 `demo-global.html`）都包含：

### UI 功能
- ✅ 3D 模型渲染画布
- ✅ 配置面板（产品选择、热点控制）
- ✅ 加载进度显示
- ✅ 点击信息提示

### 交互功能
- ✅ 产品切换
- ✅ 热点加载
- ✅ 模型点击事件
- ✅ 热点点击事件

### 事件监听
```javascript
// 加载进度
kernel.on('model:load:progress', (data) => {
  console.log('进度:', data.progress);
});

// 加载完成
kernel.on('model:loaded', (data) => {
  console.log('模型列表:', data.models);
});

// 模型点击
kernel.on('model:click', (data) => {
  console.log('点击:', data.meshName);
});

// 热点点击
kernel.on('hotspot:click', (event) => {
  console.log('热点:', event.name);
});
```

---

## 🔧 本地运行

### ES Module 方式

```bash
# 需要本地服务器（ES Module 不支持 file:// 协议）
cd examples
npx serve .

# 访问 http://localhost:3000/demo-module.html
```

### 全局脚本方式

```bash
# 可以直接双击打开
# 或使用本地服务器
cd examples
npx serve .

# 访问 http://localhost:3000/demo-global.html
```

---

## 📦 集成到项目

### Vue 3 项目

```vue
<template>
  <canvas ref="canvasRef"></canvas>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js';
import { initApp, init, getAutoLoadModelList } from '@/utils/app-logic.js';

const canvasRef = ref(null);

onMounted(async () => {
  // 注入 kernel
  initApp(kernel);
  
  // 初始化
  await init({ container: canvasRef.value });
  await getAutoLoadModelList();
});
</script>
```

### React 项目

```jsx
import { useEffect, useRef } from 'react';

function ModelViewer() {
  const canvasRef = useRef(null);

  useEffect(() => {
    (async () => {
      // 动态导入 SDK
      const { kernel } = await import('https://sdk.zguiy.com/zt/assets/index.js');
      const { initApp, init, getAutoLoadModelList } = await import('./app-logic.js');
      
      // 注入 kernel
      initApp(kernel);
      
      // 初始化
      await init({ container: canvasRef.current });
      await getAutoLoadModelList();
    })();
  }, []);

  return <canvas ref={canvasRef} />;
}
```

### 原生 HTML

```html
<!DOCTYPE html>
<html>
<head>
  <title>3D 模型展示</title>
</head>
<body>
  <canvas id="renderDom"></canvas>
  
  <script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
  <script src="./app-global.js"></script>
  <script>
    var kernel = window.faceSDK.kernel;
    window.AppLogic.initApp(kernel);
    
    (async function() {
      await window.AppLogic.init();
      await window.AppLogic.getAutoLoadModelList();
    })();
  </script>
</body>
</html>
```

---

## 🔄 业务逻辑文件说明

### 根目录 `index.js` (ES Module 版本)

- 使用 ES6+ 语法
- 支持 `import/export`
- 适用于现代构建工具
- **推荐用于新项目**

### `app-global.js` (全局脚本版本)

- 使用 ES5 语法
- 通过 IIFE 包装
- 暴露到 `window.AppLogic`
- 适用于传统 HTML 页面

**两个文件功能完全相同，只是语法不同。**

---

## ❓ 常见问题

### Q: 为什么需要两个业务逻辑文件？

**A:** 因为 ES Module 和全局脚本的语法不兼容：
- ES Module 使用 `import/export`，不能在全局脚本中使用
- 全局脚本需要通过 `window` 对象暴露 API

如果你的项目只使用一种方式，只需要维护对应的文件即可。

### Q: 如何选择使用哪种方式？

**A:** 
- **现代项目 + 构建工具** → 使用 ES Module (`demo-module.html`)
- **传统 HTML + 无构建工具** → 使用全局脚本 (`demo-global.html`)
- **需要兼容旧浏览器** → 使用全局脚本

### Q: 可以只维护一份业务逻辑吗？

**A:** 可以！有两种方案：
1. **只用 ES Module**：使用构建工具（如 Vite）将 ES Module 转换为全局脚本
2. **只用全局脚本**：所有项目都使用 `app-global.js`

### Q: `initApp(kernel)` 必须调用吗？

**A:** 是的！这是核心设计：
```javascript
// ❌ 错误 - 直接调用会报错
await init();  // Error: 请先调用 initApp(kernel)

// ✅ 正确 - 先注入 kernel
initApp(kernel);
await init();
```

---

## 📚 相关资源

- SDK 文档: https://sdk.zguiy.com/docs
- 后端 API: https://ztserver.zguiy.com
- GitHub: [项目地址]

---

## 📄 许可证

MIT License