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

10 KiB
Raw Blame History

RentEase API 接口文档

文档说明

本文档定义了 RentEase 租赁管理平台的统一 API 接口规范，用于前后端交互。

基础信息

服务器地址

环境 地址
开发环境 http://localhost:3000
生产环境 https://api.rentease.com

请求前缀

所有 API 请求都需要加上前缀 /api

响应格式

所有 API 响应统一返回以下格式：

{
  "code": 200,      // 状态码，200表示成功
  "message": "操作成功",  // 提示信息
  "data": {}        // 返回数据
}

状态码说明

状态码 说明
200 请求成功
400 请求参数错误
401 未授权，Token无效或过期
403 禁止访问，权限不足
404 资源不存在
500 服务器内部错误

认证模块 (Auth)

1. 用户登录

  • 接口地址: POST /api/auth/login
  • 是否需要认证: 否
  • 请求参数:
参数名 类型 必填 说明
username string 是 用户名/手机号
password string 是 密码
  • 响应示例:
{
  "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 是 管理员密码
  • 响应示例:
{
  "code": 200,
  "message": "注册成功，欢迎试用",
  "data": {
    "tenantId": 1,
    "name": "测试租户",
    "status": "active"
  }
}

3. 用户登出

  • 接口地址: POST /api/auth/logout
  • 是否需要认证: 是
  • 请求参数: 无
  • 响应示例:
{
  "code": 200,
  "message": "登出成功"
}

4. 获取当前用户信息

  • 接口地址: GET /api/auth/user
  • 是否需要认证: 是
  • 请求参数: 无
  • 响应示例:
{
  "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位）
  • 响应示例:
{
  "code": 200,
  "message": "密码修改成功"
}

公寓管理模块 (Apartments)

1. 获取公寓列表

  • 接口地址: GET /api/apartments
  • 是否需要认证: 是
  • 请求参数:
参数名 类型 必填 说明
page number 否 页码，默认1
pageSize number 否 每页数量，默认10
keyword string 否 搜索关键词
  • 响应示例:
{
  "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
  • 是否需要认证: 是
  • 响应示例:
{
  "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}

认证请求示例

uni.request({
  url: 'http://localhost:3000/api/apartments',
  method: 'GET',
  header: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...'
  }
})

错误处理规范

统一错误响应格式

{
  "code": 400,
  "message": "请求参数错误",
  "error": "具体错误信息"
}

常见错误场景

场景 状态码 处理方式
Token过期 401 跳转登录页重新登录
权限不足 403 提示用户无权限
参数错误 400 提示用户检查输入
服务器错误 500 提示用户稍后重试

版本记录

版本 日期 说明
v1.0.0 2025-04-07 初始版本，定义基础接口规范