meal_manager/jeesharp-business/business-mobile-gateway

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	全部标记已读

依赖说明

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

短信验证码配置

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

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。

第三方登录配置（JustAuth）

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

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

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

更新日志

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

---

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

本节记录"未登录也能访问"的接口集合，与 web-starter/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 端支付成功统一入口） /mobile/order/pay/notify/wechat/refund（商城退款）	第三方异步通知，无 Token
首页基础	/mobile/home/** /mobile/setting/homeBanner/** /mobile/setting/homeGridIntro/**	壳层 / 轮播 / 宫格介绍
公开内容 / 资讯	/mobile/setting/travelNews/** /mobile/setting/travelStrategy/** /mobile/setting/aboutUs/** /mobile/setting/helpCenter/** /mobile/setting/privacyPolicy/** /mobile/notice/** /mobile/marketing/**	资讯 / 攻略 / 关于我们 / 帮助中心 / 协议 / 公告 / 推广
公开浏览类业务	/mobile/village/** /mobile/heritage/** /mobile/culture/** /mobile/hotel/** /mobile/food/** /mobile/leisure/** /mobile/study/** /mobile/yearcard/** /mobile/explain/** /mobile/guide/** /mobile/scenic/**	仅展示用，下单/收藏等写操作走前端登录拦截

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

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

4. 前端协同：skipAuth: true

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

// 示例：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/ 开头：

   @RequestMapping("${jeesharp.web.mobilePath}/noAuth/{业务模块}/{方法}")
   

2. 前端请求 skipAuth: true：

   get('/noAuth/...', params, { skipAuth: true })
   

3. 后端通配 /mobile/noAuth/** 已永久放行，无需改 yaml。

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