offerpai_backend/项目结构说明.md

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 等）

设计理念 – manager 模块把 C 端 与 B 端 共用的代码（如实体、Mapper、统一响应、拦截器、配置）集中放在 common，从而避免在两个子项目之间出现重复实现。client‑api 只负责面向用户的 API，manager 提供后台管理相关的功能；两者均通过 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/src/main/java/.../pojo/po/User.java	记录用户基础信息（手机号、邮箱、密码、昵称、微信绑定等），配合 UserMapper 完成持久化。
OssFile	manager/src/main/java/.../pojo/po/OssFile.java	描述 OSS（对象存储）中文件的元数据（路径、大小、标签等），通过 OssFileMapper 进行增删改查。
OssUrlVo	manager/src/main/java/.../pojo/vo/OssUrlVo.java	对外返回的 OSS 访问 URL 结构体，供前端直接使用。
LoginVo	client-api/src/main/java/.../pojo/vo/LoginVo.java	登录成功后返回的用户信息（userId、nick）。
SmsLoginDto	client-api/src/main/java/.../pojo/dto/SmsLoginDto.java	短信验证码登录的请求参数（mobileNumber、code）。

这些实体位于 manager，因为它们属于业务模型，manager 负责提供完整的业务实现；同时它们可以被 C 端（如 client‑api）直接调用，体现了 B 端 + C 端共享的设计初衷。

4️⃣ 共享技术栈（位于 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
这些设施在 C 端 与 B 端 中统一使用，确保技术栈、日志、异常、配置保持一致。

5️⃣ 构建与运行

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

6️⃣ 小结

• 项目采用 三层结构：
  1. client‑api → 只负责 C 端 REST 接口。
  2. manager → 包含业务实体、Mapper 与业务 API，既供 B 端（后台）使用，也供 C 端直接调用；因此是 B 端 + C 端共享层。
  3. common → 所有层共同依赖的底层设施（配置、工具、拦截、异常、支付、邮件等），实现“一次实现、全局共享”。
• 这种布局把 业务实现 与 技术支撑 明确分离，后续在 C 端或 B 端新增功能时，只需在 manager 中编写业务代码，common 负责统一的技术支撑，避免代码重复、提高维护效率。