# 主应用：市场页 UI/UX

## 1. 页面定义

| 项目 | 内容 |
| --- | --- |
| 页面名称 | 技能市场 |
| 路由 | `/marketplace` |
| 页面实现 | `app-instance/frontend/app/(app)/marketplace/page.tsx` |
| 关键组件 | `MarketplacePage`、`SkillDetailView`、`Tabs`、`Card`、`Button`、`Input` |
| 核心任务 | 搜索 SkillHub 技能、排序筛选、打开详情、查看说明/文件/版本、安装或更新技能 |
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |

## 2. 信息架构与组件层级

```text
AppShell
└── main.pt-16
    └── /marketplace
        ├── Page Header
        │   ├── h1 Marketplace
        │   └── 页面说明
        ├── Search Form
        │   ├── 搜索输入框
        │   └── Search
        ├── Error Card
        ├── Search Results
        │   ├── Sort Buttons
        │   ├── Starred only Filter
        │   ├── Skill Button Cards
        │   └── Pagination
        └── Skill Detail
            ├── Back to search
            ├── Detail Header
            │   ├── namespace/download/star/version badges
            │   ├── title/summary
            │   └── Install/Reinstall
            ├── Overview Tab
            ├── Files Tab
            │   ├── file list
            │   └── file preview
            └── Versions Tab
                └── version rows
```

## 3. 布局与响应式规则

- 页面外层使用 `max-w-7xl`，移动端内边距为 `16px`，桌面端为 `24px`。
- 搜索区在移动端垂直排列，桌面端输入框和 Search 按钮横向排列。
- 结果卡片使用真正的 `button` 语义，而不是仅给 Card 绑定 click，键盘和读屏器都能识别为可操作项。
- 技能名、namespace、版本号、文件路径、README markdown 和代码预览都允许在容器内断行。
- 详情页文件列表和文件预览在桌面端左右分栏，移动端垂直排列。
- Tabs、按钮、输入框和分页操作均满足 `44px` 触控目标。
- Markdown 中的长代码、表格和链接不会撑出页面；表格在内容区内横向滚动。

## 4. 操作与 UX 逻辑

| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
| --- | --- | --- | --- | --- |
| 搜索技能 | 输入关键词后点击 Search 或提交表单 | 调用 SkillHub search，列表刷新 | 快速定位技能 | 正常 |
| 切换排序 | 点击 Relevance/Downloads/Newest | 当前排序按钮进入选中态并重新加载 | 支持按不同意图浏览 | 正常 |
| 只看收藏 | 点击 Starred only | 本地筛选 starCount 大于 0 的结果 | 聚焦已收藏技能 | 正常 |
| 打开技能详情 | 点击技能卡片按钮 | 加载 detail、version list、SKILL.md | 进入安装前审阅 | 正常 |
| 返回搜索 | 点击 Back to search | 清空详情状态并回到结果列表 | 提供明确退出路径 | 正常 |
| 切换说明/文件/版本 | 点击 tab | 同页切换内容区 | 让审阅信息分层 | 正常 |
| 打开文件 | Files tab 点击文件路径 | 加载并预览文件内容 | 审核技能代码或文档 | 正常 |
| 切换版本 | Versions tab 点击版本行 | 加载指定版本详情和 README | 安装前比较版本 | 正常 |
| 安装技能 | 点击 Install/Reinstall | 调用 install API，按钮 loading，成功后显示 installed | 完成技能接入 | 正常 |
| 加载/安装失败 | API 返回错误 | 显示错误卡片，文本断行 | 明确失败原因并保留当前上下文 | 正常 |

## 5. 响应式测试矩阵

测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、输入、详情打开、文件预览、安装和截图。

| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
| --- | --- | --- | --- | --- |
| 搜索结果 + 详情 | `320×568` | 无 | 0 | 长 skill 名、namespace 和 summary 不撑破页面 |
| 搜索结果 + 详情 | `390×844` | 无 | 0 | 可搜索、打开详情、切换文件并安装 |
| 搜索结果 + 详情 | `844×390` 横屏 | 无 | 0 | 横屏内容可滚动，不产生页面级横向滚动 |
| 搜索结果 + 详情 | `768×1024` | 无 | 0 | 平板详情布局稳定 |
| 搜索结果 + 详情 | `1365×900` | 无 | 0 | 桌面分栏和卡片布局正常 |

### 关键量化证据

- 本地与 `terminaltest` 市场/配置组合 QA 自动化用例均 `4 passed`，其中覆盖市场流。
- 覆盖搜索、详情、文件 tab、长路径文件预览、安装请求和响应式。
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
- 所有实测视口可见小触控目标数为 `0`。
- 本地截图保存在 `/tmp/beaver-market-settings-qa-local-shots`，生产截图保存在 `/tmp/beaver-market-settings-qa-prod-shots`。

## 6. 已修复问题

| 等级 | 问题 | 修复 |
| --- | --- | --- |
| P1 | 结果卡片只有 Card click，没有按钮语义，键盘和辅助技术不可稳定操作 | 改为真实 `button` 卡片 |
| P1 | 技能详情里的文件路径、版本号、markdown 代码块可能撑破移动端 | 增加 `min-w-0`、`break-all`、`break-words` 和 markdown 预览约束 |
| P2 | 页面缺少清晰 `h1`，市场页身份不明确 | 增加语义化标题和说明 |
| P2 | 搜索表单在窄屏可能挤压 | 移动端改为纵向布局 |
| P2 | Tabs 触控高度不足 44px | 基础 `TabsTrigger` 调整为 `44px` |
| P2 | 排序、筛选、返回、安装、分页等操作触控尺寸不统一 | 基础按钮和页面操作统一提升到 `44px` |
| P3 | 长 namespace 和版本 badge 只截断或可能撑宽 | 改为容器内断行 |

## 7. 剩余观察项

- 本轮使用模拟 SkillHub 数据；真实市场里若存在复杂 HTML/Markdown 表格或超大文件，仍需持续抽样检查。
- 当前安装成功后停留在详情页并更新 installed 状态，后续可考虑增加轻量 toast，增强成功反馈。