# 交付、部署与集成

## 1. 保存 vs 发布（两份数据）

- **保存（Ctrl+S）**：编辑态草稿，不影响线上。内容与上一份不同时把上一份归档为历史版本（AI `page_save` 不归档）。
- **发布**：生成运行态快照；`/view` 观看者始终看**最近一次发布**，草稿可继续编辑。

## 2. 三种交付方式

| 方式 | 产物 | 适用 |
|---|---|---|
| 线上发布 | 公开 `/view` 链接 | 直接分享 / 投屏 / 嵌 iframe |
| 导出工程 JSON | `*.vpproj.json` 纯数据 | 版本管理、脚本/AI 生成、跨环境导入 |
| 二次开发工程包 | Vite+Vue 工程（内置运行时 SDK + 工程数据） | 深度集成自有系统、自行编译托管 |

## 3. 二次开发工程包（编辑器「项目部署 → 导出二次开发工程包」）

```
├─ index.html
├─ src/
│  ├─ main.ts            createVpViewer 挂载
│  ├─ hooks.ts           挂载选项（params/widgets/transformData/onReady/onScript/onBehavior）
│  ├─ examples/          分类示例（基础/数据/事件/窗口/页面）
│  └─ data/project.json  工程数据（可手工替换）
└─ vendor/vp-runtime/    运行时 SDK（.mjs + .css + .d.ts）
```

`pnpm i && pnpm dev`（5173）/ `pnpm build` → `dist/` 纯静态资源（`base:'./'`），任意静态服务器/CDN 可托管。挂载：

```ts
// 工程包不依赖 vjvpsdk 包：vite.config 把 '@vp/sdk' 别名到随包的 vendor/vp-runtime/vp-runtime.mjs
import { createVpViewer, type VpProjectBody } from '@vp/sdk'
import '../vendor/vp-runtime/vp-runtime.css'
import projectData from './data/project.json'   // 导出时注入的完整 body（非精简形态）
import { hooks } from './hooks'
const ctx = createVpViewer('#app', projectData as VpProjectBody, hooks)
```

## 4. iframe 嵌入 + postMessage 喂数

最简集成：`<iframe src="https://<host>/view?project=<工程id>">`。宿主喂数据：工程内建 `postMessage` 连接器（`config.linkId`），宿主页面：

```js
iframe.contentWindow.postMessage({ linkId: 'link_demo', payload: { month: '一月', sales: 16000 } }, '*')
```

字段用 `f_xxx` + `sourceField` 映射外部键（详见 [data.md](../data.md) §7）。需要双向控制则改用 SDK 挂载（`ctx` 通信）。

## 5. 后端部署

- 后端是单文件二进制（Go + PocketBase），默认监听 `http://127.0.0.1:8090`。
- 配置 `vp_config.json`：`title`（产品显示名称，默认「唯杰AI可视化平台」）、`admin`（管理员账号）、`mcp`（见 mcp-and-ai.md）。
- 后端职责：工程存取（草稿/发布快照）、静态托管（编辑器/查看器构建产物）、**平台数据**（PocketBase 动态集合 `vpd_xxx`，编辑器「平台数据」建表，pocketbase 连接器实时订阅）、资源上传、webhook、MCP。
- 纯前端场景（SDK 嵌入 + 静态数据/自有接口）可以**不部署后端**；需要保存/发布/平台数据/MCP 才要后端。