# 主应用：配置页 UI/UX

## 1. 页面定义

| 项目 | 内容 |
| --- | --- |
| 页面名称 | 配置 |
| 主路由 | `/settings` |
| 同实现路由 | `/status` |
| 页面实现 | `app-instance/frontend/app/(app)/settings/page.tsx` re-export `app-instance/frontend/app/(app)/status/page.tsx` |
| 关键组件 | `StatusPage`、Provider Dialog、Channel Detail Dialog、Connector Dialog、Restart Dialog、`InfoRow`、`Field` |
| 核心任务 | 查看实例运行信息、调整智能体参数、配置模型提供商、配置/连接通道、查看通道事件、重启实例 |
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |

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

```text
AppShell
└── main.pt-16
    └── /settings
        ├── Page Header
        │   ├── h1 Settings
        │   ├── 页面说明
        │   └── Refresh
        ├── Instance runtime Card
        │   ├── Runtime Logs
        │   ├── Restart instance
        │   └── config/workspace InfoRow
        ├── Agent configuration Card
        │   ├── model InfoRow
        │   ├── max tokens / temperature / max tool iterations
        │   └── Save agent config
        ├── Providers Card
        │   └── provider button cards
        ├── Provider Dialog
        │   ├── enable switch
        │   ├── model / API key / API base / timeout
        │   └── Cancel / Save
        ├── Channels Card
        │   └── connector/channel button cards
        ├── Channel Detail Dialog
        │   ├── channel title and id
        │   ├── connection settings
        │   ├── credential fields
        │   ├── policy fields
        │   ├── channel state InfoRows
        │   └── recent events
        ├── Connector Dialog
        │   ├── display name / domain / mode
        │   ├── QR or plugin session
        │   └── Close / Refresh / Start connection
        └── Restart Dialog
            ├── warning text
            └── Cancel / Restart
```

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

- `/settings` 和 `/status` 使用同一实现；当前文档按配置页维护。
- 页面外层使用 `max-w-6xl`，移动端内边距为 `16px`，桌面端为 `24px`。
- `InfoRow` 使用响应式网格，长配置路径、workspace、model、channel id 和 URL 都在容器内断行。
- Provider 与 Channel 卡片是按钮语义，移动端单列，平板/桌面多列。
- 所有 Dialog 移动端使用 `width: calc(100vw - 2rem)`、顶部 16px、最大高度 `calc(100vh - 2rem)`、内部滚动；桌面端保持居中面板。
- Dialog 直接子元素统一 `min-w-0`，避免长标题或表单网格把弹窗撑出视口。
- 输入框、按钮、下拉、tab、switch 等可见操作均满足 `44px` 触控目标。
- 通道表单的 `Display name`、`Account ID` 等关键字段具备 label/input 绑定，可按标签点击和自动化定位。

## 4. 操作与 UX 逻辑

| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
| --- | --- | --- | --- | --- |
| 刷新配置 | 点击 Refresh | 重新调用 `/api/status` | 获取最新实例状态 | 正常 |
| 打开运行日志 | 点击 Runtime Logs | 跳转 `/logs` | 进入运行排障入口 | 正常 |
| 打开重启确认 | 点击 Restart instance | 打开确认 Dialog | 防止误重启 | 正常 |
| 确认重启 | Dialog 点击 Restart | 调用 `/api/runtime/restart`，成功后关闭并延迟刷新 | 应用配置变更或恢复运行态 | 正常 |
| 保存智能体配置 | 修改参数后点击 Save agent config | 校验数值并调用 `/api/agent-config` | 调整模型上下文和推理参数 | 正常 |
| 打开 Provider | 点击 OpenAI/DeepSeek 等卡片 | 打开 Provider Dialog 并填入当前值 | 配置模型接入 | 正常 |
| 保存 Provider | Dialog 点击 Save | 调用 `/api/providers/{id}/config`，成功后刷新 status | 启用或更新默认提供商 | 正常 |
| 打开通道详情 | 点击已存在通道卡片 | 加载 `/api/channels/{id}/config` 和 events | 查看并编辑通道连接 | 正常 |
| 保存通道配置 | Dialog 点击 Save channel config | 调用 `/api/channels/{id}/config`，必要时提示重启 | 更新 IM/终端通道配置 | 正常 |
| 打开连接器 | 点击可启动的 Weixin/Feishu 卡片 | 打开连接器 Dialog | 启动扫码或插件接入流程 | 正常 |
| 状态加载失败 | `/api/status` 失败 | 显示错误卡片和 Retry | 明确异常并提供恢复入口 | 正常 |

## 5. 响应式测试矩阵

测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、输入、弹窗保存、重启确认和截图。

| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
| --- | --- | --- | --- | --- |
| 配置页 + 飞书通道弹窗 | `320×568` | 无 | 0 | 长 config path、workspace、provider 名和 channel id 均不越界 |
| 配置页 + 飞书通道弹窗 | `390×844` | 无 | 0 | 可保存智能体、Provider、通道配置并打开重启确认 |
| 配置页 + 飞书通道弹窗 | `844×390` 横屏 | 无 | 0 | 横屏 Dialog 可滚动，不撑出页面 |
| 配置页 + 飞书通道弹窗 | `768×1024` | 无 | 0 | 平板布局稳定 |
| 配置页 + 飞书通道弹窗 | `1365×900` | 无 | 0 | 桌面卡片和 Dialog 布局正常 |
| 状态错误 | `390×844` | 无 | 0 | 错误文案和 Retry 可读可点 |

### 关键量化证据

- 本地与 `terminaltest` 市场/配置组合 QA 自动化用例均 `4 passed`，其中覆盖配置流。
- 覆盖智能体配置保存、OpenAI Provider 保存、Feishu 通道保存、重启确认、状态错误和响应式。
- 实测 `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 | 配置页 Dialog 在移动端按桌面宽度居中，长内容会撑出或被裁切 | 基础 `DialogContent` 增加移动端 `calc(100vw - 2rem)` 宽度、最大高度、滚动和 `min-w-0` |
| P1 | `InfoRow` 的长路径固定 `max-w-[400px] truncate`，在窄屏撑破页面 | 改为响应式网格和 `break-all` |
| P1 | 通道表单关键 label 未绑定输入框，真实点击标签和自动化定位不稳定 | `Field` 支持 `htmlFor`，关键字段增加稳定 `id` |
| P2 | Provider、Channel 卡片长名称和 channel id 可能撑宽 | 卡片内部增加 `min-w-0`、`break-all` 和可换行文本 |
| P2 | Button/Input/Select/Tabs 触控高度不足或不统一 | 基础组件统一提升到 44px 级别 |
| P2 | 通道最近事件时间和状态长文本可能挤压 | 改为移动端纵向布局并断行 |
| P3 | 错误文案和保存提示可能被长文本撑开 | 增加 `break-words` |

## 7. 剩余观察项

- 本轮使用模拟 provider/channel 数据；真实第三方连接器返回超长错误、二维码图片或异常 instructions 时仍需抽样验证。
- `/settings` 与 `/status` 共用同一实现，后续如果产品语义拆分，需要分别维护两份页面文档。