28 KiB

Raw Blame History

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

概述

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

基础信息

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

通用响应格式

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

请求体:

{
  "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": "主要制冷设备"
}

响应:

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

响应:

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

响应:

{
  "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: 设备类型枚举值

响应:

{
  "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: 报告人电话 (可选)

响应:

{
  "code": 200,
  "message": "success",
  "data": "uuid-work-order"
}

1.1.15 获取设备维修历史

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

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

路径参数:

id: 设备ID (UUID)

响应:

{
  "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，逗号分隔)

响应:

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

响应:

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

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

响应:

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

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

响应:

{
  "code": 200,
  "message": "success",
  "data": {
    "NORMAL": 120,
    "MAINTENANCE": 15,
    "FAULT": 10,
    "SCRAPPED": 5
  }
}

1.3.3 按类型统计

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

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

响应:

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

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

响应:

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

响应:

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

响应:

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

描述: 创建设备维保计划

请求体:

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

描述: 创建维保记录

请求体:

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

请求体:

{
  "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	其他费用

响应:

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

响应:

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

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

响应:

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

描述: 创建收费账单

请求体:

{
  "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": "张三"
}

响应:

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

响应:

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

响应:

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

响应:

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

响应:

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

响应:

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

响应:

{
  "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: 退款原因

响应:

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

响应:

{
  "code": 200,
  "message": "success",
  "data": true
}

2.4 统计分析

2.4.1 收费统计概览

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

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

响应:

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

描述: 获取今日应收金额

响应:

{
  "code": 200,
  "message": "success",
  "data": 15000.00
}

2.4.3 今日实收金额

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

描述: 获取今日实收金额

响应:

{
  "code": 200,
  "message": "success",
  "data": 12500.00
}

2.4.4 待收金额

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

描述: 获取待收金额

响应:

{
  "code": 200,
  "message": "success",
  "data": 85000.00
}

2.4.5 逾期金额

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

描述: 获取逾期金额

响应:

{
  "code": 200,
  "message": "success",
  "data": 25000.00
}

2.4.6 账单状态统计

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

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

响应:

{
  "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 相关文档

最后更新: 2026-02-20

28 KiB Raw Blame History Unescape Escape

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

概述

基础信息

通用响应格式

通用错误码

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

1.1 设备基础管理

1.1.1 创建设备

1.1.2 更新设备

1.1.3 删除设备

1.1.4 根据ID查询设备

1.1.5 根据编码查询设备

1.1.6 查询项目下所有设备

1.1.7 根据类型查询设备

1.1.8 根据状态查询设备

1.1.9 根据空间节点查询设备

1.1.10 搜索设备

1.1.11 更新设备状态

1.1.12 记录保养

1.1.13 生成设备编码

1.1.14 报告设备故障

1.1.15 获取设备维修历史

1.2 设备二维码管理

1.2.1 获取设备二维码

1.2.2 批量生成二维码

1.2.3 扫码获取设备信息

1.3 设备统计 API

1.3.1 设备概览统计

1.3.2 按状态统计

1.3.3 按类型统计

1.3.4 故障率统计

1.3.5 维保趋势统计

1.3.6 故障设备排行

1.4 维保计划管理

1.4.1 创建维保计划

1.4.2 查询维保计划列表

1.4.3 查询待执行的维保计划

1.4.4 执行维保计划

1.5 维保记录管理

1.5.1 创建维保记录

1.5.2 查询维保记录列表

1.5.3 开始维保

1.5.4 完成维保

1.5.5 取消维保

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

2.1 收费项目管理

2.1.1 创建收费项目

2.1.2 更新收费项目

2.1.3 删除收费项目

2.1.4 查询收费项目详情

2.1.5 查询收费项目列表

2.2 账单管理

2.2.1 创建账单

2.2.2 更新账单

2.2.3 删除账单

2.2.4 查询账单详情

2.2.5 查询账单列表

2.2.6 按状态查询账单

2.3 支付管理

2.3.1 创建支付

2.3.2 查询支付详情

2.3.3 查询支付记录列表

2.3.4 创建在线支付

2.3.5 查询支付状态

2.3.6 支付退款

2.3.7 关闭支付订单

2.4 统计分析

2.4.1 收费统计概览

2.4.2 今日应收金额

2.4.3 今日实收金额

2.4.4 待收金额

2.4.5 逾期金额

2.4.6 账单状态统计

2.5 导出功能

2.5.1 导出账单列表

2.5.2 导出支付记录

2.5.3 导出收费统计报表

2.5.4 导出业主缴费明细

3. 数据模型

28 KiB

Raw Blame History