初始化项目
This commit is contained in:
Jiacheng Xu
571
WxCheckApi/API文档.md
Normal file
571
WxCheckApi/API文档.md
Normal file
@@ -0,0 +1,571 @@
|
||||
# 微信小程序：语音信息打卡 API 接口文档
|
||||
|
||||
本文档详细描述了WxCheck项目中Login控制器和Check控制器的所有API接口，包括接口功能、请求参数、响应格式以及调用示例。
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **API基础路径**：`https://wx-xcx-check.blv-oa.com:4433/api/[controller]/[action]`
|
||||
- **请求方式**：POST
|
||||
|
||||
## 统一响应格式
|
||||
|
||||
所有接口返回以下统一格式的JSON响应：
|
||||
|
||||
```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 | 否 | 头像地址 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"UserName": "张三",
|
||||
"UserKey": "openid_from_wechat",
|
||||
"WeChatName": "张三的微信",
|
||||
"PhoneNumber": "13800138000",
|
||||
"AvatarUrl": "https://example.com/avatar.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"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..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "用户不存在"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "更新用户信息失败",
|
||||
"error": "数据库连接错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 用户登录接口
|
||||
|
||||
#### 接口描述
|
||||
用户登录功能，将微信小程序code转换为OpenID并验证用户身份。如果用户不存在，则自动创建新用户记录。无论用户是否存在，都返回完整的用户信息和Token。
|
||||
|
||||
#### 接口路径
|
||||
`/api/Login/Login`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| Code | string | 是 | 微信小程序登录凭证code，用于获取OpenID |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"Code": "wx_login_code_here"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应（已存在用户）：**
|
||||
```json
|
||||
{
|
||||
"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..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应（新用户自动注册）：**
|
||||
```json
|
||||
{
|
||||
"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..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "用户已被禁用"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "获取微信OpenID失败",
|
||||
"error": "微信API调用失败"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Check控制器接口
|
||||
|
||||
### 2.1 添加会话记录接口
|
||||
|
||||
#### 接口描述
|
||||
添加新的会话记录到系统中。
|
||||
|
||||
#### 接口路径
|
||||
`/api/Check/AddConversation`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| UserKey | string | 是 | 用户唯一标识键 |
|
||||
| ConversationContent | string | 是 | 会话内容 |
|
||||
| SendMethod | string | 是 | 发送方式 |
|
||||
| UserLocation | string | 否 | 用户定位信息 |
|
||||
| MessageType | int | 否 | 1:公有消息，2:私有消息 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "这是一条测试消息",
|
||||
"SendMethod": "文本",
|
||||
"UserLocation": "北京市海淀区",
|
||||
"MessageType": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "收到！"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "发送失败",
|
||||
"error": "数据库操作错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 查询会话记录接口
|
||||
|
||||
#### 接口描述
|
||||
根据用户唯一标识键查询该用户的所有会话记录。
|
||||
|
||||
#### 接口路径
|
||||
`https://wx-xcx-check.blv-oa.com/api/Check/GetConversations`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| UserKey | string | 是 | 用户唯一标识键 |
|
||||
| MessageType | int | 否 | 0:不判断消息类型（默认），1:只返回公有消息，2:只返回私有消息 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"UserKey": "user_123456",
|
||||
"MessageType": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"Id": 1,
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "这是一条测试消息",
|
||||
"SendMethod": "文本",
|
||||
"UserLocation": "北京市海淀区",
|
||||
"RecordTime": "2023-10-31T10:05:00",
|
||||
"RecordTimeUTCStamp": 1698732300000,
|
||||
"IsDeleted": false,
|
||||
"CreateTime": "2023-10-31T10:05:00",
|
||||
"MessageType": 0
|
||||
},
|
||||
{
|
||||
"Id": 2,
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "这是第二条测试消息",
|
||||
"SendMethod": "图片",
|
||||
"UserLocation": "北京市朝阳区",
|
||||
"RecordTime": "2023-10-31T10:06:00",
|
||||
"RecordTimeUTCStamp": 1698732360000,
|
||||
"IsDeleted": false,
|
||||
"CreateTime": "2023-10-31T10:06:00",
|
||||
"MessageType": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "查询失败",
|
||||
"error": "数据库连接错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 分页查询会话记录接口
|
||||
|
||||
#### 接口描述
|
||||
分页查询用户的会话记录，每页默认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:只返回私有消息 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"UserKey": "user_123456",
|
||||
"Page": 1,
|
||||
"PageSize": 10,
|
||||
"MessageType": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"conversations": [
|
||||
{
|
||||
"Id": 1,
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "这是一条测试消息",
|
||||
"SendMethod": "文本",
|
||||
"UserLocation": "北京市海淀区",
|
||||
"RecordTime": "2023-10-31T10:00:00",
|
||||
"RecordTimeUTCStamp": 1698727200000,
|
||||
"IsDeleted": false,
|
||||
"CreateTime": "2023-10-31T10:00:00",
|
||||
"MessageType": 0
|
||||
},
|
||||
{
|
||||
"Id": 2,
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "这是一条私有消息",
|
||||
"SendMethod": "文本",
|
||||
"UserLocation": "北京市朝阳区",
|
||||
"RecordTime": "2023-10-31T09:55:00",
|
||||
"RecordTimeUTCStamp": 1698724500000,
|
||||
"IsDeleted": false,
|
||||
"CreateTime": "2023-10-31T09:55:00",
|
||||
"MessageType": 1
|
||||
}
|
||||
],
|
||||
"totalCount": 25,
|
||||
"page": 1,
|
||||
"pageSize": 10,
|
||||
"totalPages": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "查询失败",
|
||||
"error": "数据库操作错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 更新会话记录接口
|
||||
|
||||
#### 接口描述
|
||||
更新指定ID的会话记录，需要验证UserKey的权限。
|
||||
|
||||
#### 接口路径
|
||||
`/api/Check/UpdateConversation`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| Id | long | 是 | 会话记录ID |
|
||||
| UserKey | string | 是 | 用户唯一标识键（用于权限验证） |
|
||||
| ConversationContent | string | 是 | 新的会话内容 |
|
||||
| SendMethod | string | 是 | 新的发送方式 |
|
||||
| UserLocation | string | 否 | 新的用户定位信息 |
|
||||
| MessageType | int | 否 | 1:公有消息，2:私有消息 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": 1,
|
||||
"UserKey": "user_123456",
|
||||
"ConversationContent": "更新后的会话内容",
|
||||
"SendMethod": "文本",
|
||||
"UserLocation": "北京市西城区",
|
||||
"MessageType": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "会话更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "会话记录不存在或无权限修改"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "更新失败",
|
||||
"error": "数据库操作错误"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 删除会话记录接口
|
||||
|
||||
#### 接口描述
|
||||
软删除会话记录（将IsDeleted标记为1），需要验证UserKey的权限。
|
||||
|
||||
#### 接口路径
|
||||
`/api/Check/DeleteConversation`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| Id | long | 是 | 会话记录ID |
|
||||
| UserKey | string | 是 | 用户唯一标识键（用于权限验证） |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": 1,
|
||||
"UserKey": "user_123456"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "会话删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "会话记录不存在或已被删除"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "删除失败",
|
||||
"error": "数据库操作错误"
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 接口调用说明
|
||||
|
||||
### 3.1 HTTP客户端调用示例（JavaScript）
|
||||
|
||||
```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 常见错误处理
|
||||
|
||||
1. **数据库连接错误**：检查数据库服务是否正常运行，连接字符串是否正确
|
||||
2. **权限验证失败**：确保提供的UserKey与操作资源匹配
|
||||
3. **记录不存在**：在更新或删除前确认记录ID和UserKey的正确性
|
||||
4. **网络错误**：检查API服务是否正常运行，网络连接是否稳定
|
||||
|
||||
## 4. 安全注意事项
|
||||
|
||||
1. **参数验证**：所有接口都应在前端进行基本的数据格式验证
|
||||
2. **UserKey保护**：UserKey作为用户身份标识，应妥善保护，避免泄露
|
||||
3. **错误信息处理**：生产环境中应避免返回详细的错误信息，防止信息泄露
|
||||
4. **请求频率限制**：建议在生产环境中对API接口实施请求频率限制，防止滥用
|
||||
|
||||
## 5. 接口维护信息
|
||||
|
||||
- **最后更新时间**：2023-11-01
|
||||
- **维护人员**：系统管理员
|
||||
- **版本号**：v1.1.0
|
||||
Reference in New Issue
Block a user