From 5550efff8872968b8e1ca03f5d1cba36b82081f4 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 3 Aug 2026 12:36:16 +0800 Subject: [PATCH] feat(prototype): add MVP desktop interaction flows --- docs/design/desk-device-settings.html | 357 +++++++++++++++++ docs/design/desk-execution.html | 534 ++++++++++++++++++++++++++ docs/tasks/T-006.md | 77 +++- 3 files changed, 965 insertions(+), 3 deletions(-) create mode 100644 docs/design/desk-device-settings.html create mode 100644 docs/design/desk-execution.html diff --git a/docs/design/desk-device-settings.html b/docs/design/desk-device-settings.html new file mode 100644 index 0000000..8ef445f --- /dev/null +++ b/docs/design/desk-device-settings.html @@ -0,0 +1,357 @@ + + + + + + + cmbuyer 桌面端原型 · 设备与参数 + + + +
PROTOTYPE - 仅供枚举交互，非实现依据；全部是假数据，不执行连接检查或保存真实配置
+
+
cmbuyer 执行器Windows / PySide6 前置原型
+ +
+
+ +
+
+ +
+
+ + + +
+
+
+
+

设备档案

必须显式指定 serial；不自动选择设备

+
+
+ + + 用于本机识别，不上传真实个人信息。 +
+
+ + + USB / WiFi 同时在线时仍只认这里的精确值。 +
+
+ 连接方式 +
+ 这是展示标签，不改变 serial 的唯一身份规则。 +
+
+ + + 原生实现使用文件选择器；此 HTML 不访问本地文件系统。 +
+
+
+ +
+

web 服务与设备身份

设备凭据与管理员会话隔离

+
+
+ + + 仅为原型假地址；本页不会向该地址发请求。 +
+
+ + + 仅为假值。生产实现不得把凭据写入日志、URL 或普通错误信息。 +
+
+
+ +
+

轮询与超时

以下均是原型示例值，最终默认值仍待实现和真机观察确认

+
+
+ + + 示例范围 5–300；生产值需结合风控风险确认。 +
+
+ + + 达到阈值后停止，不做无限重试。 +
+
+ + + 只用于可安全重放的普通请求。 +
+
+ + + 提交围栏前后采用不同恢复协议，不以超时直接重试提交。 +
+
+
+
+ + +
+ +
+
尚无未保存更改。连接检查不会打开拼多多。
+
+
+
+
+ + +

放弃未保存的假配置？

只会丢弃本页原型中的编辑，不影响任何真实设备或服务。

+
+ +
+ + + + diff --git a/docs/design/desk-execution.html b/docs/design/desk-execution.html new file mode 100644 index 0000000..57e6e7e --- /dev/null +++ b/docs/design/desk-execution.html @@ -0,0 +1,534 @@ + + + + + + + cmbuyer 桌面端原型 · 采购执行 + + + +
PROTOTYPE - 仅供枚举交互，非实现依据；全部是假数据，不连接 ADB、web 服务或拼多多
+
+
cmbuyer 执行器Windows / PySide6 前置原型
+ +
+ + +
+
+ +
+
+ +
+ + +
+
+ +
+
+ web 服务已连接 · 假环境 +
+
+ Android 设备FAKE-DEVICE-01 · 已解锁（模拟） +
+
+ 拼多多版本实际 / 已取证：均待 T-103 真机取证 +
+
+ + + +
+
+
+
+

当前任务

尚未领取任务

+ 空闲 +
+
+
+
任务编号
—
+
剩余租约
—
+
商品
暂无商品；轮询会在安全就绪后领取一条任务
+
颜色分类
—
+
尺码 / 数量
—
+
授权单价
—
+
金额上限
—
+
提交围栏
未建立
+
+
    +
    +
    + +
    +

    会话概览

    只显示当前前台会话，不代表后台进程

    +
    +
    下次轮询—
    +
    连续失败0 / 3
    +
    本次完成0
    +
    +
    +
    + +
    +

    事件日志

    假日志；不含凭据、地址、手机号或页面全文

    +
      +
      +
      + +
      + +
      会话：未启动当前步骤：等待开始
      +
      web、设备和已取证 App 版本均就绪后才能开始。
      +
      +
      + + +
      +

      安全说明

      +

      +

      原型边界：本对话框不会调用 API、ADB 或任何平台动作。

      +
      +
      +       +
      + + + + diff --git a/docs/tasks/T-006.md b/docs/tasks/T-006.md index 44f7e0b..e50a3a5 100644 --- a/docs/tasks/T-006.md +++ b/docs/tasks/T-006.md @@ -3,7 +3,7 @@ id: T-006 title: 桌面端 MVP 交互原型 phase: 0 deps: [] -status: TODO +status: DOING created: 2026-08-03 context_ref: dfe3d56 work_branch: task/t-006-desk-prototype @@ -97,5 +97,76 @@ desk 端将使用 PySide6 / Qt Widgets，但当前没有可确认的桌面应用 ## 执行记录 -开工后记录修改文件、浏览器检查尺寸、控制台 / 网络 / 可访问性结果、HTML → PySide6 映射、 -未验证范围和人工确认项。 +### 2026-08-03 · 原型待人工确认 + +状态保持 `DOING`。本轮只完成 Phase 0 浏览器原型，不连接 web、ADB 或拼多多，也不把浏览器 +行为视为 Qt / 真机验收。 + +**已修改** + +- `docs/design/desk-execution.html`：固定两页签桌面壳、三项就绪状态、当前任务与步骤、会话 + 指标、事件日志和唯一主动作。显式状态切换器覆盖 18 个状态：未连接、版本失配、空闲、 + 空轮询、试选、试选完成并释放手机、dry-run、dry-run 完成、真实第二趟围栏前、申请围栏、 + 围栏失败 / 响应不明、围栏后调和、待付款、结果不明、安全校验、外部支付、围栏前转人工、 + 连续失败停止。 +- `docs/design/desk-device-settings.html`：显式 serial、USB / WiFi 标识、ADB 路径、web 地址、 + 假设备凭据、轮询 / 请求 / 真机步骤超时和连续失败阈值。覆盖默认、字段校验、检查中、 + 检查通过、web 失败、版本失配、保存成功、运行中冻结 8 个状态，以及未保存离开协议。 +- 两页均使用 `Segoe UI Variable` / `Segoe UI` 回退、集中语义 token、浅色 / 深色 / 高对比 + 回退、`prefers-reduced-motion`、可见键盘焦点、`aria-live`、本地可复位假数据和内联 CSS / JS。 + 页面间只有本地相对链接；没有外部资源、生产地址请求或真实动作。 + +**HTML → PySide6 / Qt Widgets 交接映射** + +| 原型项 | 核心交互契约 | 推荐 Qt Widgets 映射 | 信号 / 状态来源 | +| --- | --- | --- | --- | +| 应用壳与两个固定页签 | 固定同级页面；切换保留各页状态 | `QMainWindow` + 不可关闭的 `QTabWidget` | `currentChanged(int)`；稳定 page id，不用标题作业务身份 | +| web / 设备 / App 版本状态 | 三项全就绪才允许普通轮询；版本失配 fail closed | `QWidget` + 3 组 `QLabel`，状态色由语义 palette / 动态属性驱动 | `ReadinessViewModel.changed`；实际版本与证据版本由服务层提供 | +| 页面信息条 | 连接、失败、待人工和围栏状态占稳定位置，不抢焦点 | 语义 Banner `QWidget`（图形 + 标题 + 说明） | `state_changed` 经 GUI 线程队列连接；重要变化触发无障碍事件 | +| 唯一主动作 | 每个状态只暴露一个安全主动作；禁用旁边必须有原因 | 共享 `QAction` + `QPushButton` | `QAction.triggered`；enabled / text 由状态机单向派生 | +| 当前任务摘要 | 只读展示任务、规格、金额、租约和 submission | `QFormLayout` + 可复制的只读 `QLabel` / `QLineEdit` | 当前 execution 快照；金额保持十进制字符串 | +| 步骤列表 | 已完成 / 当前 / 等待不只靠颜色；稳定步骤 id | `QListView` + `QAbstractListModel` + `QStyledItemDelegate` | execution step event；模型更新必须在 GUI 线程 | +| 会话指标与事件日志 | 空任务不算失败；日志不含凭据、地址、手机号或页面全文 | 指标 `QLabel`；日志 `QTableView` + `QAbstractTableModel` | poll/session event；高频更新节流，记录使用稳定 event id | +| 设置表单 | 显式提交；字段错误就近显示，失败保留输入 | `QFormLayout`、`QLineEdit`、`QButtonGroup` + `QRadioButton`、`QSpinBox` | `textChanged` / `valueChanged` 只改草稿；`QValidator` 仅做格式层校验 | +| 保存与连接检查 | 保存是唯一主动作；检查只验证连接和安装，不打开 App | `QAction` + `QPushButton`；后台 worker + 页面进度 | `triggered` → worker；结果带 request id，过期结果忽略 | +| 运行中冻结 | 轮询中禁止换设备和保存参数 | 表单容器 / 相关 `QAction.setEnabled(False)` | session state；禁用原因用可见 `QLabel` 与 accessible description | +| 对话框与关闭协议 | Escape / 关闭使用同一取消路径；围栏后关闭不等于可以重来 | `QDialog` + `QDialogButtonBox` | `accepted` / `rejected`；关闭后焦点返回调用者 | +| 焦点与快捷键 | 自然 Tab 顺序、可见焦点、`Ctrl+S` 保存 | 标签 buddy、`QAction` + `QKeySequence.Save` | Qt 标准焦点链；原生实现重新用 Narrator / Inspect 验证 | + +Qt 实现时不复制 DOM、CSS 或 JavaScript 状态对象。业务状态必须来自 web / execution 服务， +View 只渲染；I/O 离开 GUI 线程，通过 PySide6 `Signal` / `Slot` 回到 GUI 线程。PySide6 / Qt 的 +精确版本要在 T-002 初始化后核对，版本敏感 API 在此任务中未作事实声明。 + +**验证证据** + +- `python scripts/validate_agent_context.py`：通过（6 个任务路由，18 个有效仓库路径）。 +- `git diff --check`：通过。 +- Python 标准库 HTML 解析：两页可解析；`desk-execution.html` 39 个 id、 + `desk-device-settings.html` 54 个 id，均无重复；除 `data:,` favicon 外无资源引用。 +- 静态危险面扫描：未发现 `fetch`、`XMLHttpRequest`、WebSocket、外部脚本 / 图片 / iframe， + 也未发现文案为「提交订单」「继续付款」「免密支付」「先用后付」「重试提交」的按钮。 +- Chromium 本地逐页检查：最终控制台 0 error / 0 warning；网络面板只有当前本地 HTML 文档。 +- 执行页 18 个状态、设置页 8 个状态逐项切换；围栏失败时主动作是「打开围栏核查说明」， + 围栏后和结果不明时只显示同一 `submission_id` 的核查入口，危险按钮集合为空。 +- 375 / 768 / 1024 / 1440 px 均无横向溢出；表单操作区与内容区在四个宽度下无覆盖。 + 1440 px 两页均做 full-page 视觉检查。 +- 键盘路径检查到页面链接、主题、状态切换、按钮和表单字段，焦点轮廓可见；Enter 打开核查 + 对话框、Escape 关闭并把焦点还给调用按钮；表单提交聚焦第一个错误且保留输入，模拟异步 + 检查期间禁用保存，完成后恢复；未保存离开会打开确认对话框。 +- 浏览器 accessibility snapshot 可识别 navigation、main、region、表单控件标签、按钮和状态 + 文本；深色主题已交互检查。`forced-colors` 与减少动画分支已静态检查，但不替代原生测试。 + +**未验证 / 待人工确认** + +- 请人工确认：两个固定页签是否足够；执行页当前任务 / 日志的宽屏比例和紧凑页密度； + 「开始 / 停止轮询」作为普通会话唯一主动作是否清楚；待人工、版本失配、围栏失败、围栏后、 + 结果不明与外部支付的严重度和文案是否足够明确。 +- 请人工确认：设置页字段集合，以及轮询间隔、普通请求超时、真机步骤超时、连续失败阈值 + 是否应该允许用户配置。原型中的数字仅是假数据，不是产品默认值。 +- T-103 真机取证后，必须回修 App 实际 / 已取证版本展示、可读字段和文案；本原型没有定义 + 任何拼多多页面判据、选择器、节点或已验证版本。 +- 未验证原生标题栏、系统菜单、Snap Layouts、DPI / 多显示器、Qt palette / QSS、Windows + 高对比、输入法、Narrator / UI Automation、线程、性能、打包与关闭真实后台任务。这些不能 + 由 HTML 证明，需在 T-002 及后续原生实现任务中重新验收。 +- 本轮没有真机证据，也没有真实 web / ADB / API / 文件保存。人工确认前任务继续保持 + `DOING`，不得自动改为 `DONE`。