# 学业邑规划 - 小程序 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
}
```