lizi/shop-toy

Fork 0

Files

FlowerWater 0eb8ac9181 页面提交

2025-11-29 17:20:17 +08:00

8.9 KiB

Raw Blame History

Design Document

Overview

本设计文档描述了结算页面（应结账款）UI优化的技术实现方案。优化目标是提升视觉层次、改善信息密度、增强交互反馈，从而提供更好的用户体验。

当前页面基于 Vue 3 + TypeScript + uni-app 框架开发，使用 SCSS 进行样式管理。优化将保持现有架构不变，主要通过调整样式、优化组件结构和改进视觉设计来实现。

Architecture

组件层次结构

settlement.vue (主页面)
├── DueAlert (到期提醒区域)
│   └── DueItem[] (到期项列表)
├── TabNavigation (标签导航)
│   └── TabItem[] (标签项)
├── MerchantGroup[] (商户分组)
│   ├── MerchantHeader (商户头部)
│   ├── BatchActionButton (批量操作按钮)
│   └── OrderList (订单列表)
│       └── OrderItem[] (订单项)
│           ├── OrderHeader (订单头部)
│           ├── OrderContent (订单内容)
│           └── OrderFooter (订单操作)
└── EmptyState (空状态)

样式架构

采用 BEM 命名规范和模块化 SCSS：

使用语义化的颜色变量
统一的间距系统（基于 4rpx 倍数）
响应式字体大小
可复用的混入（mixin）

Components and Interfaces

1. DueAlert Component

职责: 显示即将到期的账款提醒

Props: 无（从 store 获取数据）

数据源: financeStore.dueOrders

视觉特性:

琥珀色背景 (#fffbe6)
警告图标 + 标题
横向滚动列表
卡片式到期项

2. TabNavigation Component

职责: 提供未结/已结状态切换

Props: 无

状态: currentTab (0: 未结, 1: 已结)

视觉特性:

固定在顶部
活动标签蓝色下划线
平滑过渡动画

3. MerchantGroup Component

职责: 按商户聚合显示账款信息

数据结构:

interface MerchantGroup {
  merchantId: string
  merchantName: string
  settlements: Settlement[]
  totalAmount: number
  hasOverdue: boolean
}

视觉特性:

圆角卡片 (16rpx)
渐变头部背景
逾期徽章
突出显示总金额

4. OrderItem Component

职责: 显示单个订单的结算信息

数据结构:

interface Settlement {
  id: string
  orderNo: string
  merchantId: string
  merchantName: string
  amount: number
  dueDate: string
  settlementDate?: string
  status: SettlementStatus
}

视觉特性:

清晰的信息层次
状态徽章（颜色编码）
金额突出显示
操作按钮（未结状态）

Data Models

SettlementStatus Enum

enum SettlementStatus {
  UNSETTLED = 'unsettled',  // 未结
  SETTLED = 'settled',      // 已结
  OVERDUE = 'overdue'       // 已逾期
}

Settlement Interface

interface Settlement {
  id: string
  orderNo: string
  merchantId: string
  merchantName: string
  amount: number
  dueDate: string
  settlementDate?: string
  status: SettlementStatus
}

DueOrder Interface

interface DueOrder {
  id: string
  dueDate: string
  amount: number
}

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Due Alert Visibility Consistency

For any state of the due orders list, when the list is empty, the Due Alert component should not be rendered in the DOM Validates: Requirements 1.4

Property 2: Merchant Grouping Completeness

For any settlement list, all settlements should be grouped by merchantId with no settlements left ungrouped or duplicated across groups Validates: Requirements 2.1

Property 3: Status Badge Color Mapping

For any settlement status value, the rendered status badge should use the correct color scheme (green for settled, amber for unsettled, red for overdue) Validates: Requirements 3.3

Property 4: Amount Display Formatting

For any numeric amount value, when displayed in the UI, it should be formatted with exactly 2 decimal places and prefixed with the ¥ symbol Validates: Requirements 3.4

Property 5: Tab State Synchronization

For any tab selection change, the active tab indicator should update and the corresponding settlement data should be loaded matching the selected status Validates: Requirements 5.4

Property 6: Button Interaction Feedback

For any button press event, the button should apply 0.8 opacity during the active state to provide visual feedback Validates: Requirements 4.3

Property 7: Overdue Badge Display Logic

For any merchant group, the overdue badge should be displayed if and only if at least one settlement in that group has status OVERDUE Validates: Requirements 2.3

Property 8: Empty State Rendering

For any state where the grouped merchant list is empty, the empty state component should be displayed with centered alignment and appropriate messaging Validates: Requirements 6.1, 6.2, 6.3, 6.4

Property 9: Spacing Consistency

For any rendered card or container element, the padding and margin values should follow the 4rpx-based spacing system (20rpx, 24rpx, etc.) Validates: Requirements 7.1, 7.2, 7.3

Property 10: Color Semantic Consistency

For any UI element representing a specific semantic meaning (primary action, amount, success, warning, danger), the color used should match the defined color palette Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6

Error Handling

数据加载错误

使用 uni.showToast 显示错误提示
保持当前状态，允许用户重试
下拉刷新作为恢复机制

消账提交错误

显示具体错误信息
保持弹窗打开，允许用户修改后重试
使用 loading 状态防止重复提交

空数据处理

显示友好的空状态页面
提供明确的提示信息
不显示错误，因为空数据是正常状态

Testing Strategy

Unit Testing

本项目将使用 Vitest 作为单元测试框架，配合 @vue/test-utils 进行 Vue 组件测试。

测试范围:

计算属性测试
- groupedByMerchant: 验证商户分组逻辑正确性
- currentWriteOffAmount: 验证单个/批量消账金额计算
方法测试
- getStatusText(): 验证状态文本映射
- getStatusClass(): 验证状态样式类映射
- handleTabChange(): 验证标签切换逻辑
边界情况
- 空数据列表
- 单个商户多个订单
- 全部逾期订单

Property-Based Testing

本项目将使用 fast-check 作为属性测试库，验证通用正确性属性。

配置要求:

每个属性测试至少运行 100 次迭代
使用明确的注释标记关联的设计文档属性

测试属性:

每个属性测试必须使用以下格式的注释标记：

// **Feature: settlement-ui-optimization, Property {number}: {property_text}**

属性测试列表:

Property 1: Due Alert Visibility Consistency
Property 2: Merchant Grouping Completeness
Property 3: Status Badge Color Mapping
Property 4: Amount Display Formatting
Property 5: Tab State Synchronization
Property 6: Button Interaction Feedback
Property 7: Overdue Badge Display Logic
Property 8: Empty State Rendering
Property 9: Spacing Consistency
Property 10: Color Semantic Consistency

测试工具和依赖

{
  "devDependencies": {
    "vitest": "^1.0.0",
    "@vue/test-utils": "^2.4.0",
    "fast-check": "^3.15.0",
    "@vitest/ui": "^1.0.0"
  }
}

测试命令

# 运行所有测试
pnpm test

# 运行单元测试
pnpm test:unit

# 运行属性测试
pnpm test:property

# 测试覆盖率
pnpm test:coverage

Implementation Notes

样式优化重点

颜色系统
- 主色：#1890ff (蓝色)
- 金额：#ff4d4f (红色)
- 成功：#52c41a (绿色)
- 警告：#faad14 (琥珀色)
- 文本层次：#333 / #666 / #999
间距系统
- 基础单位：4rpx
- 常用值：20rpx, 24rpx, 32rpx
- 卡片间距：20rpx
- 内容内边距：24rpx
圆角规范
- 卡片：16rpx
- 按钮：8rpx
- 徽章：4rpx
阴影效果
- 卡片：0 2rpx 8rpx rgba(0, 0, 0, 0.05)
- 固定导航：0 2rpx 8rpx rgba(0, 0, 0, 0.05)

性能考虑

使用 v-if 而非 v-show 处理大列表的条件渲染
商户分组减少渲染节点数量
横向滚动使用 scroll-view 组件优化性能

可访问性

保持足够的颜色对比度（WCAG AA 标准）
使用语义化的图标
提供清晰的状态反馈

响应式设计

使用 rpx 单位适配不同屏幕
固定导航栏考虑 H5 环境的顶部偏移
横向滚动适配小屏幕设备

8.9 KiB Raw Blame History Unescape Escape

Design Document

Overview

Architecture

组件层次结构

样式架构

Components and Interfaces

1. DueAlert Component

2. TabNavigation Component

3. MerchantGroup Component

4. OrderItem Component

Data Models

SettlementStatus Enum

Settlement Interface

DueOrder Interface

Correctness Properties

Property 1: Due Alert Visibility Consistency

Property 2: Merchant Grouping Completeness

Property 3: Status Badge Color Mapping

Property 4: Amount Display Formatting

Property 5: Tab State Synchronization

Property 6: Button Interaction Feedback

Property 7: Overdue Badge Display Logic

Property 8: Empty State Rendering

Property 9: Spacing Consistency

Property 10: Color Semantic Consistency

Error Handling

数据加载错误

消账提交错误

空数据处理

Testing Strategy

Unit Testing

Property-Based Testing

测试工具和依赖

测试命令

Implementation Notes

样式优化重点

性能考虑

可访问性

响应式设计

8.9 KiB

Raw Blame History