|
|
# 产品UI/UX设计方案 v1.0（邮件自动预报系统）
|
|
|
|
|
|
> 状态：可直接画原型 / 写前端（**2026-07-23 现行口径回写**）
|
|
|
> 依据：`docx/需求规格-邮件自动预报-v0.2.md`、`docx/技术设计方案-邮件自动预报-v1.0.md`
|
|
|
> UI 栈锁定：Ant Design 5 + TanStack Virtual（货件表）+ 本规范 Token
|
|
|
> **回写要点**：`/settings`；`/logs`=导入+拉取（无操作审计）；空态无种子；详情业务意图摘要替代得分表；详见 `docx/现行口径-修订说明-v1.md`
|
|
|
|
|
|
---
|
|
|
|
|
|
# 1. 信息架构（Information Architecture）
|
|
|
|
|
|
## 1.1 页面列表
|
|
|
|
|
|
| 页面 | 路由 | 职责 |
|
|
|
|---|---|---|
|
|
|
| 登录页 | `/login` | 账号密码登录；写 session Cookie |
|
|
|
| 邮件列表页 | `/mails` | 时间倒序展示邮件；按类型/状态筛选；进入详情 |
|
|
|
| 邮件详情页 | `/mails/[id]` | 摘要、正文、附件、证据、货件预览；重新解析；Admin 改类型；进入确认导入 |
|
|
|
| 确认导入页 | `/mails/[id]/confirm` | 柜头编辑；TransMode/OperationType；货件勾选（虚拟滚动）；二次确认后提交 CC |
|
|
|
| 导入日志/补偿页 | `/logs` | Tab：导入日志、拉取记录；失败重试 |
|
|
|
| 设置 | `/settings` | Admin：邮箱绑定、IMAP 间隔/过滤、CC、OAuth |
|
|
|
| Admin 改类型 | **详情页内 Modal**（非独立路由） | `ENABLE_TYPE_OVERRIDE`（及前端可见开关）+ `role=admin`；一期不写 audit_log |
|
|
|
|
|
|
不设 `/dashboard`、不设 `/admin/override` 独立页。登录后默认落点：`/mails`。
|
|
|
|
|
|
## 1.2 页面关系图
|
|
|
|
|
|
```
|
|
|
/login
|
|
|
→ /mails
|
|
|
→ /mails/[id]
|
|
|
→ /mails/[id]/confirm （mail_type=NEW_CONTAINER 且 status=PENDING_CONFIRM；或 Admin 改类型后满足条件）
|
|
|
→ /logs （提交结束：成功跳转；失败可停留 confirm 或跳 logs）
|
|
|
⇢ Modal「改类型」 （Admin）
|
|
|
⇢ 动作「重新解析」 （PARSE_FAILED / REJECTED_VALIDATION / 允许重解析的状态）
|
|
|
→ /logs （顶栏入口）
|
|
|
```
|
|
|
|
|
|
禁用路径：
|
|
|
- `mail_type ≠ NEW_CONTAINER` 且未改类型成功 → 不可进入 confirm（直链访问重定向详情 + Toast）
|
|
|
- `status ∈ {IMPORTING, SUCCESS}` → confirm 只读或重定向详情
|
|
|
|
|
|
## 1.3 路由结构（Next.js App Router）
|
|
|
|
|
|
```
|
|
|
/login
|
|
|
/mails
|
|
|
/mails/[id]
|
|
|
/mails/[id]/confirm
|
|
|
/logs
|
|
|
```
|
|
|
|
|
|
顶栏全局导航（登录后）：`邮件列表` | `日志` | `设置`(Admin) | 健康/IMAP/CC 状态 | `用户名` | `Admin` 徽标 | `退出`
|
|
|
|
|
|
---
|
|
|
|
|
|
# 2. 交互原型（Interaction Design）
|
|
|
|
|
|
## 2.0 全站壳层
|
|
|
|
|
|
```
|
|
|
┌──────────────────────────────────────────────────────────┐
|
|
|
│ TopNav: Logo「邮件预报」 | 导航链接 | 用户/Admin | 退出 │
|
|
|
├──────────────────────────────────────────────────────────┤
|
|
|
│ PageHeader: 标题 + 右侧主操作（按页） │
|
|
|
├──────────────────────────────────────────────────────────┤
|
|
|
│ MainContent（白底 Card 或铺满表） │
|
|
|
└──────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
- 最小视口宽：1280px
|
|
|
- 内容最大宽：1440px，水平居中
|
|
|
- Toast：右上角；Modal：居中
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.1 登录页 `/login`
|
|
|
|
|
|
**结构**
|
|
|
- 居中 Card（宽 400px）
|
|
|
- 标题：邮件自动预报
|
|
|
- 字段：用户名、密码
|
|
|
- 主按钮：登录
|
|
|
|
|
|
**交互**
|
|
|
- 提交 → 按钮 loading → 成功跳转 `/mails`；失败 Toast error + 字段下方文案
|
|
|
- 已登录访问 `/login` → 重定向 `/mails`
|
|
|
|
|
|
**空/错**
|
|
|
- 用户名或密码空 → 内联校验，不发请求
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.2 邮件列表页 `/mails`
|
|
|
|
|
|
**结构**
|
|
|
```
|
|
|
PageHeader: 「邮件列表」
|
|
|
FilterBar: [类型 Select] [状态 Select] [关键词 Input] [查询 Button]
|
|
|
MailTable（非卡片列表，密度优先用表格）:
|
|
|
列：类型Tag | 状态Pill | 主题 | 发件人 | 接收时间 | 柜号(若有)
|
|
|
Pagination: 底右，默认 pageSize=20
|
|
|
```
|
|
|
|
|
|
**交互**
|
|
|
- 行点击（整行可点）→ `/mails/[id]`
|
|
|
- 筛选变更 → 立即请求列表（防抖 300ms，关键词）
|
|
|
- 手动「刷新」按钮 → 重新拉列表（无 WebSocket）
|
|
|
|
|
|
**空态**
|
|
|
- 文案：暂无邮件，等待 IMAP 拉取
|
|
|
- 次按钮：刷新
|
|
|
|
|
|
**角标规则**
|
|
|
- 类型：左侧色点 8px + Tag 文字
|
|
|
- 状态：StatusPill 文字（不只靠颜色）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.3 邮件详情页 `/mails/[id]`
|
|
|
|
|
|
**结构**
|
|
|
```
|
|
|
PageHeader:
|
|
|
[← 返回列表] 主题（H1） StatusPill TypeTag
|
|
|
右侧操作组：
|
|
|
[重新解析]（条件可见）
|
|
|
[改类型]（Admin 条件可见）
|
|
|
[确认导入]（主按钮，条件启用）
|
|
|
|
|
|
SummaryStrip: 发件人 | 时间 | Message 状态
|
|
|
|
|
|
Tabs 或 纵向区块：
|
|
|
1) 正文摘要（等宽可读，max-height 240px 可滚动）
|
|
|
2) 附件列表：文件名 | 大小 | 下载
|
|
|
3) 业务意图摘要（动作/关键字/操作内容/转仓对；不展示得分分值）；type_evidence JSON 可选收起
|
|
|
4) 货件预览表（前 50 行 + 「共 N 行，确认导入页查看全部」链接）
|
|
|
```
|
|
|
|
|
|
**确认导入按钮启用条件（全部满足）**
|
|
|
- `mail_type === NEW_CONTAINER`
|
|
|
- `status === PENDING_CONFIRM`
|
|
|
- `valid_shipment_count >= 1`
|
|
|
|
|
|
**禁用时 Tooltip / 旁注文案（写死）**
|
|
|
- 类型非 NEW：`类型为 {mail_type}，一期不可导入`
|
|
|
- 状态非 PENDING_CONFIRM：`当前状态为 {status}，不可导入`
|
|
|
- 无有效行：`无有效货件行`
|
|
|
|
|
|
**交互**
|
|
|
- 确认导入 → `/mails/[id]/confirm`
|
|
|
- 重新解析 → POST reparse → 按钮 loading → 成功 Toast → 重新拉详情；失败 Toast
|
|
|
- 改类型 → 打开 `TypeOverrideModal`：
|
|
|
- Select 目标类型
|
|
|
- Input 原因（必填）
|
|
|
- 展示当前 type_evidence 摘要
|
|
|
- 确认 → loading → 审计成功 Toast → 刷新详情（可能出现确认导入可点）
|
|
|
|
|
|
**直链保护**
|
|
|
- 非法 id → 404 页：邮件不存在 + 回列表
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.4 确认导入页 `/mails/[id]/confirm`（核心）
|
|
|
|
|
|
**结构**
|
|
|
```
|
|
|
PageHeader:
|
|
|
[← 返回详情] 主题截断 | 柜号大号展示
|
|
|
右侧无第二主按钮（主 CTA 在底栏）
|
|
|
|
|
|
Section「柜头」Card 两列表单：
|
|
|
左列: TransMode* | OperationType* | ContainerNo* | CabinetType | Classis
|
|
|
右列: ETD | ETA | ShippingLineId（Select 可搜索，可空）| MemoRemark | Instruction
|
|
|
* 必填；ContainerNo 失焦触发 ISO 校验
|
|
|
|
|
|
Section「货件」Card：
|
|
|
Toolbar: [全选有效] [反选] [SearchInput: FBACode/ShipmentID] [有效 m / 无效 k]
|
|
|
VirtualTable 高度固定 480px:
|
|
|
列: ☑ | # | 仓库ID | 渠道 | 件数 | FBA ID | Ref | ShipmentID | 行状态 | 警告
|
|
|
INVALID 行: 背景 #F3F4F6，勾选 disabled，行状态 Tag=INVALID
|
|
|
|
|
|
StickyFooter（视口底）:
|
|
|
左: 已选 n / 有效 m
|
|
|
右: [取消] [确认导入 Primary]
|
|
|
```
|
|
|
|
|
|
**默认值**
|
|
|
- TransMode = 解析推荐或 `0`
|
|
|
- OperationType = 解析推荐或 `0`
|
|
|
- 勾选 = 全部 `VALID` 行
|
|
|
- `CHANNEL_UNMAPPED` 行可勾选，提交前若存在未 ack → 额外确认勾选「已知晓未映射渠道」
|
|
|
|
|
|
**二次确认 Modal**
|
|
|
- 标题：确认导入至 CarrierCentral
|
|
|
- 正文：`将向 CC 导入柜 {container_no}，货件 {n} 行`
|
|
|
- 展示 TransMode / OperationType 文案
|
|
|
- 按钮：取消 | 确认提交
|
|
|
|
|
|
**提交交互**
|
|
|
1. Primary 点击 → 打开 Modal（本地校验先过）
|
|
|
2. Modal 确认 → Primary+Modal 双 loading；`disabled`
|
|
|
3. 成功 → Toast success → 跳转 `/logs?mail_id={id}`
|
|
|
4. 失败 → Toast error（展示 `error.message`）→ 留在本页；可再改再提（若 status 已 IMPORTING 则整页只读 + 「导入中，请稍后刷新」）
|
|
|
5. `409 VERSION_CONFLICT` → Toast + 强制刷新页面数据
|
|
|
|
|
|
**校验（内联）**
|
|
|
- TransMode / OperationType 空 → 阻止 Modal
|
|
|
- ContainerNo 空或 ISO 失败 → 字段 Error
|
|
|
- n=0 → Primary disabled，文案：请至少勾选一行有效货件
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.5 导入日志/补偿页 `/logs`
|
|
|
|
|
|
**结构**
|
|
|
```
|
|
|
PageHeader: 「导入日志」 [返回邮件列表]
|
|
|
Filter: 状态 Select | 柜号/主题 Search
|
|
|
Table 列:
|
|
|
时间 | 邮件主题(链到详情) | 柜号 | 导入状态Pill | external_id | last_error | 操作
|
|
|
操作:
|
|
|
FAILED / TIMEOUT_UNKNOWN / CONFLICT(可重试类) → [重试]
|
|
|
SUCCESS → 显示 external_id，无重试
|
|
|
```
|
|
|
|
|
|
**交互**
|
|
|
- 重试 → 按钮 loading → Toast → 刷新行
|
|
|
- `COMPENSATION_EXHAUSTED` → 重试按钮对普通 ops 隐藏；Admin 显示「重置并重试」
|
|
|
|
|
|
**空态**
|
|
|
- 暂无导入记录
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2.6 统一交互规则（写死）
|
|
|
|
|
|
1. 所有触发写操作的按钮：点击即 `loading` + `disabled`，防重复提交。
|
|
|
2. 所有 API 失败：全局 Toast `error`；表单字段错误额外内联。
|
|
|
3. 所有必填/格式：失焦或提交前校验，不通过不发请求。
|
|
|
4. 导入类写操作：必须二次确认 Modal。
|
|
|
5. 货件表 ≥50 行：必须虚拟滚动（本系统确认页固定启用）。
|
|
|
6. 状态更新：一期无 WS；用户点「刷新」或返回列表重进。
|
|
|
7. IMPORTING 期间：详情/确认页禁止再次提交；展示 Alert「导入进行中」。
|
|
|
8. 色标旁必须有文字标签。
|
|
|
|
|
|
---
|
|
|
|
|
|
# 3. 视觉设计（Visual Design System）
|
|
|
|
|
|
## 3.1 色彩 Token
|
|
|
|
|
|
| Token | Hex | 用途 |
|
|
|
|---|---|---|
|
|
|
| `--color-primary` | `#2563EB` | 主按钮、链接、焦点 |
|
|
|
| `--color-primary-hover` | `#1D4ED8` | hover |
|
|
|
| `--color-success` | `#16A34A` | 成功 |
|
|
|
| `--color-warning` | `#F59E0B` | 警告/部分成功 |
|
|
|
| `--color-error` | `#DC2626` | 失败 |
|
|
|
| `--color-bg` | `#F8FAFC` | 页面底 |
|
|
|
| `--color-surface` | `#FFFFFF` | 卡片/表单 |
|
|
|
| `--color-text` | `#111827` | 主文字 |
|
|
|
| `--color-text-secondary` | `#6B7280` | 辅助 |
|
|
|
| `--color-border` | `#E5E7EB` | 边框 |
|
|
|
| `--color-disabled` | `#9CA3AF` | 禁用 |
|
|
|
|
|
|
**类型色（Tag 背景 / 文字白或深按对比度）**
|
|
|
|
|
|
| mail_type | 色 |
|
|
|
|---|---|
|
|
|
| NEW_CONTAINER | `#2563EB` |
|
|
|
| TRANSFER | `#F59E0B` |
|
|
|
| INSTRUCTION_HOLD_SPLIT | `#8B5CF6` |
|
|
|
| INSTRUCTION_LABEL | `#EC4899` |
|
|
|
| WORK_ORDER | `#0D9488` |
|
|
|
| UNKNOWN | `#6B7280` |
|
|
|
|
|
|
**状态色（StatusPill）**
|
|
|
|
|
|
| status | 色 |
|
|
|
|---|---|
|
|
|
| FETCHED / PARSING / PARSED | `#9CA3AF` |
|
|
|
| PENDING_CONFIRM | `#2563EB` |
|
|
|
| IMPORTING | `#F59E0B` |
|
|
|
| SUCCESS | `#16A34A` |
|
|
|
| PARTIAL_SUCCESS | `#F59E0B` |
|
|
|
| FAILED / PARSE_FAILED / REJECTED_VALIDATION | `#DC2626` |
|
|
|
| IGNORED | `#6B7280` |
|
|
|
|
|
|
## 3.2 字体
|
|
|
|
|
|
- 字体栈：`Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`
|
|
|
- H1：24px / 700 / 1.2
|
|
|
- H2：20px / 600 / 1.3
|
|
|
- Body：14px / 400 / 1.5
|
|
|
- Caption：12px / 400 / 1.4
|
|
|
- Small：11px / 400 / 1.3
|
|
|
- 等宽（证据 JSON）：`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` 12px
|
|
|
|
|
|
## 3.3 间距
|
|
|
|
|
|
`4 / 8 / 12 / 16 / 24 / 32 / 48 / 64`（px）
|
|
|
Card 内边距：16
|
|
|
区块间距：24
|
|
|
Filter 与表：16
|
|
|
|
|
|
## 3.4 圆角
|
|
|
|
|
|
| 元素 | 半径 |
|
|
|
|---|---|
|
|
|
| Button / Input | 6px |
|
|
|
| Card | 8px |
|
|
|
| Modal | 12px |
|
|
|
| Tag / Pill | 12px |
|
|
|
|
|
|
## 3.5 阴影
|
|
|
|
|
|
- Card：`0 1px 3px rgba(0,0,0,0.06), 0 1px 2px rgba(0,0,0,0.04)`
|
|
|
- Modal：`0 20px 60px rgba(0,0,0,0.15)`
|
|
|
|
|
|
## 3.6 组件视觉规格
|
|
|
|
|
|
| 组件 | 规格 |
|
|
|
|---|---|
|
|
|
| PrimaryButton | bg primary，文字白，h=36，px=16，radius 6；hover primary-hover；loading 内嵌 Spinner |
|
|
|
| SecondaryButton | bg 白，border primary，文字 primary |
|
|
|
| DangerButton | bg error，文字白 |
|
|
|
| Input / Select | h=36，border 1px border-color，focus：ring 2px primary 30% |
|
|
|
| Card | surface + shadow + radius 8 + p16 |
|
|
|
| Tag | h=22，px=8，文字 12px |
|
|
|
| StatusPill | 同 Tag |
|
|
|
| Table header | bg `#F9FAFB`，文字 secondary，字重 600 |
|
|
|
| INVALID 行 | bg `#F3F4F6`，文字 secondary |
|
|
|
| StickyFooter | 白底，上边框 border，h=56，z-index 10 |
|
|
|
| Toast success/error/warning | 对应色左边条 4px |
|
|
|
|
|
|
---
|
|
|
|
|
|
# 4. 设计规范（Design System for AI Coding）
|
|
|
|
|
|
## 4.1 React 组件清单（映射 Antd）
|
|
|
|
|
|
| 设计组件 | 实现映射 |
|
|
|
|---|---|
|
|
|
| `PrimaryButton` | `Button type="primary"` |
|
|
|
| `SecondaryButton` | `Button` |
|
|
|
| `DangerButton` | `Button danger` |
|
|
|
| `InputField` | `Form.Item` + `Input` |
|
|
|
| `SelectField` | `Form.Item` + `Select` |
|
|
|
| `DatePickerField` | `Form.Item` + `DatePicker` |
|
|
|
| `Checkbox` | `Checkbox` |
|
|
|
| `AppCard` | `Card` |
|
|
|
| `MailTable` | `Table` |
|
|
|
| `ShipmentVirtualTable` | 自研：TanStack Virtual + 行渲染 |
|
|
|
| `TypeTag` | `Tag` + 类型色 |
|
|
|
| `StatusPill` | `Tag` + 状态色 |
|
|
|
| `LoadingSpinner` | `Spin` |
|
|
|
| `ErrorBanner` | `Alert type="error"` |
|
|
|
| `AppToast` | `message` / `notification` |
|
|
|
| `ConfirmModal` | `Modal.confirm` 或受控 `Modal` |
|
|
|
| `SearchInput` | `Input.Search` |
|
|
|
| `Pagination` | `Pagination` |
|
|
|
| `TypeOverrideModal` | 受控 `Modal` + Form |
|
|
|
| `TopNav` | `Layout.Header` + `Menu` |
|
|
|
| `EmptyState` | `Empty` |
|
|
|
|
|
|
页面组件命名：
|
|
|
- `LoginPage`
|
|
|
- `MailListPage`
|
|
|
- `MailDetailPage`
|
|
|
- `MailConfirmPage`
|
|
|
- `ImportLogsPage`
|
|
|
|
|
|
## 4.2 组件状态
|
|
|
|
|
|
每个可交互组件支持：`idle | loading | success | error | disabled | empty`（按上下文取用）。
|
|
|
|
|
|
页面级状态机（前端）：
|
|
|
- `pageStatus: idle | loading | error`
|
|
|
- 详情另：`actionLoading: reparse | override | none`
|
|
|
- 确认页另：`submitPhase: idle | validating | confirming | submitting`
|
|
|
|
|
|
## 4.3 命名规范
|
|
|
|
|
|
- 组件：PascalCase
|
|
|
- 路由文件：`page.tsx` 于 `app/mails/[id]/confirm/page.tsx`
|
|
|
- 状态布尔：`isLoading` `isSubmitting` `isAdmin`
|
|
|
- 文案常量：`src/constants/ui-copy.ts`
|
|
|
- Token CSS 变量：`--color-*` 写入 `globals.css`
|
|
|
|
|
|
## 4.4 UI 硬约束（编码强制）
|
|
|
|
|
|
1. 写操作按钮必须 `loading` + 防重复。
|
|
|
2. API 失败必须可见错误（禁止静默）。
|
|
|
3. 表单校验失败禁止发请求。
|
|
|
4. 导入提交必须二次确认 Modal。
|
|
|
5. 货件表 ≥50 行必须虚拟滚动（confirm 页强制）。
|
|
|
6. 空列表必须 EmptyState。
|
|
|
7. 桌面优先，min-width 1280。
|
|
|
8. Tag/Pill 必须带文字，不只靠颜色。
|
|
|
9. confirm 直链：服务端/客户端双重校验 NEW + PENDING_CONFIRM。
|
|
|
10. Admin 改类型按钮：仅 `isAdmin && enableTypeOverride` 渲染。
|
|
|
|
|
|
## 4.5 文案常量（摘录）
|
|
|
|
|
|
| key | 中文 |
|
|
|
|---|---|
|
|
|
| `empty.mails` | 暂无邮件，等待 IMAP 拉取 |
|
|
|
| `btn.confirmImport` | 确认导入 |
|
|
|
| `btn.reparse` | 重新解析 |
|
|
|
| `btn.overrideType` | 改类型 |
|
|
|
| `btn.retry` | 重试 |
|
|
|
| `modal.import.title` | 确认导入至 CarrierCentral |
|
|
|
| `modal.import.body` | 将向 CC 导入柜 {no}，货件 {n} 行 |
|
|
|
| `disable.notNew` | 类型为 {type}，一期不可导入 |
|
|
|
| `disable.badStatus` | 当前状态为 {status}，不可导入 |
|
|
|
| `alert.importing` | 导入进行中，请稍后刷新查看结果 |
|
|
|
| `ack.unmapped` | 已知晓存在未映射渠道，仍提交原值 |
|
|
|
|
|
|
## 4.6 线框尺寸速查
|
|
|
|
|
|
| 区域 | 尺寸 |
|
|
|
|---|---|
|
|
|
| TopNav 高 | 56px |
|
|
|
| PageHeader 高 | 64px |
|
|
|
| FilterBar 高 | 48px |
|
|
|
| 确认页 VirtualTable | 高 480px |
|
|
|
| StickyFooter | 高 56px |
|
|
|
| 登录 Card | 宽 400px |
|
|
|
| Modal 宽 | 480px（改类型）/ 520px（导入确认） |
|
|
|
|
|
|
---
|
|
|
|
|
|
# 5. 页面 ↔ API 绑定（供前端直接接线）
|
|
|
|
|
|
| 页面 | 主要 API |
|
|
|
|---|---|
|
|
|
| Login | `POST /api/auth/login` |
|
|
|
| MailList | `GET /api/mails` |
|
|
|
| MailDetail | `GET /api/mails/:id`；`POST .../reparse`；`POST .../type` |
|
|
|
| Confirm | `POST /api/mails/:id/import` |
|
|
|
| Logs | `GET /api/imports`；`POST /api/imports/:id/retry` |
|
|
|
|
|
|
---
|
|
|
|
|
|
# 6. 文档索引
|
|
|
|
|
|
| 文档 | 路径 |
|
|
|
|---|---|
|
|
|
| 本设计 | `docx/产品UI-UX设计方案-邮件自动预报-v1.0.md` |
|
|
|
| PRD | `docx/需求规格-邮件自动预报-v0.2.md` |
|
|
|
| 技术设计 | `docx/技术设计方案-邮件自动预报-v1.0.md` |
|
