# 主应用：通知页 UI/UX

## 1. 页面定义

| 项目 | 内容 |
| --- | --- |
| 页面名称 | 通知中心 |
| 通知列表路由 | `/notifications` |
| 通知详情路由 | `/notifications/[scheduledRunId]` |
| 页面实现 | `app-instance/frontend/app/(app)/notifications/page.tsx`、`app-instance/frontend/app/(app)/notifications/[scheduledRunId]/page.tsx` |
| 关键组件 | `NotificationsPage`、`NotificationDetailPage`、`ChatWorkbench`、`MessageList`、`Button`、`Badge` |
| 核心任务 | 查看定时任务生成的通知、进入通知详情、刷新通知、对通知结果提出本次修改或未来规则调整、打开已接入 Task |
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |

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

```text
AppShell
└── main.pt-16
    ├── /notifications
    │   ├── Page Header
    │   │   ├── h1 Notifications
    │   │   ├── 页面说明
    │   │   └── 刷新按钮
    │   ├── Error Card
    │   └── Notification List Panel
    │       ├── Loading State
    │       ├── Empty State
    │       └── Notification Link Row/Card
    │           ├── 标题
    │           ├── 状态 Badge
    │           ├── 摘要
    │           ├── 生成时间
    │           ├── job 名称
    │           └── 桌面端箭头
    └── /notifications/[scheduledRunId]
        ├── Detail Header
        │   ├── 返回通知列表
        │   ├── 标题
        │   ├── 状态 / 已接入 Task Badge
        │   ├── 生成时间
        │   ├── 刷新按钮
        │   └── 查看任务按钮
        ├── Error Banner
        ├── ChatWorkbench
        │   └── MessageList
        │       ├── 用户原始请求
        │       └── 通知生成结果
        └── Reply Panel
            ├── 修改这次
            ├── 以后按这样
            ├── 已接入提示
            └── 回复输入框 + 发送
```

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

### 通知列表

- 外层使用 `max-w-6xl`，移动端内边距为 `16px`，桌面端为 `24px`。
- 列表区域是独立白色面板，内部垂直滚动，不产生页面级横向滚动。
- 移动端列表项按单列卡片阅读：标题、摘要、时间和 job 名称上下排列。
- `md` 及以上使用网格列展示摘要、时间、job 名称和箭头，方便桌面端扫描。
- 长标题、长摘要和长 job 名称都使用容器内断行，避免 ID 或连续字符串撑破卡片。
- 刷新按钮高度为 `44px`，满足移动端触控目标要求。

### 通知详情

- 页面整体高度为 `calc(100vh - 4rem)`，位于全局 header 下方。
- 顶部详情 header 使用浅色背景和底部分隔线，承载返回、标题、状态、生成时间和操作按钮。
- 移动端标题允许换行，不再只截断；长 scheduled run id 或长标题不会撑破页面。
- 中间 `ChatWorkbench` 使用剩余高度展示消息流。
- 底部回复区是独立面板，包含两个意图按钮和按需出现的输入框。
- 回复输入框有可见 label，不依赖 placeholder 作为唯一说明。
- 返回、刷新、查看任务、意图选择、发送等关键操作均为 `44px` 高度。

## 4. 操作与 UX 逻辑

| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
| --- | --- | --- | --- | --- |
| 刷新通知列表 | 点击列表页 Refresh | 调用 `GET /api/notifications`，列表重新渲染 | 获取最新定时通知 | 正常 |
| 打开通知详情 | 点击通知列表项 | 跳转 `/notifications/[scheduledRunId]` | 查看通知完整上下文和结果 | 正常 |
| 空通知状态 | 列表接口返回空数组 | 显示“暂无通知” | 明确没有可处理内容 | 正常 |
| 列表加载失败 | 列表接口失败 | 显示错误卡片 | 让用户知道是接口异常而不是无数据 | 正常 |
| 返回通知列表 | 详情页点击返回 | 跳转 `/notifications` | 提供明确退出路径 | 正常 |
| 刷新通知详情 | 详情页点击 Refresh | 调用 `GET /api/notifications/[id]` | 重新获取当前通知状态 | 正常 |
| 修改这次 | 点击 `Revise this` | 按钮进入选中态，显示“本次通知的修改说明”输入框 | 只影响本次通知结果 | 正常 |
| 以后按这样 | 点击 `Apply going forward` | 按钮进入选中态，显示“以后这类通知的调整说明”输入框 | 将用户偏好表达为未来规则 | 正常 |
| 发送修改说明 | 输入内容后点击 Send | 调用 `POST /api/chat`，携带 `reply_to_scheduled_run_id` 和 `scheduled_reply_intent` | 把通知反馈接回对话/任务处理流程 | 正常 |
| 打开已接入 Task | 已存在 `task_id` 时点击 Open task | 跳转 `/tasks/[taskId]` | 从通知继续跟进任务 | 正常 |
| 通知不存在 | 详情接口失败或无数据 | 显示错误信息和返回通知入口 | 提供异常恢复路径 | 正常 |

## 5. 响应式测试矩阵

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

| 页面 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
| --- | --- | --- | --- | --- |
| 通知列表 | `320×568` | 无 | 0 | 长标题和长 job 名在卡片内换行 |
| 通知列表 | `390×844` | 无 | 0 | 手机竖屏可刷新、进入详情 |
| 通知列表 | `844×390` 横屏 | 无 | 0 | 横屏无页面级横向滚动 |
| 通知列表 | `768×1024` | 无 | 0 | 平板列表布局稳定 |
| 通知列表 | `1365×900` | 无 | 0 | 桌面网格列可扫描 |
| 通知空态 | `390×844` | 无 | 0 | 空态居中显示 |
| 通知错误态 | `390×844` | 无 | 0 | 错误信息在卡片内可读 |
| 通知详情 | `320×568` | 无 | 0 | 顶部标题换行，回复区不遮挡 |
| 通知详情 | `390×844` | 无 | 0 | 消息流和底部回复区分层清楚 |
| 通知详情 | `768×1024` | 无 | 0 | 平板详情布局正常 |
| 通知详情 | `1365×900` | 无 | 0 | 桌面详情布局正常 |
| 通知详情错误态 | `390×844` | 无 | 0 | 返回通知入口可见 |

### 关键量化证据

- 本地通知页 QA 自动化用例 `4 passed`。
- 部署到 `terminaltest` 后，同一套通知页 QA 自动化用例 `4 passed`。
- 列表实测视口 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
- 详情实测视口 `320×568`、`390×844`、`768×1024`、`1365×900` 均无页面级横向越界。
- 所有实测视口可见小触控目标数为 `0`。
- 回复提交实测请求包含 `reply_to_scheduled_run_id` 和 `scheduled_reply_intent=revise_once`。

## 6. 已修复问题

| 等级 | 问题 | 修复 |
| --- | --- | --- |
| P1 | 通知列表长标题、长 job 名在移动端被右侧裁切或存在撑破风险 | 标题、摘要和 job 名增加容器内断行；列表项保留 `min-w-0` |
| P2 | 列表 Refresh 按钮高度只有 36px，低于移动端触控标准 | 调整为 `44px` |
| P2 | 详情页返回、Refresh、Revise、Apply going forward 等操作高度不足 44px | 统一调整为 `44px` |
| P2 | 详情页标题只截断，移动端无法判断完整通知主题 | 改为可换行并控制在容器内 |
| P2 | 详情回复输入框依赖 placeholder 表达含义 | 增加可见 label，并根据意图区分本次修改/未来调整 |
| P3 | 意图按钮缺少明确 pressed 状态语义 | 增加 `aria-pressed` |

## 7. 剩余观察项

- 本地 mocked API 场景会出现 WebSocket 握手失败日志，因为测试 token 不对应真实后端 WS；该日志不影响通知页 HTTP 交互和布局结论。
- 后续接入真实用户历史通知时，仍需持续观察第三方系统生成的异常长 Markdown、附件和错误文本。