|
|
# 查价系统 产品 UI/UX 设计方案 v1.0
|
|
|
|
|
|
| 版本 | 日期 | 作者 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| v1.0 | 2026-06-16 | 产品设计/UI/UX | 可直接用于前端开发与 Cursor 生成代码 |
|
|
|
|
|
|
> 配套文档：[查价系统-PRD.md](./查价系统-PRD.md) · [查价系统-技术设计.md](./查价系统-技术设计.md)
|
|
|
> 技术栈：Next.js 15 App Router · Tailwind CSS · shadcn/ui（定制 token）· Geist 字体
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 信息架构（Information Architecture）
|
|
|
|
|
|
### 1.1 页面列表
|
|
|
|
|
|
| 编号 | 页面名称 | 路由 | 角色 | 优先级 |
|
|
|
|------|----------|------|------|--------|
|
|
|
| P01 | 登录页 | `/login` | 全部 | P0 |
|
|
|
| P02 | 工作台 | `/dashboard` | customer / operator / admin | P0 |
|
|
|
| P03 | 卡派查价页 | `/quote` | customer | P0 |
|
|
|
| P04 | 询价结果页 | `/quote/result/[quoteId]` | customer | P0 |
|
|
|
| P05 | 询价历史 | `/history` | customer | P0 |
|
|
|
| P06 | 加价配置 | `/admin/markup` | operator / admin | P0 |
|
|
|
| P07 | 预警中心 | `/admin/alerts` | admin | P0 |
|
|
|
| P08 | 403 无权限 | `/403` | 全部 | P1 |
|
|
|
| P09 | 404 未找到 | `/not-found` | 全部 | P1 |
|
|
|
|
|
|
**MVP 不包含页面**：注册页、个人设置、CC 对接页、下单页、多币种设置页。
|
|
|
|
|
|
### 1.2 页面关系图
|
|
|
|
|
|
```
|
|
|
登录页 (/login)
|
|
|
│
|
|
|
├─ customer ──► 工作台 (/dashboard)
|
|
|
│ │
|
|
|
│ ├─► 卡派查价 (/quote)
|
|
|
│ │ │
|
|
|
│ │ └─► 询价结果 (/quote/result/:quoteId)
|
|
|
│ │
|
|
|
│ └─► 询价历史 (/history)
|
|
|
│ │
|
|
|
│ └─► 询价结果 (/quote/result/:quoteId)
|
|
|
│
|
|
|
├─ operator ──► 工作台 (/dashboard)
|
|
|
│ └─► 加价配置 (/admin/markup)
|
|
|
│
|
|
|
└─ admin ──► 工作台 (/dashboard)
|
|
|
├─► 加价配置 (/admin/markup)
|
|
|
└─► 预警中心 (/admin/alerts)
|
|
|
```
|
|
|
|
|
|
**全局规则**：
|
|
|
- 未登录访问受保护路由 → 重定向 `/login?redirect={path}`
|
|
|
- `customer` 访问 `/admin/*` → `/403`
|
|
|
- `operator` 访问 `/admin/alerts` → `/403`
|
|
|
- 登录成功默认跳转 `/dashboard`
|
|
|
|
|
|
### 1.3 路由结构（Next.js App Router）
|
|
|
|
|
|
```
|
|
|
app/
|
|
|
├── login/page.tsx # P01
|
|
|
├── dashboard/page.tsx # P02
|
|
|
├── quote/
|
|
|
│ ├── page.tsx # P03
|
|
|
│ └── result/[quoteId]/page.tsx # P04
|
|
|
├── history/page.tsx # P05
|
|
|
├── admin/
|
|
|
│ ├── markup/page.tsx # P06
|
|
|
│ └── alerts/page.tsx # P07
|
|
|
├── 403/page.tsx # P08
|
|
|
└── not-found.tsx # P09
|
|
|
```
|
|
|
|
|
|
| 路由 | 鉴权 | 布局 |
|
|
|
|------|------|------|
|
|
|
| `/login` | 公开 | `AuthLayout`（无侧边栏） |
|
|
|
| `/dashboard` | JWT | `AppLayout` |
|
|
|
| `/quote` | JWT + customer | `AppLayout` |
|
|
|
| `/quote/result/[quoteId]` | JWT + customer（本人） | `AppLayout` |
|
|
|
| `/history` | JWT + customer | `AppLayout` |
|
|
|
| `/admin/markup` | JWT + operator/admin | `AdminLayout` |
|
|
|
| `/admin/alerts` | JWT + admin | `AdminLayout` |
|
|
|
|
|
|
### 1.4 导航结构
|
|
|
|
|
|
**客户侧 `AppLayout` 顶栏**：
|
|
|
- Logo「美美与共 · 卡派查价」
|
|
|
- 导航：工作台 | 卡派查价 | 询价历史
|
|
|
- 右侧：客户 ID + 退出
|
|
|
|
|
|
**管理侧 `AdminLayout` 顶栏 + 侧栏**：
|
|
|
- 侧栏：工作台 | 加价配置 | 预警中心（admin 可见）
|
|
|
- 顶栏：角色标签 + 退出
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 交互原型（Interaction Design）
|
|
|
|
|
|
### 2.1 全局交互规则
|
|
|
|
|
|
| 规则 ID | 规则 |
|
|
|
|---------|------|
|
|
|
| IX-01 | 所有提交按钮点击后 `disabled` + `loading`，最短 3s |
|
|
|
| IX-02 | 表单字段 `onBlur` 触发校验；错误文案显示在字段下方 |
|
|
|
| IX-03 | API 错误统一用 `ErrorBanner` 展示在页面主内容区顶部 |
|
|
|
| IX-04 | 查价接口 `Cache-Control: no-store`，禁止浏览器缓存 |
|
|
|
| IX-05 | 金额展示固定 `USD`，格式 `$1,234.56` |
|
|
|
| IX-06 | 所有异步操作最长等待 30s，超时展示可重试入口 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.2 P01 登录页 `/login`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：Logo + 产品名
|
|
|
- 主区：登录卡片（用户名、密码）
|
|
|
- 操作区：登录按钮
|
|
|
|
|
|
**状态**：`idle` | `loading` | `error` | `success`
|
|
|
|
|
|
| 状态 | UI |
|
|
|
|------|-----|
|
|
|
| idle | 表单可编辑，按钮「登录」 |
|
|
|
| loading | 按钮 loading，输入框 disabled |
|
|
|
| error | ErrorBanner「用户名或密码错误」 |
|
|
|
| success | 跳转 `/dashboard` |
|
|
|
|
|
|
**按钮行为**：点击 → `POST /api/auth/login` → 存 token → 按角色跳转
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.3 P02 工作台 `/dashboard`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：欢迎语 + 角色
|
|
|
- 主区：快捷入口卡片（按角色渲染）
|
|
|
- 操作区：无
|
|
|
|
|
|
**客户卡片**：「卡派查价」「询价历史」
|
|
|
**运营卡片**：「加价配置」
|
|
|
**管理员卡片**：「加价配置」「预警中心」+ 未处理预警数量角标
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.4 P03 卡派查价页 `/quote`（核心）
|
|
|
|
|
|
**页面结构**：
|
|
|
```
|
|
|
┌─────────────────────────────────────────────┐
|
|
|
│ Header（AppLayout 顶栏） │
|
|
|
├─────────────────────────────────────────────┤
|
|
|
│ 页面标题：卡派查价 │
|
|
|
│ 副标题：填写货物信息，获取实时报价（约 30 秒内） │
|
|
|
├──────────────────┬──────────────────────────┤
|
|
|
│ 主输入区（左 60%） │ 结果区（右 40%，空时占位） │
|
|
|
│ QuoteForm │ QuoteResultPanel │
|
|
|
├──────────────────┴──────────────────────────┤
|
|
|
│ 操作区：获取报价（PrimaryButton） │
|
|
|
└─────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
**移动端（<768px）**：单列；输入区在上，结果区在下。
|
|
|
|
|
|
**页面状态机**：
|
|
|
|
|
|
| 状态 | 触发 | 输入区 | 结果区 | 操作区 |
|
|
|
|------|------|--------|--------|--------|
|
|
|
| `idle` | 进入页面 | 可编辑 | 空状态插画 +「填写信息后获取报价」 | 按钮可点 |
|
|
|
| `validating` | 点击提交 | 只读 | 不变 | 按钮 loading |
|
|
|
| `processing` | POST 成功且 status=processing | 只读 | Skeleton +「正在查询报价…」+ 进度条（0–30s） | 按钮 disabled |
|
|
|
| `success` | GET status=done 且 is_realtime=true | 可编辑（新询价生成新 request_id） | QuoteCard 双等级 | 按钮可点 |
|
|
|
| `fallback` | GET status=done 且 is_realtime=false | 同 success | QuoteCard + WarningBanner「非实时报价，仅供参考」 | 按钮可点 |
|
|
|
| `error` | GET status=failed 或超时 | 可编辑 | ErrorBanner + 重试按钮 | 按钮可点 |
|
|
|
| `expired` | 倒计时归零 | 可编辑 | 蒙层 +「报价已过期」ConfirmDialog | 确认后回到 idle |
|
|
|
|
|
|
**关键交互**：
|
|
|
|
|
|
1. 点击「获取报价」→ 前端生成 `request_id`(UUID v4) → `POST /api/quotes`
|
|
|
2. 若立即 `done`（L1/L2 命中）→ 直接 `success`/`fallback`
|
|
|
3. 若 `processing` → 每 2s `GET /api/quotes/{quoteId}`，最多 15 次
|
|
|
4. `success` 后展示 3 分钟倒计时 `CountdownTimer`；<30s 时文字变 Warning 色
|
|
|
5. 防重复：提交后按钮 disabled 3000ms；相同 request_id 由后端幂等
|
|
|
|
|
|
**表单字段布局（QuoteForm）**：
|
|
|
|
|
|
| 分组 | 字段 |
|
|
|
|------|------|
|
|
|
| 提货地址 | 街道、城市、州（2 字母）、邮编 |
|
|
|
| 派送地址 | 同上 |
|
|
|
| 货物信息 | 重量+单位、长×宽×高+单位、件数、货物类型（Select） |
|
|
|
| 偏好 | 单位制（公制/英制）、默认展示等级（标准/保证送达） |
|
|
|
|
|
|
**即时校验**：
|
|
|
|
|
|
| 字段 | 规则 | 错误文案 |
|
|
|
|------|------|----------|
|
|
|
| 邮编 | `^\d{5}(-\d{4})?$` | 邮编格式无效 |
|
|
|
| 重量 | 1–50000（换算后 lb） | 重量超出范围 |
|
|
|
| 件数 | 1–999 整数 | 件数无效 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.5 P04 询价结果页 `/quote/result/[quoteId]`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：面包屑「卡派查价 / 报价详情」
|
|
|
- 主区：QuoteCard（双等级 Tab）+ 明细 breakdown
|
|
|
- 操作区：「重新询价」「查看历史」
|
|
|
|
|
|
**状态**：`loading` | `success` | `fallback` | `error` | `expired`
|
|
|
|
|
|
| 状态 | UI |
|
|
|
|------|-----|
|
|
|
| loading | 全页 Skeleton |
|
|
|
| success | QuoteCard + CountdownTimer |
|
|
|
| fallback | QuoteCard + WarningBanner |
|
|
|
| error | ErrorBanner「无法获取报价」 |
|
|
|
| expired | 过期提示 + 跳转 `/quote` 按钮 |
|
|
|
|
|
|
**数据来源**：`GET /api/quotes/{quoteId}`
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.6 P05 询价历史 `/history`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：标题「询价历史」
|
|
|
- 主区：表格（时间、路线摘要、价格、来源、状态）
|
|
|
- 操作区：分页器（page/size 必填）
|
|
|
|
|
|
**状态**：`loading` | `success` | `empty` | `error`
|
|
|
|
|
|
| 状态 | UI |
|
|
|
|------|-----|
|
|
|
| loading | 表格 Skeleton 5 行 |
|
|
|
| success | 数据表格 + 分页 |
|
|
|
| empty | EmptyState「暂无询价记录」+ 按钮「去查价」 |
|
|
|
| error | ErrorBanner |
|
|
|
|
|
|
**行点击**：跳转 `/quote/result/{quoteId}`
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.7 P06 加价配置 `/admin/markup`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：标题 + 搜索框（customer_id）
|
|
|
- 主区：表格（客户 ID、加价比例、操作人、更新时间、操作）
|
|
|
- 操作区：分页
|
|
|
|
|
|
**编辑交互**：行内「编辑」→ 右侧 Drawer
|
|
|
- 字段：加价比例（NumberInput，0–30，步长 0.1）
|
|
|
- 按钮：保存（Primary）/ 取消（Secondary）
|
|
|
|
|
|
**状态**：`loading` | `success` | `empty` | `error` | `saving`
|
|
|
|
|
|
| 状态 | UI |
|
|
|
|------|-----|
|
|
|
| saving | 保存按钮 loading，Drawer 内字段 disabled |
|
|
|
| 校验失败 | 字段下「加价比例不能超过 30%」 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.8 P07 预警中心 `/admin/alerts`
|
|
|
|
|
|
**页面结构**：
|
|
|
- Header：标题 + 筛选（类型、状态 open/resolved）
|
|
|
- 主区：表格（时间、类型、quote_id、偏差%、状态）
|
|
|
- 详情：行点击展开 Drawer（detail_json）
|
|
|
- 操作区：「标记已处理」
|
|
|
|
|
|
**预警类型标签色**：
|
|
|
|
|
|
| 类型 | 标签色 |
|
|
|
|------|--------|
|
|
|
| PRICE_DEVIATION | Warning |
|
|
|
| STALE_FALLBACK | Warning |
|
|
|
| RPA_FAILED | Error |
|
|
|
| RPA_CAPTCHA | Error |
|
|
|
| STRUCT_CHANGE | Error |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 视觉设计（Visual Design System）
|
|
|
|
|
|
### 3.1 色彩系统
|
|
|
|
|
|
| Token | HEX | 用途 |
|
|
|
|-------|-----|------|
|
|
|
| `--color-primary` | `#0D9488` | 主按钮、链接、焦点环 |
|
|
|
| `--color-primary-hover` | `#0F766E` | 主按钮 hover |
|
|
|
| `--color-primary-active` | `#115E59` | 主按钮 active |
|
|
|
| `--color-success` | `#16A34A` | 成功状态、实时报价标识 |
|
|
|
| `--color-warning` | `#D97706` | 非实时角标、倒计时 <30s、预警 |
|
|
|
| `--color-error` | `#DC2626` | 错误、失败状态 |
|
|
|
| `--color-bg` | `#F8FAFC` | 页面背景 |
|
|
|
| `--color-surface` | `#FFFFFF` | 卡片、表单背景 |
|
|
|
| `--color-border` | `#E2E8F0` | 分割线、输入框边框 |
|
|
|
| `--color-text-primary` | `#0F172A` | 标题、正文 |
|
|
|
| `--color-text-secondary` | `#64748B` | 辅助说明、标签 |
|
|
|
| `--color-text-disabled` | `#94A3B8` | 禁用文字 |
|
|
|
|
|
|
**Tailwind 映射**：primary=`teal-600`，neutral=`slate`
|
|
|
|
|
|
### 3.2 字体系统
|
|
|
|
|
|
| Token | 字体 | 字号 | 字重 | 行高 | 用途 |
|
|
|
|-------|------|------|------|------|------|
|
|
|
| `--font-display` | Geist Sans | 30px / 1.875rem | 600 | 1.2 | 页面 H1 |
|
|
|
| `--font-h2` | Geist Sans | 24px / 1.5rem | 600 | 1.3 | 区块标题 |
|
|
|
| `--font-h3` | Geist Sans | 18px / 1.125rem | 600 | 1.4 | 卡片标题 |
|
|
|
| `--font-body` | Geist Sans | 16px / 1rem | 400 | 1.6 | 正文 |
|
|
|
| `--font-caption` | Geist Sans | 14px / 0.875rem | 400 | 1.5 | 辅助说明 |
|
|
|
| `--font-label` | Geist Sans | 14px / 0.875rem | 500 | 1.4 | 表单标签 |
|
|
|
| `--font-mono` | Geist Mono | 16px / 1rem | 500 | 1.4 | 金额、quote_id |
|
|
|
|
|
|
**规则**：
|
|
|
- 金额、单号使用 `font-mono`
|
|
|
- 正文最大宽度 `max-w-[65ch]`
|
|
|
|
|
|
### 3.3 间距系统（Spacing）
|
|
|
|
|
|
| Token | 值 | 用途 |
|
|
|
|-------|-----|------|
|
|
|
| `--space-1` | 4px | 图标与文字间距 |
|
|
|
| `--space-2` | 8px | 字段内 padding、标签间距 |
|
|
|
| `--space-3` | 12px | 紧凑列表项 |
|
|
|
| `--space-4` | 16px | 表单项间距、卡片内 padding |
|
|
|
| `--space-6` | 24px | 区块间距 |
|
|
|
| `--space-8` | 32px | 页面边距、卡片间距 |
|
|
|
|
|
|
**页面边距**：`px-4 md:px-6 lg:px-8`；内容区 `max-w-7xl mx-auto`
|
|
|
|
|
|
### 3.4 圆角系统
|
|
|
|
|
|
| Token | 值 | 用途 |
|
|
|
|-------|-----|------|
|
|
|
| `--radius-sm` | 6px | 输入框、标签 |
|
|
|
| `--radius-md` | 8px | 按钮 |
|
|
|
| `--radius-lg` | 12px | 卡片 |
|
|
|
| `--radius-xl` | 16px | 弹窗 |
|
|
|
|
|
|
### 3.5 阴影系统
|
|
|
|
|
|
| Token | 值 | 用途 |
|
|
|
|-------|-----|------|
|
|
|
| `--shadow-card` | `0 1px 3px rgba(15,23,42,0.06), 0 1px 2px rgba(15,23,42,0.04)` | 卡片 |
|
|
|
| `--shadow-modal` | `0 10px 25px rgba(15,23,42,0.12)` | 弹窗、Drawer |
|
|
|
| `--shadow-none` | none | 表格行、内嵌面板 |
|
|
|
|
|
|
### 3.6 组件风格
|
|
|
|
|
|
#### Button
|
|
|
|
|
|
| 变体 | 背景 | 文字 | 边框 | 高度 |
|
|
|
|------|------|------|------|------|
|
|
|
| Primary | `#0D9488` | `#FFFFFF` | none | 40px |
|
|
|
| Secondary | `#FFFFFF` | `#0F172A` | `#E2E8F0` | 40px |
|
|
|
| Ghost | transparent | `#0D9488` | none | 40px |
|
|
|
| Danger | `#DC2626` | `#FFFFFF` | none | 40px |
|
|
|
|
|
|
`border-radius: 8px`；`padding: 0 16px`；loading 时左侧 16px 旋转 Spinner
|
|
|
|
|
|
#### Input
|
|
|
|
|
|
- 高度 40px；`border: 1px solid #E2E8F0`；`radius: 6px`
|
|
|
- Focus：`ring-2 ring-teal-600/20 border-teal-600`
|
|
|
- Error：`border-error` + 下方 12px 红色 caption
|
|
|
|
|
|
#### Card（QuoteCard）
|
|
|
|
|
|
- 背景 `#FFFFFF`；`border: 1px solid #E2E8F0`；`radius: 12px`；`padding: 24px`；`shadow-card`
|
|
|
- 顶部 Tab：「标准」「保证送达」
|
|
|
- 价格区：`font-mono text-3xl font-semibold`
|
|
|
- 非实时角标：右上角 Warning 色 pill「非实时报价，仅供参考」
|
|
|
|
|
|
#### Loading
|
|
|
|
|
|
- 全页/区块：Skeleton（灰条 `bg-slate-200 animate-pulse`）
|
|
|
- 按钮内：`Spinner` 16×16，`border-2 border-white/30 border-t-white`
|
|
|
- 查价进度：线性进度条 + 文案「正在查询报价…（{elapsed}s / 30s）」
|
|
|
|
|
|
#### Error 提示
|
|
|
|
|
|
- `ErrorBanner`：背景 `#FEF2F2`，左边框 4px `#DC2626`，内边距 16px
|
|
|
- `WarningBanner`：背景 `#FFFBEB`，左边框 4px `#D97706`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 设计规范（Design System for AI Coding）
|
|
|
|
|
|
### 4.1 UI 组件清单
|
|
|
|
|
|
| 组件名 | 路径 | 用途 |
|
|
|
|--------|------|------|
|
|
|
| `PrimaryButton` | `components/ui/primary-button.tsx` | 主操作 |
|
|
|
| `SecondaryButton` | `components/ui/secondary-button.tsx` | 取消、次要操作 |
|
|
|
| `InputField` | `components/ui/input-field.tsx` | 文本输入 + label + error |
|
|
|
| `SelectField` | `components/ui/select-field.tsx` | 货物类型、州 |
|
|
|
| `QuoteForm` | `components/quote/quote-form.tsx` | 查价表单 |
|
|
|
| `QuoteCard` | `components/quote/quote-card.tsx` | 双等级报价展示 |
|
|
|
| `QuoteResultPanel` | `components/quote/quote-result-panel.tsx` | 结果区容器（含状态切换） |
|
|
|
| `CountdownTimer` | `components/quote/countdown-timer.tsx` | 3 分钟倒计时 |
|
|
|
| `LoadingSpinner` | `components/ui/loading-spinner.tsx` | 按钮/行内 loading |
|
|
|
| `Skeleton` | `components/ui/skeleton.tsx` | 骨架屏 |
|
|
|
| `ErrorBanner` | `components/ui/error-banner.tsx` | 错误提示 |
|
|
|
| `WarningBanner` | `components/ui/warning-banner.tsx` | 非实时/预警提示 |
|
|
|
| `EmptyState` | `components/ui/empty-state.tsx` | 空列表 |
|
|
|
| `ConfirmDialog` | `components/ui/confirm-dialog.tsx` | 过期重询确认 |
|
|
|
| `DataTable` | `components/ui/data-table.tsx` | 历史/加价/预警表格 |
|
|
|
| `PageHeader` | `components/layout/page-header.tsx` | 标题区 |
|
|
|
| `AppLayout` | `components/layout/app-layout.tsx` | 客户布局 |
|
|
|
| `AdminLayout` | `components/layout/admin-layout.tsx` | 管理端布局 |
|
|
|
|
|
|
### 4.2 状态规范（统一枚举）
|
|
|
|
|
|
```typescript
|
|
|
// 查价页
|
|
|
type QuotePageStatus =
|
|
|
| 'idle'
|
|
|
| 'validating'
|
|
|
| 'processing'
|
|
|
| 'success'
|
|
|
| 'fallback'
|
|
|
| 'error'
|
|
|
| 'expired';
|
|
|
|
|
|
// 通用数据页
|
|
|
type DataPageStatus = 'loading' | 'success' | 'empty' | 'error';
|
|
|
|
|
|
// 按钮
|
|
|
type ButtonState = 'default' | 'loading' | 'disabled';
|
|
|
```
|
|
|
|
|
|
| 状态 | 视觉 | 交互 |
|
|
|
|------|------|------|
|
|
|
| loading | Skeleton 或 Spinner | 禁止重复提交 |
|
|
|
| success | 正常内容 + Success/Primary 强调 | 可操作 |
|
|
|
| error | ErrorBanner | 展示重试 |
|
|
|
| empty | EmptyState 插画 + CTA | 引导主路径 |
|
|
|
| disabled | opacity 0.5 + cursor-not-allowed | 不响应点击 |
|
|
|
|
|
|
### 4.3 命名规范
|
|
|
|
|
|
| 类型 | 规则 | 示例 |
|
|
|
|------|------|------|
|
|
|
| React 组件 | PascalCase | `QuoteCard` |
|
|
|
| 文件 | kebab-case | `quote-card.tsx` |
|
|
|
| Props 接口 | 组件名 + Props | `QuoteCardProps` |
|
|
|
| 页面状态 hook | use + 页面 + Status | `useQuotePageStatus` |
|
|
|
| Tailwind class | 语义组合，禁止随意 magic number | `text-text-secondary` 用 CSS 变量 |
|
|
|
| API 状态字段 | 与 PRD 一致 | `status`, `is_realtime`, `source_type` |
|
|
|
|
|
|
### 4.4 UI 约束规则（写死）
|
|
|
|
|
|
| ID | 规则 |
|
|
|
|----|------|
|
|
|
| UI-01 | 所有触发 API 的按钮必须有 `loading` 状态 |
|
|
|
| UI-02 | 所有 API 请求必须有 `error` 状态展示（ErrorBanner） |
|
|
|
| UI-03 | 所有表单字段必须有 `validation` 状态（字段下错误文案） |
|
|
|
| UI-04 | 查价提交按钮提交后 disabled 3000ms |
|
|
|
| UI-05 | 轮询最长 30s，超时进入 `error` 状态 |
|
|
|
| UI-06 | `is_realtime=false` 必须显示 WarningBanner，不可隐藏 |
|
|
|
| UI-07 | 金额必须用 `font-mono`，保留 2 位小数 |
|
|
|
| UI-08 | 界面文案全部中文 |
|
|
|
| UI-09 | 禁止使用 emoji 作为 UI 图标；使用 `@phosphor-icons/react` |
|
|
|
| UI-10 | 移动端所有页面单列布局，禁止横向滚动 |
|
|
|
| UI-11 | 全高区域使用 `min-h-[100dvh]`，禁止 `h-screen` |
|
|
|
|
|
|
### 4.5 Tailwind 配置片段（globals.css）
|
|
|
|
|
|
```css
|
|
|
@tailwind base;
|
|
|
@tailwind components;
|
|
|
@tailwind utilities;
|
|
|
|
|
|
:root {
|
|
|
--color-primary: #0d9488;
|
|
|
--color-primary-hover: #0f766e;
|
|
|
--color-success: #16a34a;
|
|
|
--color-warning: #d97706;
|
|
|
--color-error: #dc2626;
|
|
|
--color-bg: #f8fafc;
|
|
|
--color-surface: #ffffff;
|
|
|
--color-border: #e2e8f0;
|
|
|
--color-text-primary: #0f172a;
|
|
|
--color-text-secondary: #64748b;
|
|
|
--radius-md: 8px;
|
|
|
--radius-lg: 12px;
|
|
|
--space-4: 16px;
|
|
|
--space-6: 24px;
|
|
|
--space-8: 32px;
|
|
|
}
|
|
|
|
|
|
body {
|
|
|
@apply bg-[var(--color-bg)] text-[var(--color-text-primary)] antialiased;
|
|
|
font-family: var(--font-geist-sans), system-ui, sans-serif;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 4.6 响应式断点
|
|
|
|
|
|
| 断点 | 宽度 | 布局规则 |
|
|
|
|------|------|----------|
|
|
|
| default | <768px | 单列；查价表单全宽；隐藏侧栏改底部 Tab |
|
|
|
| `md` | ≥768px | 查价页左右 60/40 分栏 |
|
|
|
| `lg` | ≥1024px | 管理端显示固定侧栏 240px |
|
|
|
| `xl` | ≥1280px | 内容区 `max-w-7xl` 居中 |
|
|
|
|
|
|
### 4.7 页面 ↔ 组件映射（Cursor 直接生成）
|
|
|
|
|
|
| 页面 | 主要组件 |
|
|
|
|------|----------|
|
|
|
| `/login` | `InputField` ×2, `PrimaryButton`, `ErrorBanner` |
|
|
|
| `/dashboard` | `PageHeader`, 快捷入口 Card ×N |
|
|
|
| `/quote` | `QuoteForm`, `QuoteResultPanel`, `QuoteCard`, `CountdownTimer`, `ConfirmDialog` |
|
|
|
| `/quote/result/[id]` | `QuoteCard`, `CountdownTimer`, `WarningBanner` |
|
|
|
| `/history` | `DataTable`, `EmptyState`, 分页 |
|
|
|
| `/admin/markup` | `DataTable`, Drawer + `InputField`, `PrimaryButton` |
|
|
|
| `/admin/alerts` | `DataTable`, 类型 Tag, Drawer 详情 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 附录 A：与 PRD / 技术设计映射
|
|
|
|
|
|
| PRD/技术项 | UI 实现 |
|
|
|
|------------|---------|
|
|
|
| GD-5 异步轮询 | `/quote` processing 状态 + 2s 轮询 |
|
|
|
| 双等级报价 | `QuoteCard` Tab：标准 / 保证送达 |
|
|
|
| 3 分钟有效期 | `CountdownTimer` |
|
|
|
| is_realtime=false | `WarningBanner` |
|
|
|
| 过期重询 | `ConfirmDialog` |
|
|
|
| 运营加价 | `/admin/markup` Drawer |
|
|
|
| 预警中心 | `/admin/alerts` 表格 + 处理按钮 |
|
|
|
|
|
|
## 附录 B：文案清单（中文）
|
|
|
|
|
|
| 场景 | 文案 |
|
|
|
|------|------|
|
|
|
| 提交查价 | 获取报价 |
|
|
|
| 处理中 | 正在查询报价，请稍候… |
|
|
|
| 非实时 | 非实时报价，仅供参考 |
|
|
|
| 失败 | 暂时无法获取报价，请稍后重试 |
|
|
|
| 超时 | 查询超时，请重试 |
|
|
|
| 过期确认 | 报价已过期，是否重新询价？ |
|
|
|
| 空历史 | 暂无询价记录 |
|
|
|
|
|
|
## 附录 C：图标（Phosphor）
|
|
|
|
|
|
| 场景 | 图标名 |
|
|
|
|------|--------|
|
|
|
| 查价 | `Truck` |
|
|
|
| 历史 | `ClockCounterClockwise` |
|
|
|
| 预警 | `Warning` |
|
|
|
| 成功 | `CheckCircle` |
|
|
|
| 错误 | `XCircle` |
|
|
|
| 加载 | `CircleNotch`（旋转） |
|
