xiaoli/peixue-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
58df75a39f
peixue-dev/Archive/peidu-temp-files/docs/[一次性]家长端打卡功能-API文档-2026-01-26.md

9.2 KiB
Raw Blame History

📡 家长端打卡功能 - API接口文档

日期： 2026-01-26
版本： v1.0

📋 接口列表

接口名称 请求方法 接口路径 说明
获取打卡记录列表 GET /api/checkin/user/records 获取用户的打卡记录列表
获取打卡统计数据 GET /api/checkin/user/statistics 获取用户的打卡统计信息

1️⃣ 获取打卡记录列表

基本信息

  • 接口路径： /api/checkin/user/records
  • 请求方法： GET
  • 接口说明： 获取指定用户的打卡记录列表，支持分页和日期筛选

请求参数

参数名 类型 必填 默认值 说明
userId Long 是 - 用户ID
page Integer 否 1 页码
size Integer 否 10 每页数量
date String 否 - 筛选日期（格式：2026-01-26）

请求示例

# 获取第1页数据
GET /api/checkin/user/records?userId=1&page=1&size=10

# 按日期筛选
GET /api/checkin/user/records?userId=1&date=2026-01-26

响应参数

参数名 类型 说明
code Integer 响应码（200=成功）
message String 响应消息
data Object 响应数据
data.records Array 打卡记录列表
data.total Long 总记录数
data.page Integer 当前页码
data.size Integer 每页数量

打卡记录对象（Record）

参数名 类型 说明
id Long 记录ID
userId Long 用户ID
teacherId Long 陪伴员ID
teacherName String 陪伴员姓名
orderId Long 订单ID
serviceName String 服务名称
checkType String 打卡类型（in=签到, out=签退）
checkTime String 打卡时间
checkInTime String 签到时间
checkOutTime String 签退时间
address String 打卡地点
checkInAddress String 签到地点
checkOutAddress String 签退地点
photoUrl String 打卡照片URL
checkInPhoto String 签到照片URL
checkOutPhoto String 签退照片URL
latitude Double 纬度
longitude Double 经度
duration String 服务时长（如：2小时0分钟）
remark String 备注
createTime String 创建时间

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "teacherId": 10,
        "teacherName": "张老师",
        "orderId": 123,
        "serviceName": "陪伴服务",
        "checkType": "in",
        "checkTime": "2026-01-26 09:00:00",
        "checkInTime": "2026-01-26 09:00:00",
        "checkOutTime": "2026-01-26 11:00:00",
        "address": "北京市朝阳区xxx小区",
        "checkInAddress": "北京市朝阳区xxx小区",
        "checkOutAddress": "北京市朝阳区xxx小区",
        "photoUrl": "http://example.com/photo1.jpg",
        "checkInPhoto": "http://example.com/checkin.jpg",
        "checkOutPhoto": "http://example.com/checkout.jpg",
        "latitude": 39.9042,
        "longitude": 116.4074,
        "duration": "2小时0分钟",
        "remark": "服务顺利完成",
        "createTime": "2026-01-26 09:00:00"
      },
      {
        "id": 2,
        "userId": 1,
        "teacherId": 11,
        "teacherName": "李老师",
        "orderId": 124,
        "serviceName": "陪伴服务",
        "checkType": "in",
        "checkTime": "2026-01-25 14:00:00",
        "checkInTime": "2026-01-25 14:00:00",
        "checkOutTime": "2026-01-25 16:30:00",
        "address": "北京市海淀区yyy小区",
        "checkInAddress": "北京市海淀区yyy小区",
        "checkOutAddress": "北京市海淀区yyy小区",
        "photoUrl": "http://example.com/photo2.jpg",
        "checkInPhoto": "http://example.com/checkin2.jpg",
        "checkOutPhoto": "http://example.com/checkout2.jpg",
        "latitude": 39.9889,
        "longitude": 116.3147,
        "duration": "2小时30分钟",
        "remark": "",
        "createTime": "2026-01-25 14:00:00"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10
  }
}

错误响应

{
  "code": 400,
  "message": "用户ID不能为空",
  "data": null
}

{
  "code": 500,
  "message": "获取失败: 数据库连接异常",
  "data": null
}

2️⃣ 获取打卡统计数据

基本信息

  • 接口路径： /api/checkin/user/statistics
  • 请求方法： GET
  • 接口说明： 获取指定用户的打卡统计信息

请求参数

参数名 类型 必填 默认值 说明
userId Long 是 - 用户ID

请求示例

GET /api/checkin/user/statistics?userId=1

响应参数

参数名 类型 说明
code Integer 响应码（200=成功）
message String 响应消息
data Object 统计数据
data.totalRecords Long 总服务次数
data.thisMonth Long 本月服务次数
data.totalHours Integer 累计时长（小时）

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "totalRecords": 50,
    "thisMonth": 10,
    "totalHours": 0
  }
}

错误响应

{
  "code": 400,
  "message": "用户ID不能为空",
  "data": null
}

{
  "code": 500,
  "message": "获取失败: 数据库查询异常",
  "data": null
}

🔧 前端调用示例

使用封装的API方法

import api from '@/api/index.js'

// 获取打卡记录列表
async function loadRecords() {
  try {
    const params = {
      userId: 1,
      page: 1,
      size: 10,
      date: '2026-01-26' // 可选
    }
    
    const res = await api.checkInApi.getUserCheckRecords(params)
    
    if (res && res.code === 200 && res.data) {
      const records = res.data.records || []
      console.log('打卡记录:', records)
      return records
    }
  } catch (error) {
    console.error('加载失败:', error)
    uni.showToast({ title: '加载失败', icon: 'none' })
  }
}

// 获取统计数据
async function loadStatistics() {
  try {
    const params = { userId: 1 }
    const res = await api.checkInApi.getStatistics(params)
    
    if (res && res.code === 200 && res.data) {
      const stats = res.data
      console.log('统计数据:', stats)
      return stats
    }
  } catch (error) {
    console.error('加载统计失败:', error)
  }
}

直接使用request

import request from '@/utils/request.js'

// 获取打卡记录列表
const records = await request.get('/api/checkin/user/records', {
  userId: 1,
  page: 1,
  size: 10
})

// 获取统计数据
const statistics = await request.get('/api/checkin/user/statistics', {
  userId: 1
})

🧪 测试用例

测试用例1：正常获取记录列表

请求：

GET /api/checkin/user/records?userId=1&page=1&size=10

预期响应：

  • 状态码：200
  • 返回记录列表
  • 包含分页信息

测试用例2：按日期筛选

请求：

GET /api/checkin/user/records?userId=1&date=2026-01-26

预期响应：

  • 状态码：200
  • 只返回指定日期的记录

测试用例3：获取统计数据

请求：

GET /api/checkin/user/statistics?userId=1

预期响应：

  • 状态码：200
  • 返回统计数据对象

测试用例4：缺少必填参数

请求：

GET /api/checkin/user/records

预期响应：

  • 状态码：400
  • 错误消息："用户ID不能为空"

📊 数据库表结构

check_in_record 表

字段名 类型 说明
id BIGINT 主键ID
user_id BIGINT 用户ID
teacher_id BIGINT 陪伴员ID
order_id BIGINT 订单ID
check_type VARCHAR(20) 打卡类型（in/out）
check_time DATETIME 打卡时间
address VARCHAR(255) 打卡地点
latitude DECIMAL(10,6) 纬度
longitude DECIMAL(10,6) 经度
photo_url VARCHAR(500) 照片URL
remark VARCHAR(500) 备注
tenant_id BIGINT 租户ID
create_time DATETIME 创建时间
update_time DATETIME 更新时间

🔐 权限说明

访问权限

  • 需要用户登录
  • 只能查询自己的打卡记录
  • 管理师可以查询所有用户的记录

数据权限

  • 家长只能看到自己订单的打卡记录
  • 陪伴员可以看到自己的打卡记录
  • 管理师可以看到所有打卡记录

📝 注意事项

  1. userId参数必填

    • 前端需要从用户信息中获取userId
    • 建议使用 uni.getStorageSync('userInfo') 获取

  2. 日期格式

    • 日期参数格式：YYYY-MM-DD
    • 示例：2026-01-26

  3. 分页参数

    • page从1开始
    • size建议设置为10或20

  4. 照片URL

    • 照片URL可能为空
    • 需要判断是否存在再显示

  5. 服务时长

    • 只有签到和签退都存在时才有时长
    • 格式：X小时Y分钟

🔄 版本历史

版本 日期 说明
v1.0 2026-01-26 初始版本，实现基础功能

📞 联系方式

如有问题，请联系开发团队。