API 接口文档

完整 RESTful API 接口定义、请求参数、响应格式、错误码说明。接口总数 70+ 个。

1. 接口概述

1.1 基本信息

1.2 通用响应格式

{
  "success": true,
  "message": "操作成功",
  "data": {},
  "code": 200
}

1.3 错误码说明

错误码说明
200成功
400请求参数错误
401未授权（Token无效或过期）
403权限不足
404资源不存在
500服务器内部错误

1.4 通用请求头

Authorization: Bearer <token>
Content-Type: application/json

2. 用户认证模块

2.1 微信小程序登录

POST /api/auth/miniprogram/login

请求参数:

{
  "code": "微信登录code"
}

响应数据:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "user_001",
      "openid": "oXXXX",
      "phone": null,
      "name": null,
      "avatar": null,
      "role": "researcher",
      "isNewUser": true
    }
  }
}

2.2 绑定手机号

POST /api/auth/bindPhone

请求参数: phoneCode（微信获取手机号的 code）

2.3 管理员登录

POST /api/auth/admin/login

请求参数: username, password

2.4 获取当前用户信息

GET /api/user/profile

2.5 获取用户统计数据

GET /api/user/statistics

3. 任务模块

3.1 获取我的任务列表

GET /api/task/my-list

Query 参数: status, keyword, page, pageSize

3.2 获取任务详情

GET /api/task/:id

3.3 开始任务

POST /api/task/:id/start

3.4 创建任务（管理端）

POST /api/task/create

请求体含 title, description, geofenceId, formTemplateId, deadline, requirePhoto, photoLabels, maxAssignees, dispatchMode, openForGrab 等。

3.5–3.8

编辑任务 PUT /api/task/:id、删除 DELETE /api/task/:id、发布 POST /api/task/:id/publish、管理端列表 GET /api/task/admin/list。

4. 打卡模块

POST /api/checkin 提交打卡；GET /api/checkin/:assignmentId 获取打卡记录；POST /api/checkin/validate 校验位置是否在围栏内。

5. 照片模块

POST /api/upload/image 上传照片（multipart/form-data）；DELETE /api/photo/:id 删除；GET /api/photo/list/:assignmentId 获取任务照片列表。

6. OCR 识别模块

POST /api/ocr/recognize 通用文字识别；POST /api/ocr/receipt 票据识别；POST /api/ocr/product 商品识别。

7. 表单模块

GET /api/form/template/:id 获取模板；POST /api/form/draft 保存草稿；POST /api/form/submit 提交表单。管理端：列表、创建、编辑、删除、复制模板。

8. 电子围栏模块

GET /api/geofence/list 围栏列表；GET /api/geofence/:id 详情；POST /api/geofence/create 创建（circle/polygon）；PUT /api/geofence/:id 编辑；DELETE /api/geofence/:id 删除。

9. 抢单模块

GET /api/grab/list 可抢任务列表（支持 latitude, longitude, radius）；POST /api/grab/:taskId 抢单。

10. 审核模块

GET /api/review/pending 待审核列表；GET /api/review/:submissionId 审核详情；POST /api/review/:submissionId/approve 通过；POST /api/review/:submissionId/reject 驳回；POST /api/review/batch 批量审核。

11. 统计导出模块

GET /api/statistics/task 任务统计；GET /api/statistics/researcher 调研员统计；POST /api/export/data 导出数据（xlsx 等）。

12. 消息通知模块

GET /api/message/list 消息列表；POST /api/message/:id/read 标记已读；POST /api/message/readAll 全部已读。

13. 调用示例

13.1 小程序端 (JavaScript)

// 登录
const { code } = await wx.login();
const res = await wx.request({
  url: 'https://api.example.com/v1/api/auth/miniprogram/login',
  method: 'POST',
  data: { code }
});
// 获取任务列表需在 header 中携带 Authorization: Bearer <token>

13.2 管理后台 (TypeScript)

import axios from 'axios';
const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  headers: { 'Content-Type': 'application/json' }
});
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

文档版本：v1.0

接口总数：70+ 个

返回文档首页