# 会员营销模块 — 移动端接口文档

> **模块**：business-marketing（HTTP 入口在 business-mobile-gateway）  
> **前缀**：`${jeesharp.web.mobilePath}`（默认 `/mobile`）  
> **更新日期**：2026-06-25  
> **版本**：P0

---

## 一、接口规范

### 1.1 请求头（登录接口）

```
Content-Type: application/json;charset=UTF-8
access_token: {token}
X-Platform: MINI | APP | H5
X-Device-Id: {deviceId}
```

### 1.2 响应格式

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

### 1.3 租户约定

- C 端 **不传全局租户 Header**。
- 扫码后前端保存 `currentTenantCode`（来自 landing 接口）。
- 领券/核销等接口 **Body 带 `tenantCode`**，后端强校验与券/入会关系一致。

### 1.4 免登录通道

须同时满足：

1. 后端路径 `/mobile/noAuth/marketing/**`
2. 前端 `skipAuth: true`

---

## 二、扫码落地（免登录）`noAuth/marketing/tenant`

**Controller**：`MarketingTenantNoAuthMobileController`

### 2.1 解析 scene 获取店铺信息

- **URL**：`GET /noAuth/marketing/tenant/landing`
- **认证**：免登录（`skipAuth: true`）

**Query**：

| 参数 | 必填 | 说明 |
|------|------|------|
| scene | ✅ | 小程序码 scene |

**响应 data**：

| 字段 | 说明 |
|------|------|
| tenantId | 店铺租户ID |
| tenantCode | 店铺租户编码 |
| tenantName | 店铺名称（来自 sys_tn_tenant_info） |
| marketingEnabled | 是否开通营销 |
| autoJoinOnQr | 是否扫码免审 |
| welcomeTitle / welcomeSubtitle | 落地文案 |
| logoUrl | Logo |
| channelCode | 解析出的渠道 |

---

## 三、店铺会员 `marketing/memberTenant`

**Controller**：`MemberTenantMobileController`  
**基础路径**：`/mobile/marketing/memberTenant`

### 3.1 扫码入会 / 绑定店铺

- **URL**：`POST /join`
- **认证**：需要登录

**请求体**：

```json
{
  "tenantCode": "T10086",
  "channelCode": "DEFAULT"
}
```

**响应**：绑定关系摘要；已绑定幂等返回成功。

### 3.2 我的店铺列表

- **URL**：`GET /myTenants`
- **认证**：需要登录

**响应 data**：`[{ tenantId, tenantCode, tenantName, joinDate, bindStatus }]`

---

## 四、店铺优惠券 `marketing/coupon`

**Controller**：`MarketingCouponMobileController`  
**基础路径**：`/mobile/marketing/coupon`  
**说明**：内部编排 `MemberCouponMobileApi`（coupon-api）

### 4.1 可领券列表

- **URL**：`POST /available`
- **认证**：需要登录

**请求体**：

```json
{
  "tenantCode": "T10086",
  "pageNo": 1,
  "pageSize": 10
}
```

**前置**：已入会该 `tenantCode`；仅返回该租户下 `STORE_OFFLINE` 场景且进行中的模板。

### 4.2 领取优惠券

- **URL**：`POST /receive`
- **认证**：需要登录

**请求体**：

```json
{
  "tenantCode": "T10086",
  "templateId": "模板ID"
}
```

### 4.3 我的优惠券（当前店铺）

- **URL**：`POST /myList`
- **认证**：需要登录

**请求体**：

```json
{
  "tenantCode": "T10086",
  "pageNo": 1,
  "pageSize": 10,
  "status": 0
}
```

`status`：0未用 1已用 2过期 3冻结 4作废。

### 4.4 券详情 / 卡面

- **URL**：`GET /detail?memberCouponId={id}&tenantCode={code}`
- **认证**：需要登录

### 4.5 到店核销动态码

- **URL**：`GET /verifyCode?memberCouponId={id}&tenantCode={code}`
- **认证**：需要登录
- **说明**：返回短时 token（如 60s）与二维码 payload，供店员扫描。

**响应 data**：

| 字段 | 说明 |
|------|------|
| verifyToken | 核销令牌 |
| expireAt | 过期时间戳 |
| qrcodeContent | 二维码内容 |

---

## 五、店员核销 `marketing/clerk/coupon`

**Controller**：`MarketingCouponVerifyMobileController`  
**基础路径**：`/mobile/marketing/clerk/coupon`

### 5.1 扫码核销

- **URL**：`POST /verify`
- **认证**：需要登录（店员账号，租户上下文=当前店铺）

**请求体**：

```json
{
  "tenantCode": "T10086",
  "verifyToken": "动态码令牌"
}
```

**校验**：

1. 店员租户 == `tenantCode`
2. 券 `tenant_id` == 该租户
3. 券未用、未过期
4. 幂等：同一 token 重复提交返回成功

**响应 data**：券名、会员脱敏信息、核销时间。

### 5.2 核销记录（店员/店长）

- **URL**：`POST /verifyRecords`
- **认证**：需要登录

**请求体**：分页 + `tenantCode` + 时间范围

---

## 六、Gateway 依赖与 Api 契约（P0）

**business-mobile-gateway/pom.xml** 须增加：

```xml
<dependency>
  <groupId>com.xinghuacuntravel</groupId>
  <artifactId>business-marketing-api</artifactId>
</dependency>
<dependency>
  <groupId>com.xinghuacuntravel</groupId>
  <artifactId>business-marketing-bean</artifactId>
</dependency>
```

**MarketingMobileApi**（business-marketing-api，由 ApiImpl 实现）：

| 方法 | 说明 |
|------|------|
| resolveLandingByScene(scene) | 扫码落地 |
| joinTenant(memberId, dto) | 入会 |
| listMyTenants(memberId) | 我的店铺 |
| pageAvailableCoupons(...) | 可领券 |
| receiveCoupon(...) | 领券 |
| pageMyCoupons(...) | 我的券 |
| getVerifyCode(...) | 动态核销码 |
| verifyCoupon(...) | 店员核销 |

---

## 七、coupon-api 扩展（P0，在 business-coupon 实现）

### MemberCouponLifecycleApi

```java
void offlineConfirmUsed(MemberCouponOfflineConfirmDTO dto);
```

**DTO 要点**：

| 字段 | 说明 |
|------|------|
| memberCouponId | 会员券ID |
| memberId | 会员ID |
| tenantId / tenantCode | 券归属租户 |
| verifyToken | 幂等号 |
| operatorId | 店员 |

---

## 八、白名单配置（web-starter）

在 `jeesharp.member-auth.sa-interceptor.exclude-path-patterns` 追加：

```yaml
- /mobile/noAuth/marketing/**
```

**勿** 放行 `/mobile/marketing/**` 整体（写操作须登录）。

---

## 九、接口地址速查表

| 操作 | 方法 | URL | 认证 |
|------|------|-----|------|
| 扫码落地 | GET | `/mobile/noAuth/marketing/tenant/landing` | 否 |
| 入会 | POST | `/mobile/marketing/memberTenant/join` | 是 |
| 我的店铺 | GET | `/mobile/marketing/memberTenant/myTenants` | 是 |
| 可领券 | POST | `/mobile/marketing/coupon/available` | 是 |
| 领券 | POST | `/mobile/marketing/coupon/receive` | 是 |
| 我的券 | POST | `/mobile/marketing/coupon/myList` | 是 |
| 券详情 | GET | `/mobile/marketing/coupon/detail` | 是 |
| 到店码 | GET | `/mobile/marketing/coupon/verifyCode` | 是 |
| 店员核销 | POST | `/mobile/marketing/clerk/coupon/verify` | 是 |
| 核销记录 | POST | `/mobile/marketing/clerk/coupon/verifyRecords` | 是 |

---

## 十、状态码

遵循 [mobile-api-rules](../../.cursor/rules/api/mobile-api-rules.mdc)：`200` 成功、`201` 需登录、`203` 参数错误等。

---

## 十一、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-06-25 | P0 初版 |