KDL_WORK/working2/07-服务器发布与演示包实施方案.md

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

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

1. 目标

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

发布目标：

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. 发布包结构

标准发布包命名：

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

解压后目录：

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 是远程页面和验收脚本的入口文件，字段必须稳定。

{
  "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. 本地发布前检查

发布前必须执行：

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. 服务器目录规范

推荐服务器目录：

/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

$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. 人工演示脚本

浏览器打开：

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. 自动化脚本

已新增脚本：

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：

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。