# 07-服务器发布与演示包实施方案

版本：0.1
日期：2026-06-28

## 1. 目标

将虚拟控制器网站、GRL 规范测试程序和最新测试证据打包发布到 HTTPS 服务器，使用户可以通过浏览器演示虚拟控制器的全部功能。

发布目标：

```text
https://82.156.24.101:8095/
```

端口 `8095` 已作为演示端口使用。本文档不记录服务器密码，部署凭据由部署人员本地管理。

## 2. 演示范围

服务器演示必须覆盖以下功能：

| 功能 | 演示来源 |
| --- | --- |
| GRL 程序加载 | 19 个 `spec-programs` 程序。 |
| 语法解析和语义编译 | 每个程序的 `compile.json`。 |
| 虚拟控制器状态机 | Runtime 程序的 `controller.json`。 |
| motion queue | Runtime 程序的 `motion-queue.json`。 |
| 轨迹摘要 | Runtime 程序的 `trajectory.json`。 |
| IO、wait、pulse | `W2_60_IOWaitPulse` 和 `W2_E50_RuntimeTimeout`。 |
| 流程控制和调用 | `W2_70_ControlFlow`、`W2_80_ProcFuncCall`。 |
| 异常和报警 | `W2_90_ExceptionAlarm`、`W2_E50_RuntimeTimeout`。 |
| 静态错误诊断 | `W2_E10`、`W2_E20`、`W2_E30`、`W2_E40`。 |
| 三品牌后处理 | `W2_P10`、`W2_P20`、`W2_P30` 的 `post-report.json`。 |
| 导入回读 | `roundtrip.json`。 |
| 页面截图 | `virtual-controller-desktop.png`、`virtual-controller-mobile.png`。 |

## 3. 发布包结构

标准发布包命名：

```text
kdl-olp-demo-YYYYMMDD-HHMMSS-<job_id>.zip
```

解压后目录：

```text
kdl-olp-demo/
  index.html
  demo-manifest.json
  README.md
  app/
    virtual-controller.html
    virtual-controller.css
    virtual-controller.js
  spec-programs/
    manifest.json
    runtime/
    static/
    error/
    post/
  test-results/
    abb120-spec/
      <job_id>/
        job.json
        manifest.json
        report.json
        report.html
        programs/
    virtual-controller/
      evidence.json
      virtual-controller-desktop.png
      virtual-controller-mobile.png
  docs/
    GRL功能语法逻辑与程序创建使用手册.docx
    通用机器人离线编程系统测试文档.docx
```

## 4. demo-manifest.json 字段

`demo-manifest.json` 是远程页面和验收脚本的入口文件，字段必须稳定。

```json
{
  "release_id": "20260628-112000-W2-JOB-...",
  "generated_at": "2026-06-28T03:20:00.000Z",
  "suite_id": "working2-abb120-spec",
  "job_id": "W2-JOB-...",
  "program_count": 19,
  "runtime_programs": 12,
  "static_programs": 4,
  "post_programs": 3,
  "entry": "app/virtual-controller.html",
  "report_json": "test-results/abb120-spec/<job_id>/report.json",
  "report_html": "test-results/abb120-spec/<job_id>/report.html",
  "program_manifest": "spec-programs/manifest.json",
  "screenshots": {
    "desktop": "test-results/virtual-controller/virtual-controller-desktop.png",
    "mobile": "test-results/virtual-controller/virtual-controller-mobile.png"
  }
}
```

## 5. 本地发布前检查

发布前必须执行：

```powershell
cd E:\Work\kdl_work
npm run typecheck
npm test
npm run suite:abb120-spec
npm run verify:virtual-controller
```

预期：

1. TypeScript 无错误。
2. Vitest 全量通过。
3. `suite:abb120-spec` 生成新 `W2-JOB-*`。
4. `verify:virtual-controller` 生成桌面和移动截图。
5. `report.json` 中 `summary.fail` 为 `0`。

## 6. 服务器目录规范

推荐服务器目录：

```text
/opt/kdl-olp-demo/8095/
  releases/
    <release_id>/
  current -> releases/<release_id>
  previous -> releases/<previous_release_id>
```

发布时只切换 `current`，不要直接覆盖正在服务的目录。

## 7. 上传和发布步骤

1. 本地生成演示包 zip。
2. 上传 zip 到服务器临时目录。
3. 在服务器创建 release 目录。
4. 解压 zip 到 release 目录。
5. 检查 `index.html`、`demo-manifest.json` 和 `app/virtual-controller.html` 是否存在。
6. 将 `previous` 指向旧 `current`。
7. 将 `current` 指向新 release。
8. 重新加载或确认 HTTPS 服务读取 `current`。
9. 执行远程 smoke test。

## 8. 远程 smoke test

```powershell
$base = "https://82.156.24.101:8095"
curl.exe -k "$base/"
curl.exe -k "$base/demo-manifest.json"
curl.exe -k "$base/spec-programs/manifest.json"
curl.exe -k "$base/app/virtual-controller.html"
curl.exe -k "$base/test-results/abb120-spec/<job_id>/report.json"
```

检查项：

| URL | 预期 |
| --- | --- |
| `/` | 返回首页 HTML。 |
| `/demo-manifest.json` | `program_count` 为 19。 |
| `/spec-programs/manifest.json` | 包含 19 个 programs。 |
| `/app/virtual-controller.html` | 返回虚拟控制器页面。 |
| `/test-results/abb120-spec/<job_id>/report.json` | `summary.fail` 为 0。 |
| `/test-results/virtual-controller/virtual-controller-desktop.png` | 返回 PNG。 |
| `/test-results/virtual-controller/virtual-controller-mobile.png` | 返回 PNG。 |

## 9. 人工演示脚本

浏览器打开：

```text
https://82.156.24.101:8095/
```

演示顺序：

1. 打开首页，说明当前 release、job_id、程序数量。
2. 打开虚拟控制器页面。
3. 展示 Runtime 程序列表，重点选择：
   - `W2_00_MinimalModule`
   - `W2_30_MotionAllTypes`
   - `W2_60_IOWaitPulse`
   - `W2_99_FullSpecExample`
4. 展示 trace、motion queue、IO image 和 diagnostics。
5. 打开 `report.html`，说明 19 个程序覆盖章节 4 到 25。
6. 打开截图，说明桌面和移动端 UI 已验证。
7. 打开 Word 手册和测试文档，说明使用和测试结论。

## 10. 回滚

若远程验证失败：

1. 保留失败 release，不删除，便于排查。
2. 将 `current` 指回 `previous`。
3. 重新执行 smoke test。
4. 在 `working2/03-推进台账.md` 记录：
   - 失败 release_id
   - 失败原因
   - 回滚到哪个 release_id
   - 后续修复任务

## 11. 自动化脚本

已新增脚本：

```text
kdl-wasm/web/scripts/build-demo-package.mjs
kdl-wasm/web/scripts/verify-demo-package.mjs
kdl-wasm/web/scripts/deploy-demo-package.ps1
```

脚本职责：

| 脚本 | 职责 |
| --- | --- |
| `build-demo-package.mjs` | 收集 app、spec-programs、latest job、screenshots、docs，生成 demo manifest 和 zip。 |
| `verify-demo-package.mjs` | 解压 zip，检查 19 个程序、report fail=0、图片和文档存在。 |
| `deploy-demo-package.ps1` | 上传 zip、远程解压、切换 current、执行 smoke test。 |

当前发布 release：

```text
20260628-120601-W2-JOB-20260628024709-51484d62
```

服务器当前状态：

| 项 | 值 |
| --- | --- |
| current | `/opt/kdl-olp-demo/8095/releases/20260628-120601-W2-JOB-20260628024709-51484d62` |
| previous | `/opt/kdl-olp-demo/8095/releases/20260628-120357-W2-JOB-20260628024709-51484d62` |
| HTTPS smoke test | 通过，关键 URL 返回 200，`program_count=19`，`summary.fail=0`。 |