考勤模块接口设计文档

开发设计

• 检测合作商是否开启考勤任务

接口名：pd.attendance.preference
接口描述：检测合作商是否开启考勤任务，本期默认所有合作商都是开启考勤任务，后端写死即可。
参数：
    0. sessionId    // 必填
返回：
{
    "success": true,
    "msgCode": null,
    "msgInfo": null,
    "count": 0,
    "model": true 
}

• 查询某月考勤记录

接口名：pd.attendance.month
接口描述：查询某月考勤记录，此处返回的数据足够客户端生成日历。点击日历上的某一天的具体考勤记录，需再次请求“某日的考勤记录”接口。
参数：
    0. sessionId    // 必填
    1. year         // 年
    2. month        // 月
返回：
{
    "success": true,
    "msgCode": null,
    "msgInfo": null,
    "count": 0,
    "model": {
        "year": 2016,
        "month": 11,
        "records": [
            {
                "day": 1,               //日期，此处指的是11月1日
                "isExceptionStatus": 1, //是否异常状态
                "signInCount": 0        //签到次数
            },
            {
                "day": 2,
                "isExceptionStatus": 1,
                "signInCount": 2
            },
            {
                "day": 3,
                "isExceptionStatus": 0,
                "signInCount": 2
            },
            {
                "day": 4,
                "isExceptionStatus": 0,
                "signInCount": 0
            }
        ]
    }
}

• 查询某天的考勤记录

接口名：pd.attendance.day
接口描述：查询某天的考勤记录，返回该天的详细记录。若给定的【日期】是未来的时间，则给出相应的错误提示。
输入：
    0. year     // 年
    1. month    // 月
    2. day      // 日
输出：
{
    "success": true,
    "msgCode": null,
    "msgInfo": null,
    "count": 0,
    "model": {
        "date": "2016年11月29日",// 2016-12-12 新增
        "description": "出勤 10:00-18:00",// 2016-12-12 新增
        "year": 2016,
        "month": 11,
        "records": [
            {
                    "type":0,// 2016-12-12 新增
                    "title": "上班签到",
                    "status": 2,
                    "tag": "旷工",
                    "time": "14: 12",
                    "address": "杭州市余杭区文一西路998号",
                    "remark": "事由：忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了。"// 异常状态，必有remark
                },{
                    "type":1,// 2016-12-12 新增
                    "title": "下班签退",
                    "status": 2,
                    "tag": "正常",
                    "time": "18: 12",
                    "address": "杭州市余杭区文一西路998号",
                    "remark":null // 正常签到，必没有remark
                }
        ]
    }
}

• 获取当日的考勤上下文，与接口pd.attendance.day部分相似

接口名：pd.attendance.context
接口描述：仅限于获取当日的考勤上下文，注意与接口`pd.attendance.day`加以区分。
参数：
    0. sessionId        //登录后的sessionId凭据【必填】
返回：
    * 若未设置考勤，异常提示“您未有考勤任务”。
    {
        "success": false,
        "msgCode": 1024,
        "msgInfo": "您未有考勤任务",
        "count": 0,
        "model": null
    }
    * 若已设置考勤，但是检查还未到生效日期，则显示“已开启考勤，于2016/11/14日开始生效。”
    {
        "success": false,
        "msgCode": 1025,
        "msgInfo": "已开启考勤，于2016/11/14日开始生效",
        "count": 0,
        "model": null
    }
    * 若已设置考勤，且已经在生效日期范围内，则显示正确的考勤任务数据。
    {
        "success": true,
        "msgCode": null,
        "msgInfo": null,
        "count": 0,
        "model": {
            "date": "2016年11月29日",
            "description": "出勤 10:00-18:00",
            "records": [
                {
                    "type":0,// 2016-12-12 新增
                    "title": "上班签到",
                    "status": 2,
                    "tag": "旷工",
                    "time": "14: 12",
                    "address": "杭州市余杭区文一西路998号",
                    "remark": "事由：忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了今天要上班了，忘了。"
                }
            ]
        }
    }

• 申请签卡（包括签到、签退）

接口名：pd.attendance.apply
接口描述：申请打卡
参数：
   0. sessionId     //  【必填】
   1. type            //  0签到 1签退
   2. longitude     //  经度，若APP实在无法定位则会传-1 兼容无法定位的情况【必填】
   3. latitude      //  纬度，若APP实在无法定位则会传-1 兼容无法定位的情况【必填】
   4. device_mac    //  打卡设备mac地址【选填】
   5. content       // 补充说明。{当出现异常打卡（经纬度未获得，距离范围之外，早退、迟到、旷工）时，必填}
返回：
{
    "success": true,
    "msgCode": null,
    "msgInfo": null,
    "count": 0,
    "model": true
}

• 使用当下的经纬度查询签卡状态（注意：只查询状态不执行签卡）
  
  • 先判断当前经纬度是否超出距离范围（范围内、范围外）
  • 再判断打卡时间是否异常（早退、迟到、旷工）

接口名：pd.attendance.status
接口描述：获取打卡状态
参数：
    0. sessionId        //  登录后的sessionId凭据【必填】
    2. type             //  0签到 1签退
    3. longitude        //  经度，若APP实在无法定位则会传-1 兼容无法定位的情况【必填】
    4. latitude         //  纬度，若APP实在无法定位则会传-1 兼容无法定位的情况【必填】
返回：
{
    "success": true,
    "msgCode": null,
    "msgInfo": null,
    "count": 0,
        "model": {
        "type":0,                        // 2016-12-12 新增
        "distance": 300,                // 实际距离
        "date": "2016年11月14日 14:20"   // 实际打卡时间（服务器上的北京时间）
        "status":0                      // 0 正常状态
                                        // 1 异常状态，迟到
                                        // 2 异常状态，旷工
                                        // 3 异常状态，早退
    }
}