# 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 | 初始版本，定义基础接口规范 |