Boonlive_RD_Web/Wx_WxCheck_Prod

Fork 0

Files

XuJiacheng f9988ae675 初始化小程序端

2025-12-11 11:06:11 +08:00

16 KiB

Raw Blame History

微信小程序：语音信息打卡 API 接口文档

本文档详细描述了WxCheck项目中Login控制器和Check控制器的所有API接口，包括接口功能、请求参数、响应格式以及调用示例。

基础信息

API基础路径：https://wx-xcx-check.blv-oa.com:4433/api/[controller]/[action]
请求方式：POST

统一响应格式

所有接口返回以下统一格式的JSON响应：

{
  "success": true/false,
  "message": "操作结果描述",
  "data": {...}, // 可选，返回的具体数据
  "error": "错误信息" // 可选，错误时返回
}

1. Login控制器接口

1.1 用户注册接口

接口描述

用户信息更新功能，根据传入的UserKey更新用户的UserName、WeChatName和PhoneNumber信息。

接口路径

/api/Login/Register

请求参数

参数名	类型	必填	描述
UserName	string	否	用户名（可以为空）
UserKey	string	是	用户唯一标识键
WeChatName	string	否	微信名称
PhoneNumber	string	否	电话号码
AvatarUrl	string	否	头像地址

请求示例

{
  "UserName": "张三",
  "UserKey": "openid_from_wechat",
  "WeChatName": "张三的微信",
  "PhoneNumber": "13800138000",
  "AvatarUrl": "https://example.com/avatar.jpg"
}

响应示例

成功响应：

{
  "success": true,
  "data": {
    "Id": 1,
    "UserName": "张三",
    "UserKey": "openid_from_wechat",
    "WeChatName": "张三的微信",
    "PhoneNumber": "13800138000",
    "AvatarUrl": "https://example.com/avatar.jpg",
    "FirstLoginTime": "2023-10-31T10:00:00",
    "IsDisabled": false,
    "CreateTime": "2023-10-31T10:00:00",
    "UpdateTime": "2023-10-31T15:30:00",
    "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

失败响应：

{
  "success": false,
  "message": "用户不存在"
}

{
  "success": false,
  "message": "更新用户信息失败",
  "error": "数据库连接错误"
}

1.2 用户登录接口

接口描述

用户登录功能，将微信小程序code转换为OpenID并验证用户身份。如果用户不存在，则自动创建新用户记录。无论用户是否存在，都返回完整的用户信息和Token。

接口路径

/api/Login/Login

请求参数

参数名	类型	必填	描述
Code	string	是	微信小程序登录凭证code，用于获取OpenID

请求示例

{
  "Code": "wx_login_code_here"
}

响应示例

成功响应（已存在用户）：

{
  "success": true,
  "data": {
    "Id": 1,
    "UserName": "张三",
    "UserKey": "openid_from_wechat",
    "WeChatName": "张三的微信",
    "PhoneNumber": "13800138000",
    "AvatarUrl": "https://example.com/avatar.jpg",
    "FirstLoginTime": "2023-10-31T10:00:00",
    "IsDisabled": false,
    "CreateTime": "2023-10-31T10:00:00",
    "UpdateTime": "2023-10-31T10:00:00",
    "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

成功响应（新用户自动注册）：

{
  "success": true,
  "data": {
    "Id": 2,
    "UserName": "",
    "UserKey": "new_openid_from_wechat",
    "WeChatName": "",
    "PhoneNumber": "",
    "AvatarUrl": "",
    "FirstLoginTime": "2023-10-31T16:00:00",
    "IsDisabled": false,
    "CreateTime": "2023-10-31T16:00:00",
    "UpdateTime": "2023-10-31T16:00:00",
    "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

失败响应：

{
  "success": false,
  "message": "用户已被禁用"
}

{
  "success": false,
  "message": "获取微信OpenID失败",
  "error": "微信API调用失败"
}

2. Check控制器接口

2.1 检查地址接口

接口描述

根据会话记录的GUID查询经纬度信息，并转换为详细地址更新到数据库中。

接口路径

/api/Check/CheckAddress

请求参数

参数名	类型	必填	描述
Guid	string	是	会话唯一标识

请求示例

{
  "Guid": "会话唯一标识"
}

响应示例

成功响应：

{
  "success": true,
  "message": "地址更新成功",
  "address": "北京市海淀区中关村南大街5号"
}

失败响应：

{
  "success": false,
  "message": "记录不存在或已被删除"
}

{
  "success": false,
  "message": "更新失败",
  "error": "数据库操作错误"
}

2.2 添加会话记录接口

接口描述

添加新的会话记录到系统中。

接口路径

/api/Check/AddConversation

请求参数

参数名	类型	必填	描述
UserKey	string	是	用户唯一标识键
ConversationContent	string	是	会话内容
SendMethod	string	是	发送方式
UserLocation	string	否	用户定位信息（经纬度格式："纬度,经度"）
MessageType	int	否	1:公有消息，2:私有消息
Guid	string	否	会话唯一标识（不提供则系统自动生成）

请求示例

{
  "UserKey": "user_123456",
  "ConversationContent": "这是一条测试消息",
  "SendMethod": "文本",
  "UserLocation": "39.9087,116.3975",
  "MessageType": 1
}

响应示例

成功响应：

{
  "success": true,
  "message": "收到！",
  "conversationGuid": "会话唯一标识",
  "receivedTime": "2023-10-31 10:05:00"
}

失败响应：

{
  "success": false,
  "message": "发送失败",
  "error": "数据库操作错误"
}

2.3 查询会话记录接口

接口描述

根据用户唯一标识键查询该用户的所有会话记录。

接口路径

https://wx-xcx-check.blv-oa.com/api/Check/GetConversations

请求参数

参数名	类型	必填	描述
UserKey	string	是	用户唯一标识键
MessageType	int	否	0:不判断消息类型（默认），1:只返回公有消息，2:只返回私有消息

请求示例

{
  "UserKey": "user_123456",
  "MessageType": 0
}

响应示例

成功响应：

{
  "success": true,
  "data": [
    {
      "Id": 1,
      "Guid": "会话唯一标识",
      "UserKey": "user_123456",
      "ConversationContent": "这是一条测试消息",
      "SendMethod": "文本",
      "UserLocation": "北京市海淀区",
      "Latitude": "39.9087",
      "Longitude": "116.3975",
      "RecordTime": "2023-10-31T10:05:00",
      "RecordTimeUTCStamp": 1698732300000,
      "IsDeleted": false,
      "CreateTime": "2023-10-31T10:05:00",
      "MessageType": 1
    },
    {
      "Id": 2,
      "Guid": "会话唯一标识",
      "UserKey": "user_123456",
      "ConversationContent": "这是第二条测试消息",
      "SendMethod": "图片",
      "UserLocation": "北京市朝阳区",
      "Latitude": "39.9180",
      "Longitude": "116.4272",
      "RecordTime": "2023-10-31T10:06:00",
      "RecordTimeUTCStamp": 1698732360000,
      "IsDeleted": false,
      "CreateTime": "2023-10-31T10:06:00",
      "MessageType": 2
    }
  ]
}

失败响应：

{
  "success": false,
  "message": "查询失败",
  "error": "数据库连接错误"
}

2.4 分页查询会话记录接口

接口描述

分页查询用户的会话记录，每页默认10条，按时间戳从最新到最旧排序，支持根据消息类型进行过滤。

接口路径

https://wx-xcx-check.blv-oa.com:4433/api/Check/GetConversationsByPage

请求参数

参数名	类型	必填	描述
UserKey	string	是	用户唯一标识键
Page	int	否	页码，默认为1，小于1时自动设为1
PageSize	int	否	每页数量，默认为10，最大100，小于1时自动设为10
MessageType	int	否	0:不判断消息类型（默认），1:只返回公有消息，2:只返回私有消息

请求示例

{
  "UserKey": "user_123456",
  "Page": 1,
  "PageSize": 10,
  "MessageType": 0
}

响应示例

成功响应：

{
  "success": true,
  "data": {
    "conversations": [
      {
        "Id": 1,
        "Guid": "会话唯一标识",
        "UserKey": "user_123456",
        "ConversationContent": "这是一条测试消息",
        "SendMethod": "文本",
        "UserLocation": "北京市海淀区",
        "Latitude": "39.9087",
        "Longitude": "116.3975",
        "RecordTime": "2023-10-31T10:00:00",
        "RecordTimeUTCStamp": 1698727200000,
        "IsDeleted": false,
        "CreateTime": "2023-10-31T10:00:00",
        "MessageType": 1
      },
      {
        "Id": 2,
        "Guid": "会话唯一标识",
        "UserKey": "user_123456",
        "ConversationContent": "这是一条私有消息",
        "SendMethod": "文本",
        "UserLocation": "北京市朝阳区",
        "Latitude": "39.9180",
        "Longitude": "116.4272",
        "RecordTime": "2023-10-31T09:55:00",
        "RecordTimeUTCStamp": 1698724500000,
        "IsDeleted": false,
        "CreateTime": "2023-10-31T09:55:00",
        "MessageType": 2
      }
    ],
    "totalCount": 25,
    "page": 1,
    "pageSize": 10,
    "totalPages": 3
  }
}

失败响应：

{
  "success": false,
  "message": "查询失败",
  "error": "数据库操作错误"
}

2.5 根据GUID查询会话记录接口

接口描述

根据会话唯一标识（GUID）查询会话记录详情，不考虑IsDeleted状态。

接口路径

/api/Check/GetConversationByGuid

请求参数

参数名	类型	必填	描述
Guid	string	是	会话唯一标识

请求示例

{
  "Guid": "会话唯一标识"
}

响应示例

成功响应：

{
  "success": true,
  "message": "查询成功",
  "data": {
    "Id": 1,
    "Guid": "会话唯一标识",
    "UserKey": "user_123456",
    "ConversationContent": "这是一条测试消息",
    "SendMethod": "文本",
    "UserLocation": "北京市海淀区",
    "Latitude": "39.9087",
    "Longitude": "116.3975",
    "RecordTime": "2023-10-31T10:05:00",
    "RecordTimeUTCStamp": 1698732300000,
    "IsDeleted": false,
    "CreateTime": "2023-10-31T10:05:00",
    "MessageType": 1
  }
}

失败响应：

{
  "success": false,
  "message": "未找到该记录"
}

{
  "success": false,
  "message": "查询失败",
  "error": "数据库操作错误"
}

2.6 更新会话记录接口

接口描述

更新指定GUID的会话记录，需要验证UserKey的权限。每次更新时，RecordTime会自动更新为当前时间。

接口路径

/api/Check/UpdateConversation

请求参数

参数名	类型	必填	描述
Guid	string	是	会话唯一标识
UserKey	string	是	用户唯一标识键（用于权限验证）
ConversationContent	string	是	新的会话内容
SendMethod	string	是	新的发送方式
UserLocation	string	否	新的用户定位信息
MessageType	int	否	1:公有消息，2:私有消息

请求示例

{
  "Guid": "会话唯一标识",
  "UserKey": "user_123456",
  "ConversationContent": "更新后的会话内容",
  "SendMethod": "文本",
  "UserLocation": "北京市西城区",
  "MessageType": 1
}

响应示例

成功响应：

{
  "success": true,
  "message": "更新成功",
  "receivedTime": "2023-10-31 10:10:00"
}

失败响应：

{
  "success": false,
  "message": "记录不存在或无权限修改"
}

{
  "success": false,
  "message": "更新失败",
  "error": "数据库操作错误"
}

2.7 删除会话记录接口

接口描述

软删除会话记录（将IsDeleted标记为1），需要验证UserKey的权限。

接口路径

/api/Check/DeleteConversation

请求参数

参数名	类型	必填	描述
Guid	string	是	会话唯一标识
UserKey	string	是	用户唯一标识键（用于权限验证）

请求示例

{
  "Guid": "会话唯一标识",
  "UserKey": "user_123456"
}

响应示例

成功响应：

{
  "success": true,
  "message": "删除成功"
}

失败响应：

{
  "success": false,
  "message": "记录不存在或已被删除"
}

{
  "success": false,
  "message": "删除失败",
  "error": "数据库操作错误"
}

2.8 从Redis Stream读取消息接口

接口描述

从Redis Stream读取新的会话消息。

接口路径

/api/Check/ReadMessageFromRedis

请求参数

参数名	类型	必填	描述
GroupName	string	否	消费组名称，默认：xcx_group
ConsumerName	string	否	消费者名称，默认：consumer_时间戳
Count	int	否	读取消息数量，默认：1

请求示例

{
  "GroupName": "xcx_group",
  "ConsumerName": "consumer_1",
  "Count": 5
}

响应示例

成功响应：

{
  "success": true,
  "message": "成功读取消息",
  "data": [
    {
      "MessageId": "1635739200000-0",
      "Id": "1",
      "Guid": "会话唯一标识",
      "UserKey": "user_123456",
      "ConversationContent": "测试消息",
      "SendMethod": "文本",
      "UserLocation": "北京市海淀区",
      "Latitude": "39.9087",
      "Longitude": "116.3975",
      "RecordTime": "2023-10-31T10:00:00",
      "RecordTimeUTCStamp": "1698727200000",
      "IsDeleted": "false",
      "CreateTime": "2023-10-31T10:00:00",
      "MessageType": "1",
      "UserName": "张三",
      "WeChatName": "张三的微信",
      "PhoneNumber": "13800138000",
      "AvatarUrl": "https://example.com/avatar.jpg"
    }
  ]
}

失败响应：

{
  "success": false,
  "message": "读取消息失败",
  "error": "Redis操作错误"
}

3. 接口调用说明

3.1 HTTP客户端调用示例（JavaScript）

// 封装API请求函数
async function callApi(endpoint, data) {
  try {
    const response = await fetch(`http://your-api-domain/api${endpoint}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('API调用失败:', error);
    throw error;
  }
}

// 用户信息更新示例
async function updateUser() {
  const result = await callApi('/Login/Register', {
    UserName: '张三',
    UserKey: 'openid_from_wechat',
    WeChatName: '张三的微信',
    PhoneNumber: '13800138000'
  });
  
  if (result.success) {
    console.log('用户信息更新成功');
  } else {
    console.log('用户信息更新失败:', result.message);
  }
}

// 用户登录示例
async function loginUser() {
  const result = await callApi('/Login/Login', {
    Code: 'wx_login_code_here'
  });
  
  if (result.success) {
    console.log('登录成功，用户信息:', result.data);
    // 保存用户信息和Token到本地存储
    localStorage.setItem('userInfo', JSON.stringify(result.data));
    localStorage.setItem('token', result.data.Token);
  } else {
    console.log('登录失败:', result.message);
  }
}

// 添加会话示例
async function addConversation() {
  const result = await callApi('/Check/AddConversation', {
    UserKey: 'user_123456',
    ConversationContent: '测试会话内容',
    SendMethod: '文本',
    UserLocation: '北京',
    MessageType: 0
  });
  
  if (result.success) {
    console.log('会话添加成功');
  } else {
    console.log('会话添加失败:', result.message);
  }
}

3.2 常见错误处理

数据库连接错误：检查数据库服务是否正常运行，连接字符串是否正确
权限验证失败：确保提供的UserKey与操作资源匹配
记录不存在：在更新或删除前确认记录ID和UserKey的正确性
网络错误：检查API服务是否正常运行，网络连接是否稳定

4. 安全注意事项

参数验证：所有接口都应在前端进行基本的数据格式验证
UserKey保护：UserKey作为用户身份标识，应妥善保护，避免泄露
错误信息处理：生产环境中应避免返回详细的错误信息，防止信息泄露
请求频率限制：建议在生产环境中对API接口实施请求频率限制，防止滥用

5. 接口维护信息

最后更新时间：2023-11-01
维护人员：系统管理员
版本号：v1.2.0

16 KiB Raw Blame History Unescape Escape

微信小程序：语音信息打卡 API 接口文档

基础信息

统一响应格式

1. Login控制器接口

1.1 用户注册接口

接口描述

接口路径

请求参数

请求示例

响应示例

1.2 用户登录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2. Check控制器接口

2.1 检查地址接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.2 添加会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.3 查询会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.4 分页查询会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.5 根据GUID查询会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.6 更新会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.7 删除会话记录接口

接口描述

接口路径

请求参数

请求示例

响应示例

2.8 从Redis Stream读取消息接口

接口描述

接口路径

请求参数

请求示例

响应示例

3. 接口调用说明

3.1 HTTP客户端调用示例（JavaScript）

3.2 常见错误处理

4. 安全注意事项

5. 接口维护信息

16 KiB

Raw Blame History