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

> **模块**：business-marketing  
> **前缀**：`${jeesharp.web.adminPath}`（默认 `/api`）  
> **完整路径示例**：`/api/marketing/memberTenant/v1/list`  
> **更新日期**：2026-06-25  
> **版本**：P0

---

## 一、接口规范

### 1.1 请求头

```
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}
```

### 1.2 响应格式

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": { },
  "requestId": "uuid-xxx"
}
```

### 1.3 租户说明

- 店铺管理员登录后，**DataScope 自动限定当前 `tenant_id`**，无需传店铺 ID。
- 平台运营可跨租户（角色权限控制）。
- 列表含 `member_id` 时，响应须含 **会员编号、会员姓名/昵称、会员手机**（`MemberService.enrichMemberDisplay`）。

---

## 二、店铺会员 `memberTenant`

**Controller**：`MemberTenantController`  
**基础路径**：`/marketing/memberTenant/v1`

### 2.1 分页列表

- **URL**：`POST /list`
- **权限**：`marketing:memberTenant:list`

**请求体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNo | Long | 页码 |
| pageSize | Long | 每页条数 |
| memberKeyword | String | 会员关键词（编号/昵称/姓名/手机/主键） |
| bindStatus | Integer | 0未绑定 1已绑定 2已解绑 |
| joinSource | String | QR_SCAN / ADMIN / IMPORT / MINI_APPLY |
| channelCode | String | 渠道 |
| joinDateStart | LocalDateTime | 入会开始 |
| joinDateEnd | LocalDateTime | 入会结束 |

**列表字段**：

| 字段 | 说明 |
|------|------|
| id | 关系主键 |
| memberId | 会员ID |
| memberNo | 会员编号（补全） |
| memberNickname | 会员姓名/昵称（补全） |
| memberMobile | 会员手机（补全） |
| tenantId / tenantCode | 店铺租户 |
| bindStatus / bindStatusName | 绑定状态 |
| joinSource / joinSourceName | 入会来源 |
| channelCode | 渠道 |
| joinDate | 入会时间 |

### 2.2 详情

- **URL**：`GET /info?id={id}`
- **权限**：`marketing:memberTenant:info`

### 2.3 导出

- **URL**：`POST /export`
- **权限**：`marketing:memberTenant:export`

---

## 三、店铺营销配置 `tenantExt`

**基础路径**：`/marketing/tenantExt/v1`

### 3.1 详情（当前租户）

- **URL**：`GET /info`
- **权限**：`marketing:tenantExt:info`
- **说明**：无 id 参数，读当前登录租户配置；无记录时返回默认结构。

### 3.2 更新

- **URL**：`POST /update`
- **权限**：`marketing:tenantExt:update`

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 编辑必填 | 新增为空 |
| marketingEnabled | Integer | ✅ | 0否 1是 |
| autoJoinOnQr | Integer | ✅ | 0需审核 1扫码免审直绑 |
| welcomeTitle | String | | 落地页标题 |
| welcomeSubtitle | String | | 落地页副标题 |
| logoUrl | String | | Logo |

---

## 四、推广二维码 `tenantQrcode`

**基础路径**：`/marketing/tenantQrcode/v1`

### 4.1 分页列表

- **URL**：`POST /list`
- **权限**：`marketing:tenantQrcode:list`

### 4.2 生成/刷新

- **URL**：`POST /create`
- **权限**：`marketing:tenantQrcode:create`

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| channelCode | String | ✅ | 渠道编码，同租户唯一 |
| channelName | String | | 渠道名称 |
| pagePath | String | | 小程序路径，默认营销落地页 |

**响应 data**：`id`、`wxScene`、`qrcodeUrl`、`channelCode`

### 4.3 删除

- **URL**：`GET /delete?ids={id1,id2}`
- **权限**：`marketing:tenantQrcode:delete`

---

## 五、核销记录 `couponVerifyLog`

**基础路径**：`/marketing/couponVerifyLog/v1`

### 5.1 分页列表

- **URL**：`POST /list`
- **权限**：`marketing:couponVerifyLog:list`

**请求体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNo / pageSize | Long | 分页 |
| memberKeyword | String | 会员关键词 |
| memberCouponId | String | 会员券ID |
| verifyTimeStart / verifyTimeEnd | LocalDateTime | 核销时间 |
| verifyType | String | OFFLINE_SCAN |

**列表字段**：含 `memberNo`、`memberNickname`、`memberMobile`（补全）、券名、核销时间、操作人、渠道等。

### 5.2 详情

- **URL**：`GET /info?id={id}`
- **权限**：`marketing:couponVerifyLog:info`

### 5.3 导出

- **URL**：`POST /export`
- **权限**：`marketing:couponVerifyLog:export`

---

## 六、数据统计 `stats`

**基础路径**：`/marketing/stats/v1`

### 6.1 概览

- **URL**：`POST /overview`
- **权限**：`marketing:stats:overview`

**请求体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| dateStart | LocalDate | 统计开始（默认近30天） |
| dateEnd | LocalDate | 统计结束 |
| channelCode | String | 可选，按渠道 |

**响应 data**：

| 字段 | 说明 |
|------|------|
| joinCount | 入会人数（期内新增绑定） |
| receiveCount | 领券数 |
| verifyCount | 核销量 |
| verifyRate | 核销率 receiveCount>0 时 |
| channelStats | 渠道维度数组 |
| dailyTrend | 日趋势 [{date, join, receive, verify}] |

---

## 七、优惠券模板（复用 coupon 模块）

店铺券在 **当前租户 DataScope** 下使用现有券模板接口：

- **基础路径**：`/coupon/couponTemplate/v1`
- **创建店铺券**：`scene_code = STORE_OFFLINE`，模板 `tenant_id` 由 DataScope 自动写入
- **权限**：`coupon:couponTemplate:*`

---

## 八、权限标识汇总

| 权限标识 | 说明 |
|----------|------|
| `marketing:memberTenant:list` | 店铺会员列表 |
| `marketing:memberTenant:info` | 店铺会员详情 |
| `marketing:memberTenant:export` | 店铺会员导出 |
| `marketing:tenantExt:info` | 营销配置详情 |
| `marketing:tenantExt:update` | 营销配置更新 |
| `marketing:tenantQrcode:list` | 推广码列表 |
| `marketing:tenantQrcode:create` | 生成推广码 |
| `marketing:tenantQrcode:delete` | 删除推广码 |
| `marketing:couponVerifyLog:list` | 核销记录列表 |
| `marketing:couponVerifyLog:info` | 核销记录详情 |
| `marketing:couponVerifyLog:export` | 核销记录导出 |
| `marketing:stats:overview` | 统计概览 |
| `coupon:couponTemplate:*` | 店铺券模板（coupon 模块） |

---

## 九、接口地址速查表

| 操作 | 方法 | URL |
|------|------|-----|
| 店铺会员列表 | POST | `/marketing/memberTenant/v1/list` |
| 店铺会员详情 | GET | `/marketing/memberTenant/v1/info` |
| 营销配置详情 | GET | `/marketing/tenantExt/v1/info` |
| 营销配置更新 | POST | `/marketing/tenantExt/v1/update` |
| 推广码列表 | POST | `/marketing/tenantQrcode/v1/list` |
| 生成推广码 | POST | `/marketing/tenantQrcode/v1/create` |
| 核销记录列表 | POST | `/marketing/couponVerifyLog/v1/list` |
| 统计概览 | POST | `/marketing/stats/v1/overview` |

---

## 十、枚举值速查

### bindStatus（绑定状态）

| 值 | 说明 |
|----|------|
| 0 | 未绑定 |
| 1 | 已绑定 |
| 2 | 已解绑 |

### joinSource（入会来源）

| 值 | 说明 |
|----|------|
| QR_SCAN | 扫码 |
| ADMIN | 后台 |
| IMPORT | 导入 |
| MINI_APPLY | 小程序申请 |

### verifyType（核销类型）

| 值 | 说明 |
|----|------|
| OFFLINE_SCAN | 线下扫码核销 |

---

## 十一、跨模块依赖（P0 须在 coupon-api 扩展）

| API | 说明 |
|-----|------|
| `MemberCouponMobileApi` | 领券、我的券（已有） |
| `MemberCouponLifecycleApi.offlineConfirmUsed` | **P0 新增**，线下核销置已用，幂等 |

---

## 十二、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-06-25 | P0 初版：入会、配置、二维码、核销流水、统计 |