Add ABB120 demo suite and docs

2026-06-28 20:58:18 +08:00
parent 84a5b54195
commit 65187499d6
820 changed files with 215410 additions and 211 deletions
--- a/working2/07-服务器发布与演示包实施方案.md
+++ b/working2/07-服务器发布与演示包实施方案.md
@@ -0,0 +1,238 @@
+# 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`。 |