# 会员营销模块 (business-marketing)

## 模块概述

会员营销模块为 **店铺租户（`sys_tn_tenant_info`）** 提供扫码入会、店铺券领取、到店线下核销与数据统计能力。优惠券规则与状态机 **复用 `business-coupon`**，通过 **`business-coupon-api`** 调用，本模块负责租户上下文、入会关系与核销流水。

**店铺 = 商户租户**，数据隔离键为 **`tenant_id` / `tenant_code`**。C 端会员账号为平台级 **`app_member`**，多店入会通过 **`app_member_tenant`** 承载。

## 模块结构

```
business-marketing/
├── business-marketing-bean/          # Entity、DTO、VO、Convert、Enum
├── business-marketing-api/           # MarketingMobileApi 等（gateway 仅依赖此 jar）
├── business-marketing-service/       # Domain Service + Mapper
├── business-marketing-application/   # ApplicationService、ApiImpl、Support
├── business-marketing-controller/    # 管理端 REST
├── src/main/resources/sql/
│   ├── marketing.sql
│   ├── marketing_coupon_scene_seed.sql
│   └── marketing_menu_permission.sql
├── README.md
├── 后台接口文档.md
└── 移动端接口文档.md
```

移动端 HTTP 入口在 **`business-mobile-gateway`**；Maven 依赖 **`business-marketing-api`** + **`business-marketing-bean`**。

## 架构与调用链

```
管理端：Controller → ApplicationService → Domain Service → Mapper
移动端：MobileController → MarketingMobileApi(ApiImpl) → ApplicationService → …
跨模块：Application → business-coupon-api / business-member-service（禁止依赖 *-application）
```

详见设计说明与 `doc/优惠券架构设计.md`（在线核销）并行 **线下核销** 路径。

## 核心数据表

| 表 | 说明 |
|----|------|
| `sys_tn_tenant_info` | 店铺主数据（平台表，本模块只读） |
| `app_member_tenant` | 会员-店铺租户关系 |
| `cfg_marketing_tenant_ext` | 营销扩展配置 |
| `cfg_marketing_tenant_qrcode` | 推广二维码 |
| `app_member_coupon_verify_log` | 线下核销流水 |
| `app_coupon_template` / `app_member_coupon` | 券（coupon 模块，`tenant_id` 表店铺） |

## 功能特性（P0）

| 能力 | 说明 |
|------|------|
| 扫码落地 | noAuth 解析 scene → 店铺信息 |
| 扫码入会 | 写 `app_member_tenant`，支持免审直绑 |
| 店铺领券 | 编排 coupon-api，校验已入会 + 租户 |
| 我的卡包 | 按 `tenantCode` 过滤 |
| 到店核销码 | 短时动态 token |
| 店员核销 | 校验租户一致 + coupon-api 置已用 + 流水 |
| 统计看板 | 入会/领券/核销按租户聚合 |

## API 文档

- [后台接口文档.md](./后台接口文档.md)
- [移动端接口文档.md](./移动端接口文档.md)

## 权限配置

见 [后台接口文档.md](./后台接口文档.md) §权限标识汇总。

## 依赖模块

| 模块 | 用途 |
|------|------|
| `business-coupon-api` | 领券、查券、线下置已用（`MemberCouponLifecycleApi` P0 扩展） |
| `business-member-service` | 会员、`enrichMemberDisplay` |
| `business-wechat`（可选） | 生成小程序码 |

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-06-25 | P0 模块骨架、建表脚本、接口文档 |