921 lines
16 KiB
Markdown
921 lines
16 KiB
Markdown
# 学业邑规划 - 小程序 API 文档
|
||
|
||
本文档定义了小程序端调用的所有后端接口。
|
||
|
||
---
|
||
|
||
## 一、接口规范
|
||
|
||
### 1.1 基础信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 基础地址 | 开发环境：`http://localhost:5000`<br>生产环境：`https://api.example.com` |
|
||
| 请求方式 | GET / POST |
|
||
| 数据格式 | JSON |
|
||
| 认证方式 | Bearer Token |
|
||
|
||
### 1.2 请求头
|
||
|
||
```
|
||
Content-Type: application/json
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
### 1.3 响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 1.4 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 1001 | 参数错误 |
|
||
| 1002 | 未登录 |
|
||
| 1003 | 登录已过期 |
|
||
| 1004 | 无权限 |
|
||
| 2001 | 业务错误 |
|
||
| 5000 | 系统错误 |
|
||
|
||
---
|
||
|
||
## 二、用户模块
|
||
|
||
### 2.1 微信登录
|
||
|
||
**接口**：`POST /api/user/login`
|
||
|
||
**描述**：微信小程序登录
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface LoginRequest {
|
||
/** 微信 code */
|
||
code: string
|
||
/** 加密手机号数据 */
|
||
encryptedData: string
|
||
/** 加密向量 */
|
||
iv: string
|
||
/** 邀请人ID（可选） */
|
||
inviteUserId?: number
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface LoginResponse {
|
||
/** 访问令牌 */
|
||
token: string
|
||
/** 刷新令牌 */
|
||
refreshToken: string
|
||
/** 用户信息 */
|
||
userInfo: UserInfo
|
||
}
|
||
|
||
interface UserInfo {
|
||
id: number
|
||
uid: string
|
||
nickname: string
|
||
avatar: string
|
||
phone: string
|
||
userLevel: number // 1普通用户 2合伙人 3渠道合伙人
|
||
createTime: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 获取用户信息
|
||
|
||
**接口**：`GET /api/user/getProfile`
|
||
|
||
**描述**：获取当前登录用户信息
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface UserInfo {
|
||
id: number
|
||
uid: string
|
||
nickname: string
|
||
avatar: string
|
||
phone: string
|
||
userLevel: number
|
||
balance: number // 可提现余额
|
||
totalIncome: number // 累计收益
|
||
createTime: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 更新用户信息
|
||
|
||
**接口**：`POST /api/user/updateProfile`
|
||
|
||
**描述**：更新用户昵称
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface UpdateProfileRequest {
|
||
nickname: string
|
||
}
|
||
```
|
||
|
||
**响应数据**：`boolean`
|
||
|
||
---
|
||
|
||
### 2.4 更新头像
|
||
|
||
**接口**：`POST /api/user/updateAvatar`
|
||
|
||
**描述**：更新用户头像
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface UpdateAvatarRequest {
|
||
/** 头像文件（Base64 或 URL） */
|
||
avatar: string
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface UpdateAvatarResponse {
|
||
/** 新头像 URL */
|
||
avatarUrl: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、首页模块
|
||
|
||
### 3.1 获取 Banner 列表
|
||
|
||
**接口**：`GET /api/home/getBannerList`
|
||
|
||
**描述**：获取首页轮播图列表
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface BannerItem {
|
||
id: number
|
||
title: string
|
||
imageUrl: string
|
||
linkType: number // 0无跳转 1内部页面 2外部链接 3小程序
|
||
linkUrl: string
|
||
appId?: string // 小程序 AppId
|
||
}
|
||
|
||
type Response = BannerItem[]
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 获取测评入口列表
|
||
|
||
**接口**：`GET /api/home/getAssessmentList`
|
||
|
||
**描述**：获取测评类型列表
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AssessmentType {
|
||
id: number
|
||
name: string
|
||
code: string
|
||
imageUrl: string
|
||
price: number
|
||
status: number // 0已下线 1已上线 2即将上线
|
||
}
|
||
|
||
type Response = AssessmentType[]
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 获取宣传图列表
|
||
|
||
**接口**：`GET /api/home/getPromotionList`
|
||
|
||
**描述**：获取首页底部宣传图
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface PromotionItem {
|
||
id: number
|
||
title: string
|
||
imageUrl: string
|
||
}
|
||
|
||
type Response = PromotionItem[]
|
||
```
|
||
|
||
---
|
||
|
||
## 四、团队模块
|
||
|
||
### 4.1 获取团队介绍
|
||
|
||
**接口**：`GET /api/team/getInfo`
|
||
|
||
**描述**：获取团队介绍图片
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface TeamInfo {
|
||
images: string[] // 图片列表
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、测评模块
|
||
|
||
### 5.1 获取测评介绍
|
||
|
||
**接口**：`GET /api/assessment/getIntro`
|
||
|
||
**描述**：获取测评介绍内容（基本信息页顶部）
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| typeId | number | 是 | 测评类型ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AssessmentIntro {
|
||
/** 介绍内容（富文本或图片URL） */
|
||
content: string
|
||
/** 内容类型：text / image */
|
||
contentType: string
|
||
/** 测评价格 */
|
||
price: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 获取题目列表
|
||
|
||
**接口**：`GET /api/assessment/getQuestionList`
|
||
|
||
**描述**：获取测评题目列表
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| typeId | number | 是 | 测评类型ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface Question {
|
||
id: number
|
||
questionNo: number
|
||
content: string
|
||
}
|
||
|
||
type Response = Question[]
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 提交测评答案
|
||
|
||
**接口**：`POST /api/assessment/submitAnswers`
|
||
|
||
**描述**：提交测评答案
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface SubmitAnswersRequest {
|
||
/** 测评记录ID */
|
||
recordId: number
|
||
/** 答案列表 */
|
||
answers: {
|
||
questionId: number
|
||
answerValue: number // 1-10
|
||
}[]
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface SubmitAnswersResponse {
|
||
/** 是否提交成功 */
|
||
success: boolean
|
||
/** 报告预计生成时间（秒） */
|
||
estimatedTime: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.4 查询报告生成状态
|
||
|
||
**接口**：`GET /api/assessment/getResultStatus`
|
||
|
||
**描述**：查询测评报告生成状态
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| recordId | number | 是 | 测评记录ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface ResultStatus {
|
||
/** 状态：1待测评 2测评中 3生成中 4已完成 */
|
||
status: number
|
||
/** 是否完成 */
|
||
isCompleted: boolean
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.5 获取测评结果
|
||
|
||
**接口**：`GET /api/assessment/getResult`
|
||
|
||
**描述**：获取测评报告详情
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| recordId | number | 是 | 测评记录ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AssessmentResult {
|
||
/** 基本信息 */
|
||
basicInfo: {
|
||
name: string
|
||
age: number
|
||
educationStage: string
|
||
testDate: string
|
||
}
|
||
/** 八大智能分析 */
|
||
intelligenceAnalysis: {
|
||
items: IntelligenceItem[]
|
||
topTwo: IntelligenceConclusion[]
|
||
bottomTwo: IntelligenceConclusion[]
|
||
}
|
||
/** 个人特质分析 */
|
||
traitAnalysis: {
|
||
items: TraitItem[]
|
||
topConclusion: string
|
||
}
|
||
/** 40项细分能力 */
|
||
abilityAnalysis: {
|
||
groups: AbilityGroup[]
|
||
topTen: AbilityItem[]
|
||
bottomTen: AbilityItem[]
|
||
}
|
||
/** 其他分析... */
|
||
}
|
||
|
||
interface IntelligenceItem {
|
||
name: string
|
||
code: string
|
||
score: number
|
||
maxScore: number
|
||
percentage: number
|
||
rank: number
|
||
}
|
||
|
||
interface IntelligenceConclusion {
|
||
name: string
|
||
rank: number
|
||
rankName: string // 最强五星 / 较强五星 / 相对较弱
|
||
conclusion: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.6 验证邀请码
|
||
|
||
**接口**：`POST /api/assessment/verifyInviteCode`
|
||
|
||
**描述**：验证测评邀请码
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface VerifyInviteCodeRequest {
|
||
/** 邀请码（5位大写字母） */
|
||
code: string
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface VerifyInviteCodeResponse {
|
||
/** 是否有效 */
|
||
isValid: boolean
|
||
/** 错误信息（无效时） */
|
||
errorMessage?: string // "邀请码有误" / "邀请码已被使用"
|
||
/** 邀请码ID（有效时） */
|
||
inviteCodeId?: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.7 获取往期测评列表
|
||
|
||
**接口**：`GET /api/assessment/getHistoryList`
|
||
|
||
**描述**：获取用户的往期测评记录
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认20 |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AssessmentHistory {
|
||
id: number
|
||
orderNo: string
|
||
assessmentName: string
|
||
status: number // 3生成中 4已完成
|
||
statusText: string
|
||
testDate: string
|
||
}
|
||
|
||
interface PageResponse {
|
||
list: AssessmentHistory[]
|
||
total: number
|
||
page: number
|
||
pageSize: number
|
||
totalPages: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、订单模块
|
||
|
||
### 6.1 获取订单列表
|
||
|
||
**接口**：`GET /api/order/getList`
|
||
|
||
**描述**：获取用户订单列表
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认20 |
|
||
| orderType | number | 否 | 订单类型：1测评 2学业规划 |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface OrderItem {
|
||
id: number
|
||
orderNo: string
|
||
orderType: number
|
||
productName: string
|
||
amount: number
|
||
status: number
|
||
statusText: string
|
||
createTime: string
|
||
/** 测评记录ID（测评订单） */
|
||
assessmentRecordId?: number
|
||
}
|
||
|
||
interface PageResponse {
|
||
list: OrderItem[]
|
||
total: number
|
||
page: number
|
||
pageSize: number
|
||
totalPages: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.2 获取订单详情
|
||
|
||
**接口**：`GET /api/order/getDetail`
|
||
|
||
**描述**：获取订单详情
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| orderId | number | 是 | 订单ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface OrderDetail {
|
||
id: number
|
||
orderNo: string
|
||
orderType: number
|
||
productId: number
|
||
productName: string
|
||
amount: number
|
||
payAmount: number
|
||
payType: number
|
||
status: number
|
||
statusText: string
|
||
payTime?: string
|
||
createTime: string
|
||
/** 测评相关 */
|
||
assessmentRecord?: {
|
||
id: number
|
||
status: number
|
||
name: string
|
||
phone: string
|
||
}
|
||
/** 学业规划相关 */
|
||
plannerBooking?: {
|
||
id: number
|
||
plannerName: string
|
||
bookingDate: string
|
||
bookingTime: string
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.3 创建订单
|
||
|
||
**接口**：`POST /api/order/create`
|
||
|
||
**描述**：创建订单
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface CreateOrderRequest {
|
||
/** 订单类型：1测评 2学业规划 */
|
||
orderType: number
|
||
/** 商品ID（测评类型ID / 规划师ID） */
|
||
productId: number
|
||
/** 测评基本信息（测评订单必填） */
|
||
assessmentInfo?: {
|
||
name: string
|
||
phone: string
|
||
gender: number
|
||
age: number
|
||
educationStage: number
|
||
province: string
|
||
city: string
|
||
district: string
|
||
}
|
||
/** 规划预约信息（学业规划订单必填） */
|
||
plannerInfo?: {
|
||
bookingDate: string
|
||
bookingTime: string
|
||
name: string
|
||
phone: string
|
||
gender: number
|
||
grade: number
|
||
majorName?: string
|
||
scoreChinese?: number
|
||
scoreMath?: number
|
||
scoreEnglish?: number
|
||
scorePhysics?: number
|
||
scoreChemistry?: number
|
||
scoreBiology?: number
|
||
scoreGeography?: number
|
||
scorePolitics?: number
|
||
}
|
||
/** 邀请码ID（使用邀请码时） */
|
||
inviteCodeId?: number
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface CreateOrderResponse {
|
||
/** 订单ID */
|
||
orderId: number
|
||
/** 订单编号 */
|
||
orderNo: string
|
||
/** 支付金额 */
|
||
payAmount: number
|
||
/** 是否需要支付（使用邀请码时为 false） */
|
||
needPay: boolean
|
||
/** 测评记录ID（测评订单） */
|
||
assessmentRecordId?: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.4 发起支付
|
||
|
||
**接口**：`POST /api/order/pay`
|
||
|
||
**描述**：发起微信支付
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface PayRequest {
|
||
/** 订单ID */
|
||
orderId: number
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface PayResponse {
|
||
/** 微信支付参数 */
|
||
timeStamp: string
|
||
nonceStr: string
|
||
package: string
|
||
signType: string
|
||
paySign: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.5 查询支付结果
|
||
|
||
**接口**：`GET /api/order/getPayResult`
|
||
|
||
**描述**：查询订单支付结果
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| orderId | number | 是 | 订单ID |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface PayResult {
|
||
/** 是否支付成功 */
|
||
isPaid: boolean
|
||
/** 订单状态 */
|
||
status: number
|
||
/** 测评记录ID（测评订单） */
|
||
assessmentRecordId?: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、学业规划模块
|
||
|
||
### 7.1 获取规划师列表
|
||
|
||
**接口**：`GET /api/planner/getList`
|
||
|
||
**描述**：获取规划师列表
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface PlannerInfo {
|
||
id: number
|
||
name: string
|
||
avatar: string
|
||
introduction: string
|
||
price: number
|
||
}
|
||
|
||
type Response = PlannerInfo[]
|
||
```
|
||
|
||
---
|
||
|
||
### 7.2 预约规划
|
||
|
||
**接口**：`POST /api/planner/book`
|
||
|
||
**描述**：预约学业规划（创建订单并支付）
|
||
|
||
**请求参数**：同 `创建订单` 接口的 `plannerInfo`
|
||
|
||
**响应数据**：同 `创建订单` 接口
|
||
|
||
---
|
||
|
||
## 八、分销模块
|
||
|
||
### 8.1 获取邀请信息
|
||
|
||
**接口**：`GET /api/invite/getInfo`
|
||
|
||
**描述**：获取邀请页面信息
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface InviteInfo {
|
||
/** 邀请链接 */
|
||
inviteUrl: string
|
||
/** 邀请码 */
|
||
inviteCode: string
|
||
/** 已提现金额 */
|
||
withdrawnAmount: number
|
||
/** 待提现金额 */
|
||
pendingAmount: number
|
||
/** 邀请人数 */
|
||
inviteCount: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8.2 生成邀请二维码
|
||
|
||
**接口**：`GET /api/invite/getQrcode`
|
||
|
||
**描述**：生成邀请二维码图片
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface QrcodeResponse {
|
||
/** 二维码图片 URL */
|
||
qrcodeUrl: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8.3 获取邀请记录
|
||
|
||
**接口**：`GET /api/invite/getRecordList`
|
||
|
||
**描述**：获取邀请记录列表
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码 |
|
||
| pageSize | number | 否 | 每页数量 |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface InviteRecord {
|
||
/** 用户ID */
|
||
userId: number
|
||
/** 用户昵称 */
|
||
nickname: string
|
||
/** 用户头像 */
|
||
avatar: string
|
||
/** 用户UID */
|
||
uid: string
|
||
/** 注册日期 */
|
||
registerDate: string
|
||
/** 贡献佣金 */
|
||
commission: number
|
||
}
|
||
|
||
interface PageResponse {
|
||
list: InviteRecord[]
|
||
total: number
|
||
page: number
|
||
pageSize: number
|
||
totalPages: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8.4 获取佣金信息
|
||
|
||
**接口**：`GET /api/invite/getCommission`
|
||
|
||
**描述**：获取佣金详情
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface CommissionInfo {
|
||
/** 累计收益 */
|
||
totalIncome: number
|
||
/** 已提现 */
|
||
withdrawnAmount: number
|
||
/** 待提现 */
|
||
pendingAmount: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8.5 申请提现
|
||
|
||
**接口**：`POST /api/invite/applyWithdraw`
|
||
|
||
**描述**：申请提现
|
||
|
||
**请求参数**：
|
||
```typescript
|
||
interface ApplyWithdrawRequest {
|
||
/** 提现金额（整数，最低1元） */
|
||
amount: number
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface ApplyWithdrawResponse {
|
||
/** 是否成功 */
|
||
success: boolean
|
||
/** 错误信息 */
|
||
errorMessage?: string // "超出待提现金额"
|
||
/** 提现单号 */
|
||
withdrawalNo?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8.6 获取提现记录
|
||
|
||
**接口**：`GET /api/invite/getWithdrawList`
|
||
|
||
**描述**：获取提现记录列表
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码 |
|
||
| pageSize | number | 否 | 每页数量 |
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface WithdrawRecord {
|
||
id: number
|
||
withdrawalNo: string
|
||
amount: number
|
||
status: number // 1申请中 2提现中 3已提现 4已取消
|
||
statusText: string
|
||
createTime: string
|
||
payTime?: string
|
||
}
|
||
|
||
interface PageResponse {
|
||
list: WithdrawRecord[]
|
||
total: number
|
||
page: number
|
||
pageSize: number
|
||
totalPages: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 九、系统模块
|
||
|
||
### 9.1 获取用户协议
|
||
|
||
**接口**：`GET /api/system/getAgreement`
|
||
|
||
**描述**：获取用户协议内容
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AgreementResponse {
|
||
/** 协议内容（富文本） */
|
||
content: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9.2 获取隐私政策
|
||
|
||
**接口**：`GET /api/system/getPrivacy`
|
||
|
||
**描述**：获取隐私政策内容
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface PrivacyResponse {
|
||
/** 政策内容（富文本） */
|
||
content: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9.3 获取关于我们
|
||
|
||
**接口**：`GET /api/system/getAbout`
|
||
|
||
**描述**：获取关于我们内容
|
||
|
||
**响应数据**：
|
||
```typescript
|
||
interface AboutResponse {
|
||
/** 内容（富文本） */
|
||
content: string
|
||
/** 版本号 */
|
||
version: string
|
||
}
|
||
```
|