回来1.0 协议文档

1、项目约定

1.1 基本约定

1.1.1 API Base Url

• 【线上url】待定
• 【测试url】待定

1.1.2 鉴权字段(身份标识)

• token : [string] 登录后获取的 token 信息
  ：时效为1年，过期提示“请重新登录”，弹出登录页面

1.1.3 HTTP请求中字段要求

• 待定

1.2 通用接口

1.2.1 上传图片

通用图片上传文件服务

请求URL

POST
/upload

请求参数

• file : 文件

响应

{
    error_code: 0,
    data: {
        url: 'http://xxx'
    }
}

• url : [string] 文件的访问URL

1.2.2 验证码图片

注：请求图片时，需解析图片的cookie，不然无法认证

• 【线上APP】待定
• 【测试APP】待定

1.3 通用响应字段

1.3.1 状态字段

• error_code: [int] 服务器状态码，0 为正常状态，异常状态待定。
• error_message：[string] 错误信息，但 error_code 不为 0 时返回

1.3.2 数据字段

• data: [object] 数据字段，所有响应数据都在此字段中
• list: [array]，当返回数据为列表时会将数据放在该字段

1.3.3 分页字段

• page: [object] 分页信息，当返回数组数据时会携带该字段
  
  • current: [int] 当前页码，默认为1
  • total: [int] 总页数
  • size: [int] 每页数量：本项目常用pageSize==10

示例

{
    error_code: 0,
    data: {
        key: value,
        list: [{
            key: value
        }],
        page {
        }
    }
}

2、数据结构

2.1 常用字段含义

2.1.1 推送和广告跳转方式

jump_mode: [int]

0:不跳转
1:跳转到link链接

2.1.2 性别字段

sex:[int]

0: 未知
1: 男
2: 女

2.1.3 是否认证字段

is_check:[int]

0: 未认证
1: 认证

2.1.4 举报类型码表

question_id:[int]

1: 私车私用
2: 车牌缺失
3: 车胎坏了
4: 车锁坏了
5: 违规乱停
6: 密码不对
7: 刹车坏了
8: 其他

2.1.5 报修类型码表

problem_id:[int]

1: 刹车失灵
2: 车胎没气
3: 掉链子
4: 车把损坏
5: 锁坏了
6: 车座坏了
7: 上私锁
8: 踏板坏了
9: 密码不对

2.2 核心结构

2.2.1 用户信息

{
    id: 123,
    user_name: '小胖墩',
    phone: '15500000000',
    icon: 'http://img1.imgtn.bdimg.com/it/u=3904886406,695848811&fm=11&gp=0.jpg',
    deposit:199.00,
    amount:133.75,
    sex:0,
    brithday:'1999-10-10',
    invite_code:'15500000000',
    is_check:0,
    token:'aaaaaaa'
}

• id: [int] 用户ID
• user_name: [string] 用户名，为空时表示未设置
• phone: [string] 用户手机
• icon: [url] 头像
• deposit: [float] 押金，为0时，表示没有押金
• amount: [float] 用户资金
• sex: [int] 性别，含义参见2.1
• brithday: [date] 用户生日
• invite_code: [string] 邀请码
• is_check: [int] 是否认证， 含义参见2.1
• token: [string] token,用户登录态，仅登陆接口下发

2.2.2 单车信息

{
    id: 1,
    code: '89757',
    pwd: '4457',
    lat: 34.198475
    lng: 114.12233,
    position: '北京市东城区天安门广场',
}

• id: [int] 单车ID
• code: [string] 单车编号
• pwd: [string] 单车密码，【仅在单车信息结构下发】
• lat: [float] 维度 【仅在单车信息结构下发，不确保下发正确】
• lng: [float] 经度【仅在单车信息结构下发，不确保下发正确】
• position: [string] 单车地点 【不确保是否下发，且仅在单车信息结构下发】

2.2.3 行程信息

{
    id: 1,
    bike_info:@单车信息,
    begin_time: '2017-02-01 13:23:12',
    end_time: '2017-02-01 13:29:12',
    ride_time: 360,
    ride_long: 3650,
    travel_way: '格式待定',
    amount: 3.00,
    real_amount: 1.00,
    discount_amount: 2.00,
    discount_reason: '优惠券减免'
}

• id: [int] 单车ID
• bike_info: @单车信息
• begin_time: [datetime] 行程开始时间
• end_time: [datetime] 行程结束时间
• ride_time: [int] 累计骑行时间，单位秒
• ride_long: [int] 累计骑行距离，单位米
• travel_way: [string] 骑行路线，polyline，格式待定，取决于sdk获取的值
• amount: [float] 行程费用
• real_amount: [float] 实缴费用
• discount_amount: [float] 减免费用
• discount_reason: [string] 减免原因

2.2.4 交易明细

{
    id: 1,
    amout_show: 100.00,
    amout_real: 0.00,
    created_at: '2017-02-27 12:12:12',
    remark: '行程消费'
}

• id: [int] 交易ID
• amout_show: [float] 展示支付金额
• amout_real: [float] 实际支付金额，大部分情况与amout_show相同；在充100送100的情况下，送100的实际支付金额为0
• created_at: [datetime] 消费时间
• remark: [string] 消费title

2.2.5 广告

{
    id:1
    img: 'https://ss0.bdstatic.com/70cFuHSh_Q1YnxGkpoWK1HF6hhy/it/u=1722966551,3293303547&fm=116&gp=0.jpg',
    jump_mode:1,
}

• id: [int] id
• img: [url] 广告图
• jump_mode: [int] 跳转方式

2.2.6 优惠券

{
    id:1
    coupon_name: '2元优惠券',
    is_used: 1,
    used_time: '2017-02-22 13:22:35',
    expire_time: '2017-02-23 13:22:35',
    payment_amount: 1.00,
    payment_time: '2017-02-22 13:22:35',
    remark:'备注',
}

• id: [int] id
• coupon_name: [string] 优惠券名称
• is_used: [int] 是否使用 0未使用 1使用
• used_time: [datetime] 使用时间
• expire_time: [datetime] 过期时间
• payment_amount: [float] 兑付金额
• payment_time: [datetime] 兑付时间
• remark: [string] 备注

3、接口列表

3.1 用户信息接口

3.1.1 登陆接口

请求URL

POST
/login

请求参数

• phone: 手机号【必填】
• verify_code: 验证码【必填】
• device_id: 设备 ID【必填】

响应

{
    "error_code": 0,
    "data":{
        @用户信息
    },
    "error_message": ""
}

注：token为用户标识，其它请求需带上

3.1.2 登出接口

请求URL

POST
/logout

请求参数

• token: token【必填】
• device_id: 设备 ID【必填】

响应

{
    "error_code": 0,
    "data":{
    },
    "error_message": ""
}

3.1.3 用户信息接口

请求URL

POST
/user/info

请求参数

• token: token【必填】

{
    "error_code": 0,
    "data":{
        @用户信息
    },
    "error_message": ""
}

3.1.4 修改个人信息接口

请求URL

POST
/user/update

请求参数

• token: token【必填】
• user_name: 用户名【非必填】
• icon: 头像【非必填】
• sex: 性别【非必填】
• brithday: 生日【非必填】

响应

{
    "error_code": 0,
    "data":{
        @用户信息
    },
    "error_message": ""
}

注：用户修改哪个字段，传哪个字段；如没有修改该字段，请不要传此字段，否则会覆盖原来的值

3.2 行程相关

3.2.1 我的行程列表接口

请求URL

POST
/travel/list

请求参数

• current_page: 页码【必填】
• page_size: 页长【必填】
• token: token【必填】

响应

{
    "error_code": 0,
    "data":{
        "list":{
            @行程信息  
        },
        "page":{
            @分页字段
        }
    },
    "error_message": ""
}

3.2.2 行程信息接口

请求URL

POST
/travel/info

请求参数

• token: token【必填】
• travel_id: 行程id【必填】

响应

{
    "error_code": 0,
    "data":{
        @行程信息
    },
    "error_message": ""
}

3.2.3 开始行程（用车）接口

请求URL

POST
/travel/begin

请求参数

• token: token【必填】
• code: 单车编号【必填】

响应

{
    "error_code": 0,
    "data":{
        @行程信息
    },
    "error_message": ""
}

3.2.4 结束行程（用车）接口

请求URL

POST
/travel/done

请求参数

• token: token【必填】
• travel_id: 行程id【必填】
• ride_long: 行程距离【必填】
• travel_way: 行程路径【必填】

响应

{
    "error_code": 0,
    "data":{
        @行程信息
    },
    "error_message": ""
}

我的优惠券列表
/coupon/list

消费明细列表
/consume/list

充值明细列表
/recharge/list

充值接口
/recharge/do

交押金接口
/deposit/do

提押金接口
/deposit/out

举报接口
/question/report

报修接口
/problem/report

广告信息接口
/ad/list

4、native与H5通信

5、其它

6、项目讨论问题

问题

TEMP
单点登录
Q：充值规则
A：充值金额不退还

Q：计费规则
A：1分钟以内不用计费， 计费还是1元/半小时

初始化车辆问题
后台设置假车辆数据问题

活动需细化，送东西都是虚拟的么？旅游券怎么用？
Q：优惠券的种类
A：用车券就5元 3元 2元 这三种

Q：邀请好友，好友注册后如何发放用车券
A：邀请好友发532 各一张，总供10元

Q：分享行程用车券发放
A：行程分享在分享页面领取2元用车券，前五名可领取，之后的提示已抢光，不显示领取的数量

Q：用户是否有分类，ofo有普通用户和师生用户
A：用户不分类型

Q：车辆没有类型？
A：车辆没有类型

7、TODO

7.1 甲方事项

• 阿里云账号注册、充值1.2w（1年的服务），我们当天购买
• 域名购买和ICP备案
• 短信平台：云通讯平台，注册和充值（1000元）
• 苹果普通开发者和企业开发者注册+购买（99美金+299美金）（这里需要用公司材料注册）
• 微信支付和支付宝账号（公司材料）注册，移动支付能力申请
• 微博开发者平台注册、微信开发者平台注册、支付宝开发者平台注册
• 百度账号注册，用于申请百度地图相关sdk
• 友盟账号注册，用户分享sdk，push，统计等申请
• 邮寄一台单车用户调试地址：北京市昌平区回龙观东大街紫金新干线18号楼3单元801 李娜 13811849645

7.2 设计事项

• logo定稿，风格定稿
• 页面设计和切图标注
• 广告图、启动图等页面设计

7.3 后端开发

• 服务器环境配置，含测试环境
• 数据库基本设计
• 完成接口文档
• 完成假接口的支持
• 接口开发、后台功能开发

7.4 app开发