# 财务计费领域技术方案

**领域编号**: 4.4  
**微服务**: ether-finance  
**最后更新**: 2026-02-10

---

## 一、领域概述

### 1.1 领域职责

财务计费领域负责物业费用管理全生命周期：
- 收费项目管理（物业费、停车费、水电费等）
- 账单生成与管理
- 支付处理与对账
- 费用催缴通知
- 财务报表与统计

### 1.2 核心概念

| 概念 | 说明 | 对应实体 |
|------|------|----------|
| **收费项目** | 可收费的项目定义 | FeeItem |
| **账单** | 应收费用单据 | FeeBill |
| **支付记录** | 支付流水记录 | FeePayment |
| **退款** | 退款申请与处理 | FeeRefund |

---

## 二、领域模型

### 2.1 聚合根设计

#### FeeItem（收费项目）

```java
@Entity
@Table(name = "fin_fee_item")
@Data
public class FeeItem {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String code;           // 项目编码
    private String name;           // 项目名称
    private FeeType type;          // PROPERTY/PARKING/WATER/ELECTRICITY/GAS/OTHER
    
    // 计费规则
    private BillingMethod billingMethod; // FIXED/AREA/USAGE/CUSTOM
    private BigDecimal unitPrice;  // 单价
    private String unit;           // 单位: 元/月、元/㎡·月、元/度
    
    // 账期
    private Integer billDay;       // 账单日(每月几号)
    private Integer dueDay;        // 到期日(每月几号)
    private Integer overdueDay;    // 逾期日(每月几号)
    
    // 滞纳金
    private Boolean enableLateFee;
    private BigDecimal lateFeeRate; // 滞纳金比例(日利率)
    private BigDecimal maxLateFee;  // 滞纳金上限
    
    // 状态
    private Boolean enabled;
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

// 收费类型枚举
public enum FeeType {
    PROPERTY("物业费"),
    PARKING("停车费"),
    WATER("水费"),
    ELECTRICITY("电费"),
    GAS("燃气费"),
    HEATING("供暖费"),
    REPAIR_FUND("维修基金"),
    OTHER("其他");
}

// 计费方式枚举
public enum BillingMethod {
    FIXED("固定金额"),
    AREA("按面积"),
    USAGE("按用量"),
    CUSTOM("自定义");
}
```

#### FeeBill（收费账单）

```java
@Entity
@Table(name = "fin_fee_bill")
@Data
public class FeeBill {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String billNo;         // 账单编号
    
    // 关联信息
    private UUID feeItemId;        // 收费项目
    private UUID spaceNodeId;      // 关联房产
    private UUID ownerId;          // 关联业主
    
    // 账期
    private String billPeriod;     // 账期: 2024-02
    private LocalDate billDate;    // 账单日期
    private LocalDate dueDate;     // 到期日期
    private LocalDate overdueDate; // 逾期日期
    
    // 用量（按用量计费）
    private BigDecimal usageAmount; // 用量
    private String usageUnit;      // 用量单位
    
    // 金额
    private BigDecimal amount;     // 应收金额
    private BigDecimal lateFee;    // 滞纳金
    private BigDecimal discount;   // 优惠金额
    private BigDecimal payableAmount; // 应付金额 = amount + lateFee - discount
    private BigDecimal paidAmount; // 已付金额
    
    // 状态
    private BillStatus status;     // UNPAID/PARTIAL_PAID/PAID/OVERDUE/CANCELLED
    
    // 关联支付记录
    @OneToMany(mappedBy = "bill")
    private List<FeePayment> payments;
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

// 账单状态枚举
public enum BillStatus {
    UNPAID("未缴费"),
    PARTIAL_PAID("部分缴费"),
    PAID("已缴费"),
    OVERDUE("已逾期"),
    CANCELLED("已取消");
}
```

#### FeePayment（支付记录）

```java
@Entity
@Table(name = "fin_fee_payment")
@Data
public class FeePayment {
    @Id
    private UUID id;
    private UUID billId;
    
    private String paymentNo;      // 支付流水号
    private BigDecimal amount;     // 支付金额
    
    // 支付方式
    private PaymentMethod method;  // WECHAT/ALIPAY/CASH/BANK_TRANSFER/CARD
    private String thirdPartyNo;   // 第三方支付流水号
    
    // 支付状态
    private PaymentStatus status;  // PENDING/SUCCESS/FAILED/REFUNDED
    private String failReason;     // 失败原因
    
    // 时间
    private LocalDateTime paymentTime;
    private String remark;
    
    // 操作人
    private UUID operatorId;
    private String operatorName;
    
    // 审计字段
    private LocalDateTime createdAt;
}

// 支付方式枚举
public enum PaymentMethod {
    WECHAT("微信支付"),
    ALIPAY("支付宝"),
    CASH("现金"),
    BANK_TRANSFER("银行转账"),
    CARD("刷卡");
}
```

#### FeeRefund（退款记录）

```java
@Entity
@Table(name = "fin_fee_refund")
@Data
public class FeeRefund {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID billId;
    private UUID paymentId;        // 关联支付记录
    
    private String refundNo;       // 退款单号
    private BigDecimal amount;     // 退款金额
    private String reason;         // 退款原因
    
    // 状态
    private RefundStatus status;   // PENDING/APPROVED/REJECTED/REFUNDED
    
    // 审批
    private UUID approverId;
    private String approverName;
    private LocalDateTime approveTime;
    private String approveRemark;
    
    // 退款执行
    private String thirdPartyRefundNo;
    private LocalDateTime refundTime;
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

---

## 三、费用催缴

### 3.1 定时任务

```java
@Component
public class FeeReminderJob {
    
    @Autowired
    private FeeBillRepository feeBillRepository;
    
    @Autowired
    private NotificationService notificationService;
    
    // 每天9点执行：提醒即将到期
    @Scheduled(cron = "0 0 9 * * ?")
    public void remindUpcomingDue() {
        // 查询3天内到期的账单
        LocalDate targetDate = LocalDate.now().plusDays(3);
        
        List<FeeBill> upcomingBills = feeBillRepository
            .findByDueDateBetweenAndStatus(LocalDate.now(), targetDate, BillStatus.UNPAID);
        
        for (FeeBill bill : upcomingBills) {
            notificationService.sendFeeReminder(bill, "FEE_UPCOMING_DUE");
        }
    }
    
    // 每天9点和18点执行：催缴逾期
    @Scheduled(cron = "0 0 9,18 * * ?")
    public void remindOverdue() {
        // 查询已逾期的账单
        List<FeeBill> overdueBills = feeBillRepository
            .findByOverdueDateBeforeAndStatus(LocalDate.now(), BillStatus.UNPAID);
        
        for (FeeBill bill : overdueBills) {
            // 计算滞纳金
            calculateLateFee(bill);
            notificationService.sendFeeReminder(bill, "FEE_OVERDUE");
        }
    }
    
    // 每周一9点执行：发送汇总
    @Scheduled(cron = "0 0 9 ? * MON")
    public void sendWeeklySummary() {
        // 发送本周待缴费汇总
    }
    
    private void calculateLateFee(FeeBill bill) {
        if (!bill.getEnableLateFee()) {
            return;
        }
        
        // 计算逾期天数
        long overdueDays = ChronoUnit.DAYS.between(bill.getOverdueDate(), LocalDate.now());
        if (overdueDays <= 0) {
            return;
        }
        
        // 计算滞纳金
        BigDecimal lateFee = bill.getAmount()
            .multiply(bill.getLateFeeRate())
            .multiply(BigDecimal.valueOf(overdueDays));
        
        // 不超过上限
        if (bill.getMaxLateFee() != null && lateFee.compareTo(bill.getMaxLateFee()) > 0) {
            lateFee = bill.getMaxLateFee();
        }
        
        bill.setLateFee(lateFee);
        bill.setPayableAmount(bill.getAmount().add(lateFee).subtract(bill.getDiscount()));
        feeBillRepository.save(bill);
    }
}
```

---

## 四、实现状态与差异

### 4.1 实现状态

| 功能模块 | 实现状态 | 备注 |
|---------|---------|------|
| FeeItem | 🟢 已实现 | 基础CRUD |
| FeeBill | 🟢 已实现 | 基础CRUD |
| FeePayment | 🟢 已实现 | 基础CRUD |
| 费用催缴 | 🟢 已实现 | 定时任务 |
| 滞纳金计算 | 🟢 已实现 | 自动计算 |
| 退款功能 | 🔴 未实现 | 待开发 |
| 财务报表 | 🔴 未实现 | 待开发 |
| 支付网关 | 🔴 未实现 | 待对接 |

### 4.2 与设计方案的差异

| 设计项 | 设计方案 | 现有实现 | 差异分析 |
|--------|----------|----------|----------|
| **实体归属** | ether-finance | ether-finance + ether-mdm重复 | ❌ 存在重复实体 |
| **支付网关** | 对接微信/支付宝 | 未对接 | 🔴 功能缺失 |
| **退款** | 退款流程 | 未实现 | 🔴 功能缺失 |

### 4.3 改进计划

| 优先级 | 改进项 | 说明 |
|--------|--------|------|
| P1 | 清理重复实体 | 删除ether-mdm中的Fee相关实体 |
| P2 | 实现退款功能 | 退款申请、审批、执行流程 |
| P2 | 对接支付网关 | 集成微信支付、支付宝SDK |
| P2 | 财务报表 | 收费统计、欠费分析、收入趋势 |

---

## 五、数据库表结构

```sql
-- 收费项目表
CREATE TABLE fin_fee_item (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    code VARCHAR(50) NOT NULL,
    name VARCHAR(100) NOT NULL,
    type VARCHAR(20) NOT NULL,
    billing_method VARCHAR(20) NOT NULL,
    unit_price NUMERIC(12,2),
    unit VARCHAR(20),
    bill_day INTEGER,
    due_day INTEGER,
    overdue_day INTEGER,
    enable_late_fee BOOLEAN DEFAULT FALSE,
    late_fee_rate NUMERIC(5,4),
    max_late_fee NUMERIC(12,2),
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, code)
);

-- 账单表
CREATE TABLE fin_fee_bill (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    bill_no VARCHAR(32) NOT NULL,
    fee_item_id UUID NOT NULL,
    space_node_id UUID,
    owner_id UUID,
    bill_period VARCHAR(10) NOT NULL,
    bill_date DATE NOT NULL,
    due_date DATE NOT NULL,
    overdue_date DATE,
    usage_amount NUMERIC(12,2),
    usage_unit VARCHAR(20),
    amount NUMERIC(12,2) NOT NULL,
    late_fee NUMERIC(12,2) DEFAULT 0,
    discount NUMERIC(12,2) DEFAULT 0,
    payable_amount NUMERIC(12,2) NOT NULL,
    paid_amount NUMERIC(12,2) DEFAULT 0,
    status VARCHAR(20) NOT NULL DEFAULT 'UNPAID',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, bill_no)
);

-- 支付记录表
CREATE TABLE fin_fee_payment (
    id UUID PRIMARY KEY,
    bill_id UUID NOT NULL,
    payment_no VARCHAR(64) NOT NULL,
    amount NUMERIC(12,2) NOT NULL,
    method VARCHAR(20) NOT NULL,
    third_party_no VARCHAR(100),
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    fail_reason VARCHAR(500),
    payment_time TIMESTAMP,
    remark VARCHAR(500),
    operator_id UUID,
    operator_name VARCHAR(100),
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 退款记录表
CREATE TABLE fin_fee_refund (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    bill_id UUID NOT NULL,
    payment_id UUID NOT NULL,
    refund_no VARCHAR(64) NOT NULL,
    amount NUMERIC(12,2) NOT NULL,
    reason VARCHAR(500),
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    approver_id UUID,
    approver_name VARCHAR(100),
    approve_time TIMESTAMP,
    approve_remark VARCHAR(500),
    third_party_refund_no VARCHAR(100),
    refund_time TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_fee_item_project ON fin_fee_item(project_id);
CREATE INDEX idx_fee_bill_project ON fin_fee_bill(project_id);
CREATE INDEX idx_fee_bill_status ON fin_fee_bill(status);
CREATE INDEX idx_fee_bill_owner ON fin_fee_bill(owner_id);
CREATE INDEX idx_fee_bill_due_date ON fin_fee_bill(due_date);
CREATE INDEX idx_fee_payment_bill ON fin_fee_payment(bill_id);
```

---

**文档维护**: 本领域技术方案由 ether-finance 服务负责人维护