OfferPie Back‑End 项目结构说明

@zk

1️⃣ 项目整体层次

offerpie/back-end
│
├─ pom.xml                     # 父 Maven 项目，统一管理依赖、插件、属性
│
├─ client‑api/                 # **C 端**（面向用户）API 服务
│   ├─ pom.xml
│   └─ src/main/java
│       └─ org.jiayunet
│           ├─ ClientApplication.java      # Spring Boot 主入口
│           ├─ annotation/
│           │   └─ FuncPermission.java     # 功能权限校验注解（标记在Controller方法上）
│           ├─ aop/
│           │   └─ FuncPermissionAspect.java  # 功能权限校验切面（拦截注解，校验+扣减+异常回退）
│           ├─ controller/
│           │   ├─ LoginController.java    # 登录相关接口（发送验证码、短信登录）
│           │   └─ RouteMenuController.java # 路由菜单接口（获取用户有效菜单树）
│           ├─ server/
│           │   ├─ LoginServer.java        # 登录业务逻辑（验证码校验、自动注册、JWT生成、Cookie设置）
│           │   ├─ FuncPermissionServer.java  # 功能权限服务（校验、扣减、查询、添加库存、回退）
│           │   ├─ RouteMenuServer.java    # 路由菜单服务（查询、添加库存、获取用户菜单树）
│           │   └─ WxPayNotifyMessageAbstractImpl.java  # 微信支付回调实现
│           └─ pojo/
│               ├─ dto/
│               │   └─ SmsLoginDto.java    # 短信登录入参（mobileNumber + code）
│               └─ vo/
│                   ├─ LoginVo.java        # 登录返回（userId + nick）
│                   └─ RouteMenuVo.java    # 路由菜单树形VO（含children子菜单）
│
├─ common/                     # **共享层**：被 C 端和 B 端共同使用的代码库
│   ├─ pom.xml
│   └─ src/main/java
│       └─ org.jiayunet
│           ├─ config/                # OSS、Redis、Security、WxPay、Sms 等统一配置
│           ├─ tool/                  # Http、IP、Redis、认证、验证码等工具类
│           ├─ interceptor/           # 全局拦截器（日志、TraceId、黑名单、SQL 统计等）
│           ├─ aop/                   # AOP 日志切面
│           ├─ exception/             # 业务异常统一处理
│           ├─ email/                 # 邮件发送抽象（EmailAbility）
│           ├─ wxPay/                 # 微信支付相关能力（Js、Native、Transfer 等）
│           ├─ pojo/                  # 公共 POJO（统一响应、登录/防重放 token 等）
│           └─ web/                   # Spring MVC 全局响应体 advice
│
└─ manager/                    # **B 端 + C 端共享** 的业务实现（尚未搭建完整的 B 端 UI）
    ├─ pom.xml
    └─ src/main/java
        └─ org.jiayunet
            ├─ constant/             # 常量枚举（OSS路径、短信模板等）
            ├─ controller/           # 对外 REST 接口（HealthCheck、Oss 等）
            ├─ mapper/               # MyBatis Mapper
            │   ├─ UserMapper.java
            │   ├─ OssFileMapper.java
            │   ├─ RouteMenuMapper.java              # 路由菜单Mapper
            │   ├─ FuncPermissionMapper.java          # 功能权限Mapper
            │   ├─ UserRouteMenuStockMapper.java      # 用户路由菜单库存Mapper
            │   └─ UserFuncPermissionStockMapper.java # 用户功能权限库存Mapper
            ├─ pojo/
            │   ├─ po/               # 持久化实体
            │   │   ├─ User.java
            │   │   ├─ OssFile.java
            │   │   ├─ RouteMenu.java                # 路由菜单表（bg_route_menu）
            │   │   ├─ FuncPermission.java            # 功能权限表（bg_func_permission）
            │   │   ├─ UserRouteMenuStock.java        # 用户路由菜单库存表（bg_user_route_menu_stock）
            │   │   └─ UserFuncPermissionStock.java   # 用户功能权限库存表（bg_user_func_permission_stock）
            │   └─ vo/               # ViewObject（OssUrlVo 等）
            └─ server/               # 业务 Service（OssServer、SmsServer 等）

设计理念 – 业务实体和 Mapper 位于 manager，B 端和 C 端共享；C 端特有的注解、切面、权限服务、路由菜单服务位于 client-api，避免 B 端误用；common 提供统一的技术支撑。

2️⃣ 各层模块职责

层级	主要职责	关键类/包
client-api	- 面向终端用户的 REST API - 启动 Spring Boot 应用 - 短信验证码登录（含自动注册） - 功能权限校验：注解 + 切面 + 权限服务（校验、扣减、回退） - 路由菜单：获取用户有效菜单树	`ClientApplication`、`LoginController`、`RouteMenuController`、`FuncPermission`、`FuncPermissionAspect`、`FuncPermissionServer`、`RouteMenuServer`、`RouteMenuVo`
common	- 统一配置：OSS、Redis、Security、WxPay、Sms 等 - 跨层工具：HTTP、IP、认证、验证码、Redis Server 等 - 全局拦截/切面：日志、TraceId、黑名单、SQL 打印 - 统一异常/响应：`GlobalExceptionAdvice`、`UnifiedResponse` - 业务抽象：邮件发送、微信支付（Native/JS/Transfer） - 公共 POJO：登录令牌、防重放信息等	`config/`, `tool/`, `interceptor/`, `aop/`, `exception/`, `email/`, `wxPay/`, `pojo/`
manager	- 业务实体（`User`、`OssFile`、`RouteMenu`、`FuncPermission`、`UserRouteMenuStock`、`UserFuncPermissionStock`） - MyBatis Mapper（`UserMapper`、`OssFileMapper`、`RouteMenuMapper`、`FuncPermissionMapper`、`UserRouteMenuStockMapper`、`UserFuncPermissionStockMapper`） - 业务 API：文件上传/下载、健康检查等 - 业务逻辑：服务层、工具类等 - 既供 B 端 UI（待实现）使用，也供 C 端业务直接调用	`controller/`, `mapper/`, `pojo/po/`, `pojo/vo/`, `server/`, `constant/`

3️⃣ 关键业务实体

实体	所属模块	作用概述
`User`	manager	记录用户基础信息（手机号、邮箱、密码、昵称、微信绑定等），配合 `UserMapper` 完成持久化。
`OssFile`	manager	描述 OSS（对象存储）中文件的元数据（路径、大小、标签等），通过 `OssFileMapper` 进行增删改查。
`RouteMenu`	manager	路由菜单表（bg_route_menu），支持多级树形结构，通过 rootId/parentId 表达层级关系，openAccess 标识是否公开免费。
`FuncPermission`	manager	功能权限表（bg_func_permission），定义功能点编码（func_code，最长12字符，唯一约束）。
`UserRouteMenuStock`	manager	用户路由菜单库存表（bg_user_route_menu_stock），记录用户拥有的菜单权限，支持时间维度。
`UserFuncPermissionStock`	manager	用户功能权限库存表（bg_user_func_permission_stock），记录用户拥有的功能权限，支持时间/次数/复合维度。
`RouteMenuVo`	client-api	路由菜单树形VO，包含 children 子菜单列表，供前端渲染动态路由。
`LoginVo`	client-api	登录成功后返回的用户信息（userId、nick）。
`SmsLoginDto`	client-api	短信验证码登录的请求参数（mobileNumber、code）。

4️⃣ 权限体系设计

整体架构

前端：路由控制菜单/页面可见性，登录后拉取用户有效菜单树（含公开免费菜单 + 库存授权菜单）
后端：AOP 切面拦截 @FuncPermission 注解，校验权限 + 扣减库存，业务异常自动回退次数
权限来源：商品模块下单成功后写入库存表，权限框架不关心来源

数据库表（4张）

表名	说明
`bg_route_menu`	路由菜单定义（树形结构，open_access 标识公开免费菜单）
`bg_user_route_menu_stock`	用户路由菜单库存（时间维度）
`bg_func_permission`	功能权限定义（func_code 唯一）
`bg_user_func_permission_stock`	用户功能权限库存（时间/次数/复合维度）

库存维度

time_limit + expire_time：时间维度，0=不限时，1=限时
count_limit + remain_count：次数维度，0=不限次，1=限次
两个维度独立控制，组合形成四种模式：永久不限次、限时不限次、永久限次、限时限次
添加库存时不降级：已经不限时/不限次的不会被覆盖

切面校验流程

拿注解上的 funcCode + 当前登录用户 userId
查库存表（唯一索引 userId + funcCode）
无记录 → 无权限
time_limit=1 且过期 → 已过期
count_limit=0 → 直接放行
count_limit=1 → SQL 原子扣减 remain_count = remain_count - 1（WHERE remain_count > 0）
业务方法异常 → 自动回退次数

5️⃣ 共享技术栈（位于 `common`）

类别	关键实现	位置
配置	`OssConfig`, `RedissonConf`, `SecurityConfig`, `WxPayConfig`, `SmsConfig`	`common/config`
安全	JWT 过滤器、登录令牌 (`RedisLoginTokenInfo`)、防重放 (`RedisPreventReplayInfo`)	`common/interceptor`、`common/pojo/interceptor`
邮件	`EmailAbility`（封装邮件发送）	`common/email`
微信支付	`WxJsPayAbility`, `WxNativePayAbility`, `WxTransferPayAbility`, `WxPayNotifyController`	`common/wxPay`
全局异常	`GlobalExceptionAdvice`, `BusinessException`, `BusinessExpCodeEnum`	`common/exception`
日志 & AOP	`ControllerLogAspect`, `LoggingOriginalRequestFilter`, `SqlLoggerInterceptor`	`common/aop`, `common/interceptor`
工具类	`HttpTool`, `HttpIpTool`, `AuthenticTool`, `ObjectTool`, `VerifyImageCodeUtils`	`common/tool`
统一返回体	`UnifiedResponse`, `UnifiedResponseBodyAdvice`	`common/pojo`, `common/web`
批量/更新	`UpdateBatchMethod`（批量更新策略）	`common/config`

6️⃣ 构建与运行

父 POM（back-end/pom.xml）统一管理子模块的依赖与插件。
子模块 (client-api, common, manager) 均可单独 mvn clean install，生成各自的 jar 包。
启动入口：运行 client-api 中的 ClientApplication，Spring Boot 会自动扫描并加载 common（配置、拦截、工具）以及 manager 中声明的 Mapper 与 Service。

7️⃣ 小结

项目采用 三层结构：
1. client-api → C 端 REST 接口 + 功能权限校验（注解/切面/服务） + 路由菜单服务。
2. manager → 业务实体、Mapper 与业务 API，B 端 + C 端共享层。
3. common → 所有层共同依赖的底层设施（配置、工具、拦截、异常、支付、邮件等）。
权限体系分两层：前端路由控制菜单可见性，后端切面控制功能点权限与库存扣减。
权限和菜单作为商品维度，框架只负责校验和库存管理，不关心权限来源。

11 KiB Raw Blame History Unescape Escape

OfferPie Back‑End 项目结构说明

1️⃣ 项目整体层次

2️⃣ 各层模块职责

3️⃣ 关键业务实体

4️⃣ 权限体系设计

整体架构

数据库表（4张）

库存维度

切面校验流程

5️⃣ 共享技术栈（位于 common）

6️⃣ 构建与运行

7️⃣ 小结

11 KiB

Raw Blame History

5️⃣ 共享技术栈（位于 `common`）