# 财务与收费域 - 详细设计

**文档类型**: 详细设计文档
**生成日期**: 2026-05-18
**数据来源**: REVERSE-FINANCE.md（反推文档）+ 04-FINANCE.md（原设计文档）+ 实际代码分析

---

## 一、功能点清单

| 编号 | 功能模块 | 功能点 | 实现状态 | 说明 |
|------|---------|--------|---------|------|
| FIN-001 | 能耗计量管理 | 计量点CRUD | 已实现 | module-mdm 中 EnergyMeter |
| FIN-002 | 能耗计量管理 | 计量点编码自动生成 | 已实现 | EM + yyyyMMddHHmmss |
| FIN-003 | 能耗计量管理 | 计量点软删除 | 已实现 | 状态设为 INACTIVE |
| FIN-004 | 能耗录入 | 能耗数据录入 | 已实现 | 手动录入 + IoT预留 |
| FIN-005 | 能耗录入 | 读数递增校验 | 已实现 | 当前读数 >= 上次读数 |
| FIN-006 | 能耗录入 | 自动计算消耗量与费用 | 已实现 | consumption = current - previous; amount = consumption * unitPrice |
| FIN-007 | 能耗统计 | 按类型统计消耗 | 已实现(有缺陷) | 当前全部归入LIGHTING，需修复 |
| FIN-008 | 能耗统计 | 单方能耗 | 已实现 | 遍历项目ACTIVE计量点累加 |
| FIN-009 | 收费项目管理 | 收费项目CRUD | 未实现 | FeeItem 实体不存在 |
| FIN-010 | 收费项目管理 | 周期性收费配置 | 未实现 | 按月/季/年收费 |
| FIN-011 | 收费项目管理 | 一次性收费配置 | 未实现 | 临时收费项目 |
| FIN-012 | 收费项目管理 | 按面积计费配置 | 未实现 | 面积 * 单价 |
| FIN-013 | 收费项目管理 | 按用量计费配置 | 未实现 | 用量 * 单价（对接能耗） |
| FIN-014 | 收费项目管理 | 固定金额计费配置 | 未实现 | 每月固定金额 |
| FIN-015 | 账单管理 | 账单自动生成 | 未实现 | 根据收费项目规则按账期生成 |
| FIN-016 | 账单管理 | 账单手动生成 | 未实现 | 人工创建单笔账单 |
| FIN-017 | 账单管理 | 批量账单生成 | 未实现 | 一次性为项目所有业主生成 |
| FIN-018 | 账单管理 | 账单状态流转 | 未实现 | UNPAID/PARTIAL_PAID/PAID/OVERDUE/CANCELLED |
| FIN-019 | 账单管理 | 催缴提醒 | 未实现 | 到期前3天提醒 + 逾期催缴 |
| FIN-020 | 账单管理 | 账单导出 | 未实现 | Excel/PDF 格式 |
| FIN-021 | 支付管理 | 线下收款登记 | 未实现 | 现金/银行转账/刷卡 |
| FIN-022 | 支付管理 | 线上支付对接 | 未实现 | 微信/支付宝 |
| FIN-023 | 支付管理 | 支付确认 | 未实现 | 支付状态确认 |
| FIN-024 | 支付管理 | 支付记录查询 | 未实现 | 按账单/业主/时间查询 |
| FIN-025 | 退款管理 | 退款申请 | 未实现 | 业主发起退款 |
| FIN-026 | 退款管理 | 退款审核 | 未实现 | 审批流程 |
| FIN-027 | 退款管理 | 退款执行 | 未实现 | 原路退回/线下退款 |
| FIN-028 | 滞纳金 | 滞纳金自动计算 | 未实现 | 逾期天数 * 日利率 |
| FIN-029 | 滞纳金 | 滞纳金上限控制 | 未实现 | 不超过 maxLateFee |
| FIN-030 | 能耗对接 | 能耗数据与账单对接 | 未实现 | EnergyConsumption -> FeeBill |
| FIN-031 | 能耗修复 | 修复按类型统计 | 未实现 | 按 meter.energyType 真正分项汇总 |
| FIN-032 | 能耗修复 | 统一前后端能源类型枚举 | 未实现 | 后端6种 vs 前端5种 |
| FIN-033 | 财务报表 | 收费统计 | 未实现 | 按项目/类型/时间维度 |
| FIN-034 | 财务报表 | 欠费分析 | 未实现 | 逾期/欠费金额统计 |
| FIN-035 | 财务报表 | 收入趋势 | 未实现 | 月度/季度趋势图 |

---

## 二、数据结构设计

### 2.1 已实现实体

#### 2.1.1 EnergyMeter（能源计量点）

**所在模块**: module-mdm
**数据库表**: `ops_energy_meter`
**源码**: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyMeter.java`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| projectId | UUID | project_id | NOT NULL | 所属项目 |
| meterCode | String | meter_code | NOT NULL, UNIQUE | 计量点编码（EM + yyyyMMddHHmmss） |
| meterName | String | meter_name | NOT NULL | 计量点名称 |
| energyType | EnergyType | energy_type | NOT NULL | 能源类型枚举 |
| spaceNodeId | UUID | space_node_id | -- | 关联空间节点 |
| installationLocation | String | installation_location | -- | 安装位置 |
| ratedCapacity | BigDecimal(10,2) | rated_capacity | -- | 额定容量 |
| unitPrice | BigDecimal(10,4) | unit_price | -- | 单价（4位小数精度） |
| status | Status | status | NOT NULL, 默认ACTIVE | 状态枚举 |
| createdAt | LocalDateTime | created_at | -- | 创建时间 |
| updatedAt | LocalDateTime | updated_at | -- | 更新时间 |

**枚举定义**:

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

public enum Status {
    ACTIVE, INACTIVE
}
```

#### 2.1.2 EnergyConsumption（能耗记录）

**所在模块**: module-mdm
**数据库表**: `ops_energy_consumption`
**源码**: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyConsumption.java`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| projectId | UUID | project_id | NOT NULL | 所属项目 |
| meterId | UUID | meter_id | NOT NULL | 关联计量点 |
| consumptionDate | LocalDate | consumption_date | NOT NULL | 记录日期 |
| previousReading | BigDecimal(12,2) | previous_reading | -- | 上次读数 |
| currentReading | BigDecimal(12,2) | current_reading | -- | 当前读数 |
| consumption | BigDecimal(12,2) | consumption | NOT NULL | 消耗量 = current - previous |
| amount | BigDecimal(10,2) | amount | -- | 费用 = consumption * unitPrice |
| recordedBy | UUID | recorded_by | -- | 记录人 |
| recordMethod | RecordMethod | record_method | -- | 记录方式，默认MANUAL |
| remarks | String(1000) | remarks | -- | 备注 |
| createdAt | LocalDateTime | created_at | -- | 创建时间 |

**数据库索引**:

```sql
idx_ec_meter_date   -- (meter_id, consumption_date)
idx_ec_project_date -- (project_id, consumption_date)
```

**枚举定义**:

```java
public enum RecordMethod {
    MANUAL,  // 手动录入
    IOT      // IoT自动采集
}
```

---

### 2.2 待实现实体

#### 2.2.1 FeeItem（收费项目）

**目标模块**: module-finance（待创建）
**目标表**: `fin_fee_item`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| projectId | UUID | project_id | NOT NULL | 所属项目 |
| code | VARCHAR(50) | code | NOT NULL, UNIQUE | 收费项目编码（FI + yyyyMMddHHmmss） |
| name | VARCHAR(100) | name | NOT NULL | 收费项目名称 |
| type | VARCHAR(20) | type | NOT NULL | 收费类型枚举 |
| billingMethod | VARCHAR(20) | billing_method | NOT NULL | 计费方式枚举 |
| unitPrice | DECIMAL(12,4) | unit_price | -- | 单价（按用量/面积计费时使用） |
| unit | VARCHAR(20) | unit | -- | 计量单位（kWh/吨/平方米/月/次） |
| fixedAmount | DECIMAL(12,2) | fixed_amount | -- | 固定金额（FIXED计费方式） |
| billDay | INT | bill_day | -- | 出账日（每月几号出账，1-28） |
| dueDay | INT | due_day | -- | 到期日（出账后第N天到期） |
| overdueDay | INT | overdue_day | -- | 逾期日（到期后第N天开始计滞纳金） |
| enableLateFee | BOOLEAN | enable_late_fee | NOT NULL, 默认false | 是否启用滞纳金 |
| lateFeeRate | DECIMAL(8,6) | late_fee_rate | -- | 日滞纳金利率（如0.0005 = 万分之五/天） |
| maxLateFee | DECIMAL(12,2) | max_late_fee | -- | 滞纳金上限金额 |
| description | VARCHAR(500) | description | -- | 收费项目说明 |
| status | VARCHAR(20) | status | NOT NULL, 默认ENABLED | 状态：ENABLED/DISABLED |
| createdAt | TIMESTAMP | created_at | NOT NULL | 创建时间 |
| updatedAt | TIMESTAMP | updated_at | NOT NULL | 更新时间 |
| createdBy | UUID | created_by | -- | 创建人 |

**枚举定义**:

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

public enum BillingMethod {
    FIXED("固定金额"),       // 每月固定金额
    AREA("按面积计费"),      // 面积 * 单价
    USAGE("按用量计费"),     // 用量 * 单价（对接能耗）
    CUSTOM("自定义");        // 自定义计费规则
}
```

**数据库索引**:

```sql
idx_fi_project_status -- (project_id, status)
idx_fi_code           -- (code) -- UNIQUE约束自带索引
idx_fi_type           -- (type, status)
```

**外键关系**:

```sql
fk_fi_project -- project_id REFERENCES mdm_project(id)
```

---

#### 2.2.2 FeeBill（收费账单）

**目标模块**: module-finance（待创建）
**目标表**: `fin_fee_bill`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| billNo | VARCHAR(30) | bill_no | NOT NULL, UNIQUE | 账单编号（BL + yyyyMMdd + 4位序号） |
| feeItemId | UUID | fee_item_id | NOT NULL | 关联收费项目 |
| projectId | UUID | project_id | NOT NULL | 所属项目 |
| spaceNodeId | UUID | space_node_id | -- | 关联空间节点（房产） |
| ownerId | UUID | owner_id | -- | 关联业主ID |
| billPeriod | VARCHAR(20) | bill_period | NOT NULL | 账期（如2026-05） |
| billDate | DATE | bill_date | NOT NULL | 出账日期 |
| dueDate | DATE | due_date | NOT NULL | 到期日期 |
| overdueDate | DATE | overdue_date | -- | 逾期日期 |
| usageAmount | DECIMAL(12,2) | usage_amount | -- | 用量（按用量计费时） |
| usageUnit | VARCHAR(20) | usage_unit | -- | 用量单位 |
| area | DECIMAL(12,2) | area | -- | 面积（按面积计费时） |
| amount | DECIMAL(12,2) | amount | NOT NULL | 应收金额 |
| lateFee | DECIMAL(12,2) | late_fee | 默认0 | 滞纳金 |
| discount | DECIMAL(12,2) | discount | 默认0 | 优惠金额 |
| payableAmount | DECIMAL(12,2) | payable_amount | NOT NULL | 应付金额 = amount + lateFee - discount |
| paidAmount | DECIMAL(12,2) | paid_amount | 默认0 | 已付金额 |
| status | VARCHAR(20) | status | NOT NULL, 默认UNPAID | 账单状态枚举 |
| sourceType | VARCHAR(20) | source_type | -- | 来源类型：AUTO/MANUAL/IMPORT |
| sourceId | UUID | source_id | -- | 来源ID（如能耗记录ID） |
| remark | VARCHAR(500) | remark | -- | 备注 |
| createdAt | TIMESTAMP | created_at | NOT NULL | 创建时间 |
| updatedAt | TIMESTAMP | updated_at | NOT NULL | 更新时间 |
| createdBy | UUID | created_by | -- | 创建人 |

**枚举定义**:

```java
public enum BillStatus {
    UNPAID("未支付"),
    PARTIAL_PAID("部分支付"),
    PAID("已支付"),
    OVERDUE("已逾期"),
    CANCELLED("已取消");
}

public enum BillSourceType {
    AUTO("自动生成"),
    MANUAL("手动创建"),
    IMPORT("导入");
}
```

**数据库索引**:

```sql
idx_fb_bill_no        -- (bill_no) -- UNIQUE约束自带索引
idx_fb_project_period -- (project_id, bill_period)
idx_fb_owner_status   -- (owner_id, status)
idx_fb_fee_item       -- (fee_item_id, bill_period)
idx_fb_space_node     -- (space_node_id, bill_period)
idx_fb_due_date       -- (due_date, status)  -- 用于催缴查询
idx_fb_overdue        -- (status, overdue_date) -- 用于滞纳金计算
```

**外键关系**:

```sql
fk_fb_fee_item   -- fee_item_id REFERENCES fin_fee_item(id)
fk_fb_project    -- project_id REFERENCES mdm_project(id)
fk_fb_space_node -- space_node_id REFERENCES mdm_space_node(id)
```

---

#### 2.2.3 FeePayment（支付记录）

**目标模块**: module-finance（待创建）
**目标表**: `fin_fee_payment`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| paymentNo | VARCHAR(30) | payment_no | NOT NULL, UNIQUE | 支付编号（PY + yyyyMMddHHmmss） |
| billId | UUID | bill_id | NOT NULL | 关联账单 |
| amount | DECIMAL(12,2) | amount | NOT NULL | 支付金额 |
| method | VARCHAR(20) | method | NOT NULL | 支付方式枚举 |
| thirdPartyNo | VARCHAR(100) | third_party_no | -- | 第三方交易号（微信/支付宝） |
| status | VARCHAR(20) | status | NOT NULL, 默认PENDING | 支付状态枚举 |
| failReason | VARCHAR(500) | fail_reason | -- | 失败原因 |
| paymentTime | TIMESTAMP | payment_time | -- | 实际支付时间 |
| operatorId | UUID | operator_id | -- | 操作人（线下收款时为收费员） |
| receiptNo | VARCHAR(30) | receipt_no | -- | 收据编号 |
| remark | VARCHAR(500) | remark | -- | 备注 |
| createdAt | TIMESTAMP | created_at | NOT NULL | 创建时间 |
| updatedAt | TIMESTAMP | updated_at | NOT NULL | 更新时间 |

**枚举定义**:

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

public enum PaymentStatus {
    PENDING("待支付"),
    SUCCESS("支付成功"),
    FAILED("支付失败"),
    REFUNDED("已退款");
}
```

**数据库索引**:

```sql
idx_fp_payment_no -- (payment_no) -- UNIQUE约束自带索引
idx_fp_bill_id    -- (bill_id)
idx_fp_status     -- (status, payment_time)
idx_fp_method     -- (method, payment_time)
idx_fp_operator   -- (operator_id, payment_time)
```

**外键关系**:

```sql
fk_fp_bill -- bill_id REFERENCES fin_fee_bill(id)
```

---

#### 2.2.4 FeeRefund（退款记录）

**目标模块**: module-finance（待创建）
**目标表**: `fin_fee_refund`

| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
|--------|------|-----------|------|------|
| id | UUID | id | PK | 主键 |
| refundNo | VARCHAR(30) | refund_no | NOT NULL, UNIQUE | 退款编号（RF + yyyyMMddHHmmss） |
| paymentId | UUID | payment_id | NOT NULL | 关联支付记录 |
| billId | UUID | bill_id | NOT NULL | 关联账单 |
| amount | DECIMAL(12,2) | amount | NOT NULL | 退款金额 |
| reason | VARCHAR(500) | reason | NOT NULL | 退款原因 |
| status | VARCHAR(20) | status | NOT NULL, 默认PENDING | 退款状态枚举 |
| applicantId | UUID | applicant_id | NOT NULL | 申请人ID |
| approverId | UUID | approver_id | -- | 审批人ID |
| approveTime | TIMESTAMP | approve_time | -- | 审批时间 |
| approveRemark | VARCHAR(500) | approve_remark | -- | 审批备注 |
| thirdPartyRefundNo | VARCHAR(100) | third_party_refund_no | -- | 第三方退款单号 |
| refundTime | TIMESTAMP | refund_time | -- | 实际退款时间 |
| refundMethod | VARCHAR(20) | refund_method | -- | 退款方式：ORIGINAL/OFFLINE |
| remark | VARCHAR(500) | remark | -- | 备注 |
| createdAt | TIMESTAMP | created_at | NOT NULL | 创建时间 |
| updatedAt | TIMESTAMP | updated_at | NOT NULL | 更新时间 |

**枚举定义**:

```java
public enum RefundStatus {
    PENDING("待审批"),
    APPROVED("已审批"),
    REJECTED("已拒绝"),
    REFUNDED("已退款"),
    FAILED("退款失败");
}

public enum RefundMethod {
    ORIGINAL("原路退回"),
    OFFLINE("线下退款");
}
```

**数据库索引**:

```sql
idx_fr_refund_no -- (refund_no) -- UNIQUE约束自带索引
idx_fr_payment   -- (payment_id)
idx_fr_bill      -- (bill_id)
idx_fr_status    -- (status)
idx_fr_applicant -- (applicant_id, status)
```

**外键关系**:

```sql
fk_fr_payment -- payment_id REFERENCES fin_fee_payment(id)
fk_fr_bill    -- bill_id REFERENCES fin_fee_bill(id)
```

---

### 2.3 实体关系图

```
EnergyMeter (module-mdm)              FeeItem (module-finance)
     |                                      |
     v                                      v
EnergyConsumption ---费用计算--->  FeeBill (自动/手动生成)
  (抄表数据)              |              |
                          |              +---> FeePayment (支付记录)
                          |                        |
                          |                        v
                          |                  FeeRefund (退款记录)
                          |
                          +-- sourceType=AUTO, sourceId=EnergyConsumption.id
```

**跨模块引用关系**:

- FeeBill.sourceId 可指向 EnergyConsumption.id（按用量计费时）
- FeeBill.spaceNodeId 引用 mdm_space_node.id
- FeeBill.ownerId 引用 auth_user.id（业主）
- FeePayment.operatorId 引用 auth_user.id（收费员）
- FeeRefund.applicantId / approverId 引用 auth_user.id

---

## 三、API设计

### 3.1 已实现API：能耗管理相关端点

**基础路径**: `/api/ops/energy`
**控制器**: `EnergyController`

#### 3.1.1 计量点管理

| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
|------|------|------|---------|---------|
| POST | `/meters` | 创建计量点 | EnergyMeter JSON | `ApiResponse<EnergyMeter>` |
| GET | `/meters` | 查询计量点列表 | projectId(必填), energyType(可选) | `ApiResponse<List<EnergyMeter>>` |
| GET | `/meters/{id}` | 获取计量点详情 | path: id | `ApiResponse<EnergyMeter>` |
| PUT | `/meters/{id}` | 更新计量点 | path: id, EnergyMeter JSON | `ApiResponse<EnergyMeter>` |
| DELETE | `/meters/{id}` | 删除计量点（软删除） | path: id | `ApiResponse<Void>` |

#### 3.1.2 能耗记录

| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
|------|------|------|---------|---------|
| POST | `/consumption` | 录入能耗数据 | `{meterId, currentReading, recordedBy}` | `ApiResponse<EnergyConsumption>` |
| GET | `/consumption/{meterId}` | 查询能耗记录 | path: meterId, startDate(可选), endDate(可选) | `ApiResponse<List<EnergyConsumption>>` |

#### 3.1.3 能耗统计

| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
|------|------|------|---------|---------|
| GET | `/statistics/by-type` | 按类型统计消耗 | projectId, month(yyyy-MM-dd) | `ApiResponse<Map<EnergyType, BigDecimal>>` |
| GET | `/statistics/unit-consumption` | 单方能耗 | projectId, month(yyyy-MM-dd) | `ApiResponse<BigDecimal>` |

---

### 3.2 待实现API：收费项目/账单/支付/退款相关端点

#### 3.2.1 FeeItemController -- 收费项目管理

**基础路径**: `/api/finance/fee-items`

| 方法 | 路径 | 说明 | 请求体/参数 | 响应类型 |
|------|------|------|------------|---------|
| POST | `/` | 创建收费项目 | FeeItemForm JSON | `ApiResponse<FeeItem>` |
| GET | `/` | 查询收费项目列表 | projectId(必填), type(可选), status(可选), page, size | `ApiResponse<PageResponse<FeeItem>>` |
| GET | `/{id}` | 获取收费项目详情 | path: id | `ApiResponse<FeeItem>` |
| PUT | `/{id}` | 更新收费项目 | path: id, FeeItemForm JSON | `ApiResponse<FeeItem>` |
| PUT | `/{id}/status` | 启用/禁用收费项目 | `{status: "ENABLED"/"DISABLED"}` | `ApiResponse<Void>` |
| DELETE | `/{id}` | 删除收费项目 | path: id | `ApiResponse<Void>` |

**FeeItemForm**:

```json
{
  "projectId": "UUID",
  "name": "物业费",
  "type": "PROPERTY",
  "billingMethod": "AREA",
  "unitPrice": 3.50,
  "unit": "平方米/月",
  "fixedAmount": null,
  "billDay": 1,
  "dueDay": 15,
  "overdueDay": 5,
  "enableLateFee": true,
  "lateFeeRate": 0.0005,
  "maxLateFee": 500.00,
  "description": "住宅物业费"
}
```

#### 3.2.2 FeeBillController -- 账单管理

**基础路径**: `/api/finance/bills`

| 方法 | 路径 | 说明 | 请求体/参数 | 响应类型 |
|------|------|------|------------|---------|
| POST | `/` | 手动创建账单 | FeeBillForm JSON | `ApiResponse<FeeBill>` |
| POST | `/generate` | 按收费项目自动生成账单 | `{projectId, feeItemId, billPeriod}` | `ApiResponse<List<FeeBill>>` |
| POST | `/generate-batch` | 批量生成账单 | `{projectId, billPeriod, feeItemIds[]}` | `ApiResponse<BatchResult>` |
| GET | `/` | 查询账单列表 | projectId, ownerId, status, billPeriod, page, size | `ApiResponse<PageResponse<FeeBill>>` |
| GET | `/{id}` | 获取账单详情 | path: id | `ApiResponse<FeeBill>` |
| PUT | `/{id}` | 更新账单 | path: id, FeeBillForm JSON | `ApiResponse<FeeBill>` |
| POST | `/{id}/cancel` | 取消账单 | `{reason}` | `ApiResponse<Void>` |
| GET | `/overdue` | 查询逾期账单 | projectId, page, size | `ApiResponse<PageResponse<FeeBill>>` |
| GET | `/statistics` | 账单统计 | projectId, billPeriod | `ApiResponse<BillStatistics>` |
| GET | `/export` | 导出账单 | projectId, billPeriod, format | `Blob` |

**FeeBillForm**:

```json
{
  "feeItemId": "UUID",
  "projectId": "UUID",
  "spaceNodeId": "UUID",
  "ownerId": "UUID",
  "billPeriod": "2026-05",
  "usageAmount": 150.50,
  "usageUnit": "kWh",
  "area": 120.00,
  "amount": 525.00,
  "remark": ""
}
```

**BillStatistics**:

```json
{
  "totalAmount": 150000.00,
  "paidAmount": 120000.00,
  "unpaidAmount": 30000.00,
  "overdueAmount": 15000.00,
  "lateFeeAmount": 500.00,
  "totalCount": 200,
  "paidCount": 160,
  "unpaidCount": 30,
  "overdueCount": 10
}
```

#### 3.2.3 FeePaymentController -- 支付管理

**基础路径**: `/api/finance/payments`

| 方法 | 路径 | 说明 | 请求体/参数 | 响应类型 |
|------|------|------|------------|---------|
| POST | `/` | 创建支付记录（线下收款） | PaymentForm JSON | `ApiResponse<FeePayment>` |
| GET | `/` | 查询支付记录 | billId, ownerId, method, status, startDate, endDate, page, size | `ApiResponse<PageResponse<FeePayment>>` |
| GET | `/{id}` | 获取支付详情 | path: id | `ApiResponse<FeePayment>` |
| POST | `/{id}/confirm` | 确认支付 | `{status: "SUCCESS"/"FAILED", failReason}` | `ApiResponse<FeePayment>` |
| POST | `/online/prepare` | 发起线上支付 | `{billId, method}` | `ApiResponse<PaymentPrepareResult>` |
| POST | `/online/callback` | 支付回调 | 第三方回调数据 | `ApiResponse<Void>` |

**PaymentForm**:

```json
{
  "billId": "UUID",
  "amount": 525.00,
  "method": "CASH",
  "receiptNo": "RCP20260518001",
  "remark": ""
}
```

#### 3.2.4 FeeRefundController -- 退款管理

**基础路径**: `/api/finance/refunds`

| 方法 | 路径 | 说明 | 请求体/参数 | 响应类型 |
|------|------|------|------------|---------|
| POST | `/` | 申请退款 | RefundForm JSON | `ApiResponse<FeeRefund>` |
| GET | `/` | 查询退款记录 | billId, status, startDate, endDate, page, size | `ApiResponse<PageResponse<FeeRefund>>` |
| GET | `/{id}` | 获取退款详情 | path: id | `ApiResponse<FeeRefund>` |
| POST | `/{id}/approve` | 审批通过 | `{approveRemark}` | `ApiResponse<FeeRefund>` |
| POST | `/{id}/reject` | 审批拒绝 | `{approveRemark}` | `ApiResponse<FeeRefund>` |
| POST | `/{id}/execute` | 执行退款 | `{thirdPartyRefundNo, refundMethod}` | `ApiResponse<FeeRefund>` |

**RefundForm**:

```json
{
  "paymentId": "UUID",
  "billId": "UUID",
  "amount": 525.00,
  "reason": "重复缴费",
  "refundMethod": "ORIGINAL"
}
```

#### 3.2.5 FeeReminderJob -- 催缴定时任务

| 任务 | Cron表达式 | 说明 |
|------|-----------|------|
| 到期提醒 | `0 0 9 * * ?` | 每天上午9点检查3天内到期账单，发送提醒 |
| 逾期催缴 | `0 0 10 * * ?` | 每天上午10点检查逾期账单，发送催缴通知 |
| 滞纳金计算 | `0 0 2 * * ?` | 每天凌晨2点计算逾期账单滞纳金 |
| 周汇总 | `0 0 18 ? * MON` | 每周一18点汇总逾期账单，通知项目经理 |

---

## 四、业务规则

### 4.1 能耗计费规则（已实现 + 待完善）

#### 4.1.1 已实现规则

| 规则编号 | 规则名称 | 规则描述 | 实现位置 |
|---------|---------|---------|---------|
| E-001 | 仪表状态校验 | 只能对ACTIVE状态的仪表进行抄表 | EnergyConsumptionServiceImpl |
| E-002 | 读数递增校验 | 当前读数不能小于上次读数 | EnergyConsumptionServiceImpl |
| E-003 | 自动获取上次读数 | 从最近一条记录获取previousReading，首次为0 | EnergyConsumptionServiceImpl |
| E-004 | 自动计算消耗量 | consumption = currentReading - previousReading | EnergyConsumptionServiceImpl |
| E-005 | 自动计算费用 | amount = consumption * meter.unitPrice（单价为空时为0） | EnergyConsumptionServiceImpl |
| E-006 | 按月统计 | 根据month参数计算月份起止日期 | EnergyConsumptionServiceImpl |
| E-007 | 单方能耗 | 遍历项目所有ACTIVE计量点，累加月度消耗量 | EnergyConsumptionServiceImpl |

#### 4.1.2 待修复缺陷

| 缺陷编号 | 描述 | 严重度 | 修复方案 |
|---------|------|--------|---------|
| E-BUG-001 | getConsumptionByType()将总消耗全部归入LIGHTING | 高 | 按 meter.energyType 真正分项汇总 |
| E-BUG-002 | 前后端能源类型枚举不一致 | 中 | 统一为后端6种枚举，前端对齐 |

---

### 4.2 收费项目规则（待设计）

| 规则编号 | 规则名称 | 规则描述 | 适用计费方式 |
|---------|---------|---------|------------|
| FI-001 | 周期性收费 | 按月/季/年定期出账，billDay指定出账日 | FIXED / AREA / USAGE |
| FI-002 | 一次性收费 | 临时创建，不参与自动出账 | CUSTOM |
| FI-003 | 临时收费 | 针对特定业主的临时性收费 | CUSTOM |
| FI-004 | 固定金额计费 | 每期收取固定金额（如停车费300元/月） | FIXED |
| FI-005 | 按面积计费 | 面积 * 单价（如物业费3.5元/平方米/月） | AREA |
| FI-006 | 按用量计费 | 用量 * 单价（如电费0.85元/kWh），对接能耗数据 | USAGE |
| FI-007 | 编码自动生成 | 格式：FI + yyyyMMddHHmmss，冲突时追加后缀 | 全部 |
| FI-008 | 禁用不删除 | 收费项目禁用后不再参与自动出账，已有账单不受影响 | 全部 |
| FI-009 | 项目隔离 | 收费项目属于特定项目，跨项目不可见 | 全部 |

---

### 4.3 账单生成规则（待设计）

| 规则编号 | 规则名称 | 规则描述 |
|---------|---------|---------|
| BL-001 | 自动生成 | 根据收费项目的billDay，定时任务自动为项目下所有业主生成账单 |
| BL-002 | 手动生成 | 管理员手动为指定业主创建账单 |
| BL-003 | 批量生成 | 一次性为项目所有业主生成某类收费项目的账单 |
| BL-004 | 账单编号生成 | 格式：BL + yyyyMMdd + 4位序号，序号按天递增 |
| BL-005 | 到期日计算 | dueDate = billDate + feeItem.dueDay天 |
| BL-006 | 逾期日计算 | overdueDate = dueDate + feeItem.overdueDay天 |
| BL-007 | 按用量计费账单 | 从EnergyConsumption获取当期用量，计算金额 |
| BL-008 | 按面积计费账单 | 从SpaceNode获取面积，计算金额 = 面积 * 单价 |
| BL-009 | 固定金额账单 | 金额 = feeItem.fixedAmount |
| BL-010 | 防重复生成 | 同一收费项目 + 同一业主 + 同一账期不可重复生成 |
| BL-011 | 催缴提醒 | 到期前3天发送提醒，逾期后发送催缴通知 |
| BL-012 | 账单取消 | 已支付/部分支付的账单不可取消，需先退款 |

---

### 4.4 支付流程（待设计）

| 规则编号 | 规则名称 | 规则描述 |
|---------|---------|---------|
| PY-001 | 线下收款 | 管理员登记现金/转账/刷卡收款，直接确认成功 |
| PY-002 | 线上支付 | 调用微信/支付宝SDK生成预支付单，等待回调确认 |
| PY-003 | 支付确认 | 线上支付由回调确认，线下支付由操作员确认 |
| PY-004 | 部分支付 | 支持部分支付，账单状态变为PARTIAL_PAID |
| PY-005 | 超额支付 | 支付金额不可超过应付金额（payableAmount - paidAmount） |
| PY-006 | 支付编号生成 | 格式：PY + yyyyMMddHHmmss |
| PY-007 | 账单状态联动 | 支付成功后更新账单paidAmount和status |
| PY-008 | 收据编号 | 线下收款时生成收据编号 |

**支付状态流转**:

```
PENDING --(支付成功)--> SUCCESS
PENDING --(支付失败)--> FAILED
SUCCESS --(发起退款)--> REFUNDED
```

**账单状态联动**:

```
UNPAID --(部分支付)--> PARTIAL_PAID
UNPAID/PARTIAL_PAID --(全额支付)--> PAID
UNPAID --(超过逾期日)--> OVERDUE
任意状态 --(取消)--> CANCELLED（需先退款）
```

---

### 4.5 退款流程（待设计）

| 规则编号 | 规则名称 | 规则描述 |
|---------|---------|---------|
| RF-001 | 退款申请 | 业主或管理员发起退款申请，需指定退款原因 |
| RF-002 | 退款金额限制 | 退款金额不可超过原支付金额 |
| RF-003 | 退款审批 | 退款金额 > 1000元需审批，否则自动通过 |
| RF-004 | 审批通过 | 审批人确认后，退款状态变为APPROVED |
| RF-005 | 审批拒绝 | 审批人可拒绝退款，需填写拒绝原因 |
| RF-006 | 原路退回 | 线上支付的退款原路退回至支付账户 |
| RF-007 | 线下退款 | 现金/转账支付的退款通过线下处理 |
| RF-008 | 退款执行 | 记录第三方退款单号和实际退款时间 |
| RF-009 | 账单金额回退 | 退款成功后，账单paidAmount减少，状态可能回退 |
| RF-010 | 退款编号生成 | 格式：RF + yyyyMMddHHmmss |

**退款状态流转**:

```
PENDING --(审批通过)--> APPROVED
PENDING --(审批拒绝)--> REJECTED
APPROVED --(退款成功)--> REFUNDED
APPROVED --(退款失败)--> FAILED
```

---

### 4.6 滞纳金计算（待设计）

| 规则编号 | 规则名称 | 规则描述 |
|---------|---------|---------|
| LF-001 | 计算触发 | 每天凌晨2点定时任务检查逾期账单 |
| LF-002 | 计算公式 | lateFee = 逾期天数 * payableAmount * lateFeeRate |
| LF-003 | 逾期天数 | 从overdueDate开始计算，到当前日期 |
| LF-004 | 上限控制 | lateFee不超过feeItem.maxLateFee |
| LF-005 | 累加计算 | 每天累加，不覆盖之前的滞纳金 |
| LF-006 | 前提条件 | 仅当feeItem.enableLateFee = true时计算 |
| LF-007 | 已支付账单 | 已全额支付的账单不再计算滞纳金 |
| LF-008 | 已取消账单 | 已取消的账单不再计算滞纳金 |
| LF-009 | 部分支付 | 滞纳金基于剩余应付金额计算 |

**滞纳金计算示例**:

```
假设：
  payableAmount = 1000元
  lateFeeRate = 0.0005（万分之五/天）
  maxLateFee = 500元
  overdueDate = 2026-05-10
  当前日期 = 2026-05-18

计算：
  逾期天数 = 8天
  每日滞纳金 = 1000 * 0.0005 = 0.5元
  累计滞纳金 = 8 * 0.5 = 4元（未超过上限500元）
```

---

## 五、执行约束

| 约束编号 | 约束名称 | 约束描述 |
|---------|---------|---------|
| CON-001 | 金额精度 | 所有金额字段使用DECIMAL(12,2)，单价使用DECIMAL(12,4)，利率使用DECIMAL(8,6) |
| CON-002 | 事务一致性 | 账单生成、支付确认、退款执行必须在同一事务中完成账单状态更新 |
| CON-003 | 并发控制 | 支付操作使用乐观锁（version字段或状态校验），防止重复支付 |
| CON-004 | 审计日志 | 所有收费/支付/退款操作必须记录审计日志 |
| CON-005 | 项目隔离 | 所有查询必须按projectId过滤，确保项目间数据隔离 |
| CON-006 | 软删除 | 收费项目使用启用/禁用替代物理删除，账单/支付/退款不允许删除 |
| CON-007 | 编码唯一性 | billNo/paymentNo/refundNo全局唯一，生成时需处理冲突 |
| CON-008 | 定时任务幂等 | 催缴/滞纳金计算任务必须幂等，重复执行不产生副作用 |

---

## 六、权限控制

| 权限编码 | 权限名称 | 适用角色 | 说明 |
|---------|---------|---------|------|
| finance:fee-item:list | 查看收费项目 | 项目管理员/财务人员 | 查看项目下收费项目列表 |
| finance:fee-item:create | 创建收费项目 | 系统管理员 | 创建新的收费项目 |
| finance:fee-item:update | 修改收费项目 | 系统管理员 | 修改收费项目配置 |
| finance:fee-item:delete | 删除收费项目 | 系统管理员 | 删除/禁用收费项目 |
| finance:bill:list | 查看账单 | 项目管理员/财务人员 | 查看项目下账单列表 |
| finance:bill:create | 创建账单 | 财务人员 | 手动创建账单 |
| finance:bill:generate | 生成账单 | 财务人员 | 自动/批量生成账单 |
| finance:bill:cancel | 取消账单 | 财务主管 | 取消账单（需审批） |
| finance:bill:export | 导出账单 | 财务人员 | 导出账单Excel/PDF |
| finance:payment:create | 登记收款 | 财务人员 | 线下收款登记 |
| finance:payment:confirm | 确认支付 | 财务人员 | 确认支付状态 |
| finance:payment:list | 查看支付记录 | 财务人员 | 查看支付记录列表 |
| finance:refund:apply | 申请退款 | 财务人员/业主 | 发起退款申请 |
| finance:refund:approve | 审批退款 | 财务主管 | 审批退款申请 |
| finance:refund:execute | 执行退款 | 财务人员 | 执行退款操作 |
| finance:refund:list | 查看退款记录 | 财务人员 | 查看退款记录列表 |
| finance:statistics:view | 查看财务统计 | 项目管理员/财务主管 | 查看财务报表 |
| finance:late-fee:config | 配置滞纳金 | 系统管理员 | 配置滞纳金规则 |

**数据级权限**:

- 财务人员（PROJECT数据范围）：只能查看/操作所属项目的财务数据
- 财务主管（ALL数据范围）：可查看所有项目的财务数据
- 业主（SELF数据范围）：只能查看自己的账单和支付记录

---

## 七、例外情况处理

| 例外编号 | 例外场景 | 处理策略 | 错误码 |
|---------|---------|---------|--------|
| EX-001 | 重复生成账单 | 检查feeItemId + ownerId + billPeriod唯一性，已存在则跳过 | 7001 |
| EX-002 | 支付金额超过应付金额 | 校验支付金额 <= payableAmount - paidAmount | 7002 |
| EX-003 | 已支付账单取消 | 拒绝取消，提示需先退款 | 7003 |
| EX-004 | 退款金额超过支付金额 | 校验退款金额 <= 原支付金额 | 7004 |
| EX-005 | 重复支付 | 状态校验，已支付/已退款的支付记录不可再次确认 | 7005 |
| EX-006 | 能耗数据缺失 | 按用量计费时无对应能耗记录，生成0元账单并标记异常 | 7006 |
| EX-007 | 业主无关联房产 | 生成账单时业主无房产关联，跳过并记录日志 | 7007 |
| EX-008 | 线上支付超时 | 支付状态保持PENDING，由对账任务处理 | 7008 |
| EX-009 | 线上支付回调异常 | 记录原始回调数据，人工介入处理 | 7009 |
| EX-010 | 滞纳金计算溢出 | lateFee不超过maxLateFee上限 | 7010 |
| EX-011 | 收费项目被禁用后自动出账 | 跳过已禁用的收费项目 | 7011 |
| EX-012 | 批量生成部分失败 | 记录成功/失败数量和失败原因，返回BatchResult | 7012 |