# 小程序后端 API — 前端对接变更说明

> 日期：2026-07-06
> 原则：新增端点，不动老的。PC/Web 端不受影响。

---

## 1. 路径映射表（设计文档 → 实际后端）

| 设计文档路径 | 实际后端路径 | 说明 |
|-------------|-------------|------|
| `POST /auth/mp/login` | `POST /api/auth/wechat/miniapp/login` | 已实现，body 用 `jsCode` 替代 `code` |
| `POST /auth/register` | `POST /api/auth/register` | **新增**，独立注册接口 |
| `POST /auth/refresh` | `POST /api/auth/refresh` | 已有，不变 |
| `POST /auth/logout` | `POST /api/auth/logout` | **新增** |
| `GET /users/me` | `GET /api/auth/user/me` | **新增**（聚合 user+gate+quota+platforms） |
| `GET /users/me/dashboard` | `GET /api/auth/user/dashboard` | **新增** |
| `GET /licenses/current` | `GET /api/business-license/info` | 已有，响应字段见下方对比 |
| `POST /licenses/upload` | `POST /api/business-license/upload-file` | 已有，multipart |
| `GET /platform-bindings` | `GET /api/platform-accounts` | 已有 |
| `POST /platform-bindings` | `POST /api/platform-accounts` | 已有 |
| `DELETE /platform-bindings/{id}` | `DELETE /api/platform-account/unbind/{platformCode}` | 已有，路径不同 |
| `GET /queries` | `GET /api/search/records` | 已有 |
| `GET /queries/{id}` | `GET /api/search/records/{id}` | 已有 |
| `GET /membership/plans` | `GET /api/payment/plans` | 已有（公开） |
| `POST /membership/orders` | `POST /api/payment/orders` | 已有 |
| `GET /membership/orders/{no}` | `GET /api/payment/orders/{no}` | 已有 |
| `POST /coupons/redeem` | `POST /api/coupons/redeem` | 已有 |
| `GET /invites/stats` | `GET /api/invite/stats` | 已有 |
| `GET /purchase-intents` | `GET /api/purchase-intents` | **新增** |
| `GET /purchase-intents/{id}` | `GET /api/purchase-intents/{id}` | **新增** |
| `POST /purchase-intents` | `POST /api/purchase-intents` | **新增**（桌面端写） |
| `GET /content/help` | `GET /api/content/help` | **新增**（公开） |
| `GET /content/download` | `GET /api/content/download` | **新增**（公开） |

---

## 2. 新增接口详情

### 2.1 独立注册 — `POST /api/auth/register`

**场景**：微信登录后 `isRegistered=false`，跳转注册页填写信息。

请求（需认证，带 tempToken）：
```json
{
  "tempToken": "eyJ...",
  "inviteCode": "PX8K2M",
  "pharmacyName": "康宁大药房",
  "province": "广东省",
  "city": "广州市",
  "district": "天河区"
}
```

响应：
```json
{
  "code": 200,
  "data": {
    "userId": "123456",
    "accessToken": "eyJ...",
    "refreshToken": "rf_...",
    "expiresIn": 3600,
    "userInfo": { /* UserInfoResponse */ }
  }
}
```

### 2.2 聚合用户信息 — `GET /api/auth/user/me`

**场景**：我的页面，一次拿到用户信息 + 门禁 + 配额 + 平台绑定。

> 旧接口 `GET /api/auth/user/info` **保持不变**。

响应新增字段（相比 `/info`）：
```json
{
  "code": 200,
  "data": {
    /* ...原有 UserInfoResponse 字段... */
    "gate": {
      "canQueryOnDesktop": false,
      "licenseStatus": "PENDING",
      "platformBoundCount": 2,
      "gateMessages": ["请先上传营业执照", "请至少绑定1个B2B平台"]
    },
    "quota": {
      "dailyQueryUsed": 8,
      "dailyQueryLimit": 20,
      "watchlistUsed": 5,
      "watchlistLimit": 30
    },
    "platformBindings": [
      {
        "platformCode": "yaobangmang",
        "platformName": "药帮忙",
        "status": "bound",
        "lastVerifyTime": "2026-06-27T10:00:00"
      }
    ]
  }
}
```

### 2.3 首页概览 — `GET /api/auth/user/dashboard`

**场景**：首页统计卡片。

响应：
```json
{
  "code": 200,
  "data": {
    "todayQueryCount": 8,
    "todayPurchaseIntentCount": 0,
    "totalQueryCount": 156,
    "recentQueries": [
      { "drugName": "阿莫西林胶囊", "searchedAt": "...", "lowestPrice": 8.50 }
    ]
  }
}
```

### 2.4 登出 — `POST /api/auth/logout`

**场景**：清除服务端 refresh token，小程序端清除本地 token。

请求：无需 body（通过 Authorization header 认证）。

响应：`{"code": 200, "message": "操作成功"}`

### 2.5 解绑平台 — `DELETE /api/platform-accounts/{platformCode}`

**场景**：平台管理页面删除已绑定的平台。

响应：`{"code": 200, "message": "操作成功"}`

---

## 3. 请求体字段差异

| 端 | 字段 | 说明 |
|----|------|------|
| 小程序登录 | `jsCode` | 对应 `wx.login()` 返回值 |
| 设计文档 | `code` | 文档用名，实际用 `jsCode` |

---

## 4. PC/Web 端影响

**无影响。** 所有新增端点均为独立的 Controller 方法，不修改已有的：

- `GET /api/auth/user/info` — 保持不变
- `POST /api/auth/sms/login` — 保持不变
- `POST /api/auth/password/login` — 保持不变
- `POST /api/auth/wechat/login` — 保持不变
- `POST /api/auth/refresh` — 保持不变
- `POST /api/auth/heartbeat` — 保持不变

---

## 5. 新增接口详情（续）

### 5.1 跳转购买记录列表 — `GET /api/purchase-intents`

查询参数：`page=1&pageSize=20`

响应 `data`（分页）：
```json
{
  "records": [
    {
      "id": "123456",
      "queryId": "789",
      "drugName": "阿莫西林胶囊",
      "spec": "0.25g×24粒",
      "manufacturer": "石药集团",
      "platformCode": "yaobangmang",
      "platformName": "药帮忙",
      "referencePrice": 8.50,
      "sourceClient": "WINDOWS",
      "clickedAt": "2026-06-27T14:35:00"
    }
  ],
  "total": 10,
  "current": 1,
  "size": 20
}
```

### 5.2 跳转购买详情 — `GET /api/purchase-intents/{id}`

返回单条记录（同上结构）。

### 5.3 写入跳转记录 — `POST /api/purchase-intents`（桌面端调用）

```json
{
  "queryId": "789",
  "drugName": "阿莫西林胶囊",
  "spec": "0.25g×24粒",
  "manufacturer": "石药集团",
  "platformCode": "yaobangmang",
  "platformName": "药帮忙",
  "referencePrice": 8.50,
  "externalUrl": "https://...",
  "sourceClient": "WINDOWS"
}
```

### 5.4 帮助 FAQ — `GET /api/content/help`（公开）

### 5.5 桌面下载链接 — `GET /api/content/download`（公开）

---

## 6. 待实现（V1.1）

| 接口 | 优先级 | 说明 |
|------|--------|------|
| `GET /licenses/current/image-url` | P1 | 已可通过 upload 返回值获取 |
| `POST /platform-bindings/{id}/validate` | P1 | 平台验证逻辑复杂 |
| `/procurement-ledgers/*` | V1.1 | 手动采购台账，下一版本 |