16 KiB

Raw Permalink Blame History Unescape Escape

产品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 文案
按钮：取消 | 确认提交

提交交互

Primary 点击 → 打开 Modal（本地校验先过）
Modal 确认 → Primary+Modal 双 loading；disabled
成功 → Toast success → 跳转 /logs?mail_id={id}
失败 → Toast error（展示 error.message）→ 留在本页；可再改再提（若 status 已 IMPORTING 则整页只读 + 「导入中，请稍后刷新」）
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 统一交互规则（写死）

所有触发写操作的按钮：点击即 loading + disabled，防重复提交。
所有 API 失败：全局 Toast error；表单字段错误额外内联。
所有必填/格式：失焦或提交前校验，不通过不发请求。
导入类写操作：必须二次确认 Modal。
货件表 ≥50 行：必须虚拟滚动（本系统确认页固定启用）。
状态更新：一期无 WS；用户点「刷新」或返回列表重进。
IMPORTING 期间：详情/确认页禁止再次提交；展示 Alert「导入进行中」。
色标旁必须有文字标签。

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 组件状态

页面级状态机（前端）：

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 硬约束（编码强制）

写操作按钮必须 loading + 防重复。
API 失败必须可见错误（禁止静默）。
表单校验失败禁止发请求。
导入提交必须二次确认 Modal。
货件表 ≥50 行必须虚拟滚动（confirm 页强制）。
空列表必须 EmptyState。
桌面优先，min-width 1280。
Tag/Pill 必须带文字，不只靠颜色。
confirm 直链：服务端/客户端双重校验 NEW + PENDING_CONFIRM。
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`

16 KiB Raw Permalink Blame History Unescape Escape