Files

T

2026-03-20 15:04:01 +08:00

23 KiB

Raw Blame History

inclusion

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 # 路由菜单接口（获取用户有效菜单树）
│           │   ├─ UserProfileController.java # 用户个人资料接口（主表+5张子表的查询与保存）
│           │   └─ JobIntentionController.java # 求职意向接口（查询与保存）
│           ├─ service/
│           │   ├─ LoginService.java        # 登录业务逻辑（验证码校验、自动注册、JWT生成、Cookie设置）
│           │   ├─ UserRegisterService.java # 用户注册服务（注册逻辑、邀请码生成与绑定）
│           │   ├─ FuncPermissionService.java  # 功能权限服务（校验、扣减、查询、添加库存、回退）
│           │   ├─ RouteMenuService.java    # 路由菜单服务（查询、添加库存、获取用户菜单树）
│           │   ├─ UserProfileService.java  # 用户个人资料服务（主表+5张子表的CRUD）
│           │   ├─ JobIntentionService.java # 求职意向服务（查询与保存/更新）
│           │   └─ WxPayNotifyMessageAbstractImpl.java  # 微信支付回调实现
│           └─ pojo/
│               ├─ param/
│               │   ├─ userProfile/        # 个人资料入参（UserProfileParam、各子表Param）
│               │   └─ job/                # 岗位相关入参（JobIntentionParam）
│               ├─ dto/
│               │   ├─ SmsLoginDto.java    # 短信登录入参（mobileNumber + code + inviteCode）
│               │   ├─ userProfile/        # 个人资料出参（UserProfileDto、各子表Dto）
│               │   └─ job/                # 岗位相关出参（JobIntentionDto）
│               └─ 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、Async 等统一配置
│           ├─ 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、字典查询等）
            │   ├─ RegionController.java          # 地区接口（树形/层级/搜索/批量查询）
            │   ├─ JobCategoryController.java     # 岗位分类接口（树形/层级/搜索/批量查询）
            │   └─ IndustryController.java        # 行业接口（树形/层级/搜索/批量查询）
            ├─ 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
            │   ├─ UserJobIntentionMapper.java        # 用户求职意向Mapper
            │   ├─ UserProfileMapper.java             # 用户个人资料Mapper
            │   ├─ UserProfileEducationMapper.java    # 用户教育经历Mapper
            │   ├─ UserProfileWorkMapper.java         # 用户工作经历Mapper
            │   ├─ UserProfileInternshipMapper.java   # 用户实习经历Mapper
            │   ├─ UserProfileProjectMapper.java      # 用户项目经历Mapper
            │   ├─ UserProfileCompetitionMapper.java  # 用户竞赛经历Mapper
            │   ├─ UserProfileSkillTagRelationMapper.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）
            │   │   ├─ UserJobIntention.java           # 用户求职意向表（bg_user_job_intention）
            │   │   ├─ UserProfile.java                # 用户个人资料表（bg_user_profile）
            │   │   ├─ UserProfileEducation.java       # 用户教育经历表（bg_user_profile_education）
            │   │   ├─ UserProfileWork.java            # 用户工作经历表（bg_user_profile_work）
            │   │   ├─ UserProfileInternship.java      # 用户实习经历表（bg_user_profile_internship）
            │   │   ├─ UserProfileProject.java         # 用户项目经历表（bg_user_profile_project）
            │   │   ├─ UserProfileCompetition.java     # 用户竞赛经历表（bg_user_profile_competition）
            │   │   ├─ UserProfileSkillTagRelation.java  # 用户技能标签关联表（bg_user_profile_skill_tag_relation）
            │   │   └─ AppJobData.java                # 爬虫岗位原始数据表（app_job_data）
            │   └─ vo/               # ViewObject（OssUrlVo、DescriptionParagraph 等）
            └─ service/               # 业务 Service（OssService、SmsService、DictCacheService、JobCleanService、JobCleanTransactionService、CompanyCleanService、CompanyCleanTransactionService、UserSkillTagMatchService 等）

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

2️⃣ 各层模块职责

层级	主要职责	关键类/包
client-api	- 面向终端用户的 REST API - 启动 Spring Boot 应用 - 短信验证码登录（含自动注册、邀请码绑定） - 功能权限校验：注解 + 切面 + 权限服务（校验、扣减、回退） - 路由菜单：获取用户有效菜单树	`ClientApplication`、`LoginController`、`RouteMenuController`、`FuncPermission`、`FuncPermissionAspect`、`FuncPermissionService`、`RouteMenuService`、`UserRegisterService`、`RouteMenuVo`
common	- 统一配置：OSS、Redis、Security、WxPay、Sms、Async 等 - 跨层工具：HTTP、IP、认证、验证码、Redis Server 等 - 全局拦截/切面：日志、TraceId、黑名单、SQL 打印 - 统一异常/响应：`GlobalExceptionAdvice`、`UnifiedResponse` - 业务抽象：邮件发送、微信支付（Native/JS/Transfer）、异步任务 - 公共 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`） - MyBatis Mapper（`UserMapper`、`OssFileMapper`、`UserInviteMapper`、`RouteMenuMapper`、`FuncPermissionMapper`、`UserRouteMenuStockMapper`、`UserFuncPermissionStockMapper`、`UserFuncUsageLogMapper`、`ChinaRegionsCodeMapper`、`JobCategoryMapper`、`CompanyMapper`、`JobMapper`、`JobRegionRelationMapper`、`IndustryMapper`、`SkillTagMapper`、`UserJobFavoriteMapper`、`UserJobApplicationMapper`、`UserJobDislikeMapper`、`AppJobDataMapper`） - 业务 API：文件上传/下载、健康检查等 - 业务逻辑：服务层、工具类等 - 既供 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方便推荐过滤。
`UserJobIntention`	manager	用户求职意向表（bg_user_job_intention），存储意向岗位类型、城市、行业（JSON数组，节点可能为任意级别）和工作类型。
`UserProfile`	manager	用户个人资料表（bg_user_profile），存储身份证号、所在城市、微信号、作品集链接、工作年限、经验行业IDs、技能标签、证书标签。
`UserProfileEducation`	manager	用户教育经历表（bg_user_profile_education，profile子表），学校、专业、学历、起止年份、描述段落（JSON对象数组）。
`UserProfileWork`	manager	用户工作经历表（bg_user_profile_work，profile子表），公司、职位、起止时间、描述段落（JSON对象数组）。
`UserProfileInternship`	manager	用户实习经历表（bg_user_profile_internship，profile子表），公司、职位、起止时间、描述段落（JSON对象数组）。
`UserProfileProject`	manager	用户项目经历表（bg_user_profile_project，profile子表），公司、项目名、角色、起止时间、描述段落（JSON对象数组）。
`UserProfileCompetition`	manager	用户竞赛经历表（bg_user_profile_competition，profile子表），竞赛名、奖项、获奖时间、描述段落（JSON对象数组）。
`JobSkillTagRelation`	manager	岗位-技能标签关联表（bg_job_skill_tag_relation），预定义技能标签与岗位的关联，用于匹配度计算。
`UserProfileSkillTagRelation`	manager	用户技能标签关联表（bg_user_profile_skill_tag_relation），记录用户匹配的技能标签，由AI自动识别生成。
`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=限次
两个维度独立控制，组合形成四种模式：永久不限次、限时不限次、永久限次、限时限次
添加库存时不降级：已经不限时/不限次的不会被覆盖

切面校验流程

拿注解上的 funcCode + 当前登录用户 userId
查 bg_func_permission（funcCode + status=1），拿到 dailyFreeCount
dailyFreeCount > 0 → COUNT 今日使用记录，未超额 → 插入使用记录，放行
免费额度用完或无免费额度 → 查付费库存表（userId + funcCode）
无记录 → 无权限
time_limit=1 且过期 → 已过期
count_limit=0 → 插入使用记录，放行
count_limit=1 → SQL 原子扣减 remain_count = remain_count - 1（WHERE remain_count > 0）→ 插入使用记录，放行
业务方法异常 → 删除使用记录 + 尝试回退库存次数（count_limit=1 时 remain_count + 1）

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

类别	关键实现	位置
配置	`OssConfig`, `RedissonConf`, `SecurityConfig`, `WxPayConfig`, `SmsConfig`, `AsyncConfig`	`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️⃣ 用户技能标签匹配设计

整体架构

触发时机：用户保存个人资料（主表或任意子表）后异步触发
匹配流程：两次 AI 调用 → 第一次识别用户所属的二级岗位分类（1-10个），第二次从候选技能标签中匹配用户技能
数据存储：全量替换 bg_user_profile_skill_tag_relation 表

数据库表（1张）

表名	说明
`bg_user_profile_skill_tag_relation`	用户技能标签关联（user_id + skill_tag_id 唯一约束）

核心流程

查询用户完整个人资料（主表 + 5张子表）
数据有效性检查（主表或所有子表为空 → 清空关联表）
第一次 AI 调用：识别用户所属的二级岗位分类（1-10个），信息不足返回空数组
查询三级分类：根据二级分类 ID 查询所有三级分类（技能标签挂在三级分类下）
查询候选技能标签（WHERE category_id IN 三级分类列表）
第二次 AI 调用：从候选标签中匹配用户技能标签
全量替换关联表（先 DELETE，结果非空则 BATCH INSERT）

异步执行

使用 Spring @Async 注解，配置独立线程池（核心5线程，最大10线程，队列200）
异常统一记录日志，不影响主流程
AI 调用失败不修改关联表（保持原状）

4.6️⃣ 邀请模块设计

数据库表（1张）

表名	说明
`bg_user_invite`	用户邀请记录（记录邀请人与被邀请人的关系及邀请时间）

核心逻辑

用户注册时自动生成10位邀请码（大写字母+数字），存入 User.invite_code，碰撞检查最多重试3次
注册时可携带 inviteCode，有效则写入邀请记录，无效仅日志警告不阻断注册
注册逻辑由 UserRegisterService 独立承担，LoginService 委托调用

23 KiB Raw Blame History Unescape Escape

OfferPie Back‑End 项目结构说明

1️⃣ 项目整体层次

2️⃣ 各层模块职责

3️⃣ 关键业务实体

4️⃣ 权限体系设计

整体架构

数据库表（5张）

库存维度

切面校验流程

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

6️⃣ 构建与运行

7️⃣ 小结

4.5️⃣ 用户技能标签匹配设计

整体架构

数据库表（1张）

核心流程

异步执行

4.6️⃣ 邀请模块设计

数据库表（1张）

核心逻辑

23 KiB

Raw Blame History

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