# business-mobile-gateway

> 移动端网关模块 - 为 APP/小程序/H5 提供统一接口

## 模块说明

`business-mobile-gateway` 是所有业务模块对移动端（APP、微信小程序、H5）提供接口的汇总模块。

## 目录结构

```
business-mobile-gateway/
├── src/main/java/com/jeesharp/business/mobile/
│   └── member/                           # 会员模块移动端接口
│       ├── controller/                   # 控制器
│       │   ├── MobileAuthController.java      # 登录认证
│       │   ├── MobileMemberController.java    # 会员信息
│       │   ├── MobileUserCenterController.java # 用户中心
│       │   ├── MobilePointsController.java    # 积分
│       │   ├── MobileCouponController.java    # 优惠券
│       │   ├── MobileBalanceController.java   # 余额
│       │   ├── MobileGrowthController.java    # 成长值
│       │   └── MobileMessageController.java   # 消息通知
│       ├── dto/                          # 请求数据传输对象
│       │   ├── SendSmsCodeDTO.java
│       │   ├── LoginByMobileDTO.java
│       │   ├── LoginByPasswordDTO.java
│       │   ├── LoginByWechatMiniDTO.java
│       │   ├── LoginByWechatDTO.java
│       │   ├── LoginByAlipayDTO.java
│       │   ├── LoginByAppleDTO.java
│       │   ├── LoginByThirdPartyDTO.java
│       │   ├── LoginByOneClickDTO.java
│       │   ├── RefreshTokenDTO.java
│       │   ├── BindMobileDTO.java
│       │   ├── ChangePasswordDTO.java
│       │   ├── ResetPasswordDTO.java
│       │   ├── CancelAccountDTO.java
│       │   ├── UpdateMemberDTO.java
│       │   └── RealNameAuthDTO.java
│       └── vo/                           # 响应视图对象
│           ├── LoginResultVO.java
│           ├── MemberDetailVO.java
│           ├── UserCenterVO.java
│           ├── PointsSummaryVO.java
│           ├── BalanceSummaryVO.java
└── pom.xml
```

## URL 规范

```
/mobile/{模块名}/{类名}/{操作}
```

**示例**：
- `/mobile/member/auth/loginByMobile` - 手机验证码登录
- `/mobile/member/member/info` - 获取会员信息
- `/mobile/member/points/signIn` - 签到

## 接口概览

### 登录认证（/mobile/member/auth）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/sendSmsCode` | POST | 发送短信验证码 |
| `/loginByMobile` | POST | 手机验证码登录 |
| `/loginByPassword` | POST | 账号密码登录 |
| `/loginByWechatMini` | POST | 微信小程序登录 |
| `/loginByWechatApp` | POST | 微信APP登录 |
| `/loginByWechatMp` | POST | 微信公众号登录 |
| `/loginByAlipay` | POST | 支付宝登录 |
| `/loginByApple` | POST | 苹果登录 |
| `/loginByHuawei` | POST | 华为登录 |
| `/loginByQQ` | POST | QQ登录 |
| `/loginByWeibo` | POST | 微博登录 |
| `/loginByDouyin` | POST | 抖音登录 |
| `/loginByOneClick` | POST | 一键登录 |
| `/refreshToken` | POST | 刷新Token |
| `/logout` | POST | 退出登录 |
| `/cancel` | POST | 注销账号 |
| `/bindMobile` | POST | 绑定手机号 |
| `/changePassword` | POST | 修改密码 |
| `/resetPassword` | POST | 重置密码 |
| `/publicKey` | GET | 获取加密公钥 |

### 会员信息（/mobile/member/member）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/info` | GET | 获取当前会员信息 |
| `/update` | POST | 更新会员信息 |
| `/realNameAuth` | POST | 实名认证 |
| `/levelInfo` | GET | 获取等级详情 |
| `/inviteInfo` | GET | 获取邀请信息 |
| `/inviteList` | POST | 获取邀请记录 |

### 用户中心（/mobile/member/userCenter）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/index` | GET | 获取用户中心首页数据（全量） |
| `/indexSimple` | GET | 获取用户中心首页数据（简化版） |
| `/profile` | GET | 获取个人信息详情 |
| `/updateProfile` | POST | 修改个人信息 |
| `/updateAvatar` | POST | 修改头像 |
| `/updateNickname` | POST | 修改昵称 |
| `/realNameStatus` | GET | 获取实名认证状态 |
| `/realNameAuth` | POST | 实名认证 |
| `/security` | GET | 获取账户安全信息 |
| `/assets` | GET | 获取资产概览 |
| `/level` | GET | 获取会员等级信息 |
| `/orderStats` | GET | 获取订单统计 |
| `/functions` | GET | 获取常用功能列表 |

### 积分（/mobile/member/points）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/summary` | GET | 获取积分概览 |
| `/list` | POST | 获取积分流水 |
| `/signIn` | POST | 签到 |
| `/signInStatus` | GET | 获取签到状态 |

### 消费券模板（/mobile/coupon，兼容小程序 GET）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/templates` | GET | 模板列表（免登录可浏览；已登录合并已领状态） |
| `/template/{id}` | GET | 模板详情 |

### 消费券模板（/mobile/coupon/couponTemplate，规范路径）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/list` | POST | 模板分页（Body：`CouponTemplateQueryVO`，仅进行中且在领取窗口内） |
| `/info` | GET | 模板详情，`id` 查询参数 |

### 优惠券（/mobile/member/coupon）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/available` | POST | 可领取优惠券列表 |
| `/receive` | POST | 领取优惠券 |
| `/my` | POST | 我的优惠券列表 |
| `/myList` | POST | 同 `/my`（与设计文档路径示例对齐） |
| `/detail` | GET | 优惠券详情 |
| `/walletDetail` | GET | 已领券卡面详情（`CouponDemoVO`，`memberCouponId`） |
| `/usable` | POST | 订单可用优惠券 |
| `/exchange` | POST | 积分兑换优惠券 |

### 余额（/mobile/member/balance）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/summary` | GET | 获取余额概览 |
| `/list` | POST | 获取余额流水 |
| `/recharge` | POST | 余额充值下单 |

### 成长值（/mobile/member/growth）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/list` | POST | 获取成长值流水 |

### 消息通知（/mobile/member/message）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/list` | POST | 获取消息列表 |
| `/unreadCount` | GET | 获取未读消息数 |
| `/read` | POST | 标记消息已读 |
| `/readAll` | POST | 全部标记已读 |

## 依赖说明

```xml
<dependency>
    <groupId>org.jeesharp.boot</groupId>
    <artifactId>business-mobile-gateway</artifactId>
</dependency>
```

## 短信验证码配置

验证码发送依赖 `jeesharp-spring-boot-starter-sms`，需在 `application.yml` 中配置：

```yaml
jeesharp:
  sms:
    provider: MOCK   # 开发环境用 MOCK，生产用 ALIBABA/TENCENT/HUAWEI
    scene-template-mapping:
      login: SMS_xxx      # 登录验证码模板
      register: SMS_xxx   # 注册验证码模板
      reset_pwd: SMS_xxx  # 重置密码模板
      bind: SMS_xxx      # 绑定手机模板
    alibaba:             # 使用阿里云时配置
      access-key-id: xxx
      access-key-secret: xxx
      sign-name: "【您的签名】"
```

详见 [jeesharp-spring-boot-starter-sms README](../../jeesharp-framework/jeesharp-spring-boot-starter-sms/README.md)。

## 第三方登录配置（JustAuth）

本模块已集成 JustAuth SDK，支持多种第三方登录方式。需在 `application.yml` 中配置：

```yaml
jeesharp:
  oauth:
    # 微信小程序配置
    wechatMini:
      appId: your_miniapp_appid
      secret: your_miniapp_secret
    
    # 微信公众号配置
    wechat:
      clientId: your_mp_appid
      clientSecret: your_mp_secret
      redirectUri: https://your-domain.com/callback/wechat
    
    # 微信开放平台（APP）配置
    wechatApp:
      clientId: your_open_appid
      clientSecret: your_open_secret
      redirectUri: https://your-domain.com/callback/wechat-app
    
    # QQ登录配置
    qq:
      clientId: your_qq_appid
      clientSecret: your_qq_appkey
      redirectUri: https://your-domain.com/callback/qq
    
    # 支付宝登录配置
    alipay:
      clientId: your_alipay_appid
      clientSecret: your_alipay_private_key
      redirectUri: https://your-domain.com/callback/alipay
      alipayPublicKey: your_alipay_public_key
    
    # 微博登录配置
    weibo:
      clientId: your_weibo_appkey
      clientSecret: your_weibo_secret
      redirectUri: https://your-domain.com/callback/weibo
    
    # 抖音登录配置
    douyin:
      clientId: your_douyin_client_key
      clientSecret: your_douyin_client_secret
      redirectUri: https://your-domain.com/callback/douyin
    
    # 华为登录配置
    huawei:
      clientId: your_huawei_client_id
      clientSecret: your_huawei_client_secret
      redirectUri: https://your-domain.com/callback/huawei
```

**注意事项**：
- 微信小程序登录使用微信官方 API，不依赖 JustAuth
- 苹果登录暂未实现（需要对接 Apple 官方 API）
- 各平台的 AppId、Secret 等需要在对应开放平台申请
- redirectUri 需要与开放平台配置的回调地址一致

## TODO

- [x] 实现 `MobileAuthService` 认证服务
- [x] 集成短信网关（jeesharp-spring-boot-starter-sms）发送验证码
- [x] 集成 JustAuth SDK 实现第三方登录（微信、QQ、支付宝、微博、抖音、华为）
- [x] 实现微信小程序登录（使用微信官方 API）
- [ ] 实现苹果登录（Apple Sign In）
- [ ] 实现一键登录（运营商SDK）
- [x] 实现签到逻辑（MemberSignInApplicationService + `app_member_sign_in_record`）
- [ ] 实现优惠券服务
- [ ] 实现消息推送服务

## 更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 3.0.1 | 2026-01-24 | 初始版本，包含会员模块移动端接口框架 |


---

## 移动端登录鉴权白名单（v1.0 / 2026-05-29）

本节记录"未登录也能访问"的接口集合，与 [web-starter/application.yaml](../../web-starter/src/main/resources/application.yaml) 中 `jeesharp.member-auth.sa-interceptor.exclude-path-patterns` 一一对应。

### 1. 平台机制

接口免登录由三个层次共同保障：

| 层 | 作用范围 | 配置入口 |
| --- | --- | --- |
| Spring Security `permitAllUrls` | URL 级匿名访问 | `jeesharp.security.permitAllUrls` |
| Sa-Token `SaInterceptor` | 校验登录态 | `jeesharp.member-auth.sa-interceptor.exclude-path-patterns` |
| Sa-Token `@SaIgnore` 注解 | 类/方法级精确跳过 | Controller 注解 |

⚠️ `application.yaml` 中的 `exclude-path-patterns` 需要平台核心 starter ≥ `3.0.1-Beta-22`（已支持 `SaInterceptorProperties` 合并默认值）才会生效。

### 2. 白名单分类

| 分类 | 路径 | 说明 |
| --- | --- | --- |
| **登录与注册** | `/mobile/member/auth/**` | 短信验证码、各类登录、刷新 Token |
| **通用免登录通道** | `/mobile/noAuth/**` | 开机动画 SplashAd、首页弹窗 OperationPopup 等 |
| **支付回调** | `/mobile/pay/notify/**`（C 端支付成功统一入口）<br>`/mobile/order/pay/notify/wechat/refund`（商城退款） | 第三方异步通知，无 Token |
| **首页基础** | `/mobile/home/**`<br>`/mobile/setting/homeBanner/**`<br>`/mobile/setting/homeGridIntro/**` | 壳层 / 轮播 / 宫格介绍 |
| **公开内容 / 资讯** | `/mobile/setting/travelNews/**`<br>`/mobile/setting/travelStrategy/**`<br>`/mobile/setting/aboutUs/**`<br>`/mobile/setting/helpCenter/**`<br>`/mobile/setting/privacyPolicy/**`<br>`/mobile/notice/**`<br>`/mobile/marketing/**` | 资讯 / 攻略 / 关于我们 / 帮助中心 / 协议 / 公告 / 推广 |
| **公开浏览类业务** | `/mobile/village/**`<br>`/mobile/heritage/**`<br>`/mobile/culture/**`<br>`/mobile/hotel/**`<br>`/mobile/food/**`<br>`/mobile/leisure/**`<br>`/mobile/study/**`<br>`/mobile/yearcard/**`<br>`/mobile/explain/**`<br>`/mobile/guide/**`<br>`/mobile/scenic/**` | 仅展示用，下单/收藏等写操作走前端登录拦截 |

### 3. 仍需登录的接口（务必保留鉴权）

| 业务 | 路径 | 原因 |
| --- | --- | --- |
| 个人中心 | `/mobile/member/userCenter/**`<br>`/mobile/member/member/**`<br>`/mobile/member/coupon/**`<br>`/mobile/member/favorite/**`<br>`/mobile/member/vipIap/**`<br>`/mobile/member/message/**` | 与当前登录会员强绑定 |
| 订单 / 交易 | `/mobile/mallOrder/**`<br>`/mobile/tradeOrder/**`<br>`/mobile/order/**`（除支付回调）<br>`/mobile/address/**` | 写操作，必须实名/实人 |
| 评价 / 反馈 | `/mobile/review/review/**` | 防垃圾评论 |
| 各业务下单接口 | `*/booking/create`、`*/enroll` 等 | 业务侧用 `@SaCheckLogin` 控制 |

### 4. 前端协同：`skipAuth: true`

[uni-app 请求拦截器](../../../xinghuacun_travel_mini_app/src/utils/request.ts) 默认会带上本地 Token，当 Token 过期时即便后端放行，starter 解析失败仍会抛 `code:201`。前端**所有免登录接口**必须显式声明 `skipAuth: true`，请求时不带 Authorization 头：

```ts
// 示例：splashAd.ts
return get<SplashAdClientBundleVO>(path, undefined, {
  showLoading: false,
  showErrorToast: false,
  skipAuth: true   // ← 不带 Authorization 头
})
```

`responseInterceptor` 在 `skipAuth: true` 时遇到 201 也**不会强制 reLaunch 登录页**，由调用方静默兜底。

已加 `skipAuth: true` 的模块清单：

| 文件 | 接口 |
| --- | --- |
| splashAd.ts | getSplashAdCurrent |
| homeShell.ts / homeBanners.ts | fetchHomeShell / fetchHomeBanners |
| homeGridIntro.ts | list / detail |
| homeEntryPopup.ts | fetchHomeEntryPopup |
| notice.ts | list / detail |
| privacyPolicy.ts | fetchPrivacyPolicyByCode |
| cultureActivity.ts | activities / activity detail |
| heritage.ts | culture-products / projects（列表 + 详情） |
| village.ts | destinations 列表 + 详情 |
| hotel.ts | stays 列表 + 详情 |
| food.ts | restaurants 列表 + 详情 |
| leisure.ts | venues 列表 + 详情 |
| yearcard.ts | products 列表 + 详情（仅商品浏览） |
| study.ts | programs 列表 + 详情 |
| explain.ts | spots 列表 + 详情 + byGuidePoi |
| travelStrategy.ts | hotList / page / detail |
| marketing.ts | activity list / activity detail |
| guidePois.ts | fetchGuidePois / fetchGuidePoiById |
| aboutUs.ts | fetchAboutUsInfo |

### 5. 未来约定（强制）

凡新建移动端免登录接口，**必须**遵循：

1. 后端路径以 `/mobile/noAuth/` 开头：
   ```java
   @RequestMapping("${jeesharp.web.mobilePath}/noAuth/{业务模块}/{方法}")
   ```
2. 前端请求 `skipAuth: true`：
   ```ts
   get('/noAuth/...', params, { skipAuth: true })
   ```
3. 后端通配 `/mobile/noAuth/**` 已永久放行，**无需改 yaml**。

这是项目"零配置免登录通道"，避免每次添加白名单都要改 starter 或 yaml，规避路径打错、yaml 缩进错、热加载不生效等坑。