# 智价云药店 - 接口文档 > **⚠️ MVP 阶段说明** > 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。 > 本文档描述的是 MVP 版本的接口定义，后续会根据业务需求持续迭代。 > > 版本：v1.0-MVP | 更新日期：2026-06-16 | 状态：开发中 > Base URL: `http://localhost:8080` --- ## 通用说明 ### 请求头 | Header | 说明 | |--------|------| | Content-Type | application/json | | Authorization | Bearer {accessToken}（需认证接口） | ### 统一响应格式 ```json { "code": 200, "message": "success", "data": {} } ``` ### 错误码 | code | 说明 | |------|------| | 200 | 成功 | | 400 | 参数错误 | | 401 | 未认证 | | 403 | 无权限 | | 404 | 资源不存在 | | 429 | 请求过于频繁 | | 500 | 服务器内部错误 | ### 分页响应格式 所有列表查询接口使用统一的分页响应格式： ```json { "code": 200, "message": "success", "data": { "total": 100, "page": 1, "size": 20, "records": [ {...} ] } } ``` | 字段 | 类型 | 说明 | |------|------|------| | total | Integer | 总记录数 | | page | Integer | 当前页码（从1开始） | | size | Integer | 每页数量 | | records | Array | 当前页的数据列表 | ### 常见错误响应示例 **参数错误：** ```json { "code": 400, "message": "手机号格式不正确", "data": null } ``` **配额不足：** ```json { "code": 400, "message": "每日配额已用完，请升级会员或等待明天", "data": null } ``` **资源不存在：** ```json { "code": 404, "message": "未找到该平台的绑定记录", "data": null } ``` **未认证：** ```json { "code": 401, "message": "Token已过期，请重新登录", "data": null } ``` **无权限：** ```json { "code": 403, "message": "需要管理员权限", "data": null } ``` --- ## 1. 认证模块 /api/auth ### 1.1 发送验证码 ``` POST /api/auth/sms/send ``` **请求体：** ```json { "phone": "13800138000" } ``` **响应：** ```json { "code": 200, "message": "success", "data": null } ``` --- ### 1.2 验证码登录/注册 ``` POST /api/auth/sms/login ``` **请求体：** ```json { "phone": "13800138000", "code": "123456", "inviteCode": "ABC123" // 可选，邀请码 } ``` **响应：** ```json { "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 ``` **响应：** ```json { "code": 200, "data": "https://open.weixin.qq.com/connect/qrconnect?appid=xxx&redirect_uri=xxx" } ``` --- ### 1.4 微信扫码登录 ``` POST /api/auth/wechat/login ``` **请求体：** ```json { "code": "wx_auth_code_xxx", "state": "login" } ``` **响应：** 同 1.2 --- ### 1.5 微信绑定手机号 ``` POST /api/auth/wechat/bind ``` **请求体：** ```json { "wechatCode": "wx_auth_code_xxx", "phone": "13800138000", "smsCode": "123456", "inviteCode": "ABC123" // 可选 } ``` **响应：** 同 1.2 --- ### 1.6 微信登录回调 ``` GET /api/auth/wechat/callback?code=xxx&state=xxx ``` **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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平台进行比价，系统爬取各平台价格并生成采购链接。 **请求体：** ```json { "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平台，其他平台将在后续版本中逐步开放。 **响应：** ```json { "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天 | **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "code": 200, "data": 15 } ``` --- ### 3.5 邀请落地页（公开） ``` GET /api/invite/page/{code}?channel=app ``` **无需认证** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | code | String | 是 | 邀请码 | | channel | String | 否 | 渠道：app/wechat/miniapp/dingtalk/feishu，默认app | **响应：** ```json { "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） **使用场景：** 1. 用户B点击邀请链接后访问此接口 2. 前端展示邀请人信息和下载按钮 3. 点击"打开APP"按钮时，尝试通过 `urlScheme` 唤醒客户端 4. 如果未安装，引导用户下载，下载后打开时可通过 DeepLink 自动填入邀请码 --- ### 3.6 追踪邀请链接点击（公开） ``` POST /api/invite/click/{code} ``` **无需认证** **响应：** ```json { "code": 200, "data": null } ``` --- ## 4. 优惠券 /api/coupon ### 4.1 发放优惠券（管理） ``` POST /api/coupon/issue ``` **请求体：** ```json { "couponId": 1, "userIds": [1, 2, 3], "validDays": 30 } ``` **响应：** ```json { "code": 200, "data": 3 } ``` --- ### 4.2 获取我的优惠券 ``` GET /api/coupon/my?status=0 ``` **需要认证** | 参数 | 类型 | 说明 | |------|------|------| | status | Integer | 可选，0-未使用 1-已使用 2-已过期 | **响应：** ```json { "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 ``` **响应：** ```json { "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 ``` **请求体：** ```json { "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 ``` **请求体：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要认证** **请求体：** ```json { "platformCode": "yaoshibang", "platformName": "药师帮", "account": "13800138000", "password": "your_password" } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | platformCode | String | 是 | 平台代码（yaoshibang/yaobangmang/yiyaocheng） | | platformName | String | 是 | 平台名称 | | account | String | 是 | 平台账号（手机号或用户名） | | password | String | 是 | 平台密码（服务端AES-256加密存储） | **响应：** ```json { "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） **响应：** ```json { "code": 200, "message": "success", "data": null } ``` --- ### 7.3 查询已绑定的平台账号列表 ``` GET /api/platform-account/list ``` **需要认证** **响应：** ```json { "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`: 平台代码 **响应：** ```json { "code": 200, "message": "success", "data": null } ``` **说明：** - 调用对应B2B平台的登录接口验证账号密码 - 验证成功后才能用于爬虫查询 --- ## 8. 营业执照模块 /api/business-license ### 8.1 上传营业执照 ``` POST /api/business-license/upload ``` **需要认证** **请求体：** ```json { "licenseImageUrl": "https://oss.example.com/license/xxx.jpg", "creditCode": "91110000XXXXXXXXXX", "pharmacyName": "XX大药房", "legalPerson": "张三" } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | licenseImageUrl | String | 是 | 营业执照图片URL（需先上传到OSS） | | creditCode | String | 是 | 统一社会信用代码（18位） | | pharmacyName | String | 是 | 药店名称 | | legalPerson | String | 否 | 法人姓名 | **响应：** ```json { "code": 200, "message": "success", "data": null } ``` **注意事项：** - 营业执照为**可选填写**，不影响基本使用 - 审核通过后显示认证标识，提升用户信任度 - 图片需要先上传到OSS，获取URL后再调用此接口 --- ### 8.2 查询营业执照信息 ``` GET /api/business-license/info ``` **需要认证** **响应：** ```json { "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 ``` **响应：** ```json { "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`: 平台代码 **响应：** ```json { "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 ``` **响应：** ```json { "code": 200, "data": { "configName": "新用户默认体验", "trialDays": 15, "dailyQueryLimit": 20, "monthlyWatchlistLimit": 199, "configType": "DEFAULT", "applicableUserType": "NEW_USER", "description": "新用户注册后自动获得的体验配额" } } ``` --- ### 10.2 查询所有体验配置（运营后台） ``` GET /api/admin/trial-quota/configs ``` **需要管理员权限** **响应：** ```json { "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 ``` **需要管理员权限** **请求体：** ```json { "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": "春节期间特别活动" } ``` **响应：** ```json { "code": 200, "message": "success", "data": null } ``` --- ### 10.4 更新体验配置（运营后台） ``` PUT /api/admin/trial-quota/config/{id} ``` **需要管理员权限** **请求体：** 同创建接口 **响应：** ```json { "code": 200, "message": "success", "data": null } ``` --- ### 10.5 删除体验配置（运营后台） ``` DELETE /api/admin/trial-quota/config/{id} ``` **需要管理员权限** **响应：** ```json { "code": 200, "message": "success", "data": null } ``` --- ## 11. 用户等级配置管理 /api/user-level-config > **说明**：支持运营动态调整等级规则，新用户自动使用最新版本，老用户由运营决定迁移到哪个版本 ### 11.1 获取当前激活的等级版本 ``` GET /api/user-level-config/current-version ``` **响应：** ```json { "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 ``` **需要认证** **响应：** ```json { "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 ``` **需要管理员权限** **响应：** ```json { "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 **响应：** ```json { "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 ``` **需要管理员权限** **请求体：** ```json { "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 | 否 | 等级描述 | **响应：** ```json { "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 **响应：** ```json { "code": 200, "message": "success", "data": null } ``` **说明：** - 激活后，该版本成为当前版本（is_current=true） - 其他版本的is_current自动设为false - **新用户注册时自动使用此版本** - **老用户不会自动迁移，需要运营手动或批量迁移** --- ### 11.7 批量迁移用户到新版本 ⚠️ ``` POST /api/admin/user-level-config/migrate-users ``` **需要管理员权限** **⚠️ 敏感操作**：此操作会影响用户的等级配额，请谨慎操作 **请求体：** ```json { "targetVersionId": 2, "userIds": [1, 2, 3, 4, 5], "remark": "春节活动，将VIP用户迁移到v2.0版本享受更高配额" } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | targetVersionId | Long | 是 | 目标版本ID | | userIds | List | 是 | 要迁移的用户ID列表 | | remark | String | 否 | 迁移备注 | **响应：** ```json { "code": 200, "data": { "totalCount": 5, "successCount": 5, "failedCount": 0, "failedUsers": [] } } ``` **说明：** - 系统会根据用户当前的等级编码（如VIP），在目标版本中找到对应的等级 - 如果目标版本中不存在该等级编码，则该用户迁移失败 - 迁移成功后，用户的配额立即生效 --- ### 11.8 手动调整单个用户等级 ``` PUT /api/admin/user-level-config/user/{userId}/level ``` **需要管理员权限** **路径参数：** - `userId`: 用户ID **请求体：** ```json { "targetLevelCode": "VIP", "reason": "用户反馈良好，手动升级为VIP" } ``` **响应：** ```json { "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） **响应：** ```json { "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 **响应：** ```json { "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`参数，标识登录来源： | 值 | 说明 | |----|------| | WINDOWS | Windows桌面应用 | | MINIAPP | 微信小程序 | | ANDROID | Android APP | | IOS | iOS APP | | WECHAT | 微信公众号H5 | **示例：** ```json { "phone": "13800138000", "code": "123456", "loginSource": "WINDOWS" } ``` ### 12.2 用户信息返回扩展 用户信息接口返回新增字段： ```json { "userId": 1, "phone": "13800138000", "nickname": "用户138****0000", "avatar": null, "levelName": "普通用户", "levelCode": "NORMAL", "pharmacyName": "XX大药房", "loginSource": "WINDOWS", "lastLoginDevice": "Windows 10 - WebView2" } ``` --- **📝 说明**：本文档会随着项目迭代持续更新，请以最新版本为准。