21 KiB

Raw Blame History

财务计费领域技术方案

领域编号: 4.4
微服务: ether-finance
最后更新: 2026-04-26

更新记录:

2026-04-26: 反向同步实际代码实现到文档。主要变更：修正 FeeItem/FeeBill/FeePayment 的实现状态标注为"未实现"（原标注为"已实现"与实际代码不符）；修正费用催缴/滞纳金的实现状态标注为"未实现"；新增能耗计量管理章节（EnergyMeter/EnergyConsumption，当前在 module-mdm 中实现）；新增能源类型枚举（EnergyType）；新增记录方式枚举（RecordMethod）；明确能耗管理与财务计费的边界。

一、领域概述

1.1 领域职责

财务计费领域负责物业费用管理全生命周期：

收费项目管理（物业费、停车费、水电费等）
账单生成与管理
支付处理与对账
费用催缴通知
财务报表与统计

1.2 核心概念

概念	说明	对应实体	实现状态
收费项目	可收费的项目定义	FeeItem	未实现
账单	应收费用单据	FeeBill	未实现
支付记录	支付流水记录	FeePayment	未实现
退款	退款申请与处理	FeeRefund	未实现
能源计量点	能耗数据采集点	EnergyMeter	已实现(module-mdm)
能耗记录	抄表数据与费用计算	EnergyConsumption	已实现(module-mdm)

二、领域模型

2.1 聚合根设计

FeeItem（收费项目）

@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（收费账单）

@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（支付记录）

@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（退款记录）

@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 定时任务

@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);
    }
}

四、能耗计量管理（已实现，当前在 module-mdm 中）

边界说明: 能耗计量管理当前在 module-mdm 中实现，属于基础数据管理（MDM）范畴。能耗数据采集和简单费用计算是已实现功能，但正式的账单生成、支付处理等财务功能属于本领域（module-finance）的待实现功能。两者通过 EnergyConsumption.amount 对接：能耗模块提供用量和计算值，财务模块将其作为按用量计费的账单数据来源。

4.1 EnergyMeter（能源计量点）

@Entity
@Table(name = "ops_energy_meter")
@Data
public class EnergyMeter {
    @Id
    private UUID id;
    private UUID projectId;

    private String meterCode;           // 计量点编码（自动生成：EM + yyyyMMddHHmmss）
    private String meterName;           // 计量点名称
    private EnergyType energyType;      // 能源类型枚举
    private UUID spaceNodeId;           // 关联空间节点
    private String installationLocation;// 安装位置
    private BigDecimal ratedCapacity;   // 额定容量
    private BigDecimal unitPrice;       // 单价（精度4位小数，用于费用计算）
    private Status status;              // ACTIVE/INACTIVE

    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

能源类型枚举:

public enum EnergyType {
    LIGHTING("照明插座用电"),
    HVAC("空调用电"),
    POWER("动力用电"),
    SPECIAL("特殊用电"),
    WATER("给排水"),
    GAS("燃气");
}

已知问题: 前后端能源类型枚举不一致。后端为 LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS，前端为 ELECTRICITY/WATER/GAS/CENTRAL_HEATING/CENTRAL_COOLING，需对齐。

4.2 EnergyConsumption（能耗记录）

@Entity
@Table(name = "ops_energy_consumption")
@Data
public class EnergyConsumption {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID meterId;               // 关联计量点

    private LocalDate consumptionDate;  // 记录日期
    private BigDecimal previousReading; // 上次读数
    private BigDecimal currentReading;  // 当前读数
    private BigDecimal consumption;     // 消耗量 = current - previous
    private BigDecimal amount;          // 费用 = consumption x unitPrice
    private UUID recordedBy;            // 记录人
    private RecordMethod recordMethod;  // 记录方式
    private String remarks;             // 备注

    private LocalDateTime createdAt;
}

记录方式枚举:

public enum RecordMethod {
    MANUAL("手动录入"),
    IOT("IoT自动采集");
}

4.3 能耗业务规则

规则	说明
编码自动生成	格式：EM + yyyyMMddHHmmss，冲突时追加后缀
仪表状态校验	只能对 ACTIVE 状态的仪表进行抄表
读数递增校验	当前读数不能小于上次读数
自动获取上次读数	从最近一条记录获取 previousReading，首次为 0
自动计算消耗量	consumption = currentReading - previousReading
自动计算费用	amount = consumption x meter.unitPrice（单价为空时为 0）
默认手动录入	recordMethod 默认设为 MANUAL
软删除	删除操作将状态设为 INACTIVE

4.4 能耗 API 接口

基础路径: /api/ops/energy

计量点管理:
  POST   /meters              创建计量点
  GET    /meters              查询计量点列表（projectId必填，energyType可选）
  GET    /meters/{id}         获取计量点详情
  PUT    /meters/{id}         更新计量点
  DELETE /meters/{id}         删除计量点（软删除）

能耗记录:
  POST   /consumption         录入能耗数据
  GET    /consumption/{meterId} 查询能耗记录（startDate/endDate可选）

能耗统计:
  GET    /statistics/by-type     按类型统计消耗
  GET    /statistics/unit-consumption 单方能耗

已知缺陷: getConsumptionByType() 当前将项目总消耗全部归入 LIGHTING 类型，未按 meter.energyType 真正分项汇总，需修复。

4.5 能耗与财务的边界

EnergyMeter (module-mdm)          FeeItem (module-finance，待实现)
       |                                |
       v                                v
EnergyConsumption --费用计算--> FeeBill (自动/手动生成，待实现)
  (抄表数据)                        |
                                    v
                              FeePayment (支付记录，待实现)
                                    |
                                    v
                              FeeRefund (退款记录，待实现)

能耗模块（module-mdm）职责: 计量点管理、抄表录入、消耗量计算、简单费用计算（consumption x unitPrice）
财务模块（module-finance，待实现）职责: 收费项目管理、账单生成、支付处理、催缴通知、滞纳金计算、退款处理

五、实现状态与差异

5.1 实现状态

功能模块	实现状态	备注
FeeItem	🔴 未实现	无 module-finance 模块，无 fin_* 表
FeeBill	🔴 未实现	无 FeeBill 实体/服务/控制器
FeePayment	🔴 未实现	无 FeePayment 实体/服务/控制器
FeeRefund	🔴 未实现	原设计即标注未实现
费用催缴	🔴 未实现	无 FeeReminderJob 定时任务
滞纳金计算	🔴 未实现	无计算逻辑
EnergyMeter	🟢 已实现	在 module-mdm 中实现
EnergyConsumption	🟢 已实现	在 module-mdm 中实现，含简单费用计算
能耗统计分析	🟢 已实现(有缺陷)	按类型统计未真正分项汇总
退款功能	🔴 未实现	待开发
财务报表	🔴 未实现	待开发
支付网关	🔴 未实现	待对接

5.2 与设计方案的差异

设计项	设计方案	现有实现	差异分析
FeeItem	完整实体定义	不存在	完全缺失，需新建 module-finance
FeeBill	完整实体定义	不存在	完全缺失
FeePayment	完整实体定义	不存在	完全缺失
FeeRefund	完整实体定义	不存在	完全缺失
费用催缴	FeeReminderJob	不存在	完全缺失
滞纳金	自动计算逻辑	不存在	完全缺失
能耗管理	未在设计文档中	module-mdm中已实现	设计文档遗漏，需补充
能源类型	FeeType(8种)	EnergyType(6种)	实际更细分(按用电分项)，但缺少供暖/物业费
前后端枚举	统一	不一致	后端LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS vs 前端ELECTRICITY/WATER/GAS/CENTRAL_HEATING/CENTRAL_COOLING

5.3 改进计划

优先级	改进项	说明
P0	创建 module-finance 模块	独立财务模块，包含 entity/service/controller/repository
P0	实现 FeeItem 收费项目	含完整字段和 CRUD API
P0	实现 FeeBill 账单	含账单自动生成和状态流转
P0	实现 FeePayment 支付记录	线下收款登记、支付记录查询
P0	能耗数据与账单对接	将 EnergyConsumption 的 amount 作为按用量计费的账单数据来源
P1	修复能耗按类型统计	getConsumptionByType() 应按 meter.energyType 真正分项汇总
P1	统一前后端能源类型枚举	对齐后端和前端的 EnergyType 定义
P1	实现费用催缴定时任务	到期提醒、逾期催缴、周汇总
P1	实现滞纳金自动计算	逾期天数 x 日利率，不超过上限
P1	实现退款功能	退款申请、审批、执行流程
P2	对接支付网关	集成微信支付、支付宝 SDK
P2	财务报表	收费统计、欠费分析、收入趋势

六、数据库表结构

-- 收费项目表
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);

-- ============================================================
-- 以下为已实现的能耗计量相关表（在 module-mdm 中）
-- ============================================================

-- 能源计量点表（已实现）
CREATE TABLE ops_energy_meter (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    meter_code VARCHAR(50) NOT NULL,
    meter_name VARCHAR(100) NOT NULL,
    energy_type VARCHAR(20) NOT NULL,
    space_node_id UUID,
    installation_location VARCHAR(255),
    rated_capacity NUMERIC(10,2),
    unit_price NUMERIC(10,4),
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, meter_code)
);

-- 能耗记录表（已实现）
CREATE TABLE ops_energy_consumption (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    meter_id UUID NOT NULL REFERENCES ops_energy_meter(id),
    consumption_date DATE NOT NULL,
    previous_reading NUMERIC(12,2),
    current_reading NUMERIC(12,2),
    consumption NUMERIC(12,2) NOT NULL,
    amount NUMERIC(10,2),
    recorded_by UUID,
    record_method VARCHAR(20) DEFAULT 'MANUAL',
    remarks VARCHAR(1000),
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 能耗表索引
CREATE INDEX idx_energy_meter_project ON ops_energy_meter(project_id);
CREATE INDEX idx_energy_meter_status ON ops_energy_meter(status);
CREATE INDEX idx_ec_meter_date ON ops_energy_consumption(meter_id, consumption_date);
CREATE INDEX idx_ec_project_date ON ops_energy_consumption(project_id, consumption_date);

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

21 KiB Raw Blame History Unescape Escape

财务计费领域技术方案

一、领域概述

1.1 领域职责

1.2 核心概念

二、领域模型

2.1 聚合根设计

FeeItem（收费项目）

FeeBill（收费账单）

FeePayment（支付记录）

FeeRefund（退款记录）

三、费用催缴

3.1 定时任务

四、能耗计量管理（已实现，当前在 module-mdm 中）

4.1 EnergyMeter（能源计量点）

4.2 EnergyConsumption（能耗记录）

4.3 能耗业务规则

4.4 能耗 API 接口

4.5 能耗与财务的边界

五、实现状态与差异

5.1 实现状态

5.2 与设计方案的差异

5.3 改进计划

六、数据库表结构

21 KiB

Raw Blame History