# carpool-service

**Repository Path**: shanch/carpool-service

## Basic Information

- **Project Name**: carpool-service
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-03-07
- **Last Updated**: 2022-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# carpool-service 拼车 - 后端
# 接口规范
> 所有接口以 /api 开头
>
> 管理员用的接口以 /api/admin 开头
>
> 如非特殊声明，接口均需要登录才能访问

<!-- more -->
## GET
> 一般无副作用的接口用 GET(如查询数据)

## POST
> 一般有副作用的接口用 POST(如修改密码)
>
> POST 接口使用 JSON 传递参数

## 参数/返回值
> 如无特殊说明，接口均使用 JSON 格式返回结果

1. 通用返回值结构

    ```jsonc
    {
        "success": true, // 是否成功
        "code":    0,    // 状态码，小于 0 为失败，大于等于 0 为成功
                         // 默认成功返回 0
                         // 默认失败返回 -1
                         // -2 为未登录
                         // -3 为网站关闭
                         // -4 为出现未处理的异常
                         // -5 为无权访问这个接口
                         // 负数可特殊处理下 -2 和 -3，其他统一提示失败
        "message": "",   // 有错误时这里传递错误消息
        "data":    ""    // 接口返回的数据，具体返回的数据以具体接口定义为准
    }
    ```
2. 带分页的查询
    1. 带分页的接口必须用`GET`请求
    2. GET 参数中的`page`为第几页`pageSize`为每页有多少条记录
    3. 如无特殊说明，`pageSize`不传默认为`10`
    4. 如无特殊说明，`pageSize`必须在`1 ~ 100`范围内，否则会被取范围中最接近的值
    5. 返回值的`data`结构

        ```js
        // 仅包含上面通用返回结构的 data 部分
        {
            "page":      1,  // 当前是第几页
            "totalRow":  96  // 总共有多少条记录
            "totalPage": 10, // 总共有几页
            "listData": [
                             // 当前页的具体记录
            ]
        }
        ```
    6. 导出模式
        * 首先，只有声明支持导出模式的请求才可用这个功能
        * 当`export`参数设置为`true`时，会禁用分页并将请求转为文件下载
        * 返回的数据会被转为`Excel`文件后下载
        * 可以通过设置`pager`参数为`true`继续启用分页功能

# 公共信息


## 文件
* id 文件的 ID
* filename 文件上传时文件的原始名称(如果要展示请注意预防 XSS)
* addtime 文件的上传时间
* size 文件的大小(字节)


> 提交预约信息后，管理员确认任务完成前，均可选`上传排队小票`
>
> 确认后，完成或失败前，均可`上传补充信息`

## 批量导入 Excel 文件格式
> Excel 中可以有任意多的`Sheet`，但不符合下面的格式的`Sheet`会被直接忽略

| 序号 | 客户名 | 电话 | ... |
| ---- | ------ | ---- | --- |
| 1 | 小明 | 13333333333 | ... |
| 2 | 小白 | 13333333334 | ... |
| 3 | 小红 | 13333333335 | ... |
| ... | ... | ... | ... |

# 接口
执行`apidoc -i src/ -o doc/`后打开`doc/index.html`查看

首次使用时你可能需要执行`npm i -g apidoc`