# 智价云（药店版） - 接口文档

> **⚠️ MVP 阶段说明**  
> 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。  
> 本文档描述的是 MVP 版本的接口定义，后续会根据业务需求持续迭代。
>
> 版本：v1.1-MVP | 更新日期：2026-07-01 | 状态：开发中  
> 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": {
    "levelName": "普通会员",
    "levelCode": "PLUS",
    "todayUsed": 2,
    "todayQuota": 15,
    "todayRemaining": 13,
    "monthUsed": 30,
    "monthQuota": 315,
    "monthRemaining": 285,
    "yearUsed": 100,
    "yearQuota": 3665,
    "yearRemaining": 3565,
    "baseDailyQuota": 10,
    "baseMonthlyQuota": 300,
    "baseYearlyQuota": 3650,
    "extraQuota": 5,
    "extraQuotaBreakdown": [
      {
        "sourceType": "INVITE",
        "sourceName": "邀请奖励",
        "available": 3,
        "total": 5,
        "used": 2
      },
      {
        "sourceType": "ADMIN",
        "sourceName": "运营发放",
        "available": 2,
        "total": 10,
        "used": 8
      }
    ],
    "maxConcurrent": 1,
    "hasCoupon": true,
    "availableCouponCount": 2
  }
}
```

**字段说明：**
- `levelName`/`levelCode`: 当前用户会员等级名称和编码
- `todayUsed`/`todayQuota`/`todayRemaining`: 今日已用/总配额/剩余
- `monthUsed`/`monthQuota`/`monthRemaining`: 本月已用/总配额/剩余
- `yearUsed`/`yearQuota`/`yearRemaining`: 本年已用/总配额/剩余（无年配额时为null）
- `baseDailyQuota`/`baseMonthlyQuota`/`baseYearlyQuota`: 等级基础配额（不含额外配额）
- `extraQuota`: 额外配额总额（邀请+运营+购买三种来源之和）
- `extraQuotaBreakdown`: 额外配额来源明细
- `maxConcurrent`: 最大并发数
- `hasCoupon`/`availableCouponCount`: 是否有可用优惠券 / 可用数量

---

### 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~~ （已下线）

> **⚠️ 已下线**：等级版本体系（NORMAL/VIP/SVIP）已下线，统一迁移至会员体系（PLUS/PRO/ULTRA）。
> 相关接口已由 `/api/membership`（会员体系）和 `/api/level`（等级列表）接管。
> 参见：第 5 节 用户等级、第 15 节 会员体系。

---

## 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
{
  "id": 1,
  "userId": 1,
  "phone": "13800138000",
  "nickname": "用户138****0000",
  "avatar": null,
  "wechatBound": false,
  "membershipLevel": "PLUS",
  "membershipLevelName": "PLUS会员",
  "levelCode": "PLUS",
  "version": "v1.0",
  "role": "USER",
  "loginSource": "WINDOWS",
  "pharmacyName": "XX大药房",
  "province": "广东省",
  "city": "深圳市",
  "district": "南山区",
  "createTime": "2026-06-15T10:00:00"
}
```

**字段说明：**
- `membershipLevel`: 会员等级（PLUS/PRO/ULTRA）
- `membershipLevelName`: 会员等级中文名
- `loginSource`: 登录来源（WINDOWS/MINIAPP/ANDROID/IOS/WECHAT）
- `role`: 用户角色（USER/ADMIN/SUPER_ADMIN）

---

## 13. 支付模块 /api/payment

### 13.1 获取支付方案列表（公开）

```
GET /api/payment/plans
```

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "planCode": "MONTHLY_PRO",
      "planName": "高级会员·月卡",
      "membershipLevel": "PRO",
      "price": 29.90,
      "originalPrice": 59.90,
      "durationDays": 30,
      "sortOrder": 3,
      "status": 1,
      "description": "每天不限量· 1个月29.9（原价59.9）"
    }
  ]
}
```

---

### 13.2 创建支付订单

```
POST /api/payment/order/create
```

**需要认证**

**请求体：**
```json
{
  "planId": 1,
  "channel": "WECHAT"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| planId | Long | 是 | 支付方案ID |
| channel | String | 是 | 支付渠道：WECHAT/ALIPAY |

**响应：**
```json
{
  "code": 200,
  "data": {
    "orderNo": "OP1234567890123456",
    "planName": "高级会员·月卡",
    "amount": 29.90,
    "channel": "WECHAT",
    "status": "PENDING",
    "qrCodeBase64": "data:image/png;base64,...",
    "payUrl": "weixin://wxpay/bizpayurl?pr=xxx",
    "expireTime": "2026-06-30T22:00:00",
    "expireHint": "请在15分钟内完成付款，超时订单将自动过期",
    "createTime": "2026-06-30T21:45:00"
  }
}
```

---

### 13.3 切换支付渠道

```
POST /api/payment/order/{orderNo}/switch-channel
```

**需要认证**

**业务场景：** 用户创建订单后，可在订单详情页切换为其他支付渠道，后端根据新渠道重新调用预下单接口生成二维码。

> **重要**：不关闭原渠道订单，允许用户在多个渠道间切换。以第一个支付成功渠道为准，后续支付记录到重复支付表并自动退款。

**请求体：**
```json
{
  "channel": "ALIPAY"
}
```

**响应：** 同 13.2 创建订单

---

### 13.4 查询订单

```
GET /api/payment/order/{orderNo}
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": {
    "orderNo": "OP1234567890123456",
    "planName": "高级会员·月卡",
    "amount": 29.90,
    "channel": "WECHAT",
    "status": "PAID",
    "qrCodeBase64": null,
    "payUrl": null,
    "expireTime": "2026-06-30T22:00:00",
    "expireHint": null,
    "createTime": "2026-06-30T21:45:00"
  }
}
```

---

### 13.5 查询我的订单列表

```
GET /api/payment/orders
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "orderNo": "OP1234567890123456",
      "planName": "高级会员·月卡",
      "amount": 29.90,
      "channel": "WECHAT",
      "status": "PAID",
      "createTime": "2026-06-30T21:45:00"
    }
  ]
}
```

---

### 13.6 模拟支付（开发测试用）

```
POST /api/payment/order/{orderNo}/pay
```

**需要认证**

> 仅在 `payment.mock=true` 时可用。已支付订单会返回错误（code=2005）。

**响应：**
```json
{
  "code": 200,
  "data": {
    "orderNo": "OP1234567890123456",
    "status": "PAID",
    "amount": 29.90,
    "planName": "高级会员·月卡",
    "membershipLevel": "PRO",
    "paidTime": "2026-06-30T21:50:00"
  }
}
```

---

### 13.7 微信支付回调（公开）

```
POST /api/payment/callback/wechat
```

**无需认证**

微信支付异步通知回调。生产环境需接入微信支付SDK完成RSA验签+解密。

**响应：** 成功返回 `SUCCESS`，失败返回 `FAIL`

---

### 13.8 支付宝回调（公开）

```
POST /api/payment/callback/alipay
```

**无需认证**

支付宝异步通知回调。生产环境需接入支付宝SDK完成RSA2验签。

**响应：** 成功返回 `success`，失败返回 `fail`

---

### 13.9 重复支付自动退款

当同一订单在多个渠道都支付成功时（用户切换渠道后），系统自动处理：

1. **第一次支付成功**：正常更新订单为 PAID，激活会员
2. **后续重复支付**：回调到达时发现订单已 PAID，触发重复支付处理
3. **幂等控制**：同一 `trade_no` 不重复记录，避免重复退款
4. **自动退款**：调用对应渠道的退款接口原路退回
5. **状态追踪**：退款状态 `PENDING → SUCCESS / FAILED`

**退款渠道实现：**

| 渠道 | 退款接口 | 说明 |
|------|----------|------|
| 微信 | WxPayService.refundV3() | API v3 退款，需配置退款证书 |
| 支付宝 | AlipayClient.execute(AlipayTradeRefundRequest) | 统一收单交易退款 |
| 模拟模式 | 直接返回模拟退款单号 | mock=true 时不调用真实SDK |

**退款状态：**

| 状态 | 说明 |
|------|------|
| PENDING | 待退款（初始状态） |
| SUCCESS | 退款成功（记录退款交易号） |
| FAILED | 退款失败（记录失败原因，可后续重试） |

**支付模块错误码：**

| code | 说明 |
|------|------|
| 2001 | 支付订单不存在 |
| 2002 | 支付订单已过期 |
| 2003 | 支付金额不正确 |
| 2004 | 不支持该支付渠道 |
| 2005 | 支付失败 |
| 2006 | 退款失败，请重试 |
| 2007 | 支付方案不存在 |
| 2008 | 支付方案已下架 |
| 2009 | 支付回调验签失败 |
| 2010 | 支付渠道未配置 |
| 2011 | 方案编码已存在 |
| 2012 | 签约协议不存在 |
| 2013 | 已存在有效签约协议 |
| 2014 | 协议未签约或已解约 |
| 2015 | 自动扣款失败 |
| 2016 | 安心付卡模板不存在 |
| 2017 | 安心付卡模板创建失败 |
| 2018 | 安心付未配置 |
| 2019 | 安心付订单不存在 |
| 2020 | 安心付扣款通知无法匹配到系统用户 |

---

### 13.10 运营管理-支付方案

| 接口 | 说明 |
|------|------|
| POST /api/admin/payment/plans | 创建支付方案（ADMIN+） |
| PUT /api/admin/payment/plans/{id} | 更新支付方案（ADMIN+） |
| PUT /api/admin/payment/plans/{id}/status | 上架/下架方案（ADMIN+） |

### 13.11 签约协议管理 /api/payment/agreement

| 接口 | 说明 |
|------|------|
| POST /api/payment/agreement/sign | 发起签约 |
| GET /api/payment/agreement/list | 查询用户签约列表 |
| GET /api/payment/agreement/{agreementId} | 查询协议详情 |
| POST /api/payment/agreement/{agreementId}/unsign | 解约 |
| POST /api/payment/agreement/notify/wechat | 微信签约回调（公开） |

### 13.12 安心付管理 /api/admin/payment/anxin

| 接口 | 说明 |
|------|------|
| POST /api/admin/payment/anxin/card/create | 创建安心付卡模板（ADMIN+） |
| GET /api/admin/payment/anxin/cards | 查询安心付卡模板列表（ADMIN+） |
| POST /api/admin/payment/anxin/card/{cardId}/sync | 同步安心付卡模板状态（ADMIN+） |
| PUT /api/admin/payment/anxin/card/{cardId}/status | 启用/禁用安心付卡模板（ADMIN+） |
| POST /api/payment/anxin/notify/deduct | 安心付扣款通知（公开） |
| POST /api/payment/anxin/notify/card-change | 安心付卡变更通知（公开） |

### 13.13 支付宝开放能力 /api/payment/alipay

| 接口 | 说明 |
|------|------|
| POST /api/payment/alipay/gateway | 支付宝网关回调（公开） |
| GET /api/payment/alipay/auth-callback | 支付宝授权回调（公开） |

### 13.14 操作审计日志 /api/admin/audit-log

| 接口 | 说明 |
|------|------|
| GET /api/admin/audit-log | 分页查询审计日志（ADMIN+） |
| GET /api/admin/audit-log/sensitive | 查询敏感操作日志（ADMIN+） |
| GET /api/admin/audit-log/user/{userId} | 查询指定用户操作历史（ADMIN+） |
| GET /api/admin/audit-log/target/{type}/{id} | 查询指定目标对象操作历史（ADMIN+） |
| GET /api/admin/audit-log/stats | 按模块统计操作次数（ADMIN+） |

### 13.15 平台会话管理 /api/platform-session

| 接口 | 说明 |
|------|------|
| PUT /api/platform-session/{platformCode} | 更新平台会话 |
| GET /api/platform-session/list | 查询平台会话列表 |
| DELETE /api/platform-session/{platformCode} | 删除平台会话 |

### 13.16 搜索历史 /api/search-record

| 接口 | 说明 |
|------|------|
| POST /api/search-record/history | 保存搜索记录 |
| GET /api/search-record/history | 获取搜索历史 |
| GET /api/search-record/history/{id} | 获取指定搜索记录 |
| DELETE /api/search-record/history/{id} | 删除指定搜索记录 |
| DELETE /api/search-record/history | 清空搜索历史 |

### 13.17 邀请补充接口

| 接口 | 说明 |
|------|------|
| GET /api/invite/my-inviter | 查询我的邀请人 |
| POST /api/invite/bind | 补填邀请码 |

---

## 14. 药品搜索比价 /api/search

### 14.1 药品搜索比价

```
POST /api/search/query
```

**需要认证**

消耗 1 次爬虫配额，返回各平台报价。

**请求体：**
```json
{
  "keyword": "阿莫西林胶囊",
  "platforms": ["yaoshibang", "yaobangmang", "yiyaocheng"]
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | String | 是 | 药品名称关键词 |
| platforms | Array<String> | 否 | 指定平台列表，为空则查全部已启用平台 |

**响应：**
```json
{
  "code": 200,
  "data": {
    "keyword": "阿莫西林胶囊",
    "results": [
      {
        "platformCode": "yaoshibang",
        "platformName": "药师帮",
        "drugName": "阿莫西林胶囊",
        "spec": "0.25g*24粒",
        "manufacturer": "珠海联邦制药",
        "price": 12.50,
        "url": "https://www.yaoshibang.com/product/xxx"
      }
    ],
    "searchedAt": "2026-06-30T22:00:00"
  }
}
```

---

### 14.2 搜索建议（公开）

```
GET /api/search/suggestions
```

**无需认证**

返回热门药品列表，用于搜索框联想。

**响应：**
```json
{
  "code": 200,
  "data": ["阿莫西林胶囊", "布洛芬片", "感冒灵颗粒", "板蓝根颗粒"]
}
```

---

## 15. 会员体系 /api/membership

### 15.1 查询我的会员信息

```
GET /api/membership/my
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": {
    "level": "PRO",
    "levelName": "高级会员",
    "effectiveFrom": "2026-06-01T00:00:00",
    "effectiveTo": "2026-07-01T00:00:00",
    "status": "ACTIVE",
    "dailyQuota": 999,
    "monthlyQuota": 29970,
    "maxConcurrent": 5
  }
}
```

---

### 15.2 查询会员等级权益

```
GET /api/membership/benefits?level=PLUS
```

**需要认证**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| level | String | PLUS | 会员等级：PLUS/PRO/ULTRA |

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "level": "PRO",
      "benefitType": "DAILY_QUOTA",
      "benefitValue": 999
    },
    {
      "level": "PRO",
      "benefitType": "MONTHLY_QUOTA",
      "benefitValue": 29970
    },
    {
      "level": "PRO",
      "benefitType": "MAX_CONCURRENT",
      "benefitValue": 5
    }
  ]
}
```

---

## 16. 关注/收藏 /api/watchlist

### 16.1 获取关注列表

```
GET /api/watchlist
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "drugName": "阿莫西林胶囊",
      "spec": "0.25g*24粒",
      "manufacturer": "珠海联邦制药",
      "minPrice": 12.50,
      "minPricePlatform": "yaoshibang",
      "lastPrice": 13.00,
      "priceChange": 0.50,
      "status": 1,
      "createTime": "2026-06-15T10:00:00"
    }
  ]
}
```

---

### 16.2 添加关注

```
POST /api/watchlist
```

**需要认证**

**请求体：**
```json
{
  "drugName": "阿莫西林胶囊",
  "spec": "0.25g*24粒",
  "manufacturer": "珠海联邦制药"
}
```

**响应：** 同 16.1 单条记录

---

### 16.3 取消关注

```
DELETE /api/watchlist/{id}
```

**需要认证**

---

### 16.4 获取关注统计

```
GET /api/watchlist/stats
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": {
    "total": 15,
    "active": 12,
    "priceDropCount": 3
  }
}
```

---

## 17. 文件上传 /api/upload

### 17.1 上传文件

```
POST /api/upload
```

**需要认证**

**请求格式：** multipart/form-data

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | MultipartFile | 是 | 上传的文件 |

**响应：**
```json
{
  "code": 200,
  "data": "/opt/uploads/abc123def456.jpg"
}
```

---

## 18. 运营管理补充接口

### 18.1 用户管理（SUPER_ADMIN） /api/admin/users

| 接口 | 说明 |
|------|------|
| GET /api/admin/users?page=1&size=20&phone=138&role=ADMIN | 分页查询用户列表（SUPER_ADMIN） |
| PUT /api/admin/users/{userId}/role | 修改用户角色（SUPER_ADMIN） |

**修改角色请求体：**
```json
{
  "role": "ADMIN"
}
```

---

### 18.2 会员管理（ADMIN+） /api/admin/membership

| 接口 | 说明 |
|------|------|
| POST /api/admin/membership/grant | 给用户发放/调整会员等级（ADMIN+） |
| GET /api/admin/membership/memberships?page=1&size=20&userId=1&level=PLUS | 分页查询会员记录（ADMIN+） |

**发放会员请求体：**
```json
{
  "userId": 1,
  "level": "PRO",
  "durationDays": 30,
  "source": "ADMIN_GRANT",
  "remark": "运营手动发放"
}
```

---

### 18.3 营业执照审核（ADMIN+） /api/admin/license

| 接口 | 说明 |
|------|------|
| GET /api/admin/license/review?reviewStatus=PENDING | 查看待审核营业执照列表（ADMIN+） |
| POST /api/admin/license/review | 审核营业执照（ADMIN+，通过后赠送30天高级会员） |

**审核请求体：**
```json
{
  "licenseId": 1,
  "action": "APPROVED",
  "rejectReason": null
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| licenseId | Long | 是 | 营业执照ID |
| action | String | 是 | 审核动作：APPROVED/REJECTED |
| rejectReason | String | 否 | 驳回原因（REJECTED时必填） |

---

## 19. 搜索记录 /api/search-record

### 19.1 保存搜索记录

```
POST /api/search-record/history
```

**需要认证**

**请求体：**
```json
{
  "drugName": "阿莫西林",
  "searchedAt": "2026-07-01T10:00:00",
  "statusText": "找到3个平台报价",
  "platformResults": [{"platform": "平台A", "price": 12.5}],
  "searchLog": null
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| drugName | String | 是 | 药品名称 |
| searchedAt | DateTime | 否 | 搜索时间 |
| statusText | String | 否 | 状态文案 |
| platformResults | Object | 否 | 平台搜索结果（任意JSON，原样存储） |
| searchLog | Object | 否 | 搜索日志（任意JSON） |

**响应：** 同 19.3 查询详情

---

### 19.2 查询最近搜索历史

```
GET /api/search-record/history?limit=20
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "drugName": "阿莫西林",
      "searchedAt": "2026-07-01T10:00:00",
      "statusText": "找到3个平台报价",
      "platformResults": [{"platform": "平台A", "price": 12.5}],
      "searchLog": null
    }
  ]
}
```

---

### 19.3 查询单条搜索记录详情

```
GET /api/search-record/history/{id}
```

**需要认证**

**响应：**
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "drugName": "阿莫西林",
    "searchedAt": "2026-07-01T10:00:00",
    "statusText": "找到3个平台报价",
    "platformResults": [{"platform": "平台A", "price": 12.5}],
    "searchLog": null
  }
}
```

---

### 19.4 删除单条搜索记录

```
DELETE /api/search-record/history/{id}
```

**需要认证**

**响应：**
```json
{ "code": 200, "message": "success", "data": null }
```

---

### 19.5 清空全部搜索记录

```
DELETE /api/search-record/history
```

**需要认证**

**响应：**
```json
{ "code": 200, "message": "success", "data": null }
```

---

## 20. 操作审计日志 /api/admin/audit-log（ADMIN+）

### 20.1 分页查询审计日志

```
GET /api/admin/audit-log?module=PAYMENT&operationType=GRANT&operatorId=1&isSensitive=false&page=1&size=20
```

**需要管理员权限**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| module | String | 否 | 模块筛选 |
| operationType | String | 否 | 操作类型筛选 |
| operatorId | Long | 否 | 操作人ID |
| startTime | DateTime | 否 | 开始时间 |
| endTime | DateTime | 否 | 结束时间 |
| isSensitive | Boolean | 否 | 是否仅敏感操作 |
| page | int | 否 | 页码（默认1） |
| size | int | 否 | 每页数量（默认20） |

**响应：** 分页格式（参见“通用说明 - 分页响应格式”）

---

### 20.2 查询敏感操作日志

```
GET /api/admin/audit-log/sensitive?startTime=2026-07-01T00:00:00
```

**需要管理员权限**

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "module": "USER",
      "operationType": "DISABLE_USER",
      "operatorId": 100,
      "isSensitive": true,
      "targetType": "USER",
      "targetId": 5,
      "beforeData": "{\"status\":\"ACTIVE\"}",
      "afterData": "{\"status\":\"DISABLED\"}",
      "ip": "192.168.1.100",
      "createdAt": "2026-07-01T10:00:00"
    }
  ]
}
```

---

### 20.3 查询指定用户的操作日志

```
GET /api/admin/audit-log/user/{userId}?limit=50
```

**需要管理员权限**

---

### 20.4 查询指定目标对象的操作历史

```
GET /api/admin/audit-log/target/{targetType}/{targetId}?limit=50
```

**需要管理员权限**

**路径参数：**
- `targetType`: 目标类型（USER/ORDER/CONFIG等）
- `targetId`: 目标ID

---

### 20.5 查询模块操作统计

```
GET /api/admin/audit-log/stats?module=PAYMENT&startTime=2026-07-01T00:00:00
```

**需要管理员权限**

**响应：**
```json
{
  "code": 200,
  "data": { "count": 42 }
}
```

---

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