239 lines
6.6 KiB
Markdown
239 lines
6.6 KiB
Markdown
# 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`。 |
|