# 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

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

**数据结构**:
```typescript
interface MerchantGroup {
  merchantId: string
  merchantName: string
  settlements: Settlement[]
  totalAmount: number
  hasOverdue: boolean
}
```

**视觉特性**:
- 圆角卡片 (16rpx)
- 渐变头部背景
- 逾期徽章
- 突出显示总金额

### 4. OrderItem Component

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

**数据结构**:
```typescript
interface Settlement {
  id: string
  orderNo: string
  merchantId: string
  merchantName: string
  amount: number
  dueDate: string
  settlementDate?: string
  status: SettlementStatus
}
```

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

## Data Models

### SettlementStatus Enum

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

### Settlement Interface

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

### DueOrder Interface

```typescript
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 组件测试。

**测试范围**:

1. **计算属性测试**
   - `groupedByMerchant`: 验证商户分组逻辑正确性
   - `currentWriteOffAmount`: 验证单个/批量消账金额计算

2. **方法测试**
   - `getStatusText()`: 验证状态文本映射
   - `getStatusClass()`: 验证状态样式类映射
   - `handleTabChange()`: 验证标签切换逻辑

3. **边界情况**
   - 空数据列表
   - 单个商户多个订单
   - 全部逾期订单

### Property-Based Testing

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

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

**测试属性**:

每个属性测试必须使用以下格式的注释标记：
```typescript
// **Feature: settlement-ui-optimization, Property {number}: {property_text}**
```

**属性测试列表**:

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

### 测试工具和依赖

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

### 测试命令

```bash
# 运行所有测试
pnpm test

# 运行单元测试
pnpm test:unit

# 运行属性测试
pnpm test:property

# 测试覆盖率
pnpm test:coverage
```

## Implementation Notes

### 样式优化重点

1. **颜色系统**
   - 主色：#1890ff (蓝色)
   - 金额：#ff4d4f (红色)
   - 成功：#52c41a (绿色)
   - 警告：#faad14 (琥珀色)
   - 文本层次：#333 / #666 / #999

2. **间距系统**
   - 基础单位：4rpx
   - 常用值：20rpx, 24rpx, 32rpx
   - 卡片间距：20rpx
   - 内容内边距：24rpx

3. **圆角规范**
   - 卡片：16rpx
   - 按钮：8rpx
   - 徽章：4rpx

4. **阴影效果**
   - 卡片：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 环境的顶部偏移
- 横向滚动适配小屏幕设备