# 会员管理模块后台接口文档

> **模块名称**：business-member  
> **版本**：3.0.1  
> **更新日期**：2026-01-24  
> **基础路径**：`${jeesharp.web.adminPath}/模块名/类名`

---

## 一、接口规范

### 1.1 URL 格式规范

```
${jeesharp.web.adminPath}/模块名/类名/操作
```

**说明**：
- `${jeesharp.web.adminPath}` 默认值为 `/api`，可在配置文件中修改
- **模块名**：业务模块标识，如 `member`
- **类名**：实体类名（驼峰命名），如 `member`、`memberLevel`
- 完整路径示例：`/api/member/member/list`

### 1.2 请求规范

| 项目 | 规范 |
|------|------|
| **Content-Type** | `application/json;charset=UTF-8` |
| **Authorization** | `Bearer {token}` |
| **URL 命名** | 驼峰命名，单数名词 |

### 1.3 HTTP 方法规范

| HTTP 方法 | 操作类型 | 说明 |
|-----------|---------|------|
| **GET** | 详情 | 获取单个资源：`GET /类名/info?id=xxx` |
| **POST** | 列表（分页） | 获取资源列表：`POST /类名/list` |
| **POST** | 新增/修改 | 保存资源：`POST /类名/save` |
| **GET** | 删除 | 删除资源：`GET /类名/delete?ids=xxx,xxx` |
| **POST** | 导出 | 导出 Excel：`POST /类名/export` |
| **POST** | 导入 | 导入 Excel：`POST /类名/import` |
| **GET** | 下载模板 | 下载模板：`GET /类名/import/template` |

### 1.4 响应格式

```json
{
    "code": 200,
    "msg": "success",
    "data": {},
    "requestId": "链路追踪ID"
}
```

### 1.5 状态码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器错误 |

---

## 二、会员管理接口（Member）

> **模块路径**：`${adminPath}/member/member`

### 2.1 获取会员列表（分页）

**接口地址**：`POST ${adminPath}/member/member/list`

**权限标识**：`member:member:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "memberNo": "M202601240001",
    "mobile": "138****1234",
    "nickname": "张三",
    "realName": "张三",
    "levelCode": "GOLD",
    "status": 1,
    "source": "WECHAT_MINI",
    "isRealName": 1,
    "registerDateStart": "2026-01-01 00:00:00",
    "registerDateEnd": "2026-01-31 23:59:59"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页条数，默认10 |
| memberNo | String | 否 | 会员编号 |
| mobile | String | 否 | 手机号（支持模糊） |
| nickname | String | 否 | 昵称（支持模糊） |
| realName | String | 否 | 真实姓名（支持模糊） |
| levelCode | String | 否 | 等级编码：NORMAL/SILVER/GOLD/PLATINUM/DIAMOND |
| status | Integer | 否 | 状态：0-禁用 1-正常 2-待审核 3-已注销 |
| source | String | 否 | 来源：APP/WECHAT_MINI/WECHAT_MP/H5/PC/HUAWEI/ALIPAY |
| isRealName | Integer | 否 | 是否实名：0-否 1-是 |
| registerDateStart | String | 否 | 注册开始时间 |
| registerDateEnd | String | 否 | 注册结束时间 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 100,
        "pages": 10,
        "current": 1,
        "size": 10,
        "records": [
            {
                "id": "1",
                "memberNo": "M202601240001",
                "nickname": "张三",
                "realName": "张三",
                "avatar": "https://xxx.com/avatar.jpg",
                "gender": 1,
                "genderName": "男",
                "mobile": "138****1234",
                "email": "zhangsan@example.com",
                "birthday": "1990-01-15",
                "province": "北京市",
                "city": "北京市",
                "district": "朝阳区",
                "levelId": "3",
                "levelCode": "GOLD",
                "levelName": "黄金会员",
                "growthValue": 5200,
                "totalPoints": 10000,
                "availablePoints": 8500,
                "frozenPoints": 500,
                "totalConsumeAmount": 15000.00,
                "totalConsumeCount": 25,
                "balance": 200.00,
                "status": 1,
                "statusName": "正常",
                "source": "WECHAT_MINI",
                "sourceName": "微信小程序",
                "isRealName": 1,
                "isRealNameName": "是",
                "inviteCode": "ABC123",
                "inviteCount": 5,
                "registerDate": "2026-01-01 10:30:00",
                "lastLoginDate": "2026-01-24 08:15:00",
                "createDate": "2026-01-01 10:30:00"
            }
        ]
    }
}
```

---

### 2.2 获取会员详情

**接口地址**：`GET ${adminPath}/member/member/info`

**权限标识**：`member:member:info`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 会员ID |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "1",
        "memberNo": "M202601240001",
        "userId": "user001",
        "nickname": "张三",
        "realName": "张三",
        "avatar": "https://xxx.com/avatar.jpg",
        "gender": 1,
        "genderName": "男",
        "mobile": "13812341234",
        "email": "zhangsan@example.com",
        "idCard": "110***********1234",
        "birthday": "1990-01-15",
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区",
        "address": "xx街道xx号",
        "levelId": "3",
        "levelCode": "GOLD",
        "levelName": "黄金会员",
        "growthValue": 5200,
        "levelExpireDate": null,
        "totalPoints": 10000,
        "availablePoints": 8500,
        "frozenPoints": 500,
        "usedPoints": 1000,
        "expiredPoints": 0,
        "totalConsumeAmount": 15000.00,
        "totalConsumeCount": 25,
        "lastConsumeDate": "2026-01-20 15:30:00",
        "avgConsumeAmount": 600.00,
        "balance": 200.00,
        "frozenBalance": 0.00,
        "inviterId": null,
        "inviteCode": "ABC123",
        "inviteCount": 5,
        "status": 1,
        "statusName": "正常",
        "source": "WECHAT_MINI",
        "sourceName": "微信小程序",
        "sourceChannel": "活动推广001",
        "tags": ["VIP", "活跃用户"],
        "isRealName": 1,
        "realNameDate": "2026-01-05 10:00:00",
        "isCompleteProfile": 1,
        "registerDate": "2026-01-01 10:30:00",
        "registerIp": "192.168.1.1",
        "lastLoginDate": "2026-01-24 08:15:00",
        "lastLoginIp": "192.168.1.100",
        "lastLoginType": "WECHAT_MINI",
        "loginCount": 50,
        "createBy": "system",
        "createDate": "2026-01-01 10:30:00",
        "updateBy": "admin",
        "updateDate": "2026-01-24 08:15:00",
        "remarks": ""
    }
}
```

---

### 2.3 新增/编辑会员

**接口地址**：`POST ${adminPath}/member/member/save`

**权限标识**：`member:member:save`

**请求参数**：

```json
{
    "id": null,
    "nickname": "张三",
    "realName": "张三",
    "avatar": "https://xxx.com/avatar.jpg",
    "gender": 1,
    "mobile": "13812341234",
    "email": "zhangsan@example.com",
    "idCard": "110101199001151234",
    "birthday": "1990-01-15",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "address": "xx街道xx号",
    "levelCode": "NORMAL",
    "status": 1,
    "source": "ADMIN",
    "tags": ["VIP"],
    "remarks": "后台创建"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 否 | 会员ID，为空新增，不为空编辑 |
| nickname | String | 否 | 昵称 |
| realName | String | 否 | 真实姓名 |
| avatar | String | 否 | 头像URL |
| gender | Integer | 否 | 性别：0-未知 1-男 2-女 |
| mobile | String | 是 | 手机号（新增必填） |
| email | String | 否 | 邮箱 |
| idCard | String | 否 | 身份证号 |
| birthday | String | 否 | 生日 yyyy-MM-dd |
| province | String | 否 | 省份 |
| city | String | 否 | 城市 |
| district | String | 否 | 区县 |
| address | String | 否 | 详细地址 |
| levelCode | String | 否 | 等级编码，默认NORMAL |
| status | Integer | 否 | 状态，默认1 |
| source | String | 否 | 来源 |
| tags | Array | 否 | 标签数组 |
| remarks | String | 否 | 备注 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "保存成功",
    "data": {
        "id": "1234567890"
    }
}
```

---

### 2.4 删除会员

**接口地址**：`GET ${adminPath}/member/member/delete`

**权限标识**：`member:member:delete`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 会员ID |

**响应示例**：

```json
{
    "code": 200,
    "msg": "删除成功",
    "data": null
}
```

---

### 2.5 导出会员

**接口地址**：`POST ${adminPath}/member/member/export`

**权限标识**：`member:member:export`

**请求参数**：同列表查询参数

**响应**：Excel 文件流

---

### 2.6 导入会员

**接口地址**：`POST ${adminPath}/member/member/import`

**权限标识**：`member:member:import`

**Content-Type**：`multipart/form-data`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | 是 | Excel文件 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "导入成功",
    "data": {
        "successCount": 100,
        "failCount": 2,
        "failList": [
            { "row": 5, "reason": "手机号格式错误" },
            { "row": 12, "reason": "手机号已存在" }
        ]
    }
}
```

---

### 2.7 下载导入模板

**接口地址**：`GET ${adminPath}/member/member/import/template`

**权限标识**：`member:member:import`

**响应**：Excel 模板文件流

---

### 2.8 修改会员状态

**接口地址**：`POST ${adminPath}/member/member/updateStatus`

**权限标识**：`member:member:save`

**请求参数**：

```json
{
    "id": "1",
    "status": 0
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 会员ID |
| status | Integer | 是 | 状态：0-禁用 1-正常 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": null
}
```

---

### 2.9 调整会员积分

**接口地址**：`POST ${adminPath}/member/member/adjustPoints`

**权限标识**：`member:member:adjustPoints`

**请求参数**：

```json
{
    "memberId": "1",
    "points": 100,
    "bizType": "MANUAL",
    "remarks": "积分调整原因"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| memberId | String | 是 | 会员ID |
| points | Integer | 是 | 积分变动值（正数增加，负数减少） |
| bizType | String | 否 | 业务类型，默认MANUAL |
| remarks | String | 是 | 调整原因 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "beforePoints": 8500,
        "afterPoints": 8600
    }
}
```

---

### 2.10 调整会员等级

**接口地址**：`POST ${adminPath}/member/member/adjustLevel`

**权限标识**：`member:member:adjustLevel`

**请求参数**：

```json
{
    "memberId": "1",
    "levelCode": "PLATINUM",
    "remarks": "等级调整原因"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| memberId | String | 是 | 会员ID |
| levelCode | String | 是 | 等级编码 |
| remarks | String | 是 | 调整原因 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "beforeLevel": "GOLD",
        "afterLevel": "PLATINUM"
    }
}
```

---

## 三、会员等级接口（MemberLevel）

> **模块路径**：`${adminPath}/member/memberLevel`

### 3.1 获取等级列表

**接口地址**：`POST ${adminPath}/member/memberLevel/list`

**权限标识**：`member:memberLevel:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "levelCode": "GOLD",
    "levelName": "黄金",
    "status": 1
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| levelCode | String | 否 | 等级编码 |
| levelName | String | 否 | 等级名称（模糊） |
| status | Integer | 否 | 状态：0-禁用 1-启用 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 5,
        "records": [
            {
                "id": "1",
                "levelCode": "NORMAL",
                "levelName": "普通会员",
                "levelIcon": "https://xxx.com/normal.png",
                "levelSort": 1,
                "minGrowthValue": 0,
                "maxGrowthValue": 999,
                "discountRate": 1.00,
                "pointsRate": 1.00,
                "freeShippingThreshold": null,
                "birthdayPoints": 0,
                "upgradeGiftPoints": 0,
                "privileges": null,
                "validityDays": null,
                "downgradeEnabled": 0,
                "status": 1,
                "statusName": "启用"
            },
            {
                "id": "2",
                "levelCode": "SILVER",
                "levelName": "白银会员",
                "levelIcon": "https://xxx.com/silver.png",
                "levelSort": 2,
                "minGrowthValue": 1000,
                "maxGrowthValue": 4999,
                "discountRate": 0.98,
                "pointsRate": 1.20,
                "freeShippingThreshold": 99.00,
                "birthdayPoints": 100,
                "upgradeGiftPoints": 50,
                "privileges": "{\"freeShipping\": true}",
                "validityDays": null,
                "downgradeEnabled": 0,
                "status": 1,
                "statusName": "启用"
            }
        ]
    }
}
```

---

### 3.2 获取等级详情

**接口地址**：`GET ${adminPath}/member/memberLevel/info`

**权限标识**：`member:memberLevel:info`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 等级ID |

---

### 3.3 新增/编辑等级

**接口地址**：`POST /api/member/memberLevel/save`

**权限标识**：`member:memberLevel:save`

**请求参数**：

```json
{
    "id": null,
    "levelCode": "DIAMOND",
    "levelName": "钻石会员",
    "levelIcon": "https://xxx.com/diamond.png",
    "levelSort": 5,
    "minGrowthValue": 50000,
    "maxGrowthValue": null,
    "discountRate": 0.88,
    "pointsRate": 3.00,
    "freeShippingThreshold": 0,
    "birthdayPoints": 1000,
    "upgradeGiftPoints": 500,
    "privileges": "{\"freeShipping\": true, \"priorityService\": true}",
    "validityDays": null,
    "downgradeEnabled": 0,
    "downgradeCycleDays": null,
    "downgradeThreshold": null,
    "status": 1,
    "remarks": ""
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 否 | 等级ID，为空新增 |
| levelCode | String | 是 | 等级编码（唯一） |
| levelName | String | 是 | 等级名称 |
| levelIcon | String | 否 | 等级图标URL |
| levelSort | Integer | 是 | 排序（越大等级越高） |
| minGrowthValue | Integer | 是 | 最低成长值 |
| maxGrowthValue | Integer | 否 | 最高成长值（NULL=无上限） |
| discountRate | BigDecimal | 是 | 折扣率（0.88=88折） |
| pointsRate | BigDecimal | 是 | 积分倍率（1.5=1.5倍） |
| freeShippingThreshold | BigDecimal | 否 | 免邮门槛 |
| birthdayPoints | Integer | 否 | 生日赠送积分 |
| upgradeGiftPoints | Integer | 否 | 升级赠送积分 |
| privileges | String | 否 | 特权配置（JSON） |
| validityDays | Integer | 否 | 有效期（天） |
| downgradeEnabled | Integer | 否 | 是否启用降级 |
| downgradeCycleDays | Integer | 否 | 降级周期（天） |
| downgradeThreshold | Integer | 否 | 保级所需成长值 |
| status | Integer | 否 | 状态 |

---

### 3.4 删除等级

**接口地址**：`GET ${adminPath}/member/memberLevel/delete`

**权限标识**：`member:memberLevel:delete`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 等级ID |

> 注意：删除前需检查是否有会员使用此等级

---

### 3.5 获取所有启用等级（下拉选择用）

**接口地址**：`GET ${adminPath}/member/memberLevel/options`

**权限标识**：无

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": [
        { "value": "NORMAL", "label": "普通会员" },
        { "value": "SILVER", "label": "白银会员" },
        { "value": "GOLD", "label": "黄金会员" },
        { "value": "PLATINUM", "label": "铂金会员" },
        { "value": "DIAMOND", "label": "钻石会员" }
    ]
}
```

---

## 四、积分流水接口（MemberPointsLog）

> **模块路径**：`${adminPath}/member/memberPointsLog`

### 4.1 获取积分流水列表

**接口地址**：`POST ${adminPath}/member/memberPointsLog/list`

**权限标识**：`member:memberPointsLog:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "memberId": "1",
    "memberNo": "M202601240001",
    "pointsType": 1,
    "bizType": "CONSUME",
    "createDateStart": "2026-01-01 00:00:00",
    "createDateEnd": "2026-01-31 23:59:59"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| memberId | String | 否 | 会员ID |
| memberNo | String | 否 | 会员编号 |
| pointsType | Integer | 否 | 积分类型：1-获取 2-消费 3-冻结 4-解冻 5-过期 6-调整 |
| bizType | String | 否 | 业务类型：CONSUME/SIGN_IN/SHARE/INVITE/BIRTHDAY/UPGRADE/EXCHANGE/REFUND/MANUAL/EXPIRE/ACTIVITY |
| createDateStart | String | 否 | 开始时间 |
| createDateEnd | String | 否 | 结束时间 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 50,
        "records": [
            {
                "id": "1",
                "memberId": "1",
                "memberNo": "M202601240001",
                "pointsType": 1,
                "pointsTypeName": "获取",
                "points": 100,
                "beforePoints": 8400,
                "afterPoints": 8500,
                "frozenPoints": 0,
                "bizType": "CONSUME",
                "bizTypeName": "消费获取",
                "bizId": "ORDER202601240001",
                "bizNo": "ORD20260124001",
                "bizDesc": "订单消费获取积分",
                "ruleName": "消费1元=1积分",
                "expireDate": "2027-01-24 23:59:59",
                "isExpired": 0,
                "operateSource": "SYSTEM",
                "createDate": "2026-01-24 10:30:00"
            }
        ]
    }
}
```

---

### 4.2 获取积分流水详情

**接口地址**：`GET ${adminPath}/member/memberPointsLog/info`

**权限标识**：`member:memberPointsLog:info`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 流水ID |

---

### 4.3 导出积分流水

**接口地址**：`POST ${adminPath}/member/memberPointsLog/export`

**权限标识**：`member:memberPointsLog:export`

**请求参数**：同列表查询参数

**响应**：Excel 文件流

---

## 五、优惠券模板接口（CouponTemplate）

> **模块路径**：`${adminPath}/member/couponTemplate`

### 5.1 获取优惠券模板列表

**接口地址**：`POST ${adminPath}/member/couponTemplate/list`

**权限标识**：`member:couponTemplate:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "couponCode": "WELCOME2026",
    "couponName": "新人",
    "couponType": 1,
    "getType": 1,
    "status": 1
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| couponCode | String | 否 | 优惠券编码 |
| couponName | String | 否 | 优惠券名称（模糊） |
| couponType | Integer | 否 | 类型：1-满减券 2-折扣券 3-无门槛券 4-兑换券 |
| getType | Integer | 否 | 领取方式：1-手动 2-自动 3-兑换 |
| status | Integer | 否 | 状态：0-下架 1-进行中 2-已结束 3-待开始 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 20,
        "records": [
            {
                "id": "1",
                "couponCode": "WELCOME2026",
                "couponName": "新人满100减20",
                "couponType": 1,
                "couponTypeName": "满减券",
                "couponImage": "https://xxx.com/coupon.png",
                "discountType": 1,
                "discountTypeName": "金额",
                "discountValue": 20.00,
                "minConsumeAmount": 100.00,
                "maxDiscountAmount": null,
                "useScope": 1,
                "useScopeName": "全场通用",
                "totalCount": 1000,
                "issuedCount": 500,
                "usedCount": 200,
                "perMemberLimit": 1,
                "getType": 1,
                "getTypeName": "手动领取",
                "exchangePoints": null,
                "validityType": 2,
                "validityTypeName": "领取后N天有效",
                "validStartDate": null,
                "validEndDate": null,
                "validDays": 30,
                "getStartDate": "2026-01-01 00:00:00",
                "getEndDate": "2026-12-31 23:59:59",
                "status": 1,
                "statusName": "进行中",
                "createDate": "2026-01-01 00:00:00"
            }
        ]
    }
}
```

---

### 5.2 获取优惠券模板详情

**接口地址**：`GET ${adminPath}/member/couponTemplate/info`

**权限标识**：`member:couponTemplate:info`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 模板ID |

---

### 5.3 新增/编辑优惠券模板

**接口地址**：`POST ${adminPath}/member/couponTemplate/save`

**权限标识**：`member:couponTemplate:save`

**请求参数**：

```json
{
    "id": null,
    "couponCode": "SUMMER2026",
    "couponName": "夏季满200减50",
    "couponType": 1,
    "couponImage": "https://xxx.com/summer.png",
    "discountType": 1,
    "discountValue": 50.00,
    "minConsumeAmount": 200.00,
    "maxDiscountAmount": null,
    "useScope": 1,
    "scopeIds": null,
    "excludeScopeIds": null,
    "totalCount": 5000,
    "perMemberLimit": 2,
    "getType": 1,
    "exchangePoints": null,
    "validityType": 1,
    "validStartDate": "2026-06-01 00:00:00",
    "validEndDate": "2026-08-31 23:59:59",
    "validDays": null,
    "getStartDate": "2026-05-20 00:00:00",
    "getEndDate": "2026-08-20 23:59:59",
    "usePlatforms": ["APP", "MINI", "H5"],
    "memberLevels": [],
    "canOverlay": 0,
    "status": 1,
    "description": "夏季促销活动优惠券",
    "remarks": ""
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 否 | 模板ID，为空新增 |
| couponCode | String | 是 | 优惠券编码（唯一） |
| couponName | String | 是 | 优惠券名称 |
| couponType | Integer | 是 | 类型：1-满减券 2-折扣券 3-无门槛券 4-兑换券 |
| couponImage | String | 否 | 优惠券图片 |
| discountType | Integer | 是 | 优惠方式：1-金额 2-折扣 |
| discountValue | BigDecimal | 是 | 优惠值 |
| minConsumeAmount | BigDecimal | 否 | 最低消费金额 |
| maxDiscountAmount | BigDecimal | 否 | 最大优惠金额 |
| useScope | Integer | 是 | 使用范围：1-全场通用 2-指定商品 3-指定分类 4-指定品牌 |
| scopeIds | Array | 否 | 范围ID列表 |
| excludeScopeIds | Array | 否 | 排除范围ID列表 |
| totalCount | Integer | 是 | 发行总量（-1不限） |
| perMemberLimit | Integer | 是 | 每人限领数量 |
| getType | Integer | 是 | 领取方式：1-手动 2-自动 3-兑换 |
| exchangePoints | Integer | 否 | 兑换积分（兑换领取时必填） |
| validityType | Integer | 是 | 有效期类型：1-固定时间段 2-领取后N天 |
| validStartDate | String | 否 | 有效期开始（固定时间段时必填） |
| validEndDate | String | 否 | 有效期结束（固定时间段时必填） |
| validDays | Integer | 否 | 有效天数（领取后N天时必填） |
| getStartDate | String | 否 | 领取开始时间 |
| getEndDate | String | 否 | 领取结束时间 |
| usePlatforms | Array | 否 | 可用平台 |
| memberLevels | Array | 否 | 可用会员等级 |
| canOverlay | Integer | 否 | 是否可叠加 |
| status | Integer | 否 | 状态 |
| description | String | 否 | 使用说明 |

---

### 5.4 删除优惠券模板

**接口地址**：`GET ${adminPath}/member/couponTemplate/delete`

**权限标识**：`member:couponTemplate:delete`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 模板ID |

> 注意：已发放的优惠券模板不可删除

---

### 5.5 上架/下架优惠券

**接口地址**：`POST ${adminPath}/member/couponTemplate/updateStatus`

**权限标识**：`member:couponTemplate:save`

**请求参数**：

```json
{
    "id": "1",
    "status": 0
}
```

---

## 六、会员优惠券接口（MemberCoupon）

> **模块路径**：`${adminPath}/member/memberCoupon`

### 6.1 获取会员优惠券列表

**接口地址**：`POST /api/member/memberCoupon/list`

**权限标识**：`member:memberCoupon:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "memberId": "1",
    "memberNo": "M202601240001",
    "couponCode": "WELCOME2026",
    "couponSn": "CPN202601240001",
    "status": 0,
    "getDateStart": "2026-01-01 00:00:00",
    "getDateEnd": "2026-01-31 23:59:59"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| memberId | String | 否 | 会员ID |
| memberNo | String | 否 | 会员编号 |
| couponCode | String | 否 | 优惠券编码 |
| couponSn | String | 否 | 优惠券券码 |
| status | Integer | 否 | 状态：0-未使用 1-已使用 2-已过期 3-已冻结 4-已作废 |
| getDateStart | String | 否 | 领取开始时间 |
| getDateEnd | String | 否 | 领取结束时间 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 30,
        "records": [
            {
                "id": "1",
                "couponSn": "CPN202601240001",
                "memberId": "1",
                "memberNo": "M202601240001",
                "memberMobile": "138****1234",
                "templateId": "1",
                "couponCode": "WELCOME2026",
                "couponName": "新人满100减20",
                "couponType": 1,
                "couponTypeName": "满减券",
                "discountType": 1,
                "discountValue": 20.00,
                "minConsumeAmount": 100.00,
                "maxDiscountAmount": null,
                "getType": 1,
                "getTypeName": "手动领取",
                "getDate": "2026-01-15 10:30:00",
                "getSource": "MINI",
                "validStartDate": "2026-01-15 10:30:00",
                "validEndDate": "2026-02-14 23:59:59",
                "status": 0,
                "statusName": "未使用",
                "useDate": null,
                "useOrderNo": null,
                "useAmount": null
            }
        ]
    }
}
```

---

### 6.2 获取会员优惠券详情

**接口地址**：`GET ${adminPath}/member/memberCoupon/info`

**权限标识**：`member:memberCoupon:info`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 优惠券ID |

---

### 6.3 发放优惠券

**接口地址**：`POST ${adminPath}/member/memberCoupon/grant`

**权限标识**：`member:memberCoupon:grant`

**请求参数**：

```json
{
    "templateId": "1",
    "memberIds": ["1", "2", "3"],
    "remarks": "活动赠送"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| templateId | String | 是 | 优惠券模板ID |
| memberIds | Array | 是 | 会员ID列表 |
| remarks | String | 否 | 备注 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "发放成功",
    "data": {
        "successCount": 3,
        "failCount": 0
    }
}
```

---

### 6.4 作废优惠券

**接口地址**：`POST ${adminPath}/member/memberCoupon/cancel`

**权限标识**：`member:memberCoupon:cancel`

**请求参数**：

```json
{
    "id": "1",
    "remarks": "作废原因"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 优惠券ID |
| remarks | String | 是 | 作废原因 |

---

### 6.5 导出会员优惠券

**接口地址**：`POST ${adminPath}/member/memberCoupon/export`

**权限标识**：`member:memberCoupon:export`

**请求参数**：同列表查询参数

**响应**：Excel 文件流

---

## 七、成长值流水接口（MemberGrowthLog）

> **模块路径**：`${adminPath}/member/memberGrowthLog`

### 7.1 获取成长值流水列表

**接口地址**：`POST ${adminPath}/member/memberGrowthLog/list`

**权限标识**：`member:memberGrowthLog:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "memberId": "1",
    "memberNo": "M202601240001",
    "growthType": 1,
    "bizType": "CONSUME",
    "isUpgrade": 1,
    "createDateStart": "2026-01-01 00:00:00",
    "createDateEnd": "2026-01-31 23:59:59"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| memberId | String | 否 | 会员ID |
| memberNo | String | 否 | 会员编号 |
| growthType | Integer | 否 | 变动类型：1-获取 2-扣减 3-调整 |
| bizType | String | 否 | 业务类型：CONSUME/SIGN_IN/SHARE/INVITE/COMPLETE_PROFILE/REAL_NAME/MANUAL/DOWNGRADE |
| isUpgrade | Integer | 否 | 是否升级：0-否 1-是 |
| createDateStart | String | 否 | 开始时间 |
| createDateEnd | String | 否 | 结束时间 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 30,
        "records": [
            {
                "id": "1",
                "memberId": "1",
                "memberNo": "M202601240001",
                "growthType": 1,
                "growthTypeName": "获取",
                "growthValue": 100,
                "beforeValue": 4900,
                "afterValue": 5000,
                "beforeLevel": "SILVER",
                "beforeLevelName": "白银会员",
                "afterLevel": "GOLD",
                "afterLevelName": "黄金会员",
                "isUpgrade": 1,
                "isDowngrade": 0,
                "bizType": "CONSUME",
                "bizTypeName": "消费",
                "bizId": "ORDER202601240001",
                "bizNo": "ORD20260124001",
                "bizDesc": "订单消费获取成长值",
                "createDate": "2026-01-24 10:30:00"
            }
        ]
    }
}
```

---

### 7.2 导出成长值流水

**接口地址**：`POST ${adminPath}/member/memberGrowthLog/export`

**权限标识**：`member:memberGrowthLog:export`

**请求参数**：同列表查询参数

**响应**：Excel 文件流

---

## 八、余额流水接口（MemberBalanceLog）

> **模块路径**：`${adminPath}/member/memberBalanceLog`

### 8.1 获取余额流水列表

**接口地址**：`POST ${adminPath}/member/memberBalanceLog/list`

**权限标识**：`member:memberBalanceLog:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "memberId": "1",
    "memberNo": "M202601240001",
    "balanceType": 1,
    "bizType": "RECHARGE",
    "payChannel": "WECHAT",
    "createDateStart": "2026-01-01 00:00:00",
    "createDateEnd": "2026-01-31 23:59:59"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| memberId | String | 否 | 会员ID |
| memberNo | String | 否 | 会员编号 |
| balanceType | Integer | 否 | 变动类型：1-充值 2-消费 3-退款 4-冻结 5-解冻 6-提现 7-调整 |
| bizType | String | 否 | 业务类型：RECHARGE/CONSUME/REFUND/WITHDRAW/GIFT/MANUAL |
| payChannel | String | 否 | 支付渠道：WECHAT/ALIPAY/BALANCE/BANK |
| createDateStart | String | 否 | 开始时间 |
| createDateEnd | String | 否 | 结束时间 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 20,
        "records": [
            {
                "id": "1",
                "memberId": "1",
                "memberNo": "M202601240001",
                "balanceType": 1,
                "balanceTypeName": "充值",
                "amount": 200.00,
                "beforeBalance": 0.00,
                "afterBalance": 200.00,
                "frozenAmount": 0.00,
                "bizType": "RECHARGE",
                "bizTypeName": "充值",
                "bizId": "RCH202601240001",
                "bizNo": "RCH20260124001",
                "bizDesc": "微信充值",
                "payChannel": "WECHAT",
                "payChannelName": "微信",
                "payTradeNo": "4200001234567890",
                "createDate": "2026-01-20 15:30:00"
            }
        ]
    }
}
```

---

### 8.2 导出余额流水

**接口地址**：`POST ${adminPath}/member/memberBalanceLog/export`

**权限标识**：`member:memberBalanceLog:export`

**请求参数**：同列表查询参数

**响应**：Excel 文件流

---

## 九、会员标签接口（MemberTag）

> **模块路径**：`${adminPath}/member/memberTag`

### 9.1 获取标签列表

**接口地址**：`POST /api/member/memberTag/list`

**权限标识**：`member:memberTag:list`

**请求参数**：

```json
{
    "pageNo": 1,
    "pageSize": 10,
    "tagCode": "VIP",
    "tagName": "VIP",
    "tagType": 1,
    "status": 1
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| tagCode | String | 否 | 标签编码 |
| tagName | String | 否 | 标签名称（模糊） |
| tagType | Integer | 否 | 标签类型：1-系统标签 2-自定义标签 |
| status | Integer | 否 | 状态：0-禁用 1-启用 |

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 10,
        "records": [
            {
                "id": "1",
                "tagCode": "VIP",
                "tagName": "VIP会员",
                "tagType": 1,
                "tagTypeName": "系统标签",
                "tagColor": "#FF6600",
                "tagIcon": "https://xxx.com/vip.png",
                "parentId": null,
                "sort": 1,
                "memberCount": 500,
                "status": 1,
                "statusName": "启用",
                "description": "VIP会员标签"
            }
        ]
    }
}
```

---

### 9.2 获取标签详情

**接口地址**：`GET ${adminPath}/member/memberTag/info`

**权限标识**：`member:memberTag:info`

---

### 9.3 新增/编辑标签

**接口地址**：`POST /api/member/memberTag/save`

**权限标识**：`member:memberTag:save`

**请求参数**：

```json
{
    "id": null,
    "tagCode": "ACTIVE",
    "tagName": "活跃用户",
    "tagType": 2,
    "tagColor": "#409EFF",
    "tagIcon": null,
    "parentId": null,
    "sort": 10,
    "autoTagRule": null,
    "status": 1,
    "description": "7天内登录3次以上的用户"
}
```

---

### 9.4 删除标签

**接口地址**：`GET ${adminPath}/member/memberTag/delete`

**权限标识**：`member:memberTag:delete`

---

### 9.5 给会员打标签

**接口地址**：`POST ${adminPath}/member/memberTag/bindMembers`

**权限标识**：`member:memberTag:bind`

**请求参数**：

```json
{
    "tagId": "1",
    "memberIds": ["1", "2", "3"]
}
```

---

### 9.6 移除会员标签

**接口地址**：`POST /api/member/memberTag/unbindMembers`

**权限标识**：`member:memberTag:bind`

**请求参数**：

```json
{
    "tagId": "1",
    "memberIds": ["1", "2", "3"]
}
```

---

### 9.7 获取所有启用标签（下拉选择用）

**接口地址**：`GET ${adminPath}/member/memberTag/options`

**权限标识**：无

**响应示例**：

```json
{
    "code": 200,
    "msg": "success",
    "data": [
        { "value": "1", "label": "VIP会员", "color": "#FF6600" },
        { "value": "2", "label": "活跃用户", "color": "#409EFF" },
        { "value": "3", "label": "新用户", "color": "#67C23A" }
    ]
}
```

---

## 十、接口地址速查表

> **说明**：`${adminPath}` 默认值为 `/api`，完整路径示例：`/api/member/member/list`

### 10.1 会员管理（member）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/member/list` |
| 详情 | GET | `${adminPath}/member/member/info?id=xxx` |
| 保存 | POST | `${adminPath}/member/member/save` |
| 删除 | GET | `${adminPath}/member/member/delete?ids=xxx` |
| 导出 | POST | `${adminPath}/member/member/export` |
| 导入 | POST | `${adminPath}/member/member/import` |
| 下载模板 | GET | `${adminPath}/member/member/import/template` |
| 修改状态 | POST | `${adminPath}/member/member/updateStatus` |
| 调整积分 | POST | `${adminPath}/member/member/adjustPoints` |
| 调整等级 | POST | `${adminPath}/member/member/adjustLevel` |

### 10.2 会员等级（memberLevel）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberLevel/list` |
| 详情 | GET | `${adminPath}/member/memberLevel/info?id=xxx` |
| 保存 | POST | `${adminPath}/member/memberLevel/save` |
| 删除 | GET | `${adminPath}/member/memberLevel/delete?id=xxx` |
| 下拉选项 | GET | `${adminPath}/member/memberLevel/options` |

### 10.3 积分流水（memberPointsLog）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberPointsLog/list` |
| 详情 | GET | `${adminPath}/member/memberPointsLog/info?id=xxx` |
| 导出 | POST | `${adminPath}/member/memberPointsLog/export` |

### 10.4 优惠券模板（couponTemplate）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/couponTemplate/list` |
| 详情 | GET | `${adminPath}/member/couponTemplate/info?id=xxx` |
| 保存 | POST | `${adminPath}/member/couponTemplate/save` |
| 删除 | GET | `${adminPath}/member/couponTemplate/delete?id=xxx` |
| 上下架 | POST | `${adminPath}/member/couponTemplate/updateStatus` |

### 10.5 会员优惠券（memberCoupon）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberCoupon/list` |
| 详情 | GET | `${adminPath}/member/memberCoupon/info?id=xxx` |
| 发放 | POST | `${adminPath}/member/memberCoupon/grant` |
| 作废 | POST | `${adminPath}/member/memberCoupon/cancel` |
| 导出 | POST | `${adminPath}/member/memberCoupon/export` |

### 10.6 成长值流水（memberGrowthLog）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberGrowthLog/list` |
| 导出 | POST | `${adminPath}/member/memberGrowthLog/export` |

### 10.7 余额流水（memberBalanceLog）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberBalanceLog/list` |
| 导出 | POST | `${adminPath}/member/memberBalanceLog/export` |

### 10.8 会员标签（memberTag）

| 操作 | 方法 | 接口地址 |
|------|------|----------|
| 列表 | POST | `${adminPath}/member/memberTag/list` |
| 详情 | GET | `${adminPath}/member/memberTag/info?id=xxx` |
| 保存 | POST | `${adminPath}/member/memberTag/save` |
| 删除 | GET | `${adminPath}/member/memberTag/delete?id=xxx` |
| 绑定会员 | POST | `${adminPath}/member/memberTag/bindMembers` |
| 解绑会员 | POST | `${adminPath}/member/memberTag/unbindMembers` |
| 下拉选项 | GET | `${adminPath}/member/memberTag/options` |

---

## 十一、枚举值速查表

### 10.1 会员状态（status）

| 值 | 说明 |
|----|------|
| 0 | 禁用 |
| 1 | 正常 |
| 2 | 待审核 |
| 3 | 已注销 |

### 11.2 性别（gender）

| 值 | 说明 |
|----|------|
| 0 | 未知 |
| 1 | 男 |
| 2 | 女 |

### 11.3 会员来源（source）

| 值 | 说明 |
|----|------|
| APP | APP |
| WECHAT_MINI | 微信小程序 |
| WECHAT_MP | 微信公众号 |
| H5 | H5 |
| PC | PC |
| IMPORT | 导入 |
| HUAWEI | 华为 |
| ALIPAY | 支付宝 |
| QQ | QQ |
| WEIBO | 微博 |
| APPLE | 苹果 |
| DOUYIN | 抖音 |
| DINGTALK | 钉钉 |
| FEISHU | 飞书 |
| ADMIN | 后台创建 |

### 11.4 会员等级（levelCode）

| 值 | 说明 | 成长值范围 |
|----|------|----------|
| NORMAL | 普通会员 | 0-999 |
| SILVER | 白银会员 | 1000-4999 |
| GOLD | 黄金会员 | 5000-19999 |
| PLATINUM | 铂金会员 | 20000-49999 |
| DIAMOND | 钻石会员 | 50000+ |

### 10.5 积分类型（pointsType）

| 值 | 说明 |
|----|------|
| 1 | 获取 |
| 2 | 消费 |
| 3 | 冻结 |
| 4 | 解冻 |
| 5 | 过期 |
| 6 | 调整 |

### 11.6 积分业务类型（bizType）

| 值 | 说明 |
|----|------|
| CONSUME | 消费获取 |
| ORDER_CANCEL | 订单取消扣回 |
| SIGN_IN | 签到 |
| SHARE | 分享 |
| INVITE | 邀请 |
| BIRTHDAY | 生日赠送 |
| UPGRADE | 升级赠送 |
| EXCHANGE | 积分兑换 |
| REFUND | 退款扣减 |
| MANUAL | 人工调整 |
| EXPIRE | 过期清零 |
| ACTIVITY | 活动获取 |

### 11.7 优惠券类型（couponType）

| 值 | 说明 |
|----|------|
| 1 | 满减券 |
| 2 | 折扣券 |
| 3 | 无门槛券 |
| 4 | 兑换券 |

### 10.8 优惠方式（discountType）

| 值 | 说明 |
|----|------|
| 1 | 金额（如减20元） |
| 2 | 折扣（如85折） |

### 11.9 优惠券领取方式（getType）

| 值 | 说明 |
|----|------|
| 1 | 手动领取 |
| 2 | 自动发放 |
| 3 | 兑换领取 |
| 4 | 活动赠送 |

### 10.10 优惠券有效期类型（validityType）

| 值 | 说明 |
|----|------|
| 1 | 固定时间段 |
| 2 | 领取后N天有效 |

### 11.11 优惠券状态（status）

| 值 | 说明 |
|----|------|
| 0 | 未使用 |
| 1 | 已使用 |
| 2 | 已过期 |
| 3 | 已冻结 |
| 4 | 已作废 |

### 11.12 优惠券模板状态（status）

| 值 | 说明 |
|----|------|
| 0 | 已下架 |
| 1 | 进行中 |
| 2 | 已结束 |
| 3 | 待开始 |

### 11.13 余额变动类型（balanceType）

| 值 | 说明 |
|----|------|
| 1 | 充值 |
| 2 | 消费 |
| 3 | 退款 |
| 4 | 冻结 |
| 5 | 解冻 |
| 6 | 提现 |
| 7 | 调整 |

### 10.14 支付渠道（payChannel）

| 值 | 说明 |
|----|------|
| WECHAT | 微信 |
| ALIPAY | 支付宝 |
| BALANCE | 余额 |
| BANK | 银行卡 |

### 11.15 标签类型（tagType）

| 值 | 说明 |
|----|------|
| 1 | 系统标签 |
| 2 | 自定义标签 |

---

## 十二、权限标识汇总

| 模块 | 权限标识 | 说明 |
|------|---------|------|
| **会员** | member:member:list | 查看列表 |
| | member:member:info | 查看详情 |
| | member:member:save | 新增/编辑 |
| | member:member:delete | 删除 |
| | member:member:export | 导出 |
| | member:member:import | 导入 |
| | member:member:adjustPoints | 调整积分 |
| | member:member:adjustLevel | 调整等级 |
| **会员等级** | member:memberLevel:list | 查看列表 |
| | member:memberLevel:info | 查看详情 |
| | member:memberLevel:save | 新增/编辑 |
| | member:memberLevel:delete | 删除 |
| **积分流水** | member:memberPointsLog:list | 查看列表 |
| | member:memberPointsLog:info | 查看详情 |
| | member:memberPointsLog:export | 导出 |
| **优惠券模板** | member:couponTemplate:list | 查看列表 |
| | member:couponTemplate:info | 查看详情 |
| | member:couponTemplate:save | 新增/编辑 |
| | member:couponTemplate:delete | 删除 |
| **会员优惠券** | member:memberCoupon:list | 查看列表 |
| | member:memberCoupon:info | 查看详情 |
| | member:memberCoupon:grant | 发放 |
| | member:memberCoupon:cancel | 作废 |
| | member:memberCoupon:export | 导出 |
| **成长值流水** | member:memberGrowthLog:list | 查看列表 |
| | member:memberGrowthLog:export | 导出 |
| **余额流水** | member:memberBalanceLog:list | 查看列表 |
| | member:memberBalanceLog:export | 导出 |
| **会员标签** | member:memberTag:list | 查看列表 |
| | member:memberTag:info | 查看详情 |
| | member:memberTag:save | 新增/编辑 |
| | member:memberTag:delete | 删除 |
| | member:memberTag:bind | 绑定/解绑会员 |

---

## 十三、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-01-24 | 初始版本 |