1581 lines
28 KiB
Markdown
1581 lines
28 KiB
Markdown
# 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*
|