Design Document: Settlement Status Display

Overview

本设计扩展仪表盘和导出报表功能，在现有界面和报表中增加结算状态的显示。主要涉及：

后端API扩展 - 在月度和年度统计API中增加结算状态相关字段
前端仪表盘更新 - 显示结算收入统计和状态标识
导出服务扩展 - 在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

扩展返回字段：

{
    "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

扩展返回字段：

{
    "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

月度报告统计卡片区域
- 新增"已结算收入"统计卡片 (绿色图标)
- 新增"未结算收入"统计卡片 (橙色图标)
人员按供应商收入明细表格
- 新增"结算状态"列
- 未结算行使用浅橙色背景 (#fff7e6)
年度汇总表格
- 新增"已结算"和"未结算"列
- 调整位置到仪表盘底部

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 字段：

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

API Error Handling
- 如果数据库查询失败，返回500错误和错误消息
- 保持现有的错误处理模式
Frontend Error Handling
- 如果API返回缺少新字段，使用默认值0显示
- 保持现有的错误提示机制

Testing Strategy

Unit Tests

Backend Service Tests
- 测试 get_monthly_summary() 返回正确的结算统计
- 测试 get_yearly_summary() 返回正确的结算统计
- 测试导出服务生成正确的结算状态列
Frontend Component Tests
- 测试仪表盘正确显示结算统计卡片
- 测试未结算行正确高亮显示

Property-Based Tests

使用 Hypothesis 库进行属性测试：

Settlement Sum Property Test
- 生成随机工作记录集合
- 验证 settled + unsettled = total
Export Accuracy Property Test
- 生成随机工作记录
- 验证导出的结算状态与数据库一致

design.md 7.8 KB Istoric Crud