# Gio 页面与导航结构

> ShopHelm 是桌面应用，没有浏览器 URL。本文用稳定的 route ID 定义页面、参数、职责和组件归属。

## 一、应用框架

首发窗口由 `AppShell` 组成：

```text
+----------------+---------------------------------------------+
| 主导航         | 页面工具栏                                  |
|                +---------------------------------------------+
| 今日工作台     |                                             |
| 店铺管理       | 当前页面内容                                |
| 商品助手       |                                             |
| 客服助手       |                                             |
| 设置           |                                             |
+----------------+---------------------------------------------+
| 全局状态栏：数据库 / 后台操作 / 错误入口                     |
+--------------------------------------------------------------+
```

主页面不做营销首页。窗口最小尺寸由 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` 状态，提供返回列表入口，不打开空白窗口。

## 三、主导航

主导航固定五项：

1. 今日工作台。
2. 店铺管理。
3. 商品助手。
4. 客服助手。
5. 设置。

图片素材和图片叠加属于商品助手，不作为一级导航。备份恢复属于设置。

## 四、页面职责

### 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 图片叠加预览

稳定布局：

```text
+----------------------------+----------------------+
|                            | 底图 / 叠加图选择    |
|                            | 位置 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。

## 六、导航状态

```go
type Route struct {
    Name   RouteName
    Params map[string]string
}

type Navigator interface {
    Push(Route)
    Replace(Route)
    Back()
}
```

- 应用启动进入 `dashboard`。
- 列表进入详情后返回时保留搜索、筛选、排序和滚动位置。
- 保存成功后回到来源页或留在详情，由页面任务验收明确；不可每页自行决定不同模式。
- 恢复数据库成功后清空历史栈并进入 `dashboard`。
- 未保存表单离开时弹确认；没有改动时直接离开。

## 七、统一页面状态

每个页面显式维护：

```text
idle -> loading -> ready
               `-> empty
               `-> error

ready -> submitting -> ready/error
```

- loading、empty、error 使用稳定尺寸，避免整个布局跳动。
- 请求进行中禁用重复动作，但保留取消或返回能力。
- error 保留用户已输入的表单内容。
- 删除/归档、覆盖、恢复等不可逆或高影响动作使用确认 modal。

## 八、UI 文字与图标

- 命令按钮优先使用 Gio/项目已有标准图标；不手画重复图标。
- 图标按钮必须有 tooltip 和可访问名称。
- 状态必须同时有文字或图标，不只靠颜色。
- 表格内部使用紧凑字号，不使用 hero 级标题。
- 固定格式画布、表格列和工具栏必须有稳定尺寸约束。
- 页面不放“本功能可以做什么”的宣传说明；只在错误、空状态和确认流程中显示必要操作信息。