peixue-dev/Archive/peidu-temp-files/docs/[一次性]家长端打卡功能-API文档-2026-01-26.md

# 📡 家长端打卡功能 - 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） |

### 请求示例

```bash
# 获取第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 | 创建时间 |

### 响应示例

```json
{
  "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
  }
}
```

### 错误响应

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

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

---

## 2️⃣ 获取打卡统计数据

### 基本信息

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

### 请求参数

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

### 请求示例

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

### 响应参数

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

### 响应示例

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

### 错误响应

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

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

---

## 🔧 前端调用示例

### 使用封装的API方法

```javascript
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

```javascript
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：正常获取记录列表

**请求：**
```bash
GET /api/checkin/user/records?userId=1&page=1&size=10
```

**预期响应：**
- 状态码：200
- 返回记录列表
- 包含分页信息

### 测试用例2：按日期筛选

**请求：**
```bash
GET /api/checkin/user/records?userId=1&date=2026-01-26
```

**预期响应：**
- 状态码：200
- 只返回指定日期的记录

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

**请求：**
```bash
GET /api/checkin/user/statistics?userId=1
```

**预期响应：**
- 状态码：200
- 返回统计数据对象

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

**请求：**
```bash
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 | 初始版本，实现基础功能 |

---

## 📞 联系方式

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