# Ether 智慧物业管理平台 - API 文档

## 概述

本文档描述了 Ether 智慧物业管理平台的 RESTful API 接口规范。

### 基础信息

- **基础URL**: `http://localhost:8080`
- **API版本**: v1
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON
- **字符编码**: UTF-8

### 通用响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

### 通用错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 1. 设备管理 API (ether-asset)

### 1.1 设备基础管理

#### 1.1.1 创建设备

**接口**: `POST /api/v1/asset/equipments`

**描述**: 创建新设备

**请求头**:
```
Authorization: Bearer {token}
X-Project-Id: {projectId}
```

**请求体**:
```json
{
  "code": "EQ-20260220-001",
  "name": "中央空调主机",
  "equipmentType": "HVAC",
  "brand": "格力",
  "model": "GMV-400W",
  "specifications": "制冷量: 40kW",
  "serialNumber": "SN20260220001",
  "manufacturer": "珠海格力电器股份有限公司",
  "supplier": "格力授权经销商",
  "spaceNodeId": "uuid-space-node",
  "locationDesc": "A栋1楼机房",
  "purchaseDate": "2026-01-15",
  "installDate": "2026-01-20",
  "warrantyDate": "2028-01-20",
  "purchasePrice": 150000.00,
  "serviceLife": 15,
  "maintenanceCycle": 90,
  "managerId": "uuid-manager",
  "managerName": "张三",
  "contactPhone": "13800138000",
  "images": "url1,url2",
  "manualUrl": "https://example.com/manual.pdf",
  "remarks": "主要制冷设备"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-equipment",
    "projectId": "uuid-project",
    "code": "EQ-20260220-001",
    "name": "中央空调主机",
    "equipmentType": "HVAC",
    "status": "NORMAL",
    ...
    "createdAt": "2026-02-20T10:30:00"
  }
}
```

---

#### 1.1.2 更新设备

**接口**: `PUT /api/v1/asset/equipments/{id}`

**描述**: 更新设备信息

**路径参数**:
- `id`: 设备ID (UUID)

**请求体**: 同创建设备

**响应**: 同创建设备

---

#### 1.1.3 删除设备

**接口**: `DELETE /api/v1/asset/equipments/{id}`

**描述**: 删除设备

**路径参数**:
- `id`: 设备ID (UUID)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

---

#### 1.1.4 根据ID查询设备

**接口**: `GET /api/v1/asset/equipments/{id}`

**描述**: 根据ID获取设备详情

**路径参数**:
- `id`: 设备ID (UUID)

**响应**: 同创建设备响应

---

#### 1.1.5 根据编码查询设备

**接口**: `GET /api/v1/asset/equipments/code/{code}`

**描述**: 根据设备编码获取设备信息

**路径参数**:
- `code`: 设备编码

**响应**: 同创建设备响应

---

#### 1.1.6 查询项目下所有设备

**接口**: `GET /api/v1/asset/equipments`

**描述**: 获取当前项目下所有设备列表

**请求头**:
```
Authorization: Bearer {token}
X-Project-Id: {projectId}
```

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "uuid-equipment-1",
      "code": "EQ-001",
      "name": "设备1",
      ...
    },
    {
      "id": "uuid-equipment-2",
      "code": "EQ-002",
      "name": "设备2",
      ...
    }
  ]
}
```

---

#### 1.1.7 根据类型查询设备

**接口**: `GET /api/v1/asset/equipments/type/{equipmentType}`

**描述**: 根据设备类型查询设备列表

**路径参数**:
- `equipmentType`: 设备类型枚举值

**设备类型枚举**:
| 枚举值 | 说明 |
|--------|------|
| HVAC | 暖通空调 |
| ELEVATOR | 电梯设备 |
| FIRE_FIGHTING | 消防设备 |
| ELECTRICAL | 电气设备 |
| WATER_SUPPLY | 给排水设备 |
| SECURITY | 安防设备 |
| PARKING | 停车设备 |
| CLEANING | 清洁设备 |
| LANDSCAPE | 园林设备 |
| OTHER | 其他设备 |

**响应**: 同查询项目下所有设备

---

#### 1.1.8 根据状态查询设备

**接口**: `GET /api/v1/asset/equipments/status/{status}`

**描述**: 根据设备状态查询设备列表

**路径参数**:
- `status`: 设备状态枚举值

**设备状态枚举**:
| 枚举值 | 说明 |
|--------|------|
| NORMAL | 正常 |
| MAINTENANCE | 维修中 |
| FAULT | 故障 |
| SCRAPPED | 报废 |

**响应**: 同查询项目下所有设备

---

#### 1.1.9 根据空间节点查询设备

**接口**: `GET /api/v1/asset/equipments/space-node/{spaceNodeId}`

**描述**: 根据空间节点ID查询设备列表

**路径参数**:
- `spaceNodeId`: 空间节点ID (UUID)

**响应**: 同查询项目下所有设备

---

#### 1.1.10 搜索设备

**接口**: `GET /api/v1/asset/equipments/search`

**描述**: 根据设备名称模糊搜索

**查询参数**:
- `name`: 设备名称关键词

**响应**: 同查询项目下所有设备

---

#### 1.1.11 更新设备状态

**接口**: `PATCH /api/v1/asset/equipments/{id}/status`

**描述**: 更新设备运行状态

**路径参数**:
- `id`: 设备ID (UUID)

**查询参数**:
- `status`: 设备状态枚举值

**响应**: 同创建设备响应

---

#### 1.1.12 记录保养

**接口**: `POST /api/v1/asset/equipments/{id}/maintenance`

**描述**: 记录设备保养操作

**路径参数**:
- `id`: 设备ID (UUID)

**响应**: 同创建设备响应

---

#### 1.1.13 生成设备编码

**接口**: `GET /api/v1/asset/equipments/generate-code`

**描述**: 生成新的设备编码

**查询参数**:
- `equipmentType`: 设备类型枚举值

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": "EQ-HVAC-20260220-001"
}
```

---

#### 1.1.14 报告设备故障

**接口**: `POST /api/v1/asset/equipments/{id}/report-fault`

**描述**: 报告设备故障，自动创建维修工单

**路径参数**:
- `id`: 设备ID (UUID)

**查询参数**:
- `faultDescription`: 故障描述 (必填)
- `reporterId`: 报告人ID (可选)
- `reporterName`: 报告人姓名 (可选)
- `reporterPhone`: 报告人电话 (可选)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": "uuid-work-order"
}
```

---

#### 1.1.15 获取设备维修历史

**接口**: `GET /api/v1/asset/equipments/{id}/repair-history`

**描述**: 获取设备维修工单历史记录

**路径参数**:
- `id`: 设备ID (UUID)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "workOrderId": "uuid-work-order",
      "workOrderNo": "WO-20260220-001",
      "title": "空调故障维修",
      "status": "COMPLETED",
      "createdAt": "2026-02-15T10:00:00"
    }
  ]
}
```

---

### 1.2 设备二维码管理

#### 1.2.1 获取设备二维码

**接口**: `GET /api/v1/asset/equipment/qrcode/{equipmentId}`

**描述**: 生成并返回设备二维码图片

**路径参数**:
- `equipmentId`: 设备ID (UUID)

**响应**: 
- Content-Type: image/png
- 返回二维码图片二进制数据

---

#### 1.2.2 批量生成二维码

**接口**: `GET /api/v1/asset/equipment/qrcode/batch`

**描述**: 批量生成设备二维码信息

**查询参数**:
- `equipmentIds`: 设备ID列表 (多个UUID，逗号分隔)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "equipmentId": "uuid-1",
      "equipmentCode": "EQ-001",
      "equipmentName": "设备1",
      "qrCodeUrl": "/api/v1/asset/equipment/qrcode/uuid-1"
    }
  ]
}
```

---

#### 1.2.3 扫码获取设备信息

**接口**: `GET /api/v1/asset/equipment/qrcode/info/{qrCode}`

**描述**: 通过二维码内容获取设备信息

**路径参数**:
- `qrCode`: 二维码内容 (格式: EQUIPMENT:{uuid})

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-equipment",
    "code": "EQ-001",
    "name": "中央空调主机",
    "type": "暖通空调",
    "status": "正常",
    "location": "A栋1楼机房",
    "brand": "格力",
    "model": "GMV-400W"
  }
}
```

---

### 1.3 设备统计 API

#### 1.3.1 设备概览统计

**接口**: `GET /api/v1/asset/equipment/statistics/overview`

**描述**: 获取设备总体统计数据

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 150,
    "normal": 120,
    "maintenance": 15,
    "fault": 10,
    "scrapped": 5,
    "maintenanceRate": 10.0,
    "faultRate": 6.67
  }
}
```

---

#### 1.3.2 按状态统计

**接口**: `GET /api/v1/asset/equipment/statistics/by-status`

**描述**: 按设备状态统计数量

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "NORMAL": 120,
    "MAINTENANCE": 15,
    "FAULT": 10,
    "SCRAPPED": 5
  }
}
```

---

#### 1.3.3 按类型统计

**接口**: `GET /api/v1/asset/equipment/statistics/by-type`

**描述**: 按设备类型统计数量

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "HVAC": 30,
    "ELEVATOR": 10,
    "FIRE_FIGHTING": 25,
    "ELECTRICAL": 40,
    "WATER_SUPPLY": 20,
    "SECURITY": 15,
    "OTHER": 10
  }
}
```

---

#### 1.3.4 故障率统计

**接口**: `GET /api/v1/asset/equipment/statistics/fault-rate`

**描述**: 获取设备故障率统计

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalFaults": 25,
    "totalEquipment": 150,
    "faultRate": 16.67,
    "monthlyFaults": [
      {"month": "2026-01", "count": 8},
      {"month": "2026-02", "count": 5}
    ]
  }
}
```

---

#### 1.3.5 维保趋势统计

**接口**: `GET /api/v1/asset/equipment/statistics/maintenance-trend`

**描述**: 获取设备维保趋势数据

**查询参数**:
- `days`: 统计天数 (默认30天)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalMaintenance": 45,
    "completedMaintenance": 40,
    "pendingMaintenance": 5,
    "dailyTrend": [
      {"date": "2026-02-19", "count": 3},
      {"date": "2026-02-20", "count": 2}
    ]
  }
}
```

---

#### 1.3.6 故障设备排行

**接口**: `GET /api/v1/asset/equipment/statistics/top-fault`

**描述**: 获取故障次数最多的设备排行

**查询参数**:
- `limit`: 返回数量 (默认10)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "topFaultEquipment": [
      {
        "equipmentId": "uuid-1",
        "equipmentCode": "EQ-001",
        "equipmentName": "电梯A",
        "faultCount": 5
      }
    ]
  }
}
```

---

### 1.4 维保计划管理

#### 1.4.1 创建维保计划

**接口**: `POST /api/v1/asset/maintenance-plans`

**描述**: 创建设备维保计划

**请求体**:
```json
{
  "equipmentId": "uuid-equipment",
  "planName": "季度保养计划",
  "planType": "PERIODIC",
  "frequency": "QUARTERLY",
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "nextExecutionDate": "2026-03-01",
  "content": "检查制冷系统、清洁滤网、检查电气连接",
  "estimatedDuration": 120,
  "estimatedCost": 500.00,
  "executorId": "uuid-executor",
  "executorName": "李四",
  "remarks": "每季度执行一次"
}
```

**响应**: 返回创建的维保计划详情

---

#### 1.4.2 查询维保计划列表

**接口**: `GET /api/v1/asset/maintenance-plans`

**描述**: 分页查询维保计划列表

**查询参数**:
- `page`: 页码 (默认0)
- `size`: 每页数量 (默认20)
- `sortBy`: 排序字段 (默认createdAt)
- `sortDir`: 排序方向 (ASC/DESC，默认DESC)

**响应**: 返回分页的维保计划列表

---

#### 1.4.3 查询待执行的维保计划

**接口**: `GET /api/v1/asset/maintenance-plans/executable`

**描述**: 查询指定日期可执行的维保计划

**查询参数**:
- `date`: 查询日期 (格式: yyyy-MM-dd)

**响应**: 返回待执行的维保计划列表

---

#### 1.4.4 执行维保计划

**接口**: `POST /api/v1/asset/maintenance-plans/{id}/execute`

**描述**: 执行维保计划，创建维保记录

**路径参数**:
- `id`: 维保计划ID

**响应**: 返回创建的维保记录ID

---

### 1.5 维保记录管理

#### 1.5.1 创建维保记录

**接口**: `POST /api/v1/asset/maintenance-records`

**描述**: 创建维保记录

**请求体**:
```json
{
  "equipmentId": "uuid-equipment",
  "planId": "uuid-plan",
  "maintenanceType": "PERIODIC",
  "scheduledDate": "2026-02-20",
  "content": "清洁滤网、检查制冷剂、检查电气连接",
  "executorId": "uuid-executor",
  "executorName": "李四",
  "estimatedCost": 500.00
}
```

**响应**: 返回创建的维保记录详情

---

#### 1.5.2 查询维保记录列表

**接口**: `GET /api/v1/asset/maintenance-records`

**描述**: 分页查询维保记录列表

**查询参数**:
- `page`: 页码 (默认0)
- `size`: 每页数量 (默认20)
- `sortBy`: 排序字段 (默认createdAt)
- `sortDir`: 排序方向 (ASC/DESC，默认DESC)

**响应**: 返回分页的维保记录列表

---

#### 1.5.3 开始维保

**接口**: `PATCH /api/v1/asset/maintenance-records/{id}/start`

**描述**: 开始执行维保任务

**路径参数**:
- `id`: 维保记录ID

**响应**: 返回更新后的维保记录

---

#### 1.5.4 完成维保

**接口**: `PATCH /api/v1/asset/maintenance-records/{id}/complete`

**描述**: 完成维保任务

**路径参数**:
- `id`: 维保记录ID

**查询参数**:
- `result`: 维保结果描述 (必填)
- `images`: 维保图片URL (可选)

**响应**: 返回更新后的维保记录

---

#### 1.5.5 取消维保

**接口**: `PATCH /api/v1/asset/maintenance-records/{id}/cancel`

**描述**: 取消维保任务

**路径参数**:
- `id`: 维保记录ID

**查询参数**:
- `reason`: 取消原因 (必填)

**响应**: 返回更新后的维保记录

---

## 2. 收费管理 API (ether-finance)

### 2.1 收费项目管理

#### 2.1.1 创建收费项目

**接口**: `POST /api/v1/finance/fee-items`

**描述**: 创建新的收费项目

**请求头**:
```
Authorization: Bearer {token}
X-Project-Id: {projectId}
```

**请求体**:
```json
{
  "itemCode": "FI-001",
  "itemName": "物业管理费",
  "feeType": "PROPERTY_MANAGEMENT",
  "unitPrice": 3.50,
  "unit": "元/平方米/月",
  "billingCycle": "MONTHLY",
  "description": "按建筑面积收取",
  "sortOrder": 1
}
```

**收费类型枚举**:
| 枚举值 | 说明 |
|--------|------|
| PROPERTY_MANAGEMENT | 物业管理费 |
| WATER | 水费 |
| ELECTRICITY | 电费 |
| GAS | 燃气费 |
| PARKING | 停车费 |
| DECORATION_DEPOSIT | 装修押金 |
| PROPERTY_MAINTENANCE | 物业维修基金 |
| OTHER | 其他费用 |

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-fee-item",
    "projectId": "uuid-project",
    "itemCode": "FI-001",
    "itemName": "物业管理费",
    "feeType": "PROPERTY_MANAGEMENT",
    "unitPrice": 3.50,
    "unit": "元/平方米/月",
    "billingCycle": "MONTHLY",
    "enabled": true,
    "createdAt": "2026-02-20T10:30:00"
  }
}
```

---

#### 2.1.2 更新收费项目

**接口**: `PUT /api/v1/finance/fee-items/{id}`

**描述**: 更新收费项目信息

**路径参数**:
- `id`: 收费项目ID (UUID)

**请求体**: 同创建收费项目

**响应**: 同创建收费项目

---

#### 2.1.3 删除收费项目

**接口**: `DELETE /api/v1/finance/fee-items/{id}`

**描述**: 删除收费项目

**路径参数**:
- `id`: 收费项目ID (UUID)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

---

#### 2.1.4 查询收费项目详情

**接口**: `GET /api/v1/finance/fee-items/{id}`

**描述**: 根据ID获取收费项目详情

**路径参数**:
- `id`: 收费项目ID (UUID)

**响应**: 同创建收费项目

---

#### 2.1.5 查询收费项目列表

**接口**: `GET /api/v1/finance/fee-items`

**描述**: 获取当前项目下所有收费项目列表

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "uuid-1",
      "itemCode": "FI-001",
      "itemName": "物业管理费",
      ...
    },
    {
      "id": "uuid-2",
      "itemCode": "FI-002",
      "itemName": "水费",
      ...
    }
  ]
}
```

---

### 2.2 账单管理

#### 2.2.1 创建账单

**接口**: `POST /api/v1/finance/bills`

**描述**: 创建收费账单

**请求体**:
```json
{
  "houseId": "uuid-house",
  "contractId": "uuid-contract",
  "houseNo": "A栋1单元101",
  "ownerId": "uuid-owner",
  "ownerName": "王五",
  "ownerPhone": "13900139000",
  "feeItemId": "uuid-fee-item",
  "feeType": "PROPERTY_MANAGEMENT",
  "feeItemName": "物业管理费",
  "billingPeriodStart": "2026-02-01",
  "billingPeriodEnd": "2026-02-28",
  "quantity": 100.00,
  "unit": "平方米",
  "unitPrice": 3.50,
  "amount": 350.00,
  "discountAmount": 0,
  "lateFee": 0,
  "totalAmount": 350.00,
  "dueDate": "2026-03-10",
  "description": "2026年2月物业管理费",
  "issuedBy": "张三"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-bill",
    "projectId": "uuid-project",
    "billNo": "FB20260220001",
    "houseNo": "A栋1单元101",
    "ownerName": "王五",
    "feeItemName": "物业管理费",
    "totalAmount": 350.00,
    "paidAmount": 0,
    "unpaidAmount": 350.00,
    "status": "PENDING",
    "dueDate": "2026-03-10",
    "createdAt": "2026-02-20T10:30:00"
  }
}
```

---

#### 2.2.2 更新账单

**接口**: `PUT /api/v1/finance/bills/{id}`

**描述**: 更新账单信息

**路径参数**:
- `id`: 账单ID (UUID)

**请求体**: 同创建账单

**响应**: 同创建账单

---

#### 2.2.3 删除账单

**接口**: `DELETE /api/v1/finance/bills/{id}`

**描述**: 删除账单

**路径参数**:
- `id`: 账单ID (UUID)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

---

#### 2.2.4 查询账单详情

**接口**: `GET /api/v1/finance/bills/{id}`

**描述**: 根据ID获取账单详情

**路径参数**:
- `id`: 账单ID (UUID)

**响应**: 同创建账单

---

#### 2.2.5 查询账单列表

**接口**: `GET /api/v1/finance/bills`

**描述**: 分页查询账单列表

**查询参数**:
- `page`: 页码 (默认0)
- `size`: 每页数量 (默认20)
- `sort`: 排序字段 (默认createdAt)
- `direction`: 排序方向 (ASC/DESC，默认DESC)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": "uuid-bill-1",
        "billNo": "FB20260220001",
        ...
      }
    ],
    "totalElements": 100,
    "totalPages": 5,
    "number": 0,
    "size": 20
  }
}
```

---

#### 2.2.6 按状态查询账单

**接口**: `GET /api/v1/finance/bills/by-status`

**描述**: 根据状态查询账单列表

**查询参数**:
- `status`: 账单状态枚举值

**账单状态枚举**:
| 枚举值 | 说明 |
|--------|------|
| PENDING | 待缴费 |
| PARTIAL | 部分缴费 |
| PAID | 已缴清 |
| OVERDUE | 已逾期 |
| CANCELLED | 已取消 |

**响应**: 返回账单列表

---

### 2.3 支付管理

#### 2.3.1 创建支付

**接口**: `POST /api/v1/finance/bills/{billId}/pay`

**描述**: 为账单创建支付记录

**路径参数**:
- `billId`: 账单ID (UUID)

**查询参数**:
- `amount`: 支付金额 (必填)
- `method`: 支付方式 (必填)

**支付方式枚举**:
| 枚举值 | 说明 |
|--------|------|
| CASH | 现金 |
| WECHAT | 微信支付 |
| ALIPAY | 支付宝 |
| BANK_TRANSFER | 银行转账 |
| OTHER | 其他 |

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-payment",
    "paymentNo": "FP20260220001",
    "billNo": "FB20260220001",
    "amount": 350.00,
    "paymentMethod": "WECHAT",
    "status": "SUCCESS",
    "paymentTime": "2026-02-20T14:30:00",
    "payerName": "王五",
    "transactionNo": "WX20260220143000001"
  }
}
```

---

#### 2.3.2 查询支付详情

**接口**: `GET /api/v1/finance/payments/{id}`

**描述**: 根据ID获取支付记录详情

**路径参数**:
- `id`: 支付记录ID (UUID)

**响应**: 同创建支付

---

#### 2.3.3 查询支付记录列表

**接口**: `GET /api/v1/finance/payments`

**描述**: 分页查询支付记录列表

**查询参数**:
- `page`: 页码 (默认0)
- `size`: 每页数量 (默认20)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": "uuid-payment-1",
        "paymentNo": "FP20260220001",
        ...
      }
    ],
    "totalElements": 50,
    "totalPages": 3,
    "number": 0,
    "size": 20
  }
}
```

---

#### 2.3.4 创建在线支付

**接口**: `POST /api/v1/finance/payments/create`

**描述**: 创建在线支付订单（微信/支付宝）

**查询参数**:
- `billId`: 账单ID
- `method`: 支付方式 (WECHAT/ALIPAY)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "paymentNo": "FP20260220001",
    "prepayId": "wx_prepay_id",
    "codeUrl": "weixin://wxpay/bizpayurl?...",
    "message": "支付订单创建成功"
  }
}
```

---

#### 2.3.5 查询支付状态

**接口**: `GET /api/v1/finance/payments/query/{paymentNo}`

**描述**: 查询在线支付订单状态

**路径参数**:
- `paymentNo`: 支付单号

**查询参数**:
- `method`: 支付方式 (WECHAT/ALIPAY)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "paymentNo": "FP20260220001",
    "status": "SUCCESS",
    "amount": 350.00,
    "paymentTime": "2026-02-20T14:30:00"
  }
}
```

---

#### 2.3.6 支付退款

**接口**: `POST /api/v1/finance/payments/refund/{paymentId}`

**描述**: 申请支付退款

**路径参数**:
- `paymentId`: 支付记录ID (UUID)

**查询参数**:
- `refundAmount`: 退款金额
- `reason`: 退款原因

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "refundNo": "RF20260220001",
    "refundAmount": 350.00,
    "message": "退款申请成功"
  }
}
```

---

#### 2.3.7 关闭支付订单

**接口**: `POST /api/v1/finance/payments/close/{paymentNo}`

**描述**: 关闭未支付的支付订单

**路径参数**:
- `paymentNo`: 支付单号

**查询参数**:
- `method`: 支付方式 (WECHAT/ALIPAY)

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": true
}
```

---

### 2.4 统计分析

#### 2.4.1 收费统计概览

**接口**: `GET /api/v1/finance/statistics`

**描述**: 获取收费统计数据概览

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "todayReceivable": 15000.00,
    "todayReceived": 12500.00,
    "outstandingAmount": 85000.00,
    "overdueAmount": 25000.00,
    "totalBills": 500,
    "pendingBills": 120,
    "paidBills": 350,
    "overdueBills": 30
  }
}
```

---

#### 2.4.2 今日应收金额

**接口**: `GET /api/v1/finance/statistics/today-receivable`

**描述**: 获取今日应收金额

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": 15000.00
}
```

---

#### 2.4.3 今日实收金额

**接口**: `GET /api/v1/finance/statistics/today-received`

**描述**: 获取今日实收金额

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": 12500.00
}
```

---

#### 2.4.4 待收金额

**接口**: `GET /api/v1/finance/statistics/pending-amount`

**描述**: 获取待收金额

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": 85000.00
}
```

---

#### 2.4.5 逾期金额

**接口**: `GET /api/v1/finance/statistics/overdue-amount`

**描述**: 获取逾期金额

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": 25000.00
}
```

---

#### 2.4.6 账单状态统计

**接口**: `GET /api/v1/finance/statistics/bill-status-count`

**描述**: 按状态统计账单数量

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "PENDING": 120,
    "PARTIAL": 30,
    "PAID": 350,
    "OVERDUE": 30,
    "CANCELLED": 5
  }
}
```

---

### 2.5 导出功能

#### 2.5.1 导出账单列表

**接口**: `GET /api/v1/finance/bills/export`

**描述**: 导出账单列表为Excel文件

**查询参数**:
- `status`: 账单状态 (可选)
- `startDate`: 开始日期 (可选)
- `endDate`: 结束日期 (可选)

**响应**: 
- Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- 返回Excel文件

---

#### 2.5.2 导出支付记录

**接口**: `GET /api/v1/finance/payments/export`

**描述**: 导出支付记录为Excel文件

**查询参数**:
- `startDate`: 开始日期 (可选)
- `endDate`: 结束日期 (可选)

**响应**: 
- Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- 返回Excel文件

---

#### 2.5.3 导出收费统计报表

**接口**: `GET /api/v1/finance/statistics/export`

**描述**: 导出收费统计报表为Excel文件

**查询参数**:
- `startDate`: 开始日期 (可选)
- `endDate`: 结束日期 (可选)

**响应**: 
- Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- 返回Excel文件

---

#### 2.5.4 导出业主缴费明细

**接口**: `GET /api/v1/finance/owner/{ownerId}/payment-detail/export`

**描述**: 导出指定业主的缴费明细

**路径参数**:
- `ownerId`: 业主ID (UUID)

**查询参数**:
- `startDate`: 开始日期 (可选)
- `endDate`: 结束日期 (可选)

**响应**: 
- Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- 返回Excel文件

---

## 3. 数据模型

### 3.1 设备实体 (Equipment)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | UUID | 主键 |
| projectId | UUID | 项目ID |
| code | String | 设备编码 |
| name | String | 设备名称 |
| equipmentType | Enum | 设备类型 |
| status | Enum | 设备状态 |
| brand | String | 品牌 |
| model | String | 型号 |
| specifications | String | 规格参数 |
| serialNumber | String | 序列号 |
| manufacturer | String | 生产厂家 |
| supplier | String | 供应商 |
| spaceNodeId | UUID | 安装位置ID |
| locationDesc | String | 位置描述 |
| purchaseDate | LocalDate | 购置日期 |
| installDate | LocalDate | 安装日期 |
| warrantyDate | LocalDate | 保修期至 |
| purchasePrice | BigDecimal | 购置价格 |
| serviceLife | Integer | 使用年限 |
| maintenanceCycle | Integer | 保养周期 |
| lastMaintenanceDate | LocalDate | 上次保养日期 |
| nextMaintenanceDate | LocalDate | 下次保养日期 |
| managerId | UUID | 负责人ID |
| managerName | String | 负责人姓名 |
| contactPhone | String | 联系电话 |
| images | String | 设备图片 |
| manualUrl | String | 说明书URL |
| remarks | String | 备注 |
| attributes | JSON | 扩展属性 |
| createdAt | LocalDateTime | 创建时间 |
| updatedAt | LocalDateTime | 更新时间 |

---

### 3.2 收费项目实体 (FeeItem)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | UUID | 主键 |
| projectId | UUID | 项目ID |
| itemCode | String | 项目编码 |
| itemName | String | 项目名称 |
| feeType | Enum | 收费类型 |
| unitPrice | BigDecimal | 单价 |
| unit | String | 单位 |
| billingCycle | String | 计费周期 |
| description | String | 描述 |
| enabled | Boolean | 是否启用 |
| sortOrder | Integer | 排序 |
| createdAt | LocalDateTime | 创建时间 |
| updatedAt | LocalDateTime | 更新时间 |

---

### 3.3 账单实体 (FeeBill)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | UUID | 主键 |
| projectId | UUID | 项目ID |
| billNo | String | 账单号 |
| houseId | UUID | 房屋ID |
| contractId | UUID | 合同ID |
| houseNo | String | 房屋编号 |
| ownerId | UUID | 业主ID |
| ownerName | String | 业主姓名 |
| ownerPhone | String | 业主电话 |
| feeItemId | UUID | 收费项目ID |
| feeType | Enum | 收费类型 |
| feeItemName | String | 收费项目名称 |
| billingPeriodStart | LocalDate | 计费开始日期 |
| billingPeriodEnd | LocalDate | 计费结束日期 |
| quantity | BigDecimal | 数量 |
| unit | String | 单位 |
| unitPrice | BigDecimal | 单价 |
| amount | BigDecimal | 金额 |
| discountAmount | BigDecimal | 优惠金额 |
| lateFee | BigDecimal | 滞纳金 |
| totalAmount | BigDecimal | 总金额 |
| paidAmount | BigDecimal | 已付金额 |
| unpaidAmount | BigDecimal | 未付金额 |
| status | Enum | 账单状态 |
| dueDate | LocalDate | 缴费截止日期 |
| overdueDays | Integer | 逾期天数 |
| description | String | 描述 |
| remarks | String | 备注 |
| issuedBy | String | 开单人 |
| issuedAt | LocalDateTime | 开单时间 |
| createdAt | LocalDateTime | 创建时间 |
| updatedAt | LocalDateTime | 更新时间 |

---

## 4. 附录

### 4.1 服务端口

| 服务 | 端口 |
|------|------|
| ether-gateway | 8080 |
| ether-auth | 8081 |
| ether-mdm | 8082 |
| ether-ops | 8083 |
| ether-finance | 8085 |
| ether-asset | 8084 |

### 4.2 相关文档

- [待开发功能列表](./pending-features.md)
- [数据库设计](./02-DESIGN/domains/03-ASSET.md)
- [领域模型设计](./02-DESIGN/domains/04-FINANCE.md)

---

*最后更新: 2026-02-20*