outsource/mi-assessment

Fork 0

zpc 501bdcc999 小程序开发文档

2026-02-09 08:02:54 +08:00

16 KiB

Raw Blame History

学业邑规划 - 小程序 API 文档

本文档定义了小程序端调用的所有后端接口。

一、接口规范

1.1 基础信息

项目	说明
基础地址	开发环境：`http://localhost:5000` 生产环境：`https://api.example.com`
请求方式	GET / POST
数据格式	JSON
认证方式	Bearer Token

1.2 请求头

Content-Type: application/json
Authorization: Bearer {token}

1.3 响应格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

1.4 错误码

错误码	说明
0	成功
1001	参数错误
1002	未登录
1003	登录已过期
1004	无权限
2001	业务错误
5000	系统错误

二、用户模块

2.1 微信登录

接口：POST /api/user/login

描述：微信小程序登录

请求参数：

interface LoginRequest {
  /** 微信 code */
  code: string
  /** 加密手机号数据 */
  encryptedData: string
  /** 加密向量 */
  iv: string
  /** 邀请人ID（可选） */
  inviteUserId?: number
}

响应数据：

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

描述：获取当前登录用户信息

响应数据：

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

描述：更新用户昵称

请求参数：

interface UpdateProfileRequest {
  nickname: string
}

响应数据：boolean

2.4 更新头像

接口：POST /api/user/updateAvatar

描述：更新用户头像

请求参数：

interface UpdateAvatarRequest {
  /** 头像文件（Base64 或 URL） */
  avatar: string
}

响应数据：

interface UpdateAvatarResponse {
  /** 新头像 URL */
  avatarUrl: string
}

三、首页模块

3.1 获取 Banner 列表

接口：GET /api/home/getBannerList

描述：获取首页轮播图列表

响应数据：

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

描述：获取测评类型列表

响应数据：

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

描述：获取首页底部宣传图

响应数据：

interface PromotionItem {
  id: number
  title: string
  imageUrl: string
}

type Response = PromotionItem[]

四、团队模块

4.1 获取团队介绍

接口：GET /api/team/getInfo

描述：获取团队介绍图片

响应数据：

interface TeamInfo {
  images: string[]  // 图片列表
}

五、测评模块

5.1 获取测评介绍

接口：GET /api/assessment/getIntro

描述：获取测评介绍内容（基本信息页顶部）

请求参数：

参数	类型	必填	说明
typeId	number	是	测评类型ID

响应数据：

interface AssessmentIntro {
  /** 介绍内容（富文本或图片URL） */
  content: string
  /** 内容类型：text / image */
  contentType: string
  /** 测评价格 */
  price: number
}

5.2 获取题目列表

接口：GET /api/assessment/getQuestionList

描述：获取测评题目列表

请求参数：

参数	类型	必填	说明
typeId	number	是	测评类型ID

响应数据：

interface Question {
  id: number
  questionNo: number
  content: string
}

type Response = Question[]

5.3 提交测评答案

接口：POST /api/assessment/submitAnswers

描述：提交测评答案

请求参数：

interface SubmitAnswersRequest {
  /** 测评记录ID */
  recordId: number
  /** 答案列表 */
  answers: {
    questionId: number
    answerValue: number  // 1-10
  }[]
}

响应数据：

interface SubmitAnswersResponse {
  /** 是否提交成功 */
  success: boolean
  /** 报告预计生成时间（秒） */
  estimatedTime: number
}

5.4 查询报告生成状态

接口：GET /api/assessment/getResultStatus

描述：查询测评报告生成状态

请求参数：

参数	类型	必填	说明
recordId	number	是	测评记录ID

响应数据：

interface ResultStatus {
  /** 状态：1待测评 2测评中 3生成中 4已完成 */
  status: number
  /** 是否完成 */
  isCompleted: boolean
}

5.5 获取测评结果

接口：GET /api/assessment/getResult

描述：获取测评报告详情

请求参数：

参数	类型	必填	说明
recordId	number	是	测评记录ID

响应数据：

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

描述：验证测评邀请码

请求参数：

interface VerifyInviteCodeRequest {
  /** 邀请码（5位大写字母） */
  code: string
}

响应数据：

interface VerifyInviteCodeResponse {
  /** 是否有效 */
  isValid: boolean
  /** 错误信息（无效时） */
  errorMessage?: string  // "邀请码有误" / "邀请码已被使用"
  /** 邀请码ID（有效时） */
  inviteCodeId?: number
}

5.7 获取往期测评列表

接口：GET /api/assessment/getHistoryList

描述：获取用户的往期测评记录

请求参数：

参数	类型	必填	说明
page	number	否	页码，默认1
pageSize	number	否	每页数量，默认20

响应数据：

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学业规划

响应数据：

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

响应数据：

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

描述：创建订单

请求参数：

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
}

响应数据：

interface CreateOrderResponse {
  /** 订单ID */
  orderId: number
  /** 订单编号 */
  orderNo: string
  /** 支付金额 */
  payAmount: number
  /** 是否需要支付（使用邀请码时为 false） */
  needPay: boolean
  /** 测评记录ID（测评订单） */
  assessmentRecordId?: number
}

6.4 发起支付

接口：POST /api/order/pay

描述：发起微信支付

请求参数：

interface PayRequest {
  /** 订单ID */
  orderId: number
}

响应数据：

interface PayResponse {
  /** 微信支付参数 */
  timeStamp: string
  nonceStr: string
  package: string
  signType: string
  paySign: string
}

6.5 查询支付结果

接口：GET /api/order/getPayResult

描述：查询订单支付结果

请求参数：

参数	类型	必填	说明
orderId	number	是	订单ID

响应数据：

interface PayResult {
  /** 是否支付成功 */
  isPaid: boolean
  /** 订单状态 */
  status: number
  /** 测评记录ID（测评订单） */
  assessmentRecordId?: number
}

七、学业规划模块

7.1 获取规划师列表

接口：GET /api/planner/getList

描述：获取规划师列表

响应数据：

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

描述：获取邀请页面信息

响应数据：

interface InviteInfo {
  /** 邀请链接 */
  inviteUrl: string
  /** 邀请码 */
  inviteCode: string
  /** 已提现金额 */
  withdrawnAmount: number
  /** 待提现金额 */
  pendingAmount: number
  /** 邀请人数 */
  inviteCount: number
}

8.2 生成邀请二维码

接口：GET /api/invite/getQrcode

描述：生成邀请二维码图片

响应数据：

interface QrcodeResponse {
  /** 二维码图片 URL */
  qrcodeUrl: string
}

8.3 获取邀请记录

接口：GET /api/invite/getRecordList

描述：获取邀请记录列表

请求参数：

参数	类型	必填	说明
page	number	否	页码
pageSize	number	否	每页数量

响应数据：

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

描述：获取佣金详情

响应数据：

interface CommissionInfo {
  /** 累计收益 */
  totalIncome: number
  /** 已提现 */
  withdrawnAmount: number
  /** 待提现 */
  pendingAmount: number
}

8.5 申请提现

接口：POST /api/invite/applyWithdraw

描述：申请提现

请求参数：

interface ApplyWithdrawRequest {
  /** 提现金额（整数，最低1元） */
  amount: number
}

响应数据：

interface ApplyWithdrawResponse {
  /** 是否成功 */
  success: boolean
  /** 错误信息 */
  errorMessage?: string  // "超出待提现金额"
  /** 提现单号 */
  withdrawalNo?: string
}

8.6 获取提现记录

接口：GET /api/invite/getWithdrawList

描述：获取提现记录列表

请求参数：

参数	类型	必填	说明
page	number	否	页码
pageSize	number	否	每页数量

响应数据：

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

描述：获取用户协议内容

响应数据：

interface AgreementResponse {
  /** 协议内容（富文本） */
  content: string
}

9.2 获取隐私政策

接口：GET /api/system/getPrivacy

描述：获取隐私政策内容

响应数据：

interface PrivacyResponse {
  /** 政策内容（富文本） */
  content: string
}

9.3 获取关于我们

接口：GET /api/system/getAbout

描述：获取关于我们内容

响应数据：

interface AboutResponse {
  /** 内容（富文本） */
  content: string
  /** 版本号 */
  version: string
}

16 KiB Raw Blame History Unescape Escape

学业邑规划 - 小程序 API 文档

一、接口规范

1.1 基础信息

1.2 请求头

1.3 响应格式

1.4 错误码

二、用户模块

2.1 微信登录

2.2 获取用户信息

2.3 更新用户信息

2.4 更新头像

三、首页模块

3.1 获取 Banner 列表

3.2 获取测评入口列表

3.3 获取宣传图列表

四、团队模块

4.1 获取团队介绍

五、测评模块

5.1 获取测评介绍

5.2 获取题目列表

5.3 提交测评答案

5.4 查询报告生成状态

5.5 获取测评结果

5.6 验证邀请码

5.7 获取往期测评列表

六、订单模块

6.1 获取订单列表

6.2 获取订单详情

6.3 创建订单

6.4 发起支付

6.5 查询支付结果

七、学业规划模块

7.1 获取规划师列表

7.2 预约规划

八、分销模块

8.1 获取邀请信息

8.2 生成邀请二维码

8.3 获取邀请记录

8.4 获取佣金信息

8.5 申请提现

8.6 获取提现记录

九、系统模块

9.1 获取用户协议

9.2 获取隐私政策

9.3 获取关于我们

16 KiB

Raw Blame History