From 9cb489761605c37697a09fca2f68212dae84ce13 Mon Sep 17 00:00:00 2001 From: TuringLambdaAI Date: Fri, 23 Oct 2026 15:56:59 +0800 Subject: [PATCH] docs: align GTK interaction acceptance with the current session and rights model --- ACCEPTANCE.md | 6 +- docs/README.md | 2 + docs/ux-acceptance.md | 160 +++++++++++++----------------------- docs/ux-acceptance.zh-CN.md | 45 ++++++++++ 4 files changed, 107 insertions(+), 106 deletions(-) create mode 100644 docs/ux-acceptance.zh-CN.md diff --git a/ACCEPTANCE.md b/ACCEPTANCE.md index 60b3ee7..d4a40a5 100644 --- a/ACCEPTANCE.md +++ b/ACCEPTANCE.md @@ -46,11 +46,13 @@ gptp-studio --simulator - [ ] License 页显示本机 Installation ID（`ins_` + 32 位十六进制），可选中复制，重启后不变； - [ ] Start Trial 后档位变为 trial，剩余天数在 1–14 内；试用期间引擎控制/导出可用； - [ ] 系统时钟回拨超过 5 分钟后试用判定失效（免费档），不崩溃； -- [ ] 试用到期后回到 free，引擎控制/导出重新被拒并给出 Pro 提示； +- [ ] 试用到期后回到 free；原始抓包导出与 Wireshark 留存回放仍免费。付费报告等受限动作按当前 PRICING 拒绝并解释，不将所有导出一概加墙； - [ ] 激活一份有效 `.permit.json` 后档位变为 Pro，detail 显示 subject 与 updates_through；激活绑定其他 Installation ID 的凭据被拒绝并提示； - [ ] Deactivate 后回到 free，`~/.gptp-studio/entitlement.permit.json` 被删除； - [ ] 「检查更新…」在有新版本的 feed 上给出同意对话框，全程错误文案可复制； -- [ ] Pro 永久授权在 `updates_through` 截止日当天仍可下载官方更新，次日起拒绝出网并说明续购；Free/试用不受限。 +- [ ] Pro 永久使用不因维护窗结束失效；候选版本经签名认证的 `published_at` 在 `updates_through` 之前/恰好等于时符合更新资格，之后才拒绝该候选并解释续购。在窗内发布的版本即使今天已经过窗仍符合资格；固定 UTC 边界与缺失发行时间的拒绝证据独立记录。Free/试用更新规则按当前产品契约。 + +具体键盘、焦点、错误恢复与双语界面场景见 [GTK 交互验收](docs/ux-acceptance.zh-CN.md) / [English](docs/ux-acceptance.md)。清单更新不表示这些运行场景已经通过。 ## 3. 官方包 diff --git a/docs/README.md b/docs/README.md index df8e8c0..9285530 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,8 @@ ## Maintain the product +- [GTK interaction qualification](ux-acceptance.md) · [中文](ux-acceptance.zh-CN.md): actual native navigation, session/packet input, failure recovery and evidence; supplements [ACCEPTANCE](../ACCEPTANCE.md), with no runtime pass implied. + Read [AGENTS](../AGENTS.md) and its existing implementation issue/plan before changing behavior. The technical contracts linked there remain canonical. [PRICING](../PRICING.md) / [中文](../PRICING.zh-CN.md) own commercial implementation decisions, not a live offer. Historical design/roadmap documents are not proof a platform, hosted service or payment flow has shipped. Keep customer navigation on the public user path. Public English/Chinese guides carry matching promises. Some deep technical or historical documents remain in one language; their presence is not a claim that the whole archive is translated. diff --git a/docs/ux-acceptance.md b/docs/ux-acceptance.md index dd72265..b35bb99 100644 --- a/docs/ux-acceptance.md +++ b/docs/ux-acceptance.md @@ -1,104 +1,56 @@ -# UX / 调试工作流验收清单 - -本清单只针对 Linux 产品平台。协议解码、linuxptp 引擎和抓包核心由自动化测试覆盖；WebKitGTK 交互项需要 Ubuntu 22.04 / 24.04 真机人工走查。 - -## 1. 模拟器快速验收 - -```bash -gptp-studio --simulator -``` - -- [ ] 应用正常打开，无初始化错误 toast。 -- [ ] 默认角色为「被动监听」，避免启动后意外参与 BMCA。 -- [ ] 切换到 GrandMaster 后，预览里 `gmCapable=1`、`slaveOnly=0`；切回 Slave/Listener 后恢复对应约束。 -- [ ] 顶部状态栏显示 timing capability 徽章。 -- [ ] 「同步总览」曲线显示 offset 告警阈值虚线。 -- [ ] 显示最近样本 RMS、Mean、Peak-to-peak、Max |offset|。 -- [ ] 统计值随模拟器数据持续更新，不阻塞曲线刷新。 -- [ ] 「复制调试快照」能复制 Linux 平台、网卡、PHC、当前同步状态和 `ptp4l.conf`。 -- [ ] 「开始会话」能启动当前模拟角色；「停止全部」结束会话。 - -## 2. 链路与网卡 - -### 支持 PTP Hardware Timestamp 的网卡 - -- [ ] Timing Capability 卡片显示网卡、驱动、链路和 timestamp path。 -- [ ] 同时检测到 TX/RX hardware timestamp 与 PHC 时显示真实 timing-capable 状态。 -- [ ] link DOWN 只显示 WARN / VERIFY，不误判为结构性 FAIL。 -- [ ] 仅 hardware timestamp、无 PHC 时明确显示 `NO PHC`。 -- [ ] 仅软件时间戳时显示 `SW ONLY`，并明确只建议协议调试，不用于 ns/µs 精度判断。 -- [ ] 显示 `ptp4l / phc2sys / pmc` 安装状态以及 root / file capabilities / `sudo -n` / direct-best-effort 路径。 -- [ ] 缺少 linuxptp 核心工具时，即使网卡具备 HW+PHC，也不会显示为完全 READY。 -- [ ] 缺少 `ethtool` / `ip` 时明确提示能力检测不完整。 -- [ ] 点击「重新扫描」后 Timing Capability、工具状态与表格同步刷新。 - -## 3. 真实调试会话 - -- [ ] 选择真实引擎后，配置页出现当前网卡 timing path 提示。 -- [ ] 切换网卡后资格结果立即更新。 -- [ ] 软件时间戳网卡不会被描述为 instrument-grade / timing-ready。 -- [ ] GM / Slave 点击「开始会话」时由 Supervisor 再次执行 Preflight，不能绕过后端保护。 -- [ ] Listener 点击「开始会话」时只启动抓包，不为了监听改变本机时钟角色。 -- [ ] 「停止全部」同时停止抓包和引擎。 -- [ ] 从 Listener 切换到 GM 后立即点击开始，不会因参数合并竞态带着 `slaveOnly=1` 启动。 -- [ ] 新配置被 Preflight 拒绝时，不会误停已经运行的健康会话。 - -## 4. 报文分析工作流 - -- [ ] 类型过滤可分别查看 Sync / Follow_Up / Announce / PDelay_* / Signalling。 -- [ ] 搜索框可按 Seq、Domain、sourcePortIdentity、MAC 等文本过滤。 -- [ ] `/` 在报文页且焦点不在输入控件时聚焦搜索框。 -- [ ] 点击「冻结视图」后表格停止跳动，但底层抓包继续。 -- [ ] 冻结状态显示 `FROZEN`；恢复后切回 `LIVE`。 -- [ ] Space 在报文页且焦点不在输入控件时切换冻结/恢复。 -- [ ] 与当前配置 Domain 不同的报文只做醒目标记，不直接判定为错误。 -- [ ] 报文健康条显示样本速率、Domain 数量、时钟源数量、序号异常和 two-step 配对情况。 -- [ ] sequenceId 重复/跳号有醒目标记，但提示抓包窗口边界/过滤也可能造成假阳性。 -- [ ] two-step Sync 缺对应 Follow_Up 时给观察提示，不武断判定 DUT 故障。 -- [ ] 打开报文详情后对应行有选中态；Esc 可以关闭详情。 -- [ ] ↑/↓ 或 J/K 可以在当前可见报文中上下浏览。 -- [ ] 报文摘要与 Raw Hex 均可一键复制。 - -## 5. Linux 快捷键与复制 - -- [ ] Ctrl + 1：同步总览 -- [ ] Ctrl + 2：链路与网卡 -- [ ] Ctrl + 3：角色与配置 -- [ ] Ctrl + 4：参考源 -- [ ] Ctrl + 5：报文分析 -- [ ] Ctrl + 6：运行与日志 -- [ ] 输入框/下拉框获得焦点时，Space、J/K 等快捷键不会抢占正常输入。 -- [ ] `ptp4l.conf` 可以一键复制。 -- [ ] 日志页可以复制当前过滤后的可见日志。 - -## 6. Doctor / Preflight 一致性 - -- [ ] `gptp-studio --doctor` 与 GUI Preflight 对同一 NIC 的结构性判断一致。 -- [ ] `--doctor-json` 默认不包含 MAC/IP。 -- [ ] READY 不显示任何“已校准精度”表述。 -- [ ] GM + system reference 与 GM + externally managed PHC 的资格结果独立。 -- [ ] `ptp4l` / `phc2sys` file capabilities 分开识别。 - -## 7. 回归检查 - -- [ ] 角色切换、参数合并和 `ptp4l.conf` 预览正常。 -- [ ] 场景预设应用后，角色、网卡、参数和隐藏约束一致。 -- [ ] pcap/pcapng 导入正常。 -- [ ] 实时抓包开始/停止正常。 -- [ ] pcap 导出 Pro gate 行为未改变。 -- [ ] 日志过滤和导出正常。 -- [ ] 场景预设保存/应用/删除正常。 -- [ ] Free / Trial / Pro 显示与原逻辑一致。 -- [ ] 中英文切换不会导致新增 UI 报错。 - -## 8. 自动化回归 - -```bash -raco make main.rkt -raco test tests/ -racket main.rkt --selfcheck -racket main.rkt --doctor-json | python3 -m json.tool >/dev/null -bash scripts/package-deb.sh 1.0.0 v1.0.0-local -``` - -CI 必须在 Ubuntu 22.04 和 Ubuntu 24.04 同时通过。 +# GTK interaction qualification + +**English** · [简体中文](ux-acceptance.zh-CN.md) + +Revision: 2026-10-23. This is the interaction supplement to the existing +[product acceptance guide](../ACCEPTANCE.md) and executable +[`rivet-acceptance.rktd`](../rivet-acceptance.rktd), not a second release gate. +All items below require fresh evidence; publishing this checklist does not +mark them passed. Follow [issue #40](https://github.com/turinglambdaai/gptp-studio/issues/40). + +## Actual interface and ownership + +The product is Linux-only, with a Rivet/GTK4 native host. The current six pages +are Engine, Qualification, Packets, Logs, GM Tuning and License & Reports. +The native-package baseline is Ubuntu 24.04 / GTK >= 4.10, as specified in +ACCEPTANCE. An AppImage needs its own host compatibility evidence; bundled +libraries do not establish support for every older distribution. Do not use +the retired WebKitGTK page list, build commands or unverified Ctrl+1…6 bindings. + +The primary user loop is select a simulator/real target and interface, inspect +readiness, explicitly start a session, inspect timing/packets, stop the owned +work and export evidence. Passive listener is the initial role. Protocol and +preflight policy remain in the shared backend; the host owns native input, +focus, accessible controls and honest state presentation. + +## One scenario contract + +| Initial state / action | Required visible result and recovery | +| --- | --- | +| Fresh package, start simulator | Mode and passive role are identifiable; startup progresses to useful status or an actionable failure. No real clock-role process starts implicitly. | +| Select real mode / interface / role | The selected target, actual running session and preflight result are distinguishable. Pending edits are not presented as applied configuration. | +| Start is rejected | Name the failed prerequisite and next diagnostic action; preserve an existing healthy session. READY is capability detection, never accuracy calibration. | +| Session is running | Curves, packet details and logs identify their source. A simulator trace is never labelled physical-NIC evidence. | +| Stop engine / stop capture | Show their independent outcomes and any still-running owned process. Do not label one control Stop All until that behavior exists and is verified. | +| Packet selection / filter / detail | Selection and detail identify the same packet; native keyboard operation and return focus are defined. Preserve selection or explain its invalidation during live refresh. | +| Export / permission failure | Raw capture export and retained Wireshark replay remain free; paid reports follow current PRICING. Cancellation/failure does not announce a completed export or leave a misleading final file. | +| Change language / window / text scale | Primary page names, mode/role controls, status/error and recovery actions remain usable. Shared semantics do not require identical typography or fixed dimensions. | + +Use existing widget names and documented native activation. Any additional +keyboard shortcut, focus rule or state representation remains a target until +implemented and exercised through native input. Do not invent automation IDs +or substitute CLI output for the GUI interaction. + +## Evidence to record + +- [ ] Source/dependency SHAs, package digest/format, distro, architecture, GTK version, display backend, language and scale. +- [ ] Clean simulator start → input → visible result → stop → export, with disposable data and native accessibility/keyboard evidence. +- [ ] Missing dependency, failed startup, denied start, failed export and recovery; preserve user context and any existing healthy session. +- [ ] Keyboard reachability, names/roles, focus return and readable layouts at declared supported window sizes and enlarged text; new screenshots of the actual artifact. +- [ ] Free export and report refusal/import/recovery follow current policy; distinguish authenticated release-time update eligibility from the current date. + +Physical NIC/PHC, hardware timestamps, actual privileges, reference clocks and +timing accuracy require the separate [hardware qualification](hardware-qualification.md) +and [real-engine setup](linux-real-engine-setup.md) evidence. Run real clock-role +changes only on the explicitly selected test setup. Do not count simulator, +build, queued, skipped or unrun checks as those results. diff --git a/docs/ux-acceptance.zh-CN.md b/docs/ux-acceptance.zh-CN.md new file mode 100644 index 0000000..baba06f --- /dev/null +++ b/docs/ux-acceptance.zh-CN.md @@ -0,0 +1,45 @@ +# GTK 交互验收 + +[English](ux-acceptance.md) · **简体中文** + +版本：2026-10-23。本文件补充既有[产品验收指南](../ACCEPTANCE.md)和可执行的 +[`rivet-acceptance.rktd`](../rivet-acceptance.rktd)，不另造发布门禁。以下各项都需新证据， +清单发布不表示通过。实施沿 [#40](https://github.com/turinglambdaai/gptp-studio/issues/40)。 + +## 当前界面与职责 + +产品只面向 Linux，采用 Rivet/GTK4 原生宿主。当前六页是 Engine、Qualification、 +Packets、Logs、GM Tuning、License & Reports。系统原生包基线为 ACCEPTANCE 中的 +Ubuntu 24.04 / GTK >= 4.10；AppImage 需单独证明宿主兼容，附带依赖不等于所有旧发行版都受支持。 +不再沿用旧 WebKitGTK 页面、构建命令或未验证的 Ctrl+1…6 绑定。 + +主任务是选择模拟/真实目标与网卡、查看资格、明确启动会话、观察时序/报文、停止所属任务并导出证据。 +初始角色是被动监听。共享后端负责协议与 preflight 规则，宿主负责原生输入、焦点、辅助功能与真实状态呈现。 + +## 统一场景契约 + +| 初始状态 / 动作 | 必需的可见结果与恢复 | +| --- | --- | +| 全新包启动模拟器 | 模式与被动角色可辨认；进入可用状态或给出可操作错误，不隐式启动真实时钟角色进程。 | +| 选择真实模式 / 网卡 / 角色 | 区分选择目标、实际运行会话和资格结果，待提交配置不能显示为已生效。 | +| 启动被拒 | 说明失败条件与下一诊断动作，保留已运行的健康会话；READY 只是能力检测，不是精度校准。 | +| 会话运行 | 曲线、报文与日志标识来源，模拟轨迹不能标成真实网卡证据。 | +| 停止引擎 / 抓包 | 分别展示结果与仍在运行的所属进程；未实现并验证前不能将其中一个操作称作停止全部。 | +| 选择 / 过滤 / 查看报文 | 选择与详情指向同一报文；定义原生键盘操作和焦点返回；刷新时保留选择或解释失效。 | +| 导出 / 权限失败 | 原始抓包导出、Wireshark 留存回放免费；付费报告遵循当前 PRICING。取消/失败不能宣告完成或留下误导的最终文件。 | +| 切换语言 / 调整窗口与文字 | 主页名、模式/角色、状态/错误与恢复动作可用；语义一致不要求固定字号或像素。 | + +使用已有控件名和原生激活方式。新增快捷键、焦点规则或状态呈现，在实现并通过原生输入验证前仍是目标； +不得虚构 automation ID 或用 CLI 输出代替 GUI 交互。 + +## 必须记录的证据 + +- [ ] 源码/依赖 SHA、包摘要/格式、发行版、架构、GTK、显示后端、语言与缩放。 +- [ ] 临时数据下，全新包完成模拟器启动→输入→结果→停止→导出，附原生辅助功能与键盘证据。 +- [ ] 缺依赖、启动失败、拒绝启动、导出失败与恢复；保留用户上下文和现有健康会话。 +- [ ] 声明支持窗口/大文字下的键盘可达、名称/角色、焦点返回与可读性；实际产物的新截图。 +- [ ] 免费导出、报告拒绝/凭据导入/恢复符合当前政策；更新资格使用已认证发行时间，不能换成当前日期判断。 + +物理 NIC/PHC、硬件时间戳、真实权限、参考时钟与时序精度需另有[硬件验收](hardware-qualification.md) +及[真实引擎配置](linux-real-engine-setup.md)证据。真实时钟角色变更只在明确选定的测试环境执行； +模拟器、构建、排队、跳过或未执行均不算上述实机结果。