210 lines
18 KiB
Markdown
210 lines
18 KiB
Markdown
---
|
||
inclusion: manual
|
||
---
|
||
|
||
# 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 # 路由菜单接口（获取用户有效菜单树）
|
||
│ ├─ service/
|
||
│ │ ├─ LoginService.java # 登录业务逻辑（验证码校验、自动注册、JWT生成、Cookie设置）
|
||
│ │ ├─ UserRegisterService.java # 用户注册服务（注册逻辑、邀请码生成与绑定）
|
||
│ │ ├─ FuncPermissionService.java # 功能权限服务（校验、扣减、查询、添加库存、回退）
|
||
│ │ ├─ RouteMenuService.java # 路由菜单服务（查询、添加库存、获取用户菜单树）
|
||
│ │ └─ WxPayNotifyMessageAbstractImpl.java # 微信支付回调实现
|
||
│ └─ pojo/
|
||
│ ├─ dto/
|
||
│ │ └─ SmsLoginDto.java # 短信登录入参（mobileNumber + code + inviteCode）
|
||
│ └─ 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）
|
||
│ ├─ ai/ # AI 对话能力封装（AiChatAbility、AiChatConfig）
|
||
│ ├─ 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
|
||
│ ├─ UserInviteMapper.java # 用户邀请记录Mapper
|
||
│ ├─ RouteMenuMapper.java # 路由菜单Mapper
|
||
│ ├─ FuncPermissionMapper.java # 功能权限Mapper
|
||
│ ├─ UserRouteMenuStockMapper.java # 用户路由菜单库存Mapper
|
||
│ ├─ UserFuncPermissionStockMapper.java # 用户功能权限库存Mapper
|
||
│ ├─ UserFuncUsageLogMapper.java # 用户功能使用记录Mapper
|
||
│ ├─ ChinaRegionsCodeMapper.java # 地区Mapper
|
||
│ ├─ JobCategoryMapper.java # 岗位类型Mapper
|
||
│ ├─ CompanyMapper.java # 公司Mapper
|
||
│ ├─ JobMapper.java # 岗位Mapper
|
||
│ ├─ JobRegionRelationMapper.java # 岗位-地区关联Mapper
|
||
│ ├─ JobSkillTagRelationMapper.java # 岗位-技能标签关联Mapper
|
||
│ ├─ IndustryMapper.java # 行业Mapper
|
||
│ ├─ SkillTagMapper.java # 技能标签Mapper
|
||
│ ├─ UserJobFavoriteMapper.java # 用户收藏岗位Mapper
|
||
│ ├─ UserJobApplicationMapper.java # 用户投递记录Mapper
|
||
│ ├─ UserJobDislikeMapper.java # 用户不感兴趣记录Mapper
|
||
│ └─ AppJobDataMapper.java # 爬虫岗位原始数据Mapper
|
||
├─ pojo/
|
||
│ ├─ po/ # 持久化实体
|
||
│ │ ├─ User.java
|
||
│ │ ├─ OssFile.java
|
||
│ │ ├─ UserInvite.java # 用户邀请记录表（bg_user_invite）
|
||
│ │ ├─ RouteMenu.java # 路由菜单表（bg_route_menu）
|
||
│ │ ├─ FuncPermission.java # 功能权限表（bg_func_permission）
|
||
│ │ ├─ UserRouteMenuStock.java # 用户路由菜单库存表（bg_user_route_menu_stock）
|
||
│ │ ├─ UserFuncPermissionStock.java # 用户功能权限库存表（bg_user_func_permission_stock）
|
||
│ │ ├─ UserFuncUsageLog.java # 用户功能使用记录表（bg_user_func_usage_log）
|
||
│ │ ├─ ChinaRegionsCode.java # 地区表（bg_china_regions_code）
|
||
│ │ ├─ JobCategory.java # 岗位类型表（bg_job_category）
|
||
│ │ ├─ Company.java # 公司表（bg_company）
|
||
│ │ ├─ Job.java # 岗位表（bg_job）
|
||
│ │ ├─ JobRegionRelation.java # 岗位-地区关联表（bg_job_region_relation）
|
||
│ │ ├─ JobSkillTagRelation.java # 岗位-技能标签关联表（bg_job_skill_tag_relation）
|
||
│ │ ├─ Industry.java # 行业字典表（bg_industry）
|
||
│ │ ├─ SkillTag.java # 技能标签表（bg_skill_tag）
|
||
│ │ ├─ UserJobFavorite.java # 用户收藏岗位表（bg_user_job_favorite）
|
||
│ │ ├─ UserJobApplication.java # 用户投递记录表（bg_user_job_application）
|
||
│ │ ├─ UserJobDislike.java # 用户不感兴趣记录表（bg_user_job_dislike）
|
||
│ │ └─ AppJobData.java # 爬虫岗位原始数据表（app_job_data）
|
||
│ └─ vo/ # ViewObject（OssUrlVo 等）
|
||
└─ service/ # 业务 Service（OssService、SmsService、DictCacheService、JobCleanService、JobCleanTransactionService 等）
|
||
```
|
||
> **设计理念** – 业务实体和 Mapper 位于 `manager`，B 端和 C 端共享；C 端特有的注解、切面、权限服务、路由菜单服务位于 `client-api`，避免 B 端误用；`common` 提供统一的技术支撑。
|
||
|
||
## 2️⃣ 各层模块职责
|
||
| 层级 | 主要职责 | 关键类/包 |
|
||
|------|----------|-----------|
|
||
| **client-api** | - 面向终端用户的 REST API <br> - 启动 Spring Boot 应用 <br> - 短信验证码登录（含自动注册、邀请码绑定） <br> - **功能权限校验**：注解 + 切面 + 权限服务（校验、扣减、回退） <br> - **路由菜单**：获取用户有效菜单树 | `ClientApplication`、`LoginController`、`RouteMenuController`、`FuncPermission`、`FuncPermissionAspect`、`FuncPermissionService`、`RouteMenuService`、`UserRegisterService`、`RouteMenuVo` |
|
||
| **common** | - **统一配置**：OSS、Redis、Security、WxPay、Sms 等 <br> - **跨层工具**：HTTP、IP、认证、验证码、Redis Server 等 <br> - **全局拦截/切面**：日志、TraceId、黑名单、SQL 打印 <br> - **统一异常/响应**：`GlobalExceptionAdvice`、`UnifiedResponse` <br> - **业务抽象**：邮件发送、微信支付（Native/JS/Transfer） <br> - **公共 POJO**：登录令牌、防重放信息等 | `config/`, `tool/`, `interceptor/`, `aop/`, `exception/`, `email/`, `wxPay/`, `pojo/` |
|
||
| **manager** | - **业务实体**（`User`、`OssFile`、`UserInvite`、`RouteMenu`、`FuncPermission`、`UserRouteMenuStock`、`UserFuncPermissionStock`、`UserFuncUsageLog`、`ChinaRegionsCode`、`JobCategory`、`Company`、`Job`、`JobRegionRelation`、`Industry`、`SkillTag`、`UserJobFavorite`、`UserJobApplication`、`UserJobDislike`、`AppJobData`） <br> - **MyBatis Mapper**（`UserMapper`、`OssFileMapper`、`UserInviteMapper`、`RouteMenuMapper`、`FuncPermissionMapper`、`UserRouteMenuStockMapper`、`UserFuncPermissionStockMapper`、`UserFuncUsageLogMapper`、`ChinaRegionsCodeMapper`、`JobCategoryMapper`、`CompanyMapper`、`JobMapper`、`JobRegionRelationMapper`、`IndustryMapper`、`SkillTagMapper`、`UserJobFavoriteMapper`、`UserJobApplicationMapper`、`UserJobDislikeMapper`、`AppJobDataMapper`） <br> - **业务 API**：文件上传/下载、健康检查等 <br> - **业务逻辑**：服务层、工具类等 <br> - **既供 B 端 UI（待实现）使用，也供 C 端业务直接调用** | `controller/`, `mapper/`, `pojo/po/`, `pojo/vo/`, `service/`, `constant/` |
|
||
|
||
## 3️⃣ 关键业务实体
|
||
| 实体 | 所属模块 | 作用概述 |
|
||
|------|----------|----------|
|
||
| `User` | manager | 记录用户基础信息（手机号、邮箱、密码、昵称、微信绑定、邀请码等），配合 `UserMapper` 完成持久化。 |
|
||
| `OssFile` | manager | 描述 OSS（对象存储）中文件的元数据（路径、大小、标签等），通过 `OssFileMapper` 进行增删改查。 |
|
||
| `UserInvite` | manager | 用户邀请记录表，记录邀请人与被邀请人的关系及邀请时间。 |
|
||
| `RouteMenu` | manager | 路由菜单表（bg_route_menu），支持多级树形结构，通过 rootId/parentId 表达层级关系，openAccess 标识是否公开免费。 |
|
||
| `FuncPermission` | manager | 功能权限表（bg_func_permission），定义功能点编码（func_code，最长12字符，唯一约束），daily_free_count 配置每日免费次数。 |
|
||
| `UserRouteMenuStock` | manager | 用户路由菜单库存表（bg_user_route_menu_stock），记录用户拥有的菜单权限，支持时间维度。 |
|
||
| `UserFuncPermissionStock` | manager | 用户功能权限库存表（bg_user_func_permission_stock），记录用户拥有的功能权限，支持时间/次数/复合维度。 |
|
||
| `UserFuncUsageLog` | manager | 用户功能使用记录表（bg_user_func_usage_log），记录每次功能使用，用于免费次数统计和异常回退。 |
|
||
| `RouteMenuVo` | client-api | 路由菜单树形VO，包含 children 子菜单列表，供前端渲染动态路由。 |
|
||
| `LoginVo` | client-api | 登录成功后返回的用户信息（userId、nick）。 |
|
||
| `SmsLoginDto` | client-api | 短信验证码登录的请求参数（mobileNumber、code、inviteCode）。 |
|
||
| `ChinaRegionsCode` | manager | 地区表（bg_china_regions_code），行政区划编码，省/市/区三级，code为主键。 |
|
||
| `JobCategory` | manager | 岗位类型表（bg_job_category），树形结构，一级/二级分类。 |
|
||
| `Company` | manager | 公司表（bg_company），公司基本信息、融资、规模、新闻动态等。 |
|
||
| `Job` | manager | 岗位表（bg_job），岗位信息、薪资、标签、技能标签，关联公司和岗位类型。 |
|
||
| `JobRegionRelation` | manager | 岗位-地区关联表（bg_job_region_relation），一个岗位可关联多个地区。 |
|
||
| `UserJobFavorite` | manager | 用户收藏岗位表（bg_user_job_favorite），用户与岗位唯一约束。 |
|
||
| `UserJobApplication` | manager | 用户投递记录表（bg_user_job_application），记录投递状态流转。 |
|
||
| `Industry` | manager | 行业字典表（bg_industry），树形结构，一级/二级分类。 |
|
||
| `SkillTag` | manager | 技能标签表（bg_skill_tag），挂在岗位类型下，不分级，用于匹配度计算。 |
|
||
| `UserJobDislike` | manager | 用户不感兴趣记录表（bg_user_job_dislike），记录用户对岗位的不感兴趣原因，冗余公司ID/地区编码/行业ID方便推荐过滤。 |
|
||
| `JobSkillTagRelation` | manager | 岗位-技能标签关联表（bg_job_skill_tag_relation），预定义技能标签与岗位的关联，用于匹配度计算。 |
|
||
| `AppJobData` | manager | 爬虫岗位原始数据表（app_job_data），存储爬虫抓取的原始岗位数据，供清洗服务读取并写入业务表。 |
|
||
|
||
## 4️⃣ 权限体系设计
|
||
### 整体架构
|
||
- **前端**：路由控制菜单/页面可见性，登录后拉取用户有效菜单树（含公开免费菜单 + 库存授权菜单）
|
||
- **后端**：AOP 切面拦截 `@FuncPermission` 注解，校验权限 + 扣减库存，业务异常自动回退次数
|
||
- **权限来源**：商品模块下单成功后写入库存表，权限框架不关心来源
|
||
|
||
### 数据库表（5张）
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `bg_route_menu` | 路由菜单定义（树形结构，open_access 标识公开免费菜单） |
|
||
| `bg_user_route_menu_stock` | 用户路由菜单库存（时间维度） |
|
||
| `bg_func_permission` | 功能权限定义（func_code 唯一，daily_free_count 配置每日免费次数） |
|
||
| `bg_user_func_permission_stock` | 用户功能权限库存（时间/次数/复合维度） |
|
||
| `bg_user_func_usage_log` | 用户功能使用记录（每次使用插入，用于免费次数统计和异常回退） |
|
||
|
||
### 库存维度
|
||
- `time_limit` + `expire_time`：时间维度，0=不限时，1=限时
|
||
- `count_limit` + `remain_count`：次数维度，0=不限次，1=限次
|
||
- 两个维度独立控制，组合形成四种模式：永久不限次、限时不限次、永久限次、限时限次
|
||
- 添加库存时不降级：已经不限时/不限次的不会被覆盖
|
||
|
||
### 切面校验流程
|
||
1. 拿注解上的 funcCode + 当前登录用户 userId
|
||
2. 查 bg_func_permission（funcCode + status=1），拿到 dailyFreeCount
|
||
3. dailyFreeCount > 0 → COUNT 今日使用记录，未超额 → 插入使用记录，放行
|
||
4. 免费额度用完或无免费额度 → 查付费库存表（userId + funcCode）
|
||
5. 无记录 → 无权限
|
||
6. time_limit=1 且过期 → 已过期
|
||
7. count_limit=0 → 插入使用记录，放行
|
||
8. count_limit=1 → SQL 原子扣减 `remain_count = remain_count - 1`（WHERE remain_count > 0）→ 插入使用记录，放行
|
||
9. 业务方法异常 → 删除使用记录 + 尝试回退库存次数（count_limit=1 时 remain_count + 1）
|
||
|
||
## 5️⃣ 共享技术栈（位于 `common`）
|
||
| 类别 | 关键实现 | 位置 |
|
||
|------|----------|------|
|
||
| **配置** | `OssConfig`, `RedissonConf`, `SecurityConfig`, `WxPayConfig`, `SmsConfig` | `common/config` |
|
||
| **安全** | JWT 过滤器、登录令牌 (`RedisLoginTokenInfo`)、防重放 (`RedisPreventReplayInfo`) | `common/interceptor`、`common/pojo/interceptor` |
|
||
| **邮件** | `EmailAbility`（封装邮件发送） | `common/email` |
|
||
| **AI** | `AiChatAbility`（OpenAI 兼容多供应商对话）、`AiChatConfig`（供应商配置） | `common/ai` |
|
||
| **微信支付** | `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** → 所有层共同依赖的底层设施（配置、工具、拦截、异常、支付、邮件等）。
|
||
- 权限体系分两层：前端路由控制菜单可见性，后端切面控制功能点权限与库存扣减。
|
||
- 权限和菜单作为商品维度，框架只负责校验和库存管理，不关心权限来源。
|
||
|
||
## 4.5️⃣ 邀请模块设计
|
||
### 数据库表（1张）
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `bg_user_invite` | 用户邀请记录（记录邀请人与被邀请人的关系及邀请时间） |
|
||
|
||
### 核心逻辑
|
||
- 用户注册时自动生成10位邀请码（大写字母+数字），存入 `User.invite_code`，碰撞检查最多重试3次
|
||
- 注册时可携带 `inviteCode`，有效则写入邀请记录，无效仅日志警告不阻断注册
|
||
- 注册逻辑由 `UserRegisterService` 独立承担，`LoginService` 委托调用
|