soft_quay/docs/routes.md

页面与视图结构(Gio)

本项目是 Gio 桌面应用,没有 URL 路由;本文约定页面(视图)划分、职责和组件归属。现代版与 Win7 版共享 ViewModel 和交互语义,Gio 控件实现允许分别适配。

主窗口布局

┌─────────────────────────────────────────────┐
│ 顶部栏:搜索框 · 分类筛选 · 检测更新 · 下载队列入口 │
├────────┬────────────────────────────────────┤
│ 左侧   │ 中部:虚拟化软件列表(layout.List)      │
│ 视图   │  每项:图标·名称·版本·状态·进度·主操作按钮 │
│ 全部   │                                    │
│ 已安装 │  右侧/弹层:软件详情                   │
│ 可更新 │   版本 · 简介 · 教程 · 授权状态 · 操作   │
│ 最近使用│                                    │
├────────┴────────────────────────────────────┤
│ 底部状态栏:网络 · 任务数 · 磁盘 · 盒子版本(Legacy 标识) │
└─────────────────────────────────────────────┘

视图清单

视图	职责	MVP
软件列表(主视图)	T-203 已实现全部/已安装/可更新切换、名称/ID/tag 即时搜索、单分类筛选、稳定滚动与明确空状态;下载中/最近使用和多标签复选随对应用例后续接入	P0
软件详情(弹层或右栏)	T-204 已实现右栏、关闭、版本/分类/简介/tags/状态/不可用原因/教程/主页展示与内存图标;真实操作和授权事实随对应模块接入	P0
下载队列	所有任务的进度、速度、剩余时间;暂停/取消/重试	P0
设置	并发数、目录、代理、自动检查更新、beta 通道、日志级别、便携模式(V2)	P0(最小集)
授权	许可证导入、已授权软件列表、machine 信息、换绑/申诉入口	P0
提示/错误弹窗	失败原因、重试路径、更新确认、退出运行中软件提示	P0

组件归属

组件	归属	说明
AppShell	全局	窗口框架、顶部栏、左侧导航、底部状态栏
AppList	主视图	惰性 layout.List;控件状态按软件 ID 保存,不按列表序号
AppRow	主视图	单个软件项:状态、进度和主操作按钮
AppDetail	详情	详情展示与操作
DownloadPanel	下载队列	任务列表与控制
SettingsForm	设置	设置项读写(经 application 用例)
LicensePanel	授权	导入与状态展示
Toast/Dialog	全局	错误与确认交互

每个页面用独立 struct 保存:widget.Clickable、widget.Editor、layout.List、过滤条件、当前 ViewModel、pending RequestID、临时提示和错误状态。

交互规则(硬约束)

• 每帧先 drain 点击事件,再提交用例;后台只发布事件,UI 在 ApplyEvent 中更新 ViewModel 后 Window.Invalidate。
• Layout 中不得读磁盘、访问网络、计算哈希;图标走内存 + 磁盘缓存(按 DPI)。
• 数百个软件项滚动不卡顿是验收标准,不是优化项。
• 未验证/不兼容的软件显示原因,操作按钮禁用,不静默失败。
• Win7 版允许减少动画、阴影和高成本渲染,但交互语义与现代版一致,并明显展示 Legacy 标识。

T-203 已落地的列表交互约束:

• 共享 core/application.CatalogListModel 只消费预先准备的内存快照;搜索覆盖名称、稳定 ID 和 tags,分类与 all/installed/updates 可组合。
• modern/win7 都使用惰性 layout.List;500 项有限 viewport 测试必须证明不会布局全部行。
• Editor、视图按钮、分类按钮、软件行的键盘顺序与视觉顺序一致;搜索和软件行有可见焦点反馈,所有按钮最小高度 44dp。
• 行 Clickable 保存在以 app ID 为键的 map;筛选、视图切换或 Catalog 快照更新不按可见序号迁移控件状态。
• 无 Catalog 与过滤无结果是两个不同空状态;后者提供“显示全部软件”恢复操作。

T-204 已落地的详情/图标约束:

• 点击软件行用 selected app ID 打开右侧详情,关闭后回到同一列表/筛选/滚动上下文。
• modern 与 Legacy 均显示版本、分类、简介、tags、状态、不可用原因、教程和主页文本;尚未接入的安装/启动/授权不伪装为已可执行操作。
• 后台把已验证图标解码为 image.Image 后发布完成事件;UI goroutine 消费事件再调用 ApplyIcon/Invalidate。ApplyIcon 预建 paint.ImageOp,列表与详情 Layout 只绘制内存操作;SetItems 在 Catalog 移除 app 时剪枝对应 ImageOp。
• 图标未命中或离线缓存不可用时显示非 emoji 的字母占位,不阻塞列表或详情。

导航规则

• 列表 → 详情:点击软件项;详情保留返回/关闭。
• 任一视图可进下载队列(顶部入口);任务完成后返回时列表状态已回填。
• 启动需授权的软件而无有效许可证时,引导到授权视图,不直接报错退出。
• 更新需要退出运行中的软件时,弹确认对话框,等待用户处理,超时取消更新。