meal_manager/jeesharp-business/business-marketing/移动端接口文档.md

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

模块：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 响应格式

{
  "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
• 认证：需要登录

请求体：

{
  "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
• 认证：需要登录

请求体：

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

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

4.2 领取优惠券

• URL：POST /receive
• 认证：需要登录

请求体：

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

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

• URL：POST /myList
• 认证：需要登录

请求体：

{
  "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
• 认证：需要登录（店员账号，租户上下文=当前店铺）

请求体：

{
  "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 须增加：

<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

void offlineConfirmUsed(MemberCouponOfflineConfirmDTO dto);

DTO 要点：

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

---

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

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

- /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：200 成功、201 需登录、203 参数错误等。

---

十一、更新日志

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