# 主应用：Outlook 页 UI/UX

## 1. 页面定义

| 项目 | 内容 |
| --- | --- |
| 页面名称 | Outlook |
| 路由 | `/outlook` |
| 页面实现 | `app-instance/frontend/app/(app)/outlook/page.tsx` |
| 关键组件 | `OutlookPage`、`MessageCard`、`EventCard`、`Field`、邮件详情 Dialog、日程详情 Dialog |
| 核心任务 | 配置 Outlook/EWS 连接、测试连接、保存启用、断开连接、查看收件箱/发件箱、分页、查看邮件详情、查看未来 7 天日程 |
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |

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

```text
AppShell
└── main.pt-16
    └── /outlook
        ├── Status Header
        │   ├── h1 Outlook
        │   ├── connection / MCP / provider badges
        │   ├── mailbox / timezone / last refresh
        │   ├── Inbox / Sent / Calendar stats
        │   └── Refresh
        ├── Error Card
        ├── Warning Card
        ├── View Tabs
        │   ├── Inbox
        │   ├── Sent
        │   ├── Calendar
        │   └── Settings
        ├── Inbox / Sent
        │   ├── Mailbox header
        │   ├── Refresh / Previous / Next
        │   └── Message rows
        ├── Calendar
        │   ├── Week header
        │   ├── Previous week / This week / Next week / Refresh
        │   └── Day cards
        ├── Settings
        │   ├── Connection settings form
        │   ├── Test connection / Save and enable / Disconnect
        │   ├── Test result panel
        │   └── Connection status panel
        ├── Message detail Dialog
        │   ├── metadata panel
        │   └── body preview
        └── Event detail Dialog
            ├── organizer / location / attendees
            └── notes
```

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

- 页面外层使用 `max-w-7xl`，移动端内边距为 `16px`，桌面端为 `24px`。
- 顶部状态区有语义化 `h1`，长邮箱、时区和刷新时间允许容器内断行。
- 已配置时显示 Inbox、Sent、Calendar、Settings；未配置时只显示 Settings。
- 邮件列表和日程列表在移动端头部为上下布局，分页和刷新按钮可换行。
- 邮件详情和日程详情 Dialog 在移动端使用 `left/right/top/bottom: 16px` 的独立面板，内容可滚动，不再被默认居中动画撑出视口。
- 设置表单字段均有 `label htmlFor` 与 input `id` 绑定，支持可访问名称和自动化定位。
- 输入框、主要按钮、分页按钮、刷新 icon、Dialog 关闭按钮均满足 `44px` 触控目标。
- 邮件正文里的明文链接使用 `min-height: 44px` 的可点击区域，移动端更容易点击。

## 4. 操作与 UX 逻辑

| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
| --- | --- | --- | --- | --- |
| 初次加载已配置状态 | 打开 `/outlook` | 加载 status 后自动加载 overview | 顶部统计和 warning 不显示过期空值 | 正常 |
| 刷新 Outlook | 点击 Refresh | 刷新 status/overview，并刷新当前 tab 数据 | 获取最新连接、邮件或日程状态 | 正常 |
| 切换 Inbox/Sent/Calendar/Settings | 点击 tab | 切换视图，按需加载邮箱或日程数据 | 保持页面内工作流清晰 | 正常 |
| 查看邮件详情 | 点击邮件行 | 打开邮件详情 Dialog，加载 message-detail | 阅读正文和收发件人信息 | 正常 |
| 查看日程详情 | 点击日程卡片 | 打开日程详情 Dialog | 查看地点、参会人和说明 | 正常 |
| 邮件分页 | 点击 Previous / Next | 使用当前 skip 加载上一页/下一页 | 浏览更多邮件 | 正常 |
| 日程切周 | 点击 Previous week / This week / Next week | 更新 7 天范围并重新加载 events | 快速查看周视图 | 正常 |
| 测试连接 | 填写必要字段后点击 Test connection | 显示 testing，成功后显示 sample 与 warning | 保存前验证配置可用 | 正常 |
| 保存并启用 | 点击 Save and enable | 成功后清空密码、刷新状态并进入 Inbox | 完成 Outlook 接入 | 正常 |
| 断开连接 | 点击 Disconnect 并确认 | 清空 overview、选中详情和分页缓存，回到 Settings | 防止误断开并恢复到配置状态 | 正常 |
| 状态加载失败 | status 接口失败 | 显示错误卡 | 明确异常原因 | 正常 |

## 5. 响应式测试矩阵

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

| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
| --- | --- | --- | --- | --- |
| 邮件详情 | `390×844` | 无 | 0 | 可打开邮件详情，长主题、收件人、正文和链接均可读 |
| 日程详情 | `390×844` | 无 | 0 | 可打开日程详情，长地点和参会人可断行 |
| 设置表单 | `390×844` | 无 | 0 | 字段可通过 label 操作，测试/保存/断开流程正常 |
| 状态错误 | `390×844` | 无 | 0 | 错误卡可读 |
| 邮件详情 + 设置 | `320×568` | 无 | 0 | 窄屏无页面级横向滚动，Dialog 可滚动 |
| 邮件详情 + 设置 | `390×844` | 无 | 0 | 手机竖屏布局稳定 |
| 邮件详情 + 设置 | `844×390` 横屏 | 无 | 0 | 横屏不出现页面级横向滚动 |
| 邮件详情 + 设置 | `768×1024` | 无 | 0 | 平板布局稳定 |
| 邮件详情 + 设置 | `1365×900` | 无 | 0 | 桌面布局正常 |

### 关键量化证据

- 本地 Outlook 页 QA 自动化用例 `4 passed`。
- 部署到 `terminaltest` 后，同一套 Outlook 页 QA 自动化用例 `4 passed`。
- 覆盖已配置状态、overview 加载、Inbox、邮件详情、Calendar、日程详情、Settings、Test、Save、Disconnect confirm、状态错误和响应式。
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
- 所有实测视口可见小触控目标数为 `0`。

## 6. 已修复问题

| 等级 | 问题 | 修复 |
| --- | --- | --- |
| P1 | 已配置 Outlook 初次进入页面不会主动加载 overview，顶部统计可能一直为 0 | `loadStatus` 在 configured 状态下自动加载 overview |
| P1 | 设置表单 label 未绑定 input，辅助技术和自动化无法按字段名定位 | `Field` 增加 `htmlFor`，所有输入框增加稳定 `id` |
| P1 | 邮件详情和日程详情 Dialog 在移动端会被默认居中/slide 动画撑出视口 | 移动端改为四边 inset 面板并覆盖 slide 偏移 |
| P1 | 长邮箱、EWS URL、邮件主题、地点、参会人、warning 可能撑破布局 | 关键文本增加 `min-w-0`、`break-all` 或 `break-words` |
| P2 | Refresh、分页、表单操作、Dialog 关闭等触控目标不足 | 统一提升到 `44px` |
| P2 | 断开 Outlook 连接没有确认，误操作风险高 | Disconnect 前增加浏览器确认弹窗 |
| P2 | 邮件正文中的明文链接触控高度过小 | 链接改为可换行的 `44px` 点击区域 |
| P2 | 邮件/日程列表头部在移动端按钮挤压 | 头部改为移动端纵向布局，操作按钮可换行 |

## 7. 剩余观察项

- 本轮自动化使用模拟 Outlook API 数据；真实 EWS 超时、鉴权失败、HTML 邮件复杂表格和超大正文仍需持续观察。
- 当前 Disconnect 使用浏览器原生确认弹窗，后续可统一为应用内确认 Dialog，以保持视觉一致性。