docs: establish ShopHelm harness coding baseline
This commit is contained in:
QiuSW
+252
@@ -0,0 +1,252 @@
|
||||
# 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 级标题。
|
||||
- 固定格式画布、表格列和工具栏必须有稳定尺寸约束。
|
||||
- 页面不放“本功能可以做什么”的宣传说明；只在错误、空状态和确认流程中显示必要操作信息。
|
||||
Reference in New Issue
Block a user