wangxiaoxian
/
rentease-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rentease-app/docs/api-docs.md

553 lines
10 KiB
Markdown
Raw Permalink Normal View History

初始化
2026-04-20 06:23:11 +00:00
# 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 | 初始版本，定义基础接口规范 |