offerpai_backend/.kiro/steering/项目结构说明.md

---
inclusion: manual
---

# OfferPie Back‑End 项目结构说明

## 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张子表的查询与保存）
│           │   ├─ UserManageController.java   # 用户账号管理接口（查看/修改个人信息、注销账号、邀请统计）
│           │   ├─ UserFeedbackController.java # 用户反馈接口（提交反馈）
│           │   ├─ UserResumeController.java   # 用户简历接口（简历列表、主表及5张子表的CRUD、子表单条添加/编辑/删除、简历删除、设置默认简历）
│           │   ├─ JobIntentionController.java # 求职意向接口（查询与保存）
│           │   ├─ JobController.java          # 岗位接口（岗位列表查询、收藏、投递、不感兴趣、求职助手任务列表、AI岗位推荐）
│           │   ├─ JobAgentConfigController.java # 求职助手配置接口（配置查询与保存）
│           │   ├─ MemberProductController.java  # 会员商品接口（商品列表、创建订单、查询订单详情）【暂未启用，注释@RestController】
│           │   ├─ MemberStatusController.java   # 会员状态接口（查询会员状态、查询功能权限库存）
│           │   └─ MessageController.java      # 站内信消息接口（消息列表、未读数、按类型未读数、标记已读）
│           ├─ service/
│           │   ├─ LoginService.java            # 登录业务逻辑（验证码校验、自动注册、JWT生成、Cookie设置）
│           │   ├─ UserRegisterService.java     # 用户注册服务（注册逻辑、邀请码生成与绑定）
│           │   ├─ UserManageService.java       # 用户账号管理服务（查看/修改个人信息、注销账号、邀请统计）
│           │   ├─ UserFeedbackService.java     # 用户反馈服务（提交反馈记录）
│           │   ├─ FuncPermissionService.java   # 功能权限服务（校验、扣减、查询、添加库存、回退）
│           │   ├─ RouteMenuService.java        # 路由菜单服务（查询、添加库存、获取用户菜单树）
│           │   ├─ UserProfileService.java      # 用户个人资料服务（主表+5张子表的CRUD）
│           │   ├─ JobIntentionService.java     # 求职意向服务（查询与保存/更新）
│           │   ├─ JobService.java              # 岗位服务（岗位列表查询、匹配度计算编排、求职助手任务列表、AI岗位推荐）
│           │   ├─ JobAgentConfigService.java   # 求职助手配置服务（配置查询与保存）
│           │   ├─ UserResumeService.java       # 用户简历服务（简历列表、主表及5张子表的CRUD、子表单条添加/编辑/删除、设置默认简历）
│           │   ├─ MemberProductService.java    # 会员商品服务（商品列表、创建订单、支付回调处理）【暂未启用，注释@Service】
│           │   ├─ MemberGrantService.java      # 会员权益发放服务（续费会员+发放功能/菜单权限）
│           │   ├─ MemberStatusService.java     # 会员状态查询服务（查询会员状态、功能权限库存详情）
│           │   ├─ MessageQueryService.java     # 站内信查询服务（消息分页列表、未读数、按类型未读数）
│           │   ├─ AlipayNotifyMessageAbstractImpl.java  # 支付宝支付回调实现（验证流水+更新状态+触发发放）【暂未启用】
│           │   └─ WxPayNotifyMessageAbstractImpl.java   # 微信支付回调实现（验证流水+更新状态+触发发放）
│           └─ pojo/
│               ├─ param/
│               │   ├─ userProfile/        # 个人资料入参（UserProfileParam、各子表Param）
│               │   ├─ resume/             # 简历入参（ResumeParam、各子表Param、各子表UpdateParam、ResumeSubTableParam）
│               │   ├─ job/                # 岗位相关入参（JobIntentionParam、JobQueryParam、JobAgentTaskQueryParam、JobAgentRecommendParam、JobApplyParam、JobApplyQueryParam、JobFavoriteQueryParam、JobDislikeParam）
│               │   ├─ jobAgent/           # 求职助手入参（JobAgentConfigParam、ChatMessageParam）
│               │   ├─ memberProduct/      # 会员商品入参（CreateOrderParam）
│               │   ├─ message/            # 站内信入参（MessageQueryParam）
│               │   ├─ feedback/           # 用户反馈入参（UserFeedbackParam）
│               │   └─ user/               # 用户账号管理入参（UserInfoParam）
│               ├─ dto/
│               │   ├─ SmsLoginDto.java    # 短信登录入参（mobileNumber + code + inviteCode）
│               │   ├─ userProfile/        # 个人资料出参（UserProfileDto、各子表Dto）
│               │   ├─ resume/             # 简历出参（ResumeDto、ResumeListItemDto、各子表Dto）
│               │   ├─ job/                # 岗位相关出参（JobIntentionDto、JobDto、JobDetailDto、JobMatchScoreDto、JobAgentRecommendDto、JobApplicationDto）
│               │   ├─ jobAgent/           # 求职助手出参（JobAgentConfigDto、ChatMessageDto）
│               │   ├─ memberProduct/      # 会员商品出参（CreateOrderDto、OrderDetailDto）
│               │   ├─ memberStatus/       # 会员状态出参（MemberStatusDto、FuncStockDto）
│               │   ├─ message/            # 站内信出参（MessageDto、MessageUnreadCountDto）
│               │   └─ user/               # 用户账号管理出参（UserInfoDto、InviteStatsDto）
│               └─ vo/
│                   ├─ LoginVo.java            # 登录返回（userId + nick）
│                   ├─ RouteMenuVo.java        # 路由菜单树形VO（含children子菜单）
│                   ├─ JobApplyCountVo.java    # 岗位投递数量统计VO
│                   └─ JobFavoriteCountVo.java # 岗位收藏数量统计VO
│
├─ common/                     # **共享层**：被 C 端和 B 端共同使用的代码库
│   ├─ pom.xml
│   └─ src/main/java
│       └─ org.jiayunet
│           ├─ config/                # 统一配置
│           │   ├─ OssConfig.java             # 阿里云OSS凭证配置
│           │   ├─ RedissonConf.java          # Redisson客户端配置
│           │   ├─ SecurityConfig.java        # Spring Security配置（JWT过滤器、白名单路径）
│           │   ├─ WxPayConfig.java           # 微信支付配置
│           │   ├─ SmsConfig.java             # 阿里云短信客户端配置
│           │   ├─ AsyncConfig.java           # 异步线程池配置
│           │   ├─ JacksonConfig.java         # Jackson序列化配置
│           │   ├─ MybatisConfig.java         # MyBatis-Plus配置（分页插件等）
│           │   ├─ LongListTypeHandler.java   # MyBatis List<Long> JSON类型处理器
│           │   ├─ UpdateBatchMethod.java     # 批量更新SQL注入策略
│           │   └─ WebConfig.java             # Spring MVC拦截器注册（黑名单+防重放）
│           ├─ constant/
│           │   └─ PreRedisKeyName.java       # Redis Key前缀常量（preventReplay、blackList、login:token）
│           ├─ mapper/
│           │   └─ CommonMapper.java          # 通用Mapper接口（继承BaseMapper，提供批量插入/更新）
│           ├─ tool/                  # 工具类
│           │   ├─ HttpTool.java              # HTTP请求工具
│           │   ├─ HttpIpTool.java            # IP地址获取工具
│           │   ├─ AuthenticTool.java         # 认证相关工具（JWT生成/解析）
│           │   ├─ ObjectTool.java            # 通用对象工具
│           │   ├─ UserSecurityTool.java      # 当前登录用户ID获取工具
│           │   ├─ VerifyImageCodeUtils.java  # 图形验证码工具
│           │   └─ server/
│           │       └─ RedisServerTool.java   # Redis操作工具（封装Redisson）
│           ├─ interceptor/           # 全局拦截器/过滤器
│           │   ├─ JwtAuthenticationTokenFilter.java  # JWT认证过滤器
│           │   ├─ LoggingOriginalRequestFilter.java  # 请求日志过滤器
│           │   ├─ TraceIdFilter.java                 # TraceId链路追踪过滤器
│           │   ├─ BlackListInterceptor.java          # 黑名单拦截器
│           │   ├─ PreventReplayInterceptor.java      # 防重放拦截器
│           │   └─ SqlLoggerInterceptor.java          # SQL日志拦截器
│           ├─ aop/
│           │   └─ ControllerLogAspect.java   # Controller日志切面
│           ├─ exception/             # 业务异常统一处理
│           │   ├─ GlobalExceptionAdvice.java          # → 移至web包，此处为异常定义
│           │   ├─ BusinessException.java              # 业务异常
│           │   ├─ BusinessExpCodeEnum.java            # 业务异常码枚举
│           │   └─ BusinessExpCodeOperations.java      # 异常码操作接口
│           ├─ web/                   # Spring MVC全局增强
│           │   ├─ GlobalExceptionAdvice.java          # 全局异常处理器
│           │   └─ UnifiedResponseBodyAdvice.java      # 统一响应体包装
│           ├─ pojo/                  # 公共POJO
│           │   ├─ UnifiedResponse.java                # 统一响应结构
│           │   ├─ PageParam.java                      # 分页请求参数基类
│           │   ├─ PageResult.java                     # 分页结果包装
│           │   ├─ login/
│           │   │   └─ RedisLoginTokenInfo.java        # Redis中登录Token信息结构
│           │   └─ interceptor/
│           │       └─ RedisPreventReplayInfo.java     # Redis中防重放信息结构
│           ├─ email/
│           │   └─ EmailAbility.java          # 邮件发送封装
│           ├─ sms/
│           │   └─ AliYunSmsAbility.java      # 阿里云短信发送能力
│           ├─ oss/
│           │   └─ AliOssAbility.java         # 阿里云OSS能力（上传/下载/签名URL）
│           ├─ ai/                    # AI对话能力封装
│           │   ├─ AiChatAbility.java         # OpenAI兼容多供应商对话
│           │   ├─ AiChatConfig.java          # AI供应商配置
│           │   └─ AiResponseCleanTool.java   # AI响应文本清洗工具
│           ├─ alipay/                # 支付宝支付能力
│           │   ├─ AlipayClientConfig.java             # 支付宝客户端配置（@ConditionalOnProperty）
│           │   ├─ AlipayPagePayAbility.java           # 支付宝电脑网站支付下单
│           │   ├─ AlipayNotifyController.java         # 支付宝回调入口（验签+分发）
│           │   └─ AlipayNotifyMessageAbstract.java    # 支付宝回调处理抽象接口
│           └─ wxPay/                 # 微信支付能力
│               ├─ WxJsPayAbility.java                 # 微信JS支付
│               ├─ WxNativePayAbility.java             # 微信Native支付
│               ├─ WxTransferPayAbility.java           # 微信转账
│               ├─ WxPayNotifyController.java          # 微信支付回调入口
│               ├─ WxPayNotifyMessageAbstract.java     # 微信回调处理抽象接口
│               └─ server/
│                   └─ TransferServer.java             # 微信转账服务端封装
│
└─ manager/                    # **B 端 + C 端共享** 的业务实现
    ├─ pom.xml
    └─ src/main/java
        └─ org.jiayunet
            ├─ constant/             # 常量枚举
            │   ├─ OssBucketEnum.java             # OSS Bucket枚举
            │   ├─ OssPathEnum.java               # OSS路径枚举
            │   ├─ SmsTemplateEnum.java           # 短信模板枚举
            │   └─ sms/
            │       ├─ SmsVariableAllows.java     # 短信变量白名单
            │       └─ UniversalSmsVariable.java  # 通用短信变量
            ├─ controller/           # 对外REST接口
            │   ├─ HealthCheckController.java     # 健康检查接口
            │   ├─ OssController.java             # 文件上传/下载接口
            │   ├─ AgreementController.java       # 协议接口（根据协议码查询最新启用版本）
            │   ├─ 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（含insertIgnore自定义SQL）
            │   ├─ MajorCategoryMapper.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
            │   ├─ UserResumeMapper.java                   # 用户简历Mapper
            │   ├─ UserResumeEducationMapper.java          # 简历-教育经历Mapper
            │   ├─ UserResumeWorkMapper.java               # 简历-工作经历Mapper
            │   ├─ UserResumeInternshipMapper.java         # 简历-实习经历Mapper
            │   ├─ UserResumeProjectMapper.java            # 简历-项目经历Mapper
            │   ├─ UserResumeCompetitionMapper.java        # 简历-竞赛经历Mapper
            │   ├─ ResumeDiagnosisReportMapper.java        # 简历诊断报告Mapper
            │   ├─ ResumeDiagnosisIssueMapper.java         # 简历诊断问题Mapper
            │   ├─ JobAgentConfigMapper.java               # 求职助手配置Mapper
            │   ├─ JobAgentChatMessageMapper.java          # 求职助手对话消息Mapper
            │   ├─ UserJobCustomizeResumeMapper.java       # 用户岗位定制简历Mapper
            │   ├─ MessageMapper.java                      # 站内信消息Mapper
            │   ├─ MessageReadMapper.java                  # 消息已读状态Mapper
            │   ├─ AgreementMapper.java                    # 协议Mapper
            │   ├─ MemberProductMapper.java                # 会员商品Mapper
            │   ├─ MemberOrderMapper.java                  # 会员订单Mapper
            │   ├─ MemberUserMapper.java                   # 会员用户Mapper
            │   ├─ MemberFuncItemMapper.java               # 会员功能配置项Mapper
            │   ├─ MemberRouteItemMapper.java              # 会员菜单配置项Mapper
            │   ├─ PayWechatFlowMapper.java                # 微信支付流水Mapper
            │   ├─ PayAlipayFlowMapper.java                # 支付宝支付流水Mapper
            │   ├─ UserFeedbackMapper.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）
            │   │   ├─ MajorCategory.java             # 专业分类表（bg_major_category）
            │   │   ├─ 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）
            │   │   ├─ UserResume.java                # 用户简历表（bg_user_resume）
            │   │   ├─ UserResumeEducation.java       # 简历-教育经历表（bg_user_resume_education）
            │   │   ├─ UserResumeWork.java            # 简历-工作经历表（bg_user_resume_work）
            │   │   ├─ UserResumeInternship.java      # 简历-实习经历表（bg_user_resume_internship）
            │   │   ├─ UserResumeProject.java         # 简历-项目经历表（bg_user_resume_project）
            │   │   ├─ UserResumeCompetition.java     # 简历-竞赛经历表（bg_user_resume_competition）
            │   │   ├─ ResumeDiagnosisReport.java     # 简历诊断报告表（bg_resume_diagnosis_report）
            │   │   ├─ ResumeDiagnosisIssue.java      # 简历诊断问题表（bg_resume_diagnosis_issue）
            │   │   ├─ JobAgentConfig.java            # 求职助手配置表（bg_job_agent_config）
            │   │   ├─ JobAgentChatMessage.java       # 求职助手对话消息表（bg_job_agent_chat_message）
            │   │   ├─ UserJobCustomizeResume.java    # 用户岗位定制简历表（bg_user_job_customize_resume）
            │   │   ├─ Message.java                   # 站内信消息表（bg_message）
            │   │   ├─ MessageRead.java               # 消息已读状态表（bg_message_read）
            │   │   ├─ Agreement.java                 # 协议表（bg_agreement，版本递增）
            │   │   ├─ MemberProduct.java             # 会员商品表（bg_member_product）
            │   │   ├─ MemberOrder.java               # 会员订单表（bg_member_order）
            │   │   ├─ MemberUser.java                # 会员用户表（bg_member_user，记录会员到期时间）
            │   │   ├─ MemberFuncItem.java            # 会员功能配置项表（bg_member_func_item，定义会员包含的功能权限）
            │   │   ├─ MemberRouteItem.java           # 会员菜单配置项表（bg_member_route_item，定义会员包含的菜单权限）
            │   │   ├─ PayWechatFlow.java             # 微信支付流水表（bg_pay_wechat_flow）
            │   │   ├─ PayAlipayFlow.java             # 支付宝支付流水表（bg_pay_alipay_flow）
            │   │   ├─ UserFeedback.java              # 用户反馈表（bg_user_feedback）
            │   │   └─ AppJobData.java                # 爬虫岗位原始数据表（app_job_data）
            │   └─ vo/               # ViewObject
            │       ├─ OssUrlVo.java              # OSS签名URL返回
            │       ├─ DescriptionParagraph.java  # 描述段落对象（JSON字段通用结构）
            │       ├─ LanguageAbility.java       # 语言能力对象（求职助手配置JSON字段）
            │       ├─ JobListItemVo.java         # 岗位列表项VO
            │       ├─ UserHonorsVo.java          # 用户荣誉VO
            │       ├─ AgreementListVo.java       # 协议列表VO
            │       ├─ RegionTreeVo.java          # 地区树形VO
            │       ├─ RegionVo.java              # 地区VO
            │       ├─ JobCategoryTreeVo.java     # 岗位分类树形VO
            │       ├─ JobCategoryVo.java         # 岗位分类VO
            │       ├─ IndustryTreeVo.java        # 行业树形VO
            │       └─ IndustryVo.java            # 行业VO
            ├─ resources/mapper/     # MyBatis XML映射文件
            │   └─ JobMapper.xml     # 岗位自定义SQL（selectJobPage）
            └─ service/              # 业务Service
                ├─ OssService.java                    # 文件上传/下载服务
                ├─ SmsService.java                    # 短信发送服务
                ├─ DictCacheService.java              # 字典缓存服务（地区/岗位分类/行业树形缓存）
                ├─ RegionService.java                 # 地区服务（树形/层级/搜索/批量查询）
                ├─ JobCategoryService.java            # 岗位分类服务（树形/层级/搜索/批量查询）
                ├─ IndustryService.java               # 行业服务（树形/层级/搜索/批量查询）
                ├─ AgreementService.java              # 协议服务（查询最新版本、列表、创建/编辑版本递增）
                ├─ JobCleanService.java               # 岗位清洗服务（爬虫数据→业务表）
                ├─ JobCleanTransactionService.java    # 岗位清洗事务服务
                ├─ CompanyCleanService.java           # 公司清洗服务
                ├─ CompanyCleanTransactionService.java # 公司清洗事务服务
                ├─ UserProfileAnalyzeService.java     # 用户简历分析服务（AI三次调用：综合分析/专业归一化/技能提取）
                ├─ JobMatchService.java               # 岗位匹配度计算服务（教育30%+经历30%+技能40%）
                └─ MessageService.java                # 站内信服务（发送系统/运营/订单消息）
```
> **设计理念** – 业务实体和 Mapper 位于 `manager`，B 端和 C 端共享；C 端特有的注解、切面、权限服务、路由菜单服务位于 `client-api`，避免 B 端误用；`common` 提供统一的技术支撑。

## 2️⃣ 各层模块职责
| 层级 | 主要职责 | 关键类/包 |
|------|----------|-----------|
| **client-api** | - 面向终端用户的 REST API <br> - 启动 Spring Boot 应用 <br> - 短信验证码登录（含自动注册、邀请码绑定） <br> - **功能权限校验**：注解 + 切面 + 权限服务（校验、扣减、回退） <br> - **路由菜单**：获取用户有效菜单树 <br> - **用户管理**：查看/修改信息、注销账号、邀请统计 <br> - **用户反馈**：提交反馈 <br> - **会员体系**：商品下单、支付回调、会员状态查询、权益发放 <br> - **求职助手**：配置管理、AI岗位推荐、任务列表 | `ClientApplication`、`LoginController`、`RouteMenuController`、`UserManageController`、`UserFeedbackController`、`MemberProductController`、`MemberStatusController`、`JobController`、`JobAgentConfigController`、`UserResumeController`、`MessageController`、`FuncPermission`、`FuncPermissionAspect`、`FuncPermissionService`、`MemberGrantService`、`MemberProductService`、`MemberStatusService`、`UserManageService` |
| **common** | - **统一配置**：OSS、Redis、Security、WxPay、Alipay、Sms、Async、Jackson、MyBatis、Web 等 <br> - **跨层工具**：HTTP、IP、认证、验证码、Redis Server、用户安全 <br> - **通用Mapper**：CommonMapper（批量插入/更新） <br> - **全局拦截/切面**：日志、TraceId、黑名单、防重放、SQL打印 <br> - **统一异常/响应**：`GlobalExceptionAdvice`、`UnifiedResponse`、`PageResult` <br> - **业务能力抽象**：邮件（EmailAbility）、短信（AliYunSmsAbility）、OSS（AliOssAbility）、AI对话（AiChatAbility）、微信支付（Native/JS/Transfer）、支付宝支付（PagePay） <br> - **公共 POJO**：登录令牌、防重放信息、分页参数/结果 | `config/`, `constant/`, `mapper/`, `tool/`, `interceptor/`, `aop/`, `exception/`, `web/`, `pojo/`, `email/`, `sms/`, `oss/`, `ai/`, `alipay/`, `wxPay/` |
| **manager** | - **业务实体**（User、OssFile、UserInvite、RouteMenu、FuncPermission、库存表、地区/岗位分类/行业/技能标签/专业分类字典、岗位及关联表、用户行为表、个人资料及5张子表、简历及5张子表、诊断报告/问题、求职助手配置/对话/定制简历、站内信、协议、会员商品/订单/用户/配置项、支付流水、用户反馈、爬虫原始数据） <br> - **MyBatis Mapper**（对应全部业务实体） <br> - **字典/公共 API**：文件上传/下载、健康检查、地区/岗位分类/行业字典查询、协议查询 <br> - **业务逻辑**：OssService、SmsService、DictCacheService、RegionService、JobCategoryService、IndustryService、AgreementService、JobCleanService、CompanyCleanService、UserProfileAnalyzeService、JobMatchService、MessageService | `controller/`, `mapper/`, `pojo/po/`, `pojo/vo/`, `service/`, `constant/` |

## 3️⃣ 关键业务实体
| 实体 | 所属模块 | 作用概述 |
|------|----------|----------|
| `User` | manager | 记录用户基础信息（手机号、邮箱、密码、昵称、头像、生日、性别、真实姓名、微信绑定、邀请码等），配合 `UserMapper` 完成持久化。 |
| `OssFile` | manager | 描述 OSS（对象存储）中文件的元数据（路径、大小、标签等），通过 `OssFileMapper` 进行增删改查。 |
| `UserInvite` | manager | 用户邀请记录表，记录邀请人与被邀请人的关系、邀请时间、奖励天数。 |
| `UserFeedback` | manager | 用户反馈表（bg_user_feedback），记录用户提交的反馈类型和内容。 |
| `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），记录每次功能使用，用于免费次数统计和异常回退。 |
| `Agreement` | manager | 协议表（bg_agreement），按协议码（agreementCode）分组，版本递增管理，支持启用/禁用状态。 |
| `MemberProduct` | manager | 会员商品表（bg_member_product），定义商品名称、价格、时长天数、排序、上下架状态。 |
| `MemberOrder` | manager | 会员订单表（bg_member_order），记录用户下单信息、支付渠道、订单状态（0待支付/1已支付）、支付时间。 |
| `MemberUser` | manager | 会员用户表（bg_member_user），记录用户的会员到期时间，一个用户一条记录。 |
| `MemberFuncItem` | manager | 会员功能配置项表（bg_member_func_item），定义会员套餐包含的功能权限项（funcCode、countLimit、addCount）。 |
| `MemberRouteItem` | manager | 会员菜单配置项表（bg_member_route_item），定义会员套餐包含的菜单权限项（routeId）。 |
| `PayWechatFlow` | manager | 微信支付流水表（bg_pay_wechat_flow），记录微信支付的订单号、金额、状态、回调数据。 |
| `PayAlipayFlow` | manager | 支付宝支付流水表（bg_pay_alipay_flow），记录支付宝支付的订单号、金额、状态、交易号、回调数据。 |
| `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），一个岗位可关联多个地区。 |
| `JobSkillTagRelation` | manager | 岗位-技能标签关联表（bg_job_skill_tag_relation），AI提取的技能标签与岗位的关联，用于匹配度计算。 |
| `Industry` | manager | 行业字典表（bg_industry），树形结构，一级/二级分类。 |
| `SkillTag` | manager | 技能标签表（bg_skill_tag），AI自动入库，name唯一索引，用于匹配度计算。 |
| `MajorCategory` | manager | 专业分类表（bg_major_category），基于教育部专业目录，三级树形结构，用于专业匹配。 |
| `UserJobFavorite` | manager | 用户收藏岗位表（bg_user_job_favorite），用户与岗位唯一约束。 |
| `UserJobApplication` | manager | 用户投递记录表（bg_user_job_application），记录投递状态流转。 |
| `UserJobDislike` | manager | 用户不感兴趣记录表（bg_user_job_dislike），冗余公司ID/地区编码/行业ID方便推荐过滤。 |
| `UserJobIntention` | manager | 用户求职意向表（bg_user_job_intention），存储意向岗位类型、城市、行业（JSON数组）和工作类型。 |
| `UserProfile` | manager | 用户个人资料表（bg_user_profile），存储维度评分字段（学校等级、公司背书、经历时长、职责深度、量化产出、荣誉、技能标签、证书标签等）。 |
| `UserProfileEducation` | manager | 用户教育经历表（bg_user_profile_education，profile子表）。 |
| `UserProfileWork` | manager | 用户工作经历表（bg_user_profile_work，profile子表）。 |
| `UserProfileInternship` | manager | 用户实习经历表（bg_user_profile_internship，profile子表）。 |
| `UserProfileProject` | manager | 用户项目经历表（bg_user_profile_project，profile子表）。 |
| `UserProfileCompetition` | manager | 用户竞赛经历表（bg_user_profile_competition，profile子表）。 |
| `UserProfileSkillTagRelation` | manager | 用户技能标签关联表（bg_user_profile_skill_tag_relation），AI自动识别生成。 |
| `UserResume` | manager | 用户简历表（bg_user_resume），简历维度信息+个人基本信息合并存储，一个用户可有多份简历。 |
| `UserResumeEducation` | manager | 简历-教育经历表（bg_user_resume_education）。 |
| `UserResumeWork` | manager | 简历-工作经历表（bg_user_resume_work）。 |
| `UserResumeInternship` | manager | 简历-实习经历表（bg_user_resume_internship）。 |
| `UserResumeProject` | manager | 简历-项目经历表（bg_user_resume_project）。 |
| `UserResumeCompetition` | manager | 简历-竞赛经历表（bg_user_resume_competition）。 |
| `ResumeDiagnosisReport` | manager | 简历诊断报告表（bg_resume_diagnosis_report），AI整体诊断评级（A/B/C/D）和各类问题统计。 |
| `ResumeDiagnosisIssue` | manager | 简历诊断问题表（bg_resume_diagnosis_issue），AI对简历各模块的诊断发现、建议、改写内容。 |
| `JobAgentConfig` | manager | 求职助手配置表（bg_job_agent_config），一个用户一条记录，存储Agent模式、投递目标、网申常见问题预设答案。 |
| `JobAgentChatMessage` | manager | 求职助手对话消息表（bg_job_agent_chat_message），完整对话流，含4种消息类型。 |
| `UserJobCustomizeResume` | manager | 用户岗位定制简历表（bg_user_job_customize_resume），唯一索引(user_id, job_id)。 |
| `Message` | manager | 站内信消息表（bg_message），支持系统(1)/运营(2)/订单(3)消息，支持指定用户和全员推送。 |
| `MessageRead` | manager | 消息已读状态表（bg_message_read），唯一索引(message_id, user_id)。 |
| `AppJobData` | manager | 爬虫岗位原始数据表（app_job_data），存储爬虫抓取的原始岗位数据，供清洗服务读取。 |

## 4️⃣ 权限体系设计
### 整体架构
- **前端**：路由控制菜单/页面可见性，登录后拉取用户有效菜单树（含公开免费菜单 + 库存授权菜单）
- **后端**：AOP 切面拦截 `@FuncPermission` 注解，校验权限 + 扣减库存，业务异常自动回退次数
- **权限来源**：会员购买成功后通过 `MemberGrantService` 统一发放到库存表

### 数据库表（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️⃣ 会员商品与支付体系
### 整体架构
- **商品管理**：`MemberProduct` 定义会员套餐（名称、价格、时长天数、排序、上下架）
- **下单流程**：用户选择商品 → 创建订单（`MemberOrder`） → 根据支付渠道调用微信/支付宝下单 → 返回支付凭据
- **支付回调**：微信/支付宝回调 → 验签 → 更新流水 → 调用 `handlePaySuccess` → 更新订单状态 → 发放权益
- **权益发放**：`MemberGrantService.grant()` → 续费会员时长 → 按 `MemberFuncItem` 发放功能权限 → 按 `MemberRouteItem` 发放菜单权限

### 数据库表
| 表名 | 说明 |
|------|------|
| `bg_member_product` | 会员商品定义（价格、时长、排序、状态） |
| `bg_member_order` | 会员订单（用户、商品、金额、支付渠道、状态、支付时间） |
| `bg_member_user` | 会员用户状态（一个用户一条记录，记录到期时间） |
| `bg_member_func_item` | 会员功能配置项（定义会员包含哪些功能权限、次数限制） |
| `bg_member_route_item` | 会员菜单配置项（定义会员包含哪些菜单权限） |
| `bg_pay_wechat_flow` | 微信支付流水 |
| `bg_pay_alipay_flow` | 支付宝支付流水 |

### 支付渠道
- **微信Native支付**：通过 `WxNativePayAbility` 调用微信下单接口，返回二维码URL
- **支付宝电脑网站支付**：通过 `AlipayPagePayAbility` 调用支付宝下单接口，返回HTML表单（内嵌二维码）
- 回调分别由 `WxPayNotifyController` 和 `AlipayNotifyController` 处理验签，再委托给具体实现类

## 6️⃣ 共享技术栈（位于 `common`）
| 类别 | 关键实现 | 位置 |
|------|----------|------|
| **配置** | `OssConfig`, `RedissonConf`, `SecurityConfig`, `WxPayConfig`, `SmsConfig`, `AsyncConfig`, `JacksonConfig`, `MybatisConfig`, `WebConfig` | `common/config` |
| **安全** | JWT 过滤器 (`JwtAuthenticationTokenFilter`)、登录令牌 (`RedisLoginTokenInfo`)、防重放 (`PreventReplayInterceptor`)、黑名单 (`BlackListInterceptor`) | `common/interceptor`、`common/pojo` |
| **通用Mapper** | `CommonMapper`（继承BaseMapper，提供batchInsert/batchUpdate方法） | `common/mapper` |
| **常量** | `PreRedisKeyName`（Redis Key前缀：preventReplay、blackList、login:token） | `common/constant` |
| **邮件** | `EmailAbility`（封装邮件发送） | `common/email` |
| **短信** | `AliYunSmsAbility`（阿里云短信发送，ConditionalOnProperty） | `common/sms` |
| **OSS** | `AliOssAbility`（阿里云OSS上传/下载/签名URL，ConditionalOnProperty） | `common/oss` |
| **AI** | `AiChatAbility`（OpenAI 兼容多供应商对话）、`AiChatConfig`（供应商配置）、`AiResponseCleanTool`（AI响应文本清洗） | `common/ai` |
| **支付宝** | `AlipayClientConfig`（客户端配置）、`AlipayPagePayAbility`（电脑网站支付）、`AlipayNotifyController`（回调验签）、`AlipayNotifyMessageAbstract`（回调抽象） | `common/alipay` |
| **微信支付** | `WxJsPayAbility`, `WxNativePayAbility`, `WxTransferPayAbility`, `WxPayNotifyController`, `WxPayNotifyMessageAbstract` | `common/wxPay` |
| **全局异常** | `GlobalExceptionAdvice`, `BusinessException`, `BusinessExpCodeEnum`, `BusinessExpCodeOperations` | `common/exception`, `common/web` |
| **日志 & AOP** | `ControllerLogAspect`, `LoggingOriginalRequestFilter`, `TraceIdFilter`, `SqlLoggerInterceptor` | `common/aop`, `common/interceptor` |
| **工具类** | `HttpTool`, `HttpIpTool`, `AuthenticTool`, `ObjectTool`, `UserSecurityTool`, `VerifyImageCodeUtils`, `RedisServerTool` | `common/tool` |
| **统一返回体** | `UnifiedResponse`, `UnifiedResponseBodyAdvice`, `PageParam`, `PageResult` | `common/pojo`, `common/web` |
| **批量/更新** | `UpdateBatchMethod`（批量更新SQL注入策略）、`LongListTypeHandler`（List<Long> JSON类型处理器） | `common/config` |

## 7️⃣ 岗位列表与匹配度计算设计
### 整体架构
- **触发时机**：用户访问岗位列表接口（支持筛选条件：地区/岗位类型/行业/工作类型）
- **核心流程**：扩展层级筛选 → 查询不感兴趣记录 → 扩展排除列表 → SQL分页查询 → 查询收藏状态 → 批量计算匹配度 → 组装返回
- **匹配度计算**：教育30% + 经历30% + 技能40%，在Java层批量计算

### 匹配度计算规则

总分公式：`MatchScore = Sedu × 30% + Sexp × 30% + Sskill × 40%`

#### 教育维度（Sedu）
- 学校等级分（Srank）：1→100, 2→80, 3→60, 4→40
- 专业相关度（Smajor）：通过 bg_major_category 树形匹配，完全匹配→100，同二级→70，同一级→30，不相关→0
- 根据 majorSensitivity 决定权重：强制(学校0.4+专业0.6，专业<40则总分减半)、优先(学校0.6+专业0.4)、不限(仅学校分)

#### 经历维度（Sexp）
- `Sexp = 公司背书×30% + 时长×10% + 经历深度×60%`
- 公司背书：1→100, 2→60, 3→30, 4→0
- 经历时长：1→100, 2→60, 3→30
- 经历深度 = 职责深度×40% + 量化产出×30% + 荣誉×30%
- 职责深度：1→100, 2→80, 3→40
- 量化产出：1→100, 2→70, 3→40
- 荣誉：封顶累加制（national每项20、provincial每项10、school每项5、paper每项15），总分不超过100

#### 技能维度（Sskill）
- 岗位无要求 → 100分
- 用户无技能 → 0分
- 匹配0个 → 0分
- 匹配≥1个 → 30分保底 + 70分按比例：`30 + (匹配数量 / 岗位要求数量) × 70`

### 核心服务
- **JobService**（client-api）：岗位列表查询主流程编排
- **JobMatchService**（manager）：批量计算匹配度（教育/经历/技能三个维度）

## 8️⃣ 用户简历分析设计
### 整体架构
- **触发时机**：用户保存个人资料（主表或任意子表）后异步触发
- **分析流程**：三次 AI 调用 → 第一次综合分析（学校等级、公司背书、经历时长、职责深度、量化产出、荣誉），第二次专业归一化（匹配到 bg_major_category ID），第三次技能提取（自由提取，入 bg_skill_tag）
- **数据存储**：维度数据更新 bg_user_profile，技能全量替换 bg_user_profile_skill_tag_relation

### 核心流程
1. 查询用户完整个人资料（主表 + 5张子表）
2. 数据有效性检查（主表或所有子表为空 → 清空关联表）
3. 第一次 AI 调用：综合分析（schoolRank、companyPrestige、experienceDuration、roleDepth、outputQuality、honors）→ 更新 bg_user_profile
4. 第二次 AI 调用：专业归一化（传三级专业分类列表）→ 更新 bg_user_profile.major_ids
5. 第三次 AI 调用：技能提取（自由提取，prompt与岗位侧一致）→ INSERT IGNORE 入 bg_skill_tag → 全量替换 bg_user_profile_skill_tag_relation

### 异步执行
- 使用 Spring `@Async` 注解，配置独立线程池
- 每次 AI 调用独立容错，某一次失败不影响其他维度
- 核心服务：**UserProfileAnalyzeService**（manager）

## 9️⃣ 邀请模块设计
### 数据库表（1张）
| 表名 | 说明 |
|------|------|
| `bg_user_invite` | 用户邀请记录（记录邀请人与被邀请人的关系、邀请时间、奖励天数） |

### 核心逻辑
- 用户注册时自动生成10位邀请码（大写字母+数字），存入 `User.invite_code`，碰撞检查最多重试3次
- 注册时可携带 `inviteCode`，有效则写入邀请记录，无效仅日志警告不阻断注册
- 注册逻辑由 `UserRegisterService` 独立承担，`LoginService` 委托调用
- 邀请统计由 `UserManageService.getInviteStats()` 提供（累计邀请人数、累计获得会员天数）

## 🔟 构建与运行
- **父 POM**（`back-end/pom.xml`）统一管理子模块的依赖与插件。
- 子模块 (`client-api`, `common`, `manager`) 均可单独 `mvn clean install`，生成各自的 jar 包。
- **启动入口**：运行 `client-api` 中的 `ClientApplication`，Spring Boot 会自动扫描并加载 `common`（配置、拦截、工具）以及 `manager` 中声明的 Mapper 与 Service。
- **条件加载**：多个能力组件使用 `@ConditionalOnProperty` 按配置启用（OSS、SMS、Alipay），未配置时不加载。

## 1️⃣1️⃣ 小结
- 项目采用 **三层结构**：
  1. **client-api** → C 端 REST 接口 + 功能权限校验 + 路由菜单 + 用户管理 + 会员体系 + 支付回调。
  2. **manager** → 业务实体、Mapper 与业务 API/Service，B 端 + C 端共享层。
  3. **common** → 所有层共同依赖的底层设施（配置、工具、拦截、异常、支付、OSS、短信、AI、邮件等）。
- 权限体系分两层：前端路由控制菜单可见性，后端切面控制功能点权限与库存扣减。
- 会员体系：商品下单 → 支付回调 → `MemberGrantService` 统一发放权益（会员时长 + 功能权限 + 菜单权限）。
- 支付双通道：微信Native支付 + 支付宝电脑网站支付，各自独立流水表和回调处理。