智价云药店 - 接口文档

⚠️ MVP 阶段说明
本项目为全新项目，尚未上线，当前处于 MVP（最小可行产品）阶段。
本文档描述的是 MVP 版本的接口定义，后续会根据业务需求持续迭代。

版本：v1.0-MVP | 更新日期：2026-06-16 | 状态：开发中
Base URL: http://localhost:8080

通用说明

请求头

Header	说明
Content-Type	application/json
Authorization	Bearer {accessToken}（需认证接口）

统一响应格式

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

错误码

code	说明
200	成功
400	参数错误
401	未认证
403	无权限
404	资源不存在
429	请求过于频繁
500	服务器内部错误

分页响应格式

所有列表查询接口使用统一的分页响应格式：

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "size": 20,
    "records": [
      {...}
    ]
  }
}

字段	类型	说明
total	Integer	总记录数
page	Integer	当前页码（从1开始）
size	Integer	每页数量
records	Array	当前页的数据列表

常见错误响应示例

参数错误：

{
  "code": 400,
  "message": "手机号格式不正确",
  "data": null
}

配额不足：

{
  "code": 400,
  "message": "每日配额已用完，请升级会员或等待明天",
  "data": null
}

资源不存在：

{
  "code": 404,
  "message": "未找到该平台的绑定记录",
  "data": null
}

未认证：

{
  "code": 401,
  "message": "Token已过期，请重新登录",
  "data": null
}

无权限：

{
  "code": 403,
  "message": "需要管理员权限",
  "data": null
}

1. 认证模块 /api/auth

1.1 发送验证码

POST /api/auth/sms/send

请求体：

{
  "phone": "13800138000"
}

响应：

{ "code": 200, "message": "success", "data": null }

1.2 验证码登录/注册

POST /api/auth/sms/login

请求体：

{
  "phone": "13800138000",
  "code": "123456",
  "inviteCode": "ABC123"  // 可选，邀请码
}

响应：

{
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "userId": 1,
    "nickname": "用户138****0000",
    "avatar": null,
    "phone": "13800138000",
    "newUser": false
  }
}

1.3 获取微信扫码登录URL

GET /api/auth/wechat/url?state=login

响应：

{
  "code": 200,
  "data": "https://open.weixin.qq.com/connect/qrconnect?appid=xxx&redirect_uri=xxx"
}

1.4 微信扫码登录

POST /api/auth/wechat/login

请求体：

{
  "code": "wx_auth_code_xxx",
  "state": "login"
}

响应： 同 1.2

1.5 微信绑定手机号

POST /api/auth/wechat/bind

请求体：

{
  "wechatCode": "wx_auth_code_xxx",
  "phone": "13800138000",
  "smsCode": "123456",
  "inviteCode": "ABC123"  // 可选
}

响应： 同 1.2

1.6 微信登录回调

GET /api/auth/wechat/callback?code=xxx&state=xxx

响应：

{ "code": 200, "data": "https://your-domain.com/wechat-login?code=xxx" }

1.7 刷新Token

POST /api/auth/refresh

请求体： refreshToken字符串

响应： 同 1.2

1.8 获取当前用户信息

GET /api/auth/user/info

需要认证

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "userId": 1,
    "phone": "13800138000",
    "nickname": "用户138****0000",
    "avatar": null,
    "levelName": "普通用户",
    "levelCode": "NORMAL",
    "pharmacyName": "XX大药房",
    "loginSource": "WINDOWS",
    "lastLoginDevice": "Windows 10 - WebView2",
    "configVersionId": 1,
    "version": "v1.0"
  }
}

字段说明：

pharmacyName: 药店名称（可选）
loginSource: 登录来源（WINDOWS/MINIAPP/ANDROID/IOS/WECHAT）
lastLoginDevice: 最后登录设备信息
configVersionId: 当前使用的等级配置版本ID
version: 当前使用的等级配置版本号

2. 爬虫配额 /api/crawler

2.1 获取爬虫权益状态

GET /api/crawler/status

需要认证

响应：

{
  "code": 200,
  "data": {
    "dailyLimit": 5,
    "dailyUsed": 2,
    "dailyRemaining": 3,
    "monthlyLimit": 100,
    "monthlyUsed": 30,
    "monthlyRemaining": 70,
    "maxConcurrent": 1,
    "baseDailyQuota": 5,
    "baseMonthlyQuota": 100,
    "extraQuotaBreakdown": [
      {
        "sourceType": "INVITE",
        "sourceName": "邀请奖励",
        "available": 10,
        "total": 15,
        "used": 5
      }
    ]
  }
}

2.2 消耗爬虫次数

POST /api/crawler/consume

需要认证

业务场景： 药店采购人员搜索药品后，选择多个医药B2B平台进行比价，系统爬取各平台价格并生成采购链接。

请求体：

{
  "count": 1,
  "useCouponFirst": false,
  "platform": "yaoshibang"
}

字段	类型	必填	说明
count	Integer	是	消耗次数（至少为1）
useCouponFirst	Boolean	否	是否优先使用优惠券，默认false
platform	String	否	爬取平台代码（见下方平台列表）

支持的医药平台列表：

✅ MVP启用的3个核心平台：

yaoshibang - 药师帮（国内领先医药B2B平台）
yaobangmang - 药帮忙（医药B2B采购平台）
yiyaocheng - 1药城（B2B医药批发平台）

🚀 后续扩展平台（Phase 2-6）：

B2B批发平台（12个）：

yaojingcai - 药京采、jianzhijia - 健之佳、kangaiduoduo - 康爱多
alihealth - 阿里健康、sinopharm - 国药控股、jointown - 九州通
zhencheng - 珍诚医药、yaoyitong - 药易通、hezong - 合纵药易购
yicaotang - 宜草堂、yaodu - 药都在线、yaocaiying - 药材盈

B2C零售平台（8个）：

dingdang - 叮当快药、quanyuantang - 泉源堂、dashenlin - 大参林
laobaixing - 老百姓大药房、yixintang - 一心堂、yifeng - 益丰大药房
haiwang - 海王星辰、guoda - 国大药房

综合电商医药频道（7个）：

jd_health - 京东健康、tmall_pharma - 天猫医药、pdd_pharma - 拼多多医药
douyin_pharma - 抖音医药、kuaishou_pharma - 快手医药
meituan_pharma - 美团买药、eleme_pharma - 饿了么医药

垂直医药平台（4个）：

weyi - 微医、pingan_good - 平安好医生
chunyu - 春雨医生、haodf - 好大夫在线

其他：

other - 其他平台

说明：MVP阶段仅启用前3个B2B平台，其他平台将在后续版本中逐步开放。

响应：

{ "code": 200, "data": true }

支持的医药平台列表（34个全渠道）：

B2B批发平台（15个 - 药店主要采购渠道）：

yaoshibang - 药师帮（国内最大医药B2B平台）
yaojingcai - 药京采（京东健康旗下医药B2B）
jianzhijia - 健之佳（云南健之佳医药B2B）
1yao - 1药网（B2B医药批发平台）
kangaiduoduo - 康爱多（医药电商B2B）
alihealth - 阿里健康（天猫医药馆B2B）
sinopharm - 国药控股（国药集团B2B平台）
jointown - 九州通（九州通医药B2B）
zhencheng - 珍诚医药（浙江地区知名医药B2B）
yaoyitong - 药易通（西南地区医药B2B平台）
hezong - 合纵药易购（四川地区医药B2B）
yicaotang - 宜草堂（华中地区医药B2B）
yaodu - 药都在线（安徽亳州药材市场B2B）
yaocaiying - 药材盈（中药材B2B交易平台）

B2C零售平台（8个 - 小批量采购/急单）：

dingdang - 叮当快药（O2O即时配送，适合急单）
quanyuantang - 泉源堂（连锁药店B2C平台）
dashenlin - 大参林（广东连锁药店B2C）
laobaixing - 老百姓大药房（全国连锁B2C）
yixintang - 一心堂（云南连锁药店B2C）
yifeng - 益丰大药房（华中连锁药店B2C）
haiwang - 海王星辰（全国连锁药店B2C）
guoda - 国大药房（国药旗下连锁药店B2C）

综合电商医药频道（7个 - 价格参考）：

jd_health - 京东健康
tmall_pharma - 天猫医药
pdd_pharma - 拼多多医药
douyin_pharma - 抖音医药
kuaishou_pharma - 快手医药
meituan_pharma - 美团买药
eleme_pharma - 饿了么医药

垂直医药平台（4个 - 特色渠道）：

weyi - 微医（互联网医院+药品销售）
pingan_good - 平安好医生（平安集团医疗健康平台）
chunyu - 春雨医生（在线问诊+药品销售）
haodf - 好大夫在线（医疗服务平台）
other - 其他平台

2.3 获取爬虫使用记录

GET /api/crawler/logs?days=7

需要认证

参数	类型	默认值	说明
days	int	7	查询最近N天

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "userId": 1,
      "usageDate": "2026-06-16",
      "usageCount": 3,
      "platform": "yaoshibang",
      "source": "QUOTA",
      "remark": null,
      "createTime": "2026-06-16T10:30:00"
    }
  ]
}

字段说明：

platform: 爬取平台（yaoshibang/yaojingcai/jianzhijia等医药B2B平台）
source: 消耗来源（QUOTA-配额、COUPON-优惠券、MIXED-混合）
remark: 备注信息

业务价值：

📊 统计各平台爬取频次，优化采购策略
💰 分析哪些平台价格更有优势
🔍 追溯历史比价记录

3. 邀请系统 /api/invite

3.1 获取我的邀请码

GET /api/invite/code

需要认证

响应：

{
  "code": 200,
  "data": {
    "code": "ABC123",
    "inviteLink": "https://app.zhijiayun.com/invite/ABC123",
    "maxUses": -1,
    "usedCount": 5,
    "clickCount": 12,
    "expireTime": "2026-07-16T00:00:00",
    "status": 1,
    "createTime": "2026-06-16T10:00:00",
    
    // 分享相关字段
    "shareTitle": "邀请你加入智价云药店",
    "shareDescription": "高效商品数据采集工具",
    "copyText": "邀请你加入智价云药店\n高效商品数据采集工具\n邀请码：ABC123\n点击链接下载：\nhttps://app.zhijiayun.com/invite/ABC123",
    "rewardDescription": "注册即送5次爬虫额度"
  }
}

字段说明：

copyText: 一键复制文本，包含标题、描述、邀请码和链接，用户可直接复制到微信分享
shareTitle: 微信分享时的标题
shareDescription: 微信分享时的描述
rewardDescription: 奖励说明，用于展示给被邀请人

3.2 获取邀请统计

GET /api/invite/stats

需要认证

响应：

{
  "code": 200,
  "data": {
    "invitedCount": 5,
    "registeredCount": 3,
    "clickedCount": 12,
    "totalRewardQuota": 21,
    "summaryText": "已邀请5人，3人注册 +21次",
    "inviteLink": "https://your-domain.com/invite/ABC123"
  }
}

3.3 获取邀请记录

GET /api/invite/rewards

需要认证

响应：

{
  "code": 200,
  "data": [
    {
      "inviteeId": 2,
      "inviteeNickname": "用户139****1111",
      "rewardQuota": 5,
      "registered": true,
      "registeredText": "已注册",
      "createTime": "2026-06-10T10:00:00"
    }
  ]
}

3.4 获取额外爬虫次数

GET /api/invite/extra-quota

需要认证

响应：

{ "code": 200, "data": 15 }

3.5 邀请落地页（公开）

GET /api/invite/page/{code}?channel=app

无需认证

参数	类型	必填	说明
code	String	是	邀请码
channel	String	否	渠道：app/wechat/miniapp/dingtalk/feishu，默认app

响应：

{
  "code": 200,
  "data": {
    "inviterNickname": "用户138****0000",
    "inviterAvatar": "https://...",
    "inviteCode": "ABC123",
    "downloadUrl": "https://download.example.com/app.exe",
    "landingTitle": "邀请你加入智价云药店",
    "landingDesc": "高效商品数据采集工具",
    "appName": "智价云药店",
    "channel": "app",
    "openType": "download",
    "miniappPath": null,
    "miniappId": null,
    "wechatRedirectUrl": null,
    "rewardPerRegister": 5,
    
    // 客户端自动填入支持
    "autoFillSupported": true,
    "urlScheme": "zhijiayun://invite?code=ABC123",
    "deepLink": "https://app.zhijiayun.com/invite/ABC123?autoFill=true",
    "instructionText": "下载安装后，在注册页面输入邀请码：智价云药店 或点击链接自动填入"
  }
}

字段说明：

urlScheme: URL Scheme，用于唤醒已安装的客户端并自动填入邀请码（如 zhijiayun://invite?code=ABC123）
deepLink: 通用深度链接，iOS/Android都支持
instructionText: 操作提示文案，根据渠道动态生成
autoFillSupported: 是否支持自动填入（始终为true）

使用场景：

用户B点击邀请链接后访问此接口
前端展示邀请人信息和下载按钮
点击"打开APP"按钮时，尝试通过 urlScheme 唤醒客户端
如果未安装，引导用户下载，下载后打开时可通过 DeepLink 自动填入邀请码

3.6 追踪邀请链接点击（公开）

POST /api/invite/click/{code}

无需认证

响应：

{ "code": 200, "data": null }

4. 优惠券 /api/coupon

4.1 发放优惠券（管理）

POST /api/coupon/issue

请求体：

{
  "couponId": 1,
  "userIds": [1, 2, 3],
  "validDays": 30
}

响应：

{ "code": 200, "data": 3 }

4.2 获取我的优惠券

GET /api/coupon/my?status=0

需要认证

参数	类型	说明
status	Integer	可选，0-未使用 1-已使用 2-已过期

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "couponName": "爬虫次数+10",
      "type": "CRAWLER",
      "value": 10,
      "status": 0,
      "expireTime": "2026-07-16T00:00:00",
      "source": "ISSUE"
    }
  ]
}

4.3 获取可用优惠券

GET /api/coupon/my/available?type=CRAWLER

需要认证

5. 用户等级 /api/level

5.1 获取等级列表（公开）

GET /api/level/list

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "levelName": "普通用户",
      "levelCode": "NORMAL",
      "crawlerQuota": 5,
      "monthlyQuota": 100,
      "maxConcurrent": 1,
      "description": "每日5次爬虫，每月100次"
    }
  ]
}

5.2 获取等级详情（公开）

GET /api/level/{id}

5.3 获取当前用户等级

GET /api/level/my

需要认证

5.4 设置用户等级（管理）

PUT /api/level/user/{userId}?levelId=2

6. 运营管理 /api/admin

6.1 获取邀请配置

GET /api/admin/invite/config

6.2 更新邀请配置

PUT /api/admin/invite/config

请求体：

{
  "rewardCrawlerCount": 5,
  "maxDailyReward": 50,
  "inviteCodeExpireDays": 30,
  "maxInvitePerDay": 10,
  "appDownloadUrl": "https://download.example.com/app.exe",
  "miniappPath": "/pages/download/index",
  "miniappId": "wx1234567890",
  "wechatRedirectUrl": "https://mp.weixin.qq.com/xxx",
  "dingtalkAppId": "dingxxx",
  "feishuAppId": "feishuxxx",
  "landingTitle": "邀请你加入智价云药店",
  "landingDesc": "高效商品数据采集工具",
  "appName": "智价云药店"
}

6.3 获取所有邀请配置

GET /api/admin/invite/configs

6.4 手动发放爬虫次数

POST /api/admin/crawler/grant

请求体：

{
  "userId": 1,
  "quotaCount": 50,
  "expireDays": 30,
  "remark": "VIP升级奖励"
}

6.5 查看发放记录

GET /api/admin/crawler/grants?userId=1&grantType=ADMIN

参数	类型	必填	说明
userId	Long	否	指定用户
grantType	String	否	INVITE/PURCHASE/ADMIN

6.6 查看邀请记录

GET /api/admin/invite/rewards?userId=1

6.7 查看用户爬虫详情（含平台分布）

GET /api/admin/crawler/user-detail?userId=1

需要认证

响应：

{
  "code": 200,
  "data": {
    "userId": 1,
    "nickname": "测试药店",
    "phone": "138****8000",
    "todayTotalUsage": 5,
    "monthlyTotalUsage": 30,
    "platformStats": [
      {
        "platformCode": "yaoshibang",
        "platformName": "药师帮",
        "todayUsage": 3,
        "monthlyUsage": 15,
        "totalUsage": 50
      },
      {
        "platformCode": "yaojingcai",
        "platformName": "药京采",
        "todayUsage": 2,
        "monthlyUsage": 10,
        "totalUsage": 30
      }
    ]
  }
}

支持的医药平台（34个全渠道）：

B2B批发平台： yaoshibang, yaojingcai, jianzhijia, 1yao, kangaiduoduo, alihealth, sinopharm, jointown, zhencheng, yaoyitong, hezong, yicaotang, yaodu, yaocaiying

B2C零售平台： dingdang, quanyuantang, dashenlin, laobaixing, yixintang, yifeng, haiwang, guoda

综合电商医药频道： jd_health, tmall_pharma, pdd_pharma, douyin_pharma, kuaishou_pharma, meituan_pharma, eleme_pharma

垂直医药平台： weyi, pingan_good, chunyu, haodf

other - 其他

业务价值：

📊 分析药店采购偏好，优化推荐策略
💡 识别高频使用平台，针对性谈判合作
🔍 监控异常使用行为（如单一平台过度依赖）

6.8 查看用户邀请转化统计

GET /api/admin/invite/conversion-stats?userId=1

需要认证

响应：

{
  "code": 200,
  "data": {
    "inviteCode": "ABC123",
    "clickedCount": 50,
    "totalInvited": 10,
    "registeredCount": 8,
    "pendingCount": 2,
    "conversionRate": 16.0,
    "totalReward": 40
  }
}

字段说明：

clickedCount: 邀请链接被打开次数
totalInvited: 总邀请人数（点击后访问落地页的人数）
registeredCount: 已注册人数
pendingCount: 待注册人数（点击但未注册）
conversionRate: 注册转化率（百分比，计算公式：已注册人数 / 点击次数 × 100%）
totalReward: 累计奖励爬虫次数

7. B2B平台账号绑定模块 /api/platform-account

7.1 绑定B2B平台账号

POST /api/platform-account/bind

需要认证

请求体：

{
  "platformCode": "yaoshibang",
  "platformName": "药师帮",
  "account": "13800138000",
  "password": "your_password"
}

字段	类型	必填	说明
platformCode	String	是	平台代码（yaoshibang/yaobangmang/yiyaocheng）
platformName	String	是	平台名称
account	String	是	平台账号（手机号或用户名）
password	String	是	平台密码（服务端AES-256加密存储）

响应：

{ "code": 200, "message": "success", "data": null }

注意事项：

⚠️ 密码会在服务端使用AES-256-GCM加密存储，不会明文保存
如果该平台已绑定，则更新账号信息
绑定后验证状态为PENDING，需要调用验证接口验证账号有效性

说明：

密码会在服务端使用AES-256-GCM加密存储
如果该平台已绑定，则更新账号信息
绑定后验证状态为PENDING，需要调用验证接口

7.2 解绑B2B平台账号

DELETE /api/platform-account/unbind/{platformCode}

需要认证

路径参数：

platformCode: 平台代码（如：yaoshibang）

响应：

{ "code": 200, "message": "success", "data": null }

7.3 查询已绑定的平台账号列表

GET /api/platform-account/list

需要认证

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "platformCode": "yaoshibang",
      "platformName": "药师帮",
      "account": "138****8000",
      "enabled": true,
      "verifyStatus": "SUCCESS",
      "lastVerifyTime": "2026-06-16T10:30:00",
      "failReason": null,
      "createTime": "2026-06-15T09:00:00"
    }
  ]
}

字段说明：

account: 脱敏后的账号（前3位+****+后4位）
verifyStatus: PENDING-待验证 / SUCCESS-成功 / FAILED-失败

7.4 验证平台账号

POST /api/platform-account/verify/{platformCode}

需要认证

路径参数：

platformCode: 平台代码

响应：

{ "code": 200, "message": "success", "data": null }

说明：

调用对应B2B平台的登录接口验证账号密码
验证成功后才能用于爬虫查询

8. 营业执照模块 /api/business-license

8.1 上传营业执照

POST /api/business-license/upload

需要认证

请求体：

{
  "licenseImageUrl": "https://oss.example.com/license/xxx.jpg",
  "creditCode": "91110000XXXXXXXXXX",
  "pharmacyName": "XX大药房",
  "legalPerson": "张三"
}

字段	类型	必填	说明
licenseImageUrl	String	是	营业执照图片URL（需先上传到OSS）
creditCode	String	是	统一社会信用代码（18位）
pharmacyName	String	是	药店名称
legalPerson	String	否	法人姓名

响应：

{ "code": 200, "message": "success", "data": null }

注意事项：

营业执照为可选填写，不影响基本使用
审核通过后显示认证标识，提升用户信任度
图片需要先上传到OSS，获取URL后再调用此接口

8.2 查询营业执照信息

GET /api/business-license/info

需要认证

响应：

{
  "code": 200,
  "data": {
    "id": 1,
    "licenseImageUrl": "https://oss.example.com/license/xxx.jpg",
    "creditCode": "91110000XXXXXXXXXX",
    "pharmacyName": "XX大药房",
    "reviewStatus": "APPROVED",
    "reviewTime": "2026-06-16T10:00:00",
    "rejectReason": null,
    "showVerifiedBadge": true,
    "createTime": "2026-06-15T09:00:00"
  }
}

字段说明：

reviewStatus: PENDING-待审核 / APPROVED-已通过 / REJECTED-已驳回

9. 平台配置模块 /api/platform-config

9.1 查询所有启用的平台

GET /api/platform-config/enabled

响应：

{
  "code": 200,
  "data": [
    {
      "platformCode": "yaoshibang",
      "platformName": "药师帮",
      "enabled": true,
      "requiresRecharge": false,
      "queryCost": 1,
      "priority": 1,
      "underMaintenance": false,
      "bindingInstructions": "请输入您在药师帮平台的手机号和密码"
    }
  ]
}

9.2 查询指定平台配置

GET /api/platform-config/{platformCode}

路径参数：

platformCode: 平台代码

响应：

{
  "code": 200,
  "data": {
    "platformCode": "yaoshibang",
    "platformName": "药师帮",
    "enabled": true,
    "requiresRecharge": false,
    "queryCost": 1,
    "priority": 1,
    "underMaintenance": false,
    "maintenanceNotice": null,
    "bindingInstructions": "请输入您在药师帮平台的手机号和密码"
  }
}

10. 体验配额配置模块 /api/trial-quota

10.1 查询当前生效的体验配置

GET /api/trial-quota/active

响应：

{
  "code": 200,
  "data": {
    "configName": "新用户默认体验",
    "trialDays": 15,
    "dailyQueryLimit": 20,
    "monthlyWatchlistLimit": 199,
    "configType": "DEFAULT",
    "applicableUserType": "NEW_USER",
    "description": "新用户注册后自动获得的体验配额"
  }
}

10.2 查询所有体验配置（运营后台）

GET /api/admin/trial-quota/configs

需要管理员权限

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "configName": "新用户默认体验",
      "trialDays": 15,
      "dailyQueryLimit": 20,
      "monthlyWatchlistLimit": 199,
      "enabled": true,
      "configType": "DEFAULT",
      "currentUsers": 1250,
      "maxUsers": null
    }
  ]
}

10.3 创建体验配置（运营后台）

POST /api/admin/trial-quota/config

需要管理员权限

请求体：

{
  "configName": "春节活动体验券",
  "trialDays": 7,
  "dailyQueryLimit": 30,
  "monthlyWatchlistLimit": 300,
  "configType": "ACTIVITY",
  "applicableUserType": "ALL",
  "effectiveFrom": "2026-02-01T00:00:00",
  "effectiveTo": "2026-02-15T23:59:59",
  "maxUsers": 1000,
  "description": "春节期间特别活动"
}

响应：

{ "code": 200, "message": "success", "data": null }

10.4 更新体验配置（运营后台）

PUT /api/admin/trial-quota/config/{id}

需要管理员权限

请求体： 同创建接口

响应：

{ "code": 200, "message": "success", "data": null }

10.5 删除体验配置（运营后台）

DELETE /api/admin/trial-quota/config/{id}

需要管理员权限

响应：

{ "code": 200, "message": "success", "data": null }

11. 用户等级配置管理 /api/user-level-config

说明：支持运营动态调整等级规则，新用户自动使用最新版本，老用户由运营决定迁移到哪个版本

11.1 获取当前激活的等级版本

GET /api/user-level-config/current-version

响应：

{
  "code": 200,
  "data": {
    "id": 1,
    "version": "v1.0",
    "versionName": "MVP初始版本",
    "isCurrent": true,
    "status": "ACTIVE",
    "changeLog": "项目上线初始版本，包含3个等级：普通用户、VIP、SVIP",
    "userCount": 1250,
    "createTime": "2026-06-01T00:00:00"
  }
}

11.2 获取用户的等级信息（含版本）

GET /api/user-level-config/my-level

需要认证

响应：

{
  "code": 200,
  "data": {
    "userId": 1,
    "configVersionId": 1,
    "version": "v1.0",
    "versionName": "MVP初始版本",
    "levelDetailId": 1,
    "levelCode": "NORMAL",
    "levelName": "普通用户",
    "dailyQuota": 5,
    "monthlyQuota": 100,
    "maxConcurrent": 1,
    "monthlyWatchlistLimit": 50
  }
}

字段说明：

version: 用户当前使用的等级配置版本
levelCode: 等级编码（NORMAL/VIP/SVIP）
dailyQuota: 每日爬虫次数配额
monthlyQuota: 每月爬虫次数配额

11.3 查询所有等级版本（运营后台）

GET /api/admin/user-level-config/versions

需要管理员权限

响应：

{
  "code": 200,
  "data": [
    {
      "id": 2,
      "version": "v2.0",
      "versionName": "2026春节版",
      "isCurrent": false,
      "status": "ACTIVE",
      "effectiveFrom": "2026-02-01T00:00:00",
      "effectiveTo": null,
      "changeLog": "春节期间提升VIP和SVIP配额，吸引用户升级",
      "userCount": 350,
      "activatedBy": 100,
      "activatedAt": "2026-01-25T10:00:00",
      "createTime": "2026-01-20T09:00:00"
    },
    {
      "id": 1,
      "version": "v1.0",
      "versionName": "MVP初始版本",
      "isCurrent": true,
      "status": "ACTIVE",
      "changeLog": "项目上线初始版本",
      "userCount": 1250,
      "activatedBy": 100,
      "activatedAt": "2026-06-01T00:00:00",
      "createTime": "2026-06-01T00:00:00"
    }
  ]
}

11.4 查询指定版本的等级明细

GET /api/admin/user-level-config/version/{versionId}/details

需要管理员权限

路径参数：

versionId: 版本ID

响应：

{
  "code": 200,
  "data": {
    "version": {
      "id": 1,
      "version": "v1.0",
      "versionName": "MVP初始版本",
      "isCurrent": true,
      "userCount": 1250
    },
    "levels": [
      {
        "id": 1,
        "levelName": "普通用户",
        "levelCode": "NORMAL",
        "levelWeight": 1,
        "dailyQuota": 5,
        "monthlyQuota": 100,
        "maxConcurrent": 1,
        "monthlyWatchlistLimit": 50,
        "description": "小型药店试用"
      },
      {
        "id": 2,
        "levelName": "VIP会员",
        "levelCode": "VIP",
        "levelWeight": 2,
        "dailyQuota": 20,
        "monthlyQuota": 500,
        "maxConcurrent": 3,
        "monthlyWatchlistLimit": 200,
        "description": "中型药店日常采购"
      },
      {
        "id": 3,
        "levelName": "SVIP会员",
        "levelCode": "SVIP",
        "levelWeight": 3,
        "dailyQuota": 100,
        "monthlyQuota": 3000,
        "maxConcurrent": 5,
        "monthlyWatchlistLimit": 500,
        "description": "大型连锁药店批量采购"
      }
    ]
  }
}

11.5 创建新的等级配置版本

POST /api/admin/user-level-config/version

需要管理员权限

请求体：

{
  "version": "v2.0",
  "versionName": "2026春节版",
  "changeLog": "春节期间提升VIP和SVIP配额，吸引用户升级",
  "levels": [
    {
      "levelName": "普通用户",
      "levelCode": "NORMAL",
      "levelWeight": 1,
      "dailyQuota": 5,
      "monthlyQuota": 100,
      "maxConcurrent": 1,
      "monthlyWatchlistLimit": 50,
      "description": "小型药店试用"
    },
    {
      "levelName": "VIP会员",
      "levelCode": "VIP",
      "levelWeight": 2,
      "dailyQuota": 30,
      "monthlyQuota": 800,
      "maxConcurrent": 3,
      "monthlyWatchlistLimit": 300,
      "description": "中型药店日常采购（春节特惠）"
    },
    {
      "levelName": "SVIP会员",
      "levelCode": "SVIP",
      "levelWeight": 3,
      "dailyQuota": 150,
      "monthlyQuota": 5000,
      "maxConcurrent": 5,
      "monthlyWatchlistLimit": 800,
      "description": "大型连锁药店批量采购（春节特惠）"
    }
  ]
}

字段	类型	必填	说明
version	String	是	版本号（如：v2.0，不能重复）
versionName	String	是	版本名称（如：2026春节版）
changeLog	String	是	变更说明（记录本次调整的原因和内容）
levels	Array	是	等级明细列表（至少包含1个等级）

levels数组元素字段：

字段	类型	必填	说明
levelName	String	是	等级名称
levelCode	String	是	等级编码（NORMAL/VIP/SVIP）
levelWeight	Integer	是	等级权重（越大越高）
dailyQuota	Integer	是	每日爬虫次数配额
monthlyQuota	Integer	是	每月爬虫次数配额
maxConcurrent	Integer	是	最大并发爬虫数
monthlyWatchlistLimit	Integer	否	每月关注品种数限制
description	String	否	等级描述

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 2,
    "version": "v2.0",
    "versionName": "2026春节版",
    "status": "DRAFT"
  }
}

注意事项：

⚠️ 敏感操作：创建新版本会影响后续新用户的等级配置
新创建的版本状态为DRAFT（草稿），需要手动激活
版本号不能重复
建议先在测试环境验证新版本的规则

11.6 激活等级配置版本

POST /api/admin/user-level-config/version/{versionId}/activate

需要管理员权限

路径参数：

versionId: 版本ID

响应：

{ "code": 200, "message": "success", "data": null }

说明：

激活后，该版本成为当前版本（is_current=true）
其他版本的is_current自动设为false
新用户注册时自动使用此版本
老用户不会自动迁移，需要运营手动或批量迁移

11.7 批量迁移用户到新版本 ⚠️

POST /api/admin/user-level-config/migrate-users

需要管理员权限

⚠️ 敏感操作：此操作会影响用户的等级配额，请谨慎操作

请求体：

{
  "targetVersionId": 2,
  "userIds": [1, 2, 3, 4, 5],
  "remark": "春节活动，将VIP用户迁移到v2.0版本享受更高配额"
}

响应：

{
  "code": 200,
  "data": {
    "totalCount": 5,
    "successCount": 5,
    "failedCount": 0,
    "failedUsers": []
  }
}

说明：

系统会根据用户当前的等级编码（如VIP），在目标版本中找到对应的等级
如果目标版本中不存在该等级编码，则该用户迁移失败
迁移成功后，用户的配额立即生效

11.8 手动调整单个用户等级

PUT /api/admin/user-level-config/user/{userId}/level

需要管理员权限

路径参数：

userId: 用户ID

请求体：

{
  "targetLevelCode": "VIP",
  "reason": "用户反馈良好，手动升级为VIP"
}

响应：

{ "code": 200, "message": "success", "data": null }

说明：

只能在用户当前使用的版本内调整等级
如需跨版本调整，先迁移版本再调整等级

11.9 查询版本下的用户列表

GET /api/admin/user-level-config/version/{versionId}/users?page=1&size=20

需要管理员权限

路径参数：

versionId: 版本ID

查询参数：

page: 页码（默认1）
size: 每页数量（默认20）

响应：

{
  "code": 200,
  "data": {
    "total": 1250,
    "page": 1,
    "size": 20,
    "users": [
      {
        "userId": 1,
        "phone": "138****0000",
        "nickname": "用户138****0000",
        "levelCode": "NORMAL",
        "levelName": "普通用户",
        "migratedAt": "2026-06-01T10:00:00",
        "migrateReason": "AUTO_REGISTER"
      }
    ]
  }
}

11.10 查看用户等级变更历史

GET /api/admin/user-level-config/user/{userId}/history

需要管理员权限

路径参数：

userId: 用户ID

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "fromVersionId": null,
      "fromVersion": null,
      "toVersionId": 1,
      "toVersion": "v1.0",
      "fromLevelCode": null,
      "toLevelCode": "NORMAL",
      "migrateReason": "AUTO_REGISTER",
      "migratedBy": null,
      "migratedAt": "2026-06-01T10:00:00",
      "remark": null
    },
    {
      "id": 2,
      "fromVersionId": 1,
      "fromVersion": "v1.0",
      "toVersionId": 2,
      "toVersion": "v2.0",
      "fromLevelCode": "VIP",
      "toLevelCode": "VIP",
      "migrateReason": "BATCH_MIGRATE",
      "migratedBy": 100,
      "migratedAt": "2026-02-01T09:00:00",
      "remark": "春节活动，将VIP用户迁移到v2.0版本享受更高配额"
    }
  ]
}

12. 多端登录支持

12.1 登录来源标识

所有登录接口支持loginSource参数，标识登录来源：

字段	类型	必填	说明
targetVersionId	Long	是	目标版本ID
userIds	List	是	要迁移的用户ID列表
remark	String	否	迁移备注

值	说明
WINDOWS	Windows桌面应用
MINIAPP	微信小程序
ANDROID	Android APP
IOS	iOS APP
WECHAT	微信公众号H5

示例：

{
  "phone": "13800138000",
  "code": "123456",
  "loginSource": "WINDOWS"
}

12.2 用户信息返回扩展

用户信息接口返回新增字段：

{
  "userId": 1,
  "phone": "13800138000",
  "nickname": "用户138****0000",
  "avatar": null,
  "levelName": "普通用户",
  "levelCode": "NORMAL",
  "pharmacyName": "XX大药房",
  "loginSource": "WINDOWS",
  "lastLoginDevice": "Windows 10 - WebView2"
}

📝 说明：本文档会随着项目迭代持续更新，请以最新版本为准。

03-接口文档.md 35 KB История Исходник

智价云药店 - 接口文档

通用说明

请求头

统一响应格式

错误码

分页响应格式

常见错误响应示例

1. 认证模块 /api/auth

1.1 发送验证码

1.2 验证码登录/注册

1.3 获取微信扫码登录URL

1.4 微信扫码登录

1.5 微信绑定手机号

1.6 微信登录回调

1.7 刷新Token

1.8 获取当前用户信息

2. 爬虫配额 /api/crawler

2.1 获取爬虫权益状态

2.2 消耗爬虫次数

2.3 获取爬虫使用记录

3. 邀请系统 /api/invite

3.1 获取我的邀请码

3.2 获取邀请统计

3.3 获取邀请记录

3.4 获取额外爬虫次数

3.5 邀请落地页（公开）

3.6 追踪邀请链接点击（公开）

4. 优惠券 /api/coupon

4.1 发放优惠券（管理）

4.2 获取我的优惠券

4.3 获取可用优惠券

5. 用户等级 /api/level

5.1 获取等级列表（公开）

5.2 获取等级详情（公开）

5.3 获取当前用户等级

5.4 设置用户等级（管理）

6. 运营管理 /api/admin

6.1 获取邀请配置

6.2 更新邀请配置

6.3 获取所有邀请配置

6.4 手动发放爬虫次数

6.5 查看发放记录

6.6 查看邀请记录

6.7 查看用户爬虫详情（含平台分布）

6.8 查看用户邀请转化统计

7. B2B平台账号绑定模块 /api/platform-account

7.1 绑定B2B平台账号

7.2 解绑B2B平台账号

7.3 查询已绑定的平台账号列表

7.4 验证平台账号

8. 营业执照模块 /api/business-license

8.1 上传营业执照

8.2 查询营业执照信息

9. 平台配置模块 /api/platform-config

9.1 查询所有启用的平台

9.2 查询指定平台配置

10. 体验配额配置模块 /api/trial-quota

10.1 查询当前生效的体验配置

10.2 查询所有体验配置（运营后台）

10.3 创建体验配置（运营后台）

10.4 更新体验配置（运营后台）

10.5 删除体验配置（运营后台）

11. 用户等级配置管理 /api/user-level-config

11.1 获取当前激活的等级版本

11.2 获取用户的等级信息（含版本）

11.3 查询所有等级版本（运营后台）

11.4 查询指定版本的等级明细

11.5 创建新的等级配置版本

11.6 激活等级配置版本

11.7 批量迁移用户到新版本 ⚠️

11.8 手动调整单个用户等级

11.9 查询版本下的用户列表

11.10 查看用户等级变更历史

12. 多端登录支持

12.1 登录来源标识

12.2 用户信息返回扩展

03-接口文档.md 35 KB

История Исходник