9.3 KiB
9.3 KiB
Gio 页面与导航结构
ShopHelm 是桌面应用，没有浏览器 URL。本文用稳定的 route ID 定义页面、参数、职责和组件归属。
一、应用框架
首发窗口由 AppShell 组成：
+----------------+---------------------------------------------+
| 主导航 | 页面工具栏 |
| +---------------------------------------------+
| 今日工作台 | |
| 店铺管理 | 当前页面内容 |
| 商品助手 | |
| 客服助手 | |
| 设置 | |
+----------------+---------------------------------------------+
| 全局状态栏：数据库 / 后台操作 / 错误入口 |
+--------------------------------------------------------------+
主页面不做营销首页。窗口最小尺寸由 T-101 实测确定；低于舒适宽度时侧栏可折叠，但表格和表单不得重叠或截断关键动作。
二、Route 定义
| Route ID | 参数 | 页面 | 首发 |
|---|---|---|---|
dashboard |
无 | 今日工作台 | 是 |
stores.list |
可选 filter snapshot | 店铺列表 | 是 |
stores.new |
无 | 新增店铺 | 是 |
stores.detail |
store_id |
店铺详情 | 是 |
stores.edit |
store_id |
编辑店铺 | 是 |
products.list |
可选 store_id |
商品草稿列表 | 是 |
products.new |
可选 store_id |
新增商品 | 是 |
products.detail |
product_id |
商品详情/编辑 | 是 |
products.templates |
kind |
标题/描述模板 | 是 |
products.import |
无 | 商品导入预览 | 是 |
images.assets |
可选 store_id,product_id |
图片素材库 | 是 |
images.compose |
可选 product_id,base_asset_id |
图片叠加预览 | 是 |
customer.replies |
可选 category/language | 客服话术库 | 是 |
customer.followups |
可选 store_id,status |
跟进记录 | 是 |
settings.general |
无 | 常规和路径设置 | 是 |
settings.backup |
无 | 备份与恢复 | 是 |
settings.logs |
无 | 日志位置和诊断信息 | P1 |
无效或已归档 ID 导航到当前页面的 not_found 状态，提供返回列表入口，不打开空白窗口。
三、主导航
主导航固定五项：
- 今日工作台。
- 店铺管理。
- 商品助手。
- 客服助手。
- 设置。
图片素材和图片叠加属于商品助手，不作为一级导航。备份恢复属于设置。
四、页面职责
4.1 今日工作台
- 最近打开店铺，可直接打开默认入口。
- 今日/逾期待办与客服跟进。
- 待上架、需优化商品。
- 最近图片导出。
- 四个新增快捷动作。
- 每个分区独立显示 loading、empty 或 error，局部失败不清空其他分区。
4.2 店铺列表
- 表格列：店铺名、平台、国家/站点、账号标识、负责人、标签、业务状态、Chrome 状态、最后打开、更新时间、操作。
- 工具栏：搜索、平台/国家/负责人/标签/状态筛选、排序、新增。
- 行操作使用图标按钮并带 tooltip：打开、快捷入口菜单、编辑、归档。
- 双击或点击店铺名进入详情；“打开 Chrome”必须是独立明确动作。
- 默认排除归档记录。
4.3 店铺新增/编辑
分区：
- 基本信息。
- Chrome/profile。
- 代理。
- 快捷入口。
- 备注。
保存前显示字段错误。切换页面时有未保存内容则确认离开。密码字段不得出现。
4.4 店铺详情
- 顶部显示店铺身份和业务/Chrome 状态。
- 主要命令：打开默认入口、打开快捷入口、编辑。
- 显示 profile 路径、代理摘要、最后打开、负责人、标签和待办。
- profile 路径可复制或在文件管理器中定位；不得提供“一键删除 profile”。
4.5 商品列表和详情
列表：
- 按店铺、状态和关键词筛选。
- 显示商品名、SKU、店铺、价格、库存、状态、检查进度、更新时间。
- 提供新增、导入、导出入口。
详情：
- 基础资料和价格。
- 标题/描述模板选择。
- 上架检查清单。
- 图片素材。
- 打开图片叠加预览。
价格计算结果与输入放在同一无嵌套面板中，明确标记为参考值。
4.6 商品导入
- 第一步选择 CSV/XLSX。
- 第二步显示文件摘要、列映射、有效行和错误行。
- 第三步选择
all_or_nothing或valid_rows_only并确认。 - 提交后显示创建、更新、跳过统计。
未经 preview 不允许直接导入。
4.7 图片素材库
- 显示真实缩略图、类型、所属店铺/商品、尺寸和缺失状态。
- 支持按路径引用或复制到 ShopHelm 素材库。
- 原图缺失时显示路径和重新定位入口。
- 删除关联和删除受管文件是两个不同动作。
4.8 图片叠加预览
稳定布局：
+----------------------------+----------------------+
| | 底图 / 叠加图选择 |
| | 位置 X / Y |
| 实时预览画布 | 缩放 |
| | 透明度 |
| | 输出尺寸 / 格式 |
| | 导出 |
+----------------------------+----------------------+
- 画布保持目标宽高比，窗口变化不改变 composition spec。
- 拖动叠加图时更新归一化中心点。
- 数字输入、滑杆和重置按钮保持同步。
- 预览生成中显示稳定 loading，不改变画布尺寸。
- 导出成功后显示输出路径和“在文件夹中显示”动作。
- 不放多图层列表、滤镜、文字工具或旋转工具。
窄窗口下控制区移到画布下方，不覆盖画布。
4.9 客服话术
- 分类、语言、关键词筛选。
- 列表显示标题和安全长度的内容预览。
- 一键复制是主要动作，并显示反馈。
- 新增/编辑使用同页表单或 modal，由 T-101 的组件原型决定，整个应用保持一致。
4.10 客服跟进
- 表格显示店铺、买家标识、订单标识、问题类型、状态、下次跟进和更新时间。
- 默认优先显示逾期、今日到期和未解决记录。
- 可快速更新状态。
- 不显示“发送消息”按钮。
4.11 设置
常规设置：
- Chrome 可执行文件。
- managed profile 根目录。
- 默认图片导出目录。
- 默认货币和界面语言。
备份设置：
- 创建备份。
- 备份清单和位置。
- 检查后恢复。
- 清晰说明备份不包含 Chrome profile 和外部素材。
五、项目内组件
| 组件 | 归属 | 稳定职责 |
|---|---|---|
AppShell |
ui/components |
侧栏、工具栏、内容区、全局状态 |
DataTable |
ui/components |
固定列、表头、滚动、选中、排序、行操作 |
FilterBar |
ui/components |
搜索、筛选、重置 |
FormField |
ui/components |
标签、输入、帮助和字段错误 |
Select |
ui/components |
有限枚举选择 |
Modal |
ui/components |
确认和小型编辑流程 |
Toast |
ui/components |
短时成功/失败反馈 |
StatusBadge |
ui/components |
状态文字、图标和颜色 |
EmptyState |
ui/components |
空数据和一个主要动作 |
ErrorPanel |
ui/components |
可行动错误与重试 |
PathPicker |
ui/components |
路径显示、选择和校验 |
ImagePreviewCanvas |
ui/components |
画布、拖动和 viewport 映射 |
ImageLayerControls |
ui/components |
位置、缩放、透明度和重置 |
组件只抽象已经在至少两个页面出现的稳定交互；首个页面不提前建设通用表单 DSL。
六、导航状态
type Route struct {
Name RouteName
Params map[string]string
}
type Navigator interface {
Push(Route)
Replace(Route)
Back()
}
- 应用启动进入
dashboard。 - 列表进入详情后返回时保留搜索、筛选、排序和滚动位置。
- 保存成功后回到来源页或留在详情，由页面任务验收明确；不可每页自行决定不同模式。
- 恢复数据库成功后清空历史栈并进入
dashboard。 - 未保存表单离开时弹确认；没有改动时直接离开。
七、统一页面状态
每个页面显式维护：
idle -> loading -> ready
`-> empty
`-> error
ready -> submitting -> ready/error
- loading、empty、error 使用稳定尺寸，避免整个布局跳动。
- 请求进行中禁用重复动作，但保留取消或返回能力。
- error 保留用户已输入的表单内容。
- 删除/归档、覆盖、恢复等不可逆或高影响动作使用确认 modal。
八、UI 文字与图标
- 命令按钮优先使用 Gio/项目已有标准图标；不手画重复图标。
- 图标按钮必须有 tooltip 和可访问名称。
- 状态必须同时有文字或图标，不只靠颜色。
- 表格内部使用紧凑字号，不使用 hero 级标题。
- 固定格式画布、表格列和工具栏必须有稳定尺寸约束。
- 页面不放“本功能可以做什么”的宣传说明；只在错误、空状态和确认流程中显示必要操作信息。