zhijiayun-pharmacy/docs/小程序/前端对接变更说明-小程序API.md

小程序后端 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）：

{
  "tempToken": "eyJ...",
  "inviteCode": "PX8K2M",
  "pharmacyName": "康宁大药房",
  "province": "广东省",
  "city": "广州市",
  "district": "天河区"
}

响应：

{
  "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）：

{
  "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

场景：首页统计卡片。

响应：

{
  "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（分页）：

{
  "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（桌面端调用）

{
  "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	手动采购台账，下一版本