UserhomeService/后端项目知识库.md

后端项目知识库

工程：UserHome ｜ 技术栈：Spring Boot 2.7.18 / JDK 1.8 / Spring Data JPA(Hibernate) + MySQL 8.0.33 / Redis ｜ 最近更新：2026-08-20 维护规则：发生重大功能变化、或收到"更新后端项目知识库"指令时更新。

一、项目概览

• 定位：yh-platform 的用户首页 / 应用门户模块。负责用户首页应用聚合展示（分类 tab + 图标网格 + 搜索）、用户「常用应用」设置（≤8）、角色身份切换。应用元数据不落本地库，跨仓来自 UserBase。
• 技术栈与版本：Spring Boot 2.7.18（parent spring-boot-starter-parent）；JDK 1.8；持久化 Spring Data JPA + Hibernate，MySQL 8.0.33；缓存 Redis（spring-boot-starter-data-redis）；构建 Maven；统一依赖经 yh-platform-dependencies BOM 与 spring-cloud-alibaba-dependencies 2021.0.5.0（Nacos，适配 Boot 2.7）。
• 启动 / 运行方式：入口 UserHomeApplication；端口 8070，context-path /。默认 profile=local（不连 Nacos，纯走 application.yml）；CI 注入 SPRING_PROFILES_ACTIVE=prod 启用 Nacos 配置中心覆盖。CAS 登录态用户以 BoaUser 注入 Controller。

二、模块与包结构

• controller.api：接口层（UserController、UsedAppController），直接 return 对象，由 yh-api-std 包成 {code:0,data}。
• service / service.impl：业务层。远程应用（AppRemoteService，跨仓 UserBase）+ 本地常用应用（UsedAppService）+ 当前角色（IUserCurrentRoleService）。
• repository：数据访问（UsedAppRepository、UserCurrentRoleRepository，JPA）。
• entity：JPA 实体（UsedApp、UserCurrentRole）。
• model：枚举（SetType）。
• config：路径前缀约定（Config 枚举）。
• common：实体基类（BaseEntity）。

三、核心领域模型与关系

• UsedApp（表 used_app）：用户常用应用设置，一行存一组（appIds 逗号分隔），set_type(0系统/1学校/2用户) + setId + roleType + schId 四维唯一，覆盖式保存。不冗余应用元数据。
  • 逻辑外键：set_id/c_id → UserBase 用户、sch_id → UserBase sys_group.id、appId → UserBase application_info.id。无物理外键，靠业务字段关联。
  • 唯一索引 idx_used_app_set(set_id,set_type,role_type,sch_id)。
• UserCurrentRole（表 user_current_role）：用户当前激活角色（会话态），userId 主键 + roleId/roleName/schId/schName/childId/childName，对齐旧 UserHome 同名表。
• SetType：常用设置级别 0=系统（超管）/1=学校/2=用户。
• BaseEntity（抽象 @MappedSuperclass）：自增 id + create_time + update_time（与 UserBase/BasePlatform 约定一致）。
• 关系边界：UserHome 只存「常用设置」与「当前角色」，应用元数据跨仓来自 UserBase（YschBaseOpenApi.getUserApp）。

四、关键业务流程

1. 获取用户应用：GET /{platform}/user/GetUserApp → AppRemoteService.getUserApps（经 YschBaseOpenApi.getUserApp(userId, PC_BROWSER) 实时拉取）→ 返回 List<BoaAppType>（id/name/apps 分组）→ 前端渲染分类 tab（含「全部」）+ 图标网格 + 搜索。
2. 常用应用展示：GET /{platform}/usedapp/getUsedApp?roleType=&schId=&isSch= → 本地 used_app 按「用户 > 学校 > 系统」多级取生效记录 → appIds 拆分 → 从跨仓全集过滤 → 返回 List<BoaApp>（详情，保持顺序）。
3. 保存常用应用：POST /{platform}/usedapp/saveUsedApp（body：appIds 逗号分隔 / type 0|1|2 / roleType / schId）→ 超管强制 type=0（系统级）→ UsedAppService.save：四维判重 upsert 覆盖保存。
4. 角色身份：getUserRole（跨仓角色列表）、findUserRole（本地当前角色）、savUserRole（校验所选 学校+角色 属于角色列表后 upsert 本地表）。
5. 其它：GetUserInfo（登录 BoaUser）、GetAppInfoById?id=（在全集中查找，免额外跨仓请求）、getUsedAppById/saveUsedAppById（用户级常用，roleType=-1）、getAppByIds（按 ids 取应用精简映射）。

五、工程约定与模式

• 异常返回结构：Controller 直接 return 对象，yh-api-std 统一包成 {code:0,data}（HTTP 200）；业务异常抛 BizException(ErrorCode.FORBIDDEN/PARAM_ERROR, msg)。
• 鉴权方式：CAS SSO（浏览器登录态，BoaUser 注入，作用于 /{platform} 普通接口）；跨仓调用 UserBase 走 yh-app-auth 应用间签名（yh.open 配置 appKey/appSecret，OpenApiHttpClient 自动附加 X-App-Key/X-Timestamp/X-Signature）。
• 路径前缀约定：Config 枚举定义 /{platform} 普通、/oapi/ 开放（与 UserBase 一致）。注意 Boot 2.6+ 默认 PathPatternParser 不合并连续斜杠，路径末尾不要带斜杠，否则 404。
• 缓存：已引入 Redis（host localhost:6379 db0），当前未实际用于业务。
• 事务边界：UsedAppServiceImpl.save 单表 upsert，未标 @Transactional（单条 save 自带事务）。

六、集成点

• MySQL（库 bsch_userhome）：used_app + user_current_role 表；JPA ddl-auto=update 自动建表。凭据见 application.yml。
• Redis（localhost:6379 db0）：已配置，用途待核实。
• Nacos 配置中心：仅 prod profile 启用（NACOS_CONFIG_ENABLED=true），拉 userhome.yaml（group USERHOME）覆盖本地；本地 local 默认不连。详见 bootstrap.yml。
• CAS SSO：https://sso.yunhaixingtong.com/cas。
• UserBase 跨仓开放接口：经 yh-openapi-spring-boot-starter 自动装配 YschBaseOpenApi → GET {yh.open.base-host}{base-path}/oapi/app/list?userId=&clientType= 返回 List<BoaAppType>；/oapi/user/roleList 返回 List<BoaRoleInfo>。
• yh-platform starters：yh-auth-spring-boot-starter(CAS)、yh-app-auth-spring-boot-starter(签名)、yh-openapi-spring-boot-starter(跨仓调用)、yh-api-std(统一响应)。

七、重要设计决策与原因

• 本地只存「常用设置 + 当前角色」，不冗余应用元数据 —— 元数据跨仓来自 UserBase，避免双写不一致。
• **一行存一组（appIds 逗号分隔）**而非逐应用一行 —— 对齐旧 UserHome 四维结构（系统/学校/用户 × 角色），支持超管设系统级、学校设角色级常用；sortNo 即逗号顺序。
• 多级生效（用户 > 学校 > 系统） —— 个人未设置时回退学校/系统默认，schId==uid 直接取学校级（对齐旧逻辑）。
• 覆盖式保存（四维唯一 upsert） —— 幂等，前端顺序即最终序。
• 跨仓调用仅替换实现 —— AppRemoteService 接口稳定，OpenApiAppRemoteServiceImpl 一行调用 YschBaseOpenApi.getUserApp，前端与 Controller 无需感知底层。
• 本地默认关闭 Nacos（profile=local） —— CI 注入 prod 才连，避免本地 403 噪音；Nacos 不可达 fail-fast=false 回退本地配置兜底。

八、待办与已知坑

• appKey/appSecret 待填：yh.open / yh.app-auth 的 app-key/app-secret 当前为占位（100000 / change-me-in-phase0），需在 UserBase 完成 UserHome 应用注册后填入真实值，否则跨仓请求签名失败 401。
• yh.open.base-host 指向：本地默认 http://localhost:8060（UserBase），生产经 Nacos userhome.yaml 覆盖。
• used_app 旧结构残留：升级前若已有 user_id/app_id/sort_no 结构的旧表，ddl-auto=update 只加列不删列，建议按 sql/userhome_init.sql 备份后重建。
• Redis 已引入但未实际使用，待核实是否计划启用。
• Nacos env 名陷阱：NACOS_NAMESPACE 不生效，必须用 SPRING_CLOUD_NACOS_CONFIG_NAMESPACE 覆盖 namespace。
• 路径前缀尾斜杠：Boot 2.6+ PathPatternParser 不合并连续斜杠，勿带尾斜杠（防 404）。
• 生产建表：ddl-auto=update 自动建表；sql/userhome_init.sql 用于显式初始化 / 回滚参考，二者需保持字段一致。