# Design Document: Settlement Status Display

## Overview

本设计扩展仪表盘和导出报表功能，在现有界面和报表中增加结算状态的显示。主要涉及：
1. 后端API扩展 - 在月度和年度统计API中增加结算状态相关字段
2. 前端仪表盘更新 - 显示结算收入统计和状态标识
3. 导出服务扩展 - 在Excel报表中增加结算状态列

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React)                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   Dashboard.jsx                      │    │
│  │  - 月度报告: 已结算/未结算收入统计卡片              │    │
│  │  - 人员按供应商明细: 结算状态列 + 未结算行高亮      │    │
│  │  - 年度汇总: 已结算/未结算收入列 (移至底部)         │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Backend (Flask)                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              work_record_service.py                  │    │
│  │  - get_monthly_summary(): 增加结算统计字段          │    │
│  │  - get_yearly_summary(): 增加结算统计字段           │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │               export_service.py                      │    │
│  │  - 月度报表: 明细+汇总增加结算状态列                │    │
│  │  - 年度报表: 明细+汇总增加结算状态列                │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

## Components and Interfaces

### Backend API Changes

#### 1. Monthly Summary API Response Extension

`GET /api/work-records/monthly-summary`

扩展返回字段：
```python
{
    "year": 2024,
    "month": 12,
    "total_records": 100,
    "total_earnings": 5000.00,
    "settled_earnings": 3000.00,      # 新增
    "unsettled_earnings": 2000.00,    # 新增
    "top_performers": [...],
    "item_breakdown": [...],
    "supplier_breakdown": [
        {
            "person_id": 1,
            "person_name": "张三",
            "supplier_name": "供应商A",
            "earnings": 1000.00,
            "is_settled": true          # 新增
        }
    ]
}
```

#### 2. Yearly Summary API Response Extension

`GET /api/work-records/yearly-summary`

扩展返回字段：
```python
{
    "year": 2024,
    "persons": [
        {
            "person_id": 1,
            "person_name": "张三",
            "monthly_earnings": [100, 200, ...],
            "yearly_total": 1500.00,
            "settled_total": 1000.00,     # 新增
            "unsettled_total": 500.00     # 新增
        }
    ],
    "monthly_totals": [...],
    "grand_total": 10000.00,
    "settled_grand_total": 7000.00,       # 新增
    "unsettled_grand_total": 3000.00      # 新增
}
```

### Frontend Component Changes

#### Dashboard.jsx Updates

1. **月度报告统计卡片区域**
   - 新增"已结算收入"统计卡片 (绿色图标)
   - 新增"未结算收入"统计卡片 (橙色图标)

2. **人员按供应商收入明细表格**
   - 新增"结算状态"列
   - 未结算行使用浅橙色背景 (#fff7e6)

3. **年度汇总表格**
   - 新增"已结算"和"未结算"列
   - 调整位置到仪表盘底部

### Export Service Changes

#### 1. Monthly Report Export

**明细表 (Detail Sheet)**
- 列顺序: 人员, 日期, 供应商, 物品, 单价, 数量, 总价, 结算状态
- 结算状态显示: "已结算" / "未结算"

**月度汇总表 (Monthly Summary Sheet)**
- 列顺序: 人员, 供应商, 总金额, 结算状态
- 按人员+供应商+结算状态分组汇总

#### 2. Yearly Report Export

**明细表 (Detail Sheet)**
- 列顺序: 人员, 日期, 供应商, 物品, 单价, 数量, 总价, 结算状态

**年度汇总表 (Yearly Summary Sheet)**
- 列顺序: 人员, 1月, 2月, ..., 12月, 年度合计, 已结算, 未结算

## Data Models

无需修改数据模型。`work_records` 表已有 `is_settled` 字段：

```python
class WorkRecord(db.Model):
    # ... existing fields ...
    is_settled = db.Column(db.Boolean, nullable=False, default=False)
```

## 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: Monthly Settlement Sum Consistency

*For any* set of work records in a given month, the sum of settled_earnings and unsettled_earnings returned by the monthly summary API SHALL equal total_earnings.

**Validates: Requirements 1.3**

### Property 2: Yearly Person Settlement Consistency

*For any* person in the yearly summary, settled_total + unsettled_total SHALL equal yearly_total.

**Validates: Requirements 3.2**

### Property 3: Yearly Grand Total Settlement Consistency

*For any* yearly summary response, settled_grand_total + unsettled_grand_total SHALL equal grand_total.

**Validates: Requirements 3.2, 3.3**

### Property 4: Export Settlement Status Text Mapping

*For any* work record exported to Excel, the settlement status column SHALL display "已结算" when is_settled is true and "未结算" when is_settled is false.

**Validates: Requirements 5.3, 6.3**

## Error Handling

1. **API Error Handling**
   - 如果数据库查询失败，返回500错误和错误消息
   - 保持现有的错误处理模式

2. **Frontend Error Handling**
   - 如果API返回缺少新字段，使用默认值0显示
   - 保持现有的错误提示机制

## Testing Strategy

### Unit Tests

1. **Backend Service Tests**
   - 测试 `get_monthly_summary()` 返回正确的结算统计
   - 测试 `get_yearly_summary()` 返回正确的结算统计
   - 测试导出服务生成正确的结算状态列

2. **Frontend Component Tests**
   - 测试仪表盘正确显示结算统计卡片
   - 测试未结算行正确高亮显示

### Property-Based Tests

使用 Hypothesis 库进行属性测试：

1. **Settlement Sum Property Test**
   - 生成随机工作记录集合
   - 验证 settled + unsettled = total

2. **Export Accuracy Property Test**
   - 生成随机工作记录
   - 验证导出的结算状态与数据库一致