553 lines
10 KiB
Markdown
553 lines
10 KiB
Markdown
# RentEase API 接口文档
|
||
|
||
## 文档说明
|
||
|
||
本文档定义了 RentEase 租赁管理平台的统一 API 接口规范，用于前后端交互。
|
||
|
||
## 基础信息
|
||
|
||
### 服务器地址
|
||
|
||
| 环境 | 地址 |
|
||
|------|------|
|
||
| 开发环境 | http://localhost:3000 |
|
||
| 生产环境 | https://api.rentease.com |
|
||
|
||
### 请求前缀
|
||
|
||
所有 API 请求都需要加上前缀 `/api`
|
||
|
||
### 响应格式
|
||
|
||
所有 API 响应统一返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200, // 状态码，200表示成功
|
||
"message": "操作成功", // 提示信息
|
||
"data": {} // 返回数据
|
||
}
|
||
```
|
||
|
||
### 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权，Token无效或过期 |
|
||
| 403 | 禁止访问，权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 认证模块 (Auth)
|
||
|
||
### 1. 用户登录
|
||
|
||
- **接口地址**: `POST /api/auth/login`
|
||
- **是否需要认证**: 否
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | string | 是 | 用户名/手机号 |
|
||
| password | string | 是 | 密码 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"userInfo": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"nickname": "管理员",
|
||
"role": {
|
||
"id": 1,
|
||
"name": "管理员",
|
||
"code": "admin"
|
||
},
|
||
"tenantId": 1,
|
||
"userType": "tenant_admin"
|
||
},
|
||
"tenant": {
|
||
"id": 1,
|
||
"name": "测试租户",
|
||
"code": "test",
|
||
"status": "active"
|
||
},
|
||
"menus": [
|
||
{
|
||
"id": 1,
|
||
"name": "首页",
|
||
"path": "/pages/home/home",
|
||
"icon": "home-filled"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 租户自助注册
|
||
|
||
- **接口地址**: `POST /api/auth/register-tenant`
|
||
- **是否需要认证**: 否
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| name | string | 是 | 租户名称 |
|
||
| code | string | 是 | 租户编码（唯一标识） |
|
||
| description | string | 否 | 租户描述 |
|
||
| contactName | string | 是 | 联系人姓名 |
|
||
| contactPhone | string | 是 | 联系人电话 |
|
||
| contactEmail | string | 是 | 联系人邮箱 |
|
||
| adminUsername | string | 是 | 管理员账号 |
|
||
| adminPassword | string | 是 | 管理员密码 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "注册成功，欢迎试用",
|
||
"data": {
|
||
"tenantId": 1,
|
||
"name": "测试租户",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 用户登出
|
||
|
||
- **接口地址**: `POST /api/auth/logout`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**: 无
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登出成功"
|
||
}
|
||
```
|
||
|
||
### 4. 获取当前用户信息
|
||
|
||
- **接口地址**: `GET /api/auth/user`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**: 无
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"nickname": "管理员",
|
||
"role": {
|
||
"id": 1,
|
||
"name": "管理员",
|
||
"code": "admin"
|
||
},
|
||
"tenantId": 1,
|
||
"userType": "tenant_admin"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 修改密码
|
||
|
||
- **接口地址**: `POST /api/auth/change-password`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| oldPassword | string | 是 | 原密码 |
|
||
| newPassword | string | 是 | 新密码（至少6位） |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "密码修改成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 公寓管理模块 (Apartments)
|
||
|
||
### 1. 获取公寓列表
|
||
|
||
- **接口地址**: `GET /api/apartments`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认10 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"name": "阳光公寓",
|
||
"address": "北京市朝阳区xxx街道",
|
||
"totalRooms": 20,
|
||
"occupiedRooms": 15,
|
||
"status": "active"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 创建公寓
|
||
|
||
- **接口地址**: `POST /api/apartments`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| name | string | 是 | 公寓名称 |
|
||
| address | string | 是 | 公寓地址 |
|
||
| description | string | 否 | 公寓描述 |
|
||
|
||
### 3. 更新公寓
|
||
|
||
- **接口地址**: `PUT /api/apartments/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除公寓
|
||
|
||
- **接口地址**: `DELETE /api/apartments/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 房间管理模块 (Rooms)
|
||
|
||
### 1. 获取房间列表
|
||
|
||
- **接口地址**: `GET /api/rooms`
|
||
- **是否需要认证**: 是
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| apartmentId | number | 否 | 公寓ID |
|
||
| status | string | 否 | 房间状态 |
|
||
|
||
### 2. 创建房间
|
||
|
||
- **接口地址**: `POST /api/rooms`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新房间
|
||
|
||
- **接口地址**: `PUT /api/rooms/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除房间
|
||
|
||
- **接口地址**: `DELETE /api/rooms/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 租户管理模块 (Tenants)
|
||
|
||
### 1. 获取租户列表
|
||
|
||
- **接口地址**: `GET /api/tenants`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建租户
|
||
|
||
- **接口地址**: `POST /api/tenants`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新租户
|
||
|
||
- **接口地址**: `PUT /api/tenants/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除租户
|
||
|
||
- **接口地址**: `DELETE /api/tenants/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 租房管理模块 (Rentals)
|
||
|
||
### 1. 获取租房记录列表
|
||
|
||
- **接口地址**: `GET /api/rentals`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建租房记录
|
||
|
||
- **接口地址**: `POST /api/rentals`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新租房记录
|
||
|
||
- **接口地址**: `PUT /api/rentals/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除租房记录
|
||
|
||
- **接口地址**: `DELETE /api/rentals/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 水电费管理模块
|
||
|
||
### 水费管理 (WaterBills)
|
||
|
||
#### 1. 获取水费记录列表
|
||
|
||
- **接口地址**: `GET /api/water-bills`
|
||
- **是否需要认证**: 是
|
||
|
||
#### 2. 创建水费记录
|
||
|
||
- **接口地址**: `POST /api/water-bills`
|
||
- **是否需要认证**: 是
|
||
|
||
### 电费管理 (ElectricityBills)
|
||
|
||
#### 1. 获取电费记录列表
|
||
|
||
- **接口地址**: `GET /api/electricity-bills`
|
||
- **是否需要认证**: 是
|
||
|
||
#### 2. 创建电费记录
|
||
|
||
- **接口地址**: `POST /api/electricity-bills`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 费用支出管理模块 (Expenses)
|
||
|
||
### 1. 获取费用支出列表
|
||
|
||
- **接口地址**: `GET /api/expenses`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建费用支出
|
||
|
||
- **接口地址**: `POST /api/expenses`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 统计分析模块 (Statistics)
|
||
|
||
### 1. 获取首页统计数据
|
||
|
||
- **接口地址**: `GET /api/statistics/dashboard`
|
||
- **是否需要认证**: 是
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"totalApartments": 5,
|
||
"totalRooms": 100,
|
||
"occupiedRooms": 80,
|
||
"vacantRooms": 20,
|
||
"monthlyIncome": 50000,
|
||
"monthlyExpenses": 15000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取收入统计
|
||
|
||
- **接口地址**: `GET /api/statistics/income`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 获取支出统计
|
||
|
||
- **接口地址**: `GET /api/statistics/expense`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 用户管理模块 (Users)
|
||
|
||
### 1. 获取用户列表
|
||
|
||
- **接口地址**: `GET /api/users`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建用户
|
||
|
||
- **接口地址**: `POST /api/users`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新用户
|
||
|
||
- **接口地址**: `PUT /api/users/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除用户
|
||
|
||
- **接口地址**: `DELETE /api/users/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 角色管理模块 (Roles)
|
||
|
||
### 1. 获取角色列表
|
||
|
||
- **接口地址**: `GET /api/roles`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建角色
|
||
|
||
- **接口地址**: `POST /api/roles`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新角色
|
||
|
||
- **接口地址**: `PUT /api/roles/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除角色
|
||
|
||
- **接口地址**: `DELETE /api/roles/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 菜单管理模块 (Menus)
|
||
|
||
### 1. 获取菜单列表
|
||
|
||
- **接口地址**: `GET /api/menus`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建菜单
|
||
|
||
- **接口地址**: `POST /api/menus`
|
||
- **是否需要认证**: 是
|
||
|
||
### 3. 更新菜单
|
||
|
||
- **接口地址**: `PUT /api/menus/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
### 4. 删除菜单
|
||
|
||
- **接口地址**: `DELETE /api/menus/:id`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 日志管理模块 (Logs)
|
||
|
||
### 1. 获取操作日志列表
|
||
|
||
- **接口地址**: `GET /api/logs`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 计费管理模块 (Billing)
|
||
|
||
### 1. 获取计费记录列表
|
||
|
||
- **接口地址**: `GET /api/billing`
|
||
- **是否需要认证**: 是
|
||
|
||
### 2. 创建计费记录
|
||
|
||
- **接口地址**: `POST /api/billing`
|
||
- **是否需要认证**: 是
|
||
|
||
---
|
||
|
||
## 请求头规范
|
||
|
||
### 公共请求头
|
||
|
||
| 请求头 | 必填 | 说明 |
|
||
|--------|------|------|
|
||
| Content-Type | 是 | 固定值 `application/json` |
|
||
| Authorization | 条件 | 认证接口需要，格式 `Bearer {token}` |
|
||
|
||
### 认证请求示例
|
||
|
||
```javascript
|
||
uni.request({
|
||
url: 'http://localhost:3000/api/apartments',
|
||
method: 'GET',
|
||
header: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...'
|
||
}
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理规范
|
||
|
||
### 统一错误响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "请求参数错误",
|
||
"error": "具体错误信息"
|
||
}
|
||
```
|
||
|
||
### 常见错误场景
|
||
|
||
| 场景 | 状态码 | 处理方式 |
|
||
|------|--------|----------|
|
||
| Token过期 | 401 | 跳转登录页重新登录 |
|
||
| 权限不足 | 403 | 提示用户无权限 |
|
||
| 参数错误 | 400 | 提示用户检查输入 |
|
||
| 服务器错误 | 500 | 提示用户稍后重试 |
|
||
|
||
---
|
||
|
||
## 版本记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v1.0.0 | 2025-04-07 | 初始版本，定义基础接口规范 |
|