接力助学 - 通信协议

接力助学

1. 协议说明

1.1 请求包格式

协议的请求包分为两种：RESTFul 和非 RESTFul。
RESTFul 接口使用以下四种动词实现数据的基本操作。

注意：下面的所有 URL 地址都省略了 HOST 字段，在 jlzx 项目中，客户端通过下面的域名访问数据：

http://jl-fe.bl99w.com

1.1.1 RESTFul API

查询：GET

访问路径是目标对象名字的单数形式。例如，要查询用户创建的收货地址，路径是：

/address

创建：POST

访问路径是目标对象名字的复数形式：

/addresses

删除：DELETE

访问路径是要删除对象名字的复数形式，再加上对象 Id：

/addresses/1

修改：PATCH

要修改对象名字的复数形式，再加上对象 Id：

/addresses/1

1.1.2 非 RESTFul API

非 RESTFul 接口只有跟用户注册、登录相关的，包括：

1. 注册：/signup
2. 登录：/login
3. 发送短信验证码：/sms-send

请在具体协议中查看对应的格式。

1.2 反馈包格式

1. 所有接口反馈包都是 JSON 格式；
2. 反馈包的基本信息如下：

基本格式为：

{
    "status": 0,
    "msg": "登录成功",
    "object": {
    },
    "items": [
        {
        },
    ],
}

1.2.1 返回对象

对于登录、注册接口，以及 RESTFul API 中的添加（POST）、修改（PATCH）接口，由于都是对单个对象做操作，所以在执行完毕后，会将相关对象信息放在 额外的 object 字段中，返回，如：

"object": {
    "id": 15,
    "username": "18037963805",
    "password": null,
    "revenueEarned": 0,
    "revenueLeft": 0,
    "balance": 0,
    "kactivityId": 0,
    "grade": 0,
    "created_at": 1477993502,
    "updated_at": 1477993502,
    "createdAt": "2016-11-01 17:45:02",
    "updatedAt": "2016-11-01 17:45:02"
}

1.2.2 返回数组

对于查询（GET）接口，会返回一个 额外的 items 字段，它是一个数组，包含查询到的数据，如：

"items": [
    {
        "id": 8,
        "serialNumber": "155818646317310",
        "kuserId": 15,
        "packageId": 1,
        "addressId": 0,
        "logisticCompany": null,
        "logisticNumber": null,
        "payMode": 0,
        "status": 0,
        "createdAt": "2016-11-01 17:46:11",
        "updatedAt": "2016-11-01 17:46:11"
    }
]

1.2.3 返回错误

当错误发生时，一般会将错误的编码（整型）和错误提示信息一起返回：

{
    "status": -10,
    "msg": "已经购买过该套餐"
}

上面的错误发生在重复购买同一套餐时。

1.3 认证方式

• 客户端调用 /login 接口进行登录；
• 登录成功后，反馈包的 object 中会包含 access_token 字段；
• 客户端对 access_token 进行运算与拼接 ，得到 认证字符串；
  
  • 认证字符串 的计算方法请参考 这里。
• 后续访问 RESTFul 接口时，需要在 HTTP Headers 中设置两个属性：
  
  • Accept: application/json
  • Authorization: 认证字符串
• 服务器会根据传过来的 认证字符串 自动认证用户身份。

1.4 名词解释

1.4.1 用户等级（grade）

• 0：未参加活动普通用户
• 1：爱心专员
• 2：爱心使者
• 3：爱心大使

2. 非 RESTFul API

2.1 注册 signup

请求：

• 类型：POST
• URL： /signup
• 参数：
  
  • username：手机号
  • password：密码
  • code：短信验证码
  • sharer：推荐人手机号（可选）

反馈：

{
    "status": 0,
    "msg": "操作成功",
    "object": {
        "id": 78
        "username": "liuwanwei",
        "status": 10,
        "access_token" : "rSOiVXEf4wb8oLk5BBXxy2BjZjKIJIkK",
        "createdAt": "2016-11-01 17:45:02",
        "updatedAt": "2016-11-01 17:45:02"
    }
}

注意：
用户信息中的时间跟别处不同，是个 time_t 类型，使用时请注意。这是因为“不可抗力”造成的：由于使用了 yii2-admin，它在处理用户登录时，提供提供的表结构中就使用了 time_t 类型。

2.2 登录 /login

请求：

• 类型：POST
• URL：/login
• 参数：
  
  • username：手机号
  • password：密码

反馈：

{
    "status": 0,
    "msg": "操作成功",
    "object": {
        "id": 15,
        "username": "18037963805",
        "password": null,
        "revenueEarned": 0,
        "revenueLeft": 0,
        "balance": 0,
        "kactivityId": 0,
        "grade": 0,         // 用户等级
        "access_token": "15h55D9ZzF6T1UGQqZX9xJtaNsW1r53kn-",
        "createdAt": "2016-11-01 17:45:02",
        "updatedAt": "2016-11-01 17:45:02"
    }
} 

2.3 发送短信 /sms-send

请求：

• 类型：POST
• 参数：
  
  • mobile：短信发送目标手机号

反馈：

{
    "status": 0,
    "msg": "操作成功"
}

2.4 修改密码 /change-password

请求：

• 类型：POST
• 参数：
  
  • accessToken: 登录后返回的 access_token
  • oldPassword：旧密码
  • newPassword：新密码

反馈：

{
    "status": 0,
    "msg": "操作成功"
}

2.5 找回密码 /reset-password

请求：

• 类型：POST
• 参数：
  
  • mobile：手机号
  • code：短信验证码
  • password：新密码

反馈：

{
    "status": 0,
    "msg": "操作成功"
}

2.6 查询当前用户信息 /user-info

请求：

• 类型：POST
• 参数：
  
  • accessToken: 用户登录后返回的 access_token 字段

反馈：

跟登录接口反馈信息格式保持一致。

2.7 批量报单结束通知 / site/batch-report-done

• 类型：POST
• 参数：
  
  • mobile：批量报单时，最后一单用户手机号

服务器会检查这个手机号是否最近通过批量报单方式报单，检查失败时，会返回参数错误信息。

反馈：

{
    "status": 0,
    "msg": "操作成功"
}

3. RESTFul API

3.1 订单相关

3.1.1 查询：/korder

请求：

• 类型：GET
• 参数：无

反馈：

{
    "status": 0,
    "msg": "操作成功",
    "items": [
        {
            "id": 9,
            "serialNumber": "155819A4B159408",
            "kuserId": 15,
            "packageId": 1,
            "kpackage":{
                "id": 1,
                "name": "家庭洗护套装",
                "content": "美白、洗护、三合一",
                "price": 520,
                "coverUrl": "http://1.upaiyun.com/0.jpg",
                "kactivityId": 1,
                "count": 1000,
                "type": 0,
                "weight": 2,
                "recommended": 1,
                "operatorId": 6,
                "createdAt": "2016-11-01 15:58:09",
                "updatedAt": "2016-11-03 17:35:50",
                "deleted": 0
            },
            "addressId": 0,
            "address":{
                "id": 3,
                "kuserId": 15,
                "name": "谢烟客",
                "mobile": "18037963805",
                "address": "金城美邻 2 号楼 1801",
                "inUse": 0,
                "createdAt": "2016-11-02 11:47:09",
                "updatedAt": "2016-11-02 11:47:09",
                "deleted": 0
            },
            "logisticCompany": null,
            "logisticNumber": null,
            "payMode": 0,
            "status": 0,
            "createdAt": "2016-11-02 16:32:49",
            "updatedAt": "2016-11-02 16:32:49"
        }
    ]
}

3.1.2 添加：/korders

请求：

• 类型：POST
• 参数：
  
  • packageId：套餐 Id
  • addressId：收货地址 Id
  • payMode：支付方式，1：支付宝，2：微信
• 备注：参数都是必填项

反馈：

{
    "status": 0,
    "msg": "成功",
    "object": {
        "id": 9,
        "serialNumber": "155819A4B159408",
        "kuserId": 15,
        "packageId": 1,
        "addressId": 0,
        "logisticCompany": null,
        "logisticNumber": null,
        "tokenId":"1234565421789",
        "payMode": 0,
        "status": 0,
        "createdAt": "2016-11-02 16:32:49",
        "updatedAt": "2016-11-02 16:32:49"
   }
}

3.1.3 修改：/korders/{{korderId}}

请求：

• 类型：PATCH
• 参数：
  
  • status：订单状态，2：确认收货

反馈：

{
    "status": 0,
    "msg": "成功",
    "object": {
        "id": 9,
        "serialNumber": "155819A4B159408",
        "kuserId": 15,
        "packageId": 1,
        "addressId": 0,
        "logisticCompany": null,
        "logisticNumber": null,
        "payMode": 0,
        "status": 0,
        "createdAt": "2016-11-02 16:32:49",
        "updatedAt": "2016-11-02 16:32:49"
   }
}

3.1.4 删除：/korders/{{korderId}}

请求：

• 类型：DELETE
• 参数：无

反馈：

{
    "status": 0,
    "msg": "操作成功"
}

3.2 收货地址相关

3.2.1 查询：/address

请求：

• 类型：GET
• 参数：无

反馈：

{
    "status": 0,
    "msg": "操作成功",
    "items": [
        {
            "id": 3,
            "kuserId": 15,
            "name": "谢烟客",
            "mobile": "18037963805",
            "address": "西工区王城大道，金城美邻 2 号楼 1801",
            "inUse": 0,
            "createdAt": "2016-11-02 11:47:09",
            "updatedAt": "2016-11-02 11:47:09",
            "deleted": 0
        }
    ]
}

3.2.2 添加：/addresses

请求：

• 类型：POST
• 参数：
  
  • name：收件人姓名
  • mobile：收件人联系电话
  • address：收件人地址
  • inUse：是否设置为默认，0：否，1：是
• 备注：
  
  • inUse 参数为可选项，不填时，不设置为默认地址
  • 其余参数都是必填项

反馈：

{
    "status": 0,
    "msg": "成功",
    "object": {
        "id": 4,
        "kuserId": 15,
        "name": "谢烟客",
        "mobile": "18037963805",
        "address": "西工区王城大道，金城美邻 2 号楼 1801",
        "inUse": 0,
        "createdAt": "2016-11-02 16:57:18",
        "updatedAt": "2016-11-02 16:57:18",
        "deleted": 0
    }
}

3.2.3 修改：/addresses/{{addressId}}

请求：

• 类型：PATCH
• 参数：
  
  • name：收件人姓名
  • mobile：收件人联系电话
  • address：收件人地址
  • inUse：是否设置为默认，0：否，1：是

反馈：

{
    "status": 0,
    "msg": "成功",
    "object": {
        "id": 4,
        "kuserId": 15,
        "name": "谢烟客",
        "mobile": "18037963805",
        "address": "西工区王城大道，金城美邻 2 号楼 1801",
        "inUse": 0,
        "createdAt": "2016-11-02 16:57:18",
        "updatedAt": "2016-11-02 16:57:18",
        "deleted": 0
    }
}

3.2.4 删除：/addresses/{{addressId}}

请求：

• 类型：DELETE
• 参数：无

反馈：

{
    "status": 0,
    "msg": "操作成功"
}