commit f182fe44ce52de77906c84108e91659e701d0387
Author: chenxing <chenxing@bestsch.com>
Date:   Fri Aug 21 10:46:47 2026 +0800

    本地工作区快照：恢复 .git 仓库（合并远端 main 前基线）

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
new file mode 100644
index 0000000..c6b15c7
--- /dev/null
+++ b/.gitea/workflows/ci.yml
@@ -0,0 +1,156 @@
+name: ci-userbase-service
+
+# 后端标准化 CI：maven 构建 jar -> docker build -> 推 Nexus docker-hosted
+# 触发：push 到 main（本仓库为 UserBaseService 独立仓，代码在根目录）/ 手动 Run workflow
+# 依赖仓库 Actions Secrets：NEXUS_USER / NEXUS_PASSWORD（ci-docker 账号，仅 docker-hosted 推送权）
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'image tag (default = short sha)'
+        required: false
+        default: 'auto'
+      deploy:
+        description: 'deploy to 160 after build (auto / skip)'
+        required: false
+        default: 'auto'
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    # docker:24 自带 docker CLI，复用宿主 docker daemon。
+    # 注意：act_runner v0.6.1 默认已把宿主 docker.sock 挂入每个 job 容器，
+    # 切勿在此再声明 volumes: docker.sock（会与默认挂载重复，报
+    # "Duplicate mount point" 导致容器创建失败、全部 step cancelled）。
+    container:
+      image: docker:24
+    steps:
+      # docker:24 基于 alpine，默认无 git；先装 git 再手动 clone 本仓库
+      - name: Install git (alpine)
+        run: apk add --no-cache git
+
+      # 内网 Gitea 无法访问 github.com 拉取 actions/checkout，改为直接 clone 本仓库
+      - name: Checkout (manual, internal Gitea)
+        run: |
+          git clone --depth 1 --branch main http://192.168.10.160:3000/${GITHUB_REPOSITORY}.git /tmp/src
+          cp -a /tmp/src/. .
+          rm -rf /tmp/src
+
+      - name: Compute image tag
+        id: meta
+        run: |
+          if [ "${{ inputs.tag }}" = "auto" ] || [ -z "${{ inputs.tag }}" ]; then
+            echo "tag=$(echo ${GITHUB_SHA} | cut -c1-7)" >> $GITHUB_OUTPUT
+          else
+            echo "tag=${{ inputs.tag }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build jar with Maven
+        run: |
+          # 注意：job 容器通过 docker.sock 调的是【宿主 docker daemon】，
+          # 因此 docker run -v <path> 里的路径会被宿主按【宿主路径】解析；
+          # 而 act 工作区是宿主上的 docker volume，容器内 $PWD 对宿主不可见，
+          # 直接 -v $PWD:/build 会绑成空目录导致找不到 pom.xml。
+          # 故改为：起 maven 容器 -> docker cp 源码入容器 -> exec 构建 -> cp 产物回工作区。
+          # mavenbuild 加入 infra-infra-net，用容器名 nexus 直连 Nexus(8081 maven-public)。
+          # 之前用 --add-host=nexus.yunhaixingtong.com:host-gateway 经 Caddy:80 反代，但该路径在
+          # CI 容器内不可达，maven 回退到 /opt/docker/ubs-m2 里 08-05 的旧 yh-auth 缓存(缺
+          # CasSsoAutoConfiguration)，镜像启动报 serverName 崩溃。现改用 settings.xml profile 把
+          # pom 的 HTTP 仓库重定向到 http://nexus:8081/repository/maven-public/（已验证 -7 可达）。
+          # 先清理上次失败残留的同名容器（set -e 下末尾的 rm 不会执行）
+          docker rm -f mavenbuild 2>/dev/null || true
+          docker run -d --name mavenbuild \
+            --network infra-infra-net \
+            -v /opt/docker/ubs-m2:/root/.m2 \
+            -w /build maven:3.6.3-jdk-8 sleep 3600
+          docker cp "${PWD}/." mavenbuild:/build/
+          # 写 settings.xml：新增 profile 把 nexus:8081 maven-public 作为额外仓库（infra-infra-net 内容器名直连，已验证 -7 可达）。
+          # 不用 mirror(external:http:*) 是因为它对 BOM import 解析未生效；profile 方式更可靠。
+          # pom 原有的 nexus.yunhaixingtong.com(Caddy:80) 在 CI 容器内不可解析 -> 快速失败，maven 转而用本仓库。
+          docker exec mavenbuild sh -c "printf '%s' '<settings><profiles><profile><id>nexus-repo</id><repositories><repository><id>nexus-internal</id><url>http://nexus:8081/repository/maven-public/</url><releases><enabled>true</enabled></releases><snapshots><enabled>true</enabled><updatePolicy>always</updatePolicy></snapshots></repository></repositories></profile></profiles><activeProfiles><activeProfile>nexus-repo</activeProfile></activeProfiles></settings>' > /root/.m2/settings.xml"
+          # 仅清旧 yh-auth 缓存（含 08-05 local install 的 maven-metadata-local.xml，避免本地安装优先于远端 -7）；
+          # BOM 等其它 yh.platform 模块保留缓存（Nexus 上它们仍是 08-05 的 -1，缓存与远端一致）。
+          docker exec mavenbuild rm -rf /root/.m2/repository/com/yunhai/platform/yh-auth-spring-boot-starter
+          docker exec mavenbuild sh -c 'cd /build && mvn -U -B -DskipTests clean package'
+          mkdir -p "${PWD}/target"
+          docker cp mavenbuild:/build/target/userbase.jar "${PWD}/target/userbase.jar"
+          docker rm -f mavenbuild
+
+      - name: Login to Nexus docker registry
+        run: echo "${{ secrets.NEXUS_PASSWORD }}" | docker login nexus:8083 -u ${{ secrets.NEXUS_USER }} --password-stdin
+
+      - name: Build image
+        run: docker build -t nexus:8083/docker-hosted/userbase-service:${{ steps.meta.outputs.tag }} -f docker/Dockerfile .
+
+      - name: Push image
+        run: docker push nexus:8083/docker-hosted/userbase-service:${{ steps.meta.outputs.tag }}
+
+      - name: Report build
+        run: echo "pushed nexus:8083/docker-hosted/userbase-service:${{ steps.meta.outputs.tag }}"
+
+      # —— 部署阶段（仅在 push 或手动 dispatch deploy=auto 时执行）——
+      # 运行在 160 的 act_runner 上，复用宿主 docker daemon（docker.sock 由 act_runner 自动挂载），
+      # 因此 docker pull / run 直接作用于 160 宿主，等价于在 160 上执行部署。
+      - name: Deploy (pull + rollout with rollback)
+        if: github.event_name == 'push' || inputs.deploy == 'auto'
+        run: |
+          set +e
+          IMG=nexus:8083/docker-hosted/userbase-service:${{ steps.meta.outputs.tag }}
+          echo "deploying $IMG"
+          echo "${{ secrets.NEXUS_PASSWORD }}" | docker login nexus:8083 -u ${{ secrets.NEXUS_USER }} --password-stdin
+          docker pull "$IMG"
+          # 回滚锚：保留当前 userbase-service:latest（已知良好镜像），再额外打一个时间点标签
+          RB=userbase-service:rb-$(date +%s)
+          docker tag userbase-service:latest "$RB" 2>/dev/null || true
+          docker stop userbase-service 2>/dev/null; docker rm -f userbase-service 2>/dev/null
+          # bootstrap.yml 默认 nacos.config.enabled=false（本地不连）；CI 必须注入 NACOS_CONFIG_ENABLED=true 才会拉配置
+          # SPRING_PROFILES_ACTIVE=prod 激活生产 profile（留给将来拆 application-prod.yml 用）
+          # namespace/凭据仍用顶层 SPRING_CLOUD_NACOS_* env（bootstrap 的 ${...} 占位符才能解析到）
+          docker run -d --name userbase-service --restart unless-stopped --network infra-infra-net -p 8060:8060 \
+            --add-host sso.yunhaixingtong.com:192.168.10.160 \
+            --memory=1.5g --memory-swap=1.5g \
+            -v /data/logs/userbase:/app/logs \
+            -e JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m" \
+            -e SPRING_PROFILES_ACTIVE=prod \
+            -e NACOS_CONFIG_ENABLED=true \
+            -e NACOS_ADDR=nacos:8848 \
+            -e SPRING_CLOUD_NACOS_CONFIG_NAMESPACE=6196f0de-a28d-4894-8f10-e2982b57c6bc \
+            -e SPRING_CLOUD_NACOS_USERNAME=yh-reader \
+            -e SPRING_CLOUD_NACOS_PASSWORD=123456 \
+            -e REDIS_PASSWORD=${{ secrets.REDIS_PASSWORD }} \
+            -e DB_PASSWORD=${{ secrets.DB_PASSWORD }} \
+            -e RABBITMQ_PASSWORD=${{ secrets.RABBITMQ_PASSWORD }} \
+            "$IMG"
+          # 健康检查：Spring 起来后 /userbase/ 返回 404（根路径无映射控制器），000 表示未起来
+          OK=0
+          for i in $(seq 1 30); do
+            sleep 5
+            CODE=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8060/userbase/ 2>/dev/null || true)
+            if [ "$CODE" != "000" ]; then OK=1; break; fi
+          done
+          if [ "$OK" = "0" ]; then
+            echo "!! UNHEALTHY -> rollback to userbase-service:latest"
+            docker stop userbase-service 2>/dev/null; docker rm -f userbase-service 2>/dev/null
+            # 回滚也必须注入同样的 env，否则 bootstrap 默认 enabled=false 会连不上 nacos 拉不到线上配置
+            docker run -d --name userbase-service --restart unless-stopped --network infra-infra-net -p 8060:8060 \
+              --add-host sso.yunhaixingtong.com:192.168.10.160 \
+              --memory=1.5g --memory-swap=1.5g \
+              -v /data/logs/userbase:/app/logs \
+              -e JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m" \
+              -e SPRING_PROFILES_ACTIVE=prod \
+              -e NACOS_CONFIG_ENABLED=true \
+              -e NACOS_ADDR=nacos:8848 \
+              -e SPRING_CLOUD_NACOS_CONFIG_NAMESPACE=6196f0de-a28d-4894-8f10-e2982b57c6bc \
+              -e SPRING_CLOUD_NACOS_USERNAME=yh-reader \
+              -e SPRING_CLOUD_NACOS_PASSWORD=123456 \
+              -e REDIS_PASSWORD=${{ secrets.REDIS_PASSWORD }} \
+              -e DB_PASSWORD=${{ secrets.DB_PASSWORD }} \
+              -e RABBITMQ_PASSWORD=${{ secrets.RABBITMQ_PASSWORD }} \
+              userbase-service:latest
+            echo "rolled back"; exit 7
+          fi
+          echo "DEPLOY OK: $IMG"
+          docker tag "$IMG" userbase-service:latest
+          docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}' | grep userbase || true
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..970d9d3
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,26 @@
+# ---- java build ----
+target/
+
+# ---- IDE ----
+.idea/
+*.iml
+
+# ---- local tooling ----
+.workbuddy/
+
+# ---- env secrets (keep *.example) ----
+.env
+!.env.example
+
+# ---- logs ----
+*.log
+deploy/*_run*.log
+deploy/verify_run*.log
+deploy/push_run.log
+
+# ---- OS ----
+Thumbs.db
+.DS_Store
+
+# ---- scanner artifacts ----
+defender_chk.txt
diff --git a/.mvnlog/mvn-gs.xml b/.mvnlog/mvn-gs.xml
new file mode 100644
index 0000000..85f34a6
--- /dev/null
+++ b/.mvnlog/mvn-gs.xml
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
+</settings>
diff --git a/.mvnlog/mvn-secure.xml b/.mvnlog/mvn-secure.xml
new file mode 100644
index 0000000..4c31414
--- /dev/null
+++ b/.mvnlog/mvn-secure.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
+
+    <servers>
+        <server>
+            <id>nexus-releases</id>
+            <username>admin</username>
+            <password>@4Jo8iDj10uSHvg</password>
+        </server>
+        <server>
+            <id>nexus-snapshots</id>
+            <username>admin</username>
+            <password>@4Jo8iDj10uSHvg</password>
+        </server>
+    </servers>
+
+    <mirrors>
+        <mirror>
+            <id>nexus-public</id>
+            <name>Nexus Public Group</name>
+            <url>http://nexus.yunhaixingtong.com/repository/maven-public/</url>
+            <mirrorOf>*</mirrorOf>
+            <allowInsecureProtocol>true</allowInsecureProtocol>
+        </mirror>
+    </mirrors>
+
+</settings>
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 0000000..19225e5
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,20 @@
+# UserBase 后端镜像（基于已构建好的 target/userbase.jar）
+# 构建上下文 = service 目录： docker build -f docker/Dockerfile -t <img> .
+FROM eclipse-temurin:8-jre
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl tzdata \
+ && ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
+ && echo "Asia/Shanghai" > /etc/timezone \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY target/userbase.jar /app/userbase.jar
+# 镜像内 application-prod.yml 仅作「nacos 不可达时的兜底默认」；
+# 正常启动由 run-app.sh 从 nacos 拉取线上配置（dataId=userbase-prod.yml）后覆盖。
+COPY docker/application-prod.yml /app/config/application-prod.yml
+COPY docker/run-app.sh /app/run-app.sh
+RUN chmod +x /app/run-app.sh && mkdir -p /data/upload
+
+EXPOSE 8060
+ENTRYPOINT ["/app/run-app.sh"]
diff --git a/docker/application-prod.yml b/docker/application-prod.yml
new file mode 100644
index 0000000..80bb6d3
--- /dev/null
+++ b/docker/application-prod.yml
@@ -0,0 +1,88 @@
+# UserBase 生产配置（线上以 nacos 的 userbase-prod.yml 为准，本文件是 nacos 不可达时的兜底）
+server:
+  port: 8060
+  servlet:
+    # 对外经 caddy 暴露为 http://base.yunhaixingtong.com/userbase
+    context-path: /userbase
+
+spring:
+  mvc:
+    date-format: yyyy-MM-dd HH:mm:ss
+  servlet:
+    multipart:
+      max-file-size: 50MB
+      max-request-size: 200MB
+  jackson:
+    time-zone: GMT+8
+    date-format: yyyy-MM-dd HH:mm:ss
+
+  redis:
+    host: redis-server
+    port: 6379
+    database: 0
+    # 生产由 nacos application-infra.yaml 注入；此处仅作 nacos 不可达时的兜底，
+    # 密码不写死，运行时由容器环境变量 REDIS_PASSWORD 注入（值来自 Gitea Secrets，不入镜像）
+    password: ${REDIS_PASSWORD}
+    timeout: 2000ms
+  data:
+    redis:
+      repositories:
+        enabled: false
+
+#  datasource:
+#    url: jdbc:mysql://mysql8:3306/bsch_userbase?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+#    username: root
+#    # 生产由 nacos application-infra.yaml 注入；兜底密码运行时由 DB_PASSWORD 环境变量注入（来自 Gitea Secrets）
+#    password: ${DB_PASSWORD}
+#    driver-class-name: com.mysql.cj.jdbc.Driver
+#    min-idle: 10
+#    max-active: 30
+
+  jpa:
+    database: MySQL
+    show-sql: false
+    hibernate:
+      ddl-auto: update
+    database-platform: org.hibernate.dialect.MySQL5InnoDBDialect
+    properties:
+      hibernate.order_by.default_null_ordering: last
+      hibernate:
+        dialect: org.hibernate.dialect.MySQL5InnoDBDialect
+      open-in-view: true
+
+  rabbitmq:
+    host: rabbitmq
+    port: 5672
+    username: admin
+    # 生产由 nacos application-infra.yaml 注入；兜底密码运行时由 RABBITMQ_PASSWORD 环境变量注入（来自 Gitea Secrets）
+    password: ${RABBITMQ_PASSWORD}
+    listener:
+      direct:
+        auto-startup: false
+      simple:
+        auto-startup: false
+
+# 单点登录 / 应用间签名鉴权（基础平台 yh-auth / yh-app-auth）
+yh:
+  sso:
+    server-url-prefix: http://sso.yunhaixingtong.com/cas/
+    client-host-url: http://base.yunhaixingtong.com/userbase
+    allow-headers: all
+    allow-origins: all
+    url-pattern: /api/*
+    mobi-api-pattern: /mobiapi/*
+  app-auth:
+    enabled: true
+
+ADMIN_TAG_ID: 290
+
+# 上传文件落容器卷，compose 里挂到宿主机 ./upload-data
+FILE_PATH: /data/upload
+FILE_WEB_PATH: http://base.yunhaixingtong.com/userbase/upload/
+UPLOAD_WEB_PATH_HTTP: http://base.yunhaixingtong.com/userbase/upload/file/
+
+logging:
+  level:
+    root: INFO
+  file:
+    path: /app/logs
diff --git a/docker/run-app.sh b/docker/run-app.sh
new file mode 100644
index 0000000..163abd4
--- /dev/null
+++ b/docker/run-app.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+# UserBase 启动入口：配置统一由 Nacos 配置中心在 bootstrap 阶段下发（见 bootstrap.yml）
+# 不再需要手动 curl 拉取；若 nacos 不可达，bootstrap 中 fail-fast=false 会自动回退到
+# 镜像内烤好的 application-prod.yml 兜底默认。
+set -e
+
+echo "[run-app] starting UserBase (profile=prod, nacos=${NACOS_ADDR:-nacos.yunhaixingtong.com:8848}) ..."
+
+exec java ${JAVA_OPTS:--Xms512m -Xmx1024m} -Dfile.encoding=UTF-8 -jar /app/userbase.jar \
+  --spring.profiles.active=prod
diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000..2c11623
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,260 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>2.7.18</version>
+        <relativePath/> <!-- lookup parent from repository -->
+    </parent>
+
+    <groupId>com.yunhai</groupId>
+    <artifactId>yunhaibase</artifactId>
+    <version>0.0.1</version>
+    <name>UserBase</name>
+    <description>用户中心</description>
+    <properties>
+        <java.version>1.8</java.version>
+        <cn.hutool.version>5.8.36</cn.hutool.version>
+        <easyexcel.version>3.1.2</easyexcel.version>
+    </properties>
+
+    <dependencyManagement>
+        <!-- 基础平台版本管理（含 yh-* 架包与 spring-boot-dependencies 对齐） -->
+        <dependencies>
+            <dependency>
+                <groupId>com.yunhai.platform</groupId>
+                <artifactId>yh-platform-dependencies</artifactId>
+                <version>1.0.0-SNAPSHOT</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+            <!-- Spring Cloud Alibaba（Nacos 配置中心，对齐 Boot 2.7） -->
+            <dependency>
+                <groupId>com.alibaba.cloud</groupId>
+                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
+                <version>2021.0.5.0</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+
+        <!-- 仅引入 Spring Security 的加密模块（BCryptPasswordEncoder），不引入整套安全框架；密码加密与 CAS 校验共用 -->
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-crypto</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-devtools</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- Nacos 配置中心（替代 Spring Cloud Config）。Spring Cloud Alibaba 2021.0.5 适配 Spring Boot 2.7 -->
+        <dependency>
+            <groupId>com.alibaba.cloud</groupId>
+            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
+        </dependency>
+        <!-- Boot 2.4+ 默认不再处理 bootstrap.yml，需显式引入以继续从 Nacos 拉取配置 -->
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-starter-bootstrap</artifactId>
+            <version>3.1.8</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-redis</artifactId>
+        </dependency>
+
+        <!-- RabbitMQ：推送订阅消息队列（串行消费 + 死信重试）。版本由 Boot 2.7 父 POM 统一管理 -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-amqp</artifactId>
+        </dependency>
+
+        <!-- Spring Cache 核心抽象（@Cacheable / @CachePut / @CacheEvict 注解支持） -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-cache</artifactId>
+        </dependency>
+
+        <!-- Spring Cache 抽象层（含 CaffeineCacheManager） -->
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-context-support</artifactId>
+        </dependency>
+
+        <!-- 本地内存缓存兜底：Caffeine（版本由 Boot 2.7 父 POM 统一管理） -->
+        <dependency>
+            <groupId>com.github.ben-manes.caffeine</groupId>
+            <artifactId>caffeine</artifactId>
+        </dependency>
+
+        <!-- Jackson JSON 序列化（Redis value 序列化，解决泛型/乱码） -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <!-- Jackson Java 8 日期时间支持（LocalDateTime / LocalDate 序列化）；
+             虽 spring-boot-starter-json 会传递引入，但此处显式声明以防上层排除 → 序列化异常 -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.datatype</groupId>
+            <artifactId>jackson-datatype-jsr310</artifactId>
+        </dependency>
+
+        <!-- Redisson 核心：分布式锁、限流器、Lua 复杂操作（与 Spring Cache 隔离，手动配置 RedissonClient 避免自动配置冲突） -->
+        <dependency>
+            <groupId>org.redisson</groupId>
+            <artifactId>redisson</artifactId>
+            <version>3.13.6</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.alibaba</groupId>
+            <artifactId>fastjson</artifactId>
+            <version>1.2.80</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- 核心基础工具 -->
+        <dependency>
+            <groupId>cn.hutool</groupId>
+            <artifactId>hutool-core</artifactId>
+            <version>${cn.hutool.version}</version>
+        </dependency>
+
+        <!-- Swagger / OpenAPI 文档（springdoc，兼容 Boot 2.7；替代旧 Springfox） -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-ui</artifactId>
+            <version>1.7.0</version>
+        </dependency>
+
+        <!--     easypoi 导出相关   -->
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>cn.afterturn</groupId>
+            <artifactId>easypoi-base</artifactId>
+            <version>4.1.0</version>
+        </dependency>
+
+        <!-- 基础平台架包：认证（CAS/会话）+ 应用间签名鉴权 -->
+        <dependency>
+            <groupId>com.yunhai.platform</groupId>
+            <artifactId>yh-auth-spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.yunhai.platform</groupId>
+            <artifactId>yh-app-auth-spring-boot-starter</artifactId>
+        </dependency>
+        <!-- 接口规范：成功响应统一包装为 {code,msg,data}；异常以应用内 GlobalExceptionHandler 为主，
+             本 starter 的异常处理器仅作「未被处理异常」的兜底。 -->
+        <dependency>
+            <groupId>com.yunhai.platform</groupId>
+            <artifactId>yh-api-std</artifactId>
+        </dependency>
+
+        <!-- CAS 客户端已由 yh-auth-spring-boot-starter 传递引入（3.5.1）：CAS 过滤器注册与
+             SPA 登录跳转统一在框架内，本工程不再直接依赖，避免重复定义过滤器 bean。 -->
+
+    </dependencies>
+
+    <build>
+        <finalName>userbase</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <!-- 关闭增量编译，避免 Windows 下 maven-status 状态文件被锁导致
+                         "Error while storing the mojo status / 拒绝访问" -->
+                    <useIncrementalCompilation>false</useIncrementalCompilation>
+                </configuration>
+            </plugin>
+            <!-- 打可执行 fat jar（Docker 镜像直接 java -jar 启动） -->
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <configuration>
+                    <mainClass>com.yunhai.userbase.UserBaseApplication</mainClass>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>repackage</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+
+    <repositories>
+        <repository>
+            <id>nexus-public</id>
+            <name>bsch/nexus public</name>
+            <url>http://nexus.yunhaixingtong.com/repository/maven-public/</url>
+            <releases><enabled>true</enabled></releases>
+            <snapshots><enabled>true</enabled></snapshots>
+        </repository>
+    </repositories>
+    <!--
+      ci 构建档案：将构建产物重定向到 IDE（IntelliJ/Eclipse）索引目录之外，
+      避免 IDE 后台进程持续锁定 target/maven-status/.../createdFiles.lst 导致
+      "Error while storing the mojo status / 拒绝访问"。
+      另：输出目录需从未被 IDE 打开过，否则同一棵输出树下的 application.yml 等资源
+      会被 IDE 的 JPS 预加载进程持有句柄而写不进（拒绝访问）。常规本地构建无需激活此 profile。
+      说明：C:/ci-build 已被 IDE 锁过，现改用全新目录 C:/ub-build。
+    -->
+    <profiles>
+        <profile>
+            <id>ci</id>
+            <build>
+                <directory>C:/ub-build2/userbase</directory>
+            </build>
+        </profile>
+    </profiles>
+
+</project>
diff --git a/scripts/deploy-via-docker.js b/scripts/deploy-via-docker.js
new file mode 100644
index 0000000..af308de
--- /dev/null
+++ b/scripts/deploy-via-docker.js
@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+// Deploy front/dist/prod to host /data/www/userbase/front using the Docker daemon
+// that act_runner already mounts into the job container (/var/run/docker.sock).
+//
+// Why this script exists:
+//   act_runner (v0.6.1) ignores both `container.options` extra --volume and
+//   workflow `container.volumes` in this setup, so the host static dir can't be
+//   bind-mounted directly into the job container. But the host docker.sock IS
+//   mounted by default, so we use the Docker HTTP API to:
+//     1. tar the built assets straight out of THIS container's filesystem
+//        (GET /containers/{jobId}/archive?path=...), and
+//     2. upload that tar into a throwaway helper container that has
+//        /data/www/userbase mounted RW (PUT /containers/{helperId}/archive),
+//        then `mv` the extracted folder so files land at the correct top level.
+//
+// Diagnostics: every step is collected and written to /data/www/userbase/_debug.txt
+// on the HOST via `docker exec` into the helper (the job container itself cannot
+// write there). The Gitea logs API is unavailable here, so this file is our only
+// reliable window into what happened.
+//
+// No docker CLI and no network egress required — we speak the Docker HTTP API
+// over the unix socket directly with Node's http module.
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const SOCKET = '/var/run/docker.sock';
+const HOST_STATIC = '/data/www/userbase';
+const HELPER_IMAGE = 'node:20'; // already cached on host (used by the job)
+const STAGING = HOST_STATIC + '/_staging';
+
+// --- low level docker http helpers -------------------------------------------
+
+function dockerJson(method, p, bodyObj) {
+  return new Promise((resolve, reject) => {
+    const data = bodyObj ? JSON.stringify(bodyObj) : null;
+    const headers = {};
+    if (data) {
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = Buffer.byteLength(data);
+    }
+    const req = http.request(
+      { socketPath: SOCKET, path: p, method, headers },
+      (res) => {
+        let buf = '';
+        res.on('data', (c) => (buf += c));
+        res.on('end', () => resolve({ status: res.statusCode, body: buf }));
+      }
+    );
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+function getArchive(id, p) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        socketPath: SOCKET,
+        path: `/containers/${id}/archive?path=${encodeURIComponent(p)}`,
+        method: 'GET',
+      },
+      (res) => resolve(res)
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function putArchive(id, p, tarStream) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        socketPath: SOCKET,
+        path: `/containers/${id}/archive?path=${encodeURIComponent(p)}`,
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/x-tar' },
+      },
+      (res) => {
+        let buf = '';
+        res.on('data', (c) => (buf += c));
+        res.on('end', () => resolve({ status: res.statusCode, body: buf }));
+      }
+    );
+    req.on('error', reject);
+    tarStream.pipe(req);
+  });
+}
+
+// Run a command inside the helper and return its stdout/stderr (Detach:false so
+// the call resolves only after the command finishes — reliable for sequencing).
+async function runExec(id, cmd) {
+  const created = await dockerJson('POST', `/containers/${id}/exec`, {
+    Cmd: ['sh', '-c', cmd],
+    AttachStdout: true,
+    AttachStderr: true,
+  });
+  if (created.status >= 400) {
+    throw new Error('exec create failed: ' + created.status + ' ' + created.body);
+  }
+  const execId = JSON.parse(created.body).Id;
+  const started = await dockerJson('POST', `/exec/${execId}/start`, {
+    Detach: false,
+    Tty: false,
+  });
+  return started; // { status, body(stdout+stderr) }
+}
+
+// --- helper container + diagnostics ------------------------------------------
+
+function getContainerId() {
+  const cg = fs.readFileSync('/proc/self/cgroup', 'utf8');
+  const m = cg.match(/[0-9a-f]{64}/);
+  if (!m) {
+    const h = fs.readFileSync('/etc/hostname', 'utf8').trim();
+    return h;
+  }
+  return m[0];
+}
+
+let HELPER_ID = null;
+let DEBUG_BUF = [];
+
+function dbg(line) {
+  const ts = new Date().toISOString();
+  DEBUG_BUF.push(`[${ts}] ${line}`);
+  console.log(line); // also emit to job log (best-effort)
+}
+
+// Write the accumulated debug buffer to the HOST file via a base64 pipe. Passing
+// the payload inline (single-quoted) avoids env-var/newline fragility that broke
+// the earlier diagnostics channel. Uses Detach:false so we know it completed.
+async function flushDebug() {
+  if (!HELPER_ID) {
+    console.error('flushDebug: no helper, cannot write host debug');
+    return;
+  }
+  const content = DEBUG_BUF.join('\n') + '\n';
+  const b64 = Buffer.from(content, 'utf8').toString('base64');
+  const cmd = `echo ${b64} | base64 -d > ${HOST_STATIC}/_debug.txt`;
+  try {
+    const r = await runExec(HELPER_ID, cmd);
+    if (r.status >= 400) console.error('flushDebug exec failed:', r.status, r.body);
+    else dbg('debug written to host (' + content.length + ' bytes)');
+  } catch (e) {
+    console.error('flushDebug error:', e.message);
+  }
+}
+
+// --- main --------------------------------------------------------------------
+
+function resolveDistPath() {
+  const candidates = [
+    path.join(process.cwd(), 'front', 'dist', 'prod'),
+    '/workspace/admin/userbase/front/dist/prod',
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+async function main() {
+  dbg('START script version=2026-08-04c');
+  dbg('cwd=' + process.cwd());
+
+  // 1) helper container with the host static dir mounted RW; keep it alive.
+  const createBody = {
+    Image: HELPER_IMAGE,
+    HostConfig: { NetworkMode: 'none', Binds: [`${HOST_STATIC}:${HOST_STATIC}`] },
+    Cmd: ['sh', '-c', `mkdir -p ${STAGING} && exec tail -f /dev/null`],
+  };
+  const created = await dockerJson('POST', '/containers/create', createBody);
+  if (created.status >= 400) {
+    throw new Error('create helper failed: ' + created.status + ' ' + created.body);
+  }
+  HELPER_ID = JSON.parse(created.body).Id;
+  dbg('helper created id=' + HELPER_ID);
+
+  const started = await dockerJson('POST', `/containers/${HELPER_ID}/start`);
+  if (started.status >= 400) {
+    throw new Error('start helper failed: ' + started.status + ' ' + started.body);
+  }
+  dbg('helper started');
+  // clean any stale staging from a previous failed run
+  await runExec(HELPER_ID, `rm -rf ${STAGING} && mkdir -p ${STAGING}`);
+
+  // 2) locate the built assets inside THIS container.
+  const jobId = getContainerId();
+  dbg('job container id=' + jobId);
+
+  const distDir = resolveDistPath();
+  if (!distDir) {
+    dbg('dist dir NOT found; cwd listing:');
+    try {
+      dbg(fs.readdirSync(process.cwd()).join(' '));
+      const front = path.join(process.cwd(), 'front');
+      if (fs.existsSync(front)) dbg('front listing: ' + fs.readdirSync(front).join(' '));
+    } catch (e) {
+      dbg('ls err: ' + e.message);
+    }
+    throw new Error('built dist/prod not found under any candidate path');
+  }
+  dbg('dist dir=' + distDir);
+  dbg('dist listing: ' + fs.readdirSync(distDir).join(' '));
+
+  // 3) tar of the built assets, fetched from THIS container's own filesystem.
+  //    We fetch WITHOUT a trailing slash so the tar contains a top-level "prod/"
+  //    folder; we then mv it into place (deterministic, no reliance on the
+  //    trailing-slash "contents only" quirk which this moby build ignores).
+  const tar = await getArchive(jobId, distDir);
+  if (tar.statusCode !== 200) {
+    let msg = '';
+    tar.on('data', (c) => (msg += c));
+    await new Promise((r) => tar.on('end', r));
+    throw new Error('get archive failed (status ' + tar.statusCode + '): ' + msg);
+  }
+  dbg('fetched dist tar (content-type=' + tar.headers['content-type'] + ')');
+
+  // 4) upload the tar into the staging dir of the helper's mounted host dir.
+  const put = await putArchive(HELPER_ID, STAGING, tar);
+  dbg('put archive status=' + put.status + (put.status >= 400 ? ' ' + put.body : ''));
+  if (put.status >= 400) {
+    throw new Error('put archive failed: ' + put.status + ' ' + put.body);
+  }
+
+  // 5) move staging/prod -> HOST_STATIC/front (deterministic top-level landing).
+  const mv = await runExec(
+    HELPER_ID,
+    `rm -rf ${HOST_STATIC}/front && mv ${STAGING}/prod ${HOST_STATIC}/front && rm -rf ${STAGING}`
+  );
+  dbg('mv status=' + mv.status + ' out=' + mv.body.replace(/\n/g, ' | '));
+
+  // 6) verify on host via exec into helper.
+  const verify = await runExec(
+    HELPER_ID,
+    `echo "count=$(find ${HOST_STATIC}/front -type f | wc -l)"; ` +
+      `echo "has_stray_prod=$(test -d ${HOST_STATIC}/front/prod && echo YES || echo NO)"; ` +
+      `ls -la ${HOST_STATIC}/front | head -20`
+  );
+  dbg('verify output: ' + verify.body.replace(/\n/g, ' | '));
+
+  dbg('DEPLOY OK -> ' + HOST_STATIC + '/front (top-level, no prod/ nesting)');
+}
+
+main()
+  .then(async () => {
+    // On success, keep diagnostics only briefly, then remove the debug file so
+    // it is not left web-served at /userbase/_debug.txt. Failures keep it for
+    // post-mortem (see .catch below).
+    await flushDebug();
+    try {
+      if (HELPER_ID) await runExec(HELPER_ID, `rm -f ${HOST_STATIC}/_debug.txt`);
+    } catch (e) {
+      console.error('cleanup debug file failed:', e.message);
+    }
+    if (HELPER_ID) await dockerJson('DELETE', `/containers/${HELPER_ID}?force=true`);
+    process.exit(0);
+  })
+  .catch(async (err) => {
+    dbg('DEPLOY FAILED: ' + err.stack);
+    await flushDebug(); // keep debug file on failure for post-mortem
+    if (HELPER_ID) await dockerJson('DELETE', `/containers/${HELPER_ID}?force=true`);
+    console.error('DEPLOY FAILED:', err.message);
+    process.exit(1);
+  });
diff --git a/src/main/java/com/yunhai/userbase/UserBaseApplication.java b/src/main/java/com/yunhai/userbase/UserBaseApplication.java
new file mode 100644
index 0000000..34cc402
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/UserBaseApplication.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase;
+
+import com.alibaba.fastjson.parser.ParserConfig;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.scheduling.annotation.EnableScheduling;
+import org.springframework.transaction.annotation.EnableTransactionManagement;
+
+@SpringBootApplication
+@EnableTransactionManagement
+@EnableAsync
+@EnableScheduling
+public class UserBaseApplication {
+
+    public static void main(String[] args) {
+        // 开启安全模式
+        ParserConfig.getGlobalInstance().setSafeMode(true);
+        SpringApplication.run(UserBaseApplication.class, args);
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/aspect/OapiLogAspect.java b/src/main/java/com/yunhai/userbase/aspect/OapiLogAspect.java
new file mode 100644
index 0000000..c204f7b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/aspect/OapiLogAspect.java
@@ -0,0 +1,279 @@
+package com.yunhai.userbase.aspect;
+
+import com.yunhai.platform.apistd.ApiResponse;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.appauth.AppAuthFilter;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.common.annotation.OapiLog;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.entity.SysOapiLog;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.service.ISysOapiLogService;
+import com.yunhai.userbase.utils.GzipUtil;
+import com.yunhai.userbase.utils.IpUtils;
+import com.yunhai.userbase.utils.OperationLogResolver;
+import com.yunhai.userbase.utils.SensitiveDataMasker;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.Around;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import javax.servlet.http.HttpSession;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 开放接口（/oapi/**）调用日志切面。<br>
+ * 拦截 {@code controller.oapi} 包下所有方法，规则：<br>
+ * - POST 写操作：全量自动记录（无需注解），级别/类型由 OperationLogResolver 关键词判定；<br>
+ * - GET 查询：默认不记录（高频调用，防刷爆表），满足任一条件则记录：方法标注 {@code @OapiLog}、或配置 oapi.log-get=true；<br>
+ * - 排除 {@code SignKeyInternalController}（/oapi/internal，响应含 appSecret 明文，绝不落库）；<br>
+ * - 请求参数与响应均经 {@link SensitiveDataMasker} 脱敏后入库；<br>
+ * - finally 中异步落库（有界池 oapiLogExecutor），失败不影响主业务。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Slf4j
+@Aspect
+@Component
+public class OapiLogAspect {
+
+    /** 内部密钥端点控制器，排除（响应含 appSecret 明文）。 */
+    private static final String INTERNAL_CONTROLLER = "com.yunhai.userbase.controller.oapi.SignKeyInternalController";
+
+    /** GET 默认不记录，开启本配置后全量记录。 */
+    @Value("${oapi.log-get:false}")
+    private boolean logGet;
+
+    @Autowired
+    private ISysOapiLogService sysOapiLogService;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Around("execution(* com.yunhai.userbase.controller.oapi..*.*(..))")
+    public Object around(ProceedingJoinPoint point) throws Throwable {
+        if (INTERNAL_CONTROLLER.equals(point.getSignature().getDeclaringTypeName())) {
+            return point.proceed();
+        }
+
+        HttpServletRequest request = getRequest();
+        String httpMethod = request != null ? request.getMethod() : "";
+        boolean isGet = "GET".equalsIgnoreCase(httpMethod);
+
+        OapiLog oapiLog = findAnnotation(point);
+        // 决策：POST 全记；GET 仅当注解强制或配置开启才记
+        if (isGet && oapiLog == null && !logGet) {
+            return point.proceed();
+        }
+
+        long start = System.currentTimeMillis();
+        SysOapiLog entity = buildEntity(point, request, httpMethod, oapiLog);
+
+        boolean saveResponse = oapiLog != null ? oapiLog.saveResponse() : true;
+        int maxResponseSize = oapiLog != null ? oapiLog.maxResponseSize() : 10240;
+
+        Object result = null;
+        try {
+            result = point.proceed();
+            entity.setStatusCode(200);
+            fillResponse(entity, result, saveResponse, maxResponseSize);
+        } catch (Throwable e) {
+            entity.setStatusCode(500);
+            entity.setErrorMsg(truncate(e.getMessage(), 2000));
+            // 业务异常（DException/BizException）同样构造实际返回的响应体落库，便于详情下载
+            fillErrorResponse(entity, e, saveResponse, maxResponseSize);
+            throw e;
+        } finally {
+            entity.setCostTime(System.currentTimeMillis() - start);
+            sysOapiLogService.saveAsync(entity);
+        }
+        return result;
+    }
+
+    private OapiLog findAnnotation(ProceedingJoinPoint point) {
+        try {
+            MethodSignature signature = (MethodSignature) point.getSignature();
+            Method method = signature.getMethod();
+            return method.getAnnotation(OapiLog.class);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    private SysOapiLog buildEntity(ProceedingJoinPoint point, HttpServletRequest request,
+                                   String httpMethod, OapiLog oapiLog) {
+        SysOapiLog entity = new SysOapiLog();
+
+        // 调用方应用：验签 attribute → appKey → application_info 解析应用名（失败记 appKey 原值，不阻塞）
+        resolveCallerApp(request, entity);
+
+        String requestUri = "";
+        if (request != null) {
+            entity.setRequestIp(IpUtils.getIpAddr(request));
+            requestUri = request.getRequestURI();
+            entity.setUserAgent(request.getHeader("User-Agent"));
+            entity.setRequestParams(maskRequestParams(point, request));
+        } else {
+            entity.setRequestParams(maskRequestParams(point, null));
+        }
+        entity.setRequestUri(requestUri);
+        entity.setRequestMethod(httpMethod);
+
+        String methodName = point.getSignature().getName();
+        entity.setLogLevel(OperationLogResolver.resolveLevel(httpMethod, requestUri, methodName).getCode());
+        entity.setOperationType(OperationLogResolver.resolveOperationType(httpMethod, requestUri, methodName));
+        entity.setClassMethod(point.getTarget().getClass().getName() + "." + methodName);
+        if (oapiLog != null && StringUtils.isNotBlank(oapiLog.value())) {
+            entity.setOperationDesc(oapiLog.value());
+        }
+        return entity;
+    }
+
+    /**
+     * 从 request attribute 解析调用方 appKey，并映射应用名。<br>
+     * 无 attribute / 解析失败：appKey 记 0、应用名记 unknown，仅 warn，不抛异常。
+     */
+    private void resolveCallerApp(HttpServletRequest request, SysOapiLog entity) {
+        entity.setCallerAppKey(0);
+        entity.setCallerAppName("unknown");
+        if (request == null) {
+            return;
+        }
+        Object attr = request.getAttribute(AppAuthFilter.APP_AUTH_ATTR);
+        if (attr == null) {
+            log.warn("[oapi-log] no AppAuth attr (should be blocked by RequireAppSignFilter), uri={}",
+                    request.getRequestURI());
+            return;
+        }
+        String appKeyStr = (attr instanceof String) ? (String) attr : String.valueOf(attr);
+        if (StringUtils.isBlank(appKeyStr)) {
+            log.warn("[oapi-log] AppAuth attr is blank, uri={}", request.getRequestURI());
+            return;
+        }
+        Integer appKey;
+        try {
+            appKey = Integer.parseInt(appKeyStr.trim());
+        } catch (NumberFormatException e) {
+            log.warn("[oapi-log] invalid appKey format={}, uri={}", appKeyStr, request.getRequestURI());
+            return;
+        }
+        entity.setCallerAppKey(appKey);
+        ApplicationInfo app = applicationInfoRepository.findByAppKey(appKey);
+        entity.setCallerAppName(app != null && StringUtils.isNotBlank(app.getName())
+                ? app.getName() : String.valueOf(appKey));
+    }
+
+    /**
+     * 构建请求参数：GET 优先 queryString；其余序列化方法入参（过滤 Servlet 三大件），统一过脱敏。
+     */
+    private String maskRequestParams(ProceedingJoinPoint point, HttpServletRequest request) {
+        try {
+            if (request != null && "GET".equalsIgnoreCase(request.getMethod())) {
+                String qs = request.getQueryString();
+                if (StringUtils.isNotBlank(qs)) {
+                    return SensitiveDataMasker.maskJson(qs);
+                }
+            }
+            Object[] args = point.getArgs();
+            if (args == null || args.length == 0) {
+                return "";
+            }
+            List<Object> filtered = new ArrayList<Object>();
+            for (Object arg : args) {
+                if (arg == null) {
+                    continue;
+                }
+                if (arg instanceof HttpServletRequest || arg instanceof HttpServletResponse
+                        || arg instanceof HttpSession) {
+                    continue;
+                }
+                filtered.add(arg);
+            }
+            if (filtered.isEmpty()) {
+                return "";
+            }
+            return SensitiveDataMasker.maskObject(filtered);
+        } catch (Exception e) {
+            return "";
+        }
+    }
+
+    /**
+     * 写入响应结果（脱敏 → 截断 → GZIP）。
+     */
+    private void fillResponse(SysOapiLog entity, Object result, boolean saveResponse, int maxResponseSize) {
+        if (!saveResponse || result == null) {
+            return;
+        }
+        writeResponseData(entity, result, maxResponseSize);
+    }
+
+    /**
+     * 异常路径：与 {@code GlobalExceptionHandler} 保持一致的响应体（DException/BizException → ApiResponse），
+     * 使日志下载内容等于调用方实际收到的 body；其余异常不构造（响应不可预期）。
+     */
+    private void fillErrorResponse(SysOapiLog entity, Throwable e, boolean saveResponse, int maxResponseSize) {
+        if (!saveResponse) {
+            return;
+        }
+        ApiResponse<?> response = toApiResponse(e);
+        if (response == null) {
+            return;
+        }
+        writeResponseData(entity, response, maxResponseSize);
+    }
+
+    private ApiResponse<?> toApiResponse(Throwable e) {
+        if (e instanceof DException) {
+            DException de = (DException) e;
+            return ApiResponse.fail(de.getCode(), de.getMessage(), de.getData());
+        }
+        if (e instanceof BizException) {
+            BizException be = (BizException) e;
+            return ApiResponse.fail(be.getErrorCode(), be.getMessage());
+        }
+        return null;
+    }
+
+    private void writeResponseData(SysOapiLog entity, Object payload, int maxResponseSize) {
+        if (payload == null) {
+            return;
+        }
+        try {
+            String resp = SensitiveDataMasker.maskObject(payload);
+            if (resp == null) {
+                return;
+            }
+            if (resp.length() > maxResponseSize) {
+                resp = resp.substring(0, maxResponseSize) + "...[截断]";
+            }
+            entity.setResponseData(GzipUtil.compress(resp));
+        } catch (Exception e) {
+            log.warn("开放接口日志响应序列化失败, uri={}", entity.getRequestUri(), e);
+        }
+    }
+
+    private HttpServletRequest getRequest() {
+        ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
+        return attrs != null ? attrs.getRequest() : null;
+    }
+
+    private String truncate(String text, int maxLen) {
+        if (text == null) {
+            return null;
+        }
+        return text.length() > maxLen ? text.substring(0, maxLen) : text;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/aspect/OperationLogAspect.java b/src/main/java/com/yunhai/userbase/aspect/OperationLogAspect.java
new file mode 100644
index 0000000..99afc9b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/aspect/OperationLogAspect.java
@@ -0,0 +1,205 @@
+package com.yunhai.userbase.aspect;
+
+import com.alibaba.fastjson.JSON;
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.common.context.UserContext;
+import com.yunhai.userbase.entity.SysOperationLog;
+import com.yunhai.userbase.service.ISysOperationLogService;
+import com.yunhai.userbase.utils.GzipUtil;
+import com.yunhai.userbase.utils.IpUtils;
+import com.yunhai.userbase.utils.OperationLogResolver;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.Around;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import javax.servlet.http.HttpSession;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 操作日志切面。<br>
+ * 拦截所有 Controller 方法，按如下规则自动采集并落库：<br>
+ * - GET 请求：自动记录为「一般(查询)」，无需任何注解；<br>
+ * - 非 GET 请求：仅当方法标注 @OperationLog 时才记录（沿用原注解式行为）；<br>
+ * - 排除日志查看接口自身（SysOperationLogController），避免递归与刷屏。<br>
+ * 响应结果 GZIP 压缩 + 截断后，在 finally 中异步落库，失败不影响主业务。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Slf4j
+@Aspect
+@Component
+public class OperationLogAspect {
+
+    /** 不记录日志查询/下载接口自身，避免递归与刷屏。 */
+    private static final String LOG_CONTROLLER = "com.yunhai.userbase.controller.api.SysOperationLogController";
+
+    /** GET 自动记录时使用的默认响应保存上限（10KB）。 */
+    private static final int DEFAULT_MAX_RESPONSE_SIZE = 10240;
+
+    @Autowired
+    private ISysOperationLogService sysOperationLogService;
+
+    @Around("execution(* com.yunhai.userbase.controller..*.*(..))"
+            + " && !execution(* com.yunhai.userbase.controller.oapi..*.*(..))")
+    public Object around(ProceedingJoinPoint point) throws Throwable {
+        // 排除日志查看接口自身
+        if (LOG_CONTROLLER.equals(point.getSignature().getDeclaringTypeName())) {
+            return point.proceed();
+        }
+
+        HttpServletRequest request = getRequest();
+        String httpMethod = request != null ? request.getMethod() : "";
+        boolean isGet = "GET".equalsIgnoreCase(httpMethod);
+
+        // 解析方法上的 @OperationLog 注解（可能为 null）
+        OperationLog operationLog = findAnnotation(point);
+
+        // 决策：GET 自动记录；非 GET 仅在有注解时记录
+        if (!isGet && operationLog == null) {
+            return point.proceed();
+        }
+
+        long start = System.currentTimeMillis();
+        SysOperationLog entity = buildEntity(point, request, httpMethod);
+
+        // GET 未标注注解时使用默认参数；标注了则优先用注解配置
+        boolean saveResponse = operationLog != null ? operationLog.saveResponse() : true;
+        int maxResponseSize = operationLog != null ? operationLog.maxResponseSize() : DEFAULT_MAX_RESPONSE_SIZE;
+
+        Object result = null;
+        try {
+            result = point.proceed();
+            entity.setStatusCode(200);
+            fillResponse(entity, result, saveResponse, maxResponseSize);
+        } catch (Throwable e) {
+            entity.setStatusCode(500);
+            entity.setErrorMsg(truncate(e.getMessage(), 2000));
+            throw e;
+        } finally {
+            entity.setCostTime(System.currentTimeMillis() - start);
+            sysOperationLogService.saveAsync(entity);
+        }
+        return result;
+    }
+
+    /**
+     * 从连接点解析方法上的 @OperationLog 注解。
+     */
+    private OperationLog findAnnotation(ProceedingJoinPoint point) {
+        try {
+            MethodSignature signature = (MethodSignature) point.getSignature();
+            Method method = signature.getMethod();
+            return method.getAnnotation(OperationLog.class);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * 组装日志实体（基础字段 + 级别/类型判定）。
+     */
+    private SysOperationLog buildEntity(ProceedingJoinPoint point, HttpServletRequest request, String httpMethod) {
+        SysOperationLog entity = new SysOperationLog();
+
+        Integer userId = UserContext.getCurrentUser();
+        entity.setUserId(userId != null ? userId.longValue() : 0L);
+        String username = request != null ? request.getRemoteUser() : null;
+        entity.setUsername(StringUtils.isNotBlank(username) ? username : "anonymous");
+
+        String requestUri = "";
+        if (request != null) {
+            entity.setRequestIp(IpUtils.getIpAddr(request));
+            requestUri = request.getRequestURI();
+            entity.setUserAgent(request.getHeader("User-Agent"));
+            entity.setRequestParams(buildRequestParams(point, request));
+        } else {
+            entity.setRequestParams(buildRequestParams(point, null));
+        }
+        entity.setRequestUri(requestUri);
+        entity.setRequestMethod(httpMethod);
+
+        String methodName = point.getSignature().getName();
+        entity.setLogLevel(OperationLogResolver.resolveLevel(httpMethod, requestUri, methodName).getCode());
+        entity.setOperationType(OperationLogResolver.resolveOperationType(httpMethod, requestUri, methodName));
+        entity.setClassMethod(point.getTarget().getClass().getName() + "." + methodName);
+        return entity;
+    }
+
+    /**
+     * 构建请求参数。<br>
+     * GET 优先使用 queryString；其余序列化方法入参，过滤掉请求/响应等不可序列化对象。<br>
+     */
+    private String buildRequestParams(ProceedingJoinPoint point, HttpServletRequest request) {
+        try {
+            if (request != null && "GET".equalsIgnoreCase(request.getMethod())) {
+                String qs = request.getQueryString();
+                if (StringUtils.isNotBlank(qs)) {
+                    return qs;
+                }
+            }
+            Object[] args = point.getArgs();
+            if (args == null || args.length == 0) {
+                return "";
+            }
+            List<Object> filtered = new ArrayList<Object>();
+            for (Object arg : args) {
+                if (arg == null) {
+                    continue;
+                }
+                if (arg instanceof HttpServletRequest || arg instanceof HttpServletResponse
+                        || arg instanceof HttpSession) {
+                    continue;
+                }
+                filtered.add(arg);
+            }
+            if (filtered.isEmpty()) {
+                return "";
+            }
+            return JSON.toJSONString(filtered);
+        } catch (Exception e) {
+            return "";
+        }
+    }
+
+    /**
+     * 写入响应结果（GZIP 压缩 + 截断）。
+     */
+    private void fillResponse(SysOperationLog entity, Object result, boolean saveResponse, int maxResponseSize) {
+        if (!saveResponse || result == null) {
+            return;
+        }
+        try {
+            String resp = JSON.toJSONString(result);
+            if (resp.length() > maxResponseSize) {
+                resp = resp.substring(0, maxResponseSize) + "...[截断]";
+            }
+            entity.setResponseData(GzipUtil.compress(resp));
+        } catch (Exception e) {
+            log.warn("操作日志响应结果序列化失败, uri={}", entity.getRequestUri(), e);
+        }
+    }
+
+    private HttpServletRequest getRequest() {
+        ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
+        return attrs != null ? attrs.getRequest() : null;
+    }
+
+    private String truncate(String text, int maxLen) {
+        if (text == null) {
+            return null;
+        }
+        return text.length() > maxLen ? text.substring(0, maxLen) : text;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/GlobalExceptionHandler.java b/src/main/java/com/yunhai/userbase/common/GlobalExceptionHandler.java
new file mode 100644
index 0000000..2e740f9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/GlobalExceptionHandler.java
@@ -0,0 +1,86 @@
+package com.yunhai.userbase.common;
+
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.validation.BindException;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+
+import javax.validation.ConstraintViolation;
+import javax.validation.ConstraintViolationException;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * 全局异常处理器：仅处理「参数校验」类异常，把 Spring 默认抛出的冗长消息收敛成「一句话」返回，
+ * 避免前端收到整段 Validation failed ... 堆栈文本。<br>
+ * 返回 HTTP 200 + {@code {code:4, msg:..., data:null}} 结构（而非 HTTP 400），
+ * 与前端 alova errorHandle 的约定一致：status!=200 会被当作网络错误，code=4 才走「参数错误」分支。<br>
+ * 注意：本处理器【不】处理业务异常（如 {@code DException}），业务异常交由项目框架统一处理
+ * （返回 code=5、msg=异常消息），此处若拦截会覆盖框架行为。
+ *
+ * @author chenx
+ */
+@RestControllerAdvice
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class GlobalExceptionHandler {
+
+    /** 参数校验失败的业务码，前端按「参数错误」处理 */
+    private static final int CODE_PARAM_ERROR = 4;
+
+    /** @RequestBody + @Validated/@Valid 失败：提取每个字段的 defaultMessage。 */
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public Map<String, Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
+        return paramError(fieldErrorsMessage(ex.getBindingResult().getFieldErrors()));
+    }
+
+    /** 普通 Bean 参数（如 SortChildren/Move 的 @Validated 请求体对象）校验失败。 */
+    @ExceptionHandler(BindException.class)
+    public Map<String, Object> handleBind(BindException ex) {
+        return paramError(fieldErrorsMessage(ex.getBindingResult().getFieldErrors()));
+    }
+
+    /** 方法级约束（@PathVariable/@RequestParam 上的 @NotNull 等）校验失败。 */
+    @ExceptionHandler(ConstraintViolationException.class)
+    public Map<String, Object> handleConstraintViolation(ConstraintViolationException ex) {
+        String msg = ex.getConstraintViolations().stream()
+                .map(ConstraintViolation::getMessage)
+                .collect(Collectors.joining("；"));
+        return paramError(msg);
+    }
+
+    /** 缺少必需的请求参数（@RequestParam 必填项未传，如 oapi 调用方漏传 groupId）。 */
+    @ExceptionHandler(MissingServletRequestParameterException.class)
+    public Map<String, Object> handleMissingParam(MissingServletRequestParameterException ex) {
+        return paramError("缺少必需的请求参数: " + ex.getParameterName());
+    }
+
+    /** 请求参数类型不匹配（如 Integer 参数收到非数字字符串）。 */
+    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
+    public Map<String, Object> handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
+        return paramError("参数类型不匹配: " + ex.getName());
+    }
+
+    private String fieldErrorsMessage(java.util.List<FieldError> fieldErrors) {
+        if (fieldErrors == null || fieldErrors.isEmpty()) {
+            return "参数校验失败";
+        }
+        return fieldErrors.stream()
+                .map(FieldError::getDefaultMessage)
+                .collect(Collectors.joining("；"));
+    }
+
+    /** HTTP 200 + code/msg/data 结构体，前端根据 code 提示 msg */
+    private Map<String, Object> paramError(String msg) {
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("code", CODE_PARAM_ERROR);
+        body.put("msg", msg);
+        body.put("data", null);
+        return body;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/annotation/OapiLog.java b/src/main/java/com/yunhai/userbase/common/annotation/OapiLog.java
new file mode 100644
index 0000000..f34290c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/annotation/OapiLog.java
@@ -0,0 +1,40 @@
+package com.yunhai.userbase.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 开放接口日志注解。<br>
+ * 标注在 {@code controller.oapi} 方法上：
+ * <ul>
+ *   <li>POST 写操作无需标注，OapiLogAspect 自动全量记录；</li>
+ *   <li>GET 默认不记录（高频查询），标注本注解可强制记录（或开启配置 oapi.log-get=true）；</li>
+ *   <li>value 提供中文操作描述，落入 operation_desc 字段。</li>
+ * </ul>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface OapiLog {
+
+    /**
+     * 操作描述，可选。
+     */
+    String value() default "";
+
+    /**
+     * 是否保存响应结果（GZIP 压缩后入库）。
+     */
+    boolean saveResponse() default true;
+
+    /**
+     * 响应结果序列化后的最大字符数，超过则截断。默认 10KB。
+     */
+    int maxResponseSize() default 10240;
+}
diff --git a/src/main/java/com/yunhai/userbase/common/annotation/OperationLog.java b/src/main/java/com/yunhai/userbase/common/annotation/OperationLog.java
new file mode 100644
index 0000000..db7b8d4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/annotation/OperationLog.java
@@ -0,0 +1,35 @@
+package com.yunhai.userbase.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 操作日志注解。<br>
+ * 标注在 Controller 方法上，AOP 拦截后自动记录操作日志并异步落库。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface OperationLog {
+
+    /**
+     * 操作描述，可选。
+     */
+    String value() default "";
+
+    /**
+     * 是否保存响应结果（GZIP 压缩后入库）。
+     */
+    boolean saveResponse() default true;
+
+    /**
+     * 响应结果序列化后的最大字符数，超过则截断。默认 10KB。
+     */
+    int maxResponseSize() default 10240;
+}
diff --git a/src/main/java/com/yunhai/userbase/common/context/CallerAppContext.java b/src/main/java/com/yunhai/userbase/common/context/CallerAppContext.java
new file mode 100644
index 0000000..0450bf8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/context/CallerAppContext.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.common.context;
+
+/**
+ * 开放接口（oapi）调用方来源上下文：在 oapi 请求链路中保存"触发本次数据变更的订阅方 appKey"，
+ * 供业务层发布 {@code DataSyncEvent} 时写入事件来源，推送分发器据此回推时排除来源应用自身
+ * （避免应用 A 自己调 oapi 写接口后又收到自己的回声）。<br><br>
+ * <b>生命周期：</b>由 {@code OapiCallerAppInterceptor} 在 {@code preHandle} 写入、
+ * {@code afterCompletion} 强制清除（防线程池复用泄漏）。管理后台 /api/* 写接口不走 oapi 拦截器，
+ * 此处为 null，表示"来源非订阅方"，推送不对其做来源排除（全量投递）。<br><br>
+ * 设计与 {@link UserContext} 同套路（ThreadLocal + remove）。
+ */
+public class CallerAppContext {
+
+    private static final ThreadLocal<Integer> CALLER_APP_KEY = new ThreadLocal<>();
+
+    public static void setAppKey(Integer appKey) {
+        CALLER_APP_KEY.set(appKey);
+    }
+
+    public static Integer getAppKey() {
+        return CALLER_APP_KEY.get();
+    }
+
+    public static void clear() {
+        CALLER_APP_KEY.remove();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/context/UserContext.java b/src/main/java/com/yunhai/userbase/common/context/UserContext.java
new file mode 100644
index 0000000..1cca890
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/context/UserContext.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.context;
+
+public class UserContext {
+
+    private static final ThreadLocal<Integer> CURRENT_USER = new ThreadLocal<>();
+
+    public static void setCurrentUser(Integer userId) {
+        CURRENT_USER.set(userId);
+    }
+
+    public static Integer getCurrentUser() {
+        return CURRENT_USER.get();
+    }
+
+    public static void clear() {
+        CURRENT_USER.remove();
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/common/converter/ClientEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/ClientEnumConverter.java
new file mode 100644
index 0000000..1899280
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/ClientEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.platform.utils.enums.ClientEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * ClientEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。
+ *
+ * @author chenx
+ */
+public class ClientEnumConverter extends CommonIntEnumConverter<ClientEnum> {
+
+    public ClientEnumConverter() {
+        super(ClientEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/CommonIntEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/CommonIntEnumConverter.java
new file mode 100644
index 0000000..47be82a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/CommonIntEnumConverter.java
@@ -0,0 +1,47 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * 通用「int &lt;-&gt; 实现 IEnum&lt;Integer&gt; 的枚举」JPA 转换器抽象基类。<br>
+ * <p>
+ * <b>绑定机制（通用做法）：</b>为每个枚举写一个极薄的子类，在构造器里传入枚举 class 即可完成绑定，
+ * 然后实体字段用 {@code @Convert(converter = XxxEnumConverter.class)} 引用该子类。例如：
+ * <pre>
+ *   public class GroupTypeEnumConverter extends CommonIntEnumConverter&lt;GroupTypeEnum&gt; {
+ *       public GroupTypeEnumConverter() { super(GroupTypeEnum.class); }
+ *   }
+ * </pre>
+ * 这样同一套逻辑可服务任意枚举；又因为每个枚举拥有<b>独立的转换器实例</b>，
+ * 彼此之间不会串类型（标准 JPA 的 @Convert 是按 converter 类创建共享单例的，
+ * 若让多个不同枚举共用同一个泛型实例，则无法区分各自的枚举 class，故采用「每枚举一子类」的绑定方式）。
+ * </p>
+ *
+ * @param <E> 必须实现 IEnum&lt;Integer&gt; 的枚举类型
+ * @author chenx
+ */
+public abstract class CommonIntEnumConverter<E extends Enum<E> & IEnum<Integer>>
+        implements AttributeConverter<E, Integer> {
+
+    private final Class<E> enumCls;
+
+    protected CommonIntEnumConverter(Class<E> enumCls) {
+        this.enumCls = enumCls;
+    }
+
+    @Override
+    public Integer convertToDatabaseColumn(E enumVal) {
+        return enumVal == null ? null : enumVal.getKey();
+    }
+
+    @Override
+    public E convertToEntityAttribute(Integer dbVal) {
+        if (dbVal == null) {
+            return null;
+        }
+        // 读库安全：无匹配的枚举值返回 null（不抛异常，避免脏数据导致整棵树加载失败）
+        return IEnum.getByKey(enumCls, dbVal);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/GenderEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/GenderEnumConverter.java
new file mode 100644
index 0000000..40cd93e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/GenderEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.GenderEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * GenderEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。
+ *
+ * @author chenx
+ */
+public class GenderEnumConverter extends CommonIntEnumConverter<GenderEnum> {
+
+    public GenderEnumConverter() {
+        super(GenderEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/GroupTypeEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/GroupTypeEnumConverter.java
new file mode 100644
index 0000000..e604aff
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/GroupTypeEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.GroupTypeEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * GroupTypeEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可，无需重复转换逻辑。
+ *
+ * @author chenx
+ */
+public class GroupTypeEnumConverter extends CommonIntEnumConverter<GroupTypeEnum> {
+
+    public GroupTypeEnumConverter() {
+        super(GroupTypeEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/IntegEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/IntegEnumConverter.java
new file mode 100644
index 0000000..3be7835
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/IntegEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.IntegEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * IntegEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。
+ *
+ * @author chenx
+ */
+public class IntegEnumConverter extends CommonIntEnumConverter<IntegEnum> {
+
+    public IntegEnumConverter() {
+        super(IntegEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/ListIntegerJsonConverter.java b/src/main/java/com/yunhai/userbase/common/converter/ListIntegerJsonConverter.java
new file mode 100644
index 0000000..ccef7bc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/ListIntegerJsonConverter.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.common.converter;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import javax.persistence.AttributeConverter;
+import javax.persistence.Converter;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/14
+ * @description 将 List<Integer> 与 MySQL JSON 字符串互相转换。
+ * 使用 Jackson 的 {@link TypeReference} 明确反序列化为 List<Integer>，
+ * 避免 Hibernate 内置 JSON 类型把数组元素类型读错的问题。
+ */
+@Converter
+public class ListIntegerJsonConverter implements AttributeConverter<List<Integer>, String> {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final TypeReference<List<Integer>> LIST_INTEGER_TYPE = new TypeReference<List<Integer>>() {
+    };
+
+    @Override
+    public String convertToDatabaseColumn(List<Integer> attribute) {
+        if (attribute == null) {
+            return null;
+        }
+        try {
+            return MAPPER.writeValueAsString(attribute);
+        } catch (JsonProcessingException e) {
+            throw new IllegalArgumentException("角色列表序列化 JSON 失败: " + attribute, e);
+        }
+    }
+
+    @Override
+    public List<Integer> convertToEntityAttribute(String dbData) {
+        if (dbData == null || dbData.trim().isEmpty()) {
+            return null;
+        }
+        try {
+            List<Integer> list = MAPPER.readValue(dbData, LIST_INTEGER_TYPE);
+            return list == null ? Collections.emptyList() : list;
+        } catch (JsonProcessingException e) {
+            throw new IllegalArgumentException("角色 JSON 解析失败: " + dbData, e);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/StatusEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/StatusEnumConverter.java
new file mode 100644
index 0000000..4e16f87
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/StatusEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.StatusEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * StatusEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。
+ *
+ * @author chenx
+ */
+public class StatusEnumConverter extends CommonIntEnumConverter<StatusEnum> {
+
+    public StatusEnumConverter() {
+        super(StatusEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/SysRoleEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/SysRoleEnumConverter.java
new file mode 100644
index 0000000..f4c1bed
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/SysRoleEnumConverter.java
@@ -0,0 +1,20 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.SysRoleEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * SysRoleEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。<br>
+ * 注意：sys_user.roles 是「角色 key 的 JSON 列表」，使用 ListIntegerJsonConverter，
+ * 若某处需要「单角色」字段，再引用本转换器即可。
+ *
+ * @author chenx
+ */
+public class SysRoleEnumConverter extends CommonIntEnumConverter<SysRoleEnum> {
+
+    public SysRoleEnumConverter() {
+        super(SysRoleEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/converter/UserTypeEnumConverter.java b/src/main/java/com/yunhai/userbase/common/converter/UserTypeEnumConverter.java
new file mode 100644
index 0000000..6c9743a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/converter/UserTypeEnumConverter.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.common.converter;
+
+import com.yunhai.userbase.enums.UserTypeEnum;
+
+import javax.persistence.AttributeConverter;
+
+/**
+ * UserTypeEnum 专用 JPA 转换器（int &lt;-&gt; 枚举）。<br>
+ * 继承通用基类 CommonIntEnumConverter，仅在构造器绑定枚举 class 即可。
+ *
+ * @author chenx
+ */
+public class UserTypeEnumConverter extends CommonIntEnumConverter<UserTypeEnum> {
+
+    public UserTypeEnumConverter() {
+        super(UserTypeEnum.class);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/interceptor/BoaUserContextInterceptor.java b/src/main/java/com/yunhai/userbase/common/interceptor/BoaUserContextInterceptor.java
new file mode 100644
index 0000000..c06b8e0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/interceptor/BoaUserContextInterceptor.java
@@ -0,0 +1,48 @@
+package com.yunhai.userbase.common.interceptor;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.userbase.common.context.UserContext;
+import com.yunhai.userbase.service.impl.UserCenterService;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * 把当前登录用户写入 {@link UserContext}（供 JPA 审计监听器 @PrePersist/@PreUpdate 与操作日志切面使用）。<br><br>
+ * 登录名取自 CAS 客户端写入的 {@code request.getRemoteUser()}（cas-client-core 过滤器已建立会话）；
+ * 再经本地 {@link UserCenterService} 组装 {@link BoaUser} 取其 id 写入 ThreadLocal。
+ * 原 bsch 的 {@code BschBaseOpenApi.getUserInfoWithDept} 与 {@code LocalMemCache} 已移除，
+ * 统一改用基础平台用户模型与本地服务中心。
+ */
+@Component
+public class BoaUserContextInterceptor implements HandlerInterceptor {
+
+    @Autowired
+    private UserCenterService userCenterService;
+
+    @Override
+    public boolean preHandle(HttpServletRequest request,
+                             HttpServletResponse response,
+                             Object handler) {
+        String loginName = request.getRemoteUser();
+        if (StringUtils.isBlank(loginName)) {
+            return true;
+        }
+        BoaUser user = userCenterService.getUserInfoWithDeptByAccount(loginName);
+        if (user != null && user.getId() != null && user.getId() != 0) {
+            UserContext.setCurrentUser(user.getId());
+        }
+        return true;
+    }
+
+    @Override
+    public void afterCompletion(HttpServletRequest request,
+                                HttpServletResponse response,
+                                Object handler, Exception ex) {
+        UserContext.clear();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/common/listener/UserAuditListener.java b/src/main/java/com/yunhai/userbase/common/listener/UserAuditListener.java
new file mode 100644
index 0000000..9de06bc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/listener/UserAuditListener.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.common.listener;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.common.context.UserContext;
+import com.yunhai.userbase.entity.BaseEntity;
+
+import javax.persistence.PrePersist;
+import javax.persistence.PreUpdate;
+
+public class UserAuditListener {
+
+    @PrePersist
+    public void prePersist(BaseEntity entity) {
+        System.out.println("=== prePersist 触发 ===");
+        Integer userId = UserContext.getCurrentUser();
+        System.out.println("ThreadLocal userId: " + userId);
+        if (userId != null) {
+            entity.setCreateUser(userId);
+            entity.setUpdateUser(userId);
+        }
+    }
+
+    @PreUpdate
+    public void preUpdate(BaseEntity entity) {
+        System.out.println("=== preUpdate 触发 ===");
+        Integer userId = UserContext.getCurrentUser();
+        System.out.println("ThreadLocal userId: " + userId);
+
+        if (userId != null) {
+            entity.setUpdateUser(userId);
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/common/validation/ValidationGroups.java b/src/main/java/com/yunhai/userbase/common/validation/ValidationGroups.java
new file mode 100644
index 0000000..3ead345
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/common/validation/ValidationGroups.java
@@ -0,0 +1,11 @@
+package com.yunhai.userbase.common.validation;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 22:11
+ * @description
+ */
+public interface  ValidationGroups {
+    interface Create {}
+    interface Update {}
+}
diff --git a/src/main/java/com/yunhai/userbase/config/AppSecretConfig.java b/src/main/java/com/yunhai/userbase/config/AppSecretConfig.java
new file mode 100644
index 0000000..5093768
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/AppSecretConfig.java
@@ -0,0 +1,45 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.appauth.AppAuthProperties;
+import com.yunhai.platform.appauth.AppSecretProvider;
+import com.yunhai.platform.appauth.LocalAppIdentityProvider;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+/**
+ * 用户中心验签密钥源：UserBase 作为密钥权威源，优先从本库 application_info 解析调用方密钥
+ * （覆盖全部「已颁发」应用），并以配置式 {@code yh.app-auth.trustedApps} 兜底平台自身默认密钥。
+ * 显式覆盖 yh-app-auth 默认的 {@code @ConditionalOnMissingBean} 实现，使开放接口签名校验
+ * 不依赖 Redis 中 {@code sign:app:*} 的预填充时机，且能验签所有已颁发应用。<br><br>
+ * 同时注册 UserBase 自身作为出站调用方的身份：固定 appKey=100000，密钥落库，不再依赖 yml
+ * 配置 app-key/app-secret。<br>
+ * <b>注意：</b>两个 Bean 都加 {@code @Primary}，保证 yh-platform starter 在按类型注入时
+ * （如 AppSignInterceptor 需要 LocalAppIdentityProvider）不会因多个候选而报
+ * 「required a single bean, but 2 were found」。
+ */
+@Configuration
+public class AppSecretConfig {
+
+    /**
+     * 入站验签密钥提供方（按类型匹配 AppSecretProvider，@Primary 优先）。
+     * SignKeyCacheService 注入时按具体类名 UserBaseAppSecretProvider 匹配，不走这个接口类型。
+     */
+    @Bean(name = "appSecretProvider")
+    @Primary
+    public AppSecretProvider appSecretProvider(ApplicationInfoRepository repository,
+                                               AppAuthProperties properties) {
+        return new UserBaseAppSecretProvider(repository, properties);
+    }
+
+    /**
+     * 出站身份提供方（按类型匹配 LocalAppIdentityProvider，@Primary 优先）。
+     * AppSignInterceptor 等 yh-platform starter 内部按接口类型注入，需要明确唯一候选。
+     */
+    @Bean(name = "localAppIdentityProvider")
+    @Primary
+    public LocalAppIdentityProvider localAppIdentityProvider(ApplicationInfoRepository repository) {
+        return new UserBaseLocalAppIdentityProvider(repository);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/AsyncConfig.java b/src/main/java/com/yunhai/userbase/config/AsyncConfig.java
new file mode 100644
index 0000000..bf8873a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/AsyncConfig.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+
+import java.util.concurrent.Executor;
+import java.util.concurrent.ThreadPoolExecutor;
+
+/**
+ * 异步线程池配置。<br>
+ * 日志类异步落库统一走有界池 {@code oapiLogExecutor}：<br>
+ * - core 4 / max 16 / queue 1000，高并发下不会为每条日志 new 一个线程；<br>
+ * - DiscardPolicy 丢弃策略：池满时直接丢弃新任务，日志宁可丢失也不拖垮/阻塞主流程。<br>
+ * 管理端操作日志（SysOperationLogServiceImpl.saveAsync）与开放接口日志
+ * （SysOapiLogServiceImpl.saveAsync）均绑定本池。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Configuration
+public class AsyncConfig {
+
+    /**
+     * 日志异步落库线程池（有界）。
+     */
+    @Bean("oapiLogExecutor")
+    public Executor oapiLogExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setCorePoolSize(4);
+        executor.setMaxPoolSize(16);
+        executor.setQueueCapacity(1000);
+        executor.setThreadNamePrefix("oplog-");
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.DiscardPolicy());
+        executor.initialize();
+        return executor;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/CacheConfig.java b/src/main/java/com/yunhai/userbase/config/CacheConfig.java
new file mode 100644
index 0000000..444784a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/CacheConfig.java
@@ -0,0 +1,189 @@
+package com.yunhai.userbase.config;
+
+import com.fasterxml.jackson.annotation.JsonAutoDetect;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.annotation.PropertyAccessor;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import com.github.benmanes.caffeine.cache.Caffeine;
+import com.yunhai.userbase.utils.ConstantUtil;
+import org.springframework.cache.Cache;
+import org.springframework.cache.CacheManager;
+import org.springframework.cache.annotation.EnableCaching;
+import org.springframework.cache.caffeine.CaffeineCacheManager;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.data.redis.cache.RedisCacheConfiguration;
+import org.springframework.data.redis.cache.RedisCacheManager;
+import org.springframework.data.redis.connection.RedisConnection;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.serializer.Jackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.RedisSerializationContext;
+import org.springframework.data.redis.serializer.StringRedisSerializer;
+
+import java.time.Duration;
+import java.util.Collection;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+@EnableCaching
+@Configuration
+public class CacheConfig {
+
+
+    /**
+     * 一级缓存：Redis 分布式缓存管理器。
+     */
+    @Bean
+    public RedisCacheManager redisCacheManager(RedisConnectionFactory factory) {
+        Jackson2JsonRedisSerializer<Object> jacksonSerializer = new Jackson2JsonRedisSerializer<>(Object.class);
+        jacksonSerializer.setObjectMapper(newCacheObjectMapper());
+
+        RedisCacheConfiguration cacheConfig = RedisCacheConfiguration.defaultCacheConfig()
+                .entryTtl(ConstantUtil.CACHE_TTL)                                      // 全局 5 分钟过期
+                .serializeKeysWith(RedisSerializationContext.SerializationPair
+                        .fromSerializer(new StringRedisSerializer()))     // key 用 String
+                .serializeValuesWith(RedisSerializationContext.SerializationPair
+                        .fromSerializer(jacksonSerializer))                // value 用 Jackson
+                .disableCachingNullValues();                               // 禁止缓存 null（防穿透）
+
+        return RedisCacheManager.builder(factory)
+                .cacheDefaults(cacheConfig)
+                .build();
+    }
+
+    /**
+     * 二级缓存：Caffeine 本地内存缓存管理器（Redis 降级兜底）。
+     */
+    @Bean
+    public CaffeineCacheManager caffeineCacheManager() {
+        CaffeineCacheManager manager = new CaffeineCacheManager();
+        manager.setCaffeine(Caffeine.newBuilder()
+                .expireAfterWrite(5, TimeUnit.MINUTES)   // 与 Redis 过期保持一致
+                .maximumSize(10000)                      // 限制本地容量，防止内存溢出
+                .recordStats());
+        manager.setAllowNullValues(false);              // 与 Redis 一致：禁止缓存 null
+        return manager;
+    }
+
+    /**
+     * 默认 RedisTemplate（Jackson 序列化），供项目已有工具类（如 RedisUtil）及手动缓存管理使用。<br>
+     * 覆盖 Boot 自动配置的 JDK 序列化默认实现，与 Spring Cache 注解缓存读写互不干扰。<br>
+     * 当 @Cacheable 无法满足需求（如 Hash/List/Set 结构、按字段读写）时，注入本模板或 RedisUtil 手动管理即可。
+     */
+    @Bean
+    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
+        RedisTemplate<String, Object> template = new RedisTemplate<>();
+        template.setConnectionFactory(factory);
+        template.setKeySerializer(new StringRedisSerializer());
+        template.setHashKeySerializer(new StringRedisSerializer());
+        template.setValueSerializer(jacksonSerializer());
+        template.setHashValueSerializer(jacksonSerializer());
+        template.afterPropertiesSet();
+        return template;
+    }
+
+    /**
+     * 复合（故障转移）缓存管理器：作为全局默认 CacheManager 供 @Cacheable 使用。
+     * 优先 Redis；Redis 不可达 / 未配置时自动降级 Caffeine；后台定时探活，恢复后自动切回。
+     */
+    @Primary
+    @Bean
+    public CacheManager cacheManager(RedisCacheManager redisCacheManager,
+                                     CaffeineCacheManager caffeineCacheManager,
+                                     RedisConnectionFactory redisConnectionFactory) {
+        return new FallbackCacheManager(redisCacheManager, caffeineCacheManager, redisConnectionFactory);
+    }
+
+    /**
+     * 轻量故障转移缓存管理器：Redis 健康时优先 Redis，故障时降级 Caffeine，无业务报错。
+     */
+    static class FallbackCacheManager implements CacheManager {
+
+        private final RedisCacheManager redisManager;
+        private final CaffeineCacheManager caffeineManager;
+        private final RedisConnectionFactory connectionFactory;
+        private final ScheduledExecutorService healthScheduler =
+                Executors.newSingleThreadScheduledExecutor(r -> {
+                    Thread t = new Thread(r, "redis-cache-health");
+                    t.setDaemon(true);
+                    return t;
+                });
+        private volatile boolean redisUp = true;
+
+        FallbackCacheManager(RedisCacheManager redisManager,
+                             CaffeineCacheManager caffeineManager,
+                             RedisConnectionFactory connectionFactory) {
+            this.redisManager = redisManager;
+            this.caffeineManager = caffeineManager;
+            this.connectionFactory = connectionFactory;
+            if (connectionFactory != null) {
+                // 启动即探活（delay=0），之后每 10s 探活一次（Redis 恢复后自动切回）
+                healthScheduler.scheduleAtFixedRate(this::probe, 0, 10, TimeUnit.SECONDS);
+            } else {
+                redisUp = false;
+            }
+        }
+
+        private void probe() {
+            if (connectionFactory == null) {
+                redisUp = false;
+                return;
+            }
+            RedisConnection connection = null;
+            try {
+                connection = connectionFactory.getConnection();
+                redisUp = connection.ping() != null;
+            } catch (Exception e) {
+                redisUp = false;
+            } finally {
+                if (connection != null) {
+                    try {
+                        connection.close();
+                    } catch (Exception ignored) {
+                        // 关闭失败忽略，下次探活重试
+                    }
+                }
+            }
+        }
+
+        @Override
+        public Cache getCache(String name) {
+            // AI-FIX: 不在请求线程做同步探活。redisUp 仅由后台定时探活(每 10s)维护。
+            // 否则 Redis 不可达时，每个 @Cacheable/@CacheEvict 都会同步阻塞一个连接超时（约 2s），
+            // resetAppSecret 等多次访问缓存的接口会累计到 4s+。Caffeine 降级必须零阻塞。
+            return redisUp ? redisManager.getCache(name) : caffeineManager.getCache(name);
+        }
+
+        @Override
+        public Collection<String> getCacheNames() {
+            return redisUp ? redisManager.getCacheNames() : caffeineManager.getCacheNames();
+        }
+    }
+
+    /** 统一构建带类型信息的 Jackson 序列化器（解决泛型/乱码），供 RedisTemplate 复用。 */
+    private Jackson2JsonRedisSerializer<Object> jacksonSerializer() {
+        Jackson2JsonRedisSerializer<Object> jackson = new Jackson2JsonRedisSerializer<>(Object.class);
+        jackson.setObjectMapper(newCacheObjectMapper());
+        return jackson;
+    }
+
+    /** 构建缓存专用 ObjectMapper：类型信息 + 可见性 + Java 8 时间类型支持。 */
+    private ObjectMapper newCacheObjectMapper() {
+        ObjectMapper mapper = new ObjectMapper();
+        // 允许任意字段可见，保证反序列化不依赖 getter/setter
+        mapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
+        // 记录完整类型信息，保证泛型/多态对象反序列化正常（解决 JDK 序列化乱码、泛型丢失）
+        mapper.activateDefaultTyping(LaissezFaireSubTypeValidator.instance,
+                ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY);
+        // 支持 Java 8 时间类型（LocalDateTime 等），否则缓存含时间字段的实体（如 ApplicationInfo.createTime）会序列化失败
+        mapper.registerModule(new JavaTimeModule());
+        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+        return mapper;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/Config.java b/src/main/java/com/yunhai/userbase/config/Config.java
new file mode 100644
index 0000000..a4e3317
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/Config.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.config;
+
+import java.util.ResourceBundle;
+
+/**
+ * @author chenx
+ * @version 1.0
+ * @date 2025/4/27 14:31
+ */
+
+public enum Config
+{
+    Inst;
+
+    // 末尾不要带斜杠：各控制器用 API_PATH + "/xxx/" 拼路径，若这里带尾斜杠会变成
+    // "/{platform}//xxx/" 这种字面双斜杠；Boot 2.6+ 默认 PathPatternParser 不合并连续斜杠，
+    // 会导致 /api/xxx 这类正常请求匹配不上而 404（旧 AntPathMatcher 会自动合并，故以前不报错）。
+    public static final String API_PATH = "/{platform}"; // manage / api / mobiapi
+    public static final String OPEN_API_PATH = "/oapi/";
+
+    public String getString(String key)
+    {
+        ResourceBundle resource = ResourceBundle.getBundle("config");
+        return resource.getString(key);
+    }
+
+    public int getInt(String key)
+    {
+        String value = getString(key);
+        return Integer.parseInt(value);
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/config/DWebMvcConfig.java b/src/main/java/com/yunhai/userbase/config/DWebMvcConfig.java
new file mode 100644
index 0000000..ebb16e9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/DWebMvcConfig.java
@@ -0,0 +1,37 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.userbase.common.interceptor.BoaUserContextInterceptor;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class DWebMvcConfig implements WebMvcConfigurer
+{
+    @Autowired
+    private BoaUserContextInterceptor boaUserContextInterceptor;
+    @Autowired
+    private OapiCallerAppInterceptor oapiCallerAppInterceptor;
+
+    @Override
+    public void addCorsMappings(CorsRegistry registry)
+    {
+        registry.addMapping("/**")
+                .allowedOrigins("*")
+                .allowedMethods("POST", "GET", "PUT", "OPTIONS", "DELETE")
+                .allowedHeaders("*")
+                .maxAge(3600).allowCredentials(true);
+    }
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        // oapi 调用方来源注入：仅命中 /oapi/**，供推送来源排除使用
+        registry.addInterceptor(oapiCallerAppInterceptor)
+                .addPathPatterns("/oapi/**");
+        registry.addInterceptor(boaUserContextInterceptor)
+                .addPathPatterns("/**")
+                .excludePathPatterns("/login", "/logout", "/static/**", "/error", "/upload/**");
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/config/FileStorageConfig.java b/src/main/java/com/yunhai/userbase/config/FileStorageConfig.java
new file mode 100644
index 0000000..cdd603c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/FileStorageConfig.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.userbase.utils.FileUtil;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import javax.annotation.PostConstruct;
+
+/**
+ * 文件存储配置注入。<br>
+ * 在 Spring 启动完成后，将上传根目录与 Web 访问前缀注入 FileUtil 静态字段，<br>
+ * 供上传工具类拼接完整可访问 URL 使用。<br>
+ *
+ * @author chenx
+ */
+@Component
+public class FileStorageConfig {
+
+    @Value("${FILE_PATH}")
+    private String filePath;
+
+    @Value("${FILE_WEB_PATH}")
+    private String fileWebPath;
+
+    /**
+     * 启动时注入存储配置到 FileUtil。<br>
+     */
+    @PostConstruct
+    public void init() {
+        FileUtil.init(filePath, fileWebPath);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/JacksonConfig.java b/src/main/java/com/yunhai/userbase/config/JacksonConfig.java
new file mode 100644
index 0000000..7f6d788
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/JacksonConfig.java
@@ -0,0 +1,44 @@
+package com.yunhai.userbase.config;
+
+import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateDeserializer;
+import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateTimeDeserializer;
+import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateSerializer;
+import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+
+/**
+ * 全局 Jackson 日期格式统一。
+ *
+ * <p>Spring Boot 的 {@code spring.jackson.date-format} 只作用于 {@link java.util.Date}，
+ * 对 {@code LocalDateTime}/{@code LocalDate} 无效；且 {@code spring.jackson.local-date-time-format}
+ * 并非 {@code JacksonProperties} 的合法绑定项（会被静默忽略）。本配置把 Nacos 中已配置的
+ * {@code spring.jackson.date-format} 同时应用到 JSR-310 时间类型，做到全局统一。
+ *
+ * <p>仅用 {@code serializerByType}/{@code deserializerByType} 覆盖 JavaTimeModule 默认序列化器，
+ * 不 new 整个 ObjectMapper，因此不会禁用 Spring Boot 的 Jackson 自动配置；
+ * 字段上的 {@code @JsonFormat} 优先级更高，不受影响。
+ */
+@Configuration
+public class JacksonConfig {
+
+    @Bean
+    public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer(
+            @Value("${spring.jackson.date-format:yyyy-MM-dd HH:mm:ss}") String dateFormat) {
+        DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern(dateFormat);
+        DateTimeFormatter dateFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+        return (Jackson2ObjectMapperBuilder builder) -> {
+            builder.serializerByType(LocalDateTime.class, new LocalDateTimeSerializer(dateTimeFormatter));
+            builder.deserializerByType(LocalDateTime.class, new LocalDateTimeDeserializer(dateTimeFormatter));
+            builder.serializerByType(LocalDate.class, new LocalDateSerializer(dateFormatter));
+            builder.deserializerByType(LocalDate.class, new LocalDateDeserializer(dateFormatter));
+        };
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/MyWebAppConfigurer.java b/src/main/java/com/yunhai/userbase/config/MyWebAppConfigurer.java
new file mode 100644
index 0000000..c439d9d
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/MyWebAppConfigurer.java
@@ -0,0 +1,29 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class  MyWebAppConfigurer  implements WebMvcConfigurer {
+
+    @Value("${FILE_PATH}")
+    public  String FILE_PATH;
+
+    @Override
+    public void addResourceHandlers(ResourceHandlerRegistry registry) {
+        String IMG_FILE_WEB_PATH = "/upload/image/";
+        String File_FILE_WEB_PATH = "/upload/file/";
+        String ICON_FILE_WEB_PATH = "/upload/icon/";
+        String WORD_FILE_WEB_PATH = "/upload/word/";
+        String HTML_FILE_WEB_PATH = "/upload/html/";
+        registry.addResourceHandler(IMG_FILE_WEB_PATH + "**").addResourceLocations("file:" + FILE_PATH + "/image/");
+        registry.addResourceHandler(File_FILE_WEB_PATH + "**").addResourceLocations("file:" + FILE_PATH + "/file/");
+        registry.addResourceHandler(ICON_FILE_WEB_PATH+"**").addResourceLocations("file:"+FILE_PATH+"/icon/");
+        registry.addResourceHandler(WORD_FILE_WEB_PATH+"**").addResourceLocations("file:"+FILE_PATH+"/word/");
+        registry.addResourceHandler(HTML_FILE_WEB_PATH+"**").addResourceLocations("file:"+FILE_PATH+"/html/");
+
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/config/OapiCallerAppInterceptor.java b/src/main/java/com/yunhai/userbase/config/OapiCallerAppInterceptor.java
new file mode 100644
index 0000000..ed6f41b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/OapiCallerAppInterceptor.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.appauth.AppAuthFilter;
+import com.yunhai.userbase.common.context.CallerAppContext;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * oapi 调用方来源注入拦截器：在 oapi 请求处理前，从 yh-app-auth 验签过滤器写入的
+ * {@link AppAuthFilter#APP_AUTH_ATTR}（调用方 appKey）解析出整型 appKey，
+ * 存入 {@link CallerAppContext}；请求结束（无论成功/异常）在 {@code afterCompletion} 强制清除，
+ * 防止线程池复用导致 appKey 串号、进而误把其他订阅方排除。<br><br>
+ * 配合 {@code PushDispatcher} 的来源排除逻辑，实现"应用自己触发的变更不回推给自己"。
+ * 管理后台 /api/* 不走此拦截器 → CallerAppContext 为 null → 推送对该来源不做排除（全量投递）。
+ */
+@Component
+public class OapiCallerAppInterceptor implements HandlerInterceptor {
+
+    @Override
+    public boolean preHandle(HttpServletRequest request,
+                             HttpServletResponse response,
+                             Object handler) {
+        Object attr = request.getAttribute(AppAuthFilter.APP_AUTH_ATTR);
+        if (attr == null) {
+            return true;
+        }
+        String appKeyStr = (attr instanceof String) ? (String) attr : String.valueOf(attr);
+        if (StringUtils.isBlank(appKeyStr)) {
+            return true;
+        }
+        try {
+            CallerAppContext.setAppKey(Integer.valueOf(appKeyStr.trim()));
+        } catch (NumberFormatException ignored) {
+            // 非法 appKey 格式：不设置来源，等同"非订阅方来源"，推送全量投递
+        }
+        return true;
+    }
+
+    @Override
+    public void afterCompletion(HttpServletRequest request,
+                                HttpServletResponse response,
+                                Object handler, Exception ex) {
+        CallerAppContext.clear();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/OpenApiAuthEnforceConfiguration.java b/src/main/java/com/yunhai/userbase/config/OpenApiAuthEnforceConfiguration.java
new file mode 100644
index 0000000..2779fac
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/OpenApiAuthEnforceConfiguration.java
@@ -0,0 +1,93 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.appauth.AppAuthFilter;
+import com.yunhai.platform.appauth.AppAuthProperties;
+import com.yunhai.platform.auth.UserDetailsProvider;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.service.impl.UserCenterService;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.web.servlet.FilterRegistrationBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.core.Ordered;
+
+import javax.servlet.Filter;
+import javax.servlet.FilterChain;
+import javax.servlet.ServletException;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+
+/**
+ * 强制开放接口必须带应用签名 + UserBase 自身 CAS 认证兜底的 UserDetailsProvider。<br>
+ * <br>
+ * yh-app-auth 的 {@link AppAuthFilter} 设计为「无签名头则放行」（以兼容浏览器 CAS 流），
+ * 但 UserBase 作为用户中心的开放接口（{/open/api/**}）与内部密钥兜底端点（{/oapi/internal/**}）
+ * 绝不允许匿名访问。本过滤器在 {@code AppAuthFilter} 之后运行，校验其写入的请求属性：
+ * 已验签（属性存在）则放行，否则返回 401。<br>
+ * 顺序须晚于 {@code AppAuthFilter}（HIGHEST_PRECEDENCE+10），故置为 +11。<br>
+ * <br>
+ *
+ * 额外注册 {@code UserDetailsProvider}（@Bean @Primary，名=userDetailsProvider）：
+ * 覆盖 yh-auth-spring-boot-starter 新版默认的 NoOpUserDetailsProvider（调用直接抛
+ * UnsupportedOperationException「未配置 UserDetailsProvider」）。必须「显式 @Bean
+ * + @Primary」
+ * 而不能只靠 @Component 扫描：starter 新版 AutoConfiguration 运行顺序可能早于 UserBase 组件扫描，
+ * 导致其 @ConditionalOnMissingBean 抢先注册 NoOp，PathBasedAuthInterceptor 注入后首次请求即抛错。
+ */
+@Configuration
+@EnableConfigurationProperties({ SignKeyInternalProperties.class, AppAuthProperties.class })
+public class OpenApiAuthEnforceConfiguration {
+
+    @Bean
+    public FilterRegistrationBean<RequireAppSignFilter> requireAppSignFilter() {
+        FilterRegistrationBean<RequireAppSignFilter> bean = new FilterRegistrationBean<>();
+        bean.setFilter(new RequireAppSignFilter());
+        bean.addUrlPatterns("/open/api/*", "/oapi/*");
+        bean.setOrder(Ordered.HIGHEST_PRECEDENCE + 11);
+        return bean;
+    }
+
+    /**
+     * 内部开放接口（/oapi/internal/*）来源 IP 白名单：
+     * 在验签过滤器之前先执行（HIGHEST_PRECEDENCE + 9），先卡掉公网来源再进行后续处理。
+     * 配置项 yh.sign-key-internal.ips / enabled 可由 Nacos 下发。
+     */
+    @Bean
+    public FilterRegistrationBean<SignKeyInternalIpFilter> signKeyInternalIpFilter(
+            SignKeyInternalProperties properties) {
+        FilterRegistrationBean<SignKeyInternalIpFilter> bean = new FilterRegistrationBean<>();
+        bean.setFilter(new SignKeyInternalIpFilter(properties));
+        bean.addUrlPatterns("/oapi/internal/*");
+        bean.setOrder(Ordered.HIGHEST_PRECEDENCE + 9);
+        return bean;
+    }
+
+    /**
+     * UserBase 本地 CAS 登录用户提供者：按登录名/手机号查 UserBase 自身库返回 BoaUser。<br>
+     * 加 {@code @Primary} 稳定覆盖 yh-auth 默认 NoOp 实现；bean 名固定=userDetailsProvider，
+     * 与 starter 默认同名，即使开启 allow-bean-definition-overriding=false 也能优先匹配。
+     */
+    @Bean(name = "userDetailsProvider")
+    @Primary
+    public UserDetailsProvider userDetailsProvider(UserCenterService userCenterService) {
+        return new UserBaseUserDetailsProvider(userCenterService);
+    }
+
+    public static class RequireAppSignFilter implements Filter {
+        @Override
+        public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
+                throws IOException, ServletException {
+            HttpServletRequest req = (HttpServletRequest) request;
+            HttpServletResponse res = (HttpServletResponse) response;
+            if (req.getAttribute(AppAuthFilter.APP_AUTH_ATTR) == null) {
+                res.sendError(HttpServletResponse.SC_UNAUTHORIZED, "missing app signature");
+                return;
+            }
+            chain.doFilter(request, response);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/PasswordEncoderConfig.java b/src/main/java/com/yunhai/userbase/config/PasswordEncoderConfig.java
new file mode 100644
index 0000000..83ca123
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/PasswordEncoderConfig.java
@@ -0,0 +1,29 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+
+/**
+ * 密码编码器配置：统一使用 BCrypt。<br>
+ * 用户中心存库与后续 CAS 登录校验共用同一编码器，保证加密/校验规则一致。<br>
+ *
+ * @author chenx
+ * @date 2026/7/23
+ * @description BCrypt 密码编码器 Bean
+ */
+@Configuration
+public class PasswordEncoderConfig {
+
+    /**
+     * BCrypt 密码编码器。<br>
+     * strength 使用默认 10，兼顾安全与性能；CAS 侧用同一 encoder 的 matches 校验即可。<br>
+     *
+     * @return PasswordEncoder
+     */
+    @Bean
+    public PasswordEncoder passwordEncoder() {
+        return new BCryptPasswordEncoder();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/PushMqConfig.java b/src/main/java/com/yunhai/userbase/config/PushMqConfig.java
new file mode 100644
index 0000000..2be5b9a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/PushMqConfig.java
@@ -0,0 +1,102 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.amqp.core.*;
+import org.springframework.amqp.rabbit.config.SimpleRabbitListenerContainerFactory;
+import org.springframework.amqp.rabbit.connection.ConnectionFactory;
+import org.springframework.amqp.rabbit.core.RabbitTemplate;
+import org.springframework.amqp.support.converter.Jackson2JsonMessageConverter;
+import org.springframework.amqp.support.converter.MessageConverter;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import com.yunhai.userbase.model.push.PushTaskMessage;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 推送订阅 MQ 配置。<br><br>
+ * 拓扑：
+ * <pre>
+ *   push.topic (topic, durable)
+ *     └─ push.main (durable, concurrency=1, x-dead-letter-exchange=push.dlx)   ← 串行消费，可观测
+ *   push.dlx (fanout, durable)
+ *     └─ push.dlq (durable)                                                    ← 死信归档（重试耗尽）
+ * </pre>
+ * 连接信息（host/port/user/pwd/vhost）由 Nacos {@code application-infra.yaml} 的 {@code spring.rabbitmq.*}
+ * 公共配置注入，本类不写死（也不改 bootstrap.yml / application.yml）。<br>
+ * 可靠性：消费端手动 ack，失败由 {@code PushConsumer} 应用层自管重试（共 3 次），耗尽进死信队列。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Configuration
+public class PushMqConfig {
+
+    public static final String EXCHANGE_TOPIC = "push.topic";
+    public static final String EXCHANGE_DLX = "push.dlx";
+    public static final String QUEUE_MAIN = "push.main";
+    public static final String QUEUE_DLQ = "push.dlq";
+
+    /** 统一 JSON 消息转换器（固定反序列化为 PushTaskMessage，绕过 trusted-packages 版本差异）。 */
+    @Bean
+    public MessageConverter pushMessageConverter() {
+        Jackson2JsonMessageConverter converter = new Jackson2JsonMessageConverter();
+        converter.setClassMapper(new PushTaskClassMapper(PushTaskMessage.class));
+        return converter;
+    }
+
+    @Bean
+    public TopicExchange pushTopicExchange() {
+        return new TopicExchange(EXCHANGE_TOPIC, true, false);
+    }
+
+    @Bean
+    public FanoutExchange pushDlxExchange() {
+        return new FanoutExchange(EXCHANGE_DLX, true, false);
+    }
+
+    /** 主队列：单消费者串行 + 死信路由到 push.dlx。 */
+    @Bean
+    public Queue pushMainQueue() {
+        Map<String, Object> args = new HashMap<>();
+        args.put("x-dead-letter-exchange", EXCHANGE_DLX);
+        return new Queue(QUEUE_MAIN, true, false, false, args);
+    }
+
+    /** 死信队列：归档重试耗尽的任务。 */
+    @Bean
+    public Queue pushDlqQueue() {
+        return new Queue(QUEUE_DLQ, true, false, false);
+    }
+
+    @Bean
+    public Binding pushMainBinding() {
+        return BindingBuilder.bind(pushMainQueue()).to(pushTopicExchange()).with("#");
+    }
+
+    @Bean
+    public Binding pushDlqBinding() {
+        return BindingBuilder.bind(pushDlqQueue()).to(pushDlxExchange());
+    }
+
+    @Bean
+    public RabbitTemplate pushRabbitTemplate(ConnectionFactory connectionFactory) {
+        RabbitTemplate template = new RabbitTemplate(connectionFactory);
+        template.setMessageConverter(pushMessageConverter());
+        return template;
+    }
+
+    /** 消费者容器：手动 ack + 单并发 + prefetch=1，保证串行可观测。 */
+    @Bean(name = "pushListenerContainerFactory")
+    public SimpleRabbitListenerContainerFactory pushListenerContainerFactory(ConnectionFactory connectionFactory) {
+        SimpleRabbitListenerContainerFactory factory = new SimpleRabbitListenerContainerFactory();
+        factory.setConnectionFactory(connectionFactory);
+        factory.setMessageConverter(pushMessageConverter());
+        factory.setAcknowledgeMode(org.springframework.amqp.core.AcknowledgeMode.MANUAL);
+        factory.setConcurrentConsumers(1);
+        factory.setMaxConcurrentConsumers(1);
+        factory.setPrefetchCount(1);
+        return factory;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/PushTaskClassMapper.java b/src/main/java/com/yunhai/userbase/config/PushTaskClassMapper.java
new file mode 100644
index 0000000..fce04f8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/PushTaskClassMapper.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.amqp.core.MessageProperties;
+import org.springframework.amqp.support.converter.ClassMapper;
+
+/**
+ * 推送消息固定反序列化为 {@link PushTaskMessage}，绕过 Jackson2JsonMessageConverter 的
+ * trusted-packages 安全限制（不同 spring-amqp 版本该方法签名/默认值不一致，编译期不可靠）。<br>
+ * 生产者端序列化仍由 Jackson2JsonMessageConverter 完成（写入 __TypeId__），消费者端忽略 __TypeId__
+ * 直接按本映射器返回 PushTaskMessage，类型单一且可控。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+public class PushTaskClassMapper implements ClassMapper {
+
+    private final Class<?> payloadClass;
+
+    public PushTaskClassMapper(Class<?> payloadClass) {
+        this.payloadClass = payloadClass;
+    }
+
+    @Override
+    public Class<?> toClass(MessageProperties properties) {
+        return payloadClass;
+    }
+
+    @Override
+    public void fromClass(Class<?> clazz, MessageProperties properties) {
+        properties.setHeader("__TypeId__", clazz.getName());
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/SignKeyInternalIpFilter.java b/src/main/java/com/yunhai/userbase/config/SignKeyInternalIpFilter.java
new file mode 100644
index 0000000..2359640
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/SignKeyInternalIpFilter.java
@@ -0,0 +1,124 @@
+package com.yunhai.userbase.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.util.CollectionUtils;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import javax.servlet.FilterChain;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.net.Inet6Address;
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.List;
+
+/**
+ * 内部开放接口（/oapi/internal/*）来源 IP 白名单过滤器。<p>
+ * 防止密钥兜底端点（/oapi/internal/sign-key/{appId}）被公网直接枚举调用；
+ * 只允许内网 / 显式配置的白名单来源通过，未命中返回 403。<p>
+ * 支持 X-Forwarded-For / X-Real-IP 等常见代理头解析，取最左侧真实来源 IP 做校验。
+ */
+public class SignKeyInternalIpFilter extends OncePerRequestFilter {
+
+    private static final Logger log = LoggerFactory.getLogger(SignKeyInternalIpFilter.class);
+
+    private final SignKeyInternalProperties properties;
+
+    public SignKeyInternalIpFilter(SignKeyInternalProperties properties) {
+        this.properties = properties;
+    }
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
+            throws ServletException, IOException {
+        if (!properties.isEnabled()) {
+            filterChain.doFilter(request, response);
+            return;
+        }
+        String sourceIp = resolveSourceIp(request);
+        List<String> effectiveIps = properties.getEffectiveIps();
+        if (CollectionUtils.isEmpty(effectiveIps) || matchAny(sourceIp, effectiveIps)) {
+            filterChain.doFilter(request, response);
+            return;
+        }
+        log.warn("[SignKeyInternal] 拒绝非白名单来源访问内部接口: uri={}, sourceIp={}, whitelist={}",
+                request.getRequestURI(), sourceIp, effectiveIps);
+        response.setStatus(HttpServletResponse.SC_FORBIDDEN);
+        response.setContentType("application/json;charset=UTF-8");
+        response.getWriter().write("{\"code\":403,\"msg\":\"内部接口不允许从该来源访问\",\"data\":null}");
+        response.getWriter().flush();
+    }
+
+    private static String resolveSourceIp(HttpServletRequest request) {
+        String[] headers = new String[] {
+                "X-Forwarded-For",
+                "X-Real-IP",
+                "Proxy-Client-IP",
+                "WL-Proxy-Client-IP",
+                "HTTP_CLIENT_IP",
+                "HTTP_X_FORWARDED_FOR"
+        };
+        for (String header : headers) {
+            String raw = request.getHeader(header);
+            if (raw == null || raw.isEmpty() || "unknown".equalsIgnoreCase(raw)) {
+                continue;
+            }
+            // X-Forwarded-For 可能是 多个IP逗号分隔，取最左侧
+            String first = raw.split(",")[0].trim();
+            if (!first.isEmpty()) {
+                return first;
+            }
+        }
+        return request.getRemoteAddr();
+    }
+
+    private static boolean matchAny(String ip, List<String> cidrs) {
+        for (String cidr : cidrs) {
+            if (matchCidr(ip, cidr)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static boolean matchCidr(String ip, String cidr) {
+        if (ip == null || cidr == null) {
+            return false;
+        }
+        try {
+            int prefixLen;
+            String network;
+            if (cidr.contains("/")) {
+                String[] parts = cidr.split("/");
+                network = parts[0].trim();
+                prefixLen = Integer.parseInt(parts[1].trim());
+            } else {
+                network = cidr.trim();
+                // 判断地址族决定默认前缀长度
+                InetAddress na = InetAddress.getByName(network);
+                prefixLen = (na instanceof Inet6Address) ? 128 : 32;
+            }
+            InetAddress ipAddr = InetAddress.getByName(ip);
+            InetAddress netAddr = InetAddress.getByName(network);
+            if (ipAddr.getClass() != netAddr.getClass()) {
+                return false;
+            }
+            byte[] ipBytes = ipAddr.getAddress();
+            byte[] netBytes = netAddr.getAddress();
+            int bits = prefixLen;
+            for (int i = 0; i < ipBytes.length && bits > 0; i++) {
+                int mask = bits >= 8 ? 0xFF : (0xFF << (8 - bits));
+                if ((ipBytes[i] & mask) != (netBytes[i] & mask)) {
+                    return false;
+                }
+                bits -= 8;
+            }
+            return true;
+        } catch (UnknownHostException | NumberFormatException ignored) {
+            return false;
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/SignKeyInternalProperties.java b/src/main/java/com/yunhai/userbase/config/SignKeyInternalProperties.java
new file mode 100644
index 0000000..f5eb76b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/SignKeyInternalProperties.java
@@ -0,0 +1,55 @@
+package com.yunhai.userbase.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * 内部开放接口（/oapi/internal/*）访问白名单 IP 配置。<br>
+ * 支持单 IP、CIDR（如 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.1/32）。<br>
+ * <p>
+ * 可在 Nacos 上配置，例如：<pre>
+ * yh:
+ *   sign-key-internal:
+ *     ips:
+ *       - 10.0.0.0/8
+ *       - 172.16.0.0/12
+ *       - 192.168.0.0/16
+ *       - 127.0.0.1/32
+ *       - 172.20.10.5/32   # 某台固定机器
+ * </pre>
+ * 未配置时，默认允许 10/172.16-31/192.168 私有段 + 127.0.0.1（方便本地开发/内网部署）。
+ */
+@ConfigurationProperties(prefix = "yh.sign-key-internal")
+public class SignKeyInternalProperties {
+
+    /** 显式允许的来源 IP（CIDR 或 单 IP）。为空时使用默认私有段规则。 */
+    private List<String> ips = new ArrayList<>();
+
+    /** 是否启用白名单校验；设置 false 可临时关闭（生产不建议）。 */
+    private boolean enabled = true;
+
+    public List<String> getIps() { return ips; }
+
+    public void setIps(List<String> ips) { this.ips = ips; }
+
+    public boolean isEnabled() { return enabled; }
+
+    public void setEnabled(boolean enabled) { this.enabled = enabled; }
+
+    /** 未配置 ips 时返回默认私有段 + localhost 规则。 */
+    public List<String> getEffectiveIps() {
+        if (ips != null && !ips.isEmpty()) {
+            return ips;
+        }
+        return Arrays.asList(
+                "10.0.0.0/8",
+                "172.16.0.0/12",
+                "192.168.0.0/16",
+                "127.0.0.1/32",
+                "0:0:0:0:0:0:0:1/128"
+        );
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/SwaggerConfig.java b/src/main/java/com/yunhai/userbase/config/SwaggerConfig.java
new file mode 100644
index 0000000..3018a12
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/SwaggerConfig.java
@@ -0,0 +1,37 @@
+package com.yunhai.userbase.config;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springdoc.core.customizers.GlobalOperationCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.method.HandlerMethod;
+
+/**
+ * 接口文档（springdoc-openapi，替代旧 Springfox）。<br><br>
+ * 提供统一文档元信息；并通过全局定制器隐藏由切面注入的 {@code BoaUser authUserWithDept} 参数，
+ * 避免其作为请求体出现在文档中（该参数不参与 HTTP 入参，由 {@code BoaUserArgumentResolver} 解析）。
+ */
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI userBaseOpenAPI() {
+        return new OpenAPI()
+                .info(new Info()
+                        .title("用户中心接口文档")
+                        .description("UserBase 用户中心 OpenAPI 文档（springdoc-openapi）")
+                        .version("0.0.1"));
+    }
+
+    /** 隐藏切面注入的登录用户参数，保持文档整洁。 */
+    @Bean
+    public GlobalOperationCustomizer hideAuthUserParam() {
+        return (operation, handlerMethod) -> {
+            if (operation.getParameters() != null) {
+                operation.getParameters().removeIf(p -> "authUserWithDept".equals(p.getName()));
+            }
+            return operation;
+        };
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/UserBaseAppSecretProvider.java b/src/main/java/com/yunhai/userbase/config/UserBaseAppSecretProvider.java
new file mode 100644
index 0000000..3f07052
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/UserBaseAppSecretProvider.java
@@ -0,0 +1,98 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.appauth.AppAuthProperties;
+import com.yunhai.platform.appauth.AppSecretProvider;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * UserBase 作为「应用密钥权威源」的验签密钥提供方。<br>
+ * <br>
+ * 解析优先级：<br>
+ * 1) 本库 application_info —— 覆盖全部「已颁发」应用，新增/重置密钥后即时生效；<br>
+ * 2) 配置式受信应用 {@code yh.app-auth.trusted-apps} —— 平台自身默认密钥（如 应用中心 100616）
+ * 兜底，使其即便尚未落库也可验签，避免「默认 appKey 未建行」导致验签失败。<br>
+ * <br>
+ * 带 60s 本地 TTL 缓存，避免每次验签直打库（密钥变更最长 60s 后生效）。<br>
+ * <br>
+ * 这样 UserBase 作为颁发方不依赖 Redis 预热、也不局限于 trustedApps 写死的少量密钥，
+ * 能够验签所有它已颁发的应用。
+ */
+public class UserBaseAppSecretProvider implements AppSecretProvider {
+
+    private final ApplicationInfoRepository repository;
+    private final Map<String, String> trustedApps;
+    private final ConcurrentHashMap<String, CacheEntry> cache = new ConcurrentHashMap<>();
+    private static final long TTL_MS = 60_000L;
+
+    public UserBaseAppSecretProvider(ApplicationInfoRepository repository, AppAuthProperties properties) {
+        this.repository = repository;
+        this.trustedApps = properties.getTrustedApps();
+    }
+
+    @Override
+    public String getSecret(String appKey) {
+        if (appKey == null) {
+            return null;
+        }
+        long now = System.currentTimeMillis();
+        CacheEntry hit = cache.get(appKey);
+        if (hit != null && now - hit.ts < TTL_MS) {
+            return hit.secret;
+        }
+        String secret = null;
+        try {
+            Integer id = parse(appKey);
+            if (id != null) {
+                ApplicationInfo info = repository.findByAppKey(id);
+                if (info != null && info.getAppSecret() != null && !info.getAppSecret().trim().isEmpty()) {
+                    secret = info.getAppSecret();
+                }
+            }
+        } catch (Exception ignored) {
+            // 查询异常不阻断，继续走配置兜底
+        }
+        if (secret == null) {
+            secret = trustedApps.get(appKey);
+        }
+        cache.put(appKey, new CacheEntry(now, secret));
+        return secret;
+    }
+
+    /**
+     * 主动失效：立刻清除本地缓存中指定 appKey 的条目，密钥重置后调用 → 下一次 getSecret 直查 DB 拿新值，
+     * 不再受最长 60s TTL 生效窗口限制。
+     */
+    public void invalidate(String appKey) {
+        if (appKey == null) {
+            return;
+        }
+        cache.remove(appKey);
+    }
+
+    /** 主动失效：立刻清空全部本地缓存（refreshAll / Redis 全量对账时调用）。 */
+    public void invalidateAll() {
+        cache.clear();
+    }
+
+    private static Integer parse(String appKey) {
+        try {
+            return Integer.parseInt(appKey.trim());
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    private static final class CacheEntry {
+        final long ts;
+        final String secret;
+
+        CacheEntry(long ts, String secret) {
+            this.ts = ts;
+            this.secret = secret;
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/UserBaseLocalAppIdentityProvider.java b/src/main/java/com/yunhai/userbase/config/UserBaseLocalAppIdentityProvider.java
new file mode 100644
index 0000000..1c553ac
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/UserBaseLocalAppIdentityProvider.java
@@ -0,0 +1,71 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.appauth.LocalAppIdentityProvider;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * UserBase 自身作为「出站签名调用方」的身份提供方。<br><br>
+ * 约定：<br>
+ * 1) appKey 固定占用 100000（基石应用段），由 application_bootstrap.sql 初始化脚本幂等插入；<br>
+ * 2) appSecret 从 application_info 表按 appKey=100000 读取，带 60s 本地缓存（密钥重设后 60s 内生效）。<br><br>
+ * 显式覆盖 yh-app-auth-spring-boot-starter 默认的 PropertyLocalAppIdentityProvider（yml 不再需要
+ * 配置 yh.app-auth.app-key / app-secret）。
+ */
+public class UserBaseLocalAppIdentityProvider implements LocalAppIdentityProvider {
+
+    private static final String USER_CENTER_APP_KEY = "100000";
+    private static final int USER_CENTER_APP_KEY_INT = 100000;
+    private static final long TTL_MS = 60_000L;
+
+    private final ApplicationInfoRepository repository;
+    private final ConcurrentHashMap<String, CacheEntry> cache = new ConcurrentHashMap<>();
+
+    public UserBaseLocalAppIdentityProvider(ApplicationInfoRepository repository) {
+        this.repository = repository;
+    }
+
+    @Override
+    public String getAppKey() {
+        return USER_CENTER_APP_KEY;
+    }
+
+    @Override
+    public String getAppSecret() {
+        long now = System.currentTimeMillis();
+        CacheEntry hit = cache.get(USER_CENTER_APP_KEY);
+        if (hit != null && now - hit.ts < TTL_MS) {
+            return hit.secret;
+        }
+        String secret = null;
+        try {
+            ApplicationInfo info = repository.findByAppKey(USER_CENTER_APP_KEY_INT);
+            if (info != null && info.getAppSecret() != null && !info.getAppSecret().trim().isEmpty()) {
+                secret = info.getAppSecret();
+            }
+        } catch (Exception ignored) {
+        }
+        cache.put(USER_CENTER_APP_KEY, new CacheEntry(now, secret));
+        return secret;
+    }
+
+    /**
+     * 主动失效：立刻清除 UserBase 自身（appKey=100000）的本地缓存，密钥重置后调用 →
+     * 下一次 getAppSecret 直查 DB 拿新值，不再受最长 60s TTL 生效窗口限制。
+     */
+    public void invalidate() {
+        cache.remove(USER_CENTER_APP_KEY);
+    }
+
+    private static final class CacheEntry {
+        final long ts;
+        final String secret;
+
+        CacheEntry(long ts, String secret) {
+            this.ts = ts;
+            this.secret = secret;
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/config/UserBaseUserDetailsProvider.java b/src/main/java/com/yunhai/userbase/config/UserBaseUserDetailsProvider.java
new file mode 100644
index 0000000..ccfec7b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/config/UserBaseUserDetailsProvider.java
@@ -0,0 +1,41 @@
+package com.yunhai.userbase.config;
+
+import com.yunhai.platform.auth.UserDetailsProvider;
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.userbase.service.impl.UserCenterService;
+import com.yunhai.userbase.service.impl.UserCenterService;
+
+/**
+ * 平台 {@link UserDetailsProvider} 的 UserBase 本地实现：CAS 会话流解析出登录名/手机号后，
+ * 由本类查 UserBase 自身库，组装成基础平台统一的 {@link BoaUser}。<br><br>
+ *
+ * 本类不再加 {@code @Component}，改为由 {@link OpenApiAuthEnforceConfiguration}
+ * 显式以 {@code @Bean @Primary} 注册（bean 名固定为 {@code userDetailsProvider}），
+ * 原因：yh-auth-spring-boot-starter 新版 AutoConfiguration 处理顺序可能早于 UserBase 组件扫描，
+ * 导致其默认注册的 {@code NoOpUserDetailsProvider}（直接抛 UnsupportedOperationException）
+ * 抢先被 PathBasedAuthInterceptor 注入。显式 @Bean+@Primary 可稳定覆盖默认实现。
+ */
+public class UserBaseUserDetailsProvider implements UserDetailsProvider {
+
+    private final UserCenterService userCenterService;
+
+    public UserBaseUserDetailsProvider(UserCenterService userCenterService) {
+        this.userCenterService = userCenterService;
+    }
+
+    @Override
+    public BoaUser loadByLoginName(String loginName) {
+        if (loginName == null) {
+            return null;
+        }
+        return userCenterService.getUserInfoWithDeptByAccount(loginName.trim());
+    }
+
+    @Override
+    public BoaUser loadByPhone(String phone) {
+        if (phone == null) {
+            return null;
+        }
+        return userCenterService.getUserInfoWithDeptByPhone(phone.trim());
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/AppRoleController.java b/src/main/java/com/yunhai/userbase/controller/api/AppRoleController.java
new file mode 100644
index 0000000..f25da78
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/AppRoleController.java
@@ -0,0 +1,135 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.approle.AppRoleAuthzAppVo;
+import com.yunhai.userbase.model.approle.AppRoleModuleAssignRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserBindRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserVo;
+import com.yunhai.userbase.model.approle.SysAppRoleQuery;
+import com.yunhai.userbase.model.approle.SysAppRoleRequest;
+import com.yunhai.userbase.model.approle.SysAppRoleVo;
+import com.yunhai.userbase.model.approle.UserAppRoleBindRequest;
+import com.yunhai.userbase.service.IAppRoleService;
+import com.yunhai.userbase.utils.PageUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.domain.Sort;
+import org.springframework.data.web.SortDefault;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 应用业务角色管理（角色 CRUD + 角色模块授权 + 用户角色绑定）。<br>
+ */
+@RestController
+@RequestMapping(value = Config.API_PATH + "/approle/")
+public class AppRoleController {
+
+    @Autowired
+    private IAppRoleService appRoleService;
+
+    /**
+     * 角色分页列表 ：name 模糊，appId/allAppFlag/disabled 精确；普通角色回填所属应用名称
+     */
+    @GetMapping("/RoleList")
+    public BasePageResult<SysAppRoleVo> roleList(SysAppRoleQuery query, BasePageQuery pageQuery,
+                                                 @SortDefault(sort = "id", direction = Sort.Direction.DESC) Sort sort) {
+        return PageUtils.toResult(appRoleService.list(query, PageUtils.toPageable(pageQuery, sort)));
+    }
+
+    /**
+     * 新增角色：普通角色（allAppFlag=false，appId 必填，同应用下名称唯一）；<br>
+     * 全应用角色（allAppFlag=true，appId 为空，全应用角色之间名称唯一）。
+     */
+    @OperationLog("新增角色")
+    @PostMapping("RoleAdd")
+    public void roleAdd(@RequestBody @Validated(ValidationGroups.Create.class) SysAppRoleRequest request) {
+        appRoleService.add(request);
+    }
+
+    /**
+     * 编辑角色：仅可改 name/remark/disabled；allAppFlag 与 appId 不允许修改。
+     */
+    @OperationLog("编辑角色")
+    @PostMapping("RoleEdit/{id}")
+    public void roleEdit(@PathVariable Integer id,
+                         @RequestBody @Validated(ValidationGroups.Update.class) SysAppRoleRequest request) {
+        appRoleService.edit(id, request);
+    }
+
+    /**
+     * 删除角色：级联清理该角色的模块授权与用户绑定记录。
+     */
+    @OperationLog("删除角色")
+    @PostMapping("RoleDelete/{id}")
+    public void roleDelete(@PathVariable Integer id) {
+        appRoleService.delete(id);
+    }
+
+    /**
+     * 角色模块授权回显：返回该角色可授权的应用及模块树（已授权 checked=true）。<br>
+     * 普通角色仅本应用；全应用角色返回全部应用（可跨应用授权）。
+     */
+    @GetMapping("/RoleModuleTree")
+    public List<AppRoleAuthzAppVo> roleModuleTree(@RequestParam Integer roleId) {
+        return appRoleService.findRoleModuleTree(roleId);
+    }
+
+    /**
+     * 角色模块授权保存：全量覆盖式更新该角色的模块授权记录。
+     */
+    @OperationLog("保存角色模块授权")
+    @PostMapping("SaveRoleModules")
+    public void saveRoleModules(@RequestBody @Validated AppRoleModuleAssignRequest request) {
+        appRoleService.saveRoleModules(request);
+    }
+
+    /**
+     * 查询角色已绑定的用户列表。
+     */
+    @GetMapping("/RoleUsers")
+    public List<AppRoleUserVo> roleUsers(@RequestParam Integer roleId) {
+        return appRoleService.findRoleUsers(roleId);
+    }
+
+    /**
+     * 角色绑定用户保存（角色维度，全量覆盖）。
+     */
+    @OperationLog("保存角色用户绑定")
+    @PostMapping("SaveRoleUsers")
+    public void saveRoleUsers(@RequestBody @Validated AppRoleUserBindRequest request) {
+        appRoleService.saveRoleUsers(request);
+    }
+
+    /**
+     * 用户绑定角色保存（用户维度，全量覆盖）。
+     */
+    @OperationLog("保存用户角色绑定")
+    @PostMapping("SaveUserRoles")
+    public void saveUserRoles(@RequestBody @Validated UserAppRoleBindRequest request) {
+        appRoleService.saveUserRoles(request);
+    }
+
+    /**
+     * 移除单个用户与角色的绑定关系（精确删除单条记录，非全量重提）。<br>
+     * 前端「用户管理 - 删除」调用此接口。
+     */
+    @OperationLog("移除角色用户绑定")
+    @PostMapping("RemoveRoleUser")
+    public void removeRoleUser(@RequestParam Integer roleId, @RequestParam Integer userId) {
+        appRoleService.removeRoleUser(roleId, userId);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/AppSettingsController.java b/src/main/java/com/yunhai/userbase/controller/api/AppSettingsController.java
new file mode 100644
index 0000000..cc3e9d6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/AppSettingsController.java
@@ -0,0 +1,178 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.appauthz.AppAuthzCategoryVo;
+import com.yunhai.userbase.model.appcategory.AppCategoryQuery;
+import com.yunhai.userbase.model.appcategory.AppCategoryRequest;
+import com.yunhai.userbase.model.appcategory.AppCategoryVo;
+import com.yunhai.userbase.model.application.ApplicationInfoQuery;
+import com.yunhai.userbase.model.application.ApplicationInfoRequest;
+import com.yunhai.userbase.model.application.ApplicationInfoSortVo;
+import com.yunhai.userbase.model.application.ApplicationInfoVo;
+import com.yunhai.userbase.model.application.PushSettingRequest;
+import com.yunhai.userbase.model.application.PushSettingVo;
+import com.yunhai.userbase.model.appmodule.AppModuleQuery;
+import com.yunhai.userbase.model.appmodule.AppModuleRequest;
+import com.yunhai.userbase.model.appmodule.AppModuleVo;
+import com.yunhai.userbase.service.IAppCategoryService;
+import com.yunhai.userbase.service.IApplicationInfoService;
+import com.yunhai.userbase.service.IAppModuleService;
+import com.yunhai.userbase.service.impl.SignKeyCacheService;
+import com.yunhai.userbase.utils.PageUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.domain.Sort;
+import org.springframework.data.web.SortDefault;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@RestController
+@RequestMapping(value = Config.API_PATH + "/app/")
+public class AppSettingsController {
+
+    @Autowired
+    private IAppCategoryService appCategoryService;
+
+    @Autowired
+    private IApplicationInfoService applicationInfoService;
+
+    @Autowired
+    private IAppModuleService appModuleService;
+
+    @Autowired
+    private SignKeyCacheService signKeyCacheService;
+
+
+
+    @OperationLog("新增应用类型")
+    @PostMapping("AddType")
+    public void addType(@RequestBody @Validated(ValidationGroups.Create.class) AppCategoryRequest request) {
+        appCategoryService.add(request);
+    }
+
+    @OperationLog("编辑应用类型")
+    @PostMapping("EditType/{id}")
+    public void editType(@PathVariable Integer id, @RequestBody @Validated(ValidationGroups.Update.class) AppCategoryRequest request) {
+        appCategoryService.edit(id, request);
+    }
+
+    @OperationLog("删除应用类型")
+    @PostMapping("DeleteType/{id}")
+    public void deleteType(@PathVariable Integer id) {
+        appCategoryService.delete(id);
+    }
+
+    @GetMapping("/AppTypeList")
+    public List<AppCategoryVo> appTypeList(AppCategoryQuery query) {
+        return appCategoryService.list(query);
+    }
+
+    @OperationLog("应用类型排序")
+    @PostMapping("/AppTypeSort")
+    public void appTypeSort(@RequestBody List<Integer> ids) {
+        appCategoryService.sort(ids);
+    }
+
+    /**
+     * 应用授权用：获取所有应用类型及其类型下的应用（每个应用含 id/name/icon）。<br>
+     * 类型按 sortNo 升序，类型内应用按 sortNo、id 升序；无应用的类型 app 为空数组。
+     */
+    @GetMapping("/AppAuthzList")
+    public List<AppAuthzCategoryVo> appAuthzList() {
+        return appCategoryService.listWithApps();
+    }
+
+    @OperationLog("新增应用")
+    @PostMapping("AddApp")
+    public void addApp(@RequestBody @Validated(ValidationGroups.Create.class) ApplicationInfoRequest request) {
+        applicationInfoService.add(request);
+    }
+
+    @OperationLog("编辑应用")
+    @PostMapping("EditApp/{id}")
+    public void editApp(@PathVariable Integer id, @RequestBody @Validated(ValidationGroups.Update.class) ApplicationInfoRequest request) {
+        applicationInfoService.edit(id, request);
+    }
+
+    @OperationLog("删除应用")
+    @PostMapping("DeleteApp/{id}")
+    public void deleteApp(@PathVariable Integer id) {
+        applicationInfoService.delete(id);
+    }
+
+    @OperationLog("重置应用密钥")
+    @PostMapping("ResetAppSecret/{id}")
+    public String resetAppSecret(@PathVariable Integer id) {
+        applicationInfoService.resetAppSecret(id);
+        ApplicationInfo info= applicationInfoService.getById(id);
+        return info.getAppSecret();
+    }
+
+    @OperationLog("全量刷新应用签名密钥到Redis")
+    @PostMapping("RefreshSignKeys")
+    public Map<String, Object> refreshSignKeys() {
+        int count = signKeyCacheService.refreshAll();
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("refreshed", count);
+        return result;
+    }
+
+    @GetMapping("/AppList")
+    public BasePageResult<ApplicationInfoVo> appList(ApplicationInfoQuery query, BasePageQuery pageQuery,
+                                                     @SortDefault(sort = "sortNo", direction = Sort.Direction.ASC) Sort sort) {
+        return PageUtils.toResult(applicationInfoService.list(query, PageUtils.toPageable(pageQuery, sort)));
+    }
+
+    @OperationLog("应用排序")
+    @PostMapping("/AppSort")
+    public void appSort(@RequestBody List<Integer> ids) {
+        applicationInfoService.sort(ids);
+    }
+
+    @GetMapping("/AppSortList")
+    public List<ApplicationInfoSortVo> appSortList(@RequestParam Integer categoryId) {
+        return applicationInfoService.findListByCategoryId(categoryId);
+    }
+
+    @OperationLog("新增模块")
+    @PostMapping("AddModule")
+    public void addModule(@RequestBody @Validated(ValidationGroups.Create.class) AppModuleRequest request) {
+        appModuleService.add(request);
+    }
+
+    @OperationLog("编辑模块")
+    @PostMapping("EditModule/{id}")
+    public void editModule(@PathVariable Integer id, @RequestBody @Validated(ValidationGroups.Update.class) AppModuleRequest request) {
+        appModuleService.edit(id, request);
+    }
+
+    @OperationLog("删除模块")
+    @PostMapping("DeleteModule/{id}")
+    public void deleteModule(@PathVariable Integer id) {
+        appModuleService.delete(id);
+    }
+
+    @GetMapping("/ModuleList")
+    public List<AppModuleVo> moduleList(AppModuleQuery query) {
+        return appModuleService.list(query);
+    }
+
+    @OperationLog("保存应用推送设置")
+    @PostMapping("SavePushSetting/{id}")
+    public void savePushSetting(@PathVariable Integer id, @RequestBody PushSettingRequest request) {
+        applicationInfoService.savePushSetting(id, request);
+    }
+
+    @GetMapping("GetPushSetting/{id}")
+    public PushSettingVo getPushSetting(@PathVariable Integer id) {
+        return applicationInfoService.getPushSetting(id);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/BaseController.java b/src/main/java/com/yunhai/userbase/controller/api/BaseController.java
new file mode 100644
index 0000000..ee159c5
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/BaseController.java
@@ -0,0 +1,142 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.platform.utils.enums.ClientEnum;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.enums.*;
+import com.yunhai.userbase.utils.*;
+import com.yunhai.platform.utils.exception.DException;
+import org.springframework.web.multipart.MultipartFile;
+import lombok.var;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.servlet.view.RedirectView;
+
+import java.util.*;
+import java.util.function.Supplier;
+
+@RestController
+@RequestMapping(value = Config.API_PATH +"/base/")
+public class BaseController {
+
+
+    @Autowired
+    private RedisUtil redisUtil;
+
+    /**
+     * 一般hashMap初始化大小
+     */
+    public static final int initialCapacity = 6;
+
+    /**
+     * 通用上传允许的子目录（与 MyWebAppConfigurer.addResourceHandlers 的资源映射一一对应）。<br>
+     * 注：html 因 FileUtil 的危险后缀黑名单被禁止通过此接口上传，故未列入，避免存储可被浏览器执行的 HTML 引发 XSS。
+     */
+    private static final Set<String> ALLOWED_UPLOAD_TYPES = new HashSet<>(Arrays.asList("image", "file", "icon", "word"));
+
+    @GetMapping("GetUserInfo")
+    public Object getUserInfo(BoaUser authUserWithDept){
+        return authUserWithDept;
+    }
+
+    //返回系统枚举2
+    @GetMapping("GetSysDict")
+    public Map getSysDict(BoaUser authUserWithDept){
+        Map<String, List> resultMap = new HashMap<>(7);
+        resultMap.put("grouptype", IEnum.toSimpleMapList(GroupTypeEnum.class, "k", "v"));
+        resultMap.put("gender", IEnum.toSimpleMapList(GenderEnum.class, "k", "v"));
+        resultMap.put("client", IEnum.toSimpleMapList(ClientEnum.class, "k", "v"));
+        resultMap.put("integ", IEnum.toSimpleMapList(IntegEnum.class, "k", "v"));
+        resultMap.put("status", IEnum.toSimpleMapList(StatusEnum.class, "k", "v"));
+        resultMap.put("sysrole", IEnum.toSimpleMapList(SysRoleEnum.class, "k", "v"));
+        resultMap.put("mode", IEnum.toSimpleMapList(SysModeEnum.class, "k", "v"));
+        return resultMap;
+    }
+
+    /**
+     * 手动管理 Redis Hash 缓存的示例（@Cacheable 注解无法满足的场景）。<br>
+     * 适用场景：需要把一个对象的多个字段按 Hash 结构存储，<br>
+     * 可单独读写/更新某个字段，而不像 @Cacheable 那样把整个对象序列化成一个大 value。<br>
+     * 访问路径：GET {Config.API_PATH}/base/ManualHashCacheDemo。<br>
+     * 注：手动缓存依赖 Redis；Redis 不可用时 RedisUtil 已内部捕获异常，操作失败但不影响接口本身。
+     *
+     * @return 本次演示各步骤的结果快照
+     */
+    @GetMapping("ManualHashCacheDemo")
+    public Map<String, Object> manualHashCacheDemo() {
+        Map<String, Object> result = new HashMap<>(8);
+        String hashKey = "demo:user:1001";
+        // 1) 写入整张 hash（带 TTL）：适合一次性缓存一个对象的多个属性
+        Map<String, Object> profile = new HashMap<>(4);
+        profile.put("name", "yunhai");
+        profile.put("age", 18);
+        profile.put("role", "admin");
+        redisUtil.hmset(hashKey, profile, 300);
+        // 2) 只更新其中一个字段，无需整体覆盖
+        redisUtil.hset(hashKey, "role", "superadmin");
+        // 3) 读取单个字段
+        result.put("roleAfterUpdate", redisUtil.hget(hashKey, "role"));
+        // 4) 读取整张 hash
+        result.put("wholeHash", redisUtil.hmget(hashKey));
+        // 5) 判断字段是否存在
+        result.put("hasAgeField", redisUtil.hHasKey(hashKey, "age"));
+        // 6) Cache-Aside（复用下方私有方法）：字段不存在时回源并写回 Hash
+        Object nickname = getHashFieldWithFallback(hashKey, "nickname", () -> "yunhai-nick");
+        result.put("nickname", nickname);
+        // 7) 删除某个字段
+        redisUtil.hdel(hashKey, "age");
+        result.put("afterDelAge", redisUtil.hmget(hashKey));
+        return result;
+    }
+
+
+
+    @GetMapping("RedirectTo/{id}")
+    public RedirectView RedirectTo(BoaUser authUserWithDept, @PathVariable(name = "id") String id) {
+        String url= OtherUtil.hexToString(id);
+        return new RedirectView(url,true);
+    }
+
+    /**
+     * 通用文件上传接口（一个接口覆盖所有类型，无需按类型拆分）。<br>
+     * type 决定存储子目录，与 MyWebAppConfigurer.addResourceHandlers 的 /upload/{type}/** 映射一一对应，<br>
+     * 上传成功后可直接用返回的 URL 访问，无需再改资源映射配置。<br>
+     * 访问路径：POST {Config.API_PATH}/base/UploadFile（multipart/form-data）。<br>
+     * 支持 type：image / file / icon / word（html 被 FileUtil 黑名单禁止上传）。<br>
+     *
+     * @param file 上传文件（必填，单文件上限 50MB，见 application.yml 的 multipart 配置）
+     * @param type 存储子目录类型，默认 image
+     * @return 文件对外可访问的 Web URL
+     */
+    @PostMapping("UploadFile")
+    public String uploadFile(@RequestParam("file") MultipartFile file,
+                             @RequestParam(value = "type", defaultValue = "image") String type) {
+        if (!ALLOWED_UPLOAD_TYPES.contains(type)) {
+            throw new DException("不支持的上传类型: " + type + "，可选: image/file/icon/word");
+        }
+        // FileUtil.upload 内部已处理空文件校验、危险后缀黑名单、目录创建与访问 URL 拼接
+        return FileUtil.upload(file, type);
+    }
+
+    /**
+     * 私有方法（可复用）：演示 Hash 结构的 Cache-Aside（缓存旁路）模式。<br>
+     * 先从 Redis Hash 读字段；读不到则回源（此处用 fallback 模拟数据库查询），再把结果写回 Hash。<br>
+     *
+     * @param hashKey  hash 键
+     * @param field    字段名
+     * @param fallback 回源加载器（真实场景替换为查数据库/远程调用）
+     * @return 字段值
+     */
+    private Object getHashFieldWithFallback(String hashKey, String field, Supplier<Object> fallback) {
+        if (redisUtil.hHasKey(hashKey, field)) {
+            return redisUtil.hget(hashKey, field);
+        }
+        Object value = fallback.get();
+        if (value != null) {
+            redisUtil.hset(hashKey, field, value);
+        }
+        return value;
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/GroupAuthzController.java b/src/main/java/com/yunhai/userbase/controller/api/GroupAuthzController.java
new file mode 100644
index 0000000..3297b28
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/GroupAuthzController.java
@@ -0,0 +1,179 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.groupauthz.GroupAppAssignRequest;
+import com.yunhai.userbase.model.groupauthz.GroupAppVo;
+import com.yunhai.userbase.model.groupauthz.GroupAuthzAppVo;
+import com.yunhai.userbase.model.groupauthz.GroupAuthzCategoryVo;
+import com.yunhai.userbase.model.groupauthz.GroupModuleAuthzItem;
+import com.yunhai.userbase.model.groupauthz.GroupModulePermRequest;
+import com.yunhai.userbase.model.groupauthz.SchoolAppAuthzRequest;
+import com.yunhai.userbase.model.groupauthz.UserGroupNodeVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionCategoryVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionUserVo;
+import com.yunhai.userbase.model.groupauthz.UserRoleVo;
+import com.yunhai.userbase.service.IGroupAuthzService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import javax.validation.Valid;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组应用权限管理（应用开通 + 组授权 + 权限判定）。<br>
+ * 左侧组树复用 /sysgroup/GetTree；本控制器提供右侧数据加载与保存接口。<br>
+ */
+@RestController
+@RequestMapping(value = Config.API_PATH + "/groupauthz/")
+public class GroupAuthzController {
+
+    @Autowired
+    private IGroupAuthzService groupAuthzService;
+
+    /**
+     * 功能1回显：点击左侧组后，返回系统全量应用列表，已开通的 checked=true。
+     */
+    @GetMapping("/GroupAppList")
+    public List<GroupAppVo> groupAppList(@RequestParam Integer groupId) {
+        return groupAuthzService.listGroupApps(groupId);
+    }
+
+    /**
+     * 功能1保存：全量覆盖式更新该组的应用开通记录。
+     */
+    @OperationLog("保存组应用开通")
+    @PostMapping("AssignApps")
+    public void assignApps(@RequestBody @Validated GroupAppAssignRequest request) {
+        groupAuthzService.assignAppsToGroup(request);
+    }
+
+    /**
+     * 功能2数据加载：返回该组已开通的应用及其模块权限树（含勾选与子组继承回显）。
+     */
+    @GetMapping("/GroupModuleTree")
+    public List<GroupAuthzAppVo> groupModuleTree(@RequestParam Integer groupId) {
+        return groupAuthzService.findGroupAppsWithModules(groupId);
+    }
+
+    /**
+     * 功能2数据加载（按应用分类分组）：供组授权页面按分类面板展示，<br>
+     * 返回全部分类及该组已开通的应用模块权限树。
+     */
+    @GetMapping("/GroupModuleTreeByCategory")
+    public List<GroupAuthzCategoryVo> groupModuleTreeByCategory(@RequestParam Integer groupId) {
+        return groupAuthzService.findGroupAppsWithModulesByCategory(groupId);
+    }
+
+    /**
+     * 功能2保存：全量覆盖式更新该组的模块权限（含子组继承开关）。
+     */
+    @OperationLog("保存组模块权限")
+    @PostMapping("SaveModulePerms")
+    public void saveModulePerms(@RequestBody @Validated GroupModulePermRequest request) {
+        groupAuthzService.saveModulePermissions(request);
+    }
+
+    /**
+     * 权限判定：判断用户对某模块是否有权限（供登录/拦截器/联调验证使用）。
+     */
+    @GetMapping("/HasModulePerm")
+    public boolean hasModulePerm(@RequestParam Integer userId, @RequestParam Integer moduleId) {
+        return groupAuthzService.hasModulePermission(userId, moduleId);
+    }
+
+    /**
+     * 权限一览：根据组ID获取该组下的直接用户列表（不含子组，不分页）。
+     */
+    @GetMapping("/GroupUsers")
+    public List<UserPermissionUserVo> groupUsers(@RequestParam Integer groupId) {
+        return groupAuthzService.findGroupUsers(groupId);
+    }
+
+    /**
+     * 权限一览：全局搜索用户（按账号/姓名/身份证模糊、手机号精确匹配），不分页。<br>
+     * 返回用户及其主归属部门/组织路径，供左侧用户搜索形态展示。
+     */
+    @GetMapping("/SearchUsers")
+    public List<UserPermissionUserVo> searchUsers(@RequestParam String keyword) {
+        return groupAuthzService.searchUsers(keyword);
+    }
+
+    /**
+     * 权限一览：根据用户ID聚合该用户的全部已授权应用模块树。<br>
+     * 只返回有授权模块的应用，并按应用类型分组；无授权的应用类型和应用不显示。<br>
+     * 角色授权并集：结果 = 组授权模块 ∪ 启用角色授权模块（角色模块不要求组先开通应用）。
+     */
+    @GetMapping("/UserPermissionTree")
+    public List<UserPermissionCategoryVo> userPermissionTree(@RequestParam Integer userId,
+                                                              @RequestParam(required = false) Integer groupId) {
+        return groupAuthzService.findUserPermissionTree(groupId, userId);
+    }
+
+    /**
+     * 权限一览：查询用户所属的业务角色列表（中间下方「所属角色」区域展示用）。<br>
+     * 返回该用户绑定的全部角色（含禁用角色，disabled 字段标记），普通角色回填所属应用名称。
+     */
+    @GetMapping("/UserRoles")
+    public List<UserRoleVo> userRoles(@RequestParam Integer userId) {
+        return groupAuthzService.findUserRoles(userId);
+    }
+
+    /**
+     * 权限一览：查询用户所属部门树（左侧上方「所属部门」区域展示用）。<br>
+     * 树仅由「用户直接归属的组 + 其全部祖先组」构成（如：云平台-学校中学-语文组）。
+     */
+    @GetMapping("/UserGroupTree")
+    public List<UserGroupNodeVo> userGroupTree(@RequestParam Integer userId) {
+        return groupAuthzService.findUserGroupTree(userId);
+    }
+
+    // ===================== 新增：树节点式增量授权（左侧树 + 右侧 appAuthzList 勾选交互） =====================
+
+    /**
+     * 功能3回显：点击左侧树节点后，返回该组「已开通的应用ID列表」，供右侧 AppSettings.appAuthzList 回显勾选状态。<br>
+     * <b>交互</b>：左树节点 → 右 appAuthzList（全量应用）→ 本接口拿到已选 id → 前端把对应多选框置为勾选。<br>
+     * <b>实现</b>：应用开通不继承，直接查 sys_group_app_rel(group_id=nodeId) 返回 app_id 列表（详见 service.findAuthorizedAppIds）。<br>
+     * 与 GroupAppList（返回全量应用+checked）互为补充：本接口更轻量，只给 id 集合。
+     */
+    @GetMapping("/GetSchoolAppId")
+    public List<Integer> getSchoolAppId(@RequestParam Integer nodeId) {
+        return groupAuthzService.findAuthorizedAppIds(nodeId);
+    }
+
+    /**
+     * 功能3保存（应用维）：点击应用多选框触发，对该组做应用开通/取消。<br>
+     * <b>入参（请求体，JSON）</b>：{@link SchoolAppAuthzRequest} —— schid=组ID(nodeId)；appid=单个应用ID（一次只传一个，逐次点击）；mode=操作模式。<br>
+     * <b>mode 语义（SysModeEnum）</b>：0=追加(开通应用) / 2=删除(取消开通)；1=覆盖 不适用，会被拒绝。<br>
+     * <b>实现</b>：应用开通不继承，仅操作本组；删除时同步清理该组在该应用下模块的权限残留（详见 service.setSchoolApps）。<br>
+     * <b>注意</b>：appid 为单个 Integer，后端不再做多值/逗号解析；每次点击提交一次请求。
+     */
+    @OperationLog("设置组应用开通")
+    @PostMapping("SetSchoolApp")
+    public void setSchoolApp(@RequestBody @Valid SchoolAppAuthzRequest request) {
+        groupAuthzService.setSchoolApps(request);
+    }
+
+    /**
+     * 功能4保存（模块维）：前端「组授权」面板逐条勾选/取消时提交，对 (组,应用,模块) 做增量授权/取消。<br>
+     * <b>入参</b>：请求体为数组，元素见 {@link GroupModuleAuthzItem}：{groupId, appId, moduleId, mode, isAll}。<br>
+     * <b>mode</b>：0=追加 / 2=删除（1=覆盖不适用）。<br>
+     * <b>isAll</b>：是否对子组继承，映射 sys_group_module_perm.inherit_flag（1=子孙组自动继承 / 0=仅本组）。<br>
+     * <b>moduleId=0</b>：表示「该应用下全部模块」，后端展开为应用下每个真实模块各写/删一条。<br>
+     * <b>实现</b>：逐条处理、顺序即执行顺序；追加前要求该组已开通该应用；越权写别的应用模块会被拒绝（详见 service.setGroupModulePerms）。<br>
+     * 与现有 SaveModulePerms（全量覆盖）共存：本接口是单条增量，二者操作同一张表、互不冲突。
+     */
+    @OperationLog("设置组模块权限")
+    @PostMapping("SetGroupModule")
+    public void setGroupModule(@RequestBody @Valid List<GroupModuleAuthzItem> items) {
+        groupAuthzService.setGroupModulePerms(items);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/IdentityController.java b/src/main/java/com/yunhai/userbase/controller/api/IdentityController.java
new file mode 100644
index 0000000..4c3c669
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/IdentityController.java
@@ -0,0 +1,62 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.identity.IdentityCurrentVo;
+import com.yunhai.userbase.model.identity.IdentityOptionVo;
+import com.yunhai.userbase.model.identity.IdentitySwitchRequest;
+import com.yunhai.userbase.service.impl.IdentityService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 用户身份（平台身份角色 × 学校）管理接口。<br><br>
+ * 走 CAS 会话路线（{@code /{platform}/identity/}），当前用户从 CAS 会话注入的
+ * {@link BoaUser#getId()} 取，不接受外部传入 userId（防越权）。<br>
+ * 三个端点对应「切换身份」业务：<br>
+ * ① {@code GET current}  当前激活身份（无切换记录则兜底主身份）；<br>
+ * ② {@code GET available} 全部可选身份清单；<br>
+ * ③ {@code POST switch}  切换到指定 (roleId, schoolId)，服务端校验属主后写入当前激活状态。
+ *
+ * @author chenx
+ * @date 2026/8/18
+ */
+@RestController
+@RequestMapping(Config.API_PATH + "/identity/")
+public class IdentityController {
+
+    @Autowired
+    private IdentityService identityService;
+
+    /**
+     * 当前激活身份。
+     */
+    @GetMapping("current")
+    public IdentityCurrentVo current(BoaUser authUserWithDept) {
+        return identityService.getCurrent(authUserWithDept.getId());
+    }
+
+    /**
+     * 全部可选身份（正常态），供「切换身份」页渲染。
+     */
+    @GetMapping("available")
+    public List<IdentityOptionVo> available(BoaUser authUserWithDept) {
+        return identityService.listAvailable(authUserWithDept.getId());
+    }
+
+    /**
+     * 切换身份：校验属主后在 sys_user_current_role 写当前激活状态。
+     */
+    @PostMapping("switch")
+    public IdentityCurrentVo switchIdentity(BoaUser authUserWithDept,
+            @RequestBody @Validated IdentitySwitchRequest request) {
+        return identityService.switchIdentity(authUserWithDept.getId(), request);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/PushSubscriptionController.java b/src/main/java/com/yunhai/userbase/controller/api/PushSubscriptionController.java
new file mode 100644
index 0000000..b16850d
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/PushSubscriptionController.java
@@ -0,0 +1,97 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.push.PushRecordListVo;
+import com.yunhai.userbase.model.push.PushRecordQuery;
+import com.yunhai.userbase.model.push.PushTestRequest;
+import com.yunhai.userbase.service.push.PushDispatcher;
+import com.yunhai.userbase.service.push.PushRecordService;
+import com.yunhai.userbase.utils.PageUtils;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.InputStreamResource;
+import org.springframework.data.domain.Sort;
+import org.springframework.data.web.SortDefault;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 推送订阅控制器：测试推送 + 推送日志记录 / 重试。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@RestController
+@Slf4j
+@RequestMapping(value = Config.API_PATH + "/push/")
+public class PushSubscriptionController {
+
+    @Autowired
+    private PushDispatcher pushDispatcher;
+    @Autowired
+    private PushRecordService pushRecordService;
+
+    /** 测试推送：手动触发一次推送（投递 MQ），并返回请求预览（URL/头/体，密钥不外露）。 */
+    @PostMapping("Test")
+    public Map<String, Object> test(@RequestBody PushTestRequest request) {
+        pushDispatcher.dispatchManual(request.getAppId(), request.getInterfacePath(), request.getTargetIds());
+        Map<String, Object> preview = pushDispatcher.previewManual(
+                request.getAppId(), request.getInterfacePath(), request.getTargetIds());
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("sent", true);
+        result.put("message", "已投递推送队列，可在「推送日志」查看实际响应与耗时");
+        result.put("preview", preview);
+        return result;
+    }
+
+    /** 推送日志列表（不含 payload，避免全量推送数据量过大；payload 经 Download 接口单独获取）。 */
+    @GetMapping("RecordList")
+    public BasePageResult<PushRecordListVo> recordList(PushRecordQuery query, BasePageQuery pageQuery,
+                                                       @SortDefault(sort = "createdAt", direction = Sort.Direction.DESC) Sort sort) {
+        return PageUtils.toResult(pushRecordService.query(query, PageUtils.toPageable(pageQuery, sort)));
+    }
+
+    /** 手动重试一条失败的推送记录。 */
+    @PostMapping("Retry/{id}")
+    public void retry(@PathVariable Long id) {
+        pushRecordService.retry(id);
+    }
+
+    /**
+     * 下载某条推送记录的请求体原文（payload 文本文件）。<br>
+     * 采用与项目 DownloadFileUtil 一致的 octet-stream + attachment 写法，确保浏览器稳定触发下载。<br>
+     * 若该记录未记录 payload，返回一段说明文本文件而非 404，便于排查。
+     */
+    @GetMapping("/Download/{id}")
+    public ResponseEntity<InputStreamResource> download(@PathVariable Long id) {
+        String data = pushRecordService.getPayload(id);
+        if (data == null) {
+            data = "该条推送记录未记录请求体（payload 为空），无法下载原始内容。";
+        }
+        try {
+            ByteArrayInputStream bis = new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8));
+            HttpHeaders headers = new HttpHeaders();
+            headers.add("Cache-Control", "no-cache, no-store, must-revalidate");
+            headers.add(HttpHeaders.CONTENT_DISPOSITION,
+                    "attachment; filename=" + new String(("payload-" + id + ".txt").getBytes("gbk"), "iso8859-1"));
+            headers.add("Pragma", "no-cache");
+            headers.add("Expires", "0");
+            return ResponseEntity.ok().headers(headers)
+                    .contentType(MediaType.parseMediaType("application/octet-stream"))
+                    .body(new InputStreamResource(bis));
+        } catch (Exception e) {
+            log.error("推送日志请求体下载失败, id={}", id, e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/SysGroupController.java b/src/main/java/com/yunhai/userbase/controller/api/SysGroupController.java
new file mode 100644
index 0000000..82fbeed
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/SysGroupController.java
@@ -0,0 +1,102 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.sysgroup.SysGroupBatchRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupMoveRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupQuery;
+import com.yunhai.userbase.model.sysgroup.SysGroupRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupSortRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupVo;
+import com.yunhai.userbase.service.ISysGroupService;
+import io.swagger.v3.oas.annotations.Operation;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组管理（组织架构树）
+ */
+@RestController
+@RequestMapping(value = Config.API_PATH + "/sysgroup/")
+public class SysGroupController {
+
+    @Autowired
+    private ISysGroupService sysGroupService;
+
+    @OperationLog("新增组")
+    @Operation(operationId = "sysGroupAdd")
+    @PostMapping("Add")
+    public void add(@RequestBody @Validated(ValidationGroups.Create.class) SysGroupRequest request) {
+        sysGroupService.add(request);
+    }
+
+    @OperationLog("编辑组")
+    @Operation(operationId = "sysGroupEdit")
+    @PostMapping("Edit/{id}")
+    public void edit(@PathVariable Integer id, @RequestBody @Validated(ValidationGroups.Update.class) SysGroupRequest request) {
+        sysGroupService.edit(id, request);
+    }
+
+    @OperationLog("删除组")
+    @Operation(operationId = "sysGroupRemove")
+    @PostMapping("Delete/{id}")
+    public void delete(@PathVariable Integer id) {
+        sysGroupService.delete(id);
+    }
+
+    @Operation(operationId = "sysGroupList")
+    @GetMapping("/List")
+    public List<SysGroupVo> list(SysGroupQuery query) {
+        return sysGroupService.list(query);
+    }
+
+    /**
+     * 获取组织架构树；表为空时自动创建根节点「教育云中心」(pid=0)。
+     */
+    @GetMapping("GetTree")
+    public List<SysGroupVo> getTree() {
+        return sysGroupService.getTree();
+    }
+
+    /**
+     * 获取「学校组」剪枝树：末端叶子一定是学校组；学校组下的组不显示；<br>
+     * 子树中无学校组的分支整体剪掉；根节点始终保留。
+     */
+    @GetMapping("GetSchoolTree")
+    public List<SysGroupVo> getSchoolTree() {
+        return sysGroupService.getSchoolTree();
+    }
+
+    /**
+     * 批量新增子组：请求体 { pid, type, items:[{name},...] }（JSON）。
+     */
+    @OperationLog("批量新增子组")
+    @PostMapping("BatchAdd")
+    public void batchAdd(@RequestBody @Validated SysGroupBatchRequest request) {
+        sysGroupService.batchAdd(request);
+    }
+
+    /**
+     * 子组排序：传入 pid 与有序 ids（必须是 pid 的直接子节点），按传入顺序落库。
+     */
+    @OperationLog("子组排序")
+    @PostMapping("SortChildren")
+    public void sortChildren(@Validated SysGroupSortRequest request) {
+        sysGroupService.sortChildren(request);
+    }
+
+    /**
+     * 移动组：将 moveId 移动到 pid 下（不支持移动到自身或自身后代）。
+     */
+    @OperationLog("移动组")
+    @PostMapping("Move")
+    public void move(@Validated SysGroupMoveRequest request) {
+        sysGroupService.move(request);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/SysOapiLogController.java b/src/main/java/com/yunhai/userbase/controller/api/SysOapiLogController.java
new file mode 100644
index 0000000..46ffd0f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/SysOapiLogController.java
@@ -0,0 +1,77 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oapilog.SysOapiLogListVo;
+import com.yunhai.userbase.model.oapilog.SysOapiLogQuery;
+import com.yunhai.userbase.service.ISysOapiLogService;
+import io.swagger.v3.oas.annotations.Operation;
+import lombok.extern.slf4j.Slf4j;
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.InputStreamResource;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 开放接口日志查询与下载接口。<br>
+ * 本控制器位于 {@code controller.api} 包，不会被 OapiLogAspect（切 oapi 包）拦截。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Slf4j
+@RestController
+@RequestMapping(value = Config.API_PATH + "/oapilog/")
+public class SysOapiLogController {
+
+    @Autowired
+    private ISysOapiLogService sysOapiLogService;
+
+    /**
+     * 分页查询开放接口日志列表（不含响应结果）。
+     */
+    @Operation(summary = "开放接口日志分页查询", operationId = "oapiLogList")
+    @GetMapping("/List")
+    public BasePageResult<SysOapiLogListVo> list(SysOapiLogQuery query, BasePageQuery pageQuery) {
+        return sysOapiLogService.pageQuery(query, pageQuery);
+    }
+
+    /**
+     * 下载某条日志的响应结果（GZIP 解压后原文，文本文件）。<br>
+     * 与 {@code SysOperationLogController.Download} 一致的 octet-stream + attachment 写法。<br>
+     * 若该日志未记录响应数据，返回一段说明文本文件而非 404，便于排查。
+     */
+    @Operation(summary = "下载开放接口日志响应原文", operationId = "oapiLogDownload")
+    @GetMapping("/Download/{id}")
+    public ResponseEntity<InputStreamResource> download(@PathVariable Long id) {
+        String data = sysOapiLogService.getResponseData(id);
+        if (data == null) {
+            data = "该条日志未记录响应数据（saveResponse=false、或接口响应为空、或响应序列化失败），无法下载原始内容。";
+        }
+        try {
+            ByteArrayInputStream bis = new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8));
+            HttpHeaders headers = new HttpHeaders();
+            headers.add("Cache-Control", "no-cache, no-store, must-revalidate");
+            headers.add(HttpHeaders.CONTENT_DISPOSITION,
+                    "attachment; filename=" + new String(("response-" + id + ".txt").getBytes("gbk"), "iso8859-1"));
+            headers.add("Pragma", "no-cache");
+            headers.add("Expires", "0");
+            return ResponseEntity.ok().headers(headers)
+                    .contentType(MediaType.parseMediaType("application/octet-stream"))
+                    .body(new InputStreamResource(bis));
+        } catch (Exception e) {
+            log.error("开放接口日志响应结果下载失败, id={}", id, e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/SysOperationLogController.java b/src/main/java/com/yunhai/userbase/controller/api/SysOperationLogController.java
new file mode 100644
index 0000000..e980c23
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/SysOperationLogController.java
@@ -0,0 +1,77 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oplog.SysOperationLogListVo;
+import com.yunhai.userbase.model.oplog.SysOperationLogQuery;
+import com.yunhai.userbase.service.ISysOperationLogService;
+import io.swagger.v3.oas.annotations.Operation;
+import lombok.extern.slf4j.Slf4j;
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.InputStreamResource;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 操作日志查询与下载接口。<br>
+ * 本控制器自身不标注 @OperationLog，避免记录日志查看行为。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Slf4j
+@RestController
+@RequestMapping(value = Config.API_PATH + "/oplog/")
+public class SysOperationLogController {
+
+    @Autowired
+    private ISysOperationLogService sysOperationLogService;
+
+    /**
+     * 分页查询操作日志列表（不含响应结果）。
+     */
+    @Operation(summary = "操作日志分页查询", operationId = "operationLogList")
+    @GetMapping("/List")
+    public BasePageResult<SysOperationLogListVo> list(SysOperationLogQuery query, BasePageQuery pageQuery) {
+        return sysOperationLogService.pageQuery(query, pageQuery);
+    }
+
+    /**
+     * 下载某条日志的响应结果（GZIP 解压后原文， 文本文件）。<br>
+     * 采用与项目 DownloadFileUtil 一致的 octet-stream + attachment 写法，确保浏览器稳定触发下载。<br>
+     * 若该日志未记录响应数据，返回一段说明文本文件而非 404，便于排查。
+     */
+    @Operation(summary = "下载日志响应原文", operationId = "operationLogDownload")
+    @GetMapping("/Download/{id}")
+    public ResponseEntity<InputStreamResource> download(@PathVariable Long id) {
+        String data = sysOperationLogService.getResponseData(id);
+        if (data == null) {
+            data = "该条日志未记录响应数据（saveResponse=false、或接口响应为空、或响应序列化失败），无法下载原始内容。";
+        }
+        try {
+            ByteArrayInputStream bis = new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8));
+            HttpHeaders headers = new HttpHeaders();
+            headers.add("Cache-Control", "no-cache, no-store, must-revalidate");
+            headers.add(HttpHeaders.CONTENT_DISPOSITION,
+                    "attachment; filename=" + new String(("response-" + id + ".txt").getBytes("gbk"), "iso8859-1"));
+            headers.add("Pragma", "no-cache");
+            headers.add("Expires", "0");
+            return ResponseEntity.ok().headers(headers)
+                    .contentType(MediaType.parseMediaType("application/octet-stream"))
+                    .body(new InputStreamResource(bis));
+        } catch (Exception e) {
+            log.error("操作日志响应结果下载失败, id={}", id, e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/api/SysUserController.java b/src/main/java/com/yunhai/userbase/controller/api/SysUserController.java
new file mode 100644
index 0000000..84c23bc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/api/SysUserController.java
@@ -0,0 +1,147 @@
+package com.yunhai.userbase.controller.api;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.userbase.common.annotation.OperationLog;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.sysuser.BatchChangeStatusRequest;
+import com.yunhai.userbase.model.sysuser.BatchDeleteRequest;
+import com.yunhai.userbase.model.sysuser.BatchImportResult;
+import com.yunhai.userbase.model.sysuser.ChangeGroupsRequest;
+import com.yunhai.userbase.model.sysuser.ChangeSortNoRequest;
+import com.yunhai.userbase.model.sysuser.SysUserQuery;
+import com.yunhai.userbase.model.sysuser.SysUserRequest;
+import com.yunhai.userbase.model.sysuser.SysUserVo;
+import com.yunhai.userbase.service.ISysUserService;
+import com.yunhai.userbase.utils.PageUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 组用户管理
+ */
+@RestController
+@RequestMapping(value = Config.API_PATH + "/sysuser/")
+public class SysUserController {
+
+    @Autowired
+    private ISysUserService sysUserService;
+
+    @OperationLog("新增用户")
+    @PostMapping("Add")
+    public Integer add(@RequestBody @Validated(ValidationGroups.Create.class) SysUserRequest request) {
+        List<String> data=new ArrayList<>();
+
+        return sysUserService.add(request);
+    }
+
+    @OperationLog("编辑用户")
+    @PostMapping("Edit/{id}")
+    public void edit(@PathVariable Integer id, @RequestBody @Validated(ValidationGroups.Update.class) SysUserRequest request) {
+        sysUserService.edit(id, request);
+    }
+
+    /**
+     * 将用户从指定组中移除；若该用户无其它组关联则级联删除用户。
+     */
+    @OperationLog("从组中删除用户")
+    @PostMapping("DeleteFromGroup/{userId}/{groupId}")
+    public void deleteFromGroup(@PathVariable Integer userId, @PathVariable Integer groupId) {
+        sysUserService.deleteFromGroup(userId, groupId);
+    }
+
+    /**
+     * 批量从指定组中移除用户；无其它组关联者级联删除用户。
+     */
+    @OperationLog("批量从组中删除用户")
+    @PostMapping("BatchDelete")
+    public void batchDelete(@RequestBody @Validated BatchDeleteRequest request) {
+        sysUserService.batchDeleteFromGroup(request.getUserIds(), request.getGroupId());
+    }
+
+    /** 禁用用户（disabled=true） */
+    @OperationLog("禁用用户")
+    @PostMapping("Disable/{id}")
+    public void disable(@PathVariable Integer id) {
+        sysUserService.changeStatus(id, true);
+    }
+
+    /** 启用用户（disabled=false） */
+    @OperationLog("启用用户")
+    @PostMapping("Enable/{id}")
+    public void enable(@PathVariable Integer id) {
+        sysUserService.changeStatus(id, false);
+    }
+
+    /** 批量设置用户状态 */
+    @OperationLog("批量设置用户状态")
+    @PostMapping("BatchChangeStatus")
+    public void batchChangeStatus(@RequestBody @Validated BatchChangeStatusRequest request) {
+        sysUserService.batchChangeStatus(request.getUserIds(), request.getDisabled());
+    }
+
+    @GetMapping("/List")
+    public BasePageResult<SysUserVo> list(SysUserQuery query, BasePageQuery pageQuery) {
+        // 排序字段在关联表，无法走 Pageable.sort，统一由 Service.Specification 控制
+        // （根节点按 id 升序，具体组按组内 sort_no 升序）。此处不传 Sort，避免覆盖 Spec 的 orderBy。
+        return PageUtils.toResult(sysUserService.list(query, PageUtils.toPageable(pageQuery, null)));
+    }
+
+    /** 调整用户在某组内的排序号（sort_no）：1~999，可空表示清除 */
+    @OperationLog("设置用户组内排序号")
+    @PostMapping("ChangeSortNo/{userId}")
+    public void changeSortNo(@PathVariable Integer userId,
+                             @RequestBody @Validated ChangeSortNoRequest request) {
+        sysUserService.changeSortNo(userId, request.getGroupId(), request.getSortNo());
+    }
+
+    @OperationLog("调整组")
+    @PostMapping("ChangeGroups")
+    public void changeGroups(@RequestBody @Validated ChangeGroupsRequest request) {
+        sysUserService.changeGroups(request.getUserIds(), request.getGroupIds());
+    }
+
+    @GetMapping("Groups/{userId}")
+    public List<Integer> getUserGroups(@PathVariable Integer userId) {
+        return sysUserService.findGroupIdsByUserId(userId);
+    }
+
+    @OperationLog("批量导入用户")
+    @PostMapping("BatchImport")
+    public BatchImportResult batchImport(@RequestParam("file") MultipartFile file) {
+        return sysUserService.batchImport(file);
+    }
+
+    /**
+     * 下载用户批量导入模板（真实 .xlsx）：平铺当前组及子孙组，仅填充组名(路径)与组id；其余列留空供填写。
+     */
+    @GetMapping("DownloadTemplate")
+    public void downloadTemplate(@RequestParam(value = "groupId", required = false) Integer groupId,
+                                 HttpServletResponse response) throws IOException {
+        sysUserService.downloadImportTemplate(groupId, response);
+    }
+
+    /**
+     * 导出组下所有用户（含子组）为 Excel；与导入模板同构，末尾追加用户id列。
+     * 前端直接跳转此地址触发浏览器下载。
+     */
+    @GetMapping("Export")
+    public void export(@RequestParam(value = "groupId", required = false) Integer groupId,
+                       @RequestParam(value = "withSub", defaultValue = "1") Integer withSub,
+                       @RequestParam(value = "name", required = false) String name,
+                       HttpServletResponse response) throws IOException {
+        sysUserService.exportUsers(groupId, withSub, name, response);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/oapi/AppController.java b/src/main/java/com/yunhai/userbase/controller/oapi/AppController.java
new file mode 100644
index 0000000..efc3ebb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/oapi/AppController.java
@@ -0,0 +1,74 @@
+package com.yunhai.userbase.controller.oapi;
+
+import com.yunhai.platform.utils.enums.ClientEnum;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.platform.utils.model.BoaAppType;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.application.ApplicationInfoVo;
+import com.yunhai.userbase.service.IAppCategoryService;
+import com.yunhai.userbase.service.IApplicationInfoService;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 应用域开放接口：供其他业务服务经 yh-app-auth 签名调用（{@code /oapi/app/...}）。<br>
+ * 接口本身不做验签——签名由 {@code OpenApiAuthEnforceConfiguration} 在过滤器层强制要求
+ * （URL pattern {@code /oapi/*} 已覆盖本控制器），未带 {@code X-App-Key/X-Timestamp/X-Signature} 的请求直接 401。
+ */
+@RestController
+@RequestMapping(Config.OPEN_API_PATH + "app/")
+public class AppController {
+
+    @Autowired
+    private IAppCategoryService appCategoryService;
+
+    @Autowired
+    private IApplicationInfoService applicationInfoService;
+
+    /**
+     * 按主键 ID 查询应用信息（带缓存）。<br>
+     * 与客户端契约 {@code GET /oapi/app/{appId}} 对应；查不到返回 null（HTTP 200 + data:null 信封）。<br>
+     * 返回 {@link ApplicationInfoVo} 并清空 appSecret，与 list 接口一致不透出签名密钥。
+     *
+     * @param appId 应用主键 ID（必填）
+     * @return 应用信息视图；不存在时返回 null
+     */
+    @GetMapping("{appId}")
+    public ApplicationInfoVo byId(@PathVariable Integer appId) {
+        ApplicationInfo info = applicationInfoService.getById(appId);
+        if (info == null) {
+            return null;
+        }
+        ApplicationInfoVo vo = new ApplicationInfoVo();
+        BeanUtils.copyProperties(info, vo);
+        // 不透出签名密钥（与 list 契约一致）
+        vo.setAppSecret(null);
+        return vo;
+    }
+
+    /**
+     * 查询用户在指定客户端类型下有权访问的应用列表（按应用类型分组）。<br>
+     * 权限过滤复用 {@code IGroupAuthzService.findUserAuthorizedAppIds}（组开通 ∪ 启用角色模块所属应用），
+     * 超级管理员返回全部；不透出 appSecret。<br>
+     * clientType 传枚举 key（2 的幂值，如 1=PC 2=移动App 4=系统模块…）；非法/缺失按不限制端处理。
+     *
+     * @param userId     用户ID（必填）
+     * @param clientType 客户端类型 key（可选）
+     * @return 应用类型分组列表；无权限时各类型 apps 为空数组
+     */
+    @GetMapping("list")
+    public List<BoaAppType> list(@RequestParam("userId") Integer userId,
+            @RequestParam(value = "clientType", required = false) Integer clientType) {
+        ClientEnum clientEnum = (clientType == null) ? null
+                : IEnum.getByKey(ClientEnum.class, clientType);
+        return appCategoryService.listBoaAppType(userId, clientEnum);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/oapi/GroupController.java b/src/main/java/com/yunhai/userbase/controller/oapi/GroupController.java
new file mode 100644
index 0000000..62108c9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/oapi/GroupController.java
@@ -0,0 +1,116 @@
+package com.yunhai.userbase.controller.oapi;
+
+import com.yunhai.platform.utils.model.BoaGroup;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.model.sysgroup.SysGroupBatchRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupMoveRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupRequest;
+import com.yunhai.userbase.service.ISysGroupService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 组织架构开放接口：供其他业务服务经 yh-app-auth 签名调用（{@code /oapi/group/...}）。<br>
+ * <br>
+ * 路径复用 {@link Config#OPEN_API_PATH} 统一前缀，与基础平台 {@code DefaultUserCenterClient}
+ * 硬编码的契约严格一致：
+ * {@code GET /oapi/group/tree}、{@code /byId?groupId=&withSub=}、{@code /list?ids=&withSub=}。<br>
+ * 接口本身不做验签——签名由 {@code OpenApiAuthEnforceConfiguration} 在过滤器层强制要求，
+ * 未带 {@code X-App-Key/X-Timestamp/X-Signature} 的请求直接 401。
+ */
+@RestController
+@RequestMapping(Config.OPEN_API_PATH + "group/")
+public class GroupController {
+
+    @Autowired
+    private ISysGroupService sysGroupService;
+
+    /**
+     * 获取整个平台的组树（从根节点开始，children 递归嵌套全部后代）。
+     */
+    @GetMapping("tree")
+    public BoaGroup tree() {
+        return sysGroupService.getGroups();
+    }
+
+    /**
+     * 获取单个组；withSub=true 时递归挂上全部子孙（整棵子树）。
+     *
+     * @param groupId 组ID（必填）
+     * @param withSub 是否展开子节点，缺省 false
+     * @return 组节点；不存在返回 null
+     */
+    @GetMapping("byId")
+    public BoaGroup byId(@RequestParam("groupId") Integer groupId,
+            @RequestParam(value = "withSub", required = false) Boolean withSub) {
+        return sysGroupService.getGroupById(groupId, withSub);
+    }
+
+    /**
+     * 批量获取组；ids 逗号/空格分隔，按入参顺序返回，不存在的跳过。
+     *
+     * @param ids     组ID列表（逗号/空格分隔）
+     * @param withSub 是否展开子节点，缺省 false
+     * @return 组节点列表（按入参顺序；不存在的跳过）
+     */
+    @GetMapping("list")
+    public List<BoaGroup> list(@RequestParam("ids") String ids,
+            @RequestParam(value = "withSub", required = false) Boolean withSub) {
+        return sysGroupService.getGroupList(ids, withSub);
+    }
+
+    /**
+     * 新增组：返回创建后的组节点（含 id）。<br>
+     * 层级类型约束、根节点保护等复用后台逻辑；鉴权由 OpenApiAuthEnforceConfiguration 在过滤器层强制签名。
+     */
+    @PostMapping("add")
+    public BoaGroup add(@RequestBody @Validated(ValidationGroups.Create.class) SysGroupRequest request) {
+        return sysGroupService.add(request);
+    }
+
+    /**
+     * 编辑组（不含移动，移动请走 group/move 后台接口）：返回更新后的组节点（含 id）。
+     */
+    @PostMapping("edit/{id}")
+    public BoaGroup edit(@PathVariable Integer id,
+            @RequestBody @Validated(ValidationGroups.Update.class) SysGroupRequest request) {
+        return sysGroupService.edit(id, request);
+    }
+
+    /**
+     * 删除组：组下存在子组或用户时拒绝删除（根节点不可删）。<br>
+     * 新增 {@code schoolId} 边界：服务端强制 id 属于该校子树且不等于 schoolId，避免删学校根组/跨校删组。
+     */
+    @PostMapping("delete/{id}/{schoolId}")
+    public void delete(@PathVariable Integer id, @PathVariable Integer schoolId) {
+        sysGroupService.delete(id, schoolId);
+    }
+
+    /**
+     * 批量新增子组：请求体 { pid, type, items:[{name},...] }，返回创建后的组节点列表（均含 id）。
+     */
+    @PostMapping("batchAdd")
+    public List<BoaGroup> batchAdd(@RequestBody @Validated SysGroupBatchRequest request) {
+        return sysGroupService.batchAdd(request);
+    }
+
+    /**
+     * 移动组（学校限定）：仅允许在同一学校（组）子树内移动——moveId、pid 都必须落在 schoolId 子树内。<br>
+     * 语义复用后台 Move（环检测/类型约束/重排），额外叠加学校边界。鉴权由 OpenApiAuthEnforceConfiguration 在过滤器层强制签名。
+     */
+    @PostMapping("move/{schoolId}")
+    public void move(@PathVariable Integer schoolId,
+            @RequestBody @Validated SysGroupMoveRequest request) {
+        sysGroupService.move(request, schoolId);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/oapi/SignKeyInternalController.java b/src/main/java/com/yunhai/userbase/controller/oapi/SignKeyInternalController.java
new file mode 100644
index 0000000..b435789
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/oapi/SignKeyInternalController.java
@@ -0,0 +1,70 @@
+package com.yunhai.userbase.controller.oapi;
+
+import com.yunhai.platform.appauth.AppAuthProperties;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 验签兜底端点：供其他业务服务在「共享 Redis 宕机且本地缓存也未命中」时直连获取某应用的密钥。<br><br>
+ * 直接从 MySQL 读（绕过可能同宕的共享 Redis），是密钥的权威源；写入侧仍由
+ * {@code SignKeyCacheService} 同步到 Redis。返回形状与 BasePlatform 读侧解析契约一致：<br>
+ * {@code {"appKey":"100616","secret":"...","enabled":true}}。<br><br>
+ * 解析优先级：<br>
+ * 1) 本库 application_info（覆盖全部「已颁发」应用的实时密钥）；<br>
+ * 2) 配置式受信应用 {@code yh.app-auth.trusted-apps}（平台自身默认密钥，如 应用中心 100616，
+ *    即便尚未落库也可解析，避免「默认 appKey 未建行」时此处返回 404 导致验签链路失败）；<br>
+ * 两者皆无 → 404。<br><br>
+ * 注意：此端点返回的是应用密钥，必须仅内网可达（由部署网络隔离保障），切勿暴露到公网。
+ */
+@RestController
+@RequestMapping(Config.OPEN_API_PATH + "internal")
+public class SignKeyInternalController {
+
+    private final ApplicationInfoRepository applicationInfoRepository;
+    private final AppAuthProperties appAuthProperties;
+
+    public SignKeyInternalController(ApplicationInfoRepository applicationInfoRepository,
+                                     AppAuthProperties appAuthProperties) {
+        this.applicationInfoRepository = applicationInfoRepository;
+        this.appAuthProperties = appAuthProperties;
+    }
+
+    @GetMapping("sign-key/{appId}")
+    public ResponseEntity<Map<String, Object>> signKey(@PathVariable String appId) {
+        Integer key;
+        try {
+            key = Integer.parseInt(appId.trim());
+        } catch (NumberFormatException e) {
+            return ResponseEntity.notFound().build();
+        }
+        ApplicationInfo info = applicationInfoRepository.findByAppKey(key);
+        if (info != null && info.getAppSecret() != null && !info.getAppSecret().trim().isEmpty()) {
+            return ok(info.getAppKey() == null ? appId : String.valueOf(info.getAppKey()),
+                    info.getAppSecret());
+        }
+        // 库内无此应用密钥：回退到配置式受信应用（平台自身默认密钥 100616 等），
+        // 避免「应用中心默认 appKey 未落库」时兜底查询返回 404。
+        String cfgSecret = appAuthProperties.getTrustedApps().get(appId);
+        if (cfgSecret != null && !cfgSecret.trim().isEmpty()) {
+            return ok(appId, cfgSecret);
+        }
+        return ResponseEntity.notFound().build();
+    }
+
+    private static ResponseEntity<Map<String, Object>> ok(String appKey, String secret) {
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("appKey", appKey);
+        body.put("secret", secret);
+        body.put("enabled", true);
+        return ResponseEntity.ok(body);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/controller/oapi/UserController.java b/src/main/java/com/yunhai/userbase/controller/oapi/UserController.java
new file mode 100644
index 0000000..9623605
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/controller/oapi/UserController.java
@@ -0,0 +1,233 @@
+package com.yunhai.userbase.controller.oapi;
+
+import com.yunhai.platform.appauth.AppAuthFilter;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.model.BoaGroup;
+import com.yunhai.platform.utils.model.BoaModule;
+import com.yunhai.platform.utils.model.BoaRoleInfo;
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import com.yunhai.userbase.config.Config;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.sysuser.SysUserGroupDeleteItem;
+import com.yunhai.userbase.model.sysuser.SysUserMoveRequest;
+import com.yunhai.userbase.model.sysuser.SysUserPasswordRequest;
+import com.yunhai.userbase.model.sysuser.SysUserRequest;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.service.IGroupAuthzService;
+import com.yunhai.userbase.service.ISysUserService;
+import com.yunhai.userbase.service.impl.UserCenterService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.servlet.http.HttpServletRequest;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 用户中心开放接口：供其他业务服务经 yh-app-auth 签名调用（{@code /oapi/user/...}）。<br>
+ * <br>
+ * 路径复用 {@link Config#OPEN_API_PATH} 统一前缀，与基础平台 {@code DefaultUserCenterClient}
+ * 硬编码的契约严格一致：
+ * {@code GET /oapi/user/byId?id=}、{@code /byLoginName?loginName=}、{@code /byPhone?phone=}、
+ * {@code /oapi/user/modules?userId=&schId=}。<br>
+ * 接口本身不做验签——签名由 {@code OpenApiAuthEnforceConfiguration} 在过滤器层强制要求，
+ * 未带 {@code X-App-Key/X-Timestamp/X-Signature} 的请求直接 401。
+ */
+@RestController
+@RequestMapping(Config.OPEN_API_PATH + "user/")
+public class UserController {
+
+    private static final Logger log = LoggerFactory.getLogger(UserController.class);
+
+    @Autowired
+    private UserCenterService userCenterService;
+
+    @Autowired
+    private ISysUserService sysUserService;
+
+    @Autowired
+    private IGroupAuthzService groupAuthzService;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @GetMapping("byId")
+    public BoaUser byId(@RequestParam("id") Integer id) {
+        return userCenterService.getUserInfoWithDeptById(id);
+    }
+
+    @GetMapping("byLoginName")
+    public BoaUser byLoginName(@RequestParam("loginName") String loginName) {
+        if (loginName == null || loginName.trim().isEmpty()) {
+            return null;
+        }
+        return userCenterService.getUserInfoWithDeptByAccount(loginName);
+    }
+
+    @GetMapping("byPhone")
+    public BoaUser byPhone(@RequestParam("phone") String phone) {
+        if (phone == null || phone.trim().isEmpty()) {
+            return null;
+        }
+        return userCenterService.getUserInfoWithDeptByPhone(phone);
+    }
+
+    /**
+     * 查询用户在<b>调用方应用</b>下、指定学校（上下文）里的已授权模块列表。<br>
+     * <br>
+     * 与管理端「权限一览」返回<b>全应用聚合</b>不同，本方法严格按调用方应用维度过滤：<br>
+     * ① 通过 {@link AppAuthFilter#APP_AUTH_ATTR} 拿到验签时的 appKey（RequireAppSignFilter
+     * 已保证非空）；<br>
+     * ② 查 application_info 映射到具体 appId；<br>
+     * ③ 调 Service 专用方法：所有 SQL/集合构建均限定在该 appId 范围内（数据库层面过滤）。<br>
+     * <br>
+     * 边界：调用方 appKey 查不到对应应用 → 直接返回空列表（安全优先，禁止意外返回其他应用的模块）。<br>
+     *
+     * @param request 用于取 AppAuthFilter 设置的 appKey
+     * @param userId  用户ID（必填）
+     * @param schId   学校ID/组ID（可选；用于限定「学校上下文」：非空时仅取该学校子树内的真实归属组参与判定，
+     *                为空时取用户全部真实归属组，与权限一览一致）
+     * @return 该应用下用户已授权模块（扁平化；无权限时返回空列表）
+     */
+    @GetMapping("modules")
+    public List<BoaModule> modules(HttpServletRequest request,
+            @RequestParam("userId") Integer userId,
+            @RequestParam(value = "schId", required = false) Integer schId) {
+        if (userId == null) {
+            return Collections.emptyList();
+        }
+        Integer appId = resolveCallerAppId(request);
+        if (appId == null) {
+            return Collections.emptyList();
+        }
+        return groupAuthzService.findUserModulesForApp(appId, schId, userId);
+    }
+
+    /**
+     * 从请求 attribute 中解析调用方 appKey，并映射为 application_info 的主键 id。<br>
+     * 映射失败返回 null（Controller 层统一返回空列表；异常只打 warn 日志，不给前端 500）。
+     */
+    private Integer resolveCallerAppId(HttpServletRequest request) {
+        Object attr = request.getAttribute(AppAuthFilter.APP_AUTH_ATTR);
+        if (attr == null) {
+            log.warn("[oapi:user:modules] no AppAuth attr (should be blocked by RequireAppSignFilter), uri={}",
+                    request.getRequestURI());
+            return null;
+        }
+        String appKeyStr = (attr instanceof String) ? (String) attr : String.valueOf(attr);
+        if (appKeyStr.trim().isEmpty()) {
+            log.warn("[oapi:user:modules] AppAuth attr is blank, uri={}", request.getRequestURI());
+            return null;
+        }
+        Integer appKey;
+        try {
+            appKey = Integer.parseInt(appKeyStr.trim());
+        } catch (NumberFormatException e) {
+            log.warn("[oapi:user:modules] invalid appKey format={}, uri={}", appKeyStr, request.getRequestURI());
+            return null;
+        }
+        ApplicationInfo app = applicationInfoRepository.findByAppKey(appKey);
+        if (app == null) {
+            log.warn("[oapi:user:modules] appKey={} not found in application_info, uri={}", appKey,
+                    request.getRequestURI());
+            return null;
+        }
+        return app.getId();
+    }
+
+
+    /**
+     * 新增用户：走完整校验（账号唯一/手机号/身份证/密码强度），BCrypt 加密并写入组关联；
+     * 返回创建后的用户（含 id 与组织链）。<br>
+     * 鉴权由 OpenApiAuthEnforceConfiguration 在过滤器层强制签名；此处不记操作日志（避免明文密码写入 request_params）。
+     */
+    @PostMapping("add")
+    public BoaUser add(@RequestBody @Validated(ValidationGroups.Create.class) SysUserRequest request) {
+        Integer id = sysUserService.add(request);
+        return userCenterService.getUserInfoWithDeptById(id);
+    }
+
+    /**
+     * 编辑用户：密码为空时不修改密码；返回更新后的用户（含 id 与组织链）。
+     */
+    @PostMapping("edit/{id}")
+    public BoaUser edit(@PathVariable Integer id,
+            @RequestBody @Validated(ValidationGroups.Update.class) SysUserRequest request) {
+        sysUserService.edit(id, request);
+        return userCenterService.getUserInfoWithDeptById(id);
+    }
+
+    /**
+     * 删除用户（按组解绑，语义同管理端「从组中删除用户」）：仅解除该用户与指定组的关联；<br>
+     * 仅当用户已无任何组关联时，才级联删除 sys_user 及其角色绑定。<br>
+     * 这样多校用户只会被退出指定学校，而不会被整体误删。<br>
+     * 新增 {@code schoolId} 边界：服务端强制 groupId 属于该校子树且不等于 schoolId，避免跨校/整校移除。
+     */
+    @PostMapping("delete/{id}/{groupId}/{schoolId}")
+    public void delete(@PathVariable Integer id, @PathVariable Integer groupId, @PathVariable Integer schoolId) {
+        sysUserService.deleteFromGroup(id, groupId, schoolId);
+    }
+
+    /**
+     * 批量删除用户-组关系：请求体为 {@code SysUserGroupDeleteItem} 数组，每条携带自身 (userId, groupId, schoolId)；<br>
+     * 服务端逐条校验学校边界后解绑，语义与单条 delete 一致。
+     */
+    @PostMapping("deleteUsers")
+    public void deleteUsers(@RequestBody List<SysUserGroupDeleteItem> items) {
+        sysUserService.deleteUsers(items);
+    }
+
+    /**
+     * 批量新增用户：逐条走完整校验（含密码强度，每条需携带 password + confirmPassword）；
+     * 返回创建后的用户列表（顺序与入参一致，均含 id 与组织链）。
+     */
+    @PostMapping("batchAdd")
+    public List<BoaUser> batchAdd(@RequestBody List<SysUserRequest> requests) {
+        List<Integer> ids = sysUserService.batchAdd(requests);
+        List<BoaUser> result = new ArrayList<>();
+        for (Integer id : ids) {
+            result.add(userCenterService.getUserInfoWithDeptById(id));
+        }
+        return result;
+    }
+
+    /**
+     * 移动用户到指定组：仅允许在同一学校（组）范围内移动——用户当前必须已在该学校子树内，
+     * 且目标组也必须在该学校子树内，否则拒绝（禁止跨校移动）。<br>
+     * 语义同后台「调整组」——覆盖式把用户组归属替换为目标组（目标设为主组）。返回移动后的用户（含新的组织链）。
+     */
+    @PostMapping("moveToGroup")
+    public BoaUser moveToGroup(@RequestBody @Validated SysUserMoveRequest request) {
+        sysUserService.moveUserWithinSchool(request.getUserId(), request.getGroupId(), request.getSchoolId());
+        return userCenterService.getUserInfoWithDeptById(request.getUserId());
+    }
+
+    /**
+     * 查询用户的业务角色身份列表（角色 + 主归属学校组上下文）。<br>
+     * 鉴权由 OpenApiAuthEnforceConfiguration 在过滤器层强制签名。
+     */
+    @GetMapping("roles")
+    public List<BoaRoleInfo> roles(@RequestParam("userId") Integer userId) {
+        return sysUserService.findUserRoles(userId);
+    }
+
+    /**
+     * 修改用户密码：先校验旧密码，再写入新密码（BCrypt）。<br>
+     * 鉴权由 OpenApiAuthEnforceConfiguration 在过滤器层强制签名；此处不记操作日志（避免明文密码写入 request_params）。
+     */
+    @PostMapping("password")
+    public void password(@RequestBody @Validated SysUserPasswordRequest request) {
+        sysUserService.changePassword(request.getUserId(), request.getOldPassword(), request.getNewPassword());
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/AppCategory.java b/src/main/java/com/yunhai/userbase/entity/AppCategory.java
new file mode 100644
index 0000000..15dccc3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/AppCategory.java
@@ -0,0 +1,28 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 15:53
+ * @description
+ */
+
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "app_category")
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class AppCategory extends  BaseEntity {
+    //类别名称
+    @Column(name = "name", nullable = false)
+    private String name;
+
+    @Column(name = "sort_no")
+    private  Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/AppModule.java b/src/main/java/com/yunhai/userbase/entity/AppModule.java
new file mode 100644
index 0000000..6ae9897
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/AppModule.java
@@ -0,0 +1,81 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块（树形，逻辑外键，最深5层）<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(
+    name = "app_module",
+    indexes = {
+        @Index(name = "idx_app_module_app", columnList = "app_id"),
+        @Index(name = "idx_app_module_parent", columnList = "parent_id")
+    },
+    uniqueConstraints = {
+        @UniqueConstraint(name = "uk_app_module_custom", columnNames = {"app_id", "custom_id"})
+    }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class AppModule extends BaseEntity {
+
+    /**
+     * 所属应用ID（逻辑外键 → ApplicationInfo.id），创建后不可改。<br>
+     */
+    @NotNull
+    @Column(name = "app_id", nullable = false, updatable = false)
+    private Integer appId;
+
+    /**
+     * 父模块ID（逻辑外键 → AppModule.id）；根模块为 null。<br>
+     */
+    @Column(name = "parent_id")
+    private Integer parentId;
+
+    /**
+     * 模块名称。<br>
+     */
+    @NotBlank
+    @Column(name = "name", nullable = false)
+    private String name;
+
+    /**
+     * 自定义ID（应用内唯一，业务编码，如 "user-mgmt"）。<br>
+     */
+    @NotBlank
+    @Column(name = "custom_id", nullable = false, length = 64)
+    private String customId;
+
+    /**
+     * 模块路径（前端路由/资源路径，如 "/system/user"）。<br>
+     */
+    @Column(name = "path", length = 255)
+    private String path;
+
+    /**
+     * 层级：根=1，子=父+1，上限5（由 Service 校验）。<br>
+     */
+    @NotNull
+    @Column(name = "level", nullable = false)
+    private Integer level;
+
+    /**
+     * 排序号（沿用 AppCategory 约定）。<br>
+     */
+    @Column(name = "sort_no")
+    private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/ApplicationInfo.java b/src/main/java/com/yunhai/userbase/entity/ApplicationInfo.java
new file mode 100644
index 0000000..6d17c06
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/ApplicationInfo.java
@@ -0,0 +1,146 @@
+package com.yunhai.userbase.entity;
+
+import com.yunhai.userbase.common.converter.ListIntegerJsonConverter;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Convert;
+import javax.persistence.Entity;
+import javax.persistence.Table;
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 15:53
+ * @description
+ */
+
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "application_info")
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class ApplicationInfo extends BaseEntity  {
+
+    /**
+     * 应用名称（页面*必填）
+     */
+    private String name;
+
+    /**
+     * 应用类型ID
+     */
+    private Integer categoryId;
+
+    /**
+     * 排序号，仅在同一个应用类型内生效；默认为 null（新增时不赋值）。<br>
+     */
+    @Column(name = "sort_no")
+    private Integer sortNo;
+
+    /**
+     * 应用描述
+     */
+    @Column(name = "app_desc", length = 500)
+    private String desc;
+
+    /**
+     * appKey 系统生成唯一标识，整型，从100000起自增。<br>
+     */
+    @NotNull
+    @Column(name = "app_key", unique = true, nullable = false)
+    private Integer appKey;
+
+    /**
+     * appSecret 密钥，支持重设
+     */
+    @NotBlank
+    @Column(name = "app_secret", nullable = false, length = 128)
+    private String appSecret;
+
+    //应用前端类型
+    @Convert(converter = ListIntegerJsonConverter.class)
+//    @Column(name = "clients", columnDefinition = "json")
+    @Column(name = "clients", columnDefinition = "TEXT")
+    private List<Integer> clients;
+
+    /**
+     * PC应用访问地址
+     */
+    @Column(name = "pc_url")
+    private String pcUrl;
+
+    /**
+     * PC应用图标 图片URL
+     */
+    @Column(name = "pc_icon")
+    private String pcIcon;
+
+    /**
+     * App访问地址（移动端主地址）
+     */
+    @Column(name = "app_url")
+    private String appUrl;
+
+    /**
+     * App应用图标 图片URL
+     */
+    @Column(name = "app_icon")
+    private String appIcon;
+
+    /**
+     * 公众号应用地址
+     */
+    @Column(name = "official_account_url")
+    private String officialAccountUrl;
+
+    /**
+     * 钉钉应用地址
+     */
+    @Column(name = "dingtalk_url")
+    private String dingtalkUrl;
+
+    // ===================== 推送订阅配置（文档《弘育基础平台数据同步接口 2》） =====================
+
+    /**
+     * 推送外部接口地址（不含固定后缀），如 http://host/notice/api/base/ 。
+     * 完整调用地址 = pushBaseUrl + 接口路径（如 group/AddGroup）。
+     */
+    @Column(name = "push_base_url")
+    private String pushBaseUrl;
+
+    /**
+     * 推送总开关：0关 1开（默认 0，自动推送默认不触发）。
+     */
+    @Column(name = "push_enabled", nullable = false)
+    private Integer pushEnabled = 0;
+
+    /**
+     * 启用的接口路径，逗号分隔（如 group/AddGroup,user/AddUser）；空=不推送任何接口。
+     */
+    @Column(name = "push_event_types")
+    private String pushEventTypes;
+
+    /**
+     * 关联学校组 id，逗号分隔；空=全局（监听所有学校变化）。
+     */
+    @Column(name = "push_school_ids")
+    private String pushSchoolIds;
+
+    /**
+     * 推送角色 key，逗号分隔；空=全部角色。
+     */
+    @Column(name = "push_role_ids")
+    private String pushRoleIds;
+
+    /**
+     * 推送签名密钥；空则复用 appSecret。
+     */
+    @Column(name = "push_secret")
+    private String pushSecret;
+
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/entity/BaseEntity.java b/src/main/java/com/yunhai/userbase/entity/BaseEntity.java
new file mode 100644
index 0000000..4ac3dcf
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/BaseEntity.java
@@ -0,0 +1,63 @@
+package com.yunhai.userbase.entity;
+
+
+import javax.persistence.*;
+import javax.validation.constraints.NotNull;
+
+import com.yunhai.userbase.common.listener.UserAuditListener;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Getter;
+import lombok.Setter;
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+/**
+ * @author chenx
+ * @date 2026/7/14 10:46
+ * @description
+ */
+
+@MappedSuperclass
+@Getter
+@Setter
+@EntityListeners(UserAuditListener.class)
+public abstract class BaseEntity  implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @NotNull(groups = ValidationGroups.Update.class)
+    private Integer id;
+
+    /**
+     * 创建人ID
+     */
+    @Column(name = "create_user", nullable = false, updatable = false)
+    private Integer createUser;
+
+    /**
+     * 创建时间
+     */
+    @CreationTimestamp
+    @Column(name = "create_time", nullable = false, updatable = false)
+    private LocalDateTime createTime;
+
+    /**
+     * 更新人ID
+     */
+    @Column(name = "update_user")
+    private Integer updateUser;
+
+    /**
+     * 更新时间
+     */
+    @UpdateTimestamp
+    @Column(name = "update_time")
+    private LocalDateTime updateTime;
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysAppRole.java b/src/main/java/com/yunhai/userbase/entity/SysAppRole.java
new file mode 100644
index 0000000..c8be052
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysAppRole.java
@@ -0,0 +1,68 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 应用业务角色。<br>
+ *              普通角色：allAppFlag=false 且 appId 必填；<br>
+ *              全应用角色：allAppFlag=true 且 appId 为空；<br>
+ *              注意：这里的“业务角色”不等同于 {@code sys_user.roles} 对应的系统身份枚举。<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "sys_app_role", indexes = {
+        @Index(name = "idx_app_role_app", columnList = "app_id"),
+        @Index(name = "idx_app_role_all_app", columnList = "all_app_flag"),
+        @Index(name = "idx_app_role_name", columnList = "name")
+})
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysAppRole extends BaseEntity {
+
+    /**
+     * 角色名称。<br>
+     */
+    @NotBlank
+    @Column(name = "name", nullable = false, length = 100)
+    private String name;
+
+    /**
+     * 所属应用ID（逻辑外键 → ApplicationInfo.id）。<br>
+     * 普通角色必填；全应用角色为空。<br>
+     */
+    @Column(name = "app_id")
+    private Integer appId;
+
+    /**
+     * 是否全应用角色。<br>
+     * true=可跨应用勾选模块；false=仅能授权所属应用下的模块。<br>
+     */
+    @NotNull
+    @Column(name = "all_app_flag", nullable = false)
+    private Boolean allAppFlag = Boolean.FALSE;
+
+    /**
+     * 角色备注。<br>
+     */
+    @Column(name = "remark", length = 500)
+    private String remark;
+
+    /**
+     * 是否禁用。<br>
+     * 禁用后角色关系可保留，但权限计算时应忽略该角色。<br>
+     */
+    @NotNull
+    @Column(name = "disabled", nullable = false)
+    private Boolean disabled = Boolean.FALSE;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysAppRoleModuleRel.java b/src/main/java/com/yunhai/userbase/entity/SysAppRoleModuleRel.java
new file mode 100644
index 0000000..fda1c4b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysAppRoleModuleRel.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 业务角色-模块权限关系表（逻辑外键，无物理 FK）。<br>
+ * 存在记录即代表该角色显式拥有该模块。<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(
+    name = "sys_app_role_module_rel",
+    indexes = {
+        @Index(name = "idx_app_role_module_role", columnList = "role_id"),
+        @Index(name = "idx_app_role_module_module", columnList = "module_id")
+    },
+    uniqueConstraints = {
+        @UniqueConstraint(name = "uk_app_role_module", columnNames = {"role_id", "module_id"})
+    }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysAppRoleModuleRel extends BaseEntity {
+
+    /**
+     * 角色ID（逻辑外键 → SysAppRole.id）。<br>
+     */
+    @NotNull
+    @Column(name = "role_id", nullable = false)
+    private Integer roleId;
+
+    /**
+     * 模块ID（逻辑外键 → AppModule.id）。<br>
+     */
+    @NotNull
+    @Column(name = "module_id", nullable = false)
+    private Integer moduleId;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysGroup.java b/src/main/java/com/yunhai/userbase/entity/SysGroup.java
new file mode 100644
index 0000000..fcfb5b7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysGroup.java
@@ -0,0 +1,42 @@
+package com.yunhai.userbase.entity;
+
+import com.yunhai.userbase.common.converter.GroupTypeEnumConverter;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/13 22:48
+ * @description 系统节点（组）表
+ */
+
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "sys_group")
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysGroup extends BaseEntity   {
+
+    private String name;
+
+    @Column(name = "parent_id", nullable = false)
+    private Integer parentId;
+
+    @Column(name = "type")
+    @Convert(converter = GroupTypeEnumConverter.class)
+    private GroupTypeEnum type;
+
+    private Integer sort;
+
+
+    // 一对多反向关联中间表
+    @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
+    @JoinColumn(name = "groupId", insertable = false, updatable = false)
+    private List<SysUserGroupRel> userGroupRelList;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysGroupAppRel.java b/src/main/java/com/yunhai/userbase/entity/SysGroupAppRel.java
new file mode 100644
index 0000000..3a99ffb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysGroupAppRel.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组应用开通表（逻辑外键，无物理 FK）。<br>
+ * 记录某个组显式开通了哪些应用；仅当本表存在记录时，「组授权」界面右侧才显示该应用。<br>
+ * 开通不继承：子组要使用应用必须自己开通。<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(
+    name = "sys_group_app_rel",
+    indexes = {
+        @Index(name = "idx_group_app_rel_app", columnList = "app_id")
+    },
+    uniqueConstraints = {
+        @UniqueConstraint(name = "uk_group_app", columnNames = {"group_id", "app_id"})
+    }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysGroupAppRel extends BaseEntity {
+
+    /**
+     * 组ID（逻辑外键 → SysGroup.id）。<br>
+     */
+    @NotNull
+    @Column(name = "group_id", nullable = false)
+    private Integer groupId;
+
+    /**
+     * 应用ID（逻辑外键 → ApplicationInfo.id）。<br>
+     */
+    @NotNull
+    @Column(name = "app_id", nullable = false)
+    private Integer appId;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysGroupModulePerm.java b/src/main/java/com/yunhai/userbase/entity/SysGroupModulePerm.java
new file mode 100644
index 0000000..c59c22a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysGroupModulePerm.java
@@ -0,0 +1,56 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组模块权限表（逻辑外键，无物理 FK）。<br>
+ * 存在记录即代表该组勾选了该模块；inheritFlag=true 时当前组及其所有子孙组自动继承该模块权限。<br>
+ * 取消勾选时物理删除记录。<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(
+    name = "sys_group_module_perm",
+    indexes = {
+        @Index(name = "idx_group_module_perm_module", columnList = "module_id")
+    },
+    uniqueConstraints = {
+        @UniqueConstraint(name = "uk_group_module", columnNames = {"group_id", "module_id"})
+    }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysGroupModulePerm extends BaseEntity {
+
+    /**
+     * 组ID（逻辑外键 → SysGroup.id）。<br>
+     */
+    @NotNull
+    @Column(name = "group_id", nullable = false)
+    private Integer groupId;
+
+    /**
+     * 模块ID（逻辑外键 → AppModule.id）。<br>
+     */
+    @NotNull
+    @Column(name = "module_id", nullable = false)
+    private Integer moduleId;
+
+    /**
+     * 是否子组继承（false=仅本组生效，true=子孙组自动继承），对应 UI「子组继承」勾选框。<br>
+     */
+    @NotNull
+    @Column(name = "inherit_flag", nullable = false)
+    private Boolean inheritFlag = Boolean.FALSE;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysOapiLog.java b/src/main/java/com/yunhai/userbase/entity/SysOapiLog.java
new file mode 100644
index 0000000..5ab18d6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysOapiLog.java
@@ -0,0 +1,148 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+
+/**
+ * 开放接口调用日志实体。<br>
+ * 记录 yh-app-auth 签名调用方（YschBaseOpenApi 门面背后的 /oapi/** 端点）的操作，
+ * 身份主体为「调用方应用」（callerAppKey/callerAppName），区别于管理端 sys_operation_log 的登录用户维度。<br>
+ * 请求参数与响应均已脱敏后入库（敏感字段见 SensitiveDataMasker）。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "sys_oapi_log", indexes = {
+        @Index(name = "idx_create_time", columnList = "create_time"),
+        @Index(name = "idx_appkey_time", columnList = "caller_app_key, create_time"),
+        @Index(name = "idx_uri_time", columnList = "request_uri, create_time"),
+        @Index(name = "idx_level_time", columnList = "log_level, create_time"),
+        @Index(name = "idx_ip_time", columnList = "request_ip, create_time")
+})
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysOapiLog implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键
+     */
+    @EqualsAndHashCode.Include
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    /**
+     * 日志级别：1-重要(删除) 2-次要(新增/编辑) 3-一般(查询)
+     */
+    @Column(name = "log_level", nullable = false, columnDefinition = "TINYINT")
+    private Integer logLevel;
+
+    /**
+     * 调用方应用 appKey（验签后写入 request attribute 的 AppAuthFilter.APP_AUTH_ATTR）
+     */
+    @Column(name = "caller_app_key", nullable = false)
+    private Integer callerAppKey;
+
+    /**
+     * 调用方应用名（application_info 解析；解析失败记 appKey 原值）
+     */
+    @Column(name = "caller_app_name", length = 128)
+    private String callerAppName;
+
+    /**
+     * 请求IP
+     */
+    @Column(name = "request_ip", nullable = false, length = 64)
+    private String requestIp;
+
+    /**
+     * 请求路径
+     */
+    @Column(name = "request_uri", nullable = false, length = 512)
+    private String requestUri;
+
+    /**
+     * 请求方法 GET/POST/PUT/DELETE
+     */
+    @Column(name = "request_method", nullable = false, length = 16)
+    private String requestMethod;
+
+    /**
+     * 操作类型 DELETE/CREATE/UPDATE/QUERY
+     */
+    @Column(name = "operation_type", nullable = false, length = 32)
+    private String operationType;
+
+    /**
+     * 类名.方法名
+     */
+    @Column(name = "class_method", nullable = false, length = 512)
+    private String classMethod;
+
+    /**
+     * 操作描述（@OapiLog 注解 value 提供，可选）
+     */
+    @Column(name = "operation_desc", length = 255)
+    private String operationDesc;
+
+    /**
+     * 请求参数JSON（脱敏后）
+     */
+    @Column(name = "request_params", columnDefinition = "TEXT")
+    private String requestParams;
+
+    /**
+     * 响应结果（GZIP 压缩，脱敏后）
+     */
+    @Column(name = "response_data", columnDefinition = "MEDIUMBLOB")
+    private byte[] responseData;
+
+    /**
+     * HTTP状态码
+     */
+    @Column(name = "status_code", nullable = false)
+    private Integer statusCode;
+
+    /**
+     * 耗时(ms)
+     */
+    @Column(name = "cost_time", nullable = false)
+    private Long costTime;
+
+    /**
+     * 调用方UA
+     */
+    @Column(name = "user_agent", length = 512)
+    private String userAgent;
+
+    /**
+     * 错误信息
+     */
+    @Column(name = "error_msg", columnDefinition = "TEXT")
+    private String errorMsg;
+
+    /**
+     * 调用时间
+     */
+    @CreationTimestamp
+    @Column(name = "create_time", nullable = false, updatable = false, columnDefinition = "DATETIME(3)")
+    private LocalDateTime createTime;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysOperationLog.java b/src/main/java/com/yunhai/userbase/entity/SysOperationLog.java
new file mode 100644
index 0000000..ade5499
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysOperationLog.java
@@ -0,0 +1,140 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+
+/**
+ * 系统操作日志实体。<br>
+ * 记录用户的关键操作（增删改查），便于审计与问题排查。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "sys_operation_log", indexes = {
+        @Index(name = "idx_create_time", columnList = "create_time"),
+        @Index(name = "idx_user_time", columnList = "user_id, create_time"),
+        @Index(name = "idx_uri_time", columnList = "request_uri, create_time"),
+        @Index(name = "idx_level_time", columnList = "log_level, create_time"),
+        @Index(name = "idx_ip_time", columnList = "request_ip, create_time")
+})
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysOperationLog implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键
+     */
+    @EqualsAndHashCode.Include
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    /**
+     * 日志级别：1-重要(删除) 2-次要(新增/编辑) 3-一般(查询)
+     */
+    @Column(name = "log_level", nullable = false, columnDefinition = "TINYINT")
+    private Integer logLevel;
+
+    /**
+     * 操作用户ID
+     */
+    @Column(name = "user_id", nullable = false)
+    private Long userId;
+
+    /**
+     * 操作用户名
+     */
+    @Column(name = "username", nullable = false, length = 64)
+    private String username;
+
+    /**
+     * 请求IP
+     */
+    @Column(name = "request_ip", nullable = false, length = 64)
+    private String requestIp;
+
+    /**
+     * 请求路径
+     */
+    @Column(name = "request_uri", nullable = false, length = 512)
+    private String requestUri;
+
+    /**
+     * 请求方法 GET/POST/PUT/DELETE
+     */
+    @Column(name = "request_method", nullable = false, length = 16)
+    private String requestMethod;
+
+    /**
+     * 操作类型 DELETE/CREATE/UPDATE/QUERY
+     */
+    @Column(name = "operation_type", nullable = false, length = 32)
+    private String operationType;
+
+    /**
+     * 类名.方法名
+     */
+    @Column(name = "class_method", nullable = false, length = 512)
+    private String classMethod;
+
+    /**
+     * 请求参数JSON
+     */
+    @Column(name = "request_params", columnDefinition = "TEXT")
+    private String requestParams;
+
+    /**
+     * 响应结果(GZIP压缩)
+     */
+    @Column(name = "response_data", columnDefinition = "MEDIUMBLOB")
+    private byte[] responseData;
+
+    /**
+     * HTTP状态码
+     */
+    @Column(name = "status_code", nullable = false)
+    private Integer statusCode;
+
+    /**
+     * 耗时(ms)
+     */
+    @Column(name = "cost_time", nullable = false)
+    private Long costTime;
+
+    /**
+     * 浏览器UA
+     */
+    @Column(name = "user_agent", length = 512)
+    private String userAgent;
+
+    /**
+     * 错误信息
+     */
+    @Column(name = "error_msg", columnDefinition = "TEXT")
+    private String errorMsg;
+
+    /**
+     * 操作时间
+     */
+    @CreationTimestamp
+    @Column(name = "create_time", nullable = false, updatable = false, columnDefinition = "DATETIME(3)")
+    private LocalDateTime createTime;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysUser.java b/src/main/java/com/yunhai/userbase/entity/SysUser.java
new file mode 100644
index 0000000..6a1c6ed
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysUser.java
@@ -0,0 +1,77 @@
+package com.yunhai.userbase.entity;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.yunhai.userbase.common.converter.ListIntegerJsonConverter;
+import com.yunhai.userbase.common.converter.StatusEnumConverter;
+import com.yunhai.userbase.common.converter.UserTypeEnumConverter;
+import com.yunhai.userbase.enums.StatusEnum;
+import com.yunhai.userbase.enums.UserTypeEnum;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/13 23:30
+ * @description 系统用户表
+ */
+
+@NoArgsConstructor
+@Data
+@Entity
+@Table(name = "sys_user")
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysUser extends BaseEntity {
+
+    @Column(name = "username", nullable = false, unique = true)
+    private String account;
+    private String password;
+    //出生日期
+    private LocalDate birthday;
+
+    @JsonProperty("name")
+    private String realName;
+
+    private String phone;
+
+    private String idcard;
+
+    private String email;
+
+    private Integer gender;
+
+    //头像
+    private String profilePicture;
+
+    /**
+     * 角色列表，存储为 MySQL JSON 类型，读取时自动映射为 List<Long>
+     * 取值对应 {@link com.yunhai.userbase.enums.SysRoleEnum} 的 key，例如 [1,2,3]
+     */
+    @Convert(converter = ListIntegerJsonConverter.class)
+//    @Column(name = "roles", columnDefinition = "json")
+    @Column(name = "roles",columnDefinition = "TEXT")
+    private List<Integer> roles;
+
+    // 一对多：关联用户分组中间表，实现多对多业务
+    @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
+    @JoinColumn(name = "userId", insertable = false, updatable = false)
+    private List<SysUserGroupRel> userGroupRelList;
+
+    // 是否禁用：存储为 StatusEnum（0=正常/未禁用，1=禁用），与 GroupTypeEnum 同机制；默认启用
+    @Convert(converter = StatusEnumConverter.class)
+    private StatusEnum disabled;
+    //是否过期
+    private Boolean expired=false;
+
+    /**
+     * 用户类型：0=普通用户，1=超级管理员，2=学校管理员（见 UserTypeEnum）。
+     * 由应用层根据用户账号/角色推导：内置超级管理员账号固定为 1，其余账号含 ADMIN(7) 角色则为 2，默认 0。
+     */
+    @Convert(converter = UserTypeEnumConverter.class)
+    private UserTypeEnum type;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysUserAppRoleRel.java b/src/main/java/com/yunhai/userbase/entity/SysUserAppRoleRel.java
new file mode 100644
index 0000000..631a609
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysUserAppRoleRel.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 用户-业务角色关系表（逻辑外键，无物理 FK）。<br>
+ * 一个用户可绑定多个业务角色；一个角色也可绑定多个用户。<br>
+ */
+@NoArgsConstructor
+@Data
+@Entity
+@Table(
+    name = "sys_user_app_role_rel",
+    indexes = {
+        @Index(name = "idx_user_app_role_user", columnList = "user_id"),
+        @Index(name = "idx_user_app_role_role", columnList = "role_id")
+    },
+    uniqueConstraints = {
+        @UniqueConstraint(name = "uk_user_app_role", columnNames = {"user_id", "role_id"})
+    }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysUserAppRoleRel extends BaseEntity {
+
+    /**
+     * 用户ID（逻辑外键 → SysUser.id）。<br>
+     */
+    @NotNull
+    @Column(name = "user_id", nullable = false)
+    private Integer userId;
+
+    /**
+     * 角色ID（逻辑外键 → SysAppRole.id）。<br>
+     */
+    @NotNull
+    @Column(name = "role_id", nullable = false)
+    private Integer roleId;
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysUserCurrentRole.java b/src/main/java/com/yunhai/userbase/entity/SysUserCurrentRole.java
new file mode 100644
index 0000000..7935603
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysUserCurrentRole.java
@@ -0,0 +1,60 @@
+package com.yunhai.userbase.entity;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import javax.validation.constraints.NotNull;
+import java.time.LocalDateTime;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 15:05
+ * @description 用户当前角色
+ */
+@Data
+@NoArgsConstructor
+@Entity
+@Table(
+        name = "sys_user_current_role",
+        uniqueConstraints = @UniqueConstraint(columnNames = {"userId"}),
+        indexes = {@Index(columnList = "userId")}
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysUserCurrentRole {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @NotNull(groups = ValidationGroups.Update.class)
+    private Integer id;
+
+    /**
+     * 用户ID，一对一唯一
+     */
+    @Column(nullable = false)
+    private Integer userId;
+
+    /**
+     * 用户切换选中的学校ID（根级group，数值即学校组 sys_group.id；区域/学段/根直属=0或null）
+     */
+    private Integer schoolId;
+    /**
+     * 用户切换后生效角色ID（SysRoleEnum.key）
+     */
+    private Integer roleId;
+
+    /**
+     * 最近一次切换时间（服务端 now() 写入）
+     */
+    @Column(name = "switch_time")
+    private LocalDateTime switchTime;
+
+    /**
+     * 学校名冗余（避免每次 join sys_group 取 name）
+     */
+    @Column(name = "school_name", length = 100)
+    private String schoolName;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysUserGroupRel.java b/src/main/java/com/yunhai/userbase/entity/SysUserGroupRel.java
new file mode 100644
index 0000000..de68291
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysUserGroupRel.java
@@ -0,0 +1,54 @@
+package com.yunhai.userbase.entity;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import javax.validation.constraints.NotNull;
+import java.time.LocalDateTime;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 15:03
+ * @description 组用户多对多关联表
+ */
+
+@Data
+@NoArgsConstructor
+@Entity
+@Table(name = "sys_user_group_rel")
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysUserGroupRel {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @NotNull(groups = Update.class)
+    private Integer id;
+    /** 用户ID */
+    private Integer userId;
+    /** 分组ID */
+    private Integer groupId;
+    /** 是否主归属 1=本职主学校/部门 0=兼职兼任 */
+    private Integer isMain;
+
+    /** 组内排序号：越小越靠前；null 表示未设置，列表按 user_id 兜底升序 */
+    @Column(name = "sort_no")
+    private Integer sortNo;
+
+    private LocalDateTime createTime;
+
+    // 关联用户，仅查询，不维护外键
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "userId", referencedColumnName = "id", insertable = false, updatable = false)
+    private SysUser user;
+
+    // 关联分组，仅查询，不维护外键
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "groupId", referencedColumnName = "id", insertable = false, updatable = false)
+    private SysGroup group;
+
+
+    public @interface Update {
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/entity/SysUserRoleRel.java b/src/main/java/com/yunhai/userbase/entity/SysUserRoleRel.java
new file mode 100644
index 0000000..07cb6a6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/entity/SysUserRoleRel.java
@@ -0,0 +1,86 @@
+package com.yunhai.userbase.entity;
+
+import com.yunhai.userbase.common.converter.StatusEnumConverter;
+import com.yunhai.userbase.enums.StatusEnum;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+
+import javax.persistence.*;
+import javax.validation.constraints.NotNull;
+import java.time.LocalDateTime;
+
+/**
+ * @author chenx
+ * @date 2026/8/18
+ * @description 用户-SysRoleEnum角色-学校 三元关联（平台身份角色的权威源）。
+ * <p>区别于 {@link SysUserAppRoleRel}（业务权限角色）：本表表达"用户在哪个学校下激活哪个平台身份角色"
+ * （如"刘文娟在 A 学校是老师"），角色取值对应 {@link com.yunhai.userbase.enums.SysRoleEnum} 的 key。</p>
+ * <p>不继承 BaseEntity：高频读写关系表，自定义字段更轻量，与 {@link SysUserGroupRel} 风格一致。</p>
+ */
+@Data
+@NoArgsConstructor
+@Entity
+@Table(
+        name = "sys_user_role_rel",
+        uniqueConstraints = @UniqueConstraint(columnNames = {"userId", "roleId", "schoolId"}),
+        indexes = {
+                @Index(columnList = "userId"),
+                @Index(columnList = "schoolId"),
+                @Index(columnList = "roleId")
+        }
+)
+@EqualsAndHashCode(onlyExplicitlyIncluded = true, callSuper = false)
+public class SysUserRoleRel {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @NotNull(groups = Update.class)
+    private Integer id;
+
+    /**
+     * 用户ID
+     */
+    @Column(nullable = false)
+    private Integer userId;
+
+    /**
+     * 角色ID（SysRoleEnum.key，1-7）
+     */
+    @Column(nullable = false)
+    private Integer roleId;
+
+    /**
+     * 学校组ID（=type=SCHOOL_GROUP 的 sys_group.id）；区域/学段/根直属用户填 0
+     */
+    @Column(nullable = false)
+    private Integer schoolId;
+
+    /**
+     * 是否主身份标记：每 userId 最多 1 条 isMain=1（应用层校验，不靠 uk）
+     */
+    @Column(nullable = false)
+    private Integer isMain = 0;
+
+    /**
+     * 排序号：越小越靠前
+     */
+    @Column(name = "sort_no", nullable = false)
+    private Integer sortNo = 0;
+
+    /**
+     * 状态：0=禁用 1=正常（StatusEnum）
+     */
+    @Convert(converter = StatusEnumConverter.class)
+    @Column(nullable = false)
+    private StatusEnum status = StatusEnum.NORMAL;
+
+    @Column(name = "create_time", nullable = false, updatable = false)
+    private LocalDateTime createTime;
+
+    @Column(name = "update_time", nullable = false)
+    private LocalDateTime updateTime;
+
+    public @interface Update {
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/BizType.java b/src/main/java/com/yunhai/userbase/enums/BizType.java
new file mode 100644
index 0000000..625634c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/BizType.java
@@ -0,0 +1,39 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/1/5 11:15
+ * @description 虚拟节点类型
+ */
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+public enum BizType {
+
+    ROOT (1),
+    TEXTBOOK (2),
+    GRADE (3),
+    KNOWLEDGE (4),
+    REALLY (5),
+    ;
+
+    private Integer key;
+
+    public static BizType getByKey(Integer key){
+        BizType[] enums = BizType.values();
+        Optional<BizType> opt = Arrays.stream(enums).filter(item -> item.getKey().equals(key)).findAny();
+        if(opt.isPresent()){
+            return opt.get();
+        }else {
+            return null;
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/BookType.java b/src/main/java/com/yunhai/userbase/enums/BookType.java
new file mode 100644
index 0000000..c4b8ad9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/BookType.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/1/16 9:32
+ * @description 资源类型
+ */
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+public enum BookType {
+    /** 教材 */
+    TextBook (1,"教材"),
+    /** 教辅 */
+    TeachingTutoring (2,"教辅"),
+    /** 知识点 */
+    KnowledgePoint (3,"知识点"),
+    ;
+
+    private Integer key;
+    private String value;
+
+    public static BookType getByKey(Integer key){
+        BookType[] enums = BookType.values();
+        Optional<BookType> opt = Arrays.stream(enums).filter(item -> item.getKey().equals(key)).findAny();
+        if(opt.isPresent()){
+            return opt.get();
+        }else {
+            return null;
+        }
+    }
+
+    public static String getValue(Integer key) {
+        for (BookType bookType : BookType.values()) {
+            if (bookType.getKey().equals(key)) {
+                return bookType.getValue();
+            }
+        }
+        return null;
+    }
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/GenderEnum.java b/src/main/java/com/yunhai/userbase/enums/GenderEnum.java
new file mode 100644
index 0000000..f456f66
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/GenderEnum.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/07/13
+ * @description 性别
+ */
+@Getter
+@AllArgsConstructor
+public enum GenderEnum implements IEnum<Integer> {
+
+    FEMALE(0, "女"),
+    MALE(1, "男");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/enums/GroupTypeEnum.java b/src/main/java/com/yunhai/userbase/enums/GroupTypeEnum.java
new file mode 100644
index 0000000..2c7fd11
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/GroupTypeEnum.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/07/13
+ * @description 分组类型
+ */
+@Getter
+@AllArgsConstructor
+public enum GroupTypeEnum implements IEnum<Integer> {
+
+    NORMAL_GROUP(1, "普通组"),
+    SCHOOL_GROUP(2, "学校组"),
+    GRADE_GROUP(3, "年级组"),
+    CLASS_GROUP(4, "班级组"),
+    AREA_GROUP(5, "区域组"),
+    STAGE_GROUP(6, "学段组"),
+    TEACHER_GROUP(7, "教师组"),
+    STUDENT_GROUP(8, "学生组");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/enums/IntegEnum.java b/src/main/java/com/yunhai/userbase/enums/IntegEnum.java
new file mode 100644
index 0000000..bb13031
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/IntegEnum.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/07/13
+ * @description 集成方式
+ */
+@Getter
+@AllArgsConstructor
+public enum IntegEnum implements IEnum<Integer> {
+
+    INNER(0, "内置"),
+    WEB(1, "Web"),
+    APP_JUMP(3, "App跳转");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/enums/LogLevel.java b/src/main/java/com/yunhai/userbase/enums/LogLevel.java
new file mode 100644
index 0000000..606d3e8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/LogLevel.java
@@ -0,0 +1,41 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 操作日志级别。<br>
+ * 1-重要(删除) 2-次要(新增/编辑) 3-一般(查询)。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Getter
+@AllArgsConstructor
+public enum LogLevel {
+
+    IMPORTANT(1, "重要(删除)"),
+    SECONDARY(2, "次要(新增/编辑)"),
+    GENERAL(3, "一般(查询)");
+
+    private final int code;
+    private final String desc;
+
+    /**
+     * 根据 code 反查级别。
+     *
+     * @param code 级别编码
+     * @return 对应级别，未知编码默认次要
+     */
+    public static LogLevel fromCode(Integer code) {
+        if (code == null) {
+            return SECONDARY;
+        }
+        for (LogLevel level : values()) {
+            if (level.code == code) {
+                return level;
+            }
+        }
+        return SECONDARY;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/ResourceSourceEnum.java b/src/main/java/com/yunhai/userbase/enums/ResourceSourceEnum.java
new file mode 100644
index 0000000..a0d2c4f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/ResourceSourceEnum.java
@@ -0,0 +1,21 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/1/5 13:53
+ * @description 资源来源
+ */
+@AllArgsConstructor
+@Getter
+public enum ResourceSourceEnum {
+    ZIYUAN("ZIYUAN","资源库"),
+    LOCAL("LOCAL","平台资源库"),
+    ;
+
+    private final String enKey;
+    private final String cnKey;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/RootNode.java b/src/main/java/com/yunhai/userbase/enums/RootNode.java
new file mode 100644
index 0000000..dac0df3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/RootNode.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2025/12/15 13:29
+ * @description 根目录树类型
+ */
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+public enum RootNode {
+
+    ZIYUANKU (1,"ZIYUAN","资源"),
+    TUTORING (2,"TUTORING","辅导"),
+    QUESTION (3,"QUESTION","题库"),
+    SHIJUAN (4,"SHIJUAN","试卷"),
+    ZHUANXIANG (5,"ZHUANXIANG","专项"),
+    ;
+
+    private Integer key;
+    private String enKey;
+    private String value;
+
+
+    public static RootNode getByKey(Integer key){
+        RootNode[] enums = RootNode.values();
+        Optional<RootNode> opt = Arrays.stream(enums).filter(item -> item.getKey().equals(key)).findAny();
+        if(opt.isPresent()){
+            return opt.get();
+        }else {
+            return null;
+        }
+    }
+
+    public static RootNode fromKey(Integer key) {
+        for (RootNode n : values()) if (n.key.equals(key)) return n;
+        throw new IllegalArgumentException("非法 RootNode key: " + key);
+    }
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/SchoolStage.java b/src/main/java/com/yunhai/userbase/enums/SchoolStage.java
new file mode 100644
index 0000000..512d41b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/SchoolStage.java
@@ -0,0 +1,66 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2025/12/15 15:55
+ * @description 学段
+ */
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+public enum SchoolStage {
+
+    PRIMARY (2,"PRIMARY","小学"),
+    MIDDLE (3,"MIDDLE","初中"),
+    HIGH (4,"HIGH","高中"),
+    ;
+
+    private Integer key;
+    private String enKey;
+    private String value;
+
+
+    public static SchoolStage getByKey(Integer key){
+        SchoolStage[] enums = SchoolStage.values();
+        Optional<SchoolStage> opt = Arrays.stream(enums).filter(item -> item.getKey().equals(key)).findAny();
+        if(opt.isPresent()){
+            return opt.get();
+        }else {
+            return null;
+        }
+    }
+
+    public static String getName(Integer key) {
+        for (SchoolStage stage : SchoolStage.values()) {
+            if (stage.getKey().equals(key)) {
+                return stage.getValue();
+            }
+        }
+        return null;
+    }
+
+
+    public static SchoolStage getByValue(String value) {
+        if (value == null || value.trim().isEmpty()) {
+            return null;
+        }
+        return Arrays.stream(values())
+                .filter(item -> item.getValue().equals(value))
+                .findAny()
+                .orElse(null);
+    }
+
+
+    public static SchoolStage fromKey(Integer key) {
+        for (SchoolStage n : values()) if (n.key.equals(key)) return n;
+        throw new IllegalArgumentException("非法 SchoolStage key: " + key);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/StatusEnum.java b/src/main/java/com/yunhai/userbase/enums/StatusEnum.java
new file mode 100644
index 0000000..fe5b7b3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/StatusEnum.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/07/13
+ * @description 通用启用禁用状态
+ */
+@Getter
+@AllArgsConstructor
+public enum StatusEnum implements IEnum<Integer> {
+
+    NORMAL(0, "正常"),
+    DISABLED(1, "禁用");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/enums/SysModeEnum.java b/src/main/java/com/yunhai/userbase/enums/SysModeEnum.java
new file mode 100644
index 0000000..fa19a8a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/SysModeEnum.java
@@ -0,0 +1,34 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/07/25
+ * @description 操作模式枚举（应用授权等场景：追加/覆盖/删除）
+ */
+@Getter
+@AllArgsConstructor
+public enum SysModeEnum implements IEnum<Integer> {
+
+    APPEND(0, "追加"),
+    OVERWRITE(1, "覆盖"),
+    DELETE(2, "删除");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/SysRoleEnum.java b/src/main/java/com/yunhai/userbase/enums/SysRoleEnum.java
new file mode 100644
index 0000000..0bb3c67
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/SysRoleEnum.java
@@ -0,0 +1,42 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/07/13
+ * @description 用户角色枚举
+ */
+@Getter
+@AllArgsConstructor
+public enum SysRoleEnum  implements IEnum<Integer>{
+
+    TEACHER(1, "老师"),
+    SCHOOL_LEADER(2, "校领导"),
+    STUDENT(3, "学生"),
+    PARENT(4, "家长"),
+    BUREAU_LEADER(5, "局领导"),
+    WORK_ACCOUNT(6, "工作号"),
+    ADMIN(7, "管理员");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/enums/SystemGrade.java b/src/main/java/com/yunhai/userbase/enums/SystemGrade.java
new file mode 100644
index 0000000..7bc5ac3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/SystemGrade.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * @ Description   :  java类作用描述
+ * @Author        :  cls
+ * @ CreateDate    :  2020/2/21 18:39
+ * @ Company       :  bestsch
+ */
+@AllArgsConstructor
+@NoArgsConstructor
+@Getter
+public enum SystemGrade {
+
+    one(1,"一年级",2),two(2,"二年级",2),
+    three(3,"三年级",2),four(4,"四年级",2),
+    five(5,"五年级",2),six(6,"六年级",2),
+    seven(7,"七年级",3),eight(8,"八年级",3),
+    nine(9,"九年级",3),ten(10,"高一",4),
+    eleven(11,"高二",4),twelve(12,"高三",4);
+
+    private Integer gradeId;
+    private String gradeName;
+    private Integer stage;
+
+    public static String getName(Integer gradeId) {
+        for (SystemGrade grade : SystemGrade.values()) {
+            if (grade.getGradeId().equals(gradeId)) {
+                return grade.gradeName;
+            }
+        }
+        return null;
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/UserType.java b/src/main/java/com/yunhai/userbase/enums/UserType.java
new file mode 100644
index 0000000..73c9e56
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/UserType.java
@@ -0,0 +1,28 @@
+package com.yunhai.userbase.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+
+/**
+ * @program: UserProfile
+ * @description: 用户类别
+ * @author: chenx
+ * @create: 2023-05-26 10:46
+ **/
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+public enum UserType {
+
+    TEACHER (1,"教师","Teacher"),
+    STUDENT (2,"学生","Student"),
+    ;
+
+    private Integer key;
+    private String value;
+    private String code;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/enums/UserTypeEnum.java b/src/main/java/com/yunhai/userbase/enums/UserTypeEnum.java
new file mode 100644
index 0000000..beb2653
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/enums/UserTypeEnum.java
@@ -0,0 +1,36 @@
+package com.yunhai.userbase.enums;
+
+import com.yunhai.platform.utils.enums.IEnum;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author chenx
+ * @date 2026/08/03
+ * @description 用户类型枚举
+ *   - NORMAL(0)      普通用户：默认类型
+ *   - SUPER_ADMIN(1) 超级管理员：系统内置种子账号（yunhaisch / yunhaisch2 / yunhaisch3），由初始化脚本写入
+ *   - SCHOOL_ADMIN(2) 学校管理员：拥有管理身份（角色含 ADMIN(7)）的普通账号（非超级管理员）
+ */
+@Getter
+@AllArgsConstructor
+public enum UserTypeEnum implements IEnum<Integer> {
+
+    NORMAL(0, "普通用户"),
+    SUPER_ADMIN(1, "超级管理员"),
+    SCHOOL_ADMIN(2, "学校管理员");
+
+    private Integer key;
+    private String value;
+
+    @Override
+    public Integer getKey() {
+        return this.key;
+    }
+
+    @Override
+    public String getValue() {
+        return this.value;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/event/ApplicationInfoCacheChangedEvent.java b/src/main/java/com/yunhai/userbase/event/ApplicationInfoCacheChangedEvent.java
new file mode 100644
index 0000000..ac0aabf
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/event/ApplicationInfoCacheChangedEvent.java
@@ -0,0 +1,45 @@
+package com.yunhai.userbase.event;
+
+import com.yunhai.userbase.entity.ApplicationInfo;
+import org.springframework.context.ApplicationEvent;
+
+/**
+ * 应用密钥/元数据变更事件：在 ApplicationInfoService 的 save/add/edit/delete/resetSecret 等事务内发布，
+ * 由 SignKeyCacheService 的 @TransactionalEventListener(phase = AFTER_COMMIT 订阅，
+ * 保证 DB 真正提交成功后再写共享 Redis / 清本地缓存，避免事务回滚导致的脏数据。
+ */
+public class ApplicationInfoCacheChangedEvent extends ApplicationEvent {
+
+    public enum Type {
+        UPSERT, DELETE
+    }
+
+    private final Type type;
+    private final Integer appKey;
+
+    /**
+     * 删除事件：appKey 必填；upsert 事件：可以传 entity 非空。
+     */
+    private final ApplicationInfo upsertEntity;
+
+    public ApplicationInfoCacheChangedEvent(Object source, Type type, Integer appKey, ApplicationInfo upsertEntity) {
+        super(source);
+        this.type = type;
+        this.appKey = appKey;
+        this.upsertEntity = upsertEntity;
+    }
+
+    public static ApplicationInfoCacheChangedEvent upsert(Object source, ApplicationInfo entity) {
+        return new ApplicationInfoCacheChangedEvent(source, Type.UPSERT, entity.getAppKey(), entity);
+    }
+
+    public static ApplicationInfoCacheChangedEvent delete(Object source, Integer appKey) {
+        return new ApplicationInfoCacheChangedEvent(source, Type.DELETE, appKey, null);
+    }
+
+    public Type getType() { return type; }
+
+    public Integer getAppKey() { return appKey; }
+
+    public ApplicationInfo getUpsertEntity() { return upsertEntity; }
+}
diff --git a/src/main/java/com/yunhai/userbase/event/DataSyncEvent.java b/src/main/java/com/yunhai/userbase/event/DataSyncEvent.java
new file mode 100644
index 0000000..267a2aa
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/event/DataSyncEvent.java
@@ -0,0 +1,30 @@
+package com.yunhai.userbase.event;
+
+import com.yunhai.userbase.model.push.PushInterfaceType;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 数据同步事件：组 / 用户变更后由 {@code SysGroupService}/{@code SysUserService} 在事务内 publish，
+ * {@code PushDispatcher} 用 {@code @TransactionalEventListener(AFTER_COMMIT)} 消费（事务提交后才推送，
+ * 推送失败不影响主业务）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class DataSyncEvent {
+
+    /** 接口类型，如 group/AddGroup */
+    private PushInterfaceType type;
+    /** 组事件携带的受影响组 id 列表 */
+    private List<Integer> groupIds;
+    /** 用户事件携带的受影响用户 id 列表 */
+    private List<Integer> userIds;
+    /** 组维度的关联事件（如删除用户=解除组关系）携带的组 id */
+    private Integer groupId;
+    /** 触发本次变更的 oapi 调用方 appKey；非 oapi 来源（如管理后台）为 null。
+     *  推送分发器据此回推时排除来源应用自身，避免收到自己的回声。 */
+    private Integer sourceAppKey;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/BaseDict.java b/src/main/java/com/yunhai/userbase/model/BaseDict.java
new file mode 100644
index 0000000..5873a5e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/BaseDict.java
@@ -0,0 +1,34 @@
+package com.yunhai.userbase.model;
+
+/**
+ * @program: QualityEvaluate
+ * @description: 系统字典类
+ * @author: chenx
+ * @create: 2023-05-15 17:17
+ **/
+public class BaseDict {
+    public Integer k;
+    public String v;
+
+
+    public int getK() {
+        return this.k;
+    }
+
+    public void setK(int k) {
+        this.k = k;
+    }
+
+    public String getV() {
+        return this.v;
+    }
+
+    public void setV(String v) {
+        this.v = v;
+    }
+
+    public BaseDict(Integer k, String v) {
+        this.k = k;
+        this.v = v;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/BasePageQuery.java b/src/main/java/com/yunhai/userbase/model/BasePageQuery.java
new file mode 100644
index 0000000..ca04263
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/BasePageQuery.java
@@ -0,0 +1,16 @@
+package com.yunhai.userbase.model;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/21 21:41
+ * @description
+ */
+@Data
+public class BasePageQuery {
+    private int pageIndex = 1;
+    private int pageSize = 10;
+    /** 通用模糊搜索关键词 */
+    private String keyword;
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/model/BasePageResult.java b/src/main/java/com/yunhai/userbase/model/BasePageResult.java
new file mode 100644
index 0000000..7e60ed1
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/BasePageResult.java
@@ -0,0 +1,39 @@
+package com.yunhai.userbase.model;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 统一分页响应外壳。<br>
+ * 由 Controller 层负责装配（见 {@link com.yunhai.userbase.utils.PageUtils#toResult}），
+ * Service 层仍返回 Spring Data 的 {@link org.springframework.data.domain.Page}，保持与传输协议解耦。<br>
+ *
+ * @author chenx
+ * @date 2026/7/21 21:40
+ * @description 统一分页响应外壳
+ */
+@Data
+public class BasePageResult<T> {
+    /** 总记录数 */
+    private int total;
+    /** 当前页数据 */
+    private List<T> content;
+    /** 当前页码（从 1 起，与 {@link BasePageQuery#getPageIndex()} 约定一致） */
+    private int pageIndex;
+    /** 每页条数 */
+    private int pageSize;
+    /** 总页数 */
+    private int totalPages;
+    /** 是否还有下一页 */
+    private boolean hasNext;
+
+    public BasePageResult(List<T> content, int total, int pageIndex, int pageSize, int totalPages, boolean hasNext) {
+        this.content = content;
+        this.total = total;
+        this.pageIndex = pageIndex;
+        this.pageSize = pageSize;
+        this.totalPages = totalPages;
+        this.hasNext = hasNext;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/BaseTree.java b/src/main/java/com/yunhai/userbase/model/BaseTree.java
new file mode 100644
index 0000000..f8f93cc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/BaseTree.java
@@ -0,0 +1,19 @@
+package com.yunhai.userbase.model;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+public class BaseTree {
+    public Integer id;
+    public String name;
+    public Integer pid ;
+    public Integer type;
+    public List<BaseTree> children;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/Excel/ExcelKnowledge.java b/src/main/java/com/yunhai/userbase/model/Excel/ExcelKnowledge.java
new file mode 100644
index 0000000..edc2d24
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/Excel/ExcelKnowledge.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.model.Excel;
+
+import cn.afterturn.easypoi.excel.annotation.Excel;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * @author chenx
+ * @date 2026/1/19 19:45
+ * @description 教材导入
+ */
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class ExcelKnowledge {
+
+    @Excel(name = "第一层", width = 20)
+    private String first;
+
+    @Excel(name = "第二层", width = 20)
+    private String second;
+
+    @Excel(name = "第三层", width =20)
+    private String third;
+
+    @Excel(name = "第四层", width = 20)
+    private String fourth;
+
+    @Excel(name = "第五层", width = 20)
+    private String five;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/Excel/ExcelResearchFill.java b/src/main/java/com/yunhai/userbase/model/Excel/ExcelResearchFill.java
new file mode 100644
index 0000000..68256ad
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/Excel/ExcelResearchFill.java
@@ -0,0 +1,28 @@
+package com.yunhai.userbase.model.Excel;
+
+import cn.afterturn.easypoi.excel.annotation.Excel;
+import lombok.Data;
+
+/**
+ * @program: ResearchLearn
+ * @description: 导入研学活动填报实体类
+ * @author: chenx
+ * @create: 2023-07-21 14:12
+ **/
+
+@Data
+public class ExcelResearchFill {
+
+    @Excel(name = "年级")
+    private String gradeName;
+
+    @Excel(name = "班级")
+    private String className;
+
+    @Excel(name = "姓名")
+    private String stuName;
+
+    @Excel(name = "研学/活动名称")
+    private String researchName;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/Page.java b/src/main/java/com/yunhai/userbase/model/Page.java
new file mode 100644
index 0000000..e58b366
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/Page.java
@@ -0,0 +1,72 @@
+package com.yunhai.userbase.model;
+
+import org.apache.commons.lang3.StringUtils;
+
+public class Page<U> {
+    private int current;
+    private int pageSize;
+    private long count;
+
+    public Page() {
+    }
+
+    public int getCurrent() {
+        return this.current;
+    }
+
+    public void setCurrent(int current) {
+        this.current = current;
+    }
+
+    public int getPageSize() {
+        return this.pageSize == 0 ? 10 : this.pageSize;
+    }
+
+    public void setPageSize(int pageSize) {
+        this.pageSize = pageSize;
+    }
+
+    public void setPageSize(String pageSize) {
+        if (!StringUtils.isEmpty(pageSize) && StringUtils.isNumeric(pageSize)) {
+            this.pageSize = Integer.valueOf(pageSize);
+        }
+
+    }
+
+    public long getCount() {
+        return this.count;
+    }
+
+    public void setCount(long count) {
+        this.count = count;
+    }
+
+
+
+    public int getPageCount() {
+        return this.getPageSize() != 0 ? (int)Math.ceil((double)this.count / (double)this.getPageSize()) : 0;
+    }
+
+    public int getStartIndex() {
+        return (this.getCurrent() - 1) * this.getPageSize();
+    }
+
+    public void setCurrent(String current) {
+        if (!StringUtils.isEmpty(current) && StringUtils.isNumeric(current)) {
+            this.current = Integer.valueOf(current);
+        }
+
+    }
+
+    public void setCount(String count) {
+        if (!StringUtils.isEmpty(count) && StringUtils.isNumeric(count)) {
+            this.count = Long.valueOf(count);
+        }
+
+    }
+
+    public int getEndIndex() {
+        return this.getStartIndex() + this.getPageSize();
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/StartEndDate.java b/src/main/java/com/yunhai/userbase/model/StartEndDate.java
new file mode 100644
index 0000000..94c1ea7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/StartEndDate.java
@@ -0,0 +1,16 @@
+package com.yunhai.userbase.model;
+
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.Date;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class StartEndDate {
+    private Date startDate;
+    private Date endDate;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/Tree.java b/src/main/java/com/yunhai/userbase/model/Tree.java
new file mode 100644
index 0000000..2523235
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/Tree.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.model;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+public class Tree {
+    private String label;
+    private String value;
+    private Integer type = 0;
+    private List<Tree> children;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzAppRow.java b/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzAppRow.java
new file mode 100644
index 0000000..15248e8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzAppRow.java
@@ -0,0 +1,37 @@
+package com.yunhai.userbase.model.appauthz;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 应用授权查询的扁平投影行（含 categoryId 供分组）。<br>
+ * 仅取授权列表所需字段，避免加载 appSecret 等无关大字段。<br>
+ *
+ * @author chenx
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class AppAuthzAppRow {
+
+    /**
+     * 应用类型ID（分组键）。<br>
+     */
+    private Integer categoryId;
+
+    /**
+     * 应用ID。<br>
+     */
+    private Integer id;
+
+    /**
+     * 应用名称。<br>
+     */
+    private String name;
+
+    /**
+     * 应用图标（pcIcon）。<br>
+     */
+    private String icon;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzCategoryVo.java b/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzCategoryVo.java
new file mode 100644
index 0000000..7021c9b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appauthz/AppAuthzCategoryVo.java
@@ -0,0 +1,48 @@
+package com.yunhai.userbase.model.appauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 应用授权视图：应用类型 + 该类型下的应用列表。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppAuthzCategoryVo {
+
+    /**
+     * 应用类型ID。<br>
+     */
+    private Integer id;
+
+    /**
+     * 应用类型名称。<br>
+     */
+    private String name;
+
+    /**
+     * 该类型下的应用列表。<br>
+     */
+    private List<AppItem> app = new ArrayList<>();
+
+    /**
+     * 授权用的应用精简项（id/name/icon）。<br>
+     */
+    @Data
+    public static class AppItem {
+
+        /**
+         * 应用ID。<br>
+         */
+        private Integer id;
+
+        /**
+         * 应用名称。<br>
+         */
+        private String name;
+
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryQuery.java b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryQuery.java
new file mode 100644
index 0000000..e0d659d
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryQuery.java
@@ -0,0 +1,13 @@
+package com.yunhai.userbase.model.appcategory;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 22:35
+ * @description
+ */
+@Data
+public class AppCategoryQuery {
+    private String name;
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryRequest.java b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryRequest.java
new file mode 100644
index 0000000..be296a3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryRequest.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase.model.appcategory;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 22:35
+ * @description
+ */
+@Data
+public class AppCategoryRequest {
+    @NotNull(groups = ValidationGroups.Update.class, message = "编辑时ID不能为空")
+    private Integer id;
+
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "类别名称不能为空")
+    private String name;
+
+    private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryVo.java b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryVo.java
new file mode 100644
index 0000000..65a2060
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appcategory/AppCategoryVo.java
@@ -0,0 +1,15 @@
+package com.yunhai.userbase.model.appcategory;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 22:35
+ * @description
+ */
+@Data
+public class AppCategoryVo {
+    private Integer id;
+    private String name;
+    private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoQuery.java b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoQuery.java
new file mode 100644
index 0000000..a78b759
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoQuery.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase.model.application;
+
+import lombok.Data;
+
+/**
+ * 应用信息查询条件。<br>
+ * 用于列表查询时封装前端传入的筛选参数。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class ApplicationInfoQuery {
+    /**
+     * 应用名称，用于模糊匹配。<br>
+     */
+    private String name;
+
+    /**
+     * 应用类别ID，用于精确筛选。<br>
+     */
+    private Integer categoryId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoRequest.java b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoRequest.java
new file mode 100644
index 0000000..99abc9a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoRequest.java
@@ -0,0 +1,76 @@
+package com.yunhai.userbase.model.application;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * 应用信息新增/修改入参。<br>
+ * 用于接收前端提交的应用数据，并按分组做参数校验。<br>
+ * 说明：appKey/appSecret 为系统生成字段，不在此入参中暴露。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class ApplicationInfoRequest {
+    /**
+     * 主键ID，编辑时必填。<br>
+     */
+    @NotNull(groups = ValidationGroups.Update.class, message = "编辑时ID不能为空")
+    private Integer id;
+
+    /**
+     * 应用名称，新增与编辑均必填。<br>
+     */
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "应用名称不能为空")
+    private String name;
+
+    /**
+     * 应用类别ID，新增与编辑均必填。<br>
+     */
+    @NotNull(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "应用类别不能为空")
+    private Integer categoryId;
+
+    /**
+     * 应用描述。<br>
+     */
+    private String desc;
+
+    /**
+     * 应用前端类型列表。<br>
+     */
+    private List<Integer> clients;
+
+    /**
+     * PC应用访问地址。<br>
+     */
+    private String pcUrl;
+
+    /**
+     * PC应用图标地址。<br>
+     */
+    private String pcIcon;
+
+    /**
+     * App访问地址（移动端主地址）。<br>
+     */
+    private String appUrl;
+
+    /**
+     * App应用图标地址。<br>
+     */
+    private String appIcon;
+
+    /**
+     * 公众号应用地址。<br>
+     */
+    private String officialAccountUrl;
+
+    /**
+     * 钉钉应用地址。<br>
+     */
+    private String dingtalkUrl;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoSortVo.java b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoSortVo.java
new file mode 100644
index 0000000..ddc0a93
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoSortVo.java
@@ -0,0 +1,34 @@
+package com.yunhai.userbase.model.application;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * 应用信息返回视图。<br>
+ * 用于接口返回给前端的应用数据。<br>
+ *
+ * @author chenx
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class ApplicationInfoSortVo {
+    /**
+     * 主键ID。<br>
+     */
+    private Integer id;
+
+    /**
+     * 应用名称。<br>
+     */
+    private String name;
+
+    /**
+     * 排序号，仅在同一个应用类型内有效；未排序时为 null。<br>
+     */
+    private Integer sortNo;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoVo.java b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoVo.java
new file mode 100644
index 0000000..5b669ef
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/ApplicationInfoVo.java
@@ -0,0 +1,84 @@
+package com.yunhai.userbase.model.application;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 应用信息返回视图。
+ * 用于接口返回给前端的应用数据。
+ *
+ * @author chenx
+ */
+@Data
+public class ApplicationInfoVo {
+    /**
+     * 主键ID。<br>
+     */
+    private Integer id;
+
+    /**
+     * 应用名称。<br>
+     */
+    private String name;
+
+    /**
+     * 应用类别ID。<br>
+     */
+    private Integer categoryId;
+
+    /**
+     * 排序号，仅在同一个应用类型内有效；未排序时为 null。<br>
+     */
+    private Integer sortNo;
+
+    /**
+     * 应用描述。<br>
+     */
+    private String desc;
+
+    /**
+     * 系统生成的唯一标识（appKey），整型，从100000起自增。<br>
+     */
+    private Integer appKey;
+
+    /**
+     * 密钥（appSecret），与数据库 app_secret 字段一致，字符串类型。<br>
+     */
+    private String appSecret;
+
+    /**
+     * 应用前端类型列表。<br>
+     */
+    private List<Integer> clients;
+
+    /**
+     * PC应用访问地址。<br>
+     */
+    private String pcUrl;
+
+    /**
+     * PC应用图标地址。<br>
+     */
+    private String pcIcon;
+
+    /**
+     * App访问地址。<br>
+     */
+    private String appUrl;
+
+    /**
+     * App应用图标地址。<br>
+     */
+    private String appIcon;
+
+    /**
+     * 公众号应用地址。<br>
+     */
+    private String officialAccountUrl;
+
+    /**
+     * 钉钉应用地址。<br>
+     */
+    private String dingtalkUrl;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/PushSettingRequest.java b/src/main/java/com/yunhai/userbase/model/application/PushSettingRequest.java
new file mode 100644
index 0000000..a6d58a4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/PushSettingRequest.java
@@ -0,0 +1,30 @@
+package com.yunhai.userbase.model.application;
+
+import lombok.Data;
+
+/**
+ * 保存应用推送设置请求（应用列表「推送设置」按钮提交）。<br>
+ * 所有字段均为可选更新：传 null 表示不修改该项。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushSettingRequest {
+
+    /** 推送外部接口地址（不含固定后缀） */
+    private String pushBaseUrl;
+    /** 推送总开关：0关 1开 */
+    private Integer pushEnabled;
+    /** 启用的接口路径，逗号分隔 */
+    private String pushEventTypes;
+    /** 关联学校组 id，逗号分隔；空=全局 */
+    private String pushSchoolIds;
+    /** 推送角色 key，逗号分隔；空=全部角色 */
+    private String pushRoleIds;
+    /**
+     * 推送签名密钥；传 null 表示不修改（保留现有值），
+     * 传空串 "" 表示清空（后续复用 appSecret）。
+     */
+    private String pushSecret;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/application/PushSettingVo.java b/src/main/java/com/yunhai/userbase/model/application/PushSettingVo.java
new file mode 100644
index 0000000..38ce68f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/application/PushSettingVo.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.application;
+
+import lombok.Data;
+
+/**
+ * 应用推送设置回显 VO（GetPushSetting 返回，仅含推送相关字段，不含 appSecret 等无关大字段）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushSettingVo {
+
+    private Integer id;
+    private Integer appKey;
+    private String name;
+    private String pushBaseUrl;
+    private Integer pushEnabled;
+    private String pushEventTypes;
+    private String pushSchoolIds;
+    private String pushRoleIds;
+    /** 推送签名密钥（可展示供复制；空=复用 appSecret） */
+    private String pushSecret;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleQuery.java b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleQuery.java
new file mode 100644
index 0000000..e16dc7c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleQuery.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.model.appmodule;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块查询条件。<br>
+ */
+@Data
+public class AppModuleQuery {
+    /** 所属应用ID（按应用过滤模块树）。<br> */
+    private Integer appId;
+    /** 模块名称（模糊匹配）。<br> */
+    private String name;
+    /** 父模块ID（传入则以该模块为根，递归返回其完整子树；不传则顶层只显示 level-1 根模块）。<br> */
+    private Integer parentId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleRequest.java b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleRequest.java
new file mode 100644
index 0000000..ff49dfd
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleRequest.java
@@ -0,0 +1,36 @@
+package com.yunhai.userbase.model.appmodule;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块请求体。<br>
+ */
+@Data
+public class AppModuleRequest {
+    @NotNull(groups = ValidationGroups.Update.class, message = "编辑时ID不能为空")
+    private Integer id;
+
+    /** 所属应用ID（创建时必填，创建后不可改）。<br> */
+    @NotNull(groups = ValidationGroups.Create.class, message = "所属应用不能为空")
+    private Integer appId;
+
+    /** 父模块ID；根模块传 null。<br> */
+    private Integer parentId;
+
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "模块名称不能为空")
+    private String name;
+
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "自定义ID不能为空")
+    private String customId;
+
+    /** 模块路径（前端路由/资源路径）。<br> */
+    private String path;
+
+    private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleVo.java b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleVo.java
new file mode 100644
index 0000000..85641b0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/appmodule/AppModuleVo.java
@@ -0,0 +1,25 @@
+package com.yunhai.userbase.model.appmodule;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块视图（树形，children 递归存放子模块）。<br>
+ */
+@Data
+public class AppModuleVo {
+    private Integer id;
+    private Integer appId;
+    private Integer parentId;
+    private String name;
+    private String customId;
+    private String path;
+    private Integer level;
+    private Integer sortNo;
+    /** 子模块（递归）；默认空列表，避免 JSON 序列化出现 null。 */
+    private List<AppModuleVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzAppVo.java b/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzAppVo.java
new file mode 100644
index 0000000..0d41d16
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzAppVo.java
@@ -0,0 +1,34 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 角色授权页应用节点视图：应用信息 + 其下模块权限树。<br>
+ * 普通角色只返回其所属应用；全应用角色返回系统全部应用。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppRoleAuthzAppVo {
+
+    /** 应用ID。 */
+    private Integer id;
+
+    /** 应用名称。 */
+    private String name;
+
+    /** 应用唯一标识 appKey。 */
+    private Integer appKey;
+
+    /** PC 应用图标地址。 */
+    private String pcIcon;
+
+    /** 排序号。 */
+    private Integer sortNo;
+
+    /** 该应用下的模块权限树（含勾选回显）。 */
+    private List<AppRoleAuthzModuleVo> modules = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzModuleVo.java b/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzModuleVo.java
new file mode 100644
index 0000000..1ece8da
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/AppRoleAuthzModuleVo.java
@@ -0,0 +1,42 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 角色授权页模块节点视图（树形）：模块信息 + 该角色勾选状态。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppRoleAuthzModuleVo {
+
+    /** 模块ID。 */
+    private Integer id;
+
+    /** 父模块ID；根模块为 null。 */
+    private Integer parentId;
+
+    /** 模块名称。 */
+    private String name;
+
+    /** 自定义ID（应用内唯一业务编码）。 */
+    private String customId;
+
+    /** 模块路径。 */
+    private String path;
+
+    /** 层级（根=1）。 */
+    private Integer level;
+
+    /** 排序号。 */
+    private Integer sortNo;
+
+    /** 该角色是否已勾选该模块（sys_app_role_module_rel 存在记录即勾选）。 */
+    private Boolean checked = Boolean.FALSE;
+
+    /** 子模块（递归）；默认空列表，避免 JSON 序列化出现 null。 */
+    private List<AppRoleAuthzModuleVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/AppRoleModuleAssignRequest.java b/src/main/java/com/yunhai/userbase/model/approle/AppRoleModuleAssignRequest.java
new file mode 100644
index 0000000..25949f8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/AppRoleModuleAssignRequest.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * 角色模块授权保存入参（全量覆盖）。<br>
+ * moduleIds 为该角色本次勾选的模块ID全量列表；传空列表即清空该角色全部模块授权。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppRoleModuleAssignRequest {
+
+    /**
+     * 角色ID。<br>
+     */
+    @NotNull(message = "角色ID不能为空")
+    private Integer roleId;
+
+    /**
+     * 勾选的模块ID全量列表。<br>
+     */
+    private List<Integer> moduleIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserBindRequest.java b/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserBindRequest.java
new file mode 100644
index 0000000..8a4b952
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserBindRequest.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * 角色绑定用户保存入参（全量覆盖，角色维度）。<br>
+ * userIds 为该角色本次绑定的用户ID全量列表；传空列表即解绑该角色全部用户。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppRoleUserBindRequest {
+
+    /**
+     * 角色ID。<br>
+     */
+    @NotNull(message = "角色ID不能为空")
+    private Integer roleId;
+
+    /**
+     * 绑定的用户ID全量列表。<br>
+     */
+    private List<Integer> userIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserVo.java b/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserVo.java
new file mode 100644
index 0000000..d6e66a9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/AppRoleUserVo.java
@@ -0,0 +1,21 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+/**
+ * 角色已绑定用户列表项视图。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class AppRoleUserVo {
+
+    /** 用户ID。 */
+    private Integer id;
+
+    /** 账号。 */
+    private String account;
+
+    /** 真实姓名。 */
+    private String realName;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleQuery.java b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleQuery.java
new file mode 100644
index 0000000..6f20bc3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleQuery.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+/**
+ * 业务角色列表查询条件。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class SysAppRoleQuery {
+
+    /** 角色名称（模糊匹配）。 */
+    private String name;
+
+    /** 所属应用ID（精确匹配，仅命中普通角色）。 */
+    private Integer appId;
+
+    /** 是否全应用角色。 */
+    private Boolean allAppFlag;
+
+    /** 是否禁用。 */
+    private Boolean disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleRequest.java b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleRequest.java
new file mode 100644
index 0000000..7140af5
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleRequest.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.model.approle;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+
+/**
+ * 业务角色新增/修改入参。<br>
+ * 普通角色：allAppFlag=false 且 appId 必填；全应用角色：allAppFlag=true 且 appId 必须为空（服务层校验）。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class SysAppRoleRequest {
+
+    /**
+     * 主键ID，编辑时必填。<br>
+     */
+    @NotNull(groups = ValidationGroups.Update.class, message = "编辑时ID不能为空")
+    private Integer id;
+
+    /**
+     * 角色名称，新增与编辑均必填。<br>
+     */
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "角色名称不能为空")
+    private String name;
+
+    /**
+     * 所属应用ID；普通角色必填，全应用角色必须为空（appId 与 allAppFlag 的匹配关系在服务层校验）。<br>
+     */
+    private Integer appId;
+
+    /**
+     * 是否全应用角色，新增与编辑均必填。<br>
+     */
+    @NotNull(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "角色类型不能为空")
+    private Boolean allAppFlag;
+
+    /**
+     * 角色备注。<br>
+     */
+    private String remark;
+
+    /**
+     * 是否禁用；空值按不禁用处理。<br>
+     */
+    private Boolean disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleVo.java b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleVo.java
new file mode 100644
index 0000000..b4826cb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/SysAppRoleVo.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+/**
+ * 业务角色列表项视图。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class SysAppRoleVo {
+
+    /** 角色ID。 */
+    private Integer id;
+
+    /** 角色名称。 */
+    private String name;
+
+    /** 所属应用ID；全应用角色为 null。 */
+    private Integer appId;
+
+    /** 所属应用名称；全应用角色为 null。 */
+    private String appName;
+
+    /** 是否全应用角色。 */
+    private Boolean allAppFlag;
+
+    /** 角色备注。 */
+    private String remark;
+
+    /** 是否禁用。 */
+    private Boolean disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/approle/UserAppRoleBindRequest.java b/src/main/java/com/yunhai/userbase/model/approle/UserAppRoleBindRequest.java
new file mode 100644
index 0000000..18e038e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/approle/UserAppRoleBindRequest.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.model.approle;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * 用户绑定角色保存入参（全量覆盖，用户维度）。<br>
+ * roleIds 为该用户本次绑定的角色ID全量列表；传空列表即解绑该用户全部角色。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class UserAppRoleBindRequest {
+
+    /**
+     * 用户ID。<br>
+     */
+    @NotNull(message = "用户ID不能为空")
+    private Integer userId;
+
+    /**
+     * 绑定的角色ID全量列表。<br>
+     */
+    private List<Integer> roleIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppAssignRequest.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppAssignRequest.java
new file mode 100644
index 0000000..7b63405
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppAssignRequest.java
@@ -0,0 +1,23 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 应用开通保存请求（功能1，全量覆盖式）。<br>
+ * 前端传递组ID与勾选的应用ID列表；appIds 为空或空列表代表取消该组全部应用开通。<br>
+ */
+@Data
+public class GroupAppAssignRequest {
+
+    /** 组ID。<br> */
+    @NotNull(message = "组ID不能为空")
+    private Integer groupId;
+
+    /** 勾选的应用ID列表（全量）；为空代表全部取消开通。<br> */
+    private List<Integer> appIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppVo.java
new file mode 100644
index 0000000..6a8b799
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAppVo.java
@@ -0,0 +1,30 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 应用开通视图（功能1）：系统全量应用 + 该组是否已开通。<br>
+ */
+@Data
+public class GroupAppVo {
+
+    /** 应用ID。<br> */
+    private Integer id;
+
+    /** 应用名称。<br> */
+    private String name;
+
+    /** 应用类别ID。<br> */
+    private Integer categoryId;
+
+    /** 应用唯一标识 appKey。<br> */
+    private Integer appKey;
+
+    /** PC应用图标地址。<br> */
+    private String pcIcon;
+
+    /** 该组是否已开通（用于复选框回显）。<br> */
+    private Boolean checked = Boolean.FALSE;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzAppVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzAppVo.java
new file mode 100644
index 0000000..c90d124
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzAppVo.java
@@ -0,0 +1,35 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组授权应用视图（功能2）：该组已开通的应用 + 其下模块权限树。<br>
+ */
+@Data
+public class GroupAuthzAppVo {
+
+    /** 应用ID。<br> */
+    private Integer id;
+
+    /** 应用名称。<br> */
+    private String name;
+
+    /** 应用唯一标识 appKey。<br> */
+    private Integer appKey;
+
+    /** PC应用图标地址。<br> */
+    private String pcIcon;
+
+    /** 应用类型ID；用于按应用分类分组展示组授权面板。<br> */
+    private Integer categoryId;
+
+    private Integer sortNo;
+
+    /** 该应用下的模块权限树；默认空列表，避免 JSON 序列化出现 null。 */
+    private List<GroupAuthzModuleVo> modules = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzCategoryVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzCategoryVo.java
new file mode 100644
index 0000000..515af61
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzCategoryVo.java
@@ -0,0 +1,25 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 组授权分类视图：按应用类型分组后，每个分类下挂载已开通的应用及其模块权限树。<br>
+ *
+ * @author chenx
+ * @date 2026/7/23
+ */
+@Data
+public class GroupAuthzCategoryVo {
+
+    /** 应用类型ID。 */
+    private Integer id;
+
+    /** 应用类型名称。 */
+    private String name;
+
+    /** 该分类下已开通的应用列表（含模块权限树）。 */
+    private List<GroupAuthzAppVo> apps = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzModuleVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzModuleVo.java
new file mode 100644
index 0000000..3bc34a0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupAuthzModuleVo.java
@@ -0,0 +1,45 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组授权模块节点视图（功能2，树形）：模块信息 + 该组勾选状态与子组继承开关。<br>
+ */
+@Data
+public class GroupAuthzModuleVo {
+
+    /** 模块ID。<br> */
+    private Integer id;
+
+    /** 父模块ID；根模块为 null。<br> */
+    private Integer parentId;
+
+    /** 模块名称。<br> */
+    private String name;
+
+    /** 自定义ID（应用内唯一业务编码）。<br> */
+    private String customId;
+
+    /** 模块路径。<br> */
+    private String path;
+
+    /** 层级（根=1）。<br> */
+    private Integer level;
+
+    /** 排序号。<br> */
+    private Integer sortNo;
+
+    /** 该组是否已勾选该模块（sys_group_module_perm 存在记录即勾选）。<br> */
+    private Boolean checked = Boolean.FALSE;
+
+    /** 是否子组继承（仅 checked=true 时有意义）。<br> */
+    private Boolean inheritFlag = Boolean.FALSE;
+
+    /** 子模块（递归）；默认空列表，避免 JSON 序列化出现 null。 */
+    private List<GroupAuthzModuleVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModuleAuthzItem.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModuleAuthzItem.java
new file mode 100644
index 0000000..ef3b2c4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModuleAuthzItem.java
@@ -0,0 +1,47 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * 组模块授权单项（增量式：对某个组的「某应用下的某模块」做追加/删除）。<br>
+ * 与 GroupModulePermRequest（全量覆盖式 SaveModulePerms）互为补充：本类用于单条/批量增量操作，<br>
+ * 由前端「组授权」面板逐条勾选或取消时提交。<br>
+ * <br>
+ * 字段语义（务必与前端对齐）：<br>
+ * - groupId：目标组ID<br>
+ * - appId：应用ID（被授权的模块必须属于该应用，越权写别的应用的模块会被拒绝）<br>
+ * - moduleId：模块ID；传 0 表示「该应用下的全部模块」（前端勾选应用根/整应用时用）<br>
+ * - mode：操作模式，取值见 SysModeEnum —— 0=追加(APPEND，授予授权) / 2=删除(DELETE，取消授权)；1=覆盖 不适用于单条增量，会被拒绝<br>
+ * - isAll：是否对子组继承，直接映射现有 sys_group_module_perm.inherit_flag 列 —— 1=子孙组自动继承 / 0=仅本组生效<br>
+ *
+ * @author chenx
+ */
+@Data
+public class GroupModuleAuthzItem {
+
+    /** 目标组ID。 */
+    @NotNull(message = "组ID不能为空")
+    private Integer groupId;
+
+    /** 应用ID（模块必须属于该应用）。 */
+    @NotNull(message = "应用ID不能为空")
+    private Integer appId;
+
+    /**
+     * 模块ID；传 0 表示「该应用下全部模块」。<br>
+     * 注意：后端不会向 sys_group_module_perm 写入 module_id=0 的伪记录，<br>
+     * 而是把 0 展开为应用下每个真实模块各写一条权限记录。
+     */
+    @NotNull(message = "模块ID不能为空（整应用传 0）")
+    private Integer moduleId;
+
+    /** 操作模式：0=追加 / 2=删除（1=覆盖不适用）。 */
+    @NotNull(message = "操作模式不能为空（0=追加/2=删除）")
+    private Integer mode;
+
+    /** 是否对子组继承：1=子孙组继承 / 0=仅本组。映射 inherit_flag。 */
+    @NotNull(message = "isAll不能为空（0=仅本组/1=子组继承）")
+    private Integer isAll;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModulePermRequest.java b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModulePermRequest.java
new file mode 100644
index 0000000..33a4202
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/GroupModulePermRequest.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组授权保存请求（功能2，全量覆盖式）。<br>
+ * perms 为该组当前勾选的模块权限全量列表：有旧记录则更新 inheritFlag，无则新增，<br>
+ * 不在列表中的旧记录物理删除（即取消勾选）。<br>
+ */
+@Data
+public class GroupModulePermRequest {
+
+    /** 组ID。<br> */
+    @NotNull(message = "组ID不能为空")
+    private Integer groupId;
+
+    /** 勾选的模块权限全量列表；为空代表全部取消勾选。<br> */
+    @Valid
+    private List<ModulePermItem> perms;
+
+    /** 单个模块权限项。<br> */
+    @Data
+    public static class ModulePermItem {
+
+        /** 模块ID。<br> */
+        @NotNull(message = "模块ID不能为空")
+        private Integer moduleId;
+
+        /** 是否子组继承；不传默认 false。<br> */
+        private Boolean inheritFlag;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/SchoolAppAuthzRequest.java b/src/main/java/com/yunhai/userbase/model/groupauthz/SchoolAppAuthzRequest.java
new file mode 100644
index 0000000..af3d91c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/SchoolAppAuthzRequest.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * 学校组应用授权增量请求（对应前端点击单个应用多选框勾选/取消时提交）。<br>
+ * 与 {@link GroupAppAssignRequest}（全量覆盖式 AssignApps）互为补充：本类用于「单条」增量开通或取消应用，<br>
+ * 前端一次只传一个应用ID（逐次点击触发），因此 appid 为单个 Integer，而非集合/逗号串。<br>
+ * <br>
+ * 字段语义（务必与前端对齐）：<br>
+ * - schid：目标学校组ID（即左侧树点击的 nodeId）<br>
+ * - appid：单个应用ID（每次只传一个）<br>
+ * - mode：操作模式，取值见 SysModeEnum —— 0=追加(APPEND，开通应用) / 2=删除(DELETE，取消开通)；1=覆盖 不适用于单条增量，会被拒绝<br>
+ * <br>
+ * <b>设计说明</b>：每次请求只携带一个 appid，控制器/服务均不再做多值解析；逐次点击即多次提交。
+ *
+ * @author chenx
+ */
+@Data
+public class SchoolAppAuthzRequest {
+
+    /** 目标学校组ID（左侧树节点 nodeId）。 */
+    @NotNull(message = "组ID不能为空")
+    private Integer schid;
+
+    /**
+     * 单个应用ID。<br>
+     * 前端逐次点击应用多选框触发，每次只传一个应用ID，故为 Integer 而非集合/字符串。
+     */
+    @NotNull(message = "应用ID不能为空")
+    private Integer appid;
+
+    /** 操作模式：0=追加 / 2=删除（1=覆盖不适用）。 */
+    @NotNull(message = "操作模式不能为空（0=追加/2=删除）")
+    private Integer mode;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserGroupNodeVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserGroupNodeVo.java
new file mode 100644
index 0000000..5212e4f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserGroupNodeVo.java
@@ -0,0 +1,29 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 权限一览：用户所属部门树节点（左侧上方「所属部门」区域）。<br>
+ * 树仅由「用户直接归属的组 + 其全部祖先组」构成（如：云平台-学校中学-语文组），
+ * 不包含无关的兄弟/子孙节点。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class UserGroupNodeVo {
+
+    /** 组ID。 */
+    private Integer id;
+
+    /** 组名称。 */
+    private String name;
+
+    /** 是否用户直接归属的组（叶子高亮用）；祖先组为 false。 */
+    private Boolean own;
+
+    /** 子节点（仅含祖先链上的节点）。 */
+    private List<UserGroupNodeVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionAppVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionAppVo.java
new file mode 100644
index 0000000..23a1394
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionAppVo.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 权限一览：用户已授权应用节点。<br>
+ * 父节点为 {@link UserPermissionCategoryVo}，子节点为 {@link UserPermissionModuleVo}。
+ */
+@Data
+public class UserPermissionAppVo {
+
+    /** 应用ID。 */
+    private Integer id;
+
+    /** 应用名称。 */
+    private String name;
+
+    /** 应用唯一标识 appKey。 */
+    private Integer appKey;
+
+    /** PC 应用图标地址。 */
+    private String pcIcon;
+
+    /** 排序号。 */
+    private Integer sortNo;
+
+    /** 该应用下已授权的模块树。 */
+    private List<UserPermissionModuleVo> modules = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionCategoryVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionCategoryVo.java
new file mode 100644
index 0000000..360e92f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionCategoryVo.java
@@ -0,0 +1,26 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 权限一览：用户已授权应用分类节点。<br>
+ * 一级子节点为 {@link UserPermissionAppVo}。
+ */
+@Data
+public class UserPermissionCategoryVo {
+
+    /** 分类ID。 */
+    private Integer id;
+
+    /** 分类名称。 */
+    private String name;
+
+    /** 排序号。 */
+    private Integer sortNo;
+
+    /** 该分类下已授权的应用列表。 */
+    private List<UserPermissionAppVo> apps = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionModuleVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionModuleVo.java
new file mode 100644
index 0000000..50edcc8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionModuleVo.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 权限一览：用户已授权模块节点（递归树）。<br>
+ * 仅包含有权限的模块，无权限的模块及其子节点均不显示。
+ */
+@Data
+public class UserPermissionModuleVo {
+
+    /** 模块ID。 */
+    private Integer id;
+
+    /** 父模块ID；根模块为 null。 */
+    private Integer parentId;
+
+    /** 模块名称。 */
+    private String name;
+
+    /** 自定义ID（应用内唯一业务编码）。 */
+    private String customId;
+
+    /** 模块路径。 */
+    private String path;
+
+    /** 层级（根=1）。 */
+    private Integer level;
+
+    /** 排序号。 */
+    private Integer sortNo;
+
+    /** 子模块（递归）。 */
+    private List<UserPermissionModuleVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionUserVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionUserVo.java
new file mode 100644
index 0000000..4ec8fb0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserPermissionUserVo.java
@@ -0,0 +1,25 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+/**
+ * 权限一览：用户列表项（组下用户或全局搜索用户）。<br>
+ */
+@Data
+public class UserPermissionUserVo {
+
+    /** 用户ID。 */
+    private Integer id;
+
+    /** 账号。 */
+    private String account;
+
+    /** 真实姓名。 */
+    private String realName;
+
+    /** 是否主归属：1=本职主学校/部门，0=兼职兼任。 */
+    private Integer isMain;
+
+    /** 用户所属部门/组织路径，如 /上海市仙霞高级中学/教师/行政。 */
+    private String groupPath;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/groupauthz/UserRoleVo.java b/src/main/java/com/yunhai/userbase/model/groupauthz/UserRoleVo.java
new file mode 100644
index 0000000..7e5adc8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/groupauthz/UserRoleVo.java
@@ -0,0 +1,30 @@
+package com.yunhai.userbase.model.groupauthz;
+
+import lombok.Data;
+
+/**
+ * 权限一览：用户所属业务角色列表项（中间下方「所属角色」区域）。<br>
+ *
+ * @author chenx
+ */
+@Data
+public class UserRoleVo {
+
+    /** 角色ID。 */
+    private Integer id;
+
+    /** 角色名称。 */
+    private String name;
+
+    /** 是否全应用角色。 */
+    private Boolean allAppFlag;
+
+    /** 所属应用ID；全应用角色为 null。 */
+    private Integer appId;
+
+    /** 所属应用名称；全应用角色为 null。 */
+    private String appName;
+
+    /** 是否禁用（禁用角色仍展示，但不参与权限计算）。 */
+    private Boolean disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/identity/IdentityCurrentVo.java b/src/main/java/com/yunhai/userbase/model/identity/IdentityCurrentVo.java
new file mode 100644
index 0000000..60adcaa
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/identity/IdentityCurrentVo.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.model.identity;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 当前激活身份（来自 {@code sys_user_current_role}；无切换记录时兜底主身份）。<br>
+ *
+ * @author chenx
+ * @date 2026/8/18
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class IdentityCurrentVo {
+
+    /** 当前激活角色ID（SysRoleEnum.key） */
+    private Integer roleId;
+
+    /** 当前激活角色名 */
+    private String roleName;
+
+    /** 当前激活学校ID（=学校组 sys_group.id；无学校时为 0） */
+    private Integer schoolId;
+
+    /** 当前激活学校名 */
+    private String schoolName;
+
+    /** 是否兜底（无主动切换记录时为 true，提示前端可引导用户显式切换） */
+    private Boolean fallback;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/identity/IdentityOptionVo.java b/src/main/java/com/yunhai/userbase/model/identity/IdentityOptionVo.java
new file mode 100644
index 0000000..c06e657
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/identity/IdentityOptionVo.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.model.identity;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 用户可选身份（一条 = 某学校下的某平台角色）。<br>
+ * 数据源：{@code sys_user_role_rel}（平台身份角色权威源）。<br>
+ *
+ * @author chenx
+ * @date 2026/8/18
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class IdentityOptionVo {
+
+    /** 角色ID（SysRoleEnum.key，1-7） */
+    private Integer roleId;
+
+    /** 角色名（老师/校领导/学生…，查枚举快取） */
+    private String roleName;
+
+    /** 学校ID（=学校组 sys_group.id；区域/学段/直属无学校时为 0） */
+    private Integer schoolId;
+
+    /** 学校名（冗余，免 join sys_group） */
+    private String schoolName;
+
+    /** 是否主身份（isMain=1） */
+    private Boolean isMain;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/identity/IdentitySwitchRequest.java b/src/main/java/com/yunhai/userbase/model/identity/IdentitySwitchRequest.java
new file mode 100644
index 0000000..f7f88d7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/identity/IdentitySwitchRequest.java
@@ -0,0 +1,25 @@
+package com.yunhai.userbase.model.identity;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * 切换身份入参：指定目标学校与该学校下的角色。<br>
+ * 服务端校验 (userId, roleId, schoolId) 在 {@code sys_user_role_rel} 中存在且正常态，<br>
+ * 不存在则拒绝（防止越权切换到非授权身份）。<br>
+ *
+ * @author chenx
+ * @date 2026/8/18
+ */
+@Data
+public class IdentitySwitchRequest {
+
+    /** 目标角色ID（SysRoleEnum.key） */
+    @NotNull(message = "角色ID不能为空")
+    private Integer roleId;
+
+    /** 目标学校ID（=学校组 sys_group.id；无学校维度传 0） */
+    @NotNull(message = "学校ID不能为空")
+    private Integer schoolId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogListVo.java b/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogListVo.java
new file mode 100644
index 0000000..37a5acd
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogListVo.java
@@ -0,0 +1,82 @@
+package com.yunhai.userbase.model.oapilog;
+
+import com.alibaba.fastjson.annotation.JSONField;
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 开放接口日志列表项视图。<br>
+ * 不含 response_data（响应结果），列表不展示，需通过下载接口单独获取。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Data
+public class SysOapiLogListVo {
+
+    /** 主键 */
+    private Long id;
+    /** 日志级别 1-重要 2-次要 3-一般 */
+    private Integer logLevel;
+    /** 调用方应用 appKey */
+    private Integer callerAppKey;
+    /** 调用方应用名 */
+    private String callerAppName;
+    /** 请求IP */
+    private String requestIp;
+    /** 请求路径 */
+    private String requestUri;
+    /** 请求方法 GET/POST/PUT/DELETE */
+    private String requestMethod;
+    /** 操作类型 DELETE/CREATE/UPDATE/QUERY */
+    private String operationType;
+    /** 类名.方法名 */
+    private String classMethod;
+    /** 操作描述 */
+    private String operationDesc;
+    /** 请求参数JSON（脱敏后） */
+    private String requestParams;
+    /** 响应结果（GZIP 解压后原文，脱敏后；随列表带出，详情弹窗直接展示） */
+    private String responseData;
+    /** HTTP 状态码 */
+    private Integer statusCode;
+    /** 耗时(ms) */
+    private Long costTime;
+    /** 调用方UA */
+    private String userAgent;
+    /** 错误信息 */
+    private String errorMsg;
+    /** 调用时间 */
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime createTime;
+
+    /**
+     * 全参构造，顺序需与 {@code SysOapiLog} 的列表投影字段一致。<br>
+     * 用于 JPA Criteria {@code cb.construct} 投影查询。<br>
+     */
+    public SysOapiLogListVo(Long id, Integer logLevel, Integer callerAppKey, String callerAppName,
+                            String requestIp, String requestUri, String requestMethod,
+                            String operationType, String classMethod, String operationDesc,
+                            String requestParams, Integer statusCode, Long costTime,
+                            String userAgent, String errorMsg, LocalDateTime createTime) {
+        this.id = id;
+        this.logLevel = logLevel;
+        this.callerAppKey = callerAppKey;
+        this.callerAppName = callerAppName;
+        this.requestIp = requestIp;
+        this.requestUri = requestUri;
+        this.requestMethod = requestMethod;
+        this.operationType = operationType;
+        this.classMethod = classMethod;
+        this.operationDesc = operationDesc;
+        this.requestParams = requestParams;
+        this.statusCode = statusCode;
+        this.costTime = costTime;
+        this.userAgent = userAgent;
+        this.errorMsg = errorMsg;
+        this.createTime = createTime;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogQuery.java b/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogQuery.java
new file mode 100644
index 0000000..cfbad9b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/oapilog/SysOapiLogQuery.java
@@ -0,0 +1,59 @@
+package com.yunhai.userbase.model.oapilog;
+
+import lombok.Data;
+
+import org.springframework.format.annotation.DateTimeFormat;
+
+import java.time.LocalDateTime;
+
+/**
+ * 开放接口日志查询条件。<br>
+ * 覆盖调用方应用、URI、级别、IP、时间等高频查询场景，与表索引前缀对齐。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Data
+public class SysOapiLogQuery {
+
+    /** 日志级别（1-重要 2-次要 3-一般） */
+    private Integer logLevel;
+
+    /** 调用方应用 appKey（等值） */
+    private Integer callerAppKey;
+
+    /** 调用方应用名（模糊） */
+    private String callerAppName;
+
+    /** 请求路径（模糊） */
+    private String requestUri;
+
+    /** 请求IP（模糊） */
+    private String requestIp;
+
+    /** 操作类型 DELETE/CREATE/UPDATE/QUERY */
+    private String operationType;
+
+    /** HTTP 状态码 */
+    private Integer statusCode;
+
+    /**
+     * 成功/失败筛选。<br>
+     * true=仅 HTTP 200（成功），false=非 200（失败）。
+     */
+    private Boolean success;
+
+    /**
+     * 关键字，同时匹配请求路径（requestUri）与应用名（callerAppName）。<br>
+     * 前端单输入框搜索这两个字段。
+     */
+    private String keyword;
+
+    /** 调用起始时间（含） */
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime startTime;
+
+    /** 调用结束时间（含） */
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime endTime;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogListVo.java b/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogListVo.java
new file mode 100644
index 0000000..c731bfc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogListVo.java
@@ -0,0 +1,77 @@
+package com.yunhai.userbase.model.oplog;
+
+import com.alibaba.fastjson.annotation.JSONField;
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 操作日志列表项视图。<br>
+ * 不含 response_data（响应结果），列表不展示，需通过下载接口单独获取。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Data
+public class SysOperationLogListVo {
+
+    /** 主键 */
+    private Long id;
+    /** 日志级别 1-重要 2-次要 3-一般 */
+    private Integer logLevel;
+    /** 操作用户ID */
+    private Long userId;
+    /** 操作用户名 */
+    private String username;
+    /** 请求IP */
+    private String requestIp;
+    /** 请求路径 */
+    private String requestUri;
+    /** 请求方法 GET/POST/PUT/DELETE */
+    private String requestMethod;
+    /** 操作类型 DELETE/CREATE/UPDATE/QUERY */
+    private String operationType;
+    /** 类名.方法名 */
+    private String classMethod;
+    /** 请求参数JSON */
+    private String requestParams;
+    /** HTTP 状态码 */
+    private Integer statusCode;
+    /** 耗时(ms) */
+    private Long costTime;
+    /** 浏览器UA */
+    private String userAgent;
+    /** 错误信息 */
+    private String errorMsg;
+    /** 操作时间 */
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime createTime;
+
+    /**
+     * 全参构造，顺序需与 {@code SysOperationLog} 的列表投影字段一致。<br>
+     * 用于 JPA Criteria {@code cb.construct} 投影查询。<br>
+     */
+    public SysOperationLogListVo(Long id, Integer logLevel, Long userId, String username,
+                                 String requestIp, String requestUri, String requestMethod,
+                                 String operationType, String classMethod, String requestParams,
+                                 Integer statusCode, Long costTime, String userAgent,
+                                 String errorMsg, LocalDateTime createTime) {
+        this.id = id;
+        this.logLevel = logLevel;
+        this.userId = userId;
+        this.username = username;
+        this.requestIp = requestIp;
+        this.requestUri = requestUri;
+        this.requestMethod = requestMethod;
+        this.operationType = operationType;
+        this.classMethod = classMethod;
+        this.requestParams = requestParams;
+        this.statusCode = statusCode;
+        this.costTime = costTime;
+        this.userAgent = userAgent;
+        this.errorMsg = errorMsg;
+        this.createTime = createTime;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogQuery.java b/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogQuery.java
new file mode 100644
index 0000000..ca67306
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/oplog/SysOperationLogQuery.java
@@ -0,0 +1,59 @@
+package com.yunhai.userbase.model.oplog;
+
+import lombok.Data;
+
+import org.springframework.format.annotation.DateTimeFormat;
+
+import java.time.LocalDateTime;
+
+/**
+ * 操作日志查询条件。<br>
+ * 覆盖时间、用户、URI、级别、IP 等高频查询场景，与表索引前缀对齐。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Data
+public class SysOperationLogQuery {
+
+    /** 日志级别（1-重要 2-次要 3-一般） */
+    private Integer logLevel;
+
+    /** 操作用户ID */
+    private Long userId;
+
+    /** 操作用户名（模糊） */
+    private String username;
+
+    /** 请求路径（模糊） */
+    private String requestUri;
+
+    /** 请求IP（模糊） */
+    private String requestIp;
+
+    /** 操作类型 DELETE/CREATE/UPDATE/QUERY */
+    private String operationType;
+
+    /** HTTP 状态码 */
+    private Integer statusCode;
+
+    /**
+     * 成功/失败筛选。<br>
+     * true=仅 HTTP 200（成功），false=非 200（失败）。
+     */
+    private Boolean success;
+
+    /**
+     * 关键字，同时匹配接口名称（requestUri）与用户名（username）。<br>
+     * 前端单输入框搜索这两个字段。
+     */
+    private String keyword;
+
+    /** 操作起始时间（含） */
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime startTime;
+
+    /** 操作结束时间（含） */
+    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime endTime;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/other/OperationDetailsModel.java b/src/main/java/com/yunhai/userbase/model/other/OperationDetailsModel.java
new file mode 100644
index 0000000..c0f146b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/other/OperationDetailsModel.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.model.other;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * @program: UserProfile
+ * @description: 接口日志操作应用详情
+ * @author: chenx
+ * @create: 2024-07-05 12:34
+ **/
+
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+public class OperationDetailsModel {
+
+    private Integer id;//应用id
+    private String name;//应用名称
+    private Long time;//requestTime
+    private String url;
+    private String errorMsg;
+
+    @JsonIgnore
+    private Integer indicatorId;
+    @JsonIgnore
+    private String resultMsg;
+    @JsonIgnore
+    private Double computeScore;//计算后的分数
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/other/SchLenGradeModel.java b/src/main/java/com/yunhai/userbase/model/other/SchLenGradeModel.java
new file mode 100644
index 0000000..a41d539
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/other/SchLenGradeModel.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase.model.other;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2025/12/25 21:28
+ * @description 学校学制年级实体
+ */
+
+@Data
+public class SchLenGradeModel {
+    private Integer gradeId;
+    private String gradeName;
+    private Integer stage;
+
+    public SchLenGradeModel(Integer gradeId, String gradeName, Integer stage) {
+        this.gradeId = gradeId;
+        this.gradeName = gradeName;
+        this.stage = stage;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/other/SchLenLevelModel.java b/src/main/java/com/yunhai/userbase/model/other/SchLenLevelModel.java
new file mode 100644
index 0000000..fc11539
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/other/SchLenLevelModel.java
@@ -0,0 +1,19 @@
+package com.yunhai.userbase.model.other;
+
+import com.yunhai.userbase.enums.SchoolStage;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2025/12/25 17:44
+ * @description 学校学段学制年级实体
+ */
+
+@Data
+public class SchLenLevelModel {
+    private SchoolStage stage;
+    private List<SchLenGradeModel> grades;
+}
+
diff --git a/src/main/java/com/yunhai/userbase/model/other/UserInfoModel.java b/src/main/java/com/yunhai/userbase/model/other/UserInfoModel.java
new file mode 100644
index 0000000..a158910
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/other/UserInfoModel.java
@@ -0,0 +1,26 @@
+package com.yunhai.userbase.model.other;
+
+import com.yunhai.userbase.enums.UserType;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * @program: UserProfile
+ * @description: 用户信息
+ * @author: chenx
+ * @create: 2024-07-09 17:30
+ **/
+
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+public class UserInfoModel {
+
+    private Integer userId;
+    private String userName;
+    private Integer schId;
+    private Integer groupId;
+    private String photo;
+    private UserType userType;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushInterfaceType.java b/src/main/java/com/yunhai/userbase/model/push/PushInterfaceType.java
new file mode 100644
index 0000000..61b45f7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushInterfaceType.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.model.push;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 文档约定的 8 个订阅接口：path（固定后缀，拼在订阅方 base URL 后）↔ 友好名 label。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Getter
+@AllArgsConstructor
+public enum PushInterfaceType {
+
+    SYNC_GROUP("group/SyncGroup", "组全量同步"),
+    SYNC_USER("user/SyncUser", "用户全量同步"),
+    ADD_GROUP("group/AddGroup", "添加组"),
+    UPDATE_GROUP("group/UpdateGroup", "更新组"),
+    DELETE_GROUP("group/DeleteGroup", "删除组"),
+    ADD_USER("user/AddUser", "添加用户"),
+    UPDATE_USER("user/UpdateUser", "更新用户"),
+    DELETE_USER("user/DeleteUser", "删除用户");
+
+    private final String path;
+    private final String label;
+
+    public static PushInterfaceType getByPath(String path) {
+        if (path == null) {
+            return null;
+        }
+        for (PushInterfaceType type : values()) {
+            if (type.path.equals(path)) {
+                return type;
+            }
+        }
+        return null;
+    }
+
+    /** 是否为组相关接口。 */
+    public boolean isGroup() {
+        return path.startsWith("group/");
+    }
+
+    /** 是否为用户相关接口。 */
+    public boolean isUser() {
+        return path.startsWith("user/");
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushRecordEntity.java b/src/main/java/com/yunhai/userbase/model/push/PushRecordEntity.java
new file mode 100644
index 0000000..9017d6a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushRecordEntity.java
@@ -0,0 +1,74 @@
+package com.yunhai.userbase.model.push;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import org.hibernate.annotations.CreationTimestamp;
+
+import javax.persistence.*;
+import java.time.LocalDateTime;
+
+/**
+ * 推送订阅记录实体（订阅方维度，落库用于日志 / 重试 / 排查）。<br>
+ * 与 DDL（push_subscription_ddl.sql §2）的 push_record 表一一对应。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+@NoArgsConstructor
+@Entity
+@Table(name = "push_record")
+public class PushRecordEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "subscriber_app_key", nullable = false)
+    private Integer subscriberAppKey;
+
+    @Column(name = "app_name")
+    private String appName;
+
+    @Column(name = "interface_path", nullable = false)
+    private String interfacePath;
+
+    @Column(name = "interface_label")
+    private String interfaceLabel;
+
+    @Column(name = "request_url", nullable = false)
+    private String requestUrl;
+
+    @Column(name = "payload", columnDefinition = "MEDIUMTEXT")
+    private String payload;
+
+    @Column(name = "sign_t")
+    private String signT;
+
+    @Column(name = "http_status")
+    private Integer httpStatus;
+
+    @Column(name = "resp_code")
+    private Integer respCode;
+
+    @Column(name = "resp_msg")
+    private String respMsg;
+
+    /** 是否成功：0失败 1成功 */
+    @Column(name = "success", nullable = false)
+    private Integer success = 0;
+
+    @Column(name = "attempt_no", nullable = false)
+    private Integer attemptNo = 1;
+
+    @Column(name = "cost_ms")
+    private Integer costMs;
+
+    /** 触发类型：manual / auto / retry */
+    @Column(name = "trigger_type")
+    private String triggerType;
+
+    @CreationTimestamp
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushRecordListVo.java b/src/main/java/com/yunhai/userbase/model/push/PushRecordListVo.java
new file mode 100644
index 0000000..41e13db
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushRecordListVo.java
@@ -0,0 +1,74 @@
+package com.yunhai.userbase.model.push;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 推送记录列表项视图。<br>
+ * 不含 payload（请求体原文），列表不展示，需通过下载接口单独获取，避免全量推送时数据量过大。<br>
+ *
+ * @author chenx
+ * @date 2026/8/17
+ */
+@Data
+public class PushRecordListVo {
+
+    /** 主键 */
+    private Long id;
+    /** 订阅方 appKey */
+    private Integer subscriberAppKey;
+    /** 应用名称 */
+    private String appName;
+    /** 接口路径，如 group/SyncGroup */
+    private String interfacePath;
+    /** 接口中文标签 */
+    private String interfaceLabel;
+    /** 请求地址 */
+    private String requestUrl;
+    /** 签名时间 t */
+    private String signT;
+    /** HTTP 状态码 */
+    private Integer httpStatus;
+    /** 业务码 */
+    private Integer respCode;
+    /** 业务消息 */
+    private String respMsg;
+    /** 是否成功：0失败 1成功 */
+    private Integer success;
+    /** 重试次数 */
+    private Integer attemptNo;
+    /** 耗时(ms) */
+    private Integer costMs;
+    /** 触发类型：manual / auto / retry */
+    private String triggerType;
+    /** 创建时间 */
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime createdAt;
+
+    /**
+     * 全参构造，顺序需与 {@code PushRecordEntity} 的列表投影字段一致。<br>
+     * 用于 JPA Criteria {@code cb.construct} 投影查询。
+     */
+    public PushRecordListVo(Long id, Integer subscriberAppKey, String appName, String interfacePath,
+                            String interfaceLabel, String requestUrl, String signT, Integer httpStatus,
+                            Integer respCode, String respMsg, Integer success, Integer attemptNo,
+                            Integer costMs, String triggerType, LocalDateTime createdAt) {
+        this.id = id;
+        this.subscriberAppKey = subscriberAppKey;
+        this.appName = appName;
+        this.interfacePath = interfacePath;
+        this.interfaceLabel = interfaceLabel;
+        this.requestUrl = requestUrl;
+        this.signT = signT;
+        this.httpStatus = httpStatus;
+        this.respCode = respCode;
+        this.respMsg = respMsg;
+        this.success = success;
+        this.attemptNo = attemptNo;
+        this.costMs = costMs;
+        this.triggerType = triggerType;
+        this.createdAt = createdAt;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushRecordQuery.java b/src/main/java/com/yunhai/userbase/model/push/PushRecordQuery.java
new file mode 100644
index 0000000..ffa1240
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushRecordQuery.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.push;
+
+import lombok.Data;
+
+/**
+ * 推送记录查询条件（前端日志页搜索用）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushRecordQuery {
+
+    /** 订阅方 appKey */
+    private Integer appKey;
+    /** 接口路径，如 group/AddGroup */
+    private String interfacePath;
+    /** 是否成功：0失败 1成功 */
+    private Integer success;
+    /** 起始时间 yyyy-MM-dd（含当天 00:00:00） */
+    private String startTime;
+    /** 结束时间 yyyy-MM-dd（含当天 23:59:59） */
+    private String endTime;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushTaskMessage.java b/src/main/java/com/yunhai/userbase/model/push/PushTaskMessage.java
new file mode 100644
index 0000000..744d641
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushTaskMessage.java
@@ -0,0 +1,38 @@
+package com.yunhai.userbase.model.push;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * MQ 推送任务消息。<br>
+ * 由 {@code PushDispatcher}（生产方）投递，{@code PushConsumer}（消费方）取出后 POST 给订阅方。<br>
+ * 签名（t + sign）在投递时由基础平台计算一次；自动重试保持原 t/sign，手动重试重新生成。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class PushTaskMessage implements Serializable {
+
+    /** 订阅方 appKey */
+    private Integer appKey;
+    /** 接口路径，如 group/AddGroup */
+    private String interfacePath;
+    /** 接口友好名 */
+    private String interfaceLabel;
+    /** 业务数据原始 JSON 字符串（签名与发送均基于该原始字符串字节） */
+    private String body;
+    /** 签名时间戳（字符串） */
+    private String t;
+    /** HMAC-SHA256(业务JSON + t, secret) hex 小写 */
+    private String sign;
+    /** 第几次尝试：1=首次 */
+    private int attemptNo;
+    /** 触发类型：manual / auto / retry */
+    private String triggerType;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/PushTestRequest.java b/src/main/java/com/yunhai/userbase/model/push/PushTestRequest.java
new file mode 100644
index 0000000..4859229
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/PushTestRequest.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase.model.push;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 测试推送请求（测试推送页调用）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushTestRequest {
+
+    /** 订阅方应用 id */
+    private Integer appId;
+    /** 接口路径，如 group/AddGroup */
+    private String interfacePath;
+    /** 目标 id 列表（可选）：不传则按接口类型取全量/全部 */
+    private List<Integer> targetIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/dto/PushGroupDTO.java b/src/main/java/com/yunhai/userbase/model/push/dto/PushGroupDTO.java
new file mode 100644
index 0000000..06cd21a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/dto/PushGroupDTO.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.model.push.dto;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 文档「组」契约 DTO（group/SyncGroup、AddGroup、UpdateGroup 共用）。<br>
+ * 字段严格对齐《弘育基础平台数据同步接口 2》：
+ * <ul>
+ *   <li>SyncGroup：children 递归树（可空）</li>
+ *   <li>AddGroup：pid 必填（上级组 id，0 为顶级）</li>
+ *   <li>UpdateGroup：仅 id 必填，其余可选</li>
+ * </ul>
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushGroupDTO {
+
+    private Integer id;
+    private String name;
+    private String code;
+    /** 组类别 1-8，与 GroupTypeEnum 1:1 零映射 */
+    private Integer type;
+    /** 上级组 id（AddGroup 必填） */
+    private Integer pid;
+    private Integer no;
+    /** 子组列表（SyncGroup 用） */
+    private List<PushGroupDTO> children;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/push/dto/PushUserDTO.java b/src/main/java/com/yunhai/userbase/model/push/dto/PushUserDTO.java
new file mode 100644
index 0000000..697ca4b
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/push/dto/PushUserDTO.java
@@ -0,0 +1,53 @@
+package com.yunhai.userbase.model.push.dto;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 文档「用户」契约 DTO（user/SyncUser、AddUser、UpdateUser 共用）。<br>
+ * 字段严格对齐《弘育基础平台数据同步接口 2》：
+ * <ul>
+ *   <li>status：0正常 / 2禁用（由 userbase StatusEnum 映射）</li>
+ *   <li>groups：用户所属组，含 groupId / no / schoolId（schoolId = 组所属学校范围 id）</li>
+ *   <li>roleList：用户身份，含 roleId / schId（schId = 用户主组所属学校范围 id）</li>
+ * </ul>
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Data
+public class PushUserDTO {
+
+    private Integer id;
+    private String account;
+    private String name;
+    private String idcard;
+    private String phone;
+    private String email;
+    /** 性别 0女 1男 */
+    private Integer gender;
+    private String birthday;
+    /** 用户状态 0正常 2禁用 */
+    private Integer status;
+    private String profilePicture;
+    private List<PushUserGroupRef> groups;
+    private List<PushUserRoleRef> roleList;
+
+    /** 用户所属组引用。 */
+    @Data
+    public static class PushUserGroupRef {
+        private Integer groupId;
+        private Integer no;
+        /** 组所属学校范围 id（沿 parentId 向上最近的 SCHOOL_GROUP） */
+        private Integer schoolId;
+    }
+
+    /** 用户身份引用。 */
+    @Data
+    public static class PushUserRoleRef {
+        private Integer roleId;
+        /** 所属学校 id（userbase 无角色-学校关联，统一取用户主组所属学校） */
+        private Integer schId;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/AcademicYear.java b/src/main/java/com/yunhai/userbase/model/serialize/AcademicYear.java
new file mode 100644
index 0000000..a8c41f8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/AcademicYear.java
@@ -0,0 +1,20 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+/**
+* @Description: 学年学期
+* @Author: chenx
+* @Date: 2023/9/5
+*/
+
+@Data
+public class AcademicYear {
+    public Integer id;
+    public String name;
+    public Integer year;
+    public Integer semester;
+    public String startDate;
+    public String endDate;
+    public String intervalDate;//日期区间
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/AcademicYearSeq.java b/src/main/java/com/yunhai/userbase/model/serialize/AcademicYearSeq.java
new file mode 100644
index 0000000..23f6b1f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/AcademicYearSeq.java
@@ -0,0 +1,25 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+* @Description: 班级管理学年学期序列化
+* @Author: chenx
+* @Date: 2023/9/5
+*/
+
+@Data
+public class AcademicYearSeq {
+    private int id;
+    private String name;
+    private Date startDate;
+    private Date endDate;
+    private Date progressionDate;
+    private int year;
+    private Date firstSemesterStartDate;
+    private Date firstSemesterEndDate;
+    private Date secondSemesterStartDate;
+    private Date secondSemesterEndDate;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/BaseSchool.java b/src/main/java/com/yunhai/userbase/model/serialize/BaseSchool.java
new file mode 100644
index 0000000..029444e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/BaseSchool.java
@@ -0,0 +1,18 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2025/12/30 19:31
+ * @description 学校列表
+ */
+
+@Data
+public class BaseSchool {
+    private String SchSerID;
+    private int Type;
+    private String PID;
+    private int ID;
+    private String Name;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/GradeClassStu.java b/src/main/java/com/yunhai/userbase/model/serialize/GradeClassStu.java
new file mode 100644
index 0000000..5e87ee4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/GradeClassStu.java
@@ -0,0 +1,22 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+/**
+* @Description: 班级管理接口序列化 ：GetClaArrStulist
+* @Author: chenx
+* @Date: 2023/6/8
+*/
+
+@Data
+public class GradeClassStu {
+    private Integer gradeId;
+    private String gradeName;
+    private Integer classId;
+    private String className;
+    private Integer stuId;
+    private String stuName;
+    private String CardID;//学号
+    private Integer StuSex;//性别
+    private String StuPhoto;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/SchClass.java b/src/main/java/com/yunhai/userbase/model/serialize/SchClass.java
new file mode 100644
index 0000000..bdfe307
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/SchClass.java
@@ -0,0 +1,15 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+@Data
+public class SchClass {
+
+    public String SchSerID;
+    public int SchID;
+    public String GradeName;
+    public String ClassName;
+    public String ClassID;
+    public int GradeID;
+    public int CID;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/SchClassModel.java b/src/main/java/com/yunhai/userbase/model/serialize/SchClassModel.java
new file mode 100644
index 0000000..d8913a7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/SchClassModel.java
@@ -0,0 +1,12 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+@Data
+public class SchClassModel {
+    public Integer classID;
+    public Integer gradeID;
+    public String gradeName;
+    public String className;
+
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/SchLenLevel.java b/src/main/java/com/yunhai/userbase/model/serialize/SchLenLevel.java
new file mode 100644
index 0000000..fd8d7d8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/SchLenLevel.java
@@ -0,0 +1,23 @@
+package com.yunhai.userbase.model.serialize;
+
+import com.alibaba.fastjson.annotation.JSONField;
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2025/12/25 15:56
+ * @description 学校学制年级信息
+ */
+
+@Data
+public class SchLenLevel {
+    private Integer code;
+    @JSONField(name = "OwnerId")
+    private Integer ownerId;
+    private String sx;
+    @JSONField(name = "Id")
+    private Integer id;
+    private Integer levell;
+    @JSONField(name = "Name")
+    private String name;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/SchTeaInfo.java b/src/main/java/com/yunhai/userbase/model/serialize/SchTeaInfo.java
new file mode 100644
index 0000000..7ee4969
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/SchTeaInfo.java
@@ -0,0 +1,35 @@
+package com.yunhai.userbase.model.serialize;
+
+/**
+ * @program: ResearchLearn
+ * @description: 全部教师信息
+ * @author: chenx
+ * @create: 2024-06-07 10:16
+ **/
+
+import lombok.Data;
+
+@Data
+public class SchTeaInfo {
+    private String SchSerID;
+    private String Teapolitical;
+    private String TeaWorkStart;
+    private String Account;
+    private String role;
+    private Integer TeaSex;
+    private String IsLeadingMiddle;
+    private String TeaOriginPlace;
+    private String Photo;
+    private String TeaIDCard;
+    private String Name;
+    private Integer GroupID;
+    private String SchName;
+    private String TeaTeachStart;
+    private String TeaSerID;
+    private Integer UserID;
+    private String TeaNation;
+    private String Tel;
+    private String TeaWorkType;
+    private Integer TeaNo;
+    private String TeaBirth;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/StuInfo.java b/src/main/java/com/yunhai/userbase/model/serialize/StuInfo.java
new file mode 100644
index 0000000..e5a32b4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/StuInfo.java
@@ -0,0 +1,29 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+/**
+ * @program: QualityEvaluate
+ * @description: 获取班级列表的学生信息序列化
+ * @author: chenx
+ * @create: 2023-08-21 10:27
+ **/
+
+@Data
+public class StuInfo {
+    private String SchSerID;
+    private String Account;
+    private String StuStatus;
+    private String invitecode;
+    private int StuSex;
+    private String ClassID;
+    private String CardID;
+    private String ClassStuID;
+    private String StuPhoto;
+    private long GroupID;
+    private String StuName;
+    private long UserStuSerID;
+    private boolean Graduated;
+    private String StuIDCard;
+    private String StuCurrentTel;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/StuInfo2.java b/src/main/java/com/yunhai/userbase/model/serialize/StuInfo2.java
new file mode 100644
index 0000000..4c65fe6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/StuInfo2.java
@@ -0,0 +1,31 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+ * @program: QualityEvaluate
+ * @description: 获取单个学生信息序列化
+ * @author: chenx
+ * @create: 2023-09-06 14:46
+ **/
+
+@Data
+public class StuInfo2 {
+    private int status_code;
+    private String idCard;
+    private int sex;
+    private String photo;
+    private int IsGraduation;
+    private Date birth;
+    private String ClaName;
+    private String stuName;
+    private String SchName;
+    private String studentId;
+    private long classId;
+    private String GradeName;
+    private long UserStuSerID;
+    private String ClassName;
+    private int IsDelete;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/serialize/TeaFirstClass.java b/src/main/java/com/yunhai/userbase/model/serialize/TeaFirstClass.java
new file mode 100644
index 0000000..1eb1237
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/serialize/TeaFirstClass.java
@@ -0,0 +1,13 @@
+package com.yunhai.userbase.model.serialize;
+
+import lombok.Data;
+
+@Data
+public class TeaFirstClass {
+    public String gradeName;
+    public int gradeId ;
+    public String alias;
+    public String className ;
+    public String name ;
+    public int id ;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupBatchRequest.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupBatchRequest.java
new file mode 100644
index 0000000..7102524
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupBatchRequest.java
@@ -0,0 +1,48 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import lombok.Data;
+
+import javax.validation.Valid;
+import javax.validation.constraints.NotEmpty;
+import javax.validation.constraints.NotNull;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 系统组批量新增请求：在指定父组下，按 items 列表逐个创建子组。<br>
+ * 请求体示例：<br>
+ * {<br>
+ *   "pid": 11285,<br>
+ *   "type": 4,<br>
+ *   "items": [<br>
+ *     { "name": "高一1班" },<br>
+ *     { "name": "高一2班" }<br>
+ *   ]<br>
+ * }
+ */
+@Data
+public class SysGroupBatchRequest {
+
+    /** 父组ID（待生成子组的挂载点，必须存在）。 */
+    @NotNull(message = "父组ID不能为空")
+    private Integer pid;
+
+    /** 组类型（GroupTypeEnum.key，如 4=班级组）。 */
+    @NotNull(message = "组类型不能为空")
+    private Integer type;
+
+    /** 待新增的子组列表，每一项仅需提供 name。 */
+    @NotEmpty(message = "批量新增的子组列表不能为空")
+    @Valid
+    private List<BatchItem> items;
+
+    /** 批量新增的单项。 */
+    @Data
+    public static class BatchItem {
+        /** 子组名称。 */
+        @javax.validation.constraints.NotBlank(message = "组名称不能为空")
+        private String name;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupMoveRequest.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupMoveRequest.java
new file mode 100644
index 0000000..3643b72
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupMoveRequest.java
@@ -0,0 +1,23 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 移动组请求：将 moveId 节点移动到 pid 节点下。<br>
+ * 不支持移动到自身或自身后代下（环检测）。
+ */
+@Data
+public class SysGroupMoveRequest {
+
+    /** 待移动节点ID。 */
+    @NotNull(message = "待移动节点ID不能为空")
+    private Integer moveId;
+
+    /** 目标父节点ID（移动后的挂载点，必须存在）。 */
+    @NotNull(message = "目标父节点ID不能为空")
+    private Integer pid;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupQuery.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupQuery.java
new file mode 100644
index 0000000..ece4fc8
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupQuery.java
@@ -0,0 +1,15 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组查询条件
+ */
+@Data
+public class SysGroupQuery {
+    private String name;
+
+    private Integer parentId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupRequest.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupRequest.java
new file mode 100644
index 0000000..405668c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupRequest.java
@@ -0,0 +1,31 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.NotBlank;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组新增/编辑请求
+ */
+@Data
+public class SysGroupRequest {
+    // ID 通过路径参数传递，body 无需携带，故不在校验组内强制
+    private Integer id;
+
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "组名称不能为空")
+    private String name;
+
+    // 新增时必填；编辑不通过此字段移动节点（移动请走 Move 接口），故编辑时可选
+    @NotNull(groups = ValidationGroups.Create.class, message = "上级组ID不能为空")
+    private Integer parentId;
+
+    // 新增时必填；编辑时可选（仅当需要变更类型时传入）
+    @NotNull(groups = ValidationGroups.Create.class, message = "组类型不能为空")
+    private Integer type;
+
+    private Integer sort;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupSortRequest.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupSortRequest.java
new file mode 100644
index 0000000..d01ecd1
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupSortRequest.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 子组排序请求：将 pid 的直接子节点按给定 ids 顺序重新排列并落库。<br>
+ * ids 必须全部是 pid 下一级的直接子节点，否则报错。
+ */
+@Data
+public class SysGroupSortRequest {
+
+    /** 父组ID。 */
+    @NotNull(message = "父组ID不能为空")
+    private Integer pid;
+
+    /** 期望的、pid 直接子节点有序 ID 列表（按传入顺序生效）。 */
+    @NotNull(message = "子节点ID列表不能为空")
+    private List<Integer> ids;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupVo.java b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupVo.java
new file mode 100644
index 0000000..8aadbe5
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysgroup/SysGroupVo.java
@@ -0,0 +1,21 @@
+package com.yunhai.userbase.model.sysgroup;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组返回对象（树形：children 递归存放子组）。<br>
+ */
+@Data
+public class SysGroupVo {
+    private Integer id;
+    private String name;
+    private Integer type;
+    private Integer sort;
+    /** 子组（递归）；默认空列表，避免 JSON 序列化出现 null。 */
+    private List<SysGroupVo> children = new ArrayList<>();
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/BatchChangeStatusRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/BatchChangeStatusRequest.java
new file mode 100644
index 0000000..28905f7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/BatchChangeStatusRequest.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotEmpty;
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/8/12
+ * @description 批量设置用户状态请求
+ */
+@Data
+public class BatchChangeStatusRequest {
+
+    /** 待设置用户ID列表 */
+    @NotEmpty(message = "待设置用户不能为空")
+    private List<Integer> userIds;
+
+    /** 是否禁用：true=禁用，false=启用 */
+    @NotNull(message = "状态不能为空")
+    private Boolean disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/BatchDeleteRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/BatchDeleteRequest.java
new file mode 100644
index 0000000..5f1b4cb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/BatchDeleteRequest.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotEmpty;
+import javax.validation.constraints.NotNull;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/8/12
+ * @description 批量从当前组删除用户请求
+ */
+@Data
+public class BatchDeleteRequest {
+
+    /** 待删除用户ID列表 */
+    @NotEmpty(message = "待删除用户不能为空")
+    private List<Integer> userIds;
+
+    /** 当前组ID */
+    @NotNull(message = "组ID不能为空")
+    private Integer groupId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/BatchImportResult.java b/src/main/java/com/yunhai/userbase/model/sysuser/BatchImportResult.java
new file mode 100644
index 0000000..f479d3a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/BatchImportResult.java
@@ -0,0 +1,47 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/8/11
+ * @description 用户批量导入结果
+ */
+@Data
+public class BatchImportResult {
+
+    /** 总行数（含表头） */
+    private int total;
+
+    /** 成功条数 */
+    private int success;
+
+    /** 失败条数 */
+    private int fail;
+
+    /** 失败明细：行号 + 原因 */
+    private List<FailItem> fails = new ArrayList<>();
+
+    @Data
+    public static class FailItem {
+        private int row;
+        private String reason;
+
+        public FailItem(int row, String reason) {
+            this.row = row;
+            this.reason = reason;
+        }
+    }
+
+    public void addSuccess() {
+        this.success++;
+    }
+
+    public void addFail(int row, String reason) {
+        this.fail++;
+        this.fails.add(new FailItem(row, reason));
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/ChangeGroupsRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/ChangeGroupsRequest.java
new file mode 100644
index 0000000..5c15b38
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/ChangeGroupsRequest.java
@@ -0,0 +1,23 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotEmpty;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/8/11
+ * @description 批量调整用户所属组请求
+ */
+@Data
+public class ChangeGroupsRequest {
+
+    /** 待调整用户ID列表 */
+    @NotEmpty(message = "待调整用户不能为空")
+    private List<Integer> userIds;
+
+    /** 目标组ID列表（覆盖式） */
+    @NotEmpty(message = "请至少保留一个组")
+    private List<Integer> groupIds;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/ChangeSortNoRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/ChangeSortNoRequest.java
new file mode 100644
index 0000000..0631049
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/ChangeSortNoRequest.java
@@ -0,0 +1,29 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.Max;
+import javax.validation.constraints.Min;
+import javax.validation.constraints.NotNull;
+
+/**
+ * @author chenx
+ * @date 2026/8/12
+ * @description 调整用户在某组内的排序号
+ */
+@Data
+public class ChangeSortNoRequest {
+
+    /** 所属分组（排序号按组维度存储，必须明确是哪个组） */
+    @NotNull(message = "所属分组不能为空")
+    private Integer groupId;
+
+    /**
+     * 组内排序号：1~999 的正整数；越小越靠前。<br>
+     * 允许为 null —— 表示清除排序号，列表回退到 user_id 升序兜底。<br>
+     * 注意：@Min/@Max 对 null 不生效，null 由业务层解释为「清除」。
+     */
+    @Min(1)
+    @Max(999)
+    private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/ExcelSysUser.java b/src/main/java/com/yunhai/userbase/model/sysuser/ExcelSysUser.java
new file mode 100644
index 0000000..675e952
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/ExcelSysUser.java
@@ -0,0 +1,53 @@
+package com.yunhai.userbase.model.sysuser;
+
+import cn.afterturn.easypoi.excel.annotation.Excel;
+import lombok.Data;
+
+import java.io.Serializable;
+
+/**
+ * 组用户导出 Excel 实体：与导入模板 {@code IMPORT_COLUMN_DEFS} 同构（前 12 列顺序一致），
+ * 末尾追加「用户id」列。导出 = 读取数据库数据填充 list，复用 EasyPoi 的 {@code @Excel} 注解生成 Excel。
+ */
+@Data
+public class ExcelSysUser implements Serializable {
+
+    @Excel(name = "组名\n（不必填，供与id对应参考用）", orderNum = "0", width = 36)
+    private String groupName;
+
+    @Excel(name = "组id(必须)", orderNum = "1", width = 14)
+    private String groupId;
+
+    @Excel(name = "用户名(必须)", orderNum = "2", width = 20)
+    private String account;
+
+    @Excel(name = "密码\n(可选，\n默认Vzuk4Dp3)", orderNum = "3", width = 18)
+    private String password;
+
+    @Excel(name = "姓名(必须)", orderNum = "4", width = 16)
+    private String realName;
+
+    @Excel(name = "身份证号(可选)", orderNum = "5", width = 22)
+    private String idcard;
+
+    @Excel(name = "手机号(可选)", orderNum = "6", width = 16)
+    private String phone;
+
+    @Excel(name = "email(可选)", orderNum = "7", width = 24)
+    private String email;
+
+    @Excel(name = "用户性质\n(可选，默认普通用户\n组管理员2,\n普通用户0,\n导入不接受别的代码)", orderNum = "8", width = 26)
+    private Integer nature;
+
+    @Excel(name = "用户身份\n(1教师 2教职工 3学生 4家长)", orderNum = "9", width = 24)
+    private Integer identity;
+
+    @Excel(name = "性别(可选)", orderNum = "10", width = 12)
+    private Integer gender;
+
+    @Excel(name = "生日(yyyy-MM-dd)(可选)", orderNum = "11", width = 22)
+    private String birthday;
+
+    @Excel(name = "用户id", orderNum = "12", width = 14)
+    private Integer userId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserGroupDeleteItem.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserGroupDeleteItem.java
new file mode 100644
index 0000000..7645bfb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserGroupDeleteItem.java
@@ -0,0 +1,40 @@
+package com.yunhai.userbase.model.sysuser;
+
+/**
+ * 批量删除用户-组关系单项（与 BasePlatform 开放接口模型 {@code SysUserGroupDeleteItem} 字段对齐）。<br>
+ * 每条记录携带自身所属学校范围 {@code schoolId}，供 {@code SysUserService.deleteUsers} 逐条校验：<br>
+ * groupId 必须属于 schoolId 子树且不能等于 schoolId（禁止跨校解绑 / 整校移除）。
+ */
+public class SysUserGroupDeleteItem {
+
+    /** 待解绑用户 ID */
+    private Integer userId;
+    /** 待解绑的组 ID（必须属于 schoolId 子树，且不能等于 schoolId） */
+    private Integer groupId;
+    /** 学校组 ID：限定该条解绑的学校范围 */
+    private Integer schoolId;
+
+    public Integer getUserId() {
+        return userId;
+    }
+
+    public void setUserId(Integer userId) {
+        this.userId = userId;
+    }
+
+    public Integer getGroupId() {
+        return groupId;
+    }
+
+    public void setGroupId(Integer groupId) {
+        this.groupId = groupId;
+    }
+
+    public Integer getSchoolId() {
+        return schoolId;
+    }
+
+    public void setSchoolId(Integer schoolId) {
+        this.schoolId = schoolId;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserMoveRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserMoveRequest.java
new file mode 100644
index 0000000..abad1a7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserMoveRequest.java
@@ -0,0 +1,24 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * @description 开放接口：移动用户到指定组请求（语义同后台「调整组」——覆盖式把用户组归属替换为目标组，目标设为主组）。
+ */
+@Data
+public class SysUserMoveRequest {
+
+    /** 待移动用户ID。 */
+    @NotNull(message = "用户ID不能为空")
+    private Integer userId;
+
+    /** 目标组ID（移动后的主归属组，必须存在）。 */
+    @NotNull(message = "目标组ID不能为空")
+    private Integer groupId;
+
+    /** 学校组ID：限定移动范围，仅允许将用户在同一学校（组）范围内移动。 */
+    @NotNull(message = "学校ID不能为空")
+    private Integer schoolId;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserPasswordRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserPasswordRequest.java
new file mode 100644
index 0000000..78454c2
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserPasswordRequest.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+
+/**
+ * 修改用户密码请求（oapi 开放接口专用）。
+ *
+ * @author chenx
+ */
+@Data
+public class SysUserPasswordRequest {
+
+    /**
+     * 用户ID（必填）。
+     */
+    @NotNull
+    private Integer userId;
+
+    /**
+     * 旧密码（必填，须与库中 BCrypt 密文匹配）。
+     */
+    @NotBlank
+    private String oldPassword;
+
+    /**
+     * 新密码（必填，走弱密码规则校验后 BCrypt 加密写入）。
+     */
+    @NotBlank
+    private String newPassword;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserQuery.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserQuery.java
new file mode 100644
index 0000000..2f35855
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserQuery.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户列表查询条件
+ */
+@Data
+public class SysUserQuery {
+
+    /** 分组ID（列表以某个组节点为上下文查询其下用户） */
+    private Integer groupId;
+
+    /**
+     * 是否包含子组用户：0=仅查询该节点下的用户；1=查询该节点及其所有子孙组下的用户。<br>
+     * 默认 0。<br>
+     */
+    private Integer withSub = 0;
+
+    /** 关键字：同时匹配账号、姓名、身份证（模糊）与手机号（精确） */
+    private String name;
+
+    /** 启用状态过滤（可选）；对应实体 disabled 字段（StatusEnum key：0=正常/未禁用，1=禁用） */
+    private Integer disabled;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserRequest.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserRequest.java
new file mode 100644
index 0000000..ccdf606
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserRequest.java
@@ -0,0 +1,45 @@
+package com.yunhai.userbase.model.sysuser;
+
+import com.yunhai.userbase.common.validation.ValidationGroups;
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户新增/编辑请求
+ */
+@Data
+public class SysUserRequest {
+    @NotNull(groups = ValidationGroups.Update.class, message = "编辑时ID不能为空")
+    private Integer id;
+
+    /** 所属分组ID，新增时必填（用户创建后写入组用户关联表） */
+    @NotNull(groups = ValidationGroups.Create.class, message = "所属分组不能为空")
+    private Integer groupId;
+
+    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, message = "账号不能为空")
+    private String account;
+
+    @NotBlank(groups = ValidationGroups.Create.class, message = "密码不能为空")
+    private String password;
+
+    /** 确认密码：与 password 一致性由 Service 校验（编辑时若不修改密码可不传） */
+    private String confirmPassword;
+
+    private String realName;
+    private String phone;
+    private LocalDate birthday;
+    private String idcard;
+    private String email;
+    private Integer gender;
+    private String profilePicture;
+    private List<Integer> roles;
+    /** 启用状态：对应 StatusEnum 的 key（0=正常/未禁用，1=禁用）；不传则默认启用 */
+    private Integer disabled;
+    private Boolean expired;
+}
diff --git a/src/main/java/com/yunhai/userbase/model/sysuser/SysUserVo.java b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserVo.java
new file mode 100644
index 0000000..3dee203
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/model/sysuser/SysUserVo.java
@@ -0,0 +1,35 @@
+package com.yunhai.userbase.model.sysuser;
+
+import lombok.Data;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户返回对象
+ */
+@Data
+public class SysUserVo {
+    private Integer id;
+    private String account;
+    private LocalDate birthday;
+    private String realName;
+    private String phone;
+    private String idcard;
+    private String email;
+    private Integer gender;
+    private String profilePicture;
+    private List<Integer> roles;
+    /** 启用状态：StatusEnum 的 key（0=正常/未禁用，1=禁用） */
+    private Integer disabled;
+    /** 用户类型：UserTypeEnum 的 key（0=普通用户，1=超级管理员，2=学校管理员） */
+    private Integer type;
+    /** 当前组维度的排序号（组内 sort_no）；根节点/未选组时为 null */
+    private Integer sortNo;
+    private Boolean expired;
+    private LocalDateTime createTime;
+    private LocalDateTime updateTime;
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/AppCategoryRepository.java b/src/main/java/com/yunhai/userbase/repository/AppCategoryRepository.java
new file mode 100644
index 0000000..1401768
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/AppCategoryRepository.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.AppCategory;
+import io.lettuce.core.dynamic.annotation.Param;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 21:29
+ * @description
+ */
+public interface AppCategoryRepository extends JpaRepository<AppCategory, Integer>, JpaSpecificationExecutor<AppCategory> {
+
+    @Query("SELECT MAX(c.sortNo) FROM AppCategory c")
+    Integer findMaxSortNo();
+
+    List<AppCategory> findAllByOrderBySortNoAsc();
+
+    List<AppCategory> findByNameContainingOrderBySortNoAsc(String name);
+
+    boolean existsByName(String name);
+
+    boolean existsByNameAndIdNot(String name, Integer id);
+
+    @Modifying
+    @Query("UPDATE AppCategory c SET c.sortNo = :sortNo WHERE c.id = :id")
+    void updateSortNoById(@Param("id") Integer id, @Param("sortNo") Integer sortNo);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/AppModuleRepository.java b/src/main/java/com/yunhai/userbase/repository/AppModuleRepository.java
new file mode 100644
index 0000000..e1306d9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/AppModuleRepository.java
@@ -0,0 +1,46 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.AppModule;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块仓储。<br>
+ */
+public interface AppModuleRepository extends JpaRepository<AppModule, Integer>, JpaSpecificationExecutor<AppModule> {
+
+    /**
+     * 动态过滤：appId/parentId/name 均可空；<br>
+     * 排序：sortNo 正序（空视为 999），再按 id 正序。
+     */
+    @Query("SELECT m FROM AppModule m " +
+            "WHERE (:appId IS NULL OR m.appId = :appId) " +
+            "AND (:parentId IS NULL OR m.parentId = :parentId) " +
+            "AND (:name IS NULL OR m.name LIKE CONCAT('%', :name, '%')) " +
+            "ORDER BY CASE WHEN m.sortNo IS NULL THEN 999 ELSE m.sortNo END ASC, m.id ASC")
+    List<AppModule> findModules(@Param("appId") Integer appId,
+                                @Param("parentId") Integer parentId,
+                                @Param("name") String name);
+
+    boolean existsByAppIdAndCustomId(Integer appId, String customId);
+
+    boolean existsByAppIdAndCustomIdAndIdNot(Integer appId, String customId, Integer id);
+
+    long countByParentId(Integer parentId);
+
+    /**
+     * 按应用ID集合查询全部模块（组授权按已开通应用批量加载模块树用）。<br>
+     */
+    List<AppModule> findByAppIdIn(List<Integer> appIds);
+
+    /**
+     * 按应用ID级联删除其下全部模块（逻辑外键 appId，无物理 FK，需手动清理整棵子树）。<br>
+     */
+    void deleteByAppId(Integer appId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/ApplicationInfoRepository.java b/src/main/java/com/yunhai/userbase/repository/ApplicationInfoRepository.java
new file mode 100644
index 0000000..a34acb3
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/ApplicationInfoRepository.java
@@ -0,0 +1,80 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.appauthz.AppAuthzAppRow;
+import com.yunhai.userbase.model.application.ApplicationInfoSortVo;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 21:29
+ * @description
+ */
+public interface ApplicationInfoRepository  extends JpaRepository<ApplicationInfo, Integer>, JpaSpecificationExecutor<ApplicationInfo> {
+    @Query("SELECT COUNT(a.id) FROM ApplicationInfo a WHERE a.categoryId = :categoryId AND a.appKey > 100000")
+    Integer countByCategoryId(@Param("categoryId") Integer id);
+
+    boolean existsByName(String name);
+
+    boolean existsByNameAndIdNot(String name, Integer id);
+
+    /**
+     * 查询当前最大的 appKey 值。<br>
+     * 用于新增应用时生成从 100000 起自增的整型 appKey。<br>
+     *
+     * @return 当前最大 appKey，无记录时返回 null
+     */
+    @Query("SELECT MAX(a.appKey) FROM ApplicationInfo a")
+    Integer findMaxAppKey();
+
+    /**
+     * 按整型 appKey 查单个应用（验签兜底端点直连读取用）。<br>
+     * appKey 由新增应用自增生成，业务上唯一。
+     *
+     * @param appKey 应用标识（整数）
+     * @return 匹配的应用实体，无则 null
+     */
+    ApplicationInfo findByAppKey(Integer appKey);
+
+    /** 查询所有开启推送的应用（自动推送遍历订阅方用）。 */
+    List<ApplicationInfo> findByPushEnabled(Integer pushEnabled);
+
+    /**
+     * 按 id 更新排序号（同一应用类型内排序使用）。<br>
+     *
+     * @param id     应用ID
+     * @param sortNo 新的排序号
+     */
+    @Modifying
+    @Query("UPDATE ApplicationInfo a SET a.sortNo = :sortNo WHERE a.id = :id")
+    void updateSortNoById(@Param("id") Integer id, @Param("sortNo") Integer sortNo);
+
+    /**
+     * 按应用类型查询排序所需的精简视图（仅 id/name/sortNo），不分页。<br>
+     * 使用构造器表达式做 DTO 投影，避免加载整个实体（含 appSecret、各类 URL 等无关大字段）。<br>
+     * 排除用户中心自身的基石应用（appKey=100000）。
+     *
+     * @param categoryId 应用类型ID
+     * @return 该类型下全部应用的排序视图，按 sortNo 升序（未排序排末尾），id 升序兜底
+     */
+    @Query("SELECT new com.yunhai.userbase.model.application.ApplicationInfoSortVo(a.id, a.name, a.sortNo) " +
+            "FROM ApplicationInfo a WHERE a.categoryId = :categoryId AND a.appKey > 100000 ORDER BY a.sortNo ASC, a.id ASC")
+    List<ApplicationInfoSortVo> findSortVoByCategoryId(@Param("categoryId") Integer categoryId);
+
+    /**
+     * 应用授权用：查询全部应用的扁平投影（含 categoryId 供按类型分组），仅取 id/name/pcIcon。<br>
+     * 按 categoryId、sortNo、id 升序，便于分组后同类型内保持排序。<br>
+     * 排除用户中心自身的基石应用（appKey=100000）。
+     *
+     * @return 全部应用的授权投影行
+     */
+    @Query("SELECT new com.yunhai.userbase.model.appauthz.AppAuthzAppRow(a.categoryId, a.id, a.name, a.pcIcon) " +
+            "FROM ApplicationInfo a WHERE a.appKey > 100000 ORDER BY a.categoryId ASC, a.sortNo ASC, a.id ASC")
+    List<AppAuthzAppRow> findAllAuthzRows();
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/PushRecordRepository.java b/src/main/java/com/yunhai/userbase/repository/PushRecordRepository.java
new file mode 100644
index 0000000..65a4eaa
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/PushRecordRepository.java
@@ -0,0 +1,16 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.model.push.PushRecordEntity;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.stereotype.Repository;
+
+/**
+ * 推送记录仓储。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Repository
+public interface PushRecordRepository extends JpaRepository<PushRecordEntity, Long>, JpaSpecificationExecutor<PushRecordEntity> {
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysAppRoleModuleRelRepository.java b/src/main/java/com/yunhai/userbase/repository/SysAppRoleModuleRelRepository.java
new file mode 100644
index 0000000..d94a60c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysAppRoleModuleRelRepository.java
@@ -0,0 +1,47 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysAppRoleModuleRel;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 业务角色-模块权限关系仓储。<br>
+ */
+public interface SysAppRoleModuleRelRepository extends JpaRepository<SysAppRoleModuleRel, Integer>, JpaSpecificationExecutor<SysAppRoleModuleRel> {
+
+    List<SysAppRoleModuleRel> findByRoleId(Integer roleId);
+
+    /**
+     * 权限计算用：批量查询一组角色的全部模块授权记录。<br>
+     */
+    List<SysAppRoleModuleRel> findByRoleIdIn(List<Integer> roleIds);
+
+    /**
+     * 按角色ID批量物理删除模块授权记录（bulk delete 直接发 SQL）。<br>
+     * 用于「角色模块授权」全量覆盖式保存的先删后插，避免 Hibernate flush 先 insert 后 delete 触发唯一键冲突。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysAppRoleModuleRel r WHERE r.roleId = :roleId")
+    void deleteByRoleIdBulk(@Param("roleId") Integer roleId);
+
+    /**
+     * 按角色ID集合批量物理删除模块授权记录（删除应用时级联清理该应用下角色）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysAppRoleModuleRel r WHERE r.roleId IN :roleIds")
+    void deleteByRoleIdInBulk(@Param("roleIds") List<Integer> roleIds);
+
+    /**
+     * 按模块ID集合批量物理删除模块授权记录（删除模块/应用时级联清理）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysAppRoleModuleRel r WHERE r.moduleId IN :moduleIds")
+    void deleteByModuleIdInBulk(@Param("moduleIds") List<Integer> moduleIds);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysAppRoleRepository.java b/src/main/java/com/yunhai/userbase/repository/SysAppRoleRepository.java
new file mode 100644
index 0000000..4c30a65
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysAppRoleRepository.java
@@ -0,0 +1,40 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysAppRole;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 应用业务角色仓储。<br>
+ */
+public interface SysAppRoleRepository extends JpaRepository<SysAppRole, Integer>, JpaSpecificationExecutor<SysAppRole> {
+
+    /**
+     * 普通角色重名校验：同一应用下角色名称唯一（新增用）。<br>
+     */
+    boolean existsByNameAndAppId(String name, Integer appId);
+
+    /**
+     * 普通角色重名校验：同一应用下角色名称唯一，排除自身（编辑用）。<br>
+     */
+    boolean existsByNameAndAppIdAndIdNot(String name, Integer appId, Integer id);
+
+    /**
+     * 全应用角色重名校验：全应用角色之间名称唯一（新增用）。<br>
+     */
+    boolean existsByNameAndAllAppFlagTrue(String name);
+
+    /**
+     * 全应用角色重名校验：全应用角色之间名称唯一，排除自身（编辑用）。<br>
+     */
+    boolean existsByNameAndAllAppFlagTrueAndIdNot(String name, Integer id);
+
+    /**
+     * 查询某应用下的全部普通角色（删除应用时级联清理用）。<br>
+     */
+    List<SysAppRole> findByAppId(Integer appId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysGroupAppRelRepository.java b/src/main/java/com/yunhai/userbase/repository/SysGroupAppRelRepository.java
new file mode 100644
index 0000000..8ec1200
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysGroupAppRelRepository.java
@@ -0,0 +1,49 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysGroupAppRel;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组应用开通仓储。<br>
+ */
+public interface SysGroupAppRelRepository extends JpaRepository<SysGroupAppRel, Integer>, JpaSpecificationExecutor<SysGroupAppRel> {
+
+    List<SysGroupAppRel> findByGroupId(Integer groupId);
+
+    List<SysGroupAppRel> findByGroupIdIn(List<Integer> groupIds);
+
+    boolean existsByGroupIdAndAppId(Integer groupId, Integer appId);
+
+    long countByAppId(Integer appId);
+
+    /**
+     * 按组ID批量物理删除开通记录（bulk delete 直接发 SQL）。<br>
+     * 用于「应用开通」全量覆盖式保存的先删后插，避免 Hibernate flush 先 insert 后 delete 触发唯一键冲突。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupAppRel r WHERE r.groupId = :groupId")
+    void deleteByGroupIdBulk(@Param("groupId") Integer groupId);
+
+    /**
+     * 按应用ID批量物理删除开通记录（删除应用时级联清理）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupAppRel r WHERE r.appId = :appId")
+    void deleteByAppIdBulk(@Param("appId") Integer appId);
+
+    /**
+     * 按 (组ID + 应用ID) 物理删除单条开通记录（增量取消开通用）。<br>
+     * 用于 SetSchoolApp 的「删除」模式：取消某个组下某个应用的开通。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupAppRel r WHERE r.groupId = :groupId AND r.appId = :appId")
+    void deleteByGroupIdAndAppIdBulk(@Param("groupId") Integer groupId, @Param("appId") Integer appId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysGroupModulePermRepository.java b/src/main/java/com/yunhai/userbase/repository/SysGroupModulePermRepository.java
new file mode 100644
index 0000000..c63ad22
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysGroupModulePermRepository.java
@@ -0,0 +1,60 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysGroupModulePerm;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组模块权限仓储。<br>
+ */
+public interface SysGroupModulePermRepository extends JpaRepository<SysGroupModulePerm, Integer>, JpaSpecificationExecutor<SysGroupModulePerm> {
+
+    List<SysGroupModulePerm> findByGroupId(Integer groupId);
+
+    /**
+     * 增量 upsert 用：查询某组对某模块是否已有权限记录。<br>
+     */
+    SysGroupModulePerm findByGroupIdAndModuleId(Integer groupId, Integer moduleId);
+
+    /**
+     * 权限判定用：查询目标模块在指定组ID集合（祖先链）上的全部权限记录。<br>
+     */
+    List<SysGroupModulePerm> findByModuleIdAndGroupIdIn(Integer moduleId, List<Integer> groupIds);
+
+    /**
+     * 按组ID批量物理删除权限记录（删除组时级联清理）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupModulePerm p WHERE p.groupId = :groupId")
+    void deleteByGroupIdBulk(@Param("groupId") Integer groupId);
+
+    /**
+     * 权限一览用：批量查询一组模块在指定组集合上的权限记录。<br>
+     */
+    List<SysGroupModulePerm> findByModuleIdInAndGroupIdIn(List<Integer> moduleIds, List<Integer> groupIds);
+    @Modifying
+    @Query("DELETE FROM SysGroupModulePerm p WHERE p.moduleId IN :moduleIds")
+    void deleteByModuleIdInBulk(@Param("moduleIds") List<Integer> moduleIds);
+
+    /**
+     * 删除某组在指定模块集合上的权限记录（组取消开通应用时清理该应用下模块的残留权限）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupModulePerm p WHERE p.groupId = :groupId AND p.moduleId IN :moduleIds")
+    void deleteByGroupIdAndModuleIdInBulk(@Param("groupId") Integer groupId, @Param("moduleIds") List<Integer> moduleIds);
+
+    /**
+     * 按 (组ID + 模块ID) 物理删除单条权限记录（增量取消模块授权用）。<br>
+     * 用于 SetGroupModule 的「删除」模式。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysGroupModulePerm p WHERE p.groupId = :groupId AND p.moduleId = :moduleId")
+    void deleteByGroupIdAndModuleIdBulk(@Param("groupId") Integer groupId, @Param("moduleId") Integer moduleId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysGroupRepository.java b/src/main/java/com/yunhai/userbase/repository/SysGroupRepository.java
new file mode 100644
index 0000000..a9c2f02
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysGroupRepository.java
@@ -0,0 +1,31 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysGroup;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Query;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组仓储
+ */
+public interface SysGroupRepository extends JpaRepository<SysGroup, Integer>, JpaSpecificationExecutor<SysGroup> {
+
+    @Query("SELECT MAX(g.sort) FROM SysGroup g")
+    Integer findMaxSort();
+
+    @Query("SELECT MAX(g.sort) FROM SysGroup g WHERE g.parentId = :parentId")
+    Integer findMaxSortByParentId(Integer parentId);
+
+    List<SysGroup> findAllByOrderBySortAsc();
+
+    List<SysGroup> findByNameContainingOrderBySortAsc(String name);
+
+    List<SysGroup> findByParentIdOrderBySortAsc(Integer parentId);
+
+    long countByParentId(Integer parentId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysOapiLogRepository.java b/src/main/java/com/yunhai/userbase/repository/SysOapiLogRepository.java
new file mode 100644
index 0000000..7bcf205
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysOapiLogRepository.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysOapiLog;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.time.LocalDateTime;
+
+/**
+ * 开放接口调用日志仓储。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+public interface SysOapiLogRepository extends JpaRepository<SysOapiLog, Long>,
+        JpaSpecificationExecutor<SysOapiLog> {
+
+    /**
+     * 按日志级别 + 创建时间批量删除（单条 DELETE 语句，不先加载实体）。<br>
+     * 用于定时清理：一般日志保留 12 个月，重要/次要日志保留 36 个月。<br>
+     *
+     * @param logLevel   日志级别编码
+     * @param createTime 截止时间（早于该时间的记录被删除）
+     * @return 删除条数
+     */
+    long deleteByLogLevelAndCreateTimeBefore(Integer logLevel, LocalDateTime createTime);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysOperationLogRepository.java b/src/main/java/com/yunhai/userbase/repository/SysOperationLogRepository.java
new file mode 100644
index 0000000..d8faaac
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysOperationLogRepository.java
@@ -0,0 +1,27 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysOperationLog;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.time.LocalDateTime;
+
+/**
+ * 系统操作日志仓储。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+public interface SysOperationLogRepository extends JpaRepository<SysOperationLog, Long>,
+        JpaSpecificationExecutor<SysOperationLog> {
+
+    /**
+     * 按日志级别 + 创建时间批量删除（单条 DELETE 语句，不先加载实体）。<br>
+     * 用于定时清理：一般日志保留 6 个月，重要/次要日志保留 12 个月。<br>
+     *
+     * @param logLevel    日志级别编码
+     * @param createTime  截止时间（早于该时间的记录被删除）
+     * @return 删除条数
+     */
+    long deleteByLogLevelAndCreateTimeBefore(Integer logLevel, LocalDateTime createTime);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysUserAppRoleRelRepository.java b/src/main/java/com/yunhai/userbase/repository/SysUserAppRoleRelRepository.java
new file mode 100644
index 0000000..82b7231
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysUserAppRoleRelRepository.java
@@ -0,0 +1,51 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysUserAppRoleRel;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 用户-业务角色关系仓储。<br>
+ */
+public interface SysUserAppRoleRelRepository extends JpaRepository<SysUserAppRoleRel, Integer>, JpaSpecificationExecutor<SysUserAppRoleRel> {
+
+    List<SysUserAppRoleRel> findByUserId(Integer userId);
+
+    List<SysUserAppRoleRel> findByRoleId(Integer roleId);
+
+    /**
+     * 按角色ID批量物理删除绑定记录（bulk delete 直接发 SQL）。<br>
+     * 用于「角色绑定用户」全量覆盖式保存的先删后插，以及删除角色时级联清理。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysUserAppRoleRel r WHERE r.roleId = :roleId")
+    void deleteByRoleIdBulk(@Param("roleId") Integer roleId);
+
+    /**
+     * 按角色ID集合批量物理删除绑定记录（删除应用时级联清理该应用下角色）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysUserAppRoleRel r WHERE r.roleId IN :roleIds")
+    void deleteByRoleIdInBulk(@Param("roleIds") List<Integer> roleIds);
+
+    /**
+     * 按用户ID批量物理删除绑定记录（「用户绑定角色」全量覆盖保存 + 删除用户时级联清理）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysUserAppRoleRel r WHERE r.userId = :userId")
+    void deleteByUserIdBulk(@Param("userId") Integer userId);
+
+    /**
+     * 按角色ID + 用户ID 删除单条绑定记录（移除单个用户的角色关联，避免全量重提）。<br>
+     */
+    @Modifying
+    @Query("DELETE FROM SysUserAppRoleRel r WHERE r.roleId = :roleId AND r.userId = :userId")
+    void deleteByRoleIdAndUserId(@Param("roleId") Integer roleId, @Param("userId") Integer userId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysUserCurrentRoleRepository.java b/src/main/java/com/yunhai/userbase/repository/SysUserCurrentRoleRepository.java
new file mode 100644
index 0000000..bd79400
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysUserCurrentRoleRepository.java
@@ -0,0 +1,17 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysUserCurrentRole;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/8/18
+ * @description 用户当前激活身份仓储（一对一：user_id 唯一）
+ */
+public interface SysUserCurrentRoleRepository extends JpaRepository<SysUserCurrentRole, Integer>, JpaSpecificationExecutor<SysUserCurrentRole> {
+
+    Optional<SysUserCurrentRole> findByUserId(Integer userId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysUserGroupRelRepository.java b/src/main/java/com/yunhai/userbase/repository/SysUserGroupRelRepository.java
new file mode 100644
index 0000000..0a53aff
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysUserGroupRelRepository.java
@@ -0,0 +1,34 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 组用户关联仓储（用于删除组/用户时校验关联数据）
+ */
+public interface SysUserGroupRelRepository extends JpaRepository<SysUserGroupRel, Integer>, JpaSpecificationExecutor<SysUserGroupRel> {
+
+    long countByGroupId(Integer groupId);
+
+    long countByUserId(Integer userId);
+
+    List<SysUserGroupRel> findByUserId(Integer userId);
+
+    List<SysUserGroupRel> findByUserIdIn(List<Integer> userIds);
+
+    List<SysUserGroupRel> findByUserIdInAndGroupId(List<Integer> userIds, Integer groupId);
+
+    Optional<SysUserGroupRel> findByUserIdAndGroupId(Integer userId, Integer groupId);
+
+    List<SysUserGroupRel> findByGroupId(Integer groupId);
+
+    void deleteByUserId(Integer userId);
+
+    void deleteByUserIdAndGroupId(Integer userId, Integer groupId);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysUserRepository.java b/src/main/java/com/yunhai/userbase/repository/SysUserRepository.java
new file mode 100644
index 0000000..015d584
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysUserRepository.java
@@ -0,0 +1,86 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysUser;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户仓储
+ */
+public interface SysUserRepository extends JpaRepository<SysUser, Integer>, JpaSpecificationExecutor<SysUser> {
+
+    long countByAccount(String account);
+
+    long countByAccountAndIdNot(String account, Integer id);
+
+    /** 按登录账号（username）查用户，供用户中心组装 BoaUser。 */
+    SysUser findByAccount(String account);
+
+    /** 按手机号查用户，供用户中心组装 BoaUser。 */
+    SysUser findByPhone(String phone);
+
+    /**
+     * 组上下文列表专用分页（原生 SQL）。<br>
+     * INNER JOIN 关联表后按 user_id 聚合（GROUP BY u.id），以「组内最小 sort_no」为排序键
+     * （NULLS LAST + sort_no 升序 + user_id 兜底升序）。GROUP BY 天然去重，规避 MySQL 的
+     * DISTINCT+ORDER BY 限制与 Hibernate 不支持 ORDER BY 标量子查询的限制。<br>
+     * 入参 name / disabled 为可空：为空（NULL）时该过滤条件整体跳过。
+     */
+    @Query(value =
+            "SELECT u.id AS userId, MIN(r.sort_no) AS minSortNo " +
+            "FROM sys_user u " +
+            "INNER JOIN sys_user_group_rel r ON r.user_id = u.id " +
+            "WHERE r.group_id IN (:groupIds) " +
+            "  AND (:name IS NULL OR u.username LIKE CONCAT('%', :name, '%') " +
+            "       OR u.real_name LIKE CONCAT('%', :name, '%') " +
+            "       OR u.idcard LIKE CONCAT('%', :name, '%') " +
+            "       OR u.phone = :name) " +
+            "  AND (:disabled IS NULL OR u.disabled = :disabled) " +
+            "GROUP BY u.id " +
+            "ORDER BY CASE WHEN MIN(r.sort_no) IS NULL THEN 1 ELSE 0 END, MIN(r.sort_no) ASC, u.id ASC",
+            countQuery =
+            "SELECT COUNT(DISTINCT u.id) " +
+            "FROM sys_user u " +
+            "INNER JOIN sys_user_group_rel r ON r.user_id = u.id " +
+            "WHERE r.group_id IN (:groupIds) " +
+            "  AND (:name IS NULL OR u.username LIKE CONCAT('%', :name, '%') " +
+            "       OR u.real_name LIKE CONCAT('%', :name, '%') " +
+            "       OR u.idcard LIKE CONCAT('%', :name, '%') " +
+            "       OR u.phone = :name) " +
+            "  AND (:disabled IS NULL OR u.disabled = :disabled)",
+            nativeQuery = true)
+    Page<Object[]> findGroupUserPage(@Param("groupIds") List<Integer> groupIds,
+                                     @Param("name") String name,
+                                     @Param("disabled") Integer disabled,
+                                     Pageable pageable);
+
+    /**
+     * 组上下文导出专用（原生 SQL，非分页）：INNER JOIN 关联表后按 user_id 聚合，
+     * 仅返回「属于指定组范围」的用户（无组归属的用户天然被排除）；超管(type=1)豁免
+     * （type 为 NULL 视为非超管，一并保留）。入参 name 为可空：为空时跳过关键字过滤。
+     * 排序按 user_id 升序，保证导出结果稳定。
+     */
+    @Query(value =
+            "SELECT u.id " +
+            "FROM sys_user u " +
+            "INNER JOIN sys_user_group_rel r ON r.user_id = u.id " +
+            "WHERE r.group_id IN (:groupIds) " +
+            "  AND (:name IS NULL OR u.username LIKE CONCAT('%', :name, '%') " +
+            "       OR u.real_name LIKE CONCAT('%', :name, '%') " +
+            "       OR u.idcard LIKE CONCAT('%', :name, '%') " +
+            "       OR u.phone = :name) " +
+            "  AND (u.type IS NULL OR u.type != 1) " +
+            "GROUP BY u.id " +
+            "ORDER BY u.id ASC",
+            nativeQuery = true)
+    List<Integer> findGroupUserIds(@Param("groupIds") List<Integer> groupIds,
+                                   @Param("name") String name);
+}
diff --git a/src/main/java/com/yunhai/userbase/repository/SysUserRoleRelRepository.java b/src/main/java/com/yunhai/userbase/repository/SysUserRoleRelRepository.java
new file mode 100644
index 0000000..44b7af7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/repository/SysUserRoleRelRepository.java
@@ -0,0 +1,39 @@
+package com.yunhai.userbase.repository;
+
+import com.yunhai.userbase.entity.SysUserRoleRel;
+import com.yunhai.userbase.enums.StatusEnum;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * @author chenx
+ * @date 2026/8/18
+ * @description 用户-SysRoleEnum角色-学校 关联仓储（平台身份角色权威源）
+ */
+public interface SysUserRoleRelRepository extends JpaRepository<SysUserRoleRel, Integer>, JpaSpecificationExecutor<SysUserRoleRel> {
+
+    /** 用户全部可选身份（含禁用态由调用方过滤） */
+    List<SysUserRoleRel> findByUserId(Integer userId);
+
+    /** 用户某状态下的全部可选身份 */
+    List<SysUserRoleRel> findByUserIdAndStatus(Integer userId, StatusEnum status);
+
+    /** 用户主身份（isMain=1），最多 1 条 */
+    Optional<SysUserRoleRel> findByUserIdAndIsMain(Integer userId, Integer isMain);
+
+    /** 用户在某学校下、某状态下的全部角色关联 */
+    List<SysUserRoleRel> findByUserIdAndSchoolIdAndStatus(Integer userId, Integer schoolId, StatusEnum status);
+
+    /** 用户所有正常态的 roleId 去重列表（用于 BoaUser.roleIds） */
+    @Query("SELECT DISTINCT r.roleId FROM SysUserRoleRel r WHERE r.userId = :userId AND r.status = :status")
+    List<Integer> findDistinctRoleIdsByUserIdAndStatus(@Param("userId") Integer userId, @Param("status") StatusEnum status);
+
+    /** 用户所有正常态的 schoolId 去重列表（用于 BoaUser.schools，schoolId>0 的过滤在调用方做） */
+    @Query("SELECT DISTINCT r.schoolId FROM SysUserRoleRel r WHERE r.userId = :userId AND r.status = :status")
+    List<Integer> findDistinctSchoolIdsByUserIdAndStatus(@Param("userId") Integer userId, @Param("status") StatusEnum status);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/IAppCategoryService.java b/src/main/java/com/yunhai/userbase/service/IAppCategoryService.java
new file mode 100644
index 0000000..13772b4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/IAppCategoryService.java
@@ -0,0 +1,52 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.platform.utils.enums.ClientEnum;
+import com.yunhai.platform.utils.model.BoaAppType;
+import com.yunhai.userbase.entity.AppCategory;
+import com.yunhai.userbase.model.appauthz.AppAuthzCategoryVo;
+import com.yunhai.userbase.model.appcategory.AppCategoryQuery;
+import com.yunhai.userbase.model.appcategory.AppCategoryRequest;
+import com.yunhai.userbase.model.appcategory.AppCategoryVo;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 21:30
+ * @description
+ */
+public interface IAppCategoryService {
+
+    void add(AppCategoryRequest request);
+
+    void edit(Integer id, AppCategoryRequest request);
+
+    void delete(Integer id);
+
+    List<AppCategoryVo> list(AppCategoryQuery query);
+
+    void sort(List<Integer> ids);
+
+    /**
+     * 应用授权用：获取所有应用类型及其类型下的应用（id/name/icon）。<br>
+     * 类型按 sortNo 升序，类型内应用按 sortNo、id 升序；无应用的类型 app 为空数组。<br>
+     *
+     * @return 应用类型 + 应用列表的授权视图
+     */
+    List<AppAuthzCategoryVo> listWithApps();
+
+    /**
+     * 开放接口专用：按用户 + 客户端类型查询其有权访问的应用列表（按应用类型分组）。<br>
+     * 规则：<br>
+     * ① 权限过滤：仅返回该用户有权访问的应用（复用 {@code IGroupAuthzService.findUserAuthorizedAppIds}）；<br>
+     * ② 客户端过滤：仅返回支持该客户端类型的应用（{@code app.clients} 位掩码与 clientType 有交集；clients 为空视为不限端）；<br>
+     * ③ 不透出 appSecret。<br>
+     * 类型按 sortNo 升序，类型内应用按 sortNo、id 升序；无有权应用的类型 apps 为空数组。
+     *
+     * @param userId     用户ID
+     * @param clientType 客户端类型（null=不按端过滤）
+     * @return 应用类型 + 有权应用列表
+     */
+    List<BoaAppType> listBoaAppType(Integer userId, ClientEnum clientType);
+
+}
diff --git a/src/main/java/com/yunhai/userbase/service/IAppModuleService.java b/src/main/java/com/yunhai/userbase/service/IAppModuleService.java
new file mode 100644
index 0000000..aa0d1b7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/IAppModuleService.java
@@ -0,0 +1,23 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.model.appmodule.AppModuleQuery;
+import com.yunhai.userbase.model.appmodule.AppModuleRequest;
+import com.yunhai.userbase.model.appmodule.AppModuleVo;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块服务。<br>
+ */
+public interface IAppModuleService {
+
+    void add(AppModuleRequest request);
+
+    void edit(Integer id, AppModuleRequest request);
+
+    void delete(Integer id);
+
+    List<AppModuleVo> list(AppModuleQuery query);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/IAppRoleService.java b/src/main/java/com/yunhai/userbase/service/IAppRoleService.java
new file mode 100644
index 0000000..681240c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/IAppRoleService.java
@@ -0,0 +1,105 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.model.approle.AppRoleAuthzAppVo;
+import com.yunhai.userbase.model.approle.AppRoleModuleAssignRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserBindRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserVo;
+import com.yunhai.userbase.model.approle.SysAppRoleQuery;
+import com.yunhai.userbase.model.approle.SysAppRoleRequest;
+import com.yunhai.userbase.model.approle.SysAppRoleVo;
+import com.yunhai.userbase.model.approle.UserAppRoleBindRequest;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 应用业务角色服务（角色 CRUD + 角色模块授权 + 用户角色绑定）。<br>
+ */
+public interface IAppRoleService {
+
+    /**
+     * 分页查询角色列表（name 模糊、appId/allAppFlag/disabled 精确）。<br>
+     * 普通角色回填所属应用名称 appName。<br>
+     *
+     * @param query    查询条件
+     * @param pageable 分页参数
+     * @return 分页角色列表
+     */
+    Page<SysAppRoleVo> list(SysAppRoleQuery query, Pageable pageable);
+
+    /**
+     * 新增角色。<br>
+     * 规则：普通角色 allAppFlag=false 且 appId 必填（应用须存在），同应用下名称唯一；<br>
+     * 全应用角色 allAppFlag=true 且 appId 必须为空，全应用角色之间名称唯一。<br>
+     *
+     * @param request 角色入参
+     */
+    void add(SysAppRoleRequest request);
+
+    /**
+     * 编辑角色（可改 name/remark/disabled）。<br>
+     * 角色类型 allAppFlag 与所属应用 appId 不允许修改（修改会导致已授权模块越界），需删除后重建。<br>
+     * 重名校验规则与新增一致（排除自身）。<br>
+     *
+     * @param id      角色ID
+     * @param request 角色入参
+     */
+    void edit(Integer id, SysAppRoleRequest request);
+
+    /**
+     * 删除角色，并级联清理其模块授权记录与用户绑定记录（逻辑外键，无物理 FK）。<br>
+     *
+     * @param id 角色ID
+     */
+    void delete(Integer id);
+
+    /**
+     * 角色模块授权页回显：返回该角色可授权的应用及其模块树，已授权模块 checked=true。<br>
+     * 普通角色仅返回其所属应用；全应用角色返回系统全部应用（可跨应用授权）。<br>
+     *
+     * @param roleId 角色ID
+     * @return 应用列表（含模块权限树）
+     */
+    List<AppRoleAuthzAppVo> findRoleModuleTree(Integer roleId);
+
+    /**
+     * 角色模块授权保存：全量覆盖式更新 sys_app_role_module_rel（bulk 先删后插）。<br>
+     * 校验：模块必须存在；普通角色只能授权其所属应用下的模块，越权写其他应用的模块会被拒绝。<br>
+     *
+     * @param request 角色ID + 勾选的模块ID全量列表
+     */
+    void saveRoleModules(AppRoleModuleAssignRequest request);
+
+    /**
+     * 查询角色已绑定的用户列表。<br>
+     *
+     * @param roleId 角色ID
+     * @return 用户列表
+     */
+    List<AppRoleUserVo> findRoleUsers(Integer roleId);
+
+    /**
+     * 角色绑定用户保存（角色维度，全量覆盖）：bulk 先删该角色全部绑定再批量插入。<br>
+     *
+     * @param request 角色ID + 用户ID全量列表
+     */
+    void saveRoleUsers(AppRoleUserBindRequest request);
+
+    /**
+     * 用户绑定角色保存（用户维度，全量覆盖）：bulk 先删该用户全部绑定再批量插入。<br>
+     *
+     * @param request 用户ID + 角色ID全量列表
+     */
+    void saveUserRoles(UserAppRoleBindRequest request);
+
+    /**
+     * 移除单个用户与角色的绑定关系（精确删除单条记录，非全量重提）。<br>
+     *
+     * @param roleId 角色ID
+     * @param userId 用户ID
+     */
+    void removeRoleUser(Integer roleId, Integer userId);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/IApplicationInfoService.java b/src/main/java/com/yunhai/userbase/service/IApplicationInfoService.java
new file mode 100644
index 0000000..08d31c0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/IApplicationInfoService.java
@@ -0,0 +1,104 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.application.ApplicationInfoQuery;
+import com.yunhai.userbase.model.application.ApplicationInfoRequest;
+import com.yunhai.userbase.model.application.ApplicationInfoSortVo;
+import com.yunhai.userbase.model.application.ApplicationInfoVo;
+import com.yunhai.userbase.model.application.PushSettingRequest;
+import com.yunhai.userbase.model.application.PushSettingVo;
+
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import java.util.List;
+
+/**
+ * 应用信息业务接口（缓存由 Spring Cache 注解统一管控）。
+ */
+public interface IApplicationInfoService {
+
+    /**
+     * 根据 id 查询应用信息（带缓存，防击穿）。
+     */
+    ApplicationInfo getById(Integer id);
+
+    /**
+     * 保存/更新应用信息（写后同步更新缓存）。
+     */
+    ApplicationInfo save(ApplicationInfo info);
+
+    /**
+     * 根据 id 删除应用信息（同步清除缓存）。
+     */
+    void deleteById(Integer id);
+
+    /**
+     * 新增应用信息。<br>
+     * 由入参构造实体并落库；appKey 为整型，从 100000 起按数据库最大值自增，appSecret 为 32 位 UUID。<br>
+     *
+     * @param request 应用新增入参
+     */
+    void add(ApplicationInfoRequest request);
+
+    /**
+     * 编辑应用信息。<br>
+     * 按 id 查找后拷贝入参字段并保存，appKey/appSecret 不随编辑变更。<br>
+     *
+     * @param id 应用ID
+     * @param request 应用编辑入参
+     */
+    void edit(Integer id, ApplicationInfoRequest request);
+
+    /**
+     * 根据 id 删除应用信息。<br>
+     *
+     * @param id 应用ID
+     */
+    void delete(Integer id);
+
+    /**
+     * 重设应用密钥（appSecret）。<br>
+     * 按 id 查找应用并生成新的 32 位 UUID 密钥后保存。<br>
+     *
+     * @param id 应用ID
+     */
+    void resetAppSecret(Integer id);
+
+    /**
+     * 根据条件分页查询应用列表。<br>
+     *
+     * @param query    查询条件（name 关键词按名称模糊或 appKey 精确匹配，categoryId 按类别精确匹配）
+     * @param pageable 分页参数（page 从 0 起，size 每页条数）
+     * @return 分页后的应用视图（含总条数 totalElements）
+     */
+    Page<ApplicationInfoVo> list(ApplicationInfoQuery query, Pageable pageable);
+
+    List<ApplicationInfoSortVo> findListByCategoryId(Integer categoryId);
+
+    /**
+     * 同一应用类型内排序。<br>
+     * 入参为该类型下应用的完整有序 id 列表，按列表顺序写入 sortNo（1 起）。<br>
+     * 接口会额外校验：所有 id 必须存在且同属一个应用类型，避免跨类型串号导致排序错乱。<br>
+     *
+     * @param ids 同一应用类型下的应用ID有序列表
+     */
+    void sort(List<Integer> ids);
+
+    /**
+     * 保存应用推送设置（外部接口地址 / 总开关 / 启用的接口 / 学校范围 / 角色范围 / 推送密钥）。<br>
+     * 仅更新推送相关字段，写后同步更新 appInfo 缓存。
+     *
+     * @param id 应用ID
+     * @param request 推送设置（各字段可选，null 表示不修改）
+     */
+    ApplicationInfo savePushSetting(Integer id, PushSettingRequest request);
+
+    /**
+     * 获取应用推送设置回显 VO。
+     *
+     * @param id 应用ID
+     * @return 推送设置 VO（仅含推送相关字段）
+     */
+    PushSettingVo getPushSetting(Integer id);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/IGroupAuthzService.java b/src/main/java/com/yunhai/userbase/service/IGroupAuthzService.java
new file mode 100644
index 0000000..95ef9c6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/IGroupAuthzService.java
@@ -0,0 +1,190 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.platform.utils.model.BoaModule;
+import com.yunhai.userbase.model.groupauthz.*;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组应用权限服务（应用开通 + 组授权 + 权限判定）。<br>
+ */
+public interface IGroupAuthzService {
+
+    /**
+     * 功能1回显：查询系统全量应用列表，并标记该组已开通的应用（checked）。<br>
+     *
+     * @param groupId 组ID
+     * @return 全量应用列表（含开通勾选状态）
+     */
+    List<GroupAppVo> listGroupApps(Integer groupId);
+
+    /**
+     * 功能1保存：全量覆盖式更新组的应用开通记录（先删旧记录再批量插入）。<br>
+     * 被取消开通的应用，同步清理该组在其模块上的权限记录，避免残留脏数据。<br>
+     *
+     * @param request 组ID + 勾选的应用ID全量列表
+     */
+    void assignAppsToGroup(GroupAppAssignRequest request);
+
+    /**
+     * 功能2数据加载：查询该组已开通的应用及其模块树，并回显勾选状态与子组继承开关。<br>
+     * 仅返回 sys_group_app_rel 中有记录的应用；未开通的应用不显示。<br>
+     *
+     * @param groupId 组ID
+     * @return 已开通应用列表（含模块权限树）
+     */
+    List<GroupAuthzAppVo> findGroupAppsWithModules(Integer groupId);
+
+    /**
+     * 功能2数据加载（按应用分类分组版）：与 {@link #findGroupAppsWithModules(Integer)} 数据一致，<br>
+     * 但按应用类型分类聚合，便于组授权页面按分类面板展示。<br>
+     * 返回全部分类（含空数组），保证前端分类筛选下拉完整。<br>
+     *
+     * @param groupId 组ID
+     * @return 按应用分类分组的已开通应用列表
+     */
+    List<GroupAuthzCategoryVo> findGroupAppsWithModulesByCategory(Integer groupId);
+
+    /**
+     * 功能2保存：全量覆盖式更新组的模块权限。<br>
+     * 有旧记录则更新 inheritFlag，无则新增，不在传入列表中的旧记录物理删除。<br>
+     *
+     * @param request 组ID + 勾选的模块权限全量列表（moduleId + inheritFlag）
+     */
+    void saveModulePermissions(GroupModulePermRequest request);
+
+    /**
+     * 权限判定（供登录/拦截器使用）：判断用户对某模块是否有权限。<br>
+     * 规则：用户任一所属组，沿祖先链回溯——自身显式勾选即通过；祖先勾选且 inheritFlag=true 即通过。<br>
+     * 前置校验：该所属组必须已开通模块所属应用（最终权限 = 继承的模块权限 ∩ 该组已开通的应用）。<br>
+     * 角色授权并集：用户经「启用状态」业务角色获得该模块授权也通过，且不要求组已开通模块所属应用；禁用角色不参与判定。<br>
+     *
+     * @param userId   用户ID
+     * @param moduleId 模块ID
+     * @return true=有权限
+     */
+    boolean hasModulePermission(Integer userId, Integer moduleId);
+
+    /**
+     * 权限一览：查询指定组下的直接用户列表（不含子组，不分页）。<br>
+     *
+     * @param groupId 组ID
+     * @return 用户列表
+     */
+    List<UserPermissionUserVo> findGroupUsers(Integer groupId);
+
+    /**
+     * 权限一览：全局搜索用户（按账号/姓名/身份证模糊、手机号精确匹配），不分页。<br>
+     * 返回用户及其主归属部门/组织路径。
+     *
+     * @param keyword 搜索关键字
+     * @return 用户列表
+     */
+    List<UserPermissionUserVo> searchUsers(String keyword);
+
+    /**
+     * 权限一览：根据用户ID聚合该用户的全部已授权应用模块树。<br>
+     * 只返回<b>有授权模块</b>的应用，并按应用类型分组；无授权的应用类型和应用不显示。<br>
+     * 权限判定复用 {@link #hasModulePermission(Integer, Integer)} 的祖先链继承逻辑。<br>
+     * 角色授权并集：最终模块权限 = 组授权模块 ∪ 启用角色授权模块；<br>
+     * 最终应用范围 = 组开通应用 ∪ 角色模块所属应用（角色模块不要求组必须先开通应用）。<br>
+     *
+     * @param groupId 组ID（上下文，可选；目前仅用于校验用户存在性，实际聚合以 userId 为准）
+     * @param userId  用户ID
+     * @return 按应用类型分组的已授权应用模块树
+     */
+    List<UserPermissionCategoryVo> findUserPermissionTree(Integer groupId, Integer userId);
+
+    /**
+     * 权限一览：查询用户所属的业务角色列表（中间下方「所属角色」区域展示用）。<br>
+     * 返回该用户绑定的全部角色（含禁用角色，disabled 字段标记），普通角色回填所属应用名称。<br>
+     *
+     * @param userId 用户ID
+     * @return 用户所属角色列表
+     */
+    List<UserRoleVo> findUserRoles(Integer userId);
+
+    /**
+     * 权限一览：查询用户所属部门树（左侧上方「所属部门」区域展示用）。<br>
+     * 树仅由「用户直接归属的组 + 其全部祖先组」构成（如：云平台-学校中学-语文组），
+     * 多个归属组时合并为一棵树（公共祖先只出现一次）。<br>
+     *
+     * @param userId 用户ID
+     * @return 所属部门树（根节点列表）；用户无组归属时返回空列表
+     */
+    List<UserGroupNodeVo> findUserGroupTree(Integer userId);
+
+    /**
+     * 开放接口专用：查询用户在<b>指定调用方应用</b>下的已授权模块（扁平化 BoaModule 列表）。<br>
+     * 与 {@link #findUserPermissionTree(Integer, Integer)} 的核心差别：<br>
+     * - 后者返回用户在全部已开通应用下的权限聚合（供管理端权限一览使用）；<br>
+     * - 本方法只返回 {@code appId} 对应这一个应用下的模块，所有 SQL/集合构建均限定该应用（数据库层面过滤）。<br>
+     * <br>
+     * 上下文组（schId）语义与开放接口一致：schId 非空=只认该组链路；schId 为空=取用户主学校组（若仍空=用户主归属组 id）。<br>
+     * 超级管理员：不做组/继承判定，直接返回该应用下全部模块（但仍只返回该应用，不会跨应用返回）。<br>
+     * 角色授权并集：最终权限 = 组授权模块 ∪ 启用角色下属于该应用的模块（逻辑与权限一览保持一致）。
+     *
+     * @param appId  调用方应用ID（必填；查不到或该应用无开通=返回空列表）
+     * @param schId  学校/组上下文（可选；为 null 时按"主学校→主归属组"规则推断）
+     * @param userId 用户ID（必填）
+     * @return 该应用下用户有权限的模块（扁平化；无权限时返回空列表）
+     */
+    List<BoaModule> findUserModulesForApp(Integer appId, Integer schId, Integer userId);
+
+    // ===================== 新增：树节点式增量授权（供左侧树 + 右侧 appAuthzList 的勾选交互） =====================
+
+    /**
+     * 获取某组「已开通的应用ID列表」，供前端右侧应用清单回显勾选状态。<br>
+     * <b>实现思路</b>：应用开通「不继承」（见 SysGroupAppRel 设计）——直接查 sys_group_app_rel 中 group_id=nodeId 的记录，<br>
+     * 返回其 app_id 集合；<b>不</b>沿祖先链回填父组开通的应用（父组开通不代表子组自动拥有）。<br>
+     * 与现有 GroupAppList（返回全量应用 + checked）的区别：本接口只返回已选 id 列表，更轻量，适合做勾选回显。
+     *
+     * @param nodeId 左侧树点击的组节点ID
+     * @return 该组已开通的应用ID列表（无则空列表）
+     */
+    List<Integer> findAuthorizedAppIds(Integer nodeId);
+
+    /**
+     * 增量设置某组的应用开通/取消（对应前端「应用多选框」勾选/取消）。<br>
+     * <b>入参</b>：{@link SchoolAppAuthzRequest} 封装 schid / appids(逗号分隔字符串) / mode。<br>
+     * <b>实现思路</b>：<br>
+     * - mode=0(追加/APPEND)：对 appids 中每个应用，若 sys_group_app_rel 尚无记录则插入（已存在则跳过，幂等）。<br>
+     * - mode=2(删除/DELETE)：对每个应用删除开通记录，并<b>同步清理该组在该应用下模块的权限残留</b>（与现有 assignAppsToGroup 取消开通时行为一致，避免脏数据）。<br>
+     * - 应用开通「不继承」，故<b>仅操作传入的 schId 自身，不做子组级联</b>。<br>
+     * - mode=1(覆盖) 不适用于单条增量，直接拒绝。
+     *
+     * @param request 学校组应用授权请求（组ID + 应用ID字符串 + 操作模式）
+     */
+    void setSchoolApps(SchoolAppAuthzRequest request);
+
+    /**
+     * 增量设置「组-应用-模块」的模块授权（对应前端「组授权」面板逐条勾选/取消）。<br>
+     * <b>实现思路</b>：逐条处理 items 列表（顺序即执行顺序，后者覆盖前者）：<br>
+     * - mode=0(追加)：对 (groupId, 展开后的 moduleId) upsert 一条 sys_group_module_perm，inherit_flag=isAll。<br>
+     * - mode=2(删除)：删除对应权限记录。<br>
+     * - moduleId=0 表示「该应用下全部模块」，展开为应用下每个真实模块各写/删一条（不写 module_id=0 伪记录）。<br>
+     * - <b>isAll 的语义（重点）</b>：直接映射现有 sys_group_module_perm.inherit_flag 列。<br>
+     *   &nbsp;&nbsp;isAll=1 → inherit_flag=true：子孙组在 hasModulePermission 判定时沿祖先链自动继承该模块权限（逻辑继承，不物理写子组）；<br>
+     *   &nbsp;&nbsp;isAll=0 → inherit_flag=false：仅本组生效。<br>
+     *   这与「应用不继承 / 模块可继承」的对称性一致，且复用现有权限判定逻辑，不破坏其他功能。<br>
+     * - 越权防护：模块必须属于该 appId；追加前要求该组已开通该应用（与现有 SaveModulePerms 边界一致）。<br>
+     * <br>
+     * <i>若产品实际想要「物理写子组」（子组各存一条 perm，而非逻辑继承），把 isAll=1 分支改成「对 groupId + 其全部子孙组分别 upsert」即可，详见实现类注释。</i>
+     *
+     * @param items 模块授权条目列表（groupId/appId/moduleId/mode/isAll）
+     */
+    void setGroupModulePerms(List<GroupModuleAuthzItem> items);
+
+    /**
+     * 查询用户有权访问的应用ID集合（oapi 开放接口 getUserApp 权限过滤用）。<br>
+     * 规则与 {@link #hasModulePermission(Integer, Integer)} 对齐：<br>
+     * - 超级管理员：全部应用；<br>
+     * - 普通用户：用户所属组（沿祖先链）开通的应用 ∪ 启用角色模块所属应用。<br>
+     *
+     * @param userId 用户ID
+     * @return 有权应用ID列表（无则空列表）
+     */
+    List<Integer> findUserAuthorizedAppIds(Integer userId);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/ISysGroupService.java b/src/main/java/com/yunhai/userbase/service/ISysGroupService.java
new file mode 100644
index 0000000..37d665a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/ISysGroupService.java
@@ -0,0 +1,113 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.model.sysgroup.SysGroupBatchRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupMoveRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupQuery;
+import com.yunhai.userbase.model.sysgroup.SysGroupRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupSortRequest;
+import com.yunhai.platform.utils.model.BoaGroup;
+import com.yunhai.userbase.model.sysgroup.SysGroupVo;
+
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组服务接口
+ */
+public interface ISysGroupService {
+
+    BoaGroup add(SysGroupRequest request);
+
+    BoaGroup edit(Integer id, SysGroupRequest request);
+
+    void delete(Integer id);
+
+    /**
+     * 开放接口专用：在学校（组）范围内删除组。<br>
+     * 与 {@link #delete(Integer)} 删除逻辑一致，但额外强制边界：<br>
+     * ① id 不能等于 schoolId（禁止删学校根组）；<br>
+     * ② id 必须属于 schoolId 子树（禁止跨校删组）。<br>
+     * 任意一条不满足即抛异常。
+     *
+     * @param id       待删除组ID
+     * @param schoolId 学校组ID（限定删除范围）
+     */
+    void delete(Integer id, Integer schoolId);
+
+    /**
+     * 开放接口通用：校验学校锚点 schoolId 合法——非空、存在、且必须为学校组(SCHOOL_GROUP)。<br>
+     * 供 delete/move/用户组关系等带 schoolId 边界的开放接口统一调用。
+     *
+     * @param schoolId 学校组ID（限定范围）
+     */
+    void assertSchoolId(Integer schoolId);
+
+    List<SysGroupVo> list(SysGroupQuery query);
+
+    /** 获取组织架构树；表为空时自动创建根节点「教育云中心」(pid=0)。 */
+    List<SysGroupVo> getTree();
+
+    /**
+     * 获取「学校组」剪枝树：末端叶子一定是学校组。<br>
+     * 规则：遇到学校组即截断（学校组作为叶子，其下所有组不显示）；<br>
+     * 子树中不含任何学校组的非学校组节点整体剪掉；根节点始终保留。<br>
+     */
+    List<SysGroupVo> getSchoolTree();
+
+    /** 在指定父组下按规则批量生成子组。 */
+    List<BoaGroup> batchAdd(SysGroupBatchRequest request);
+
+    /** 对 pid 的直接子节点按给定顺序重排并落库（ids 必须全是直接子节点）。 */
+    void sortChildren(SysGroupSortRequest request);
+
+    /** 将 moveId 移动到 pid 下（环检测）。 */
+    void move(SysGroupMoveRequest request);
+
+    /**
+     * 开放接口专用：在学校（组）范围内移动组。<br>
+     * 与 {@link #move(SysGroupMoveRequest)} 移动逻辑一致，但额外强制边界：<br>
+     * ① moveId 不能等于 schoolId（禁止移动学校根组）；<br>
+     * ② pid 不能是平台根(0)（禁止移出学校范围）；<br>
+     * ③ moveId 与 pid 都必须属于 schoolId 子树（禁止跨校移动）。<br>
+     *
+     * @param request  待移动节点 moveId + 目标父节点 pid
+     * @param schoolId 学校组ID（限定移动范围）
+     */
+    void move(SysGroupMoveRequest request, Integer schoolId);
+
+    /**
+     * 收集指定组自身及其所有子孙组的ID（沿 parentId 向下遍历）。<br>
+     * 用于「查询该节点及其子组下所有用户」等子树聚合场景。<br>
+     *
+     * @param groupId 组ID
+     * @return 含自身在内的组ID集合；组不存在时返回仅含自身的集合
+     */
+    List<Integer> listSelfAndDescendantIds(Integer groupId);
+
+    /**
+     * 获取整个平台的组树：从根节点（pid=0）开始，children 递归嵌套全部后代。<br>
+     * 根节点唯一，取最小 id 作为树入口。表为空时返回 null。
+     */
+    BoaGroup getGroups();
+
+    /**
+     * 获取单个组；withSub=true 时递归挂上全部子孙（整棵子树），false/不传时只返回节点本身（children 为 null）。<br>
+     * 组不存在时返回 null。
+     *
+     * @param groupId 组ID
+     * @param withSub 是否展开子节点，缺省 false
+     * @return 组节点（BoaGroup）
+     */
+    BoaGroup getGroupById(Integer groupId, Boolean withSub);
+
+    /**
+     * 批量获取组；ids 逗号/空格分隔，按入参顺序返回，不存在的 id 跳过。<br>
+     * withSub 语义同 {@link #getGroupById(Integer, Boolean)}。
+     *
+     * @param ids     组ID列表（逗号/空格分隔）
+     * @param withSub 是否展开子节点，缺省 false
+     * @return 组节点列表（按入参顺序；不存在的跳过）
+     */
+    List<BoaGroup> getGroupList(String ids, Boolean withSub);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/ISysOapiLogService.java b/src/main/java/com/yunhai/userbase/service/ISysOapiLogService.java
new file mode 100644
index 0000000..293c7d4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/ISysOapiLogService.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.entity.SysOapiLog;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oapilog.SysOapiLogListVo;
+import com.yunhai.userbase.model.oapilog.SysOapiLogQuery;
+
+/**
+ * 开放接口调用日志业务接口。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+public interface ISysOapiLogService {
+
+    /**
+     * 异步保存开放接口日志。<br>
+     * 由 OapiLogAspect 在 finally 中调用，失败仅记录日志，不影响主业务。<br>
+     *
+     * @param entity 日志实体
+     */
+    void saveAsync(SysOapiLog entity);
+
+    /**
+     * 分页查询开放接口日志列表。<br>
+     * 列表不含响应结果(response_data)，避免加载 MEDIUMBLOB 影响性能。<br>
+     *
+     * @param query     查询条件
+     * @param pageQuery 分页参数（pageIndex 从 1 起）
+     * @return 分页结果
+     */
+    BasePageResult<SysOapiLogListVo> pageQuery(SysOapiLogQuery query, BasePageQuery pageQuery);
+
+    /**
+     * 获取某条日志的响应结果（解压后原文）。<br>
+     *
+     * @param id 日志ID
+     * @return 解压后的响应字符串，无记录或无响应数据返回 null
+     */
+    String getResponseData(Long id);
+
+    /**
+     * 清理过期日志。<br>
+     * 一般日志(level=3)保留 12 个月，重要(level=1)/次要(level=2)保留 36 个月。<br>
+     *
+     * @return 删除条数
+     */
+    long cleanupExpired();
+}
diff --git a/src/main/java/com/yunhai/userbase/service/ISysOperationLogService.java b/src/main/java/com/yunhai/userbase/service/ISysOperationLogService.java
new file mode 100644
index 0000000..9808163
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/ISysOperationLogService.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.userbase.entity.SysOperationLog;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oplog.SysOperationLogListVo;
+import com.yunhai.userbase.model.oplog.SysOperationLogQuery;
+
+/**
+ * 系统操作日志业务接口。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+public interface ISysOperationLogService {
+
+    /**
+     * 异步保存操作日志。<br>
+     * 由 AOP 在 finally 中调用，失败仅记录日志，不影响主业务。<br>
+     *
+     * @param entity 日志实体
+     */
+    void saveAsync(SysOperationLog entity);
+
+    /**
+     * 分页查询操作日志列表。<br>
+     * 列表不含响应结果(response_data)，避免加载 MEDIUMBLOB 影响性能。<br>
+     *
+     * @param query    查询条件
+     * @param pageQuery 分页参数（pageIndex 从 1 起）
+     * @return 分页结果
+     */
+    BasePageResult<SysOperationLogListVo> pageQuery(SysOperationLogQuery query, BasePageQuery pageQuery);
+
+    /**
+     * 获取某条日志的响应结果（解压后原文）。<br>
+     *
+     * @param id 日志ID
+     * @return 解压后的响应字符串，无记录或无响应数据返回 null
+     */
+    String getResponseData(Long id);
+
+    /**
+     * 清理过期日志。<br>
+     * 一般日志(level=3)保留 6 个月，重要(level=1)/次要(level=2)保留 12 个月。<br>
+     *
+     * @return 删除条数
+     */
+    long cleanupExpired();
+}
diff --git a/src/main/java/com/yunhai/userbase/service/ISysUserService.java b/src/main/java/com/yunhai/userbase/service/ISysUserService.java
new file mode 100644
index 0000000..d3bb66f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/ISysUserService.java
@@ -0,0 +1,182 @@
+package com.yunhai.userbase.service;
+
+import com.yunhai.platform.utils.model.BoaRoleInfo;
+import com.yunhai.userbase.model.sysuser.BatchImportResult;
+import com.yunhai.userbase.model.sysuser.SysUserGroupDeleteItem;
+import com.yunhai.userbase.model.sysuser.SysUserQuery;
+import com.yunhai.userbase.model.sysuser.SysUserRequest;
+import com.yunhai.userbase.model.sysuser.SysUserVo;
+import org.springframework.web.multipart.MultipartFile;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.util.List;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户服务接口
+ */
+public interface ISysUserService {
+
+    /** 新增用户：校验密码/手机号/身份证，BCrypt 加密，并写入组用户关联。返回创建后的用户ID。 */
+    Integer add(SysUserRequest request);
+
+    /** 编辑用户；密码为空时不修改密码。 */
+    void edit(Integer id, SysUserRequest request);
+
+    /**
+     * 批量新增用户：逐条走完整校验（含密码强度），返回创建后的用户ID列表（顺序与入参一致）。
+     */
+    List<Integer> batchAdd(List<SysUserRequest> requests);
+
+    /**
+     * 把用户从指定组中移除；若移除后该用户已无其它组关联，则级联删除用户本身。
+     *
+     * @param userId  用户ID
+     * @param groupId 当前组ID
+     */
+    void deleteFromGroup(Integer userId, Integer groupId);
+
+    /**
+     * 批量把用户从指定组中移除；无其它组关联者级联删除用户本身。
+     *
+     * @param userIds 用户ID列表
+     * @param groupId 当前组ID
+     */
+    void batchDeleteFromGroup(List<Integer> userIds, Integer groupId);
+
+    /**
+     * 开放接口专用：在学校（组）范围内按组解绑用户。<br>
+     * 与 {@link #deleteFromGroup(Integer, Integer)} 语义一致，但额外强制边界：<br>
+     * ① groupId 不能等于 schoolId（禁止对学校根组解绑，避免整校移除）；<br>
+     * ② groupId 必须属于 schoolId 子树（禁止跨校解绑）。<br>
+     * 任意一条不满足即抛异常。
+     *
+     * @param userId   用户ID
+     * @param groupId  当前组ID
+     * @param schoolId 学校组ID（限定解绑范围）
+     */
+    void deleteFromGroup(Integer userId, Integer groupId, Integer schoolId);
+
+    /**
+     * 开放接口专用：批量删除用户-组关系；每条携带自身 (userId, groupId, schoolId)，逐条做上述学校边界校验后解绑。
+     *
+     * @param items 待删除项列表（{@link SysUserGroupDeleteItem}）
+     */
+    void deleteUsers(List<SysUserGroupDeleteItem> items);
+
+    /**
+     * 启用/禁用用户。<br>
+     *
+     * @param id       用户ID
+     * @param disabled true=禁用，false=启用
+     */
+    void changeStatus(Integer id, boolean disabled);
+
+    /**
+     * 批量启用/禁用用户。
+     *
+     * @param userIds  用户ID列表
+     * @param disabled true=禁用，false=启用
+     */
+    void batchChangeStatus(List<Integer> userIds, boolean disabled);
+
+    /**
+     * 分页查询组下用户。<br>
+     * 依据 query.groupId 与 query.withSub 决定组范围，query.name 做多字段匹配。<br>
+     *
+     * @param query    查询条件
+     * @param pageable 分页与排序
+     * @return 用户分页
+     */
+    Page<SysUserVo> list(SysUserQuery query, Pageable pageable);
+
+    /**
+     * 查询指定用户当前所属的所有组ID。
+     *
+     * @param userId 用户ID
+     * @return 组ID列表
+     */
+    List<Integer> findGroupIdsByUserId(Integer userId);
+
+    /**
+     * 批量调整用户所属组：覆盖式更新 sys_user_group_rel。<br>
+     * 同一批用户统一设置为目标组列表，第一个组设为主归属，其余为兼职。
+     *
+     * @param userIds  待调整用户ID列表
+     * @param groupIds 目标组ID列表
+     */
+    void changeGroups(List<Integer> userIds, List<Integer> groupIds);
+
+    /**
+     * 开放接口专用：在学校（组）范围内移动用户。<br>
+     * 语义同 {@link #changeGroups}（覆盖式把用户组归属替换为目标组，目标设为主组），但额外强制：<br>
+     * ① 用户当前必须已在该学校子树内（至少一个组归属落在 schoolId 子树）；<br>
+     * ② 目标 groupId 必须也在该学校子树内。<br>
+     * 任意一条不满足即抛异常，禁止跨校移动。
+     *
+     * @param userId   待移动用户ID
+     * @param groupId  目标组ID（移动后的主归属组）
+     * @param schoolId 学校组ID（限定移动范围，仅允许同校内移动）
+     */
+    void moveUserWithinSchool(Integer userId, Integer groupId, Integer schoolId);
+
+    /**
+     * 调整用户在某组内的排序号（sort_no）。<br>
+     * sortNo 为 null 时清除排序号，列表回退到 user_id 升序兜底。
+     *
+     * @param userId  用户ID
+     * @param groupId 组ID（排序号按组维度，必须落到具体组）
+     * @param sortNo  排序号（1~999），可空表示清除
+     */
+    void changeSortNo(Integer userId, Integer groupId, Integer sortNo);
+
+    /**
+     * 批量导入用户：按模板解析 Excel，逐行校验并新增。
+     * 失败行继续处理，返回成功/失败统计及失败原因。
+     *
+     * @param file Excel 文件
+     * @return 导入结果
+     */
+    BatchImportResult batchImport(MultipartFile file);
+
+    /**
+     * 下载用户批量导入模板（真实 .xlsx）：平铺指定组及其所有子孙组，仅填充组名(路径)与组id。
+     *
+     * @param groupId  当前组ID（可空，空则取组织树根）
+     * @param response 直接写入 Excel 流
+     */
+    void downloadImportTemplate(Integer groupId, HttpServletResponse response) throws IOException;
+
+    /**
+     * 导出组下所有用户（含子组）为 Excel：与导入模板同构，末尾追加「用户id」列。<br>
+     * 组名 / 组id 取每个用户实际所属的主组（isMain=1）；密码为密文不可逆，留空。
+     *
+     * @param groupId  当前组ID（可空，空则取组织树根）
+     * @param withSub  是否包含子组：1=含所有子孙组；其它=仅当前组
+     * @param name     关键字（可选）
+     * @param response 直接写入 Excel 流
+     */
+    void exportUsers(Integer groupId, Integer withSub, String name, HttpServletResponse response) throws IOException;
+
+    /**
+     * 查询用户的业务角色身份列表（oapi 开放接口专用）。
+     *
+     * @param userId 用户ID
+     * @return 角色身份列表（roleId/roleName + 主归属学校组上下文）
+     */
+    List<BoaRoleInfo> findUserRoles(Integer userId);
+
+    /**
+     * 修改用户密码：先校验旧密码，再写入新密码（BCrypt）。<br>
+     * oapi 开放接口专用；不加操作日志（避免明文密码入日志）。
+     *
+     * @param userId      用户ID
+     * @param oldPassword 旧密码（须与库中 BCrypt 密文匹配）
+     * @param newPassword 新密码（弱密码规则校验后加密写入）
+     */
+    void changePassword(Integer userId, String oldPassword, String newPassword);
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/AppCategoryService.java b/src/main/java/com/yunhai/userbase/service/impl/AppCategoryService.java
new file mode 100644
index 0000000..0fbbb21
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/AppCategoryService.java
@@ -0,0 +1,242 @@
+package com.yunhai.userbase.service.impl;
+
+
+import com.yunhai.platform.utils.enums.ClientEnum;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.model.BoaApp;
+import com.yunhai.platform.utils.model.BoaAppType;
+import com.yunhai.userbase.entity.AppCategory;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.appauthz.AppAuthzAppRow;
+import com.yunhai.userbase.model.appauthz.AppAuthzCategoryVo;
+import com.yunhai.userbase.model.appcategory.AppCategoryQuery;
+import com.yunhai.userbase.model.appcategory.AppCategoryRequest;
+import com.yunhai.userbase.model.appcategory.AppCategoryVo;
+import com.yunhai.userbase.repository.AppCategoryRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.service.IAppCategoryService;
+import com.yunhai.userbase.service.IGroupAuthzService;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * @author chenx
+ * @date 2026/7/15 21:30
+ * @description
+ */
+@Service
+public class AppCategoryService implements IAppCategoryService {
+    @Autowired
+    private AppCategoryRepository appCategoryRepository;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Autowired
+    private IGroupAuthzService groupAuthzService;
+
+
+    @Override
+    @Transactional
+    public void add(AppCategoryRequest request) {
+        // 重名校验：新增类别名称不允许重复
+        if (appCategoryRepository.existsByName(request.getName())) {
+            throw new DException("应用类型已存在");
+        }
+        AppCategory entity = new AppCategory();
+        entity.setName(request.getName());
+
+        if (request.getSortNo() == null) {
+            Integer maxSortNo = appCategoryRepository.findMaxSortNo();
+            entity.setSortNo(maxSortNo == null ? 1 : maxSortNo + 1);
+        } else {
+            entity.setSortNo(request.getSortNo());
+        }
+
+        appCategoryRepository.save(entity);
+    }
+
+    @Override
+    @Transactional
+    public void edit(Integer id, AppCategoryRequest request) {
+        AppCategory entity = appCategoryRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用类别不存在"));
+        // 重名校验：编辑时排除自身
+        if (appCategoryRepository.existsByNameAndIdNot(request.getName(), id)) {
+            throw new DException("应用类型已存在");
+        }
+        entity.setName(request.getName());
+        if (request.getSortNo() != null) {
+            entity.setSortNo(request.getSortNo());
+        }
+        appCategoryRepository.save(entity);
+    }
+
+    @Override
+    @Transactional
+    public void delete(Integer id) {
+        if (applicationInfoRepository.countByCategoryId(id) > 0) {
+            throw new RuntimeException("该类别下存在应用，无法删除");
+        }
+        appCategoryRepository.deleteById(id);
+    }
+
+    @Override
+    public List<AppCategoryVo> list(AppCategoryQuery query) {
+        List<AppCategory> list;
+        if (StringUtils.hasText(query.getName())) {
+            list = appCategoryRepository.findByNameContainingOrderBySortNoAsc(query.getName());
+        } else {
+            list = appCategoryRepository.findAllByOrderBySortNoAsc();
+        }
+        return list.stream().map(this::convertToVo).collect(Collectors.toList());
+    }
+
+    @Override
+    @Transactional
+    public void sort(List<Integer> ids) {
+        for (int i = 0; i < ids.size(); i++) {
+            if (!appCategoryRepository.existsById(ids.get(i))) {
+                throw new RuntimeException("类别不存在: " + ids.get(i));
+            }
+            appCategoryRepository.updateSortNoById(ids.get(i), i + 1);
+        }
+    }
+
+    @Override
+    public List<AppAuthzCategoryVo> listWithApps() {
+        List<AppCategory> categories = appCategoryRepository.findAllByOrderBySortNoAsc();
+        List<AppAuthzAppRow> rows = applicationInfoRepository.findAllAuthzRows();
+        // categoryId -> 该类型下应用列表（查询已按 sortNo、id 升序，插入顺序即排序）
+        Map<Integer, List<AppAuthzCategoryVo.AppItem>> appMap = new HashMap<>();
+        for (AppAuthzAppRow row : rows) {
+            AppAuthzCategoryVo.AppItem item = new AppAuthzCategoryVo.AppItem();
+            item.setId(row.getId());
+            item.setName(row.getName());
+            appMap.computeIfAbsent(row.getCategoryId(), k -> new ArrayList<>()).add(item);
+        }
+        List<AppAuthzCategoryVo> result = new ArrayList<>();
+        for (AppCategory category : categories) {
+            AppAuthzCategoryVo vo = new AppAuthzCategoryVo();
+            vo.setId(category.getId());
+            vo.setName(category.getName());
+            vo.setApp(appMap.getOrDefault(category.getId(), new ArrayList<>()));
+            result.add(vo);
+        }
+        return result;
+    }
+
+    private AppCategoryVo convertToVo(AppCategory entity) {
+        AppCategoryVo vo = new AppCategoryVo();
+        BeanUtils.copyProperties(entity, vo);
+        return vo;
+    }
+
+    @Override
+    public List<BoaAppType> listBoaAppType(Integer userId, ClientEnum clientType) {
+        Set<Integer> authorizedAppIds = new HashSet<>(groupAuthzService.findUserAuthorizedAppIds(userId));
+        List<AppCategory> categories = appCategoryRepository.findAllByOrderBySortNoAsc();
+        List<ApplicationInfo> apps = applicationInfoRepository.findAll();
+        apps.sort(Comparator.comparing(ApplicationInfo::getSortNo, Comparator.nullsLast(Integer::compareTo))
+                .thenComparing(ApplicationInfo::getId, Comparator.nullsLast(Integer::compareTo)));
+        // categoryId -> 该类型下应用列表（插入顺序即排序）
+        Map<Integer, List<ApplicationInfo>> appMap = new LinkedHashMap<>();
+        for (ApplicationInfo app : apps) {
+            if (app.getCategoryId() == null) {
+                continue;
+            }
+            appMap.computeIfAbsent(app.getCategoryId(), k -> new ArrayList<>()).add(app);
+        }
+        List<BoaAppType> result = new ArrayList<>();
+        for (AppCategory category : categories) {
+            BoaAppType type = new BoaAppType();
+            type.setId(category.getId());
+            type.setName(category.getName());
+            List<BoaApp> boaApps = new ArrayList<>();
+            for (ApplicationInfo app : appMap.getOrDefault(category.getId(), Collections.emptyList())) {
+                // 用户权限过滤
+                if (!authorizedAppIds.contains(app.getId())) {
+                    continue;
+                }
+                // 客户端类型位掩码过滤：clients 为空视为不限端
+                if (clientType != null && !containsClient(app.getClients(), clientType.getKey())) {
+                    continue;
+                }
+                boaApps.add(convertToBoaApp(app));
+            }
+            type.setApps(boaApps);
+            result.add(type);
+        }
+        return result;
+    }
+
+    /**
+     * ApplicationInfo -> BoaApp 映射。不透出 appSecret；模块列表留空（由调用方按需填充）。
+     */
+    private BoaApp convertToBoaApp(ApplicationInfo app) {
+        BoaApp boa = new BoaApp();
+        boa.setId(app.getId());
+        boa.setName(app.getName());
+        boa.setIcon(app.getPcIcon());
+        boa.setType(app.getCategoryId());
+        boa.setWebAddr(app.getPcUrl());
+        boa.setWebAddress(app.getPcUrl());
+        boa.setAppKey(app.getAppKey());
+        boa.setOrderNumber(app.getSortNo());
+        boa.setCreateUser(app.getCreateUser());
+        boa.setCreateTime(app.getCreateTime());
+        boa.setMobiIcon(app.getAppIcon());
+        boa.setClients(toClientMask(app.getClients()));
+        boa.setWxgzhAddress(app.getOfficialAccountUrl());
+        boa.setDingAddress(app.getDingtalkUrl());
+        return boa;
+    }
+
+    /**
+     * clients 列表（[1,2,4]）折叠为位掩码叠加值（7）。
+     */
+    private Integer toClientMask(List<Integer> clients) {
+        if (clients == null || clients.isEmpty()) {
+            return null;
+        }
+        int mask = 0;
+        for (Integer c : clients) {
+            if (c != null) {
+                mask |= c;
+            }
+        }
+        return mask;
+    }
+
+    /**
+     * 判断客户端类型位掩码是否与 app.clients 有交集；clients 为空视为不限端。
+     */
+    private boolean containsClient(List<Integer> clients, Integer clientKey) {
+        if (clients == null || clients.isEmpty()) {
+            return true;
+        }
+        for (Integer c : clients) {
+            if (c != null && (c & clientKey) != 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/AppModuleService.java b/src/main/java/com/yunhai/userbase/service/impl/AppModuleService.java
new file mode 100644
index 0000000..d3ebd9e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/AppModuleService.java
@@ -0,0 +1,277 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.entity.AppModule;
+import com.yunhai.userbase.model.appmodule.AppModuleQuery;
+import com.yunhai.userbase.model.appmodule.AppModuleRequest;
+import com.yunhai.userbase.model.appmodule.AppModuleVo;
+import com.yunhai.userbase.repository.AppModuleRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysAppRoleModuleRelRepository;
+import com.yunhai.userbase.repository.SysGroupModulePermRepository;
+import com.yunhai.userbase.service.IAppModuleService;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * @author chenx
+ * @date 2026/7/22
+ * @description 应用模块服务：树形模块的增删改查与层级校验（逻辑外键，最深5层）。<br>
+ */
+@Service
+public class AppModuleService implements IAppModuleService {
+
+    /** 模块最大层级（根模块=1，最深5层）。<br> */
+    private static final int MAX_DEPTH = 5;
+
+    @Autowired
+    private AppModuleRepository appModuleRepository;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Autowired
+    private SysGroupModulePermRepository sysGroupModulePermRepository;
+
+    @Autowired
+    private SysAppRoleModuleRelRepository sysAppRoleModuleRelRepository;
+
+    @Override
+    @Transactional
+    public void add(AppModuleRequest request) {
+        Objects.requireNonNull(request, "模块新增入参不能为空");
+        if (!applicationInfoRepository.existsById(request.getAppId())) {
+            throw new DException("所属应用不存在");
+        }
+        if (appModuleRepository.existsByAppIdAndCustomId(request.getAppId(), request.getCustomId())) {
+            throw new DException("自定义ID在该应用下已存在");
+        }
+        AppModule entity = new AppModule();
+        BeanUtils.copyProperties(request, entity);
+        entity.setId(null);
+        entity.setLevel(resolveLevel(request.getAppId(), request.getParentId()));
+        // sortNo 默认为空（由前端编辑时带入），不自动递增
+        appModuleRepository.save(entity);
+    }
+
+    @Override
+    @Transactional
+    public void edit(Integer id, AppModuleRequest request) {
+        Objects.requireNonNull(id, "模块ID不能为空");
+        Objects.requireNonNull(request, "模块编辑入参不能为空");
+        AppModule entity = appModuleRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("模块不存在: " + id));
+        if (appModuleRepository.existsByAppIdAndCustomIdAndIdNot(entity.getAppId(), request.getCustomId(), id)) {
+            throw new DException("自定义ID在该应用下已存在");
+        }
+        // 可编辑字段：name/customId/path/sortNo；id、appId 不可改
+        entity.setName(request.getName());
+        entity.setCustomId(request.getCustomId());
+        entity.setPath(request.getPath());
+        entity.setSortNo(request.getSortNo());
+        // parentId 变更即移动子树：校验层级上限与环，并级联刷新后代层级
+        if (!Objects.equals(request.getParentId(), entity.getParentId())) {
+            moveSubtree(entity, request.getParentId());
+        } else {
+            appModuleRepository.save(entity);
+        }
+    }
+
+    @Override
+    @Transactional
+    public void delete(Integer id) {
+        Objects.requireNonNull(id, "模块ID不能为空");
+        if (!appModuleRepository.existsById(id)) {
+            throw new RuntimeException("模块不存在: " + id);
+        }
+        if (appModuleRepository.countByParentId(id) > 0) {
+            throw new DException("该模块下存在子模块，无法删除");
+        }
+        // AI-FIX: 删除模块时级联清理各组对该模块的权限记录（逻辑外键无物理 FK，避免残留孤儿数据）
+        sysGroupModulePermRepository.deleteByModuleIdInBulk(Collections.singletonList(id));
+        // AI-FIX(角色授权): 删除模块时级联清理各业务角色对该模块的授权（逻辑外键无物理 FK）
+        sysAppRoleModuleRelRepository.deleteByModuleIdInBulk(Collections.singletonList(id));
+        appModuleRepository.deleteById(id);
+    }
+
+    @Override
+    public List<AppModuleVo> list(AppModuleQuery query) {
+        // 载入该应用下全部模块（忽略 parentId/name，树在后处理阶段组装）
+        List<AppModule> all = appModuleRepository.findModules(query.getAppId(), null, null);
+        if (all.isEmpty()) {
+            return Collections.emptyList();
+        }
+        // parentId -> 子节点列表
+        Map<Integer, List<AppModule>> childrenMap = new HashMap<Integer, List<AppModule>>();
+        for (AppModule m : all) {
+            Integer key = (m.getParentId() == null) ? 0 : m.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<AppModule>()).add(m);
+        }
+        // 每个兄弟组按 sortNo(空视为999) 升序，再按 id 升序
+        Comparator<AppModule> siblingOrder = (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<AppModule> siblings : childrenMap.values()) {
+            siblings.sort(siblingOrder);
+        }
+        // 组装树：默认顶层为 level-1（parentId=null）；传入 parentId 则以该模块为根返回其完整子树
+        List<AppModuleVo> tree;
+        if (query.getParentId() != null) {
+            AppModule root = all.stream()
+                    .filter(m -> Objects.equals(m.getId(), query.getParentId()))
+                    .findFirst()
+                    .orElseThrow(() -> new RuntimeException("父模块不存在: " + query.getParentId()));
+            tree = Collections.singletonList(buildNode(root, childrenMap));
+        } else {
+            List<AppModule> roots = childrenMap.getOrDefault(0, Collections.emptyList());
+            tree = new ArrayList<AppModuleVo>();
+            for (AppModule r : roots) {
+                tree.add(buildNode(r, childrenMap));
+            }
+        }
+        // 名称过滤：保留名称匹配或含匹配后代的分支
+        String name = query.getName();
+        if (name != null && !name.trim().isEmpty()) {
+            tree = pruneByKeyword(tree, name.trim());
+        }
+        return tree;
+    }
+
+    /**
+     * 递归组装节点及其子模块。<br>
+     */
+    private AppModuleVo buildNode(AppModule node, Map<Integer, List<AppModule>> childrenMap) {
+        AppModuleVo vo = convertToVo(node);
+        List<AppModule> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (AppModule child : children) {
+                vo.getChildren().add(buildNode(child, childrenMap));
+            }
+        }
+        return vo;
+    }
+
+    /**
+     * 按关键字剪枝：仅保留自身或后代命中的分支。<br>
+     */
+    private List<AppModuleVo> pruneByKeyword(List<AppModuleVo> nodes, String keyword) {
+        List<AppModuleVo> result = new ArrayList<AppModuleVo>();
+        for (AppModuleVo n : nodes) {
+            boolean selfMatch = n.getName() != null && n.getName().contains(keyword);
+            List<AppModuleVo> keptChildren = pruneByKeyword(n.getChildren(), keyword);
+            if (selfMatch || !keptChildren.isEmpty()) {
+                n.setChildren(keptChildren);
+                result.add(n);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * 计算新建模块层级。<br>
+     * 根模块（parentId=null）=1；子模块=父模块层级+1，超过 MAX_DEPTH 抛异常。
+     */
+    private Integer resolveLevel(Integer appId, Integer parentId) {
+        if (parentId == null) {
+            return 1;
+        }
+        AppModule parent = appModuleRepository.findById(parentId)
+                .orElseThrow(() -> new DException("父模块不存在"));
+        if (!Objects.equals(parent.getAppId(), appId)) {
+            throw new DException("父模块不属于该应用");
+        }
+        int childLevel = parent.getLevel() + 1;
+        if (childLevel > MAX_DEPTH) {
+            throw new DException("模块层级不能超过" + MAX_DEPTH + "层");
+        }
+        return childLevel;
+    }
+
+    /**
+     * 移动子树：校验环与层级上限，刷新自身及后代层级后批量保存。<br>
+     * 依赖同一事务内持久化上下文的对象同一性（all 中即 entity）。
+     */
+    private void moveSubtree(AppModule entity, Integer newParentId) {
+        List<AppModule> all = appModuleRepository.findModules(entity.getAppId(), null, null);
+        Map<Integer, AppModule> idMap = new HashMap<Integer, AppModule>();
+        for (AppModule m : all) {
+            idMap.put(m.getId(), m);
+        }
+        // 环检测：新父节点不能是自身或自身的后代
+        if (newParentId != null) {
+            if (Objects.equals(newParentId, entity.getId())) {
+                throw new DException("不能将模块移动到自身下");
+            }
+            Integer ancestor = newParentId;
+            while (ancestor != null) {
+                AppModule a = idMap.get(ancestor);
+                if (a == null) {
+                    throw new DException("父模块不存在");
+                }
+                if (Objects.equals(a.getId(), entity.getId())) {
+                    throw new DException("不能将模块移动到其子模块下");
+                }
+                ancestor = a.getParentId();
+            }
+        }
+        int newLevel = (newParentId == null) ? 1 : idMap.get(newParentId).getLevel() + 1;
+        int delta = newLevel - entity.getLevel();
+        int maxRelative = maxDescendantRelativeDepth(entity.getId(), all);
+        if (newLevel + maxRelative > MAX_DEPTH) {
+            throw new DException("移动后模块层级超过" + MAX_DEPTH + "层");
+        }
+        entity.setLevel(newLevel);
+        entity.setParentId(newParentId);
+        shiftDescendantLevels(entity.getId(), delta, all);
+        appModuleRepository.saveAll(all);
+    }
+
+    /**
+     * 计算指定节点下后代的最大相对深度（直接子节点=1）。<br>
+     */
+    private int maxDescendantRelativeDepth(Integer rootId, List<AppModule> all) {
+        int max = 0;
+        for (AppModule m : all) {
+            if (Objects.equals(m.getParentId(), rootId)) {
+                int d = 1 + maxDescendantRelativeDepth(m.getId(), all);
+                if (d > max) {
+                    max = d;
+                }
+            }
+        }
+        return max;
+    }
+
+    /**
+     * 将指定节点所有后代的 level 增加 delta。<br>
+     */
+    private void shiftDescendantLevels(Integer rootId, int delta, List<AppModule> all) {
+        for (AppModule m : all) {
+            if (Objects.equals(m.getParentId(), rootId)) {
+                m.setLevel(m.getLevel() + delta);
+                shiftDescendantLevels(m.getId(), delta, all);
+            }
+        }
+    }
+
+    private AppModuleVo convertToVo(AppModule entity) {
+        AppModuleVo vo = new AppModuleVo();
+        BeanUtils.copyProperties(entity, vo);
+        return vo;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/AppRoleService.java b/src/main/java/com/yunhai/userbase/service/impl/AppRoleService.java
new file mode 100644
index 0000000..f1023d9
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/AppRoleService.java
@@ -0,0 +1,500 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.entity.AppModule;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.entity.SysAppRole;
+import com.yunhai.userbase.entity.SysAppRoleModuleRel;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserAppRoleRel;
+import com.yunhai.userbase.model.approle.AppRoleAuthzAppVo;
+import com.yunhai.userbase.model.approle.AppRoleAuthzModuleVo;
+import com.yunhai.userbase.model.approle.AppRoleModuleAssignRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserBindRequest;
+import com.yunhai.userbase.model.approle.AppRoleUserVo;
+import com.yunhai.userbase.model.approle.SysAppRoleQuery;
+import com.yunhai.userbase.model.approle.SysAppRoleRequest;
+import com.yunhai.userbase.model.approle.SysAppRoleVo;
+import com.yunhai.userbase.model.approle.UserAppRoleBindRequest;
+import com.yunhai.userbase.repository.AppModuleRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysAppRoleModuleRelRepository;
+import com.yunhai.userbase.repository.SysAppRoleRepository;
+import com.yunhai.userbase.repository.SysUserAppRoleRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import com.yunhai.userbase.service.IAppRoleService;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.domain.Specification;
+import org.springframework.stereotype.Service;
+
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.CriteriaQuery;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * @author chenx
+ * @date 2026/7/27
+ * @description 应用业务角色服务实现。<br>
+ * 角色创建：普通角色（allAppFlag=false，appId 必填，同应用下重名校验）/ 全应用角色（allAppFlag=true，appId 为空，全应用角色间重名校验）。<br>
+ * 模块授权：sys_app_role_module_rel 全量覆盖式保存（bulk 先删后插）；普通角色仅能授权本应用模块，全应用角色可跨应用。<br>
+ * 用户绑定：sys_user_app_role_rel 支持角色维度 / 用户维度两个方向的全量覆盖保存。<br>
+ */
+@Service
+public class AppRoleService implements IAppRoleService {
+
+    @Autowired
+    private SysAppRoleRepository sysAppRoleRepository;
+
+    @Autowired
+    private SysAppRoleModuleRelRepository sysAppRoleModuleRelRepository;
+
+    @Autowired
+    private SysUserAppRoleRelRepository sysUserAppRoleRelRepository;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Autowired
+    private AppModuleRepository appModuleRepository;
+
+    @Autowired
+    private SysUserRepository sysUserRepository;
+
+    // ===================== 角色 CRUD =====================
+
+    @Override
+    public Page<SysAppRoleVo> list(SysAppRoleQuery query, Pageable pageable) {
+        Objects.requireNonNull(query, "角色查询条件不能为空");
+        Objects.requireNonNull(pageable, "分页参数不能为空");
+        Page<SysAppRole> page = sysAppRoleRepository.findAll(select(query), pageable);
+        // 批量取应用名称，避免逐条查询
+        Set<Integer> appIds = new LinkedHashSet<>();
+        for (SysAppRole role : page.getContent()) {
+            if (role.getAppId() != null) {
+                appIds.add(role.getAppId());
+            }
+        }
+        Map<Integer, String> appNameMap = buildAppNameMap(appIds);
+        List<SysAppRoleVo> content = new ArrayList<SysAppRoleVo>();
+        for (SysAppRole role : page.getContent()) {
+            content.add(convertToVo(role, appNameMap));
+        }
+        return new PageImpl<>(content, pageable, page.getTotalElements());
+    }
+
+    @Override
+    @Transactional
+    public void add(SysAppRoleRequest request) {
+        Objects.requireNonNull(request, "角色新增入参不能为空");
+        boolean allAppFlag = Boolean.TRUE.equals(request.getAllAppFlag());
+        checkRoleShape(allAppFlag, request.getAppId());
+        // 重名校验：全应用角色之间唯一；普通角色同应用下唯一
+        if (allAppFlag) {
+            if (sysAppRoleRepository.existsByNameAndAllAppFlagTrue(request.getName())) {
+                throw new DException("全应用角色名称已存在");
+            }
+        } else {
+            if (sysAppRoleRepository.existsByNameAndAppId(request.getName(), request.getAppId())) {
+                throw new DException("该应用下角色名称已存在");
+            }
+        }
+        SysAppRole entity = new SysAppRole();
+        entity.setName(request.getName());
+        entity.setAllAppFlag(allAppFlag);
+        // 全应用角色强制 appId 为空，防止脏数据
+        entity.setAppId(allAppFlag ? null : request.getAppId());
+        entity.setRemark(request.getRemark());
+        entity.setDisabled(Boolean.TRUE.equals(request.getDisabled()));
+        sysAppRoleRepository.save(entity);
+    }
+
+    @Override
+    @Transactional
+    public void edit(Integer id, SysAppRoleRequest request) {
+        Objects.requireNonNull(id, "角色ID不能为空");
+        Objects.requireNonNull(request, "角色编辑入参不能为空");
+        SysAppRole entity = sysAppRoleRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("角色不存在: " + id));
+        // 角色类型与所属应用不允许修改：修改会导致已授权模块越界（普通角色授权范围与 appId 绑定）
+        if (!Objects.equals(entity.getAllAppFlag(), Boolean.TRUE.equals(request.getAllAppFlag()))
+                || !Objects.equals(entity.getAppId(), request.getAppId())) {
+            throw new DException("角色类型与所属应用不允许修改，请删除后重建");
+        }
+        // 重名校验（排除自身）
+        if (Boolean.TRUE.equals(entity.getAllAppFlag())) {
+            if (sysAppRoleRepository.existsByNameAndAllAppFlagTrueAndIdNot(request.getName(), id)) {
+                throw new DException("全应用角色名称已存在");
+            }
+        } else {
+            if (sysAppRoleRepository.existsByNameAndAppIdAndIdNot(request.getName(), entity.getAppId(), id)) {
+                throw new DException("该应用下角色名称已存在");
+            }
+        }
+        entity.setName(request.getName());
+        entity.setRemark(request.getRemark());
+        if (request.getDisabled() != null) {
+            entity.setDisabled(request.getDisabled());
+        }
+        sysAppRoleRepository.save(entity);
+    }
+
+    @Override
+    @Transactional
+    public void delete(Integer id) {
+        Objects.requireNonNull(id, "角色ID不能为空");
+        if (!sysAppRoleRepository.existsById(id)) {
+            throw new RuntimeException("角色不存在: " + id);
+        }
+        // 逻辑外键级联：先清模块授权与用户绑定，再删角色本体
+        sysAppRoleModuleRelRepository.deleteByRoleIdBulk(id);
+        sysUserAppRoleRelRepository.deleteByRoleIdBulk(id);
+        sysAppRoleRepository.deleteById(id);
+    }
+
+    // ===================== 角色模块授权 =====================
+
+    @Override
+    public List<AppRoleAuthzAppVo> findRoleModuleTree(Integer roleId) {
+        Objects.requireNonNull(roleId, "角色ID不能为空");
+        SysAppRole role = sysAppRoleRepository.findById(roleId)
+                .orElseThrow(() -> new RuntimeException("角色不存在: " + roleId));
+        // 授权范围：普通角色仅本应用；全应用角色为系统全部应用
+        List<ApplicationInfo> apps;
+        if (Boolean.TRUE.equals(role.getAllAppFlag())) {
+            apps = applicationInfoRepository.findAll();
+        } else {
+            ApplicationInfo app = applicationInfoRepository.findById(role.getAppId()).orElse(null);
+            if (app == null) {
+                // 应用已删除的孤儿角色：不再抛错导致整页 500，返回空授权树（数据侧请用清理 SQL 修复）
+                return Collections.emptyList();
+            }
+            apps = Collections.singletonList(app);
+        }
+        apps.sort(appOrder());
+        List<Integer> appIds = new ArrayList<>();
+        for (ApplicationInfo app : apps) {
+            appIds.add(app.getId());
+        }
+        // 应用下全部模块，按 appId 分桶
+        Map<Integer, List<AppModule>> appModuleMap = new HashMap<>();
+        for (AppModule m : appModuleRepository.findByAppIdIn(appIds)) {
+            appModuleMap.computeIfAbsent(m.getAppId(), k -> new ArrayList<>()).add(m);
+        }
+        // 已授权模块集合，供 checked 回显
+        Set<Integer> checkedModuleIds = new HashSet<>();
+        for (SysAppRoleModuleRel rel : sysAppRoleModuleRelRepository.findByRoleId(roleId)) {
+            checkedModuleIds.add(rel.getModuleId());
+        }
+        List<AppRoleAuthzAppVo> result = new ArrayList<>();
+        for (ApplicationInfo app : apps) {
+            AppRoleAuthzAppVo appVo = new AppRoleAuthzAppVo();
+            BeanUtils.copyProperties(app, appVo);
+            List<AppModule> modules = appModuleMap.get(app.getId());
+            if (modules != null) {
+                appVo.setModules(buildModuleTree(modules, checkedModuleIds));
+            }
+            result.add(appVo);
+        }
+        return result;
+    }
+
+    @Override
+    @Transactional
+    public void saveRoleModules(AppRoleModuleAssignRequest request) {
+        Objects.requireNonNull(request, "角色模块授权入参不能为空");
+        Integer roleId = request.getRoleId();
+        SysAppRole role = sysAppRoleRepository.findById(roleId)
+                .orElseThrow(() -> new RuntimeException("角色不存在: " + roleId));
+        // 去重并校验模块均存在
+        List<Integer> moduleIds = new ArrayList<>(new LinkedHashSet<>(
+                request.getModuleIds() == null ? Collections.emptyList() : request.getModuleIds()));
+        if (!moduleIds.isEmpty()) {
+            Map<Integer, AppModule> moduleMap = new HashMap<>();
+            for (AppModule m : appModuleRepository.findAllById(moduleIds)) {
+                moduleMap.put(m.getId(), m);
+            }
+            for (Integer moduleId : moduleIds) {
+                AppModule m = moduleMap.get(moduleId);
+                if (m == null) {
+                    throw new DException("模块不存在: " + moduleId);
+                }
+                // 越权防护：普通角色只能授权其所属应用下的模块；全应用角色可跨应用
+                if (!Boolean.TRUE.equals(role.getAllAppFlag()) && !Objects.equals(m.getAppId(), role.getAppId())) {
+                    throw new DException("模块 " + moduleId + " 不属于该角色所属应用，普通角色不能跨应用授权");
+                }
+            }
+        }
+        // 全量覆盖：bulk 先删旧记录（立即发 SQL，避免 flush 顺序触发唯一键冲突），再批量插入
+        sysAppRoleModuleRelRepository.deleteByRoleIdBulk(roleId);
+        List<SysAppRoleModuleRel> batch = new ArrayList<>();
+        for (Integer moduleId : moduleIds) {
+            SysAppRoleModuleRel rel = new SysAppRoleModuleRel();
+            rel.setRoleId(roleId);
+            rel.setModuleId(moduleId);
+            batch.add(rel);
+        }
+        if (!batch.isEmpty()) {
+            sysAppRoleModuleRelRepository.saveAll(batch);
+        }
+    }
+
+    // ===================== 用户角色绑定 =====================
+
+    @Override
+    public List<AppRoleUserVo> findRoleUsers(Integer roleId) {
+        Objects.requireNonNull(roleId, "角色ID不能为空");
+        if (!sysAppRoleRepository.existsById(roleId)) {
+            throw new DException("角色不存在: " + roleId);
+        }
+        List<SysUserAppRoleRel> rels = sysUserAppRoleRelRepository.findByRoleId(roleId);
+        if (rels.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Set<Integer> userIds = new LinkedHashSet<>();
+        for (SysUserAppRoleRel rel : rels) {
+            userIds.add(rel.getUserId());
+        }
+        Map<Integer, SysUser> userMap = new HashMap<>();
+        for (SysUser user : sysUserRepository.findAllById(userIds)) {
+            userMap.put(user.getId(), user);
+        }
+        List<AppRoleUserVo> result = new ArrayList<>();
+        for (SysUserAppRoleRel rel : rels) {
+            SysUser user = userMap.get(rel.getUserId());
+            if (user == null) {
+                continue;
+            }
+            AppRoleUserVo vo = new AppRoleUserVo();
+            vo.setId(user.getId());
+            vo.setAccount(user.getAccount());
+            vo.setRealName(user.getRealName());
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    @Transactional
+    public void saveRoleUsers(AppRoleUserBindRequest request) {
+        Objects.requireNonNull(request, "角色绑定用户入参不能为空");
+        Integer roleId = request.getRoleId();
+        if (!sysAppRoleRepository.existsById(roleId)) {
+            throw new DException("角色不存在: " + roleId);
+        }
+        // 去重并校验用户均存在
+        List<Integer> userIds = new ArrayList<>(new LinkedHashSet<>(
+                request.getUserIds() == null ? Collections.emptyList() : request.getUserIds()));
+        for (Integer userId : userIds) {
+            if (!sysUserRepository.existsById(userId)) {
+                throw new DException("用户不存在: " + userId);
+            }
+        }
+        // 全量覆盖：bulk 先删旧绑定，再批量插入
+        sysUserAppRoleRelRepository.deleteByRoleIdBulk(roleId);
+        List<SysUserAppRoleRel> batch = new ArrayList<>();
+        for (Integer userId : userIds) {
+            SysUserAppRoleRel rel = new SysUserAppRoleRel();
+            rel.setUserId(userId);
+            rel.setRoleId(roleId);
+            batch.add(rel);
+        }
+        if (!batch.isEmpty()) {
+            sysUserAppRoleRelRepository.saveAll(batch);
+        }
+    }
+
+    @Override
+    @Transactional
+    public void saveUserRoles(UserAppRoleBindRequest request) {
+        Objects.requireNonNull(request, "用户绑定角色入参不能为空");
+        Integer userId = request.getUserId();
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("用户不存在: " + userId);
+        }
+        // 去重并校验角色均存在
+        List<Integer> roleIds = new ArrayList<>(new LinkedHashSet<>(
+                request.getRoleIds() == null ? Collections.emptyList() : request.getRoleIds()));
+        for (Integer roleId : roleIds) {
+            if (!sysAppRoleRepository.existsById(roleId)) {
+                throw new DException("角色不存在: " + roleId);
+            }
+        }
+        // 全量覆盖：bulk 先删旧绑定，再批量插入
+        sysUserAppRoleRelRepository.deleteByUserIdBulk(userId);
+        List<SysUserAppRoleRel> batch = new ArrayList<>();
+        for (Integer roleId : roleIds) {
+            SysUserAppRoleRel rel = new SysUserAppRoleRel();
+            rel.setUserId(userId);
+            rel.setRoleId(roleId);
+            batch.add(rel);
+        }
+        if (!batch.isEmpty()) {
+            sysUserAppRoleRelRepository.saveAll(batch);
+        }
+    }
+
+    @Override
+    @Transactional
+    public void removeRoleUser(Integer roleId, Integer userId) {
+        Objects.requireNonNull(roleId, "角色ID不能为空");
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        if (!sysAppRoleRepository.existsById(roleId)) {
+            throw new DException("角色不存在: " + roleId);
+        }
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("用户不存在: " + userId);
+        }
+        sysUserAppRoleRelRepository.deleteByRoleIdAndUserId(roleId, userId);
+    }
+
+    // ===================== 私有工具 =====================
+
+    /**
+     * 校验角色形态：普通角色 appId 必填且应用存在；全应用角色 appId 必须为空。<br>
+     */
+    private void checkRoleShape(boolean allAppFlag, Integer appId) {
+        if (allAppFlag) {
+            if (appId != null) {
+                throw new DException("全应用角色不能指定所属应用");
+            }
+        } else {
+            if (appId == null) {
+                throw new DException("普通角色必须指定所属应用");
+            }
+            if (!applicationInfoRepository.existsById(appId)) {
+                throw new DException("所属应用不存在: " + appId);
+            }
+        }
+    }
+
+    /**
+     * 构建角色列表的动态查询条件（Tier 1 Specification）。<br>
+     * name 模糊匹配；appId/allAppFlag/disabled 精确匹配。<br>
+     */
+    private Specification<SysAppRole> select(SysAppRoleQuery query) {
+        Specification<SysAppRole> specification = new Specification<SysAppRole>() {
+            @Override
+            public Predicate toPredicate(Root<SysAppRole> root, CriteriaQuery<?> cq, CriteriaBuilder cb) {
+                List<Predicate> predicates = new ArrayList<Predicate>();
+                if (query != null) {
+                    if (StringUtils.isNotEmpty(query.getName())) {
+                        predicates.add(cb.like(root.get("name"), "%" + query.getName() + "%"));
+                    }
+                    if (query.getAppId() != null) {
+                        predicates.add(cb.equal(root.get("appId"), query.getAppId()));
+                    }
+                    if (query.getAllAppFlag() != null) {
+                        predicates.add(cb.equal(root.get("allAppFlag"), query.getAllAppFlag()));
+                    }
+                    if (query.getDisabled() != null) {
+                        predicates.add(cb.equal(root.get("disabled"), query.getDisabled()));
+                    }
+                }
+                return cq.where(predicates.toArray(new Predicate[predicates.size()])).getRestriction();
+            }
+        };
+        return specification;
+    }
+
+    /**
+     * 批量查询应用名称映射（角色列表回填 appName 用）。<br>
+     */
+    private Map<Integer, String> buildAppNameMap(Set<Integer> appIds) {
+        Map<Integer, String> map = new HashMap<>();
+        if (appIds.isEmpty()) {
+            return map;
+        }
+        for (ApplicationInfo app : applicationInfoRepository.findAllById(appIds)) {
+            map.put(app.getId(), app.getName());
+        }
+        return map;
+    }
+
+    private SysAppRoleVo convertToVo(SysAppRole entity, Map<Integer, String> appNameMap) {
+        SysAppRoleVo vo = new SysAppRoleVo();
+        BeanUtils.copyProperties(entity, vo);
+        if (entity.getAppId() != null) {
+            vo.setAppName(appNameMap.get(entity.getAppId()));
+        }
+        return vo;
+    }
+
+    /**
+     * 组装单个应用下的模块树（沿用 GroupAuthzService 的组装方式：childrenMap + sortNo 排序），并回显 checked。<br>
+     */
+    private List<AppRoleAuthzModuleVo> buildModuleTree(List<AppModule> modules, Set<Integer> checkedModuleIds) {
+        // parentId -> 子节点列表（null 视为 0）
+        Map<Integer, List<AppModule>> childrenMap = new HashMap<>();
+        for (AppModule m : modules) {
+            Integer key = (m.getParentId() == null) ? 0 : m.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(m);
+        }
+        // 每个兄弟组按 sortNo(空视为999) 升序，再按 id 升序
+        Comparator<AppModule> siblingOrder = (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<AppModule> siblings : childrenMap.values()) {
+            siblings.sort(siblingOrder);
+        }
+        List<AppModule> roots = childrenMap.getOrDefault(0, Collections.emptyList());
+        List<AppRoleAuthzModuleVo> tree = new ArrayList<>();
+        for (AppModule root : roots) {
+            tree.add(buildModuleNode(root, childrenMap, checkedModuleIds));
+        }
+        return tree;
+    }
+
+    /**
+     * 递归组装模块节点，并按角色授权记录回显 checked。<br>
+     */
+    private AppRoleAuthzModuleVo buildModuleNode(AppModule node,
+                                                 Map<Integer, List<AppModule>> childrenMap,
+                                                 Set<Integer> checkedModuleIds) {
+        AppRoleAuthzModuleVo vo = new AppRoleAuthzModuleVo();
+        BeanUtils.copyProperties(node, vo);
+        if (checkedModuleIds.contains(node.getId())) {
+            vo.setChecked(Boolean.TRUE);
+        }
+        List<AppModule> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (AppModule child : children) {
+                vo.getChildren().add(buildModuleNode(child, childrenMap, checkedModuleIds));
+            }
+        }
+        return vo;
+    }
+
+    /** 应用排序：sortNo 升序（空视为999），再按 id 升序（与应用列表展示一致）。 */
+    private Comparator<ApplicationInfo> appOrder() {
+        return (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/ApplicationInfoService.java b/src/main/java/com/yunhai/userbase/service/impl/ApplicationInfoService.java
new file mode 100644
index 0000000..a24150a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/ApplicationInfoService.java
@@ -0,0 +1,319 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.userbase.entity.AppModule;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.entity.SysAppRole;
+import com.yunhai.userbase.repository.AppModuleRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysAppRoleModuleRelRepository;
+import com.yunhai.userbase.repository.SysAppRoleRepository;
+import com.yunhai.userbase.repository.SysGroupAppRelRepository;
+import com.yunhai.userbase.repository.SysGroupModulePermRepository;
+import com.yunhai.userbase.repository.SysUserAppRoleRelRepository;
+import com.yunhai.userbase.service.IApplicationInfoService;
+import com.yunhai.platform.utils.exception.DException;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.CachePut;
+import org.springframework.cache.annotation.Cacheable;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.stereotype.Service;
+import com.yunhai.userbase.model.application.ApplicationInfoQuery;
+import com.yunhai.userbase.model.application.ApplicationInfoRequest;
+import com.yunhai.userbase.model.application.ApplicationInfoSortVo;
+import com.yunhai.userbase.model.application.ApplicationInfoVo;
+import com.yunhai.userbase.model.application.PushSettingRequest;
+import com.yunhai.userbase.model.application.PushSettingVo;
+import com.yunhai.userbase.event.ApplicationInfoCacheChangedEvent;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.BeanUtils;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.domain.Specification;
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.CriteriaQuery;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.UUID;
+
+@Service
+public class ApplicationInfoService implements IApplicationInfoService {
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Autowired
+    private AppModuleRepository appModuleRepository;
+
+    @Autowired
+    private SysGroupAppRelRepository sysGroupAppRelRepository;
+
+    @Autowired
+    private SysGroupModulePermRepository sysGroupModulePermRepository;
+
+    @Autowired
+    private SysAppRoleRepository sysAppRoleRepository;
+
+    @Autowired
+    private SysAppRoleModuleRelRepository sysAppRoleModuleRelRepository;
+
+    @Autowired
+    private SysUserAppRoleRelRepository sysUserAppRoleRelRepository;
+
+    @Autowired
+    private SignKeyCacheService signKeyCacheService;
+
+    @Autowired
+    private ApplicationEventPublisher eventPublisher;
+
+    /**
+     * 查询缓存：sync = true 防击穿；底层优先 Redis，Redis 故障时自动降级 Caffeine。
+     */
+    @Override
+    @Cacheable(value = "appInfo", key = "#id", sync = true)
+    public ApplicationInfo getById(Integer id) {
+        return applicationInfoRepository.findById(id).orElse(null);
+    }
+
+    /**
+     * 更新缓存：方法返回即写入缓存（与 @Cacheable 同一 cacheName/key，保证一致）。
+     */
+    @Override
+    @CachePut(value = "appInfo", key = "#info.id")
+    public ApplicationInfo save(ApplicationInfo info) {
+        ApplicationInfo saved = applicationInfoRepository.save(info);
+        eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.upsert(this, saved));
+        return saved;
+    }
+
+    /**
+     * 删除缓存：删除数据时同步清除对应缓存项。
+     */
+    @Override
+    @CacheEvict(value = "appInfo", key = "#id")
+    public void deleteById(Integer id) {
+        ApplicationInfo existing = applicationInfoRepository.findById(id).orElse(null);
+        applicationInfoRepository.deleteById(id);
+        if (existing != null && existing.getAppKey() != null) {
+            eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.delete(this, existing.getAppKey()));
+        }
+    }
+
+    @Override
+    @Transactional
+    public void add(ApplicationInfoRequest request) {
+        Objects.requireNonNull(request, "应用新增入参不能为空");
+        // 重名校验：新增应用名称不允许重复
+        if (applicationInfoRepository.existsByName(request.getName())) {
+            throw new DException("应用名称已存在");
+        }
+        ApplicationInfo entity = new ApplicationInfo();
+        BeanUtils.copyProperties(request, entity);
+        entity.setId(null);
+        // appKey：整型，从 100000 起，取数据库现有最大 appKey + 1
+        Integer maxAppKey = applicationInfoRepository.findMaxAppKey();
+        Integer appKey = (maxAppKey == null) ? 100000 : maxAppKey + 1;
+        entity.setAppKey(appKey);
+        // appSecret：32 位 UUID（去除连字符）
+        entity.setAppSecret(UUID.randomUUID().toString().replace("-", ""));
+        ApplicationInfo saved = applicationInfoRepository.save(entity);
+        eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.upsert(this, saved));
+    }
+
+    @Override
+    @Transactional
+    public void edit(Integer id, ApplicationInfoRequest request) {
+        Objects.requireNonNull(id, "应用ID不能为空");
+        Objects.requireNonNull(request, "应用编辑入参不能为空");
+        // 重名校验：编辑时排除自身
+        if (applicationInfoRepository.existsByNameAndIdNot(request.getName(), id)) {
+            throw new DException("应用名称已存在");
+        }
+        ApplicationInfo entity = applicationInfoRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用不存在: " + id));
+        BeanUtils.copyProperties(request, entity, "id", "appKey", "appSecret");
+        ApplicationInfo saved = applicationInfoRepository.save(entity);
+        eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.upsert(this, saved));
+    }
+
+    @Override
+    @Transactional
+    // AI-FIX: 删除应用同时级联删除其下全部模块（逻辑外键 appId，无物理 FK，需手动清理），并清除 appInfo 缓存
+    @CacheEvict(value = "appInfo", key = "#id")
+    public void delete(Integer id) {
+        Objects.requireNonNull(id, "应用ID不能为空");
+        ApplicationInfo existing = applicationInfoRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用不存在: " + id));
+        Integer appKey = existing.getAppKey();
+        // AI-FIX: 删除应用前级联清理组权限关联（逻辑外键无物理 FK）：先清该应用模块的组权限记录，再清组开通记录
+        List<AppModule> modules = appModuleRepository.findByAppIdIn(java.util.Collections.singletonList(id));
+        if (!modules.isEmpty()) {
+            List<Integer> moduleIds = new ArrayList<Integer>();
+            for (AppModule m : modules) {
+                moduleIds.add(m.getId());
+            }
+            sysGroupModulePermRepository.deleteByModuleIdInBulk(moduleIds);
+        }
+        sysGroupAppRelRepository.deleteByAppIdBulk(id);
+        // AI-FIX(角色授权): 删除应用前级联清理该应用下的业务角色及其授权关系（逻辑外键无物理 FK）
+        // 仅清理「普通角色」（appId=本应用）；全应用角色（appId=null）不受应用删除影响，保留不动
+        List<SysAppRole> appRoles = sysAppRoleRepository.findByAppId(id);
+        if (!appRoles.isEmpty()) {
+            List<Integer> roleIds = new ArrayList<Integer>();
+            for (SysAppRole r : appRoles) {
+                roleIds.add(r.getId());
+            }
+            sysAppRoleModuleRelRepository.deleteByRoleIdInBulk(roleIds);
+            sysUserAppRoleRelRepository.deleteByRoleIdInBulk(roleIds);
+            sysAppRoleRepository.deleteAll(appRoles);
+        }
+        // 先删模块（整棵子树随 appId 一并清除），再删应用，避免残留孤儿数据
+        appModuleRepository.deleteByAppId(id);
+        applicationInfoRepository.deleteById(id);
+        eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.delete(this, appKey));
+    }
+
+    @Override
+    public Page<ApplicationInfoVo> list(ApplicationInfoQuery query, Pageable pageable) {
+        Objects.requireNonNull(query, "应用查询条件不能为空");
+        Objects.requireNonNull(pageable, "分页参数不能为空");
+        Page<ApplicationInfo> page = applicationInfoRepository.findAll(select(query), pageable);
+        List<ApplicationInfoVo> content = new ArrayList<ApplicationInfoVo>();
+        for (ApplicationInfo entity : page.getContent()) {
+            content.add(convertToVo(entity));
+        }
+        return new PageImpl<>(content, pageable, page.getTotalElements());
+    }
+
+    /**
+     * 构建应用列表的动态查询条件。<br>
+     * name 关键词：按应用名称模糊匹配，或按 appKey（appId）精确匹配；categoryId：按应用类别精确匹配。<br>
+     *
+     * @param query 前端传入的查询条件
+     * @return 动态查询 Specification
+     */
+    private Specification select(ApplicationInfoQuery query) {
+        Specification<ApplicationInfo> specification = new Specification<ApplicationInfo>() {
+            @Override
+            public Predicate toPredicate(Root<ApplicationInfo> root, CriteriaQuery<?> cq, CriteriaBuilder cb) {
+                List<Predicate> predicates = new ArrayList<Predicate>();
+                predicates.add(cb.greaterThan(root.get("appKey"), 100000));
+                if (query != null) {
+                    if (StringUtils.isNotEmpty(query.getName())) {
+                        String keyword = query.getName();
+                        Predicate byName = cb.like(root.get("name"), "%" + keyword + "%");
+                        // 关键词为纯数字时，同时按 appKey（appId）精确匹配
+                        if (keyword.matches("\\d+")) {
+                            predicates.add(cb.or(byName, cb.equal(root.get("appKey"), Integer.parseInt(keyword))));
+                        } else {
+                            predicates.add(byName);
+                        }
+                    }
+                    if (query.getCategoryId() != null) {
+                        predicates.add(cb.equal(root.get("categoryId"), query.getCategoryId()));
+                    }
+                }
+                return cq.where(predicates.toArray(new Predicate[predicates.size()])).getRestriction();
+            }
+        };
+        return specification;
+    }
+
+    @Override
+    @Transactional
+    // AI-FIX: 重置密钥后必须清除 appInfo 缓存，否则控制器随后 getById 命中旧缓存、返回旧密钥
+    @CacheEvict(value = "appInfo", key = "#id")
+    public void resetAppSecret(Integer id) {
+        Objects.requireNonNull(id, "应用ID不能为空");
+        ApplicationInfo entity = applicationInfoRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用不存在: " + id));
+        entity.setAppSecret(UUID.randomUUID().toString().replace("-", ""));
+        ApplicationInfo saved = applicationInfoRepository.save(entity);
+        eventPublisher.publishEvent(ApplicationInfoCacheChangedEvent.upsert(this, saved));
+    }
+
+    @Override
+    @Transactional
+    public void sort(List<Integer> ids) {
+        if (ids == null || ids.isEmpty()) {
+            throw new DException("排序应用ID列表不能为空");
+        }
+        Integer categoryId = null;
+        for (int i = 0; i < ids.size(); i++) {
+            Integer id = ids.get(i);
+            ApplicationInfo entity = applicationInfoRepository.findById(id)
+                    .orElseThrow(() -> new DException("应用不存在: " + id));
+            // 额外校验：排序必须限定在同一个应用类型内，避免跨类型串号导致排序错乱
+            if (categoryId == null) {
+                categoryId = entity.getCategoryId();
+            } else if (!Objects.equals(categoryId, entity.getCategoryId())) {
+                throw new DException("排序应用不属于同一应用类型，请检查入参");
+            }
+            applicationInfoRepository.updateSortNoById(id, i + 1);
+        }
+    }
+
+    private ApplicationInfoVo convertToVo(ApplicationInfo entity) {
+        ApplicationInfoVo vo = new ApplicationInfoVo();
+        BeanUtils.copyProperties(entity, vo);
+        return vo;
+    }
+
+    @Override
+    public List<ApplicationInfoSortVo> findListByCategoryId(Integer categoryId) {
+        return applicationInfoRepository.findSortVoByCategoryId(categoryId);
+    }
+
+    @Override
+    @Transactional
+    @CachePut(value = "appInfo", key = "#id")
+    public ApplicationInfo savePushSetting(Integer id, PushSettingRequest request) {
+        Objects.requireNonNull(id, "应用ID不能为空");
+        Objects.requireNonNull(request, "推送设置入参不能为空");
+        ApplicationInfo entity = applicationInfoRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用不存在: " + id));
+        if (request.getPushBaseUrl() != null) {
+            entity.setPushBaseUrl(request.getPushBaseUrl());
+        }
+        if (request.getPushEnabled() != null) {
+            entity.setPushEnabled(request.getPushEnabled());
+        }
+        if (request.getPushEventTypes() != null) {
+            entity.setPushEventTypes(request.getPushEventTypes());
+        }
+        if (request.getPushSchoolIds() != null) {
+            entity.setPushSchoolIds(request.getPushSchoolIds());
+        }
+        if (request.getPushRoleIds() != null) {
+            entity.setPushRoleIds(request.getPushRoleIds());
+        }
+        // pushSecret：null=不修改；空串=清空（后续复用 appSecret）
+        if (request.getPushSecret() != null) {
+            entity.setPushSecret(request.getPushSecret());
+        }
+        return applicationInfoRepository.save(entity);
+    }
+
+    @Override
+    public PushSettingVo getPushSetting(Integer id) {
+        Objects.requireNonNull(id, "应用ID不能为空");
+        ApplicationInfo entity = applicationInfoRepository.findById(id)
+                .orElseThrow(() -> new RuntimeException("应用不存在: " + id));
+        PushSettingVo vo = new PushSettingVo();
+        vo.setId(entity.getId());
+        vo.setAppKey(entity.getAppKey());
+        vo.setName(entity.getName());
+        vo.setPushBaseUrl(entity.getPushBaseUrl());
+        vo.setPushEnabled(entity.getPushEnabled());
+        vo.setPushEventTypes(entity.getPushEventTypes());
+        vo.setPushSchoolIds(entity.getPushSchoolIds());
+        vo.setPushRoleIds(entity.getPushRoleIds());
+        vo.setPushSecret(entity.getPushSecret());
+        return vo;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/service/impl/GroupAuthzService.java b/src/main/java/com/yunhai/userbase/service/impl/GroupAuthzService.java
new file mode 100644
index 0000000..a7cfe08
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/GroupAuthzService.java
@@ -0,0 +1,1626 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.model.BoaModule;
+import com.yunhai.userbase.entity.*;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.userbase.enums.SysModeEnum;
+import com.yunhai.userbase.enums.UserTypeEnum;
+import com.yunhai.userbase.model.groupauthz.GroupAppAssignRequest;
+import com.yunhai.userbase.model.groupauthz.GroupAppVo;
+import com.yunhai.userbase.model.groupauthz.GroupAuthzAppVo;
+import com.yunhai.userbase.model.groupauthz.GroupAuthzCategoryVo;
+import com.yunhai.userbase.model.groupauthz.GroupAuthzModuleVo;
+import com.yunhai.userbase.model.groupauthz.GroupModuleAuthzItem;
+import com.yunhai.userbase.model.groupauthz.GroupModulePermRequest;
+import com.yunhai.userbase.model.groupauthz.SchoolAppAuthzRequest;
+import com.yunhai.userbase.repository.AppCategoryRepository;
+import com.yunhai.userbase.repository.AppModuleRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysGroupAppRelRepository;
+import com.yunhai.userbase.repository.SysGroupModulePermRepository;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.model.groupauthz.UserGroupNodeVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionAppVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionCategoryVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionModuleVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionUserVo;
+import com.yunhai.userbase.model.groupauthz.UserRoleVo;
+import com.yunhai.userbase.repository.SysAppRoleModuleRelRepository;
+import com.yunhai.userbase.repository.SysAppRoleRepository;
+import com.yunhai.userbase.repository.SysUserAppRoleRelRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import com.yunhai.userbase.service.IGroupAuthzService;
+import com.yunhai.userbase.service.impl.UserCenterService;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.jpa.domain.Specification;
+import org.springframework.stereotype.Service;
+
+import javax.persistence.criteria.Predicate;
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * @author chenx
+ * @date 2026/7/23
+ * @description 组应用权限服务实现。<br>
+ *              功能1「应用开通」：sys_group_app_rel 全量覆盖式保存，开通不继承（子组须自己开通）。<br>
+ *              功能2「组授权」：sys_group_module_perm 全量覆盖式保存，inheritFlag=true
+ *              时子孙组自动继承。<br>
+ *              权限判定：沿 sys_group 祖先链内存回溯（树深度有限，MySQL 5.7 无递归 CTE，批量 IN 查询）。<br>
+ *              角色授权并集：最终模块权限 = 组授权模块 ∪ 启用角色授权模块；角色模块不要求组先开通应用（见 AI-FIX 标记）。<br>
+ */
+@Service
+public class GroupAuthzService implements IGroupAuthzService {
+
+    /** 虚拟父节点：根节点的 parentId，表示「无上级」（与 SysGroupService 保持一致）。 */
+    private static final int ROOT_PARENT_ID = 0;
+
+    @Autowired
+    private SysGroupAppRelRepository sysGroupAppRelRepository;
+
+    @Autowired
+    private SysGroupModulePermRepository sysGroupModulePermRepository;
+
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    @Autowired
+    private AppCategoryRepository appCategoryRepository;
+
+    @Autowired
+    private AppModuleRepository appModuleRepository;
+
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+
+    @Autowired
+    private SysUserRepository sysUserRepository;
+
+    @Autowired
+    private SysAppRoleRepository sysAppRoleRepository;
+
+    @Autowired
+    private SysAppRoleModuleRelRepository sysAppRoleModuleRelRepository;
+
+    @Autowired
+    private SysUserAppRoleRelRepository sysUserAppRoleRelRepository;
+
+    // ===================== 新增：沿祖先链收集「本组+所有祖先组开通的应用ID并集」（应用池联动GetSchoolAppId）
+    // =====================
+
+    /**
+     * 按用户需求：父组(学校组)若开通了应用(GetSchoolAppId返回非空)，则其所有子孙组的模块权限分配面板也能看到这些应用(无需子组重复开通)。<br>
+     * 取应用范围=sys_group_app_rel里group_id属于「本组+全部祖先组」的app_id并集；开通不继承，模块权限池继承。<br>
+     * 对 hasModulePermission / UserPermissionTree
+     * 不做修改，避免越权（最终用户拿到权限仍需要自己的归属组开通应用+继承到模块权限，双保险）。
+     */
+    private Set<Integer> collectAppIdsForAuthzScope(Integer groupId) {
+        Map<Integer, SysGroup> allGroupMap = buildAllGroupMap();
+        List<Integer> chain = ancestorChain(groupId, allGroupMap);
+        if (chain == null || chain.isEmpty()) {
+            return Collections.emptySet();
+        }
+        List<SysGroupAppRel> rels = sysGroupAppRelRepository.findByGroupIdIn(chain);
+        Set<Integer> appIds = new LinkedHashSet<>();
+        for (SysGroupAppRel rel : rels) {
+            if (rel.getAppId() != null) {
+                appIds.add(rel.getAppId());
+            }
+        }
+        return appIds;
+    }
+
+    // ===================== 功能1：应用开通 =====================
+
+    @Override
+    public List<GroupAppVo> listGroupApps(Integer groupId) {
+        Objects.requireNonNull(groupId, "组ID不能为空");
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("系统组不存在");
+        }
+        List<ApplicationInfo> apps = applicationInfoRepository.findAll();
+        apps.sort(appOrder());
+        Set<Integer> openedAppIds = new HashSet<>();
+        for (SysGroupAppRel rel : sysGroupAppRelRepository.findByGroupId(groupId)) {
+            openedAppIds.add(rel.getAppId());
+        }
+        List<GroupAppVo> result = new ArrayList<>();
+        for (ApplicationInfo app : apps) {
+            GroupAppVo vo = new GroupAppVo();
+            BeanUtils.copyProperties(app, vo);
+            vo.setChecked(openedAppIds.contains(app.getId()));
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    @Transactional
+    public void assignAppsToGroup(GroupAppAssignRequest request) {
+        Objects.requireNonNull(request, "应用开通入参不能为空");
+        Integer groupId = request.getGroupId();
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("系统组不存在");
+        }
+        // 去重并校验应用均存在
+        List<Integer> appIds = new ArrayList<>(new LinkedHashSet<>(
+                request.getAppIds() == null ? Collections.emptyList() : request.getAppIds()));
+        for (Integer appId : appIds) {
+            if (!applicationInfoRepository.existsById(appId)) {
+                throw new DException("应用不存在: " + appId);
+            }
+        }
+        // 计算本次被取消开通的应用，先清理该组在其模块上的权限记录，避免残留脏数据
+        List<SysGroupAppRel> oldRels = sysGroupAppRelRepository.findByGroupId(groupId);
+        List<Integer> removedAppIds = new ArrayList<>();
+        for (SysGroupAppRel rel : oldRels) {
+            if (!appIds.contains(rel.getAppId())) {
+                removedAppIds.add(rel.getAppId());
+            }
+        }
+        if (!removedAppIds.isEmpty()) {
+            List<Integer> removedModuleIds = new ArrayList<>();
+            for (AppModule m : appModuleRepository.findByAppIdIn(removedAppIds)) {
+                removedModuleIds.add(m.getId());
+            }
+            if (!removedModuleIds.isEmpty()) {
+                sysGroupModulePermRepository.deleteByGroupIdAndModuleIdInBulk(groupId, removedModuleIds);
+            }
+        }
+        // 全量覆盖：bulk 先删旧记录（立即发 SQL，避免 flush 顺序触发唯一键冲突），再批量插入
+        sysGroupAppRelRepository.deleteByGroupIdBulk(groupId);
+        List<SysGroupAppRel> batch = new ArrayList<>();
+        for (Integer appId : appIds) {
+            SysGroupAppRel rel = new SysGroupAppRel();
+            rel.setGroupId(groupId);
+            rel.setAppId(appId);
+            batch.add(rel);
+        }
+        if (!batch.isEmpty()) {
+            sysGroupAppRelRepository.saveAll(batch);
+        }
+    }
+
+    // ===================== 功能2：组授权 =====================
+
+    @Override
+    public List<GroupAuthzAppVo> findGroupAppsWithModules(Integer groupId) {
+        Objects.requireNonNull(groupId, "组ID不能为空");
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("系统组不存在");
+        }
+        Set<Integer> appIdSet = collectAppIdsForAuthzScope(groupId);
+        if (appIdSet.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<Integer> appIds = new ArrayList<>(appIdSet);
+        List<ApplicationInfo> apps = applicationInfoRepository.findAllById(appIds);
+        apps.sort(appOrder());
+        List<AppModule> allModules = appModuleRepository.findByAppIdIn(appIds);
+        Map<Integer, List<AppModule>> appModuleMap = new HashMap<>();
+        for (AppModule m : allModules) {
+            appModuleMap.computeIfAbsent(m.getAppId(), k -> new ArrayList<>()).add(m);
+        }
+        Map<Integer, SysGroupModulePerm> permMap = new HashMap<>();
+        for (SysGroupModulePerm perm : sysGroupModulePermRepository.findByGroupId(groupId)) {
+            permMap.put(perm.getModuleId(), perm);
+        }
+        List<GroupAuthzAppVo> result = new ArrayList<>();
+        for (ApplicationInfo app : apps) {
+            GroupAuthzAppVo appVo = new GroupAuthzAppVo();
+            BeanUtils.copyProperties(app, appVo);
+            List<AppModule> modules = appModuleMap.get(app.getId());
+            if (modules != null) {
+                appVo.setModules(buildModuleTree(modules, permMap));
+            }
+            result.add(appVo);
+        }
+        return result;
+    }
+
+    @Override
+    public List<GroupAuthzCategoryVo> findGroupAppsWithModulesByCategory(Integer groupId) {
+        // 1. 先拿到已开通应用 + 模块权限树（categoryId 已由 BeanUtils 复制）
+        List<GroupAuthzAppVo> appVos = findGroupAppsWithModules(groupId);
+        if (appVos.isEmpty()) {
+            // 无开通应用时仍返回全部分类（空应用列表），方便前端下拉筛选完整
+            return buildEmptyCategories();
+        }
+
+        // 2. 按 categoryId 分组
+        Map<Integer, List<GroupAuthzAppVo>> categoryAppMap = new HashMap<>();
+        for (GroupAuthzAppVo appVo : appVos) {
+            Integer categoryId = appVo.getCategoryId() == null ? 0 : appVo.getCategoryId();
+            categoryAppMap.computeIfAbsent(categoryId, k -> new ArrayList<>()).add(appVo);
+        }
+
+        // 3. 按分类排序号组装结果，未命中分类的放到“未分类”
+        List<GroupAuthzCategoryVo> result = new ArrayList<>();
+        List<AppCategory> categories = appCategoryRepository.findAllByOrderBySortNoAsc();
+        for (AppCategory category : categories) {
+            GroupAuthzCategoryVo vo = new GroupAuthzCategoryVo();
+            vo.setId(category.getId());
+            vo.setName(category.getName());
+            List<GroupAuthzAppVo> apps = categoryAppMap.remove(category.getId());
+            if (apps != null) {
+                // 同一分类内应用保持排序
+                apps.sort(appVoOrder());
+                vo.getApps().addAll(apps);
+            }
+            result.add(vo);
+        }
+        // 未分类（categoryId 为 null 或不存在）兜底
+        List<GroupAuthzAppVo> uncategorized = categoryAppMap.remove(0);
+        if (uncategorized != null && !uncategorized.isEmpty()) {
+            GroupAuthzCategoryVo vo = new GroupAuthzCategoryVo();
+            vo.setId(0);
+            vo.setName("未分类");
+            uncategorized.sort(appVoOrder());
+            vo.getApps().addAll(uncategorized);
+            result.add(vo);
+        }
+        return result;
+    }
+
+    private List<GroupAuthzCategoryVo> buildEmptyCategories() {
+        List<GroupAuthzCategoryVo> result = new ArrayList<>();
+        for (AppCategory category : appCategoryRepository.findAllByOrderBySortNoAsc()) {
+            GroupAuthzCategoryVo vo = new GroupAuthzCategoryVo();
+            vo.setId(category.getId());
+            vo.setName(category.getName());
+            result.add(vo);
+        }
+        return result;
+    }
+
+    /** 应用VO排序：sortNo 升序（空视为999），再按 id 升序。 */
+    private Comparator<GroupAuthzAppVo> appVoOrder() {
+        return (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId() == null ? 0 : a.getId(), b.getId() == null ? 0 : b.getId());
+        };
+    }
+
+    @Override
+    @Transactional
+    public void saveModulePermissions(GroupModulePermRequest request) {
+        Objects.requireNonNull(request, "组授权入参不能为空");
+        Integer groupId = request.getGroupId();
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("系统组不存在");
+        }
+        List<GroupModulePermRequest.ModulePermItem> perms = request.getPerms() == null ? Collections.emptyList()
+                : request.getPerms();
+        Set<Integer> appIdSet = collectAppIdsForAuthzScope(groupId);
+        Set<Integer> validModuleIds = new HashSet<>();
+        if (!appIdSet.isEmpty()) {
+            for (AppModule m : appModuleRepository.findByAppIdIn(new ArrayList<>(appIdSet))) {
+                validModuleIds.add(m.getId());
+            }
+        }
+        // 现有记录按 moduleId 索引，做差异比对
+        Map<Integer, SysGroupModulePerm> existingMap = new HashMap<>();
+        for (SysGroupModulePerm perm : sysGroupModulePermRepository.findByGroupId(groupId)) {
+            existingMap.put(perm.getModuleId(), perm);
+        }
+        List<SysGroupModulePerm> toSave = new ArrayList<>();
+        Set<Integer> requestedModuleIds = new HashSet<>();
+        for (GroupModulePermRequest.ModulePermItem item : perms) {
+            Integer moduleId = item.getModuleId();
+            if (!validModuleIds.contains(moduleId)) {
+                throw new DException("模块不属于该组已开通的应用: " + moduleId);
+            }
+            if (!requestedModuleIds.add(moduleId)) {
+                throw new DException("模块权限列表存在重复模块: " + moduleId);
+            }
+            boolean inheritFlag = Boolean.TRUE.equals(item.getInheritFlag());
+            SysGroupModulePerm existing = existingMap.get(moduleId);
+            if (existing != null) {
+                // 有旧记录：仅当继承开关变化时更新
+                if (!Objects.equals(existing.getInheritFlag(), inheritFlag)) {
+                    existing.setInheritFlag(inheritFlag);
+                    toSave.add(existing);
+                }
+            } else {
+                // 无旧记录：新增
+                SysGroupModulePerm perm = new SysGroupModulePerm();
+                perm.setGroupId(groupId);
+                perm.setModuleId(moduleId);
+                perm.setInheritFlag(inheritFlag);
+                toSave.add(perm);
+            }
+        }
+        // 取消勾选：旧记录不在本次全量列表中的，物理删除
+        List<SysGroupModulePerm> toDelete = new ArrayList<>();
+        for (Map.Entry<Integer, SysGroupModulePerm> entry : existingMap.entrySet()) {
+            if (!requestedModuleIds.contains(entry.getKey())) {
+                toDelete.add(entry.getValue());
+            }
+        }
+        if (!toSave.isEmpty()) {
+            sysGroupModulePermRepository.saveAll(toSave);
+        }
+        if (!toDelete.isEmpty()) {
+            sysGroupModulePermRepository.deleteAll(toDelete);
+        }
+    }
+
+    // ===================== 新增：树节点式增量授权 =====================
+
+    @Override
+    public List<Integer> findAuthorizedAppIds(Integer nodeId) {
+        Objects.requireNonNull(nodeId, "节点组ID不能为空");
+        if (!sysGroupRepository.existsById(nodeId)) {
+            throw new DException("系统组不存在: " + nodeId);
+        }
+        // 应用开通「不继承」：直接查本组在 sys_group_app_rel 的开通记录，返回 app_id 列表。
+        // 不沿祖先链回填父组开通的应用（父组开通 != 子组拥有），与「开通不继承」原则一致。
+        List<Integer> appIds = new ArrayList<>();
+        for (SysGroupAppRel rel : sysGroupAppRelRepository.findByGroupId(nodeId)) {
+            appIds.add(rel.getAppId());
+        }
+        return appIds;
+    }
+
+    @Override
+    @Transactional
+    public void setSchoolApps(SchoolAppAuthzRequest request) {
+        Integer schId = request.getSchid();
+        Integer appId = request.getAppid();
+        int mode = request.getMode();
+        Objects.requireNonNull(schId, "组ID不能为空");
+        Objects.requireNonNull(appId, "应用ID不能为空");
+        if (!sysGroupRepository.existsById(schId)) {
+            throw new DException("系统组不存在: " + schId);
+        }
+        // 操作模式：仅 0=追加 / 2=删除 合法；1=覆盖 不适用于单条增量，拒绝。
+        // 注：IEnum 的静态方法不被实现类继承，必须用 IEnum.getByKey 调用；未知值返回 null，便于抛清晰错误。
+        SysModeEnum modeEnum = IEnum.getByKey(SysModeEnum.class, mode);
+        if (modeEnum == null || (modeEnum != SysModeEnum.APPEND && modeEnum != SysModeEnum.DELETE)) {
+            throw new DException("不支持的操作模式: " + mode + "，应用授权仅支持 0(追加)/2(删除)");
+        }
+        // 校验应用存在（单值，无需去重/批量）
+        if (!applicationInfoRepository.existsById(appId)) {
+            throw new DException("应用不存在: " + appId);
+        }
+        // 应用开通「不继承」：仅操作 schId 自身，不级联子组（与现有 AssignApps 一致）。
+        if (modeEnum == SysModeEnum.APPEND) {
+            if (!sysGroupAppRelRepository.existsByGroupIdAndAppId(schId, appId)) {
+                SysGroupAppRel rel = new SysGroupAppRel();
+                rel.setGroupId(schId);
+                rel.setAppId(appId);
+                sysGroupAppRelRepository.save(rel);
+            }
+        } else { // DELETE 取消开通
+            sysGroupAppRelRepository.deleteByGroupIdAndAppIdBulk(schId, appId);
+            // 同步清理该组在该应用下模块的权限残留，避免「应用已关但模块权限还在」的脏数据
+            List<Integer> moduleIds = new ArrayList<>();
+            for (AppModule m : appModuleRepository.findByAppIdIn(Collections.singletonList(appId))) {
+                moduleIds.add(m.getId());
+            }
+            if (!moduleIds.isEmpty()) {
+                sysGroupModulePermRepository.deleteByGroupIdAndModuleIdInBulk(schId, moduleIds);
+            }
+        }
+    }
+
+    @Override
+    @Transactional
+    public void setGroupModulePerms(List<GroupModuleAuthzItem> items) {
+        Objects.requireNonNull(items, "组模块授权入参不能为空");
+        for (GroupModuleAuthzItem item : items) {
+            Integer groupId = item.getGroupId();
+            Integer appId = item.getAppId();
+            Integer moduleId = item.getModuleId();
+            int mode = item.getMode();
+            boolean isAll = item.getIsAll() != null && item.getIsAll() == 1;
+            if (!sysGroupRepository.existsById(groupId)) {
+                throw new DException("系统组不存在: " + groupId);
+            }
+            if (!applicationInfoRepository.existsById(appId)) {
+                throw new DException("应用不存在: " + appId);
+            }
+            SysModeEnum modeEnum = IEnum.getByKey(SysModeEnum.class, mode);
+            if (modeEnum == null || (modeEnum != SysModeEnum.APPEND && modeEnum != SysModeEnum.DELETE)) {
+                throw new DException("不支持的操作模式: " + mode + "，模块授权仅支持 0(追加)/2(删除)");
+            }
+            List<Integer> targetModuleIds = resolveModuleIds(appId, moduleId);
+            Set<Integer> scopeAppIds = collectAppIdsForAuthzScope(groupId);
+            for (Integer mid : targetModuleIds) {
+                if (modeEnum == SysModeEnum.APPEND) {
+                    if (!scopeAppIds.contains(appId)) {
+                        throw new DException("组及其祖先均未开通应用 " + appId + "，无法授权其模块 " + mid);
+                    }
+                    SysGroupModulePerm existing = sysGroupModulePermRepository.findByGroupIdAndModuleId(groupId, mid);
+                    if (existing != null) {
+                        if (!Objects.equals(existing.getInheritFlag(), isAll)) {
+                            existing.setInheritFlag(isAll);
+                            sysGroupModulePermRepository.save(existing);
+                        }
+                    } else {
+                        SysGroupModulePerm perm = new SysGroupModulePerm();
+                        perm.setGroupId(groupId);
+                        perm.setModuleId(mid);
+                        perm.setInheritFlag(isAll);
+                        sysGroupModulePermRepository.save(perm);
+                    }
+                } else {
+                    sysGroupModulePermRepository.deleteByGroupIdAndModuleIdBulk(groupId, mid);
+                }
+            }
+        }
+    }
+
+    /**
+     * 解析某条授权项实际要操作的模块ID集合。<br>
+     * - moduleId 为 null 或 0：返回该应用下全部真实模块的 ID（「整应用」语义）。<br>
+     * - 具体 moduleId：校验其确实存在且属于该应用，越权写别的应用的模块会被拒绝。<br>
+     */
+    private List<Integer> resolveModuleIds(Integer appId, Integer moduleId) {
+        if (moduleId == null || moduleId == 0) {
+            List<Integer> ids = new ArrayList<>();
+            for (AppModule m : appModuleRepository.findByAppIdIn(Collections.singletonList(appId))) {
+                ids.add(m.getId());
+            }
+            return ids;
+        }
+        AppModule m = appModuleRepository.findById(moduleId).orElse(null);
+        if (m == null) {
+            throw new DException("模块不存在: " + moduleId);
+        }
+        if (!Objects.equals(m.getAppId(), appId)) {
+            throw new DException("模块 " + moduleId + " 不属于应用 " + appId);
+        }
+        return Collections.singletonList(moduleId);
+    }
+
+    // ===================== 开放接口专用：单应用维度模块过滤 =====================
+
+    @Override
+    public List<BoaModule> findUserModulesForApp(Integer appId, Integer schId, Integer userId) {
+        Objects.requireNonNull(appId, "应用ID不能为空");
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        // 1. 调用方应用本身存在性校验（数据库过滤第一层：appId 必须真实存在，否则直接空）
+        ApplicationInfo app = applicationInfoRepository.findById(appId).orElse(null);
+        if (app == null) {
+            return Collections.emptyList();
+        }
+        String appIcon = app.getPcIcon();
+        SysUser user = sysUserRepository.findById(userId).orElse(null);
+        if (user == null) {
+            return Collections.emptyList();
+        }
+        // 2. 超级管理员短路：不再返回全应用模块=仅返回该应用下全部模块（数据库过滤第二层：appId 限定）
+        if (isSuperAdmin(user.getType(), userId)) {
+            List<AppModule> allModules = appModuleRepository.findByAppIdIn(Collections.singletonList(appId));
+            return flattenToBoaModules(allModules, appIcon);
+        }
+        // 3. 收集该用户启用角色下=属于目标应用的模块ID（角色授权并集，不要求组先开通应用）
+        Set<Integer> roleModuleIdsInApp = collectEnabledRoleModuleIdsForApp(userId, appId);
+        // 4. 归属组集合解析（与权限一览 findUserPermissionTree 语义对齐，修复"只返回学校节点"的 bug）：
+        //    - schId 非空：只取用户真实归属组中「位于该学校子树内」的组（含直接挂学校组本身），
+        //      每个组独立建链向上判定；子树内无任何归属组 → 保留空 selfGroupIds（方案A：仅靠角色授权拿模块，
+        //      不把 schId 冒充本组，否则会绕过子组继承闸门、丢本组数据）；
+        //    - schId 空：取用户全部真实归属组（与权限一览「用户全局模式」一致）。
+        List<SysUserGroupRel> userRels = sysUserGroupRelRepository.findByUserId(userId);
+        Map<Integer, SysGroup> allGroupMap = buildAllGroupMap();
+        Set<Integer> selfGroupIds = new LinkedHashSet<>();
+        if (schId != null) {
+            for (SysUserGroupRel rel : userRels) {
+                Integer gid = rel.getGroupId();
+                if (gid == null) {
+                    continue;
+                }
+                if (gid.equals(schId) || ancestorChain(gid, allGroupMap).contains(schId)) {
+                    selfGroupIds.add(gid);
+                }
+            }
+        } else {
+            for (SysUserGroupRel rel : userRels) {
+                if (rel.getGroupId() != null) {
+                    selfGroupIds.add(rel.getGroupId());
+                }
+            }
+        }
+        // 5. 构建各归属组的祖先链与开通池，并判定：任意归属组开通池里是否包含目标 appId（应用开通闸门）。
+        //    归属组为空（该学校子树内无组 / 无学校无组）时仍可能因角色授权而返回模块，不能直接返回空。
+        Map<Integer, List<Integer>> chainMap = new HashMap<>();
+        Set<Integer> allChainIds = new LinkedHashSet<>();
+        Map<Integer, Set<Integer>> groupToApps = new HashMap<>();
+        boolean appOpened = false;
+        for (Integer gid : selfGroupIds) {
+            List<Integer> chain = ancestorChain(gid, allGroupMap);
+            chainMap.put(gid, chain);
+            allChainIds.addAll(chain);
+            Set<Integer> openedApps = collectAppIdsForAuthzScope(gid);
+            groupToApps.put(gid, openedApps);
+            if (openedApps.contains(appId)) {
+                appOpened = true;
+            }
+        }
+        // 6. 数据库过滤第三层：只加载目标应用下的模块
+        List<AppModule> appModules = appModuleRepository.findByAppIdIn(Collections.singletonList(appId));
+        if (appModules.isEmpty()) {
+            return (roleModuleIdsInApp.isEmpty()) ? Collections.emptyList()
+                    : flattenToBoaModulesById(roleModuleIdsInApp, appIcon, buildAppModuleMap(appModules));
+        }
+        Set<Integer> appModuleIds = new LinkedHashSet<>();
+        for (AppModule m : appModules) {
+            appModuleIds.add(m.getId());
+        }
+        // 7. 数据库过滤第四层：只查「目标应用模块 × 祖先链」上的组授权记录
+        Map<Integer, Map<Integer, SysGroupModulePerm>> modulePermMap = new HashMap<>();
+        Map<Integer, Set<Integer>> groupConfiguredApps = new HashMap<>();
+        if (appOpened && !appModuleIds.isEmpty() && !allChainIds.isEmpty()) {
+            List<SysGroupModulePerm> perms = sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                    new ArrayList<>(appModuleIds), new ArrayList<>(allChainIds));
+            for (SysGroupModulePerm perm : perms) {
+                if (perm.getModuleId() == null || perm.getGroupId() == null) {
+                    continue;
+                }
+                modulePermMap.computeIfAbsent(perm.getModuleId(), k -> new HashMap<>())
+                        .put(perm.getGroupId(), perm);
+                groupConfiguredApps.computeIfAbsent(perm.getGroupId(), k -> new HashSet<>()).add(appId);
+            }
+        }
+        // 8. 权限判定合并：组授权 ∪ 角色授权（均属于该应用）
+        Set<Integer> permittedModuleIds = new LinkedHashSet<>();
+        for (Integer mid : roleModuleIdsInApp) {
+            if (appModuleIds.contains(mid)) {
+                permittedModuleIds.add(mid);
+            }
+        }
+        if (appOpened) {
+            for (AppModule m : appModules) {
+                if (permittedModuleIds.contains(m.getId())) {
+                    continue;
+                }
+                if (hasUserModulePermission(m.getId(), m.getAppId(), selfGroupIds, chainMap, groupToApps,
+                        modulePermMap, allGroupMap, groupConfiguredApps)) {
+                    permittedModuleIds.add(m.getId());
+                }
+            }
+        }
+        if (permittedModuleIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        return flattenToBoaModulesById(permittedModuleIds, appIcon, buildAppModuleMap(appModules));
+    }
+
+    /**
+     * 收集用户启用角色下=且属于目标应用 appId 的模块ID集合（角色授权并集专用的"应用过滤版"）。<br>
+     * 与 {@link #collectEnabledRoleModuleIds(Integer)} 的区别：后者返回全部角色模块；
+     * 本方法在其之上再按模块.appId == appId 过滤一次（不额外发 SQL，遍历两次即可）。
+     */
+    private Set<Integer> collectEnabledRoleModuleIdsForApp(Integer userId, Integer appId) {
+        Set<Integer> allRoleModuleIds = collectEnabledRoleModuleIds(userId);
+        if (allRoleModuleIds.isEmpty() || appId == null) {
+            return Collections.emptySet();
+        }
+        Set<Integer> result = new LinkedHashSet<>();
+        for (AppModule m : appModuleRepository.findAllById(allRoleModuleIds)) {
+            if (Objects.equals(m.getAppId(), appId) && m.getId() != null) {
+                result.add(m.getId());
+            }
+        }
+        return result;
+    }
+
+    private static Map<Integer, AppModule> buildAppModuleMap(List<AppModule> appModules) {
+        Map<Integer, AppModule> map = new HashMap<>();
+        for (AppModule m : appModules) {
+            if (m.getId() != null) {
+                map.put(m.getId(), m);
+            }
+        }
+        return map;
+    }
+
+    private static List<BoaModule> flattenToBoaModules(List<AppModule> modules, String icon) {
+        if (modules == null || modules.isEmpty()) {
+            return Collections.emptyList();
+        }
+        modules.sort(moduleOrder());
+        List<BoaModule> result = new ArrayList<>(modules.size());
+        for (AppModule m : modules) {
+            result.add(toBoaModule(m, icon));
+        }
+        return result;
+    }
+
+    private static List<BoaModule> flattenToBoaModulesById(Set<Integer> moduleIds, String icon,
+            Map<Integer, AppModule> moduleMap) {
+        if (moduleIds == null || moduleIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<AppModule> list = new ArrayList<>(moduleIds.size());
+        for (Integer mid : moduleIds) {
+            AppModule m = moduleMap.get(mid);
+            if (m != null) {
+                list.add(m);
+            }
+        }
+        return flattenToBoaModules(list, icon);
+    }
+
+    private static BoaModule toBoaModule(AppModule m, String icon) {
+        BoaModule bm = new BoaModule();
+        BeanUtils.copyProperties(m, bm);
+        bm.setIcon(icon);
+        return bm;
+    }
+
+    private static Comparator<AppModule> moduleOrder() {
+        return (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId() == null ? 0 : a.getId(), b.getId() == null ? 0 : b.getId());
+        };
+    }
+
+    // ===================== 权限一览 =====================
+
+    @Override
+    public List<UserPermissionUserVo> findGroupUsers(Integer groupId) {
+        Objects.requireNonNull(groupId, "组ID不能为空");
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("系统组不存在");
+        }
+        List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByGroupId(groupId);
+        if (rels.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Set<Integer> userIds = new LinkedHashSet<>();
+        for (SysUserGroupRel rel : rels) {
+            if (rel.getUserId() != null) {
+                userIds.add(rel.getUserId());
+            }
+        }
+        Map<Integer, SysUser> userMap = new HashMap<>();
+        for (SysUser user : sysUserRepository.findAllById(userIds)) {
+            userMap.put(user.getId(), user);
+        }
+        String groupPath = buildGroupPath(groupId, buildAllGroupMap());
+
+        List<UserPermissionUserVo> result = new ArrayList<>();
+        for (SysUserGroupRel rel : rels) {
+            SysUser user = userMap.get(rel.getUserId());
+            if (user == null) {
+                continue;
+            }
+            UserPermissionUserVo vo = new UserPermissionUserVo();
+            vo.setId(user.getId());
+            vo.setAccount(user.getAccount());
+            vo.setRealName(user.getRealName());
+            vo.setIsMain(rel.getIsMain());
+            vo.setGroupPath(groupPath);
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    public List<UserPermissionUserVo> searchUsers(String keyword) {
+        if (keyword == null) {
+            keyword = "";
+        }
+        String kw = keyword.trim();
+        if (kw.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Specification<SysUser> spec = buildUserSearchSpec(kw);
+        List<SysUser> users = sysUserRepository.findAll(spec);
+        if (users.isEmpty()) {
+            return Collections.emptyList();
+        }
+
+        // 加载所有组，用于构建主归属路径
+        Map<Integer, SysGroup> allGroupMap = buildAllGroupMap();
+        // 加载用户与组关联，找到每个用户的主归属组
+        Set<Integer> userIds = new LinkedHashSet<>();
+        for (SysUser user : users) {
+            userIds.add(user.getId());
+        }
+        Map<Integer, SysUserGroupRel> mainRelMap = new HashMap<>();
+        for (SysUserGroupRel rel : sysUserGroupRelRepository.findAll()) {
+            if (rel.getUserId() == null || !userIds.contains(rel.getUserId())) {
+                continue;
+            }
+            SysUserGroupRel existing = mainRelMap.get(rel.getUserId());
+            // 优先取主归属（isMain=1），否则保留第一个
+            if (existing == null || (existing.getIsMain() == null || existing.getIsMain() != 1)
+                    && rel.getIsMain() != null && rel.getIsMain() == 1) {
+                mainRelMap.put(rel.getUserId(), rel);
+            }
+        }
+
+        List<UserPermissionUserVo> result = new ArrayList<>();
+        for (SysUser user : users) {
+            SysUserGroupRel mainRel = mainRelMap.get(user.getId());
+            String path = "";
+            if (mainRel != null && mainRel.getGroupId() != null) {
+                path = buildGroupPath(mainRel.getGroupId(), allGroupMap);
+            }
+            UserPermissionUserVo vo = new UserPermissionUserVo();
+            vo.setId(user.getId());
+            vo.setAccount(user.getAccount());
+            vo.setRealName(user.getRealName());
+            vo.setIsMain(mainRel != null ? mainRel.getIsMain() : null);
+            vo.setGroupPath(path);
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    public List<UserPermissionCategoryVo> findUserPermissionTree(Integer groupId, Integer userId) {
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        SysUser user = sysUserRepository.findById(userId).orElse(null);
+        if (user == null) {
+            throw new DException("用户不存在");
+        }
+        // ============================================================
+        // 超级管理员（UserTypeEnum.SUPER_ADMIN，type=1）：直接返回所有已开通应用下的全部模块，不做任何组/继承判定
+        // ============================================================
+        if (isSuperAdmin(user.getType(), userId)) {
+            return buildSuperAdminAllPermissions();
+        }
+        // AI-FIX(角色授权): 先取用户经「启用」角色获得的模块ID集合，与组授权做并集；
+        // 角色授权不依赖组归属与组开通应用，故下方不再因无组归属而提前返回
+        Set<Integer> roleModuleIds = collectEnabledRoleModuleIds(userId);
+
+        // 1. 归属组集合：区分「组上下文模式」和「用户全局模式」
+        // A) 接口显式传了 groupId（= 管理员在"某个组的授权面板"点用户权限一览，是典型的组视角查询）：
+        // 以传入的 groupId 作为唯一 selfGroupId，仅沿「该组 -> 祖先 -> 第一个学校组（含）」链路判定；
+        // 【关键】不再把用户真实加入的其他组（例如用户还属于学校组）并入判断。
+        // 原因：如果允许用户归属的"学校组"作为独立 selfGroupId 参与本组显式判定，
+        // 则子组未设置的模块会直接命中学校组自己的显式记录（permMap.get(学校组)!=null），
+        // 导致"子组设置的覆盖限制"完全失效=父级所有模块都拿到，即你观察到的"本组继承没生效/还是父级全量"。
+        // B) 未传 groupId（全局查用户权限/开放接口 modules 未传schId以外的其他上下文）：
+        // 正常取用户所有真实归属组并集。
+        List<SysUserGroupRel> userRels = sysUserGroupRelRepository.findByUserId(userId);
+        Set<Integer> selfGroupIds = new LinkedHashSet<>();
+        if (groupId != null) {
+            // 组上下文模式：只认传入的 groupId，不认其他真实归属组（避免越级命中显式记录）
+            selfGroupIds.add(groupId);
+        } else {
+            // 用户全局模式：按真实归属组并集
+            for (SysUserGroupRel rel : userRels) {
+                if (rel.getGroupId() != null) {
+                    selfGroupIds.add(rel.getGroupId());
+                }
+            }
+        }
+
+        // 2. 全部组，构建祖先链
+        Map<Integer, SysGroup> allGroupMap = buildAllGroupMap();
+        Map<Integer, List<Integer>> chainMap = new HashMap<>();
+        Set<Integer> allChainIds = new LinkedHashSet<>();
+        for (Integer groupIdItem : selfGroupIds) {
+            List<Integer> chain = ancestorChain(groupIdItem, allGroupMap);
+            chainMap.put(groupIdItem, chain);
+            allChainIds.addAll(chain);
+        }
+
+        // 3. 收集「用户归属组 + 其祖先链」所有组已开通的应用并集。
+        // 安全：hasUserModulePermission 仍会判定 groupId（当前归属组）必须在 openedApps
+        // 链上（即归属组或其祖先开通应用），
+        // 不会出现“无组归属、父级未开”的越权；此处只是把过滤和写面板（GroupModuleTreeByCategory）联动对齐，
+        // 解决之前“管理员在组8面板勾了checked=true，但UserPermissionTree返回空”的对称bug。
+        Map<Integer, Set<Integer>> groupToApps = new HashMap<>();
+        Set<Integer> allAppIds = new LinkedHashSet<>();
+        for (Integer groupIdItem : selfGroupIds) {
+            Set<Integer> apps = collectAppIdsForAuthzScope(groupIdItem);
+            groupToApps.put(groupIdItem, apps);
+            allAppIds.addAll(apps);
+        }
+        // AI-FIX(角色授权): 最终应用范围 = 组开通应用 ∪ 角色模块所属应用（角色模块不要求组先开通应用）
+        if (!roleModuleIds.isEmpty()) {
+            for (AppModule m : appModuleRepository.findAllById(roleModuleIds)) {
+                if (m.getAppId() != null) {
+                    allAppIds.add(m.getAppId());
+                }
+            }
+        }
+        if (allAppIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+
+        // 4. 查询应用与分类
+        Map<Integer, ApplicationInfo> appMap = new HashMap<>();
+        List<ApplicationInfo> apps = applicationInfoRepository.findAllById(allAppIds);
+        for (ApplicationInfo app : apps) {
+            appMap.put(app.getId(), app);
+        }
+
+        // 5. 查询这些应用下的所有模块
+        List<AppModule> allModules = appModuleRepository.findByAppIdIn(new ArrayList<>(allAppIds));
+        if (allModules.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Set<Integer> allModuleIds = new LinkedHashSet<>();
+        Map<Integer, List<AppModule>> appModulesMap = new HashMap<>();
+        Map<Integer, Integer> moduleToAppMap = new HashMap<>();
+        for (AppModule m : allModules) {
+            allModuleIds.add(m.getId());
+            appModulesMap.computeIfAbsent(m.getAppId(), k -> new ArrayList<>()).add(m);
+            moduleToAppMap.put(m.getId(), m.getAppId());
+        }
+
+        // 6. 批量查询所有相关模块在所有相关组/祖先上的权限记录
+        Map<Integer, Map<Integer, SysGroupModulePerm>> modulePermMap = new HashMap<>();
+        // AI-FIX(角色授权): 用户可能无任何组归属（纯角色授权），祖先链为空时跳过 IN 空集合查询
+        if (!allChainIds.isEmpty()) {
+            List<SysGroupModulePerm> perms = sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                    new ArrayList<>(allModuleIds), new ArrayList<>(allChainIds));
+            for (SysGroupModulePerm perm : perms) {
+                if (perm.getModuleId() == null || perm.getGroupId() == null) {
+                    continue;
+                }
+                modulePermMap.computeIfAbsent(perm.getModuleId(), k -> new HashMap<>()).put(perm.getGroupId(), perm);
+            }
+        }
+
+        // AI-FIX(应用级覆盖): 某组只要对该应用有任意显式模块配置，子孙/本组就只按该组配置判定，
+        // 不再继承更上层祖先的同应用模块权限（避免「子组只勾了1个模块，却仍继承学校全部模块」）。
+        Map<Integer, Set<Integer>> groupConfiguredApps = new HashMap<>();
+        for (Map.Entry<Integer, Map<Integer, SysGroupModulePerm>> entry : modulePermMap.entrySet()) {
+            Integer appId = moduleToAppMap.get(entry.getKey());
+            if (appId == null) {
+                continue;
+            }
+            for (Integer gid : entry.getValue().keySet()) {
+                groupConfiguredApps.computeIfAbsent(gid, k -> new HashSet<>()).add(appId);
+            }
+        }
+
+        // 7. 判定每个模块是否有权限
+        // AI-FIX(角色授权): 最终模块权限 = 组授权模块 ∪ 角色授权模块
+        Set<Integer> permittedModuleIds = new LinkedHashSet<>();
+        for (AppModule m : allModules) {
+            if (roleModuleIds.contains(m.getId())
+                    || hasUserModulePermission(m.getId(), m.getAppId(), selfGroupIds, chainMap, groupToApps,
+                            modulePermMap, allGroupMap, groupConfiguredApps)) {
+                permittedModuleIds.add(m.getId());
+            }
+        }
+        if (permittedModuleIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+
+        // 8. 按应用过滤并构建模块树（仅保留有权限的模块）
+        Map<Integer, List<UserPermissionAppVo>> categoryAppMap = new HashMap<>();
+        for (Map.Entry<Integer, List<AppModule>> entry : appModulesMap.entrySet()) {
+            Integer appId = entry.getKey();
+            ApplicationInfo app = appMap.get(appId);
+            if (app == null) {
+                continue;
+            }
+            List<UserPermissionModuleVo> moduleTree = buildUserPermissionModuleTree(
+                    entry.getValue(), permittedModuleIds);
+            if (moduleTree.isEmpty()) {
+                continue; // 无授权模块的应用不显示
+            }
+            UserPermissionAppVo appVo = new UserPermissionAppVo();
+            appVo.setId(app.getId());
+            appVo.setName(app.getName());
+            appVo.setAppKey(app.getAppKey());
+            appVo.setPcIcon(app.getPcIcon());
+            appVo.setSortNo(app.getSortNo());
+            appVo.setModules(moduleTree);
+            Integer categoryId = app.getCategoryId() == null ? 0 : app.getCategoryId();
+            categoryAppMap.computeIfAbsent(categoryId, k -> new ArrayList<>()).add(appVo);
+        }
+        if (categoryAppMap.isEmpty()) {
+            return Collections.emptyList();
+        }
+
+        // 9. 按分类排序号组装结果，只返回有应用的分组
+        List<UserPermissionCategoryVo> result = new ArrayList<>();
+        List<AppCategory> categories = appCategoryRepository.findAllByOrderBySortNoAsc();
+        for (AppCategory category : categories) {
+            List<UserPermissionAppVo> appVos = categoryAppMap.remove(category.getId());
+            if (appVos == null || appVos.isEmpty()) {
+                continue;
+            }
+            appVos.sort(userPermissionAppOrder());
+            UserPermissionCategoryVo vo = new UserPermissionCategoryVo();
+            vo.setId(category.getId());
+            vo.setName(category.getName());
+            vo.setSortNo(category.getSortNo());
+            vo.getApps().addAll(appVos);
+            result.add(vo);
+        }
+        // 未分类兜底
+        List<UserPermissionAppVo> uncategorized = categoryAppMap.remove(0);
+        if (uncategorized != null && !uncategorized.isEmpty()) {
+            uncategorized.sort(userPermissionAppOrder());
+            UserPermissionCategoryVo vo = new UserPermissionCategoryVo();
+            vo.setId(0);
+            vo.setName("未分类");
+            vo.setSortNo(999);
+            vo.getApps().addAll(uncategorized);
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    public List<UserRoleVo> findUserRoles(Integer userId) {
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("用户不存在");
+        }
+        List<SysUserAppRoleRel> rels = sysUserAppRoleRelRepository.findByUserId(userId);
+        if (rels.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Set<Integer> roleIds = new LinkedHashSet<>();
+        for (SysUserAppRoleRel rel : rels) {
+            if (rel.getRoleId() != null) {
+                roleIds.add(rel.getRoleId());
+            }
+        }
+        Map<Integer, SysAppRole> roleMap = new HashMap<>();
+        Set<Integer> appIds = new LinkedHashSet<>();
+        for (SysAppRole role : sysAppRoleRepository.findAllById(roleIds)) {
+            roleMap.put(role.getId(), role);
+            if (role.getAppId() != null) {
+                appIds.add(role.getAppId());
+            }
+        }
+        // 批量取应用名称，普通角色回填 appName
+        Map<Integer, String> appNameMap = new HashMap<>();
+        if (!appIds.isEmpty()) {
+            for (ApplicationInfo app : applicationInfoRepository.findAllById(appIds)) {
+                appNameMap.put(app.getId(), app.getName());
+            }
+        }
+        List<UserRoleVo> result = new ArrayList<>();
+        for (Integer roleId : roleIds) {
+            SysAppRole role = roleMap.get(roleId);
+            if (role == null) {
+                continue;
+            }
+            UserRoleVo vo = new UserRoleVo();
+            vo.setId(role.getId());
+            vo.setName(role.getName());
+            vo.setAllAppFlag(role.getAllAppFlag());
+            vo.setAppId(role.getAppId());
+            if (role.getAppId() != null) {
+                vo.setAppName(appNameMap.get(role.getAppId()));
+            }
+            vo.setDisabled(role.getDisabled());
+            result.add(vo);
+        }
+        return result;
+    }
+
+    @Override
+    public List<UserGroupNodeVo> findUserGroupTree(Integer userId) {
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("用户不存在");
+        }
+        // 1. 用户直接归属的组
+        List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByUserId(userId);
+        Set<Integer> selfGroupIds = new LinkedHashSet<>();
+        for (SysUserGroupRel rel : rels) {
+            if (rel.getGroupId() != null) {
+                selfGroupIds.add(rel.getGroupId());
+            }
+        }
+        if (selfGroupIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        // 2. 祖先链并集（含自身）；多个归属组共享祖先时只出现一次
+        Map<Integer, SysGroup> allGroupMap = buildAllGroupMap();
+        Set<Integer> nodeIds = new LinkedHashSet<>();
+        for (Integer gid : selfGroupIds) {
+            nodeIds.addAll(ancestorChain(gid, allGroupMap));
+        }
+        if (nodeIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        // 3. 仅用链上节点组装树：父节点在链上则挂到父下，否则视为根
+        Map<Integer, UserGroupNodeVo> voMap = new LinkedHashMap<>();
+        for (Integer id : nodeIds) {
+            SysGroup g = allGroupMap.get(id);
+            UserGroupNodeVo vo = new UserGroupNodeVo();
+            vo.setId(id);
+            vo.setName(g == null || g.getName() == null ? String.valueOf(id) : g.getName());
+            vo.setOwn(selfGroupIds.contains(id));
+            voMap.put(id, vo);
+        }
+        List<UserGroupNodeVo> roots = new ArrayList<>();
+        for (Integer id : nodeIds) {
+            SysGroup g = allGroupMap.get(id);
+            Integer parentId = (g == null) ? null : g.getParentId();
+            UserGroupNodeVo parent = (parentId == null) ? null : voMap.get(parentId);
+            if (parent != null) {
+                parent.getChildren().add(voMap.get(id));
+            } else {
+                roots.add(voMap.get(id));
+            }
+        }
+        return roots;
+    }
+
+    /**
+     * 就近原则：在 groupId 的祖先链上，找到离它最近的、对目标应用有显式模块配置的组（含自身）。
+     *
+     * <p>
+     * 链首即自身（{@link #ancestorChain} 由自身向根排列），天然「就近优先」；遍历时第一个
+     * 「groupConfiguredApps 中包含该应用」的组即作为该应用在本组范围内的<b>唯一权限来源</b>返回。
+     *
+     * <p>
+     * 学校截止：遇到学校组（无论是否已配置）即作为继承上限，不再向教育局/根越级，避免跨学校继承到未开通的应用。
+     *
+     * <p>
+     * 找不到返回 null（该应用在此范围内没有任何组的显式配置，对应模块不许可）。
+     */
+    private Integer findNearestAuthorityGroup(Integer groupId, List<Integer> chain,
+            Integer appId, Map<Integer, Set<Integer>> groupConfiguredApps,
+            Map<Integer, SysGroup> allGroupMap) {
+        if (chain == null || chain.isEmpty()) {
+            return null;
+        }
+        for (Integer gid : chain) {
+            Set<Integer> apps = groupConfiguredApps.get(gid);
+            if (apps != null && apps.contains(appId)) {
+                return gid;
+            }
+            SysGroup g = allGroupMap.get(gid);
+            if (g != null && g.getType() == GroupTypeEnum.SCHOOL_GROUP) {
+                break;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * 子组继承闸门：判定「来源组 authority 对 moduleId 的记录」是否对<b>本组</b> selfGroupId 生效。
+     *
+     * <p>
+     * 规则（修复「父级未勾子组继承却仍被继承」的 bug）：
+     * ① 来源组 == 本组：本组自身勾选的模块直接生效——{@code inheritFlag} 只约束是否下放到<b>子组</b>，不影响本组自己；
+     * ② 来源组为祖先（往上回溯得来）：必须勾选了「子组继承」({@code inheritFlag=true}) 才会下放到本组，
+     * 否则该模块不继承。即「只过滤勾选了子组继承的模块；若来源组对该应用所有模块都没勾子组继承，则本组对该应用返回空」。
+     */
+    private boolean isPermEffectiveForSelf(Integer authority, Integer selfGroupId,
+            Map<Integer, SysGroupModulePerm> permMap) {
+        SysGroupModulePerm perm = (permMap == null) ? null : permMap.get(authority);
+        if (perm == null) {
+            return false;
+        }
+        if (authority.equals(selfGroupId)) {
+            return true;
+        }
+        return Boolean.TRUE.equals(perm.getInheritFlag());
+    }
+
+    /**
+     * 用户维度权限判定：用户对指定模块是否有权限（就近原则 + 学校截止 + 角色授权并集 + 超管兜底）。
+     *
+     * <p>
+     * <b>就近原则</b>（统一了「本组覆盖」与「最近祖先继承」两种情形，修复两类合并 bug）：
+     * 沿 selfGroupId 的祖先链（含自身）向上，找到「离它最近、且对 appId 有任意显式模块配置」的组作为
+     * 该应用的<b>唯一权限来源</b>；该模块被许可，当且仅当这个来源组对它自身有显式 {@code sys_group_module_perm} 记录。
+     * 这样：
+     * ① 本组有配置（如英语组只勾模块8）→ 本组即来源，只返回本组勾选的模块，不再合并学校全部模块；
+     * ② 本组无配置（如英语组为空）→ 取<b>最近</b>的有配置祖先（如教师组）为来源，不再越级到更远的学校组；
+     * ③ 来源组的模块集合即最终集合，更上层同应用模块（如学校组多勾的模块8）一律不合并。
+     *
+     * <p>
+     * <b>子组继承闸门</b>（修复「父级未勾子组继承仍被继承」的 bug）：来源组若是本组，本组勾选的模块直接生效；
+     * 来源组若是祖先，必须该模块记录 {@code inheritFlag=true}（勾选子组继承）才下放到本组，否则不继承——
+     * 即「只过滤勾选了子组继承的模块；若来源组对该应用所有模块都没勾子组继承，则本组对该应用返回空」。
+     *
+     * <p>
+     * <b>学校截止</b>：祖先链只查到第一个学校组（含）为止，不跨学校到教育局/根。
+     *
+     * <p>
+     * <b>其余</b>：归属组需已开通该模块所属应用（双保险，防越权）。
+     */
+    private boolean hasUserModulePermission(Integer moduleId, Integer appId,
+            Set<Integer> selfGroupIds,
+            Map<Integer, List<Integer>> chainMap,
+            Map<Integer, Set<Integer>> groupToApps,
+            Map<Integer, Map<Integer, SysGroupModulePerm>> modulePermMap,
+            Map<Integer, SysGroup> allGroupMap,
+            Map<Integer, Set<Integer>> groupConfiguredApps) {
+        Map<Integer, SysGroupModulePerm> permMap = modulePermMap.get(moduleId);
+        for (Integer selfGroupId : selfGroupIds) {
+            Set<Integer> openedApps = groupToApps.get(selfGroupId);
+            if (openedApps == null || !openedApps.contains(appId)) {
+                continue;
+            }
+            List<Integer> chain = chainMap.get(selfGroupId);
+            if (chain == null || chain.isEmpty()) {
+                continue;
+            }
+            // 就近原则：取离本组最近、对该应用有显式配置的组作为唯一权限来源
+            Integer authority = findNearestAuthorityGroup(selfGroupId, chain, appId, groupConfiguredApps, allGroupMap);
+            if (authority == null) {
+                continue;
+            }
+            // 来源组对该模块有显式记录，且（来源是本组 或 来源是祖先且勾选了子组继承）→ 许可；
+            // 否则（来源组未勾此模块 / 祖先未开启子组继承）不许可。
+            if (isPermEffectiveForSelf(authority, selfGroupId, permMap)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // ===================== 超级管理员 & 工具方法 =====================
+
+    /**
+     * 超级管理员判定：
+     * ① 用户记录的 type = UserTypeEnum.SUPER_ADMIN（1）；或
+     * ② userId = DicUtil.SUPER_ADMIN_ID（100000，系统内置基石超级管理员账号）。
+     * 任一命中即可视为超级管理员，直接授予全部模块权限。
+     */
+    private static boolean isSuperAdmin(UserTypeEnum userType, Integer userId) {
+        if (userType != null && UserTypeEnum.SUPER_ADMIN.getKey().equals(userType.getKey())) {
+            return true;
+        }
+        return userId != null && com.yunhai.userbase.utils.DicUtil.SUPER_ADMIN_ID.equals(userId);
+    }
+
+    /**
+     * 超级管理员全模块权限：不依赖组/继承，直接「所有已分类应用下的模块」全量返回。
+     * 应用范围 = 所有已分类（category 存在）且有模块的应用，按应用过滤构建分类→应用→模块树。
+     */
+    private List<UserPermissionCategoryVo> buildSuperAdminAllPermissions() {
+        List<AppCategory> categories = appCategoryRepository.findAllByOrderBySortNoAsc();
+        List<ApplicationInfo> allApps = applicationInfoRepository.findAll();
+        allApps.sort(appOrder());
+        Map<Integer, ApplicationInfo> appMap = new HashMap<>();
+        Set<Integer> allAppIds = new LinkedHashSet<>();
+        for (ApplicationInfo app : allApps) {
+            appMap.put(app.getId(), app);
+            allAppIds.add(app.getId());
+        }
+        if (allAppIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<AppModule> allModules = appModuleRepository.findByAppIdIn(new ArrayList<>(allAppIds));
+        if (allModules.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Map<Integer, List<AppModule>> appModulesMap = new HashMap<>();
+        Set<Integer> allModuleIds = new LinkedHashSet<>();
+        for (AppModule m : allModules) {
+            allModuleIds.add(m.getId());
+            appModulesMap.computeIfAbsent(m.getAppId(), k -> new ArrayList<>()).add(m);
+        }
+        Map<Integer, List<UserPermissionAppVo>> categoryAppMap = new HashMap<>();
+        for (Map.Entry<Integer, List<AppModule>> entry : appModulesMap.entrySet()) {
+            Integer appId = entry.getKey();
+            ApplicationInfo app = appMap.get(appId);
+            if (app == null) {
+                continue;
+            }
+            List<UserPermissionModuleVo> moduleTree = buildUserPermissionModuleTree(entry.getValue(), allModuleIds);
+            if (moduleTree.isEmpty()) {
+                continue;
+            }
+            UserPermissionAppVo appVo = new UserPermissionAppVo();
+            appVo.setId(app.getId());
+            appVo.setName(app.getName());
+            appVo.setAppKey(app.getAppKey());
+            appVo.setPcIcon(app.getPcIcon());
+            appVo.setSortNo(app.getSortNo());
+            appVo.setModules(moduleTree);
+            Integer categoryId = app.getCategoryId() == null ? 0 : app.getCategoryId();
+            categoryAppMap.computeIfAbsent(categoryId, k -> new ArrayList<>()).add(appVo);
+        }
+        if (categoryAppMap.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<UserPermissionCategoryVo> result = new ArrayList<>();
+        for (AppCategory category : categories) {
+            List<UserPermissionAppVo> appVos = categoryAppMap.remove(category.getId());
+            if (appVos == null || appVos.isEmpty()) {
+                continue;
+            }
+            appVos.sort(userPermissionAppOrder());
+            UserPermissionCategoryVo c = new UserPermissionCategoryVo();
+            c.setId(category.getId());
+            c.setName(category.getName());
+            c.setSortNo(category.getSortNo());
+            c.setApps(appVos);
+            result.add(c);
+        }
+        List<UserPermissionAppVo> remain = categoryAppMap.remove(0);
+        if (remain != null && !remain.isEmpty()) {
+            remain.sort(userPermissionAppOrder());
+            UserPermissionCategoryVo uncategorized = new UserPermissionCategoryVo();
+            uncategorized.setId(0);
+            uncategorized.setName("未分类");
+            uncategorized.setSortNo(Integer.MAX_VALUE);
+            uncategorized.setApps(remain);
+            result.add(uncategorized);
+        }
+        result.sort(Comparator.comparingInt(c -> c.getSortNo() == null ? Integer.MAX_VALUE : c.getSortNo()));
+        return result;
+    }
+
+    /**
+     * 构建用户权限一览的模块树：仅保留有权限的模块，父节点无权限时子节点挂到根级。
+     */
+    private List<UserPermissionModuleVo> buildUserPermissionModuleTree(List<AppModule> modules,
+            Set<Integer> permittedModuleIds) {
+        // 先过滤
+        List<AppModule> permitted = new ArrayList<>();
+        for (AppModule m : modules) {
+            if (permittedModuleIds.contains(m.getId())) {
+                permitted.add(m);
+            }
+        }
+        if (permitted.isEmpty()) {
+            return Collections.emptyList();
+        }
+        // parentId -> 子节点列表；若父节点不在 permitted 集合中，则视为根节点
+        Map<Integer, List<AppModule>> childrenMap = new HashMap<>();
+        for (AppModule m : permitted) {
+            Integer parentId = m.getParentId();
+            Integer key = (parentId == null || !permittedModuleIds.contains(parentId)) ? 0 : parentId;
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(m);
+        }
+        Comparator<AppModule> siblingOrder = (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<AppModule> siblings : childrenMap.values()) {
+            siblings.sort(siblingOrder);
+        }
+        List<AppModule> roots = childrenMap.getOrDefault(0, Collections.emptyList());
+        List<UserPermissionModuleVo> tree = new ArrayList<>();
+        for (AppModule root : roots) {
+            tree.add(buildUserPermissionModuleNode(root, childrenMap));
+        }
+        return tree;
+    }
+
+    private UserPermissionModuleVo buildUserPermissionModuleNode(AppModule node,
+            Map<Integer, List<AppModule>> childrenMap) {
+        UserPermissionModuleVo vo = new UserPermissionModuleVo();
+        BeanUtils.copyProperties(node, vo);
+        List<AppModule> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (AppModule child : children) {
+                vo.getChildren().add(buildUserPermissionModuleNode(child, childrenMap));
+            }
+        }
+        return vo;
+    }
+
+    private Comparator<UserPermissionAppVo> userPermissionAppOrder() {
+        return (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId() == null ? 0 : a.getId(), b.getId() == null ? 0 : b.getId());
+        };
+    }
+
+    private Map<Integer, SysGroup> buildAllGroupMap() {
+        Map<Integer, SysGroup> map = new HashMap<>();
+        for (SysGroup g : sysGroupRepository.findAll()) {
+            map.put(g.getId(), g);
+        }
+        return map;
+    }
+
+    private String buildGroupPath(Integer groupId, Map<Integer, SysGroup> allGroupMap) {
+        if (groupId == null) {
+            return "";
+        }
+        List<String> names = new ArrayList<>();
+        Set<Integer> visited = new HashSet<>();
+        Integer cursor = groupId;
+        while (cursor != null && cursor != ROOT_PARENT_ID && visited.add(cursor)) {
+            SysGroup g = allGroupMap.get(cursor);
+            if (g == null) {
+                break;
+            }
+            names.add(g.getName() == null ? "" : g.getName());
+            cursor = g.getParentId();
+        }
+        Collections.reverse(names);
+        return names.isEmpty() ? "" : "/" + String.join("/", names);
+    }
+
+    private Specification<SysUser> buildUserSearchSpec(String keyword) {
+        return (root, cbQuery, cb) -> {
+            List<Predicate> predicates = new ArrayList<>();
+            String like = "%" + keyword + "%";
+            predicates.add(cb.like(root.get("account"), like));
+            predicates.add(cb.like(root.get("realName"), like));
+            predicates.add(cb.like(root.get("idcard"), like));
+            try {
+                predicates.add(cb.equal(root.get("phone"), keyword));
+            } catch (Exception ignored) {
+                // phone 字段可能不存在或类型不匹配时忽略精确匹配
+            }
+            return cb.or(predicates.toArray(new Predicate[0]));
+        };
+    }
+
+    // ===================== 权限判定 =====================
+
+    @Override
+    public boolean hasModulePermission(Integer userId, Integer moduleId) {
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        Objects.requireNonNull(moduleId, "模块ID不能为空");
+        // 超级管理员（UserTypeEnum.SUPER_ADMIN / 基石账号）：直接赋予全部模块权限，
+        // 不做任何组/角色/继承判定——避免「超管不归属任何组 → userRels 为空 → 直接返回 false（即无任何权限）」的 bug。
+        SysUser user = sysUserRepository.findById(userId).orElse(null);
+        if (user != null && isSuperAdmin(user.getType(), userId)) {
+            return true;
+        }
+        AppModule module = appModuleRepository.findById(moduleId).orElse(null);
+        if (module == null) {
+            return false;
+        }
+        Integer appId = module.getAppId();
+        // AI-FIX(角色授权): 用户经「启用」角色获得该模块授权即通过，不要求组开通模块所属应用；禁用角色已在收集时过滤
+        if (collectEnabledRoleModuleIds(userId).contains(moduleId)) {
+            return true;
+        }
+        // 1. 用户所属的全部组
+        List<SysUserGroupRel> userRels = sysUserGroupRelRepository.findByUserId(userId);
+        if (userRels.isEmpty()) {
+            return false;
+        }
+        // 2. 全部组载入内存（树深度有限），供祖先链回溯
+        Map<Integer, SysGroup> allGroupMap = new HashMap<>();
+        for (SysGroup g : sysGroupRepository.findAll()) {
+            allGroupMap.put(g.getId(), g);
+        }
+        // 3. 前置校验：所属组必须已开通模块所属应用（最终权限 = 就近来源模块权限 ∩ 已开通应用）；
+        // 通过校验的组构建祖先链（含自身），并收集祖先链并集用于一次批量 IN 查询
+        Map<Integer, List<Integer>> chainMap = new HashMap<>();
+        Set<Integer> allChainIds = new LinkedHashSet<>();
+        Set<Integer> selfGroupIds = new LinkedHashSet<>();
+        for (SysUserGroupRel rel : userRels) {
+            Integer groupId = rel.getGroupId();
+            if (groupId == null || chainMap.containsKey(groupId)) {
+                continue;
+            }
+            if (!sysGroupAppRelRepository.existsByGroupIdAndAppId(groupId, appId)) {
+                continue;
+            }
+            selfGroupIds.add(groupId);
+            List<Integer> chain = ancestorChain(groupId, allGroupMap);
+            chainMap.put(groupId, chain);
+            allChainIds.addAll(chain);
+        }
+        if (chainMap.isEmpty()) {
+            return false;
+        }
+        // 4. 一次批量查询「该应用下所有模块」在全部祖先链节点上的权限记录
+        // （要判定就近来源，需要知道链上哪些组对该应用有显式配置，不能只看单模块）
+        List<AppModule> appModules = appModuleRepository.findByAppIdIn(Collections.singletonList(appId));
+        Set<Integer> appModuleIds = new LinkedHashSet<>();
+        for (AppModule m : appModules) {
+            appModuleIds.add(m.getId());
+        }
+        Map<Integer, Map<Integer, SysGroupModulePerm>> modulePermMap = new HashMap<>();
+        Map<Integer, Set<Integer>> groupConfiguredApps = new HashMap<>();
+        if (!appModuleIds.isEmpty() && !allChainIds.isEmpty()) {
+            List<SysGroupModulePerm> perms = sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                    new ArrayList<>(appModuleIds), new ArrayList<>(allChainIds));
+            for (SysGroupModulePerm perm : perms) {
+                if (perm.getModuleId() == null || perm.getGroupId() == null) {
+                    continue;
+                }
+                modulePermMap.computeIfAbsent(perm.getModuleId(), k -> new HashMap<>())
+                        .put(perm.getGroupId(), perm);
+                groupConfiguredApps.computeIfAbsent(perm.getGroupId(), k -> new HashSet<>()).add(appId);
+            }
+        }
+        // 5. 就近原则判定：对每个归属组，取离它最近的、对该应用有显式配置的组为唯一权限来源；
+        // 该来源组对目标模块有记录即通过（多个归属组取并集）。
+        for (Integer selfGroupId : selfGroupIds) {
+            List<Integer> chain = chainMap.get(selfGroupId);
+            Integer authority = findNearestAuthorityGroup(selfGroupId, chain, appId, groupConfiguredApps, allGroupMap);
+            if (authority == null) {
+                continue;
+            }
+            Map<Integer, SysGroupModulePerm> pm = modulePermMap.get(moduleId);
+            if (isPermEffectiveForSelf(authority, selfGroupId, pm)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // ===================== 私有工具 =====================
+
+    /**
+     * 构建组的祖先链（从自身到根节点，含自身），沿 parentId 向上回溯。<br>
+     * 带 visited 防环保护，脏数据成环时中断回溯。<br>
+     */
+    private List<Integer> ancestorChain(Integer groupId, Map<Integer, SysGroup> allGroupMap) {
+        List<Integer> chain = new ArrayList<>();
+        Set<Integer> visited = new HashSet<>();
+        Integer cursor = groupId;
+        while (cursor != null && cursor != ROOT_PARENT_ID && visited.add(cursor)) {
+            SysGroup g = allGroupMap.get(cursor);
+            if (g == null) {
+                break;
+            }
+            chain.add(cursor);
+            cursor = g.getParentId();
+        }
+        return chain;
+    }
+
+    /**
+     * 组装单个应用下的模块权限树（沿用 AppModuleService 的组装方式：childrenMap + sortNo 排序）。<br>
+     */
+    private List<GroupAuthzModuleVo> buildModuleTree(List<AppModule> modules,
+            Map<Integer, SysGroupModulePerm> permMap) {
+        // parentId -> 子节点列表（null 视为 0）
+        Map<Integer, List<AppModule>> childrenMap = new HashMap<>();
+        for (AppModule m : modules) {
+            Integer key = (m.getParentId() == null) ? 0 : m.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(m);
+        }
+        // 每个兄弟组按 sortNo(空视为999) 升序，再按 id 升序
+        Comparator<AppModule> siblingOrder = (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<AppModule> siblings : childrenMap.values()) {
+            siblings.sort(siblingOrder);
+        }
+        List<AppModule> roots = childrenMap.getOrDefault(0, Collections.emptyList());
+        List<GroupAuthzModuleVo> tree = new ArrayList<>();
+        for (AppModule root : roots) {
+            tree.add(buildModuleNode(root, childrenMap, permMap));
+        }
+        return tree;
+    }
+
+    /**
+     * 递归组装模块节点，并按权限记录回显 checked / inheritFlag。<br>
+     */
+    private GroupAuthzModuleVo buildModuleNode(AppModule node,
+            Map<Integer, List<AppModule>> childrenMap,
+            Map<Integer, SysGroupModulePerm> permMap) {
+        GroupAuthzModuleVo vo = new GroupAuthzModuleVo();
+        BeanUtils.copyProperties(node, vo);
+        SysGroupModulePerm perm = permMap.get(node.getId());
+        if (perm != null) {
+            vo.setChecked(Boolean.TRUE);
+            vo.setInheritFlag(Boolean.TRUE.equals(perm.getInheritFlag()));
+        }
+        List<AppModule> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (AppModule child : children) {
+                vo.getChildren().add(buildModuleNode(child, childrenMap, permMap));
+            }
+        }
+        return vo;
+    }
+
+    /** 应用排序：sortNo 升序（空视为999），再按 id 升序（与应用列表展示一致）。 */
+    private Comparator<ApplicationInfo> appOrder() {
+        return (a, b) -> {
+            int sa = a.getSortNo() == null ? 999 : a.getSortNo();
+            int sb = b.getSortNo() == null ? 999 : b.getSortNo();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+    }
+
+    /**
+     * 收集用户经「启用状态」业务角色获得授权的模块ID集合（角色授权并集的角色侧输入）。<br>
+     * 禁用角色（disabled=true）不参与权限计算；用户无绑定或角色全被禁用时返回空集合。<br>
+     */
+    private Set<Integer> collectEnabledRoleModuleIds(Integer userId) {
+        List<SysUserAppRoleRel> rels = sysUserAppRoleRelRepository.findByUserId(userId);
+        if (rels.isEmpty()) {
+            return Collections.emptySet();
+        }
+        Set<Integer> roleIds = new LinkedHashSet<>();
+        for (SysUserAppRoleRel rel : rels) {
+            if (rel.getRoleId() != null) {
+                roleIds.add(rel.getRoleId());
+            }
+        }
+        // 仅保留启用角色
+        List<Integer> enabledRoleIds = new ArrayList<>();
+        for (SysAppRole role : sysAppRoleRepository.findAllById(roleIds)) {
+            if (!Boolean.TRUE.equals(role.getDisabled())) {
+                enabledRoleIds.add(role.getId());
+            }
+        }
+        if (enabledRoleIds.isEmpty()) {
+            return Collections.emptySet();
+        }
+        Set<Integer> moduleIds = new LinkedHashSet<>();
+        for (SysAppRoleModuleRel rel : sysAppRoleModuleRelRepository.findByRoleIdIn(enabledRoleIds)) {
+            if (rel.getModuleId() != null) {
+                moduleIds.add(rel.getModuleId());
+            }
+        }
+        return moduleIds;
+    }
+
+    @Override
+    public List<Integer> findUserAuthorizedAppIds(Integer userId) {
+        Objects.requireNonNull(userId, "用户ID不能为空");
+        SysUser user = sysUserRepository.findById(userId).orElse(null);
+        if (user == null) {
+            throw new DException("用户不存在");
+        }
+        // 超级管理员：全部应用
+        if (isSuperAdmin(user.getType(), userId)) {
+            List<Integer> allIds = new ArrayList<>();
+            for (ApplicationInfo app : applicationInfoRepository.findAll()) {
+                allIds.add(app.getId());
+            }
+            return allIds;
+        }
+        Set<Integer> appIds = new LinkedHashSet<>();
+        // 1. 组开通应用（用户所属组沿祖先链的开通池并集）
+        List<SysUserGroupRel> userRels = sysUserGroupRelRepository.findByUserId(userId);
+        for (SysUserGroupRel rel : userRels) {
+            if (rel.getGroupId() == null) {
+                continue;
+            }
+            appIds.addAll(collectAppIdsForAuthzScope(rel.getGroupId()));
+        }
+        // 2. 启用角色模块所属应用（角色授权不要求组先开通应用）
+        Set<Integer> roleModuleIds = collectEnabledRoleModuleIds(userId);
+        if (!roleModuleIds.isEmpty()) {
+            for (AppModule m : appModuleRepository.findAllById(roleModuleIds)) {
+                if (m.getAppId() != null) {
+                    appIds.add(m.getAppId());
+                }
+            }
+        }
+        return new ArrayList<>(appIds);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/IdentityService.java b/src/main/java/com/yunhai/userbase/service/impl/IdentityService.java
new file mode 100644
index 0000000..16992b1
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/IdentityService.java
@@ -0,0 +1,146 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.entity.SysUserCurrentRole;
+import com.yunhai.userbase.entity.SysUserRoleRel;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.userbase.enums.StatusEnum;
+import com.yunhai.userbase.enums.SysRoleEnum;
+import com.yunhai.userbase.model.identity.IdentityCurrentVo;
+import com.yunhai.userbase.model.identity.IdentityOptionVo;
+import com.yunhai.userbase.model.identity.IdentitySwitchRequest;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserCurrentRoleRepository;
+import com.yunhai.userbase.repository.SysUserRoleRelRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * 用户身份服务：管理「平台身份角色 × 学校」维度的当前激活状态与可选清单。<br><br>
+ * 身份 = (userId, roleId, schoolId) 三元组，权威源为 {@code sys_user_role_rel}；<br>
+ * 当前激活状态存 {@code sys_user_current_role}（1:1，每用户一条）。<br>
+ * 本服务不处理业务权限角色（sys_app_role），那套与学校维度无关。
+ *
+ * @author chenx
+ * @date 2026/8/18
+ */
+@Service
+public class IdentityService {
+
+    @Autowired
+    private SysUserRoleRelRepository sysUserRoleRelRepository;
+    @Autowired
+    private SysUserCurrentRoleRepository sysUserCurrentRoleRepository;
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+
+    /**
+     * 用户全部可选身份（正常态），用于「切换身份」页渲染。
+     */
+    public List<IdentityOptionVo> listAvailable(Integer userId) {
+        List<SysUserRoleRel> rels = sysUserRoleRelRepository
+                .findByUserIdAndStatus(userId, StatusEnum.NORMAL);
+        List<IdentityOptionVo> result = new ArrayList<>(rels.size());
+        for (SysUserRoleRel rel : rels) {
+            IdentityOptionVo vo = new IdentityOptionVo();
+            vo.setRoleId(rel.getRoleId());
+            vo.setRoleName(roleName(rel.getRoleId()));
+            vo.setSchoolId(rel.getSchoolId());
+            vo.setSchoolName(schoolName(rel.getSchoolId()));
+            vo.setIsMain(rel.getIsMain() != null && rel.getIsMain() == 1);
+            result.add(vo);
+        }
+        return result;
+    }
+
+    /**
+     * 当前激活身份：优先读 sys_user_current_role；无切换记录时兜底主身份（isMain=1）。
+     */
+    public IdentityCurrentVo getCurrent(Integer userId) {
+        Optional<SysUserCurrentRole> currentOpt = sysUserCurrentRoleRepository.findByUserId(userId);
+        IdentityCurrentVo vo = new IdentityCurrentVo();
+        if (currentOpt.isPresent()) {
+            SysUserCurrentRole current = currentOpt.get();
+            vo.setRoleId(current.getRoleId());
+            vo.setRoleName(roleName(current.getRoleId()));
+            vo.setSchoolId(current.getSchoolId());
+            vo.setSchoolName(current.getSchoolName());
+            vo.setFallback(false);
+            return vo;
+        }
+        // 兜底：主身份整条记录（isMain=1）
+        SysUserRoleRel mainRel = sysUserRoleRelRepository.findByUserIdAndIsMain(userId, 1).orElse(null);
+        if (mainRel != null) {
+            vo.setRoleId(mainRel.getRoleId());
+            vo.setRoleName(roleName(mainRel.getRoleId()));
+            vo.setSchoolId(mainRel.getSchoolId());
+            vo.setSchoolName(schoolName(mainRel.getSchoolId()));
+            vo.setFallback(true);
+            return vo;
+        }
+        // 连主身份都没有（测试期初数据尚未建立）：返回空对象，前端引导创建身份
+        vo.setFallback(true);
+        return vo;
+    }
+
+    /**
+     * 切换身份：校验 (userId, roleId, schoolId) 在 sys_user_role_rel 正常态中存在，
+     * 再 UPSERT sys_user_current_role（按 userId 唯一）。
+     */
+    public IdentityCurrentVo switchIdentity(Integer userId, IdentitySwitchRequest request) {
+        Integer roleId = request.getRoleId();
+        Integer schoolId = request.getSchoolId();
+        // 校验目标身份确属该用户且正常态，防越权切换
+        SysUserRoleRel rel = sysUserRoleRelRepository
+                .findByUserIdAndSchoolIdAndStatus(userId, schoolId, StatusEnum.NORMAL)
+                .stream()
+                .filter(r -> Objects.equals(r.getRoleId(), roleId))
+                .findFirst()
+                .orElse(null);
+        if (rel == null) {
+            throw new DException("目标身份不存在或非正常态，无法切换");
+        }
+
+        SysUserCurrentRole current = sysUserCurrentRoleRepository.findByUserId(userId).orElse(null);
+        if (current == null) {
+            current = new SysUserCurrentRole();
+            current.setUserId(userId);
+        }
+        current.setRoleId(roleId);
+        current.setSchoolId(schoolId);
+        current.setSchoolName(schoolName(schoolId));
+        current.setSwitchTime(LocalDateTime.now());
+        sysUserCurrentRoleRepository.save(current);
+
+        IdentityCurrentVo vo = new IdentityCurrentVo();
+        vo.setRoleId(roleId);
+        vo.setRoleName(roleName(roleId));
+        vo.setSchoolId(schoolId);
+        vo.setSchoolName(current.getSchoolName());
+        vo.setFallback(false);
+        return vo;
+    }
+
+    private String roleName(Integer roleId) {
+        if (roleId == null) {
+            return null;
+        }
+        SysRoleEnum e = IEnum.getByKey(SysRoleEnum.class, roleId);
+        return e != null ? e.getValue() : null;
+    }
+
+    private String schoolName(Integer schoolId) {
+        if (schoolId == null || schoolId <= 0) {
+            return null;
+        }
+        SysGroup g = sysGroupRepository.findById(schoolId).orElse(null);
+        return g != null ? g.getName() : null;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/SignKeyCacheService.java b/src/main/java/com/yunhai/userbase/service/impl/SignKeyCacheService.java
new file mode 100644
index 0000000..3463459
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/SignKeyCacheService.java
@@ -0,0 +1,275 @@
+package com.yunhai.userbase.service.impl;
+
+import com.alibaba.fastjson.JSON;
+import com.yunhai.userbase.config.UserBaseAppSecretProvider;
+import com.yunhai.userbase.config.UserBaseLocalAppIdentityProvider;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.event.ApplicationInfoCacheChangedEvent;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 应用签名密钥的 Redis 桥接服务。<br>
+ * <br>
+ * 职责：把 {@code application_info} 表的 appKey/appSecret 同步到 Redis，供各业务服务的
+ * common-sign-starter（SignKeyResolver）读取做验签——业务服务无需直连 UserBase 数据库。<br>
+ * <br>
+ * 约定（读侧 starter 必须严格一致）：<br>
+ * 1) key 前缀 {@code sign:app:}，后接 appKey，例 {@code sign:app:100616}；<br>
+ * 2) value 为 fastjson 序列化的 JSON
+ * 字符串：{@code {"appKey":"100616","secret":"...","enabled":true}}；<br>
+ * 3) 不设过期时间，依赖 Redis 持久化（AOF/RDB）保证重启不丢；删除应用时直接删 key（等价于禁用）。<br>
+ * <br>
+ * <b>变更同步说明（IDEA 灰色=正常）：</b>本类的 {@code onCacheChanged(...)} 由 Spring 容器在运行时通过
+ * 反射注册为事务监听器（{@code @TransactionalEventListener}），不会在 IDE 的静态调用链中直接显示
+ * 引用，属正常现象。真实触发点在
+ * {@link com.yunhai.userbase.service.impl.ApplicationInfoService}
+ * 的增/改/删/重置密钥、以及
+ * 通用 save/deleteById 方法末尾，统一发布 {@link ApplicationInfoCacheChangedEvent}。
+ */
+@Service
+public class SignKeyCacheService implements ApplicationRunner, ApplicationContextAware {
+
+    private static final Logger log = LoggerFactory.getLogger(SignKeyCacheService.class);
+
+    /** Redis key 前缀；读侧 SignKeyResolver 必须保持一致：sign:app:{appKey} */
+    public static final String KEY_PREFIX = "sign:app:";
+
+    /** UserBase 本身作为调用方（出站签名）时固定使用的基石应用 appKey，对应 100000 这条初始化记录 */
+    public static final String USER_BASE_APP_KEY = "100000";
+
+    @Autowired
+    private StringRedisTemplate stringRedisTemplate;
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+
+    private ApplicationContext applicationContext;
+
+    /**
+     * 事务提交后的安全订阅：只有 ApplicationInfoService 对应事务真正 commit 后，
+     * 才会去写共享 Redis / 清本地缓存，避免事务回滚导致的 DB-Redis 数据不一致。
+     */
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    public void onCacheChanged(ApplicationInfoCacheChangedEvent event) {
+        if (event.getType() == ApplicationInfoCacheChangedEvent.Type.DELETE) {
+            removeOne(event.getAppKey());
+            return;
+        }
+        if (event.getUpsertEntity() != null) {
+            syncOne(event.getUpsertEntity());
+        }
+    }
+
+    /**
+     * 同步单条应用到 Redis（新增 / 编辑 / 重置密钥时调用）。
+     * <p>
+     * 同步前主动失效本机的本地缓存，保证密钥变更后本机入站验签 / 出站签名 0 窗口生效。
+     */
+    public void syncOne(ApplicationInfo info) {
+        if (info == null || info.getAppKey() == null || info.getAppSecret() == null) {
+            return;
+        }
+        String key = KEY_PREFIX + info.getAppKey();
+        SignAppKeyPayload payload = new SignAppKeyPayload(
+                String.valueOf(info.getAppKey()), info.getAppSecret(), true);
+        stringRedisTemplate.opsForValue().set(key, JSON.toJSONString(payload));
+        invalidateLocal(info.getAppKey());
+    }
+
+    /**
+     * 从 Redis 移除某应用的密钥（删除应用时调用，等价于禁用该应用签名）。
+     * 删除前同步失效本机本地缓存。
+     */
+    public void removeOne(Integer appKey) {
+        if (appKey == null) {
+            return;
+        }
+        stringRedisTemplate.delete(KEY_PREFIX + appKey);
+        invalidateLocal(appKey);
+        log.info("[SignKeyCache] remove appKey={} from redis", appKey);
+    }
+
+    /**
+     * 全量刷新：把数据库全部应用重新写入 Redis，并清理库中已不存在的残留 key。<br>
+     * 用于 Redis 数据丢失 / 不一致后的手动恢复，以及首次部署预热 + 每日定时对账。
+     *
+     * @return 实际写入的密钥条数
+     */
+    public int refreshAll() {
+        List<ApplicationInfo> all = applicationInfoRepository.findAll();
+        Set<String> dbKeys = new HashSet<>();
+        for (ApplicationInfo info : all) {
+            if (info.getAppKey() == null || info.getAppSecret() == null) {
+                continue;
+            }
+            syncOne(info);
+            dbKeys.add(KEY_PREFIX + info.getAppKey());
+        }
+        // 清理残留：DB 已删除但 Redis 仍存在的 key（防止被删应用仍可验签）
+        Set<String> redisKeys = stringRedisTemplate.keys(KEY_PREFIX + "*");
+        if (redisKeys != null) {
+            for (String k : redisKeys) {
+                if (!dbKeys.contains(k)) {
+                    stringRedisTemplate.delete(k);
+                    log.info("[SignKeyCache] prune stale key={}", k);
+                }
+            }
+        }
+        // 全量刷新后清空本地缓存，保证之前残留的任何旧密钥在下一次 getSecret 时重新查 DB 获取新值
+        invalidateAllLocal();
+        log.info("[SignKeyCache] refreshAll done, synced={}", dbKeys.size());
+        return dbKeys.size();
+    }
+
+    /**
+     * 3A 方案兜底：<b>每日对账定时任务已迁移到
+     * {@link com.yunhai.userbase.task.SignKeyCacheDailyTask#syncAll()}。</b>
+     * 保持 Service 层单纯（CRUD 同步 + 启动预热），定时任务统一放在 task 包，便于运维集中查看。
+     * 
+     * @deprecated 请使用 task 包下的 SignKeyCacheDailyTask.syncAll() 每日对账。
+     *             本方法保留仅为兼容手动调用场景。
+     */
+    @Deprecated
+    public void scheduledRefreshAll() {
+        try {
+            int n = refreshAll();
+            log.info("[SignKeyCache] scheduled daily refreshAll done, synced={}", n);
+        } catch (Exception e) {
+            log.warn("[SignKeyCache] scheduled daily refreshAll failed: {}", e.getMessage());
+        }
+    }
+
+    /**
+     * 启动预热：应用启动后尽力把密钥同步到 Redis。
+     * Redis 不可用时仅告警，不影响应用启动（此时验签依赖后续手动刷新或 Redis 恢复）。
+     */
+    @Override
+    public void run(ApplicationArguments args) {
+        try {
+            int n = refreshAll();
+            log.info("[SignKeyCache] startup warm-up synced={}", n);
+        } catch (Exception e) {
+            log.warn("[SignKeyCache] startup warm-up failed (redis may be unavailable): {}", e.getMessage());
+        }
+    }
+
+    /**
+     * 失效本机本地缓存：变更某应用密钥/删除该应用时，
+     * 同时失效 AppSecretProvider（入站验签读的缓存）和若其为基石应用则失效出站签名缓存。
+     */
+    public void invalidateLocal(Integer appKey) {
+        if (appKey == null) {
+            return;
+        }
+        try {
+            Map<String, UserBaseAppSecretProvider> providers = applicationContext
+                    .getBeansOfType(UserBaseAppSecretProvider.class);
+            if (providers != null && !providers.isEmpty()) {
+                for (UserBaseAppSecretProvider p : providers.values()) {
+                    p.invalidate(String.valueOf(appKey));
+                }
+            }
+        } catch (Exception ignored) {
+        }
+        if (USER_BASE_APP_KEY.equals(String.valueOf(appKey))) {
+            try {
+                Map<String, UserBaseLocalAppIdentityProvider> locals = applicationContext
+                        .getBeansOfType(UserBaseLocalAppIdentityProvider.class);
+                if (locals != null && !locals.isEmpty()) {
+                    for (UserBaseLocalAppIdentityProvider p : locals.values()) {
+                        p.invalidate();
+                    }
+                }
+            } catch (Exception ignored) {
+            }
+        }
+    }
+
+    /** 全量对账/预热时，直接清空本机的所有密钥缓存，避免残留。 */
+    public void invalidateAllLocal() {
+        try {
+            Map<String, UserBaseAppSecretProvider> providers = applicationContext
+                    .getBeansOfType(UserBaseAppSecretProvider.class);
+            if (providers != null && !providers.isEmpty()) {
+                for (UserBaseAppSecretProvider p : providers.values()) {
+                    p.invalidateAll();
+                }
+            }
+        } catch (Exception ignored) {
+        }
+        try {
+            Map<String, UserBaseLocalAppIdentityProvider> locals = applicationContext
+                    .getBeansOfType(UserBaseLocalAppIdentityProvider.class);
+            if (locals != null && !locals.isEmpty()) {
+                for (UserBaseLocalAppIdentityProvider p : locals.values()) {
+                    p.invalidate();
+                }
+            }
+        } catch (Exception ignored) {
+        }
+    }
+
+    @Override
+    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
+        this.applicationContext = applicationContext;
+    }
+
+    /**
+     * Redis value 的 JSON 载体。字段名即契约，读侧 starter 的解析类需一一对应。
+     */
+    public static class SignAppKeyPayload {
+        private String appKey;
+        private String secret;
+        private boolean enabled;
+
+        public SignAppKeyPayload() {
+        }
+
+        public SignAppKeyPayload(String appKey, String secret, boolean enabled) {
+            this.appKey = appKey;
+            this.secret = secret;
+            this.enabled = enabled;
+        }
+
+        public String getAppKey() {
+            return appKey;
+        }
+
+        public void setAppKey(String appKey) {
+            this.appKey = appKey;
+        }
+
+        public String getSecret() {
+            return secret;
+        }
+
+        public void setSecret(String secret) {
+            this.secret = secret;
+        }
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/SysGroupService.java b/src/main/java/com/yunhai/userbase/service/impl/SysGroupService.java
new file mode 100644
index 0000000..8eb0b5e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/SysGroupService.java
@@ -0,0 +1,784 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.model.BoaGroup;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.userbase.event.DataSyncEvent;
+import com.yunhai.userbase.common.context.CallerAppContext;
+import com.yunhai.userbase.model.push.PushInterfaceType;
+import org.springframework.context.ApplicationEventPublisher;
+import com.yunhai.userbase.model.sysgroup.SysGroupBatchRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupMoveRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupQuery;
+import com.yunhai.userbase.model.sysgroup.SysGroupRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupSortRequest;
+import com.yunhai.userbase.model.sysgroup.SysGroupVo;
+import com.yunhai.userbase.repository.SysGroupAppRelRepository;
+import com.yunhai.userbase.repository.SysGroupModulePermRepository;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.service.ISysGroupService;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import javax.transaction.Transactional;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:00
+ * @description 系统组服务实现：组织架构树（仅 parentId 逻辑外键，不使用 path；后续可用 MySQL8 WITH 优化递归查询）。<br>
+ */
+@Service
+public class SysGroupService implements ISysGroupService {
+
+    /** 虚拟父节点：根节点(教育云中心)的 parentId，表示「无上级」。 */
+    private static final int ROOT_PARENT_ID = 0;
+
+    /** 开放接口/oapi 写操作无登录态时使用的审计人哨兵值（非真实用户ID），用于兜底 create_user/update_user 的 NOT NULL 约束。 */
+    private static final int SYSTEM_USER_ID = 0;
+
+    /**
+     * 层级类型约束：父类型 -> 允许直接创建的子类型集合。
+     * key 为 {@code null} 表示「根节点(教育云中心)」。
+     * 集合为空 = 该类型禁止创建任何子组（班级组叶子节点、学段组占位等由空集自然拒绝）。
+     * <p>规则来源：用户中心组层级约束（根-区域-学段-学校-教师|学生-年级-班级）。</p>
+     */
+    private static final Map<GroupTypeEnum, Set<GroupTypeEnum>> ALLOWED_CHILDREN = new HashMap<>();
+    static {
+        ALLOWED_CHILDREN.put(null, EnumSet.of(
+                GroupTypeEnum.SCHOOL_GROUP, GroupTypeEnum.NORMAL_GROUP, GroupTypeEnum.AREA_GROUP));
+        // 区域组：只能挂在根节点下（由根节点的白名单约束），其下可挂 学段组/学校组/普通组
+        ALLOWED_CHILDREN.put(GroupTypeEnum.AREA_GROUP, EnumSet.of(
+                GroupTypeEnum.STAGE_GROUP, GroupTypeEnum.SCHOOL_GROUP, GroupTypeEnum.NORMAL_GROUP));
+        // 学段组（高中/初中/小学）：学校组的上级，可含 学校组/年级组
+        ALLOWED_CHILDREN.put(GroupTypeEnum.STAGE_GROUP, EnumSet.of(
+                GroupTypeEnum.SCHOOL_GROUP, GroupTypeEnum.GRADE_GROUP));
+        // 学校组：可含 教师组/学生组/普通组
+        ALLOWED_CHILDREN.put(GroupTypeEnum.SCHOOL_GROUP, EnumSet.of(
+                GroupTypeEnum.TEACHER_GROUP, GroupTypeEnum.STUDENT_GROUP, GroupTypeEnum.NORMAL_GROUP));
+        // 教师组：维持原规范，仅含 普通组
+        ALLOWED_CHILDREN.put(GroupTypeEnum.TEACHER_GROUP, EnumSet.of(GroupTypeEnum.NORMAL_GROUP));
+        // 学生组：可含 年级组/学段组/普通组（学段组既可在区域组下、也可在学生组下）
+        ALLOWED_CHILDREN.put(GroupTypeEnum.STUDENT_GROUP, EnumSet.of(
+                GroupTypeEnum.GRADE_GROUP, GroupTypeEnum.STAGE_GROUP, GroupTypeEnum.NORMAL_GROUP));
+        // 年级组：可含 班级组/普通组
+        ALLOWED_CHILDREN.put(GroupTypeEnum.GRADE_GROUP, EnumSet.of(
+                GroupTypeEnum.CLASS_GROUP, GroupTypeEnum.NORMAL_GROUP));
+        // 班级组：叶子节点，禁止创建任何子组（⛔ 强约束，空集自然拒绝）
+        ALLOWED_CHILDREN.put(GroupTypeEnum.CLASS_GROUP, EnumSet.noneOf(GroupTypeEnum.class));
+        // 普通组：可含 学校组/教师组/学段组/普通组（年级组/班级组/学生组 受限，区域组受「只能挂根」硬约束排除）
+        ALLOWED_CHILDREN.put(GroupTypeEnum.NORMAL_GROUP, EnumSet.of(
+                GroupTypeEnum.SCHOOL_GROUP, GroupTypeEnum.TEACHER_GROUP,
+                GroupTypeEnum.STAGE_GROUP, GroupTypeEnum.NORMAL_GROUP));
+    }
+
+    /** 层级类型约束校验：parentType 为 null 表示根节点；非法组合抛 {@link DException}。 */
+    private void validateParentChild(GroupTypeEnum parentType, GroupTypeEnum childType) {
+        Set<GroupTypeEnum> allowed = ALLOWED_CHILDREN.get(parentType);
+        if (allowed == null) {
+            allowed = Collections.emptySet();
+        }
+        if (allowed.contains(childType)) {
+            return;
+        }
+        String parentName = (parentType == null) ? "根节点" : parentType.getValue();
+        if (childType == GroupTypeEnum.CLASS_GROUP) {
+            throw new DException(parentName + "下不允许创建班级组（班级组为叶子节点，禁止创建子组）");
+        }
+        if (childType == GroupTypeEnum.AREA_GROUP) {
+            throw new DException("区域组只能建立在根节点下");
+        }
+        throw new DException(parentName + "下不允许创建" + childType.getValue());
+    }
+
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+
+    @Autowired
+    private SysGroupAppRelRepository sysGroupAppRelRepository;
+
+    @Autowired
+    private SysGroupModulePermRepository sysGroupModulePermRepository;
+
+    @Autowired
+    private ApplicationEventPublisher eventPublisher;
+
+    // ===================== 基础增删改（含根节点保护） =====================
+
+    @Override
+    @Transactional
+    public BoaGroup add(SysGroupRequest request) {
+        Integer parentId = request.getParentId();
+        // parentId 为 null 或 0 表示「挂在根节点(教育云中心)下」；
+        // 新组必须挂到真实根节点的 id 之下，绝不能把 parentId 写成 0（否则会生成第二个伪根节点）。
+        GroupTypeEnum parentType = null; // null 表示根节点
+        int realPid;
+        if (parentId != null && parentId != ROOT_PARENT_ID) {
+            SysGroup parent = sysGroupRepository.findById(parentId)
+                    .orElseThrow(() -> new DException("父组不存在"));
+            parentType = parent.getType();
+            realPid = parentId;
+        } else {
+            // 解析唯一真实根节点，取其真实 id 作为挂载点
+            realPid = resolveRootGroup().getId();
+        }
+        GroupTypeEnum typeEnum = resolveType(request.getType());
+        // 层级类型约束：当前父组是否允许创建该子类型
+        validateParentChild(parentType, typeEnum);
+
+        SysGroup entity = new SysGroup();
+        entity.setName(request.getName());
+        entity.setParentId(realPid);
+        entity.setType(typeEnum);
+        entity.setSort(nextSort(realPid));
+        entity.setCreateUser(SYSTEM_USER_ID);
+        entity.setUpdateUser(SYSTEM_USER_ID);
+        SysGroup saved = sysGroupRepository.save(entity);
+        publishGroupEvent(PushInterfaceType.ADD_GROUP, saved.getId());
+        return convertToBoaGroup(saved);
+    }
+
+    @Override
+    @Transactional
+    public BoaGroup edit(Integer id, SysGroupRequest request) {
+        SysGroup entity = sysGroupRepository.findById(id)
+                .orElseThrow(() -> new DException("系统组不存在"));
+        // 根节点不可编辑
+        if (isRoot(entity)) {
+            throw new DException("根节点不可编辑");
+        }
+        entity.setName(request.getName());
+        if (request.getType() != null) {
+            GroupTypeEnum newType = resolveType(request.getType());
+            if (!Objects.equals(newType, entity.getType())) {
+                // 1) 新类型须被当前父允许（根节点 parentId=0，parentType 视为 null）
+                GroupTypeEnum parentType = null;
+                if (entity.getParentId() != null && entity.getParentId() != ROOT_PARENT_ID) {
+                    SysGroup parent = sysGroupRepository.findById(entity.getParentId()).orElse(null);
+                    parentType = (parent != null) ? parent.getType() : null;
+                }
+                validateParentChild(parentType, newType);
+                // 2) 新类型的允许子类型须覆盖现有直接子类型，避免把「含子组的组」改成叶子/不兼容类型
+                Set<GroupTypeEnum> newAllowed = ALLOWED_CHILDREN.get(newType);
+                if (newAllowed == null) {
+                    newAllowed = Collections.emptySet();
+                }
+                List<SysGroup> children = sysGroupRepository.findByParentIdOrderBySortAsc(entity.getId());
+                for (SysGroup child : children) {
+                    GroupTypeEnum ct = child.getType();
+                    if (ct != null && !newAllowed.contains(ct)) {
+                        throw new DException("该组下已存在「" + ct.getValue() + "」，不可变更为「"
+                                + newType.getValue() + "」（" + newType.getValue() + "不允许包含" + ct.getValue() + "）");
+                    }
+                }
+            }
+            entity.setType(newType);
+        }
+        if (request.getSort() != null) {
+            entity.setSort(request.getSort());
+        }
+        // 注：移动请走 move 接口，edit 不改 parentId，避免与移动逻辑混淆
+        entity.setUpdateUser(SYSTEM_USER_ID);
+        sysGroupRepository.save(entity);
+        publishGroupEvent(PushInterfaceType.UPDATE_GROUP, id);
+        return convertToBoaGroup(entity);
+    }
+
+    @Override
+    @Transactional
+    public void delete(Integer id) {
+        deleteInternal(id);
+    }
+
+    @Override
+    @Transactional
+    public void delete(Integer id, Integer schoolId) {
+        // 开放接口边界：id 必须属于 schoolId 子树且不能等于 schoolId（禁止删学校根组/跨校删组）
+        assertWithinSchool(id, schoolId);
+        deleteInternal(id);
+    }
+
+    /**
+     * 公共学校锚点校验：schoolId 非空、存在、且必须为学校组(SCHOOL_GROUP)。<br>
+     * 供本服务 delete/move 及 {@code SysUserService} 等带 schoolId 边界的开放接口统一调用。
+     */
+    @Override
+    public void assertSchoolId(Integer schoolId) {
+        if (schoolId == null) {
+            throw new DException("学校ID不能为空");
+        }
+        SysGroup school = sysGroupRepository.findById(schoolId)
+                .orElseThrow(() -> new DException("学校分组不存在"));
+        if (school.getType() != GroupTypeEnum.SCHOOL_GROUP) {
+            throw new DException("学校ID必须为学校分组");
+        }
+    }
+
+    private void deleteInternal(Integer id) {
+        SysGroup entity = sysGroupRepository.findById(id)
+                .orElseThrow(() -> new DException("系统组不存在"));
+        // 根节点不可删除
+        if (isRoot(entity)) {
+            throw new DException("根节点不可删除");
+        }
+        if (sysGroupRepository.countByParentId(id) > 0) {
+            throw new DException("该组下存在子组，无法删除");
+        }
+        if (sysUserGroupRelRepository.countByGroupId(id) > 0) {
+            throw new DException("有用户，不能删除组");
+        }
+        // AI-FIX: 删除组时级联清理其应用开通记录与模块权限记录（逻辑外键无物理 FK，避免残留孤儿数据）
+        sysGroupAppRelRepository.deleteByGroupIdBulk(id);
+        sysGroupModulePermRepository.deleteByGroupIdBulk(id);
+        sysGroupRepository.deleteById(id);
+        publishGroupEvent(PushInterfaceType.DELETE_GROUP, id);
+    }
+
+    /**
+     * 学校边界校验：确保待删除的组属于指定学校范围，且不是学校根组本身。
+     *
+     * @param groupId  待删除组ID
+     * @param schoolId 学校组ID（限定范围）
+     */
+    private void assertWithinSchool(Integer groupId, Integer schoolId) {
+        // 公共锚点校验：schoolId 非空、存在、必须为学校组
+        assertSchoolId(schoolId);
+        if (groupId == null) {
+            throw new DException("组ID不能为空");
+        }
+        if (groupId.equals(schoolId)) {
+            throw new DException("禁止删除学校根组，请指定具体子组");
+        }
+        List<Integer> schoolScope = listSelfAndDescendantIds(schoolId);
+        if (!schoolScope.contains(groupId)) {
+            throw new DException("组不属于该学校范围，禁止跨校操作");
+        }
+    }
+
+    @Override
+    public List<SysGroupVo> list(SysGroupQuery query) {
+        List<SysGroup> list;
+        if (StringUtils.hasText(query.getName())) {
+            list = sysGroupRepository.findByNameContainingOrderBySortAsc(query.getName());
+        } else if (query.getParentId() != null) {
+            list = sysGroupRepository.findByParentIdOrderBySortAsc(query.getParentId());
+        } else {
+            list = sysGroupRepository.findAllByOrderBySortAsc();
+        }
+        return list.stream().map(this::convertToVo).collect(Collectors.toList());
+    }
+
+    // ===================== 组织架构树 =====================
+
+    @Override
+    public List<SysGroupVo> getTree() {
+        // 根节点由 SysGroupRootInitializer 在启动时幂等创建，此处直接读取组装
+        List<SysGroup> all = sysGroupRepository.findAll();
+        if (all.isEmpty()) {
+            return new ArrayList<>();
+        }
+        Map<Integer, List<SysGroup>> childrenMap = buildSortedChildrenMap(all);
+        // 从根（pid=0）开始组装树
+        List<SysGroup> roots = childrenMap.getOrDefault(ROOT_PARENT_ID, new ArrayList<>());
+        return roots.stream().map(r -> buildNode(r, childrenMap)).collect(Collectors.toList());
+    }
+
+    @Override
+    public List<SysGroupVo> getSchoolTree() {
+        List<SysGroup> all = sysGroupRepository.findAll();
+        if (all.isEmpty()) {
+            return new ArrayList<>();
+        }
+        Map<Integer, List<SysGroup>> childrenMap = buildSortedChildrenMap(all);
+        List<SysGroup> roots = childrenMap.getOrDefault(ROOT_PARENT_ID, new ArrayList<>());
+        List<SysGroupVo> result = new ArrayList<>();
+        for (SysGroup root : roots) {
+            SysGroupVo vo = buildSchoolNode(root, childrenMap);
+            if (vo == null) {
+                // 根节点始终保留（即使其下没有任何学校组），children 为空
+                vo = convertToVo(root);
+            }
+            result.add(vo);
+        }
+        return result;
+    }
+
+    /**
+     * 递归组装「学校组」剪枝节点。<br>
+     * 学校组：直接作为叶子返回（不再向下递归，其下所有组不显示）；<br>
+     * 非学校组：递归剪枝后仍有子节点才保留，否则返回 null（整枝剪掉）。<br>
+     */
+    private SysGroupVo buildSchoolNode(SysGroup node, Map<Integer, List<SysGroup>> childrenMap) {
+        if (node.getType() == GroupTypeEnum.SCHOOL_GROUP) {
+            return convertToVo(node);
+        }
+        List<SysGroup> children = childrenMap.get(node.getId());
+        if (children == null) {
+            return null;
+        }
+        SysGroupVo vo = convertToVo(node);
+        for (SysGroup child : children) {
+            SysGroupVo childVo = buildSchoolNode(child, childrenMap);
+            if (childVo != null) {
+                vo.getChildren().add(childVo);
+            }
+        }
+        return vo.getChildren().isEmpty() ? null : vo;
+    }
+
+    /**
+     * 构建 parentId -> 直接子节点列表 的映射（null 视为 0），同层级按 sort 升序、再按 id 升序。<br>
+     */
+    private Map<Integer, List<SysGroup>> buildSortedChildrenMap(List<SysGroup> all) {
+        Map<Integer, List<SysGroup>> childrenMap = new HashMap<>();
+        for (SysGroup g : all) {
+            Integer key = (g.getParentId() == null) ? ROOT_PARENT_ID : g.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(g);
+        }
+        Comparator<SysGroup> siblingOrder = (a, b) -> {
+            int sa = a.getSort() == null ? 999 : a.getSort();
+            int sb = b.getSort() == null ? 999 : b.getSort();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<SysGroup> siblings : childrenMap.values()) {
+            siblings.sort(siblingOrder);
+        }
+        return childrenMap;
+    }
+
+    private SysGroupVo buildNode(SysGroup node, Map<Integer, List<SysGroup>> childrenMap) {
+        SysGroupVo vo = convertToVo(node);
+        List<SysGroup> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (SysGroup child : children) {
+                vo.getChildren().add(buildNode(child, childrenMap));
+            }
+        }
+        return vo;
+    }
+
+    // ===================== 开放接口：组树（BoaGroup） =====================
+
+    /**
+     * 获取整个平台的组树：从根节点（pid=0）开始，children 递归嵌套全部后代。<br>
+     * 根节点唯一，取最小 id 作为树入口。表为空或无根时返回 null。
+     */
+    @Override
+    public BoaGroup getGroups() {
+        List<SysGroup> all = sysGroupRepository.findAll();
+        if (all.isEmpty()) {
+            return null;
+        }
+        Map<Integer, List<SysGroup>> childrenMap = buildSortedChildrenMap(all);
+        List<SysGroup> roots = childrenMap.getOrDefault(ROOT_PARENT_ID, new ArrayList<>());
+        if (roots.isEmpty()) {
+            return null;
+        }
+        // 根节点唯一，取最小 id 作为整棵树入口
+        SysGroup root = roots.stream()
+                .min(Comparator.comparingInt(SysGroup::getId))
+                .orElse(roots.get(0));
+        return buildBoaNode(root, childrenMap, true);
+    }
+
+    /**
+     * 获取单个组；withSub=true 时递归挂上全部子孙（整棵子树），false/不传时只返回节点本身（children 为 null）。<br>
+     * 组不存在时返回 null。
+     */
+    @Override
+    public BoaGroup getGroupById(Integer groupId, Boolean withSub) {
+        if (groupId == null) {
+            return null;
+        }
+        SysGroup entity = sysGroupRepository.findById(groupId).orElse(null);
+        if (entity == null) {
+            return null;
+        }
+        if (!Boolean.TRUE.equals(withSub)) {
+            return convertToBoaGroup(entity);
+        }
+        List<SysGroup> all = sysGroupRepository.findAll();
+        Map<Integer, List<SysGroup>> childrenMap = buildSortedChildrenMap(all);
+        return buildBoaNode(entity, childrenMap, true);
+    }
+
+    /**
+     * 批量获取组；ids 逗号/空格分隔，按入参顺序返回，不存在的 id 跳过。<br>
+     * withSub 语义同 {@link #getGroupById(Integer, Boolean)}。
+     */
+    @Override
+    public List<BoaGroup> getGroupList(String ids, Boolean withSub) {
+        List<Integer> idList = parseIds(ids);
+        if (idList.isEmpty()) {
+            return new ArrayList<>();
+        }
+        boolean expand = Boolean.TRUE.equals(withSub);
+        List<SysGroup> all = sysGroupRepository.findAll();
+        Map<Integer, SysGroup> allMap = all.stream()
+                .collect(Collectors.toMap(SysGroup::getId, g -> g, (a, b) -> a));
+        Map<Integer, List<SysGroup>> childrenMap = buildSortedChildrenMap(all);
+        List<BoaGroup> result = new ArrayList<>();
+        for (Integer id : idList) {
+            SysGroup g = allMap.get(id);
+            if (g == null) {
+                continue;
+            }
+            result.add(expand ? buildBoaNode(g, childrenMap, true) : convertToBoaGroup(g));
+        }
+        return result;
+    }
+
+    // ===================== 批量新增 =====================
+
+    @Override
+    @Transactional
+    public List<BoaGroup> batchAdd(SysGroupBatchRequest request) {
+        Integer pid = request.getPid();
+        GroupTypeEnum parentType = null; // null 表示根节点
+        int realPid;
+        if (pid != null && pid != ROOT_PARENT_ID) {
+            SysGroup parent = sysGroupRepository.findById(pid)
+                    .orElseThrow(() -> new DException("父组不存在"));
+            parentType = parent.getType();
+            realPid = pid;
+        } else {
+            // pid 为 null 或 0 表示「挂在根节点(教育云中心)下」：解析真实根节点 id 作为挂载点，
+            // 绝不能写成 ROOT_PARENT_ID(0)，否则批量建出的组都会变成伪根节点。
+            realPid = resolveRootGroup().getId();
+        }
+        GroupTypeEnum typeEnum = resolveType(request.getType());
+        // 层级类型约束
+        validateParentChild(parentType, typeEnum);
+        List<SysGroupBatchRequest.BatchItem> items = request.getItems();
+        if (items == null || items.isEmpty()) {
+            throw new DException("批量新增的子组列表不能为空");
+        }
+        // 追加到当前父组子节点之后
+        int base = nextSort(realPid);
+
+        List<SysGroup> batch = new ArrayList<>();
+        for (int i = 0; i < items.size(); i++) {
+            String name = items.get(i).getName();
+            if (name == null || name.trim().isEmpty()) {
+                throw new DException("第 " + (i + 1) + " 个子组名称为空");
+            }
+            SysGroup g = new SysGroup();
+            g.setName(name.trim());
+            g.setParentId(realPid);
+            g.setType(typeEnum);
+            g.setSort(base + i);
+            g.setCreateUser(SYSTEM_USER_ID);
+            g.setUpdateUser(SYSTEM_USER_ID);
+            batch.add(g);
+        }
+        sysGroupRepository.saveAll(batch);
+        publishGroupEvent(PushInterfaceType.ADD_GROUP,
+                batch.stream().map(SysGroup::getId).collect(Collectors.toList()));
+        return batch.stream().map(this::convertToBoaGroup).collect(Collectors.toList());
+    }
+
+    // ===================== 子组排序 =====================
+
+    @Override
+    @Transactional
+    public void sortChildren(SysGroupSortRequest request) {
+        Integer pid = request.getPid();
+        List<Integer> ids = request.getIds();
+        if (pid == null || !sysGroupRepository.existsById(pid)) {
+            throw new DException("父组不存在");
+        }
+        if (ids == null || ids.isEmpty()) {
+            throw new DException("子节点ID列表不能为空");
+        }
+        if (new HashSet<>(ids).size() != ids.size()) {
+            throw new DException("子节点ID列表存在重复");
+        }
+        // 取出 pid 的直接子节点，校验 ids 全是其直接子节点
+        List<SysGroup> children = sysGroupRepository.findByParentIdOrderBySortAsc(pid);
+        Set<Integer> childIdSet = children.stream().map(SysGroup::getId).collect(Collectors.toSet());
+        for (Integer id : ids) {
+            if (!childIdSet.contains(id)) {
+                throw new DException("ids 中存在不属于该父组的直接子节点");
+            }
+        }
+        // 按传入顺序落库排序（1 起）
+        Map<Integer, SysGroup> childMap = children.stream()
+                .collect(Collectors.toMap(SysGroup::getId, c -> c, (a, b) -> a));
+        for (int i = 0; i < ids.size(); i++) {
+            childMap.get(ids.get(i)).setSort(i + 1);
+        }
+        sysGroupRepository.saveAll(children);
+    }
+
+    // ===================== 移动组 =====================
+
+    @Override
+    @Transactional
+    public void move(SysGroupMoveRequest request) {
+        Integer moveId = request.getMoveId();
+        Integer pid = request.getPid();
+        if (moveId == null || !sysGroupRepository.existsById(moveId)) {
+            throw new DException("待移动节点不存在");
+        }
+        if (pid == null) {
+            throw new DException("目标父节点不存在");
+        }
+        // 目标父为根节点时 pid=0；其余情况校验目标父存在并取其类型
+        GroupTypeEnum parentType = null; // null 表示根节点
+        if (pid != ROOT_PARENT_ID) {
+            SysGroup target = sysGroupRepository.findById(pid)
+                    .orElseThrow(() -> new DException("目标父节点不存在"));
+            parentType = target.getType();
+        }
+        SysGroup moveEntity = sysGroupRepository.findById(moveId).get();
+        // 根节点不可移动
+        if (isRoot(moveEntity)) {
+            throw new DException("根节点不可移动");
+        }
+        if (Objects.equals(pid, moveId)) {
+            throw new DException("不能移动到自身下");
+        }
+        // 环检测：目标父节点不能是待移动节点的后代（含自身）
+        Map<Integer, SysGroup> allMap = sysGroupRepository.findAll().stream()
+                .collect(Collectors.toMap(SysGroup::getId, g -> g, (a, b) -> a));
+        if (isDescendantOf(pid, moveId, allMap)) {
+            throw new DException("不能移动到自身子节点下");
+        }
+        // 层级类型约束：移动后目标父类型须允许该节点类型
+        validateParentChild(parentType, moveEntity.getType());
+        // 移动后追加到目标父节点的子节点末尾
+        moveEntity.setParentId(pid);
+        moveEntity.setSort(nextSort(pid));
+        sysGroupRepository.save(moveEntity);
+        publishGroupEvent(PushInterfaceType.UPDATE_GROUP, moveId);
+    }
+
+    @Override
+    @Transactional
+    public void move(SysGroupMoveRequest request, Integer schoolId) {
+        // 开放接口边界：moveId/pid 必须落在 schoolId 子树内（禁止跨校/移学校根组/移出平台根）
+        assertMoveWithinSchool(request.getMoveId(), request.getPid(), schoolId);
+        move(request);
+    }
+
+    /**
+     * 学校边界校验：确保待移动节点与目标父节点都属于指定学校范围，且不越界。
+     *
+     * @param moveId   待移动节点ID
+     * @param pid      目标父节点ID
+     * @param schoolId 学校组ID（限定移动范围）
+     */
+    private void assertMoveWithinSchool(Integer moveId, Integer pid, Integer schoolId) {
+        // 公共锚点校验：schoolId 非空、存在、必须为学校组
+        assertSchoolId(schoolId);
+        if (moveId == null) {
+            throw new DException("待移动节点ID不能为空");
+        }
+        if (pid == null) {
+            throw new DException("目标父节点ID不能为空");
+        }
+        if (moveId.equals(schoolId)) {
+            throw new DException("禁止移动学校根组，请指定具体子组");
+        }
+        if (pid == ROOT_PARENT_ID) {
+            throw new DException("禁止移动到学校范围之外（根节点）");
+        }
+        List<Integer> schoolScope = listSelfAndDescendantIds(schoolId);
+        if (!schoolScope.contains(moveId)) {
+            throw new DException("待移动节点不属于该学校范围，禁止跨校移动");
+        }
+        if (!schoolScope.contains(pid)) {
+            throw new DException("目标父节点不属于该学校范围，禁止跨校移动");
+        }
+    }
+
+    /**
+     * 判断 ancestorCandidate 是否为 nodeId 的后代（沿 parentId 向上回溯）。<br>
+     */
+    private boolean isDescendantOf(Integer ancestorCandidate, Integer nodeId, Map<Integer, SysGroup> allMap) {
+        Integer cursor = ancestorCandidate;
+        while (cursor != null && cursor != ROOT_PARENT_ID) {
+            if (Objects.equals(cursor, nodeId)) {
+                return true;
+            }
+            SysGroup g = allMap.get(cursor);
+            if (g == null) {
+                return false;
+            }
+            cursor = g.getParentId();
+        }
+        return false;
+    }
+
+    // ===================== 子树聚合 =====================
+
+    @Override
+    public List<Integer> listSelfAndDescendantIds(Integer groupId) {
+        List<Integer> result = new ArrayList<>();
+        if (groupId == null) {
+            return result;
+        }
+        result.add(groupId);
+        // parentId -> 直接子节点ID列表
+        Map<Integer, List<Integer>> childrenMap = new HashMap<>();
+        for (SysGroup g : sysGroupRepository.findAll()) {
+            Integer parent = (g.getParentId() == null) ? ROOT_PARENT_ID : g.getParentId();
+            childrenMap.computeIfAbsent(parent, k -> new ArrayList<>()).add(g.getId());
+        }
+        // 广度优先向下收集所有子孙
+        List<Integer> frontier = new ArrayList<>();
+        frontier.add(groupId);
+        while (!frontier.isEmpty()) {
+            List<Integer> next = new ArrayList<>();
+            for (Integer id : frontier) {
+                List<Integer> children = childrenMap.get(id);
+                if (children != null) {
+                    result.addAll(children);
+                    next.addAll(children);
+                }
+            }
+            frontier = next;
+        }
+        return result;
+    }
+
+    // ===================== 私有工具 =====================
+
+    /** SysGroup -> BoaGroup（id/name/parentId/type/sort）；children 默认 null（未展开）。 */
+    private BoaGroup convertToBoaGroup(SysGroup entity) {
+        BoaGroup bg = new BoaGroup();
+        bg.setId(entity.getId());
+        bg.setName(entity.getName());
+        bg.setParentId(entity.getParentId());
+        bg.setType(entity.getType() == null ? null : entity.getType().getKey());
+        bg.setSort(entity.getSort());
+        return bg;
+    }
+
+    /**
+     * 递归组装 BoaGroup 树节点。withSub=true 时挂上全部子孙（子树），children 为列表（无子则空列表）；
+     * withSub=false 时直接返回节点，children 保持 null（表示未展开）。
+     */
+    private BoaGroup buildBoaNode(SysGroup node, Map<Integer, List<SysGroup>> childrenMap, boolean withSub) {
+        BoaGroup bg = convertToBoaGroup(node);
+        if (!withSub) {
+            return bg;
+        }
+        List<BoaGroup> childBgs = new ArrayList<>();
+        List<SysGroup> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (SysGroup child : children) {
+                childBgs.add(buildBoaNode(child, childrenMap, true));
+            }
+        }
+        bg.setChildren(childBgs);
+        return bg;
+    }
+
+    /** 解析逗号/空格分隔的 id 串为 Integer 列表；非数字片段忽略。 */
+    private List<Integer> parseIds(String ids) {
+        List<Integer> result = new ArrayList<>();
+        if (ids == null || ids.trim().isEmpty()) {
+            return result;
+        }
+        for (String s : ids.split("[,\\s]+")) {
+            if (s == null || s.trim().isEmpty()) {
+                continue;
+            }
+            try {
+                result.add(Integer.parseInt(s.trim()));
+            } catch (NumberFormatException ignored) {
+                // 跳过非数字片段
+            }
+        }
+        return result;
+    }
+
+    /** pid 下已有子节点的最大 sort +1；无子节点返回 1。 */
+    private int nextSort(Integer pid) {
+        Integer max = sysGroupRepository.findMaxSortByParentId(pid);
+        return (max == null ? 0 : max) + 1;
+    }
+
+    /** 校验并返回组类型枚举；非法类型抛异常。 */
+    private GroupTypeEnum resolveType(Integer type) {
+        GroupTypeEnum typeEnum = IEnum.getByKey(GroupTypeEnum.class, type);
+        if (typeEnum == null) {
+            throw new DException("组类型不存在");
+        }
+        return typeEnum;
+    }
+
+    /** 是否为系统根节点（唯一的 pid=0 节点）。 */
+    private boolean isRoot(SysGroup entity) {
+        return entity.getParentId() != null && entity.getParentId() == ROOT_PARENT_ID;
+    }
+
+    /**
+     * 解析唯一真实根节点（parentId=0 中 id 最小者，与 {@link #getGroups()} 约定一致）。<br>
+     * 用于「parentId/ pid 为 0 或 null 表示挂根下」场景：必须把新组挂到该根节点的真实 id 下，
+     * 而非把 parentId 写成 0（0 仅属于根本身，写成 0 会生成第二个伪根节点）。
+     *
+     * @return 根节点实体
+     * @throws DException 当不存在任何根节点时
+     */
+    private SysGroup resolveRootGroup() {
+        List<SysGroup> roots = sysGroupRepository.findByParentIdOrderBySortAsc(ROOT_PARENT_ID);
+        if (roots.isEmpty()) {
+            throw new DException("根节点不存在，无法在根下建组");
+        }
+        // 与 getGroups 约定一致：pid=0 中 id 最小者为唯一真实根节点
+        return roots.stream()
+                .min(Comparator.comparingInt(SysGroup::getId))
+                .orElse(roots.get(0));
+    }
+
+    private SysGroupVo convertToVo(SysGroup entity) {
+        SysGroupVo vo = new SysGroupVo();
+        BeanUtils.copyProperties(entity, vo);
+        vo.setType(entity.getType() == null ? null : entity.getType().getKey());
+        return vo;
+    }
+
+    // ===================== 推送事件（AFTER_COMMIT 由 PushDispatcher 消费，push_enabled 默认 0 不触发） =====================
+
+    private void publishGroupEvent(PushInterfaceType type, Integer groupId) {
+        DataSyncEvent e = new DataSyncEvent();
+        e.setType(type);
+        e.setGroupIds(Collections.singletonList(groupId));
+        e.setSourceAppKey(CallerAppContext.getAppKey());
+        eventPublisher.publishEvent(e);
+    }
+
+    private void publishGroupEvent(PushInterfaceType type, List<Integer> groupIds) {
+        if (groupIds == null || groupIds.isEmpty()) {
+            return;
+        }
+        DataSyncEvent e = new DataSyncEvent();
+        e.setType(type);
+        e.setGroupIds(groupIds);
+        e.setSourceAppKey(CallerAppContext.getAppKey());
+        eventPublisher.publishEvent(e);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/SysOapiLogServiceImpl.java b/src/main/java/com/yunhai/userbase/service/impl/SysOapiLogServiceImpl.java
new file mode 100644
index 0000000..e6327c7
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/SysOapiLogServiceImpl.java
@@ -0,0 +1,186 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.userbase.entity.SysOapiLog;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oapilog.SysOapiLogListVo;
+import com.yunhai.userbase.model.oapilog.SysOapiLogQuery;
+import com.yunhai.userbase.repository.SysOapiLogRepository;
+import com.yunhai.userbase.service.ISysOapiLogService;
+import com.yunhai.userbase.utils.GzipUtil;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+import javax.persistence.TypedQuery;
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.CriteriaQuery;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 开放接口调用日志业务实现。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Slf4j
+@Service
+public class SysOapiLogServiceImpl implements ISysOapiLogService {
+
+    /** 一般日志(level=3)保留时长：一年（12 个月）。 */
+    private static final int GENERAL_RETENTION_MONTHS = 12;
+    /** 重要(level=1)/次要(level=2)日志保留时长：三年（36 个月）。 */
+    private static final int IMPORTANT_RETENTION_MONTHS = 36;
+
+    @Autowired
+    private SysOapiLogRepository sysOapiLogRepository;
+
+    @PersistenceContext
+    private EntityManager em;
+
+    @Override
+    @Async("oapiLogExecutor")
+    public void saveAsync(SysOapiLog entity) {
+        try {
+            sysOapiLogRepository.save(entity);
+        } catch (Exception e) {
+            // 日志落库失败绝不抛回主流程，仅记录
+            log.error("开放接口日志异步落库失败, uri={}, method={}",
+                    entity.getRequestUri(), entity.getRequestMethod(), e);
+        }
+    }
+
+    @Override
+    public BasePageResult<SysOapiLogListVo> pageQuery(SysOapiLogQuery query, BasePageQuery pageQuery) {
+        int pageIndex = Math.max(pageQuery.getPageIndex(), 1);
+        int pageSize = Math.max(pageQuery.getPageSize(), 1);
+
+        CriteriaBuilder cb = em.getCriteriaBuilder();
+        // 列表投影：显式选择字段，不包含 response_data，避免加载 MEDIUMBLOB
+        CriteriaQuery<SysOapiLogListVo> cq = cb.createQuery(SysOapiLogListVo.class);
+        Root<SysOapiLog> root = cq.from(SysOapiLog.class);
+        cq.select(cb.construct(SysOapiLogListVo.class,
+                root.get("id"), root.get("logLevel"), root.get("callerAppKey"), root.get("callerAppName"),
+                root.get("requestIp"), root.get("requestUri"), root.get("requestMethod"),
+                root.get("operationType"), root.get("classMethod"), root.get("operationDesc"),
+                root.get("requestParams"), root.get("statusCode"), root.get("costTime"),
+                root.get("userAgent"), root.get("errorMsg"), root.get("createTime")));
+        List<Predicate> predicates = buildPredicates(cb, root, query);
+        cq.where(predicates.toArray(new Predicate[0]));
+        cq.orderBy(cb.desc(root.get("createTime")));
+
+        // 总数查询
+        CriteriaQuery<Long> countCq = cb.createQuery(Long.class);
+        Root<SysOapiLog> countRoot = countCq.from(SysOapiLog.class);
+        countCq.select(cb.count(countRoot));
+        countCq.where(buildPredicates(cb, countRoot, query).toArray(new Predicate[0]));
+        long total = em.createQuery(countCq).getSingleResult();
+
+        TypedQuery<SysOapiLogListVo> typed = em.createQuery(cq);
+        typed.setFirstResult((pageIndex - 1) * pageSize);
+        typed.setMaxResults(pageSize);
+        List<SysOapiLogListVo> content = typed.getResultList();
+        // 响应结果随列表带出（GZIP 解压后），供详情弹窗直接展示，无需再单独请求
+        for (SysOapiLogListVo vo : content) {
+            vo.setResponseData(getResponseData(vo.getId()));
+        }
+
+        int totalPages = (int) Math.ceil((double) total / pageSize);
+        boolean hasNext = pageIndex < totalPages;
+
+        return new BasePageResult<>(content, (int) total, pageIndex, pageSize, totalPages, hasNext);
+    }
+
+    @Override
+    public String getResponseData(Long id) {
+        SysOapiLog entity = sysOapiLogRepository.findById(id).orElse(null);
+        if (entity == null || entity.getResponseData() == null) {
+            return null;
+        }
+        return GzipUtil.decompress(entity.getResponseData());
+    }
+
+    @Override
+    @Transactional
+    public long cleanupExpired() {
+        LocalDateTime now = LocalDateTime.now();
+        LocalDateTime generalDeadline = now.minusMonths(GENERAL_RETENTION_MONTHS);
+        LocalDateTime importantDeadline = now.minusMonths(IMPORTANT_RETENTION_MONTHS);
+        // 一般日志(level=3)保留一年（12个月）；重要(level=1)/次要(level=2)保留三年（36个月）
+        long deleted = sysOapiLogRepository.deleteByLogLevelAndCreateTimeBefore(3, generalDeadline)
+                + sysOapiLogRepository.deleteByLogLevelAndCreateTimeBefore(2, importantDeadline)
+                + sysOapiLogRepository.deleteByLogLevelAndCreateTimeBefore(1, importantDeadline);
+        log.info("开放接口日志清理完成, 删除{}条(一般截止={}, 重要/次要截止={})",
+                deleted, generalDeadline, importantDeadline);
+        return deleted;
+    }
+
+    /**
+     * 构建动态查询条件。<br>
+     * 模糊字段使用 LIKE，时间使用范围，其余等值匹配。<br>
+     *
+     * @param cb    条件构建器
+     * @param root  根路径
+     * @param query 查询条件
+     * @return 谓词列表
+     */
+    private List<Predicate> buildPredicates(CriteriaBuilder cb, Root<SysOapiLog> root,
+                                            SysOapiLogQuery query) {
+        List<Predicate> predicates = new ArrayList<Predicate>();
+        if (query == null) {
+            return predicates;
+        }
+        if (query.getLogLevel() != null) {
+            predicates.add(cb.equal(root.get("logLevel"), query.getLogLevel()));
+        }
+        if (query.getCallerAppKey() != null) {
+            predicates.add(cb.equal(root.get("callerAppKey"), query.getCallerAppKey()));
+        }
+        if (StringUtils.isNotBlank(query.getCallerAppName())) {
+            predicates.add(cb.like(root.get("callerAppName"), "%" + query.getCallerAppName() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getRequestUri())) {
+            predicates.add(cb.like(root.get("requestUri"), "%" + query.getRequestUri() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getRequestIp())) {
+            predicates.add(cb.like(root.get("requestIp"), "%" + query.getRequestIp() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getOperationType())) {
+            predicates.add(cb.equal(root.get("operationType"), query.getOperationType()));
+        }
+        if (query.getStatusCode() != null) {
+            predicates.add(cb.equal(root.get("statusCode"), query.getStatusCode()));
+        }
+        if (query.getSuccess() != null) {
+            if (Boolean.TRUE.equals(query.getSuccess())) {
+                predicates.add(cb.equal(root.get("statusCode"), 200));
+            } else {
+                predicates.add(cb.notEqual(root.get("statusCode"), 200));
+            }
+        }
+        if (StringUtils.isNotBlank(query.getKeyword())) {
+            String kw = "%" + query.getKeyword().trim() + "%";
+            // 单输入框同时匹配：请求路径(requestUri) / 应用名(callerAppName) / appKey(callerAppKey)
+            predicates.add(cb.or(
+                    cb.like(root.get("requestUri"), kw),
+                    cb.like(root.get("callerAppName"), kw),
+                    cb.like(cb.toString(root.get("callerAppKey")), kw)));
+        }
+        if (query.getStartTime() != null) {
+            predicates.add(cb.greaterThanOrEqualTo(root.get("createTime"), query.getStartTime()));
+        }
+        if (query.getEndTime() != null) {
+            predicates.add(cb.lessThanOrEqualTo(root.get("createTime"), query.getEndTime()));
+        }
+        return predicates;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/SysOperationLogServiceImpl.java b/src/main/java/com/yunhai/userbase/service/impl/SysOperationLogServiceImpl.java
new file mode 100644
index 0000000..72076b4
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/SysOperationLogServiceImpl.java
@@ -0,0 +1,181 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.userbase.entity.SysOperationLog;
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import com.yunhai.userbase.model.oplog.SysOperationLogListVo;
+import com.yunhai.userbase.model.oplog.SysOperationLogQuery;
+import com.yunhai.userbase.repository.SysOperationLogRepository;
+import com.yunhai.userbase.service.ISysOperationLogService;
+import com.yunhai.userbase.utils.GzipUtil;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+import javax.persistence.TypedQuery;
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.CriteriaQuery;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 系统操作日志业务实现。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Slf4j
+@Service
+public class SysOperationLogServiceImpl implements ISysOperationLogService {
+
+    /** 一般日志(level=3)保留时长：一年（12 个月）。 */
+    private static final int GENERAL_RETENTION_MONTHS = 12;
+    /** 重要(level=1)/次要(level=2)日志保留时长：三年（36 个月）。 */
+    private static final int IMPORTANT_RETENTION_MONTHS = 36;
+
+    @Autowired
+    private SysOperationLogRepository sysOperationLogRepository;
+
+    @PersistenceContext
+    private EntityManager em;
+
+    @Override
+    @Async("oapiLogExecutor")
+    public void saveAsync(SysOperationLog entity) {
+        try {
+            sysOperationLogRepository.save(entity);
+        } catch (Exception e) {
+            // 日志落库失败绝不抛回主流程，仅记录
+            log.error("操作日志异步落库失败, uri={}, method={}",
+                    entity.getRequestUri(), entity.getRequestMethod(), e);
+        }
+    }
+
+    @Override
+    public BasePageResult<SysOperationLogListVo> pageQuery(SysOperationLogQuery query,
+                                                          BasePageQuery pageQuery) {
+        int pageIndex = Math.max(pageQuery.getPageIndex(), 1);
+        int pageSize = Math.max(pageQuery.getPageSize(), 1);
+
+        CriteriaBuilder cb = em.getCriteriaBuilder();
+        // 列表投影：显式选择字段，不包含 response_data，避免加载 MEDIUMBLOB
+        CriteriaQuery<SysOperationLogListVo> cq = cb.createQuery(SysOperationLogListVo.class);
+        Root<SysOperationLog> root = cq.from(SysOperationLog.class);
+        cq.select(cb.construct(SysOperationLogListVo.class,
+                root.get("id"), root.get("logLevel"), root.get("userId"), root.get("username"),
+                root.get("requestIp"), root.get("requestUri"), root.get("requestMethod"),
+                root.get("operationType"), root.get("classMethod"), root.get("requestParams"),
+                root.get("statusCode"), root.get("costTime"), root.get("userAgent"),
+                root.get("errorMsg"), root.get("createTime")));
+        List<Predicate> predicates = buildPredicates(cb, root, query);
+        cq.where(predicates.toArray(new Predicate[0]));
+        cq.orderBy(cb.desc(root.get("createTime")));
+
+        // 总数查询
+        CriteriaQuery<Long> countCq = cb.createQuery(Long.class);
+        Root<SysOperationLog> countRoot = countCq.from(SysOperationLog.class);
+        countCq.select(cb.count(countRoot));
+        countCq.where(buildPredicates(cb, countRoot, query).toArray(new Predicate[0]));
+        long total = em.createQuery(countCq).getSingleResult();
+
+        TypedQuery<SysOperationLogListVo> typed = em.createQuery(cq);
+        typed.setFirstResult((pageIndex - 1) * pageSize);
+        typed.setMaxResults(pageSize);
+        List<SysOperationLogListVo> content = typed.getResultList();
+
+        int totalPages = (int) Math.ceil((double) total / pageSize);
+        boolean hasNext = pageIndex < totalPages;
+
+        return new BasePageResult<>(content, (int) total, pageIndex, pageSize, totalPages, hasNext);
+    }
+
+    @Override
+    public String getResponseData(Long id) {
+        SysOperationLog entity = sysOperationLogRepository.findById(id).orElse(null);
+        if (entity == null || entity.getResponseData() == null) {
+            return null;
+        }
+        return GzipUtil.decompress(entity.getResponseData());
+    }
+
+    @Override
+    @Transactional
+    public long cleanupExpired() {
+        LocalDateTime now = LocalDateTime.now();
+        LocalDateTime generalDeadline = now.minusMonths(GENERAL_RETENTION_MONTHS);
+        LocalDateTime importantDeadline = now.minusMonths(IMPORTANT_RETENTION_MONTHS);
+        // 一般日志(level=3)保留一年（12个月）；重要(level=1)/次要(level=2)保留三年（36个月）
+        long deleted = sysOperationLogRepository.deleteByLogLevelAndCreateTimeBefore(3, generalDeadline)
+                + sysOperationLogRepository.deleteByLogLevelAndCreateTimeBefore(2, importantDeadline)
+                + sysOperationLogRepository.deleteByLogLevelAndCreateTimeBefore(1, importantDeadline);
+        log.info("操作日志清理完成, 删除{}条(一般截止={}, 重要/次要截止={})",
+                deleted, generalDeadline, importantDeadline);
+        return deleted;
+    }
+
+    /**
+     * 构建动态查询条件。<br>
+     * 模糊字段使用 LIKE，时间使用范围，其余等值匹配。<br>
+     *
+     * @param cb    条件构建器
+     * @param root  根路径
+     * @param query 查询条件
+     * @return 谓词列表
+     */
+    private List<Predicate> buildPredicates(CriteriaBuilder cb, Root<SysOperationLog> root,
+                                            SysOperationLogQuery query) {
+        List<Predicate> predicates = new ArrayList<Predicate>();
+        if (query == null) {
+            return predicates;
+        }
+        if (query.getLogLevel() != null) {
+            predicates.add(cb.equal(root.get("logLevel"), query.getLogLevel()));
+        }
+        if (query.getUserId() != null) {
+            predicates.add(cb.equal(root.get("userId"), query.getUserId()));
+        }
+        if (StringUtils.isNotBlank(query.getUsername())) {
+            predicates.add(cb.like(root.get("username"), "%" + query.getUsername() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getRequestUri())) {
+            predicates.add(cb.like(root.get("requestUri"), "%" + query.getRequestUri() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getRequestIp())) {
+            predicates.add(cb.like(root.get("requestIp"), "%" + query.getRequestIp() + "%"));
+        }
+        if (StringUtils.isNotBlank(query.getOperationType())) {
+            predicates.add(cb.equal(root.get("operationType"), query.getOperationType()));
+        }
+        if (query.getStatusCode() != null) {
+            predicates.add(cb.equal(root.get("statusCode"), query.getStatusCode()));
+        }
+        if (query.getSuccess() != null) {
+            if (Boolean.TRUE.equals(query.getSuccess())) {
+                predicates.add(cb.equal(root.get("statusCode"), 200));
+            } else {
+                predicates.add(cb.notEqual(root.get("statusCode"), 200));
+            }
+        }
+        if (StringUtils.isNotBlank(query.getKeyword())) {
+            String kw = "%" + query.getKeyword().trim() + "%";
+            predicates.add(cb.or(
+                    cb.like(root.get("requestUri"), kw),
+                    cb.like(root.get("username"), kw)));
+        }
+        if (query.getStartTime() != null) {
+            predicates.add(cb.greaterThanOrEqualTo(root.get("createTime"), query.getStartTime()));
+        }
+        if (query.getEndTime() != null) {
+            predicates.add(cb.lessThanOrEqualTo(root.get("createTime"), query.getEndTime()));
+        }
+        return predicates;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/SysUserService.java b/src/main/java/com/yunhai/userbase/service/impl/SysUserService.java
new file mode 100644
index 0000000..c9253c5
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/SysUserService.java
@@ -0,0 +1,1148 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.platform.utils.model.BoaRoleInfo;
+import com.yunhai.userbase.entity.SysAppRole;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.platform.utils.enums.IEnum;
+import com.yunhai.userbase.enums.StatusEnum;
+import com.yunhai.userbase.enums.SysRoleEnum;
+import com.yunhai.userbase.enums.UserTypeEnum;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserAppRoleRel;
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import com.yunhai.userbase.model.sysuser.BatchImportResult;
+import com.yunhai.userbase.model.sysuser.SysUserGroupDeleteItem;
+import com.yunhai.userbase.model.sysuser.SysUserQuery;
+import com.yunhai.userbase.model.sysuser.SysUserRequest;
+import com.yunhai.userbase.model.sysuser.SysUserVo;
+import com.yunhai.userbase.repository.SysAppRoleRepository;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserAppRoleRelRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import com.yunhai.userbase.service.ISysGroupService;
+import com.yunhai.userbase.service.ISysUserService;
+import com.yunhai.userbase.event.DataSyncEvent;
+import com.yunhai.userbase.common.context.CallerAppContext;
+import com.yunhai.userbase.model.push.PushInterfaceType;
+import org.springframework.context.ApplicationEventPublisher;
+import cn.afterturn.easypoi.excel.ExcelExportUtil;
+import cn.afterturn.easypoi.excel.entity.ExportParams;
+import cn.afterturn.easypoi.excel.entity.enmus.ExcelType;
+import com.yunhai.userbase.model.sysuser.ExcelSysUser;
+import com.yunhai.userbase.utils.EasyPoiUtils;
+import com.yunhai.userbase.utils.ValidatorUtil;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.domain.Specification;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+
+import org.apache.poi.ss.usermodel.*;
+import org.apache.poi.xssf.usermodel.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.URLEncoder;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+import java.util.*;
+import java.util.stream.Collectors;
+
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * @author chenx
+ * @date 2026/7/20 16:14
+ * @description 系统用户服务实现
+ */
+@Service
+public class SysUserService implements ISysUserService {
+
+    /** 主归属标识：1=本职主学校/部门 */
+    private static final int IS_MAIN = 1;
+
+    /** 开放接口/oapi 写操作无登录态时使用的审计人哨兵值（非真实用户ID），用于兜底 create_user/update_user 的 NOT NULL 约束。 */
+    private static final int SYSTEM_USER_ID = 0;
+
+    /** 系统内置超级管理员账号（与 sys_user_init.sql 种子账号保持一致） */
+    private static final Set<String> SUPER_ADMIN_ACCOUNTS =
+            new HashSet<>(Arrays.asList("yunhaisch", "yunhaisch2", "yunhaisch3"));
+
+    @Autowired
+    private SysUserRepository sysUserRepository;
+
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+
+    @Autowired
+    private SysUserAppRoleRelRepository sysUserAppRoleRelRepository;
+
+    @Autowired
+    private ApplicationEventPublisher eventPublisher;
+
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+
+    @Autowired
+    private ISysGroupService sysGroupService;
+
+    @Autowired
+    private SysAppRoleRepository sysAppRoleRepository;
+
+    @Autowired
+    private PasswordEncoder passwordEncoder;
+
+    @Override
+    @Transactional
+    public Integer add(SysUserRequest request) {
+        // 单条新增走完整校验（含密码强度）
+        return createUser(request, true);
+    }
+
+    /**
+     * 创建用户并写入组关联。
+     *
+     * @param enforcePasswordStrength 是否强制密码强度校验：
+     *                                 - 单条新增 = true（前端已交互式校验）；
+     *                                 - 批量导入 = false（默认密码 Vzuk4Dp3 不含符号，按业务约定直接放行）。
+     */
+    private Integer createUser(SysUserRequest request, boolean enforcePasswordStrength) {
+        if (sysUserRepository.countByAccount(request.getAccount()) > 0) {
+            throw new DException("账号已存在");
+        }
+        if (!sysGroupRepository.existsById(request.getGroupId())) {
+            throw new DException("所属分组不存在");
+        }
+        validateProfile(request);
+        String encodedPassword = enforcePasswordStrength
+                ? validateAndEncodePassword(request.getPassword(), request.getConfirmPassword())
+                : passwordEncoder.encode(request.getPassword());
+
+        SysUser entity = new SysUser();
+        entity.setAccount(request.getAccount());
+        entity.setPassword(encodedPassword);
+        entity.setRealName(request.getRealName());
+        entity.setPhone(request.getPhone());
+        entity.setBirthday(request.getBirthday());
+        entity.setIdcard(request.getIdcard());
+        entity.setEmail(request.getEmail());
+        entity.setGender(request.getGender());
+        entity.setProfilePicture(request.getProfilePicture());
+        entity.setRoles(request.getRoles());
+        // 用户类型推导：超级管理员账号固定为 1；其余含 ADMIN(7) 角色 -> 2 学校管理员；默认 0 普通用户
+        entity.setType(resolveUserType(entity.getAccount(), entity.getRoles()));
+        // disabled 用枚举存储：不传时默认 NORMAL（正常/未禁用）
+        entity.setDisabled(request.getDisabled() != null ? resolveStatus(request.getDisabled()) : StatusEnum.NORMAL);
+        entity.setExpired(request.getExpired() != null ? request.getExpired() : false);
+        // oapi 写操作无登录态时，用系统哨兵值兜底 create_user/update_user（NOT NULL 约束）
+        entity.setCreateUser(SYSTEM_USER_ID);
+        entity.setUpdateUser(SYSTEM_USER_ID);
+        SysUser saved = sysUserRepository.save(entity);
+        publishUserEvent(PushInterfaceType.ADD_USER, saved.getId());
+
+        // 写入组用户关联
+        SysUserGroupRel rel = new SysUserGroupRel();
+        rel.setUserId(entity.getId());
+        rel.setGroupId(request.getGroupId());
+        rel.setIsMain(IS_MAIN);
+        rel.setCreateTime(LocalDateTime.now());
+        sysUserGroupRelRepository.save(rel);
+
+        return saved.getId();
+    }
+
+    @Override
+    @Transactional
+    public void edit(Integer id, SysUserRequest request) {
+        if (sysUserRepository.countByAccountAndIdNot(request.getAccount(), id) > 0) {
+            throw new DException("账号已被其他用户使用");
+        }
+        SysUser entity = sysUserRepository.findById(id)
+                .orElseThrow(() -> new DException("系统用户不存在"));
+        validateProfile(request);
+
+        entity.setAccount(request.getAccount());
+        // 密码非空才修改：需两次一致 + 弱密码校验 + BCrypt 加密
+        if (StringUtils.isNotBlank(request.getPassword())) {
+            entity.setPassword(validateAndEncodePassword(request.getPassword(), request.getConfirmPassword()));
+        }
+        entity.setRealName(request.getRealName());
+        entity.setPhone(request.getPhone());
+        entity.setBirthday(request.getBirthday());
+        entity.setIdcard(request.getIdcard());
+        entity.setEmail(request.getEmail());
+        entity.setGender(request.getGender());
+        entity.setProfilePicture(request.getProfilePicture());
+        entity.setRoles(request.getRoles());
+        // 用户类型推导：仅当本次传入了角色时才重算，避免编辑时未传角色把 type 误重置为 0
+        if (request.getRoles() != null) {
+            entity.setType(resolveUserType(entity.getAccount(), entity.getRoles()));
+        }
+        if (request.getDisabled() != null) {
+            entity.setDisabled(resolveStatus(request.getDisabled()));
+        }
+        if (request.getExpired() != null) {
+            entity.setExpired(request.getExpired());
+        }
+        entity.setUpdateUser(SYSTEM_USER_ID);
+        sysUserRepository.save(entity);
+        publishUserEvent(PushInterfaceType.UPDATE_USER, id);
+    }
+
+    @Override
+    @Transactional
+    public List<Integer> batchAdd(List<SysUserRequest> requests) {
+        if (requests == null || requests.isEmpty()) {
+            throw new DException("批量新增用户列表不能为空");
+        }
+        // 批量新增与单条一致：强制密码强度校验（每条需携带 password + confirmPassword）
+        List<Integer> ids = new ArrayList<>();
+        for (SysUserRequest request : requests) {
+            ids.add(createUser(request, true));
+        }
+        return ids;
+    }
+
+    @Override
+    @Transactional
+    public void deleteFromGroup(Integer userId, Integer groupId) {
+        batchDeleteFromGroup(Collections.singletonList(userId), groupId);
+    }
+
+    @Override
+    @Transactional
+    public void batchDeleteFromGroup(List<Integer> userIds, Integer groupId) {
+        if (userIds == null || userIds.isEmpty()) {
+            throw new DException("待删除用户不能为空");
+        }
+        if (groupId == null) {
+            throw new DException("组ID不能为空");
+        }
+
+        List<SysUser> users = sysUserRepository.findAllById(userIds);
+        if (users.size() != userIds.size()) {
+            throw new DException("存在无效用户");
+        }
+
+        for (Integer userId : userIds) {
+            // 删除当前组关联
+            sysUserGroupRelRepository.deleteByUserIdAndGroupId(userId, groupId);
+            // 若用户已无其它组关联，则级联删除用户本身及其角色绑定
+            if (sysUserGroupRelRepository.countByUserId(userId) == 0) {
+                sysUserAppRoleRelRepository.deleteByUserIdBulk(userId);
+                sysUserRepository.deleteById(userId);
+            }
+        }
+        // 业务语义：从组移除 = 对子应用即删除（不论是否真删账户），统一推送 DELETE_USER
+        // 因是「解除组关系」，需携带 (userId, groupId) 供子应用精确处理
+        publishUserEvent(PushInterfaceType.DELETE_USER, userIds, groupId);
+    }
+
+    @Override
+    @Transactional
+    public void deleteFromGroup(Integer userId, Integer groupId, Integer schoolId) {
+        // 开放接口边界：groupId 必须属于 schoolId 子树且不能等于 schoolId（禁止跨校/整校移除）
+        assertGroupWithinSchool(groupId, schoolId);
+        batchDeleteFromGroup(Collections.singletonList(userId), groupId);
+    }
+
+    @Override
+    @Transactional
+    public void deleteUsers(List<SysUserGroupDeleteItem> items) {
+        if (items == null || items.isEmpty()) {
+            throw new DException("批量删除用户-组关系列表不能为空");
+        }
+        for (SysUserGroupDeleteItem item : items) {
+            deleteFromGroup(item.getUserId(), item.getGroupId(), item.getSchoolId());
+        }
+    }
+
+    /**
+     * 学校边界校验：确保待操作的组属于指定学校范围，且不是学校根组本身。<br>
+     * 与 {@link #moveUserWithinSchool} 的「学校子树范围」判定一致，复用 {@code listSelfAndDescendantIds}。
+     *
+     * @param groupId  待操作组ID（解绑/删除目标）
+     * @param schoolId 学校组ID（限定范围）
+     */
+    private void assertGroupWithinSchool(Integer groupId, Integer schoolId) {
+        // 公共锚点校验：schoolId 非空、存在、必须为学校组（复用 SysGroupService.assertSchoolId）
+        sysGroupService.assertSchoolId(schoolId);
+        if (groupId == null) {
+            throw new DException("组ID不能为空");
+        }
+        // 拿学校根组当 groupId = 把用户从整所学校移除，禁止
+        if (groupId.equals(schoolId)) {
+            throw new DException("禁止对学校根组执行该操作，请指定具体子组");
+        }
+        // groupId 必须落在 schoolId 子树（含子孙，不含学校根组自身——上面已拦截）
+        List<Integer> schoolScope = sysGroupService.listSelfAndDescendantIds(schoolId);
+        if (!schoolScope.contains(groupId)) {
+            throw new DException("组不属于该学校范围，禁止跨校操作");
+        }
+    }
+
+    @Override
+    @Transactional
+    public void changeStatus(Integer id, boolean disabled) {
+        SysUser entity = sysUserRepository.findById(id)
+                .orElseThrow(() -> new DException("系统用户不存在"));
+        // 实体 disabled 字段为 StatusEnum（0=正常/未禁用，1=禁用）：boolean 直接映射枚举
+        entity.setDisabled(disabled ? StatusEnum.DISABLED : StatusEnum.NORMAL);
+        sysUserRepository.save(entity);
+        publishUserEvent(PushInterfaceType.UPDATE_USER, id);
+    }
+
+    @Override
+    @Transactional
+    public void batchChangeStatus(List<Integer> userIds, boolean disabled) {
+        if (userIds == null || userIds.isEmpty()) {
+            throw new DException("待设置用户不能为空");
+        }
+        List<SysUser> users = sysUserRepository.findAllById(userIds);
+        if (users.size() != userIds.size()) {
+            throw new DException("存在无效用户");
+        }
+        StatusEnum targetStatus = disabled ? StatusEnum.DISABLED : StatusEnum.NORMAL;
+        for (SysUser user : users) {
+            user.setDisabled(targetStatus);
+        }
+        sysUserRepository.saveAll(users);
+        publishUserEvent(PushInterfaceType.UPDATE_USER,
+                users.stream().map(SysUser::getId).collect(Collectors.toList()));
+    }
+
+    @Override
+    @Transactional
+    public void changeSortNo(Integer userId, Integer groupId, Integer sortNo) {
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("系统用户不存在");
+        }
+        // 排序号按组维度存储，必须落到具体的 (userId, groupId) 关联行
+        SysUserGroupRel rel = sysUserGroupRelRepository.findByUserIdAndGroupId(userId, groupId)
+                .orElseThrow(() -> new DException("用户不在该组，无法设置排序号"));
+        rel.setSortNo(sortNo);
+        sysUserGroupRelRepository.save(rel);
+    }
+
+    @Override
+    public Page<SysUserVo> list(SysUserQuery query, Pageable pageable) {
+        // 组上下文（选中具体组）：走原生 SQL 按「组内最小 sort_no」排序的专用分页，
+        // 规避 MySQL 的 DISTINCT+ORDER BY 限制以及 Hibernate 不支持 ORDER BY 标量子查询的限制。
+        if (query.getGroupId() != null) {
+            return listByGroup(query, pageable);
+        }
+        // 根节点 / 未选组：用 Specification 过滤，按主键 id 升序（聚簇索引顺序，无 filesort）。
+        Specification<SysUser> spec = buildSpecification(query);
+        Page<SysUser> page = sysUserRepository.findAll(spec, pageable);
+        return page.map(u -> convertToVo(u, null));
+    }
+
+    /**
+     * 组上下文列表：原生 SQL 分页。<br>
+     * 思路：INNER JOIN 关联表后按 user_id 聚合（GROUP BY u.id），用 MIN(sort_no) 作为排序键
+     * （NULLS LAST + sort_no 升序 + user_id 兜底升序）。GROUP BY 天然去重，既无 DISTINCT+ORDER BY 冲突，
+     * 也无 ORDER BY 标量子查询（Hibernate 5.6 不支持），分页/排序语义与「组内自定义排序」完全一致。
+     * 同页的 (userId, minSortNo) 一并查出，省去二次查询。
+     */
+    private Page<SysUserVo> listByGroup(SysUserQuery query, Pageable pageable) {
+        List<Integer> groupIds = resolveGroupIds(query.getGroupId(), query.getWithSub());
+        String name = StringUtils.isNotBlank(query.getName()) ? query.getName().trim() : null;
+        Integer disabledKey = query.getDisabled();
+
+        Page<Object[]> idPage = sysUserRepository.findGroupUserPage(
+                groupIds, name, disabledKey,
+                PageRequest.of(pageable.getPageNumber(), pageable.getPageSize()));
+
+        List<Object[]> rows = idPage.getContent();
+        if (rows.isEmpty()) {
+            return new PageImpl<>(Collections.emptyList(), pageable, 0);
+        }
+
+        // 保持 DB 返回的排序顺序，并记录每个用户的「组范围内最小 sort_no」
+        List<Integer> orderedIds = new ArrayList<>(rows.size());
+        Map<Integer, Integer> sortNoMap = new LinkedHashMap<>();
+        for (Object[] row : rows) {
+            Integer userId = ((Number) row[0]).intValue();
+            Object minObj = row[1]; // MIN(sort_no) 可能为空（该用户在组范围内均未设置排序号）
+            Integer sortNo = minObj == null ? null : ((Number) minObj).intValue();
+            orderedIds.add(userId);
+            sortNoMap.put(userId, sortNo);
+        }
+
+        // 按有序 ID 取实体（findAllById 返回顺序不可靠，需按 orderedIds 重排）
+        List<SysUser> users = sysUserRepository.findAllById(orderedIds);
+        Map<Integer, SysUser> userMap = users.stream()
+                .collect(Collectors.toMap(SysUser::getId, u -> u, (a, b) -> a));
+
+        List<SysUserVo> voList = new ArrayList<>(orderedIds.size());
+        for (Integer id : orderedIds) {
+            SysUser u = userMap.get(id);
+            if (u != null) {
+                voList.add(convertToVo(u, sortNoMap.get(id)));
+            }
+        }
+        return new PageImpl<>(voList, pageable, idPage.getTotalElements());
+    }
+
+    @Override
+    public List<Integer> findGroupIdsByUserId(Integer userId) {
+        return sysUserGroupRelRepository.findByUserId(userId).stream()
+                .map(SysUserGroupRel::getGroupId)
+                .collect(Collectors.toList());
+    }
+
+    @Override
+    @Transactional
+    public void changeGroups(List<Integer> userIds, List<Integer> groupIds) {
+        if (userIds == null || userIds.isEmpty()) {
+            throw new DException("待调整用户不能为空");
+        }
+        if (groupIds == null || groupIds.isEmpty()) {
+            throw new DException("请至少保留一个组");
+        }
+
+        List<SysUser> users = sysUserRepository.findAllById(userIds);
+        if (users.size() != userIds.size()) {
+            throw new DException("存在无效用户");
+        }
+        List<SysGroup> groups = sysGroupRepository.findAllById(groupIds);
+        if (groups.size() != groupIds.size()) {
+            throw new DException("存在无效分组");
+        }
+
+        LocalDateTime now = LocalDateTime.now();
+        for (Integer userId : userIds) {
+            sysUserGroupRelRepository.deleteByUserId(userId);
+            List<SysUserGroupRel> rels = new ArrayList<>(groupIds.size());
+            for (int i = 0; i < groupIds.size(); i++) {
+                SysUserGroupRel rel = new SysUserGroupRel();
+                rel.setUserId(userId);
+                rel.setGroupId(groupIds.get(i));
+                rel.setIsMain(i == 0 ? IS_MAIN : 0);
+                rel.setCreateTime(now);
+                rels.add(rel);
+            }
+            sysUserGroupRelRepository.saveAll(rels);
+        }
+        publishUserEvent(PushInterfaceType.UPDATE_USER, userIds);
+    }
+
+    @Override
+    @Transactional
+    public void moveUserWithinSchool(Integer userId, Integer groupId, Integer schoolId) {
+        if (userId == null) {
+            throw new DException("用户ID不能为空");
+        }
+        if (groupId == null) {
+            throw new DException("目标组ID不能为空");
+        }
+        // 公共锚点校验：schoolId 非空、存在、必须为学校组（复用 SysGroupService.assertSchoolId）
+        sysGroupService.assertSchoolId(schoolId);
+        if (!sysUserRepository.existsById(userId)) {
+            throw new DException("系统用户不存在");
+        }
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("目标分组不存在");
+        }
+
+        // 学校子树范围（含学校自身）：用户与目标组都必须落在此范围内，否则视为跨校移动
+        List<Integer> schoolScope = sysGroupService.listSelfAndDescendantIds(schoolId);
+
+        // ① 用户当前必须已在该学校内（至少一个组归属落在 schoolScope）
+        List<Integer> userGroupIds = findGroupIdsByUserId(userId);
+        boolean userInSchool = userGroupIds.stream().anyMatch(schoolScope::contains);
+        if (!userInSchool) {
+            throw new DException("用户不在该学校范围内，禁止跨校移动");
+        }
+        // ② 目标组必须也在该学校内
+        if (!schoolScope.contains(groupId)) {
+            throw new DException("目标组不属于该学校范围，禁止跨校移动");
+        }
+
+        // 复用覆盖式改组逻辑（目标设为主组）
+        changeGroups(Collections.singletonList(userId), Collections.singletonList(groupId));
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public BatchImportResult batchImport(MultipartFile file) {
+        BatchImportResult result = new BatchImportResult();
+        if (file == null || file.isEmpty()) {
+            throw new DException("上传文件不能为空");
+        }
+
+        Workbook workbook = null;
+        try {
+            workbook = WorkbookFactory.create(file.getInputStream());
+            Sheet sheet = workbook.getSheetAt(0);
+            int lastRowNum = sheet.getLastRowNum();
+
+            for (int i = 1; i <= lastRowNum; i++) {
+                Row row = sheet.getRow(i);
+                if (row == null || isBlankRow(row)) {
+                    continue;
+                }
+                try {
+                    SysUserRequest request = parseImportRow(row);
+                    createUser(request, false);
+                    result.addSuccess();
+                } catch (DException e) {
+                    result.addFail(i + 1, e.getMessage());
+                } catch (Exception e) {
+                    result.addFail(i + 1, "系统异常：" + e.getMessage());
+                }
+            }
+            // 仅统计实际参与解析的数据行（跳过空行），使 总数 = 成功 + 失败
+            result.setTotal(result.getSuccess() + result.getFail());
+        } catch (Exception e) {
+            throw new DException("文件读取失败：" + e.getMessage());
+        } finally {
+            if (workbook != null) {
+                try {
+                    workbook.close();
+                } catch (IOException ignored) {
+                    // 关闭资源失败不阻断主流程
+                }
+            }
+        }
+        return result;
+    }
+
+    // ===================== 导入模板下载 =====================
+
+    /**
+     * 导入/导出共用的列定义（顺序即 Excel 列顺序）。<br>
+     * 导入模板生成与（后续）导出复用同一套，避免两边列顺序/文案漂移。
+     */
+    private static final List<ImportColumnDef> IMPORT_COLUMN_DEFS = Arrays.asList(
+            new ImportColumnDef("groupName", "组名\n（不必填，供与id对应参考用）", 36, false, null),
+            new ImportColumnDef("groupId", "组id(必须)", 14, true, null),
+            new ImportColumnDef("account", "用户名(必须)", 20, true, null),
+            new ImportColumnDef("password", "密码\n(可选，\n默认Vzuk4Dp3)", 18, false, ""),
+            new ImportColumnDef("realName", "姓名(必须)", 16, true, null),
+            new ImportColumnDef("idcard", "身份证号(可选)", 22, false, null),
+            new ImportColumnDef("phone", "手机号(可选)", 16, false, null),
+            new ImportColumnDef("email", "email(可选)", 24, false, null),
+            new ImportColumnDef("nature", "用户性质\n(可选，默认普通用户\n组管理员2,\n普通用户0,\n导入不接受别的代码)", 24, false, "0"),
+            new ImportColumnDef("identity", "用户身份\n(1教师 2校领导 3学生 4家长)", 24, false, null),
+            new ImportColumnDef("gender", "性别(可选)", 12, false, null),
+            new ImportColumnDef("birthday", "生日(yyyy-MM-dd)(可选)", 22, false, null)
+    );
+
+    /** 组织树虚拟根 parentId（与 SysGroupService 约定一致）。 */
+    private static final int ROOT_PARENT_ID = 0;
+
+    /**
+     * 下载用户导入模板：以指定组（含）为根，将其自身及所有子孙组平铺为数据行，
+     * 仅填充「组名(路径)」与「组id」两列，其余列为空供用户填写。<br>
+     * 生成真实 .xlsx（POI XSSF），可被后端 BatchImport 正确解析（HTML 表格伪装 .xls 无法被 POI 解析）。
+     */
+    @Override
+    public void downloadImportTemplate(Integer groupId, HttpServletResponse response) throws IOException {
+        List<GroupPath> groups = buildImportGroupPaths(groupId);
+
+        XSSFWorkbook workbook = new XSSFWorkbook();
+        try {
+            XSSFSheet sheet = workbook.createSheet("用户导入模板");
+
+            // 表头样式：加粗、居中、自动换行、细边框
+            XSSFCellStyle headerStyle = workbook.createCellStyle();
+            XSSFFont headerFont = workbook.createFont();
+            headerFont.setBold(true);
+            headerStyle.setFont(headerFont);
+            headerStyle.setWrapText(true);
+            headerStyle.setVerticalAlignment(VerticalAlignment.CENTER);
+            headerStyle.setAlignment(HorizontalAlignment.CENTER);
+            headerStyle.setBorderTop(BorderStyle.THIN);
+            headerStyle.setBorderBottom(BorderStyle.THIN);
+            headerStyle.setBorderLeft(BorderStyle.THIN);
+            headerStyle.setBorderRight(BorderStyle.THIN);
+
+            XSSFRow headerRow = sheet.createRow(0);
+            for (int i = 0; i < IMPORT_COLUMN_DEFS.size(); i++) {
+                ImportColumnDef col = IMPORT_COLUMN_DEFS.get(i);
+                XSSFCell cell = headerRow.createCell(i);
+                cell.setCellValue(col.getTitle());
+                cell.setCellStyle(headerStyle);
+                sheet.setColumnWidth(i, col.getWidth() * 256);
+            }
+            headerRow.setHeightInPoints(64);
+
+            // 数据行：每个组一行，仅填 组名(路径) + 组id
+            int r = 1;
+            for (GroupPath g : groups) {
+                XSSFRow row = sheet.createRow(r++);
+                row.createCell(IDX_GROUP_NAME).setCellValue(g.getPath());
+                row.createCell(IDX_GROUP_ID).setCellValue(String.valueOf(g.getId()));
+            }
+
+            String filename = URLEncoder.encode("用户导入模板.xlsx", "UTF-8");
+            response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+            response.setHeader("Content-Disposition",
+                    "attachment; filename=\"" + filename + "\"; filename*=UTF-8''" + filename);
+            try (OutputStream out = response.getOutputStream()) {
+                workbook.write(out);
+            }
+        } finally {
+            workbook.close();
+        }
+    }
+
+    // ===================== 导出 =====================
+
+    /**
+     * 导出组下所有用户（含子组）为 Excel：与导入模板 {@code IMPORT_COLUMN_DEFS} 同构，末尾追加「用户id」列。<br>
+     * - 组名 / 组id：取每个用户实际所属的主组（isMain=1），与导入模板的「参考」列保持一致；<br>
+     * - 密码：数据库存的是 BCrypt 密文、不可逆，导出留空（再导入时退化为默认 Vzuk4Dp3）；<br>
+     * - 用户性质 nature：取 type 的 key（0普通 / 1超级管理员 / 2学校管理员）；<br>
+     * - 用户身份 identity：取 roles 数组第一个元素（系统角色枚举 SysRoleEnum key：1老师 2校领导 3学生 4家长 5局领导 6工作号 7管理员）。
+     */
+    @Override
+    public void exportUsers(Integer groupId, Integer withSub, String name, HttpServletResponse response) throws IOException {
+        // 1. 解析组范围（含子孙），复用与列表一致的 INNER JOIN 原生 SQL 取范围内用户（含超管豁免），不分页。
+        //    无组归属的用户被 INNER JOIN 天然排除；type=1 超管在 SQL 中显式豁免，永不导出。
+        List<Integer> groupIds = resolveGroupIds(groupId, withSub);
+        String nameKey = StringUtils.isNotBlank(name) ? name.trim() : null;
+        List<Integer> userIds = sysUserRepository.findGroupUserIds(groupIds, nameKey);
+        List<SysUser> users = userIds.isEmpty()
+                ? Collections.emptyList()
+                : sysUserRepository.findAllById(userIds).stream()
+                    .sorted(Comparator.comparing(SysUser::getId))
+                    .collect(Collectors.toList());
+
+        // 2. 批量取每个用户的主组（isMain=1），用于填充「组名 / 组id」参考列
+        Map<Integer, Integer> userMainGroup = resolveUserMainGroup(userIds);
+
+        // 3. 批量取组名
+        Map<Integer, String> groupNameMap = sysGroupRepository.findAllById(userMainGroup.values())
+                .stream().collect(Collectors.toMap(SysGroup::getId, SysGroup::getName));
+
+        // 4. 组装导出行
+        List<ExcelSysUser> rows = new ArrayList<>(users.size());
+        for (SysUser u : users) {
+            ExcelSysUser row = new ExcelSysUser();
+            Integer gid = userMainGroup.get(u.getId());
+            row.setGroupId(gid == null ? "" : String.valueOf(gid));
+            row.setGroupName(gid != null ? groupNameMap.get(gid) : null);
+            row.setAccount(u.getAccount());
+            row.setPassword(""); // 密文不可逆，导出留空
+            row.setRealName(u.getRealName());
+            row.setIdcard(u.getIdcard());
+            row.setPhone(u.getPhone());
+            row.setEmail(u.getEmail());
+            row.setNature(u.getType() == null ? null : u.getType().getKey());
+            row.setIdentity(u.getRoles() == null || u.getRoles().isEmpty() ? null : u.getRoles().get(0));
+            row.setGender(u.getGender());
+            row.setBirthday(u.getBirthday() == null ? "" : u.getBirthday().toString());
+            row.setUserId(u.getId());
+            rows.add(row);
+        }
+
+        // 5. 写出（HSSF .xls，与 EasyPoiUtils.downLoadExcel 的 .xls 兜底一致）
+        ExportParams exportParams = new ExportParams("组用户导出", "组用户");
+        exportParams.setType(ExcelType.HSSF);
+        Workbook workbook = ExcelExportUtil.exportExcel(exportParams, ExcelSysUser.class, rows);
+        EasyPoiUtils.downLoadExcel("组用户导出", response, workbook);
+    }
+
+    /**
+     * 批量解析 用户 -> 主组(groupId) 映射：优先取 isMain=1 的组，否则取第一个关联组。
+     */
+    private Map<Integer, Integer> resolveUserMainGroup(List<Integer> userIds) {
+        Map<Integer, Integer> mainGroup = new HashMap<>();
+        if (userIds.isEmpty()) {
+            return mainGroup;
+        }
+        List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByUserIdIn(userIds);
+        Map<Integer, List<SysUserGroupRel>> byUser = rels.stream()
+                .collect(Collectors.groupingBy(SysUserGroupRel::getUserId));
+        for (Map.Entry<Integer, List<SysUserGroupRel>> e : byUser.entrySet()) {
+            Integer gid = e.getValue().stream()
+                    .filter(r -> r.getIsMain() != null && r.getIsMain() == IS_MAIN)
+                    .map(SysUserGroupRel::getGroupId)
+                    .findFirst()
+                    .orElse(e.getValue().get(0).getGroupId());
+            mainGroup.put(e.getKey(), gid);
+        }
+        return mainGroup;
+    }
+
+    /**
+     * 收集导入模板所需的「组路径 + 组id」列表：以指定组为根做先序 DFS，
+     * 路径用「/」拼接（如 上海鸿育初级中学/教师组/校长室）。
+     */
+    private List<GroupPath> buildImportGroupPaths(Integer groupId) {
+        List<SysGroup> all = sysGroupRepository.findAll();
+        Map<Integer, SysGroup> byId = new HashMap<>();
+        Map<Integer, List<SysGroup>> childrenMap = new HashMap<>();
+        for (SysGroup g : all) {
+            byId.put(g.getId(), g);
+            Integer key = (g.getParentId() == null) ? ROOT_PARENT_ID : g.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(g);
+        }
+        // 同层级按 sort 升序、再按 id 升序，保证模板顺序稳定且与树展示一致
+        Comparator<SysGroup> order = (a, b) -> {
+            int sa = a.getSort() == null ? 999 : a.getSort();
+            int sb = b.getSort() == null ? 999 : b.getSort();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<SysGroup> siblings : childrenMap.values()) {
+            siblings.sort(order);
+        }
+
+        List<GroupPath> result = new ArrayList<>();
+        List<SysGroup> roots;
+        if (groupId != null && byId.containsKey(groupId)) {
+            roots = Collections.singletonList(byId.get(groupId));
+        } else {
+            roots = childrenMap.getOrDefault(ROOT_PARENT_ID, new ArrayList<>());
+        }
+        for (SysGroup root : roots) {
+            dfsGroup(root, "", childrenMap, result);
+        }
+        return result;
+    }
+
+    private void dfsGroup(SysGroup node, String parentPath,
+                          Map<Integer, List<SysGroup>> childrenMap, List<GroupPath> out) {
+        String path = parentPath.isEmpty() ? node.getName() : parentPath + "/" + node.getName();
+        GroupPath gp = new GroupPath();
+        gp.setId(node.getId());
+        gp.setPath(path);
+        out.add(gp);
+        List<SysGroup> children = childrenMap.get(node.getId());
+        if (children != null) {
+            for (SysGroup child : children) {
+                dfsGroup(child, path, childrenMap, out);
+            }
+        }
+    }
+
+    /** 导入/导出列定义（轻量 DTO）。 */
+    @lombok.Data
+    private static class ImportColumnDef {
+        private final String key;
+        private final String title;
+        private final int width;
+        private final boolean required;
+        private final String sample;
+    }
+
+    /** 模板所需的组路径节点。 */
+    @lombok.Data
+    private static class GroupPath {
+        private Integer id;
+        private String path;
+    }
+
+    // ===================== 私有工具 =====================
+
+    /**
+     * 组装「根节点 / 未选组」上下文的用户列表查询条件：关键字（账号/姓名/身份证模糊、手机号精确）+ 启用状态，
+     * 按主键 id 升序（聚簇索引顺序，无 filesort）。<br>
+     * 注意：选中具体组的上下文不走 Specification，改由 {@link #listByGroup} 用原生 SQL 分页，
+     * 以规避 MySQL 的 DISTINCT+ORDER BY 限制与 Hibernate 不支持 ORDER BY 标量子查询的限制。
+     */
+    private Specification<SysUser> buildSpecification(SysUserQuery query) {
+        return (root, cbQuery, cb) -> {
+            List<Predicate> predicates = new ArrayList<>();
+
+            // 根节点 / 未选组：无组上下文，按主键 id 升序
+            cbQuery.orderBy(cb.asc(root.get("id")));
+
+            // 关键字：账号/姓名/身份证模糊，手机号精确
+            if (StringUtils.isNotBlank(query.getName())) {
+                String keyword = query.getName().trim();
+                String like = "%" + keyword + "%";
+                Predicate byAccount = cb.like(root.get("account"), like);
+                Predicate byRealName = cb.like(root.get("realName"), like);
+                Predicate byIdcard = cb.like(root.get("idcard"), like);
+                Predicate byPhone = cb.equal(root.get("phone"), keyword);
+                predicates.add(cb.or(byAccount, byRealName, byIdcard, byPhone));
+            }
+
+            if (query.getDisabled() != null) {
+                // 实体 disabled 为 StatusEnum，查询条件需用枚举值比较（按 key 解析）
+                predicates.add(cb.equal(root.get("disabled"), IEnum.getByKey(StatusEnum.class, query.getDisabled())));
+            }
+            return cb.and(predicates.toArray(new Predicate[0]));
+        };
+    }
+
+    /**
+     * 依据 withSub 决定组范围：1=含所有子孙组，否则仅当前组。
+     */
+    private List<Integer> resolveGroupIds(Integer groupId, Integer withSub) {
+        if (withSub != null && withSub == 1) {
+            return sysGroupService.listSelfAndDescendantIds(groupId);
+        }
+        List<Integer> single = new ArrayList<>();
+        single.add(groupId);
+        return single;
+    }
+
+    @Override
+    public List<BoaRoleInfo> findUserRoles(Integer userId) {
+        if (userId == null) {
+            throw new DException("用户ID不能为空");
+        }
+        List<BoaRoleInfo> result = new ArrayList<>();
+        // 主归属组（学校/部门）上下文：schId/schName
+        Integer mainGroupId = null;
+        String mainGroupName = null;
+        List<SysUserGroupRel> groupRels = sysUserGroupRelRepository.findByUserId(userId);
+        for (SysUserGroupRel gr : groupRels) {
+            if (gr.getIsMain() != null && gr.getIsMain() == IS_MAIN) {
+                mainGroupId = gr.getGroupId();
+                break;
+            }
+        }
+        if (mainGroupId != null) {
+            SysGroup mainGroup = sysGroupRepository.findById(mainGroupId).orElse(null);
+            if (mainGroup != null) {
+                mainGroupName = mainGroup.getName();
+            }
+        }
+        // 业务角色：用户-角色关系 → 角色名称
+        List<SysUserAppRoleRel> rels = sysUserAppRoleRelRepository.findByUserId(userId);
+        for (SysUserAppRoleRel rel : rels) {
+            if (rel.getRoleId() == null) {
+                continue;
+            }
+            SysAppRole role = sysAppRoleRepository.findById(rel.getRoleId()).orElse(null);
+            if (role == null) {
+                continue;
+            }
+            BoaRoleInfo info = new BoaRoleInfo();
+            info.setRoleId(role.getId());
+            info.setRoleName(role.getName());
+            info.setSchId(mainGroupId);
+            info.setSchName(mainGroupName);
+            result.add(info);
+        }
+        return result;
+    }
+
+    @Override
+    @Transactional
+    public void changePassword(Integer userId, String oldPassword, String newPassword) {
+        SysUser entity = sysUserRepository.findById(userId)
+                .orElseThrow(() -> new DException("系统用户不存在"));
+        if (StringUtils.isBlank(oldPassword) || StringUtils.isBlank(newPassword)) {
+            throw new DException("新旧密码不能为空");
+        }
+        if (!passwordEncoder.matches(oldPassword, entity.getPassword())) {
+            throw new DException("原密码不正确");
+        }
+        String weakReason = ValidatorUtil.checkPasswordStrength(newPassword);
+        if (weakReason != null) {
+            throw new DException(weakReason);
+        }
+        entity.setPassword(passwordEncoder.encode(newPassword));
+        entity.setUpdateUser(SYSTEM_USER_ID);
+        sysUserRepository.save(entity);
+    }
+
+    /** 校验手机号与身份证（有值才校验）。 */
+    private void validateProfile(SysUserRequest request) {
+        if (StringUtils.isNotBlank(request.getPhone()) && !ValidatorUtil.isPhone(request.getPhone())) {
+            throw new DException("手机号格式不正确");
+        }
+        if (StringUtils.isNotBlank(request.getIdcard()) && !ValidatorUtil.isIdCard(request.getIdcard())) {
+            throw new DException("身份证号不合法");
+        }
+    }
+
+    /**
+     * 校验两次密码一致性与弱密码规则，通过后返回 BCrypt 密文。<br>
+     */
+    private String validateAndEncodePassword(String password, String confirmPassword) {
+        if (!StringUtils.equals(password, confirmPassword)) {
+            throw new DException("两次输入的密码不一致");
+        }
+        String weakReason = ValidatorUtil.checkPasswordStrength(password);
+        if (weakReason != null) {
+            throw new DException(weakReason);
+        }
+        return passwordEncoder.encode(password);
+    }
+
+    private SysUserVo convertToVo(SysUser entity) {
+        return convertToVo(entity, null);
+    }
+
+    private SysUserVo convertToVo(SysUser entity, Integer sortNo) {
+        SysUserVo vo = new SysUserVo();
+        BeanUtils.copyProperties(entity, vo);
+        // disabled 为枚举，需要单独映射为 key（与 GroupTypeEnum 的 type 处理一致）
+        vo.setDisabled(entity.getDisabled() == null ? null : entity.getDisabled().getKey());
+        // type 为枚举，同样映射为 key
+        vo.setType(entity.getType() == null ? null : entity.getType().getKey());
+        // 当前组维度的排序号；根节点 / 未选组时为 null
+        vo.setSortNo(sortNo);
+        return vo;
+    }
+
+    /**
+     * 推导用户类型（见 {@link UserTypeEnum}）：
+     *  - 内置超级管理员账号 -> 1 超级管理员；
+     *  - 其余账号若拥有 ADMIN(7) 角色 -> 2 学校管理员；
+     *  - 其他 -> 0 普通用户。
+     */
+    private UserTypeEnum resolveUserType(String account, List<Integer> roles) {
+        if (account != null && SUPER_ADMIN_ACCOUNTS.contains(account)) {
+            return UserTypeEnum.SUPER_ADMIN;
+        }
+        if (roles != null && roles.contains(SysRoleEnum.ADMIN.getKey())) {
+            return UserTypeEnum.SCHOOL_ADMIN;
+        }
+        return UserTypeEnum.NORMAL;
+    }
+
+    /** 校验并返回用户状态枚举；非法状态抛异常。 */
+    private StatusEnum resolveStatus(Integer status) {
+        StatusEnum statusEnum = IEnum.getByKey(StatusEnum.class, status);
+        if (statusEnum == null) {
+            throw new DException("用户状态不存在");
+        }
+        return statusEnum;
+    }
+
+    // ===================== 批量导入私有工具 =====================
+
+    private static final int IDX_GROUP_NAME = 0;
+    private static final int IDX_GROUP_ID = 1;
+    private static final int IDX_ACCOUNT = 2;
+    private static final int IDX_PASSWORD = 3;
+    private static final int IDX_REAL_NAME = 4;
+    private static final int IDX_IDCARD = 5;
+    private static final int IDX_PHONE = 6;
+    private static final int IDX_EMAIL = 7;
+    private static final int IDX_NATURE = 8;
+    private static final int IDX_IDENTITY = 9;
+    private static final int IDX_GENDER = 10;
+    private static final int IDX_BIRTHDAY = 11;
+
+    /**
+     * 解析 Excel 一行为 SysUserRequest。
+     * 列顺序与前端导入模板严格一致：
+     * 0组名 1组id 2用户名 3密码 4姓名 5身份证 6手机 7email 8用户性质 9用户身份 10性别 11生日。
+     */
+    private SysUserRequest parseImportRow(Row row) {
+        SysUserRequest request = new SysUserRequest();
+
+        Integer groupId = parseInteger(getCellString(row, IDX_GROUP_ID));
+        if (groupId == null) {
+            throw new DException("组id不能为空");
+        }
+        if (!sysGroupRepository.existsById(groupId)) {
+            throw new DException("组id【" + groupId + "】不存在");
+        }
+        request.setGroupId(groupId);
+
+        String account = getCellString(row, IDX_ACCOUNT);
+        if (StringUtils.isBlank(account)) {
+            throw new DException("用户名不能为空");
+        }
+        request.setAccount(account.trim());
+
+        String password = getCellString(row, IDX_PASSWORD);
+        if (StringUtils.isBlank(password)) {
+            password = "Vzuk4Dp3";
+        }
+        request.setPassword(password);
+        request.setConfirmPassword(password);
+
+        String realName = getCellString(row, IDX_REAL_NAME);
+        if (StringUtils.isBlank(realName)) {
+            throw new DException("姓名不能为空");
+        }
+        request.setRealName(realName.trim());
+
+        request.setIdcard(getCellString(row, IDX_IDCARD));
+        request.setPhone(getCellString(row, IDX_PHONE));
+        request.setEmail(getCellString(row, IDX_EMAIL));
+
+        Integer nature = parseInteger(getCellString(row, IDX_NATURE));
+        Integer identity = parseInteger(getCellString(row, IDX_IDENTITY));
+        request.setRoles(buildImportRoles(nature, identity));
+
+        request.setGender(parseGender(getCellString(row, IDX_GENDER)));
+        request.setBirthday(parseBirthday(row.getCell(IDX_BIRTHDAY)));
+
+        validateProfile(request);
+        return request;
+    }
+
+    /**
+     * 根据模板中的用户性质与用户身份构建 roles 列表。
+     * - 用户性质：0普通用户（不加管理员），2组管理员（加 ADMIN=7）；其他值视为非法。
+     * - 用户身份：1教师->TEACHER(1)，2校领导->SCHOOL_LEADER(2)，3学生->STUDENT(3)，4家长->PARENT(4)。
+     */
+    private List<Integer> buildImportRoles(Integer nature, Integer identity) {
+        Set<Integer> roleSet = new HashSet<>();
+        if (nature != null) {
+            if (nature == 2) {
+                roleSet.add(SysRoleEnum.ADMIN.getKey());
+            } else if (nature != 0) {
+                throw new DException("用户性质只能为 0 或 2");
+            }
+        }
+        if (identity != null) {
+            switch (identity) {
+                case 1:
+                    roleSet.add(SysRoleEnum.TEACHER.getKey());
+                    break;
+                case 2:
+                    roleSet.add(SysRoleEnum.SCHOOL_LEADER.getKey());
+                    break;
+                case 3:
+                    roleSet.add(SysRoleEnum.STUDENT.getKey());
+                    break;
+                case 4:
+                    roleSet.add(SysRoleEnum.PARENT.getKey());
+                    break;
+                default:
+                    throw new DException("用户身份只能为 1/2/3/4");
+            }
+        }
+        return new ArrayList<>(roleSet);
+    }
+
+    private Integer parseGender(String value) {
+        if (StringUtils.isBlank(value)) {
+            return null;
+        }
+        String v = value.trim();
+        if ("1".equals(v) || "男".equals(v)) {
+            return 1;
+        }
+        if ("0".equals(v) || "女".equals(v)) {
+            return 0;
+        }
+        throw new DException("性别只能为 0/女 或 1/男");
+    }
+
+    private LocalDate parseBirthday(Cell cell) {
+        if (cell == null) {
+            return null;
+        }
+        if (cell.getCellType() == CellType.NUMERIC && DateUtil.isCellDateFormatted(cell)) {
+            return cell.getDateCellValue().toInstant().atZone(ZoneId.systemDefault()).toLocalDate();
+        }
+        String value = getCellString(cell);
+        if (StringUtils.isBlank(value)) {
+            return null;
+        }
+        try {
+            return LocalDate.parse(value.trim());
+        } catch (Exception e) {
+            throw new DException("生日格式错误，请使用 yyyy-MM-dd");
+        }
+    }
+
+    private boolean isBlankRow(Row row) {
+        for (int i = 0; i <= IDX_BIRTHDAY; i++) {
+            if (StringUtils.isNotBlank(getCellString(row, i))) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private String getCellString(Row row, int cellIndex) {
+        Cell cell = row.getCell(cellIndex);
+        if (cell == null) {
+            return "";
+        }
+        return getCellString(cell);
+    }
+
+    private String getCellString(Cell cell) {
+        switch (cell.getCellType()) {
+            case STRING:
+                return StringUtils.trim(cell.getStringCellValue());
+            case NUMERIC:
+                if (DateUtil.isCellDateFormatted(cell)) {
+                    return cell.getDateCellValue().toInstant().atZone(ZoneId.systemDefault()).toLocalDate().toString();
+                }
+                double numeric = cell.getNumericCellValue();
+                if (numeric == Math.floor(numeric)) {
+                    return String.valueOf((long) numeric);
+                }
+                return String.valueOf(numeric);
+            case BOOLEAN:
+                return String.valueOf(cell.getBooleanCellValue());
+            case FORMULA:
+                try {
+                    return String.valueOf(cell.getNumericCellValue());
+                } catch (Exception e) {
+                    return cell.getStringCellValue();
+                }
+            default:
+                return "";
+        }
+    }
+
+    private Integer parseInteger(String value) {
+        if (StringUtils.isBlank(value)) {
+            return null;
+        }
+        try {
+            return Integer.valueOf(value.trim());
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    // ===================== 推送事件 =====================
+
+    private void publishUserEvent(PushInterfaceType type, Integer userId) {
+        DataSyncEvent e = new DataSyncEvent();
+        e.setType(type);
+        e.setUserIds(Collections.singletonList(userId));
+        e.setSourceAppKey(CallerAppContext.getAppKey());
+        eventPublisher.publishEvent(e);
+    }
+
+    private void publishUserEvent(PushInterfaceType type, List<Integer> userIds) {
+        if (userIds == null || userIds.isEmpty()) {
+            return;
+        }
+        DataSyncEvent e = new DataSyncEvent();
+        e.setType(type);
+        e.setUserIds(userIds);
+        e.setSourceAppKey(CallerAppContext.getAppKey());
+        eventPublisher.publishEvent(e);
+    }
+
+    /** 组维度的用户事件（如 DELETE_USER=解除组关系），额外携带组 id */
+    private void publishUserEvent(PushInterfaceType type, List<Integer> userIds, Integer groupId) {
+        if (userIds == null || userIds.isEmpty()) {
+            return;
+        }
+        DataSyncEvent e = new DataSyncEvent();
+        e.setType(type);
+        e.setUserIds(userIds);
+        e.setGroupId(groupId);
+        e.setSourceAppKey(CallerAppContext.getAppKey());
+        eventPublisher.publishEvent(e);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/impl/UserCenterService.java b/src/main/java/com/yunhai/userbase/service/impl/UserCenterService.java
new file mode 100644
index 0000000..f6c5949
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/impl/UserCenterService.java
@@ -0,0 +1,206 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.platform.utils.model.BoaGroup;
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserCurrentRole;
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import com.yunhai.userbase.entity.SysUserRoleRel;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.userbase.enums.StatusEnum;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import com.yunhai.userbase.repository.SysUserRoleRelRepository;
+import com.yunhai.userbase.repository.SysUserCurrentRoleRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * 用户中心核心服务：把 UserBase 自身的 sys_user / sys_group 组装成基础平台统一的
+ * {@link BoaUser}（含部门/学校/教育局多级组织）。<br><br>
+ * 这是「UserBase 由子应用升级为用户中心」的关键：平台侧 {@code UserDetailsProvider}
+ * （{@code UserBaseUserDetailsProvider}）与开放接口（{@code OpenBaseController}）都复用本服务，
+ * 保证 CAS 会话流与签名开放流返回的 BoaUser 结构完全一致。
+ */
+@Service
+public class UserCenterService {
+
+    /** 虚拟根节点 parentId（与 SysGroupService 约定一致）。 */
+    private static final int ROOT_PARENT_ID = 0;
+
+    @Autowired
+    private SysUserRepository sysUserRepository;
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+    @Autowired
+    private SysUserRoleRelRepository sysUserRoleRelRepository;
+    @Autowired
+    private SysUserCurrentRoleRepository sysUserCurrentRoleRepository;
+
+    public BoaUser getUserInfoWithDeptByAccount(String account) {
+        if (account == null) {
+            return null;
+        }
+        return resolve(sysUserRepository.findByAccount(account.trim()));
+    }
+
+    public BoaUser getUserInfoWithDeptByPhone(String phone) {
+        if (phone == null) {
+            return null;
+        }
+        return resolve(sysUserRepository.findByPhone(phone.trim()));
+    }
+
+    public BoaUser getUserInfoWithDeptById(Integer id) {
+        if (id == null) {
+            return null;
+        }
+        return resolve(sysUserRepository.findById(id).orElse(null));
+    }
+
+    private BoaUser resolve(SysUser user) {
+        if (user == null) {
+            return null;
+        }
+        BoaUser boa = new BoaUser();
+        boa.setId(user.getId());
+        boa.setAccount(user.getAccount());
+        boa.setName(user.getRealName());
+        boa.setIdcard(user.getIdcard());
+        boa.setPhone(user.getPhone());
+        boa.setProfilePicture(user.getProfilePicture());
+        // 用户表无 email / gender 列，置 null
+        boa.setEmail(null);
+        boa.setGender(null);
+        boa.setType(user.getType() != null ? user.getType().getKey() : null);
+        // 状态语义对齐：本表 disabled(NORMAL=0 正常 / DISABLED=1 禁用) -> BoaUser(1 正常 / 0 禁用)
+        boa.setStatus(user.getDisabled() == StatusEnum.NORMAL ? 1 : 0);
+        // 角色列表：从 sys_user_role_rel（平台身份角色权威源）取正常态 roleId 去重，不再读 sys_user.roles
+        List<Integer> roleIds = sysUserRoleRelRepository
+                .findDistinctRoleIdsByUserIdAndStatus(user.getId(), StatusEnum.NORMAL);
+        boa.setRoleIds(roleIds);
+
+        List<BoaGroup> groups = buildGroups(user.getId());
+        boa.setGroups(groups);
+        // 部门/教育局：仍从组织链推导（与主组/区域组语义绑定）
+        deriveOrg(groups, boa);
+        // 学校/当前激活身份/可选学校：从身份关联表推导（school 语义=当前激活学校）
+        deriveIdentity(user.getId(), boa);
+        return boa;
+    }
+
+    /**
+     * 组装用户组织链：取主归属组（isMain=1，否则首个关联），沿 parentId 向上回溯到根，
+     * 顺序为「主组 -> ... -> 根方向」（近 -> 远）。
+     */
+    private List<BoaGroup> buildGroups(Integer userId) {
+        List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByUserId(userId);
+        if (rels == null || rels.isEmpty()) {
+            return new ArrayList<>();
+        }
+        SysUserGroupRel mainRel = rels.stream()
+                .filter(r -> r.getIsMain() != null && r.getIsMain() == 1)
+                .findFirst()
+                .orElse(rels.get(0));
+        Integer groupId = mainRel.getGroupId();
+        if (groupId == null) {
+            return new ArrayList<>();
+        }
+
+        List<BoaGroup> chain = new ArrayList<>();
+        Integer cursor = groupId;
+        Set<Integer> seen = new HashSet<>();
+        while (cursor != null && cursor != ROOT_PARENT_ID && seen.add(cursor)) {
+            SysGroup g = sysGroupRepository.findById(cursor).orElse(null);
+            if (g == null) {
+                break;
+            }
+            BoaGroup bg = new BoaGroup();
+            bg.setId(g.getId());
+            bg.setName(g.getName());
+            bg.setParentId(g.getParentId());
+            bg.setType(g.getType() != null ? g.getType().getKey() : null);
+            chain.add(bg);
+            cursor = g.getParentId();
+        }
+        return chain;
+    }
+
+    /** 从组织链推导 school / bureau / dept。 */
+    private void deriveOrg(List<BoaGroup> groups, BoaUser boa) {
+        if (groups == null || groups.isEmpty()) {
+            return;
+        }
+        BoaGroup school = null;
+        BoaGroup bureau = null;
+        for (BoaGroup g : groups) {
+            if (school == null && Objects.equals(g.getType(), GroupTypeEnum.SCHOOL_GROUP.getKey())) {
+                school = g;
+            }
+            if (bureau == null && Objects.equals(g.getType(), GroupTypeEnum.AREA_GROUP.getKey())) {
+                bureau = g;
+            }
+        }
+        boa.setSchool(school);
+        boa.setBureau(bureau);
+        // 部门：主组（链的近端第一个）；若主组本身为学校，则部门即学校
+        boa.setDept(groups.get(0));
+    }
+
+    /**
+     * 从身份关联推导当前激活身份与可选学校。school 字段语义=当前激活学校：<br>
+     * ① 优先读 {@code sys_user_current_role}（用户主动切换后的状态）；<br>
+     * ② 无切换记录时兜底取 {@code sys_user_role_rel.is_main=1} 的整条记录（保证是合法存在的身份，
+     *    避免「主组+主角色」组合出 B 学校老师的非法身份）；<br>
+     * ③ schools：用户在全部学校下的可选身份去重 schoolId（>0）集合。
+     */
+    private void deriveIdentity(Integer userId, BoaUser boa) {
+        Integer currentSchoolId = null;
+        String currentSchoolName = null;
+
+        SysUserCurrentRole current = sysUserCurrentRoleRepository.findByUserId(userId).orElse(null);
+        if (current != null && current.getRoleId() != null) {
+            currentSchoolId = current.getSchoolId();
+            currentSchoolName = current.getSchoolName();
+        } else {
+            // 兜底：直接取主身份整条记录（isMain=1），而不是「主组+主角色」组合
+            SysUserRoleRel mainRel = sysUserRoleRelRepository
+                    .findByUserIdAndIsMain(userId, 1).orElse(null);
+            if (mainRel != null) {
+                currentSchoolId = mainRel.getSchoolId();
+                if (currentSchoolId != null && currentSchoolId > 0) {
+                    SysGroup sch = sysGroupRepository.findById(currentSchoolId).orElse(null);
+                    currentSchoolName = sch != null ? sch.getName() : null;
+                }
+            }
+        }
+
+        if (currentSchoolId != null && currentSchoolId > 0) {
+            boa.setSchool(toBoaGroup(currentSchoolId, currentSchoolName));
+        }
+    }
+
+    /** 组装一个 BoaGroup（仅填充 id 与 name；name 为 null 时回源查 sys_group） */
+    private BoaGroup toBoaGroup(Integer groupId, String fallbackName) {
+        BoaGroup bg = new BoaGroup();
+        bg.setId(groupId);
+        if (fallbackName != null) {
+            bg.setName(fallbackName);
+        } else {
+            SysGroup g = sysGroupRepository.findById(groupId).orElse(null);
+            bg.setName(g != null ? g.getName() : null);
+        }
+        return bg;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/GroupScopeHelper.java b/src/main/java/com/yunhai/userbase/service/push/GroupScopeHelper.java
new file mode 100644
index 0000000..a708f08
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/GroupScopeHelper.java
@@ -0,0 +1,60 @@
+package com.yunhai.userbase.service.push;
+
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.service.ISysGroupService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 学校范围辅助：把「学校组」语义落地为可计算的范围。<br><br>
+ * 语义（已与用户确认）：一个组属于学校 S ⇔ 该组是学校组 S 本身，或 S 的任意后代子节点。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Service
+public class GroupScopeHelper {
+
+    private static final int ROOT_PARENT_ID = 0;
+
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+    @Autowired
+    private ISysGroupService sysGroupService;
+
+    /**
+     * 计算组所属学校范围 id：自身为学校组则取自身，否则沿 parentId 向上找最近的 SCHOOL_GROUP。
+     * 无学校祖先返回 null（属于教育云中心直属，全局）。
+     */
+    public Integer resolveSchoolId(Integer groupId) {
+        if (groupId == null) {
+            return null;
+        }
+        SysGroup g = sysGroupRepository.findById(groupId).orElse(null);
+        while (g != null) {
+            if (g.getType() == GroupTypeEnum.SCHOOL_GROUP) {
+                return g.getId();
+            }
+            if (g.getParentId() == null || g.getParentId() == ROOT_PARENT_ID) {
+                break;
+            }
+            g = sysGroupRepository.findById(g.getParentId()).orElse(null);
+        }
+        return null;
+    }
+
+    /**
+     * 学校范围 = 学校组自身 + 全部子孙（复用 SysGroupService.listSelfAndDescendantIds）。
+     */
+    public List<Integer> getSchoolScopeGroupIds(Integer schoolId) {
+        if (schoolId == null) {
+            return Collections.emptyList();
+        }
+        return sysGroupService.listSelfAndDescendantIds(schoolId);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/PushConsumer.java b/src/main/java/com/yunhai/userbase/service/push/PushConsumer.java
new file mode 100644
index 0000000..bb84f7f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/PushConsumer.java
@@ -0,0 +1,159 @@
+package com.yunhai.userbase.service.push;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.rabbitmq.client.Channel;
+import com.yunhai.userbase.config.PushMqConfig;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.push.PushRecordEntity;
+import com.yunhai.userbase.model.push.PushTaskMessage;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.PushRecordRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.amqp.rabbit.annotation.RabbitListener;
+import org.springframework.amqp.rabbit.core.RabbitTemplate;
+import org.springframework.amqp.support.AmqpHeaders;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.messaging.handler.annotation.Header;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestTemplate;
+
+import java.io.IOException;
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * 推送消费者（订阅方调用方）：<br>
+ * 从 push.main 串行消费，手动 ack；POST 给订阅方 Webhook，按文档契约带 t/sign 头；<br>
+ * 每次尝试均落 push_record；失败应用层自管重试（共 3 次），耗尽进死信队列。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Slf4j
+@Service
+public class PushConsumer {
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+    @Autowired
+    private PushRecordRepository pushRecordRepository;
+    @Autowired
+    @Qualifier("pushRabbitTemplate")
+    private RabbitTemplate pushRabbitTemplate;
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @RabbitListener(queues = PushMqConfig.QUEUE_MAIN, containerFactory = "pushListenerContainerFactory")
+    public void onMessage(PushTaskMessage msg, Channel channel,
+                          @Header(AmqpHeaders.DELIVERY_TAG) long deliveryTag) {
+        long start = System.currentTimeMillis();
+        String url = null;
+        Integer httpStatus = null;
+        Integer respCode = null;
+        String respMsg = null;
+        boolean ok = false;
+        String appName = null;
+        try {
+            ApplicationInfo app = applicationInfoRepository.findByAppKey(msg.getAppKey());
+            if (app == null) {
+                respMsg = "订阅方不存在 appKey=" + msg.getAppKey();
+            } else {
+                appName = app.getName();
+                url = joinUrl(app.getPushBaseUrl(), msg.getInterfacePath());
+                HttpHeaders headers = new HttpHeaders();
+                headers.setContentType(MediaType.APPLICATION_JSON);
+                headers.set("t", msg.getT());
+                headers.set("sign", msg.getSign());
+                int readTimeout = msg.getInterfacePath().contains("Sync") ? 60000 : 10000;
+                SimpleClientHttpRequestFactory rf = new SimpleClientHttpRequestFactory();
+                rf.setConnectTimeout(5000);
+                rf.setReadTimeout(readTimeout);
+                RestTemplate rt = new RestTemplate(rf);
+                ResponseEntity<String> resp = rt.postForEntity(url, new HttpEntity<>(msg.getBody(), headers), String.class);
+                httpStatus = resp.getStatusCodeValue();
+                String body = resp.getBody();
+                try {
+                    JsonNode node = objectMapper.readTree(body);
+                    respCode = node.path("code").asInt();
+                    respMsg = node.path("msg").asText();
+                } catch (Exception e) {
+                    respMsg = body;
+                }
+                ok = (httpStatus != null && httpStatus == 200 && respCode != null && respCode == 0);
+            }
+        } catch (Exception e) {
+            respMsg = e.getMessage();
+        } finally {
+            long cost = System.currentTimeMillis() - start;
+            try {
+                PushRecordEntity rec = new PushRecordEntity();
+                rec.setSubscriberAppKey(msg.getAppKey());
+                rec.setAppName(appName);
+                rec.setInterfacePath(msg.getInterfacePath());
+                rec.setInterfaceLabel(msg.getInterfaceLabel());
+                rec.setRequestUrl(url == null ? "" : url);
+                rec.setPayload(msg.getBody());
+                rec.setSignT(msg.getT());
+                rec.setHttpStatus(httpStatus);
+                rec.setRespCode(respCode);
+                rec.setRespMsg(truncate(respMsg, 500));
+                rec.setSuccess(ok ? 1 : 0);
+                rec.setAttemptNo(msg.getAttemptNo());
+                rec.setCostMs((int) cost);
+                rec.setTriggerType(msg.getTriggerType());
+                pushRecordRepository.save(rec);
+            } catch (Exception dbErr) {
+                log.error("[推送] 落库失败", dbErr);
+            }
+            try {
+                if (ok) {
+                    channel.basicAck(deliveryTag, false);
+                } else if (msg.getAttemptNo() < 3) {
+                    PushTaskMessage retry = new PushTaskMessage(msg.getAppKey(), msg.getInterfacePath(),
+                            msg.getInterfaceLabel(), msg.getBody(), msg.getT(), msg.getSign(),
+                            msg.getAttemptNo() + 1, msg.getTriggerType());
+                    pushRabbitTemplate.convertAndSend(PushMqConfig.EXCHANGE_TOPIC, msg.getInterfacePath(), retry);
+                    channel.basicAck(deliveryTag, false);
+                } else {
+                    // 重试耗尽：进死信队列归档
+                    channel.basicNack(deliveryTag, false, false);
+                }
+            } catch (IOException io) {
+                log.error("[推送] ACK 失败", io);
+            }
+        }
+    }
+
+    private static String truncate(String s, int max) {
+        if (s == null) {
+            return null;
+        }
+        return s.length() > max ? s.substring(0, max) : s;
+    }
+
+    private static String joinUrl(String base, String path) {
+        if (base == null) {
+            return path;
+        }
+        String b = base.endsWith("/") ? base : base + "/";
+        String p = path.startsWith("/") ? path.substring(1) : path;
+        return b + p;
+    }
+
+    /** 供 {@link PushDispatcher} 共享的 URL 拼接（保持语义一致）。 */
+    static String joinUrlForTest(String base, String path) {
+        return joinUrl(base, path);
+    }
+
+    @SuppressWarnings("unused")
+    private static Map<String, Object> unused() {
+        return Collections.emptyMap();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/PushDispatcher.java b/src/main/java/com/yunhai/userbase/service/push/PushDispatcher.java
new file mode 100644
index 0000000..3a56ddb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/PushDispatcher.java
@@ -0,0 +1,394 @@
+package com.yunhai.userbase.service.push;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.config.PushMqConfig;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import com.yunhai.userbase.event.DataSyncEvent;
+import com.yunhai.userbase.model.push.PushInterfaceType;
+import com.yunhai.userbase.model.push.PushTaskMessage;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.amqp.rabbit.core.RabbitTemplate;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.event.TransactionalEventListener;
+import org.springframework.transaction.event.TransactionPhase;
+
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * 推送分发器（生产方）：<br>
+ * ① 自动触发：监听 {@link DataSyncEvent}（AFTER_COMMIT），遍历所有开启推送的订阅方，按配置过滤后投递 MQ；<br>
+ * ② 手动测试：{@link #dispatchManual} 供测试推送页调用。<br><br>
+ * 签名在此处由基础平台计算一次（HMAC-SHA256(业务JSON+t, secret)），消息携带 t/sign，消费方原样 POST。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Slf4j
+@Service
+public class PushDispatcher {
+
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+    @Autowired
+    private SysUserRepository sysUserRepository;
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+    @Autowired
+    private GroupScopeHelper groupScopeHelper;
+    @Autowired
+    private PushPayloadAssembler pushPayloadAssembler;
+    @Autowired
+    private ObjectMapper objectMapper;
+    @Autowired
+    @Qualifier("pushRabbitTemplate")
+    private RabbitTemplate pushRabbitTemplate;
+
+    // ===================== 自动触发（AFTER_COMMIT，推送失败不影响主业务） =====================
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    public void onDataSync(DataSyncEvent event) {
+        try {
+            PushInterfaceType type = event.getType();
+            if (type == null) {
+                return;
+            }
+            // 删除类事件：实体已从库中删除，AFTER_COMMIT 阶段重载必然为空，
+            // 直接用事件携带的 id 构建删除体；删除幂等，绕过范围过滤全量投递给已开启删除事件的订阅方
+            if (type == PushInterfaceType.DELETE_GROUP || type == PushInterfaceType.DELETE_USER) {
+                List<Integer> ids = (type == PushInterfaceType.DELETE_GROUP)
+                        ? event.getGroupIds() : event.getUserIds();
+                Integer groupId = event.getGroupId();
+                for (ApplicationInfo app : applicationInfoRepository.findByPushEnabled(1)) {
+                    // 来源排除：应用自己触发的变更（如 oapi 写接口）不回推给自己，避免收到自己的回声
+                    if (event.getSourceAppKey() != null && event.getSourceAppKey().equals(app.getAppKey())) {
+                        continue;
+                    }
+                    dispatchDeleteToOne(app, type, ids, groupId, "auto");
+                }
+                return;
+            }
+            List<SysGroup> groups = (event.getGroupIds() != null && !event.getGroupIds().isEmpty())
+                    ? sysGroupRepository.findAllById(event.getGroupIds()) : Collections.emptyList();
+            List<SysUser> users = (event.getUserIds() != null && !event.getUserIds().isEmpty())
+                    ? sysUserRepository.findAllById(event.getUserIds()) : Collections.emptyList();
+            // 全量同步需要全部数据
+            if (type == PushInterfaceType.SYNC_GROUP) {
+                groups = sysGroupRepository.findAll();
+            }
+            if (type == PushInterfaceType.SYNC_USER) {
+                users = sysUserRepository.findAll();
+            }
+            for (ApplicationInfo app : applicationInfoRepository.findByPushEnabled(1)) {
+                // 来源排除：应用自己触发的变更（如 oapi 写接口）不回推给自己，避免收到自己的回声
+                if (event.getSourceAppKey() != null && event.getSourceAppKey().equals(app.getAppKey())) {
+                    continue;
+                }
+                dispatchToOne(app, type, groups, users, "auto", false);
+            }
+        } catch (Exception e) {
+            log.error("[推送] 分发失败（不影响主业务）", e);
+        }
+    }
+
+    // ===================== 手动测试 =====================
+
+    public void dispatchManual(Integer appId, String interfacePath, List<Integer> targetIds) {
+        ApplicationInfo app = applicationInfoRepository.findById(appId).orElse(null);
+        if (app == null) {
+            throw new DException("应用不存在");
+        }
+        PushInterfaceType type = PushInterfaceType.getByPath(interfacePath);
+        if (type == null) {
+            throw new DException("不支持的接口路径：" + interfacePath);
+        }
+        List<SysGroup> groups = Collections.emptyList();
+        List<SysUser> users = Collections.emptyList();
+        if (type == PushInterfaceType.SYNC_GROUP) {
+            groups = sysGroupRepository.findAll();
+        } else if (type == PushInterfaceType.SYNC_USER) {
+            users = sysUserRepository.findAll();
+        } else if (type.isGroup()) {
+            groups = (targetIds == null || targetIds.isEmpty())
+                    ? sysGroupRepository.findAll() : sysGroupRepository.findAllById(targetIds);
+        } else {
+            users = (targetIds == null || targetIds.isEmpty())
+                    ? sysUserRepository.findAll() : sysUserRepository.findAllById(targetIds);
+        }
+        // 手动全量同步（SyncGroup/SyncUser）属于管理员主动触发，绕过订阅接口开关，确保一定能投递
+        boolean force = (type == PushInterfaceType.SYNC_GROUP || type == PushInterfaceType.SYNC_USER);
+        dispatchToOne(app, type, groups, users, "manual", force);
+    }
+
+    /**
+     * 生成一次推送请求的预览（URL / 头 / 体），供测试推送页展示。<br>
+     * 签名在服务端用 secret 计算，前端不持有密钥；实际投递仍走 {@link #dispatchManual} → MQ。
+     */
+    public Map<String, Object> previewManual(Integer appId, String interfacePath, List<Integer> targetIds) {
+        ApplicationInfo app = applicationInfoRepository.findById(appId).orElse(null);
+        if (app == null) {
+            throw new DException("应用不存在");
+        }
+        PushInterfaceType type = PushInterfaceType.getByPath(interfacePath);
+        if (type == null) {
+            throw new DException("不支持的接口路径：" + interfacePath);
+        }
+        List<SysGroup> groups = Collections.emptyList();
+        List<SysUser> users = Collections.emptyList();
+        if (type == PushInterfaceType.SYNC_GROUP) {
+            groups = sysGroupRepository.findAll();
+        } else if (type == PushInterfaceType.SYNC_USER) {
+            users = sysUserRepository.findAll();
+        } else if (type.isGroup()) {
+            groups = (targetIds == null || targetIds.isEmpty())
+                    ? sysGroupRepository.findAll() : sysGroupRepository.findAllById(targetIds);
+        } else {
+            users = (targetIds == null || targetIds.isEmpty())
+                    ? sysUserRepository.findAll() : sysUserRepository.findAllById(targetIds);
+        }
+        List<Object> bodies = buildBodies(type, groups, users);
+        if (bodies.isEmpty()) {
+            Map<String, Object> empty = new LinkedHashMap<>();
+            empty.put("url", joinUrl(app.getPushBaseUrl(), type.getPath()));
+            empty.put("method", "POST");
+            empty.put("headers", buildHeaders("", ""));
+            empty.put("body", "{}");
+            empty.put("batch", 0);
+            return empty;
+        }
+        try {
+            String body = objectMapper.writeValueAsString(bodies.get(0));
+            String t = String.valueOf(System.currentTimeMillis());
+            String secret = (app.getPushSecret() != null && !app.getPushSecret().isEmpty())
+                    ? app.getPushSecret() : app.getAppSecret();
+            String sign = PushSigner.sign(body, secret, t);
+            Map<String, Object> preview = new LinkedHashMap<>();
+            preview.put("url", joinUrl(app.getPushBaseUrl(), type.getPath()));
+            preview.put("method", "POST");
+            preview.put("headers", buildHeaders(t, sign));
+            preview.put("body", body);
+            preview.put("batch", bodies.size());
+            return preview;
+        } catch (Exception e) {
+            throw new DException("预览生成失败：" + e.getMessage());
+        }
+    }
+
+    private static Map<String, String> buildHeaders(String t, String sign) {
+        Map<String, String> headers = new LinkedHashMap<>();
+        headers.put("Content-Type", "application/json");
+        headers.put("t", t);
+        headers.put("sign", sign);
+        return headers;
+    }
+
+    // ===================== 核心 =====================
+
+    /** 删除类事件专用投递：跳过 DB 重载与范围过滤，直接用事件携带的 id 构建删除体。 */
+    private void dispatchDeleteToOne(ApplicationInfo app, PushInterfaceType type, List<Integer> ids,
+                                     Integer groupId, String triggerType) {
+        if (app.getPushEnabled() == null || app.getPushEnabled() != 1) {
+            return;
+        }
+        // 仍校验订阅方是否勾选了删除接口
+        if (!containsEventType(app.getPushEventTypes(), type.getPath())) {
+            return;
+        }
+        if (ids == null || ids.isEmpty()) {
+            return;
+        }
+        for (Object bodyObj : buildDeleteBodies(type, ids, groupId)) {
+            sendMessage(app, type, bodyObj, triggerType);
+        }
+    }
+
+    /**
+     * 删除类接口 body 形态：<br>
+     * DELETE_GROUP：每个 id 一条 {@code {id}}；<br>
+     * DELETE_USER：因是「解除组关系」，每行携带 {@code {userId, groupId}}（整体一条数组）。
+     */
+    private List<Object> buildDeleteBodies(PushInterfaceType type, List<Integer> ids, Integer groupId) {
+        if (type == PushInterfaceType.DELETE_GROUP) {
+            return ids.stream()
+                    .map(id -> Collections.singletonMap("id", id))
+                    .collect(Collectors.toList());
+        }
+        if (type == PushInterfaceType.DELETE_USER) {
+            // 单组维度批量移出，所有 userId 共享同一 groupId
+            return ids.stream()
+                    .map(userId -> {
+                        Map<String, Integer> item = new LinkedHashMap<>();
+                        item.put("userId", userId);
+                        item.put("groupId", groupId);
+                        return item;
+                    })
+                    .collect(Collectors.toList());
+        }
+        return Collections.emptyList();
+    }
+
+    private void dispatchToOne(ApplicationInfo app, PushInterfaceType type,
+                               List<SysGroup> groups, List<SysUser> users, String triggerType, boolean force) {
+        if (app.getPushEnabled() == null || app.getPushEnabled() != 1) {
+            return;
+        }
+        // 手动全量同步为管理员主动触发，绕过订阅接口开关（force=true）；
+        // 自动/增量事件仍要求订阅方在 pushEventTypes 中勾选对应接口。
+        if (!force && !containsEventType(app.getPushEventTypes(), type.getPath())) {
+            return;
+        }
+        boolean isFull = (type == PushInterfaceType.SYNC_GROUP || type == PushInterfaceType.SYNC_USER);
+        List<SysGroup> fGroups = (type.isGroup() && !isFull) ? filterGroups(groups, app) : groups;
+        List<SysUser> fUsers = (type.isUser() && !isFull) ? filterUsers(users, app) : users;
+
+        // 增量事件无匹配则跳过（全量即使为空也照常投递，供订阅方清空）
+        if (!isFull) {
+            if (type.isGroup() && fGroups.isEmpty()) {
+                return;
+            }
+            if (type.isUser() && fUsers.isEmpty()) {
+                return;
+            }
+        }
+
+        for (Object bodyObj : buildBodies(type, fGroups, fUsers)) {
+            sendMessage(app, type, bodyObj, triggerType);
+        }
+    }
+
+    /** 按接口形状构建待发送 body（删除类接口 body 形态与增改不同）。 */
+    private List<Object> buildBodies(PushInterfaceType type, List<SysGroup> groups, List<SysUser> users) {
+        switch (type) {
+            case SYNC_GROUP:
+                return Collections.singletonList(pushPayloadAssembler.buildFullGroupTree());
+            case ADD_GROUP:
+            case UPDATE_GROUP:
+                return Collections.singletonList(pushPayloadAssembler.toGroupDtoList(groups));
+            case DELETE_GROUP:
+                // 文档 3.5：json 对象 {id}；每个组独立一条消息
+                return groups.stream()
+                        .map(g -> Collections.singletonMap("id", g.getId()))
+                        .collect(Collectors.toList());
+            case SYNC_USER:
+                return Collections.singletonList(pushPayloadAssembler.toUserDtoList(users));
+            case ADD_USER:
+            case UPDATE_USER:
+                return Collections.singletonList(pushPayloadAssembler.toUserDtoList(users));
+            case DELETE_USER:
+                // 文档 3.8：json 数组 [id,...]
+                return Collections.singletonList(users.stream().map(SysUser::getId).collect(Collectors.toList()));
+            default:
+                return Collections.emptyList();
+        }
+    }
+
+    private void sendMessage(ApplicationInfo app, PushInterfaceType type, Object bodyObj, String triggerType) {
+        try {
+            String body = objectMapper.writeValueAsString(bodyObj);
+            String t = String.valueOf(System.currentTimeMillis());
+            String secret = (app.getPushSecret() != null && !app.getPushSecret().isEmpty())
+                    ? app.getPushSecret() : app.getAppSecret();
+            String sign = PushSigner.sign(body, secret, t);
+            PushTaskMessage msg = new PushTaskMessage(app.getAppKey(), type.getPath(), type.getLabel(),
+                    body, t, sign, 1, triggerType);
+            pushRabbitTemplate.convertAndSend(PushMqConfig.EXCHANGE_TOPIC, type.getPath(), msg);
+            log.info("[推送] 投递 appKey={} type={} trigger={}", app.getAppKey(), type.getPath(), triggerType);
+        } catch (Exception e) {
+            log.error("[推送] 消息投递失败 appKey={} type={}", app.getAppKey(), type.getPath(), e);
+        }
+    }
+
+    // ===================== 过滤 =====================
+
+    private List<SysGroup> filterGroups(List<SysGroup> groups, ApplicationInfo app) {
+        Set<Integer> schoolSet = parseIds(app.getPushSchoolIds());
+        if (schoolSet.isEmpty()) {
+            return groups;
+        }
+        return groups.stream()
+                .filter(g -> {
+                    Integer sid = groupScopeHelper.resolveSchoolId(g.getId());
+                    return sid != null && schoolSet.contains(sid);
+                })
+                .collect(Collectors.toList());
+    }
+
+    private List<SysUser> filterUsers(List<SysUser> users, ApplicationInfo app) {
+        Set<Integer> schoolSet = parseIds(app.getPushSchoolIds());
+        Set<Integer> roleSet = parseIds(app.getPushRoleIds());
+        if (schoolSet.isEmpty() && roleSet.isEmpty()) {
+            return users;
+        }
+        return users.stream().filter(u -> {
+            if (!schoolSet.isEmpty()) {
+                List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByUserId(u.getId());
+                boolean schoolMatch = rels.stream().anyMatch(r -> {
+                    Integer sid = groupScopeHelper.resolveSchoolId(r.getGroupId());
+                    return sid != null && schoolSet.contains(sid);
+                });
+                if (!schoolMatch) {
+                    return false;
+                }
+            }
+            if (!roleSet.isEmpty()) {
+                if (u.getRoles() == null || u.getRoles().stream().noneMatch(roleSet::contains)) {
+                    return false;
+                }
+            }
+            return true;
+        }).collect(Collectors.toList());
+    }
+
+    // ===================== 工具 =====================
+
+    private boolean containsEventType(String eventTypes, String path) {
+        if (eventTypes == null || eventTypes.trim().isEmpty()) {
+            return false;
+        }
+        for (String s : eventTypes.split(",")) {
+            if (s.trim().equals(path)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private Set<Integer> parseIds(String csv) {
+        Set<Integer> set = new HashSet<>();
+        if (csv == null || csv.trim().isEmpty()) {
+            return set;
+        }
+        for (String s : csv.split(",")) {
+            s = s.trim();
+            if (!s.isEmpty()) {
+                try {
+                    set.add(Integer.valueOf(s));
+                } catch (NumberFormatException ignored) {
+                    // 跳过非数字片段
+                }
+            }
+        }
+        return set;
+    }
+
+    private static String joinUrl(String base, String path) {
+        if (base == null) {
+            return path;
+        }
+        String b = base.endsWith("/") ? base : base + "/";
+        String p = path.startsWith("/") ? path.substring(1) : path;
+        return b + p;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/PushPayloadAssembler.java b/src/main/java/com/yunhai/userbase/service/push/PushPayloadAssembler.java
new file mode 100644
index 0000000..4596df5
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/PushPayloadAssembler.java
@@ -0,0 +1,186 @@
+package com.yunhai.userbase.service.push;
+
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.userbase.enums.StatusEnum;
+import com.yunhai.userbase.model.push.dto.PushGroupDTO;
+import com.yunhai.userbase.model.push.dto.PushUserDTO;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDate;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * 领域模型 → 文档契约 DTO 的装配器。<br><br>
+ * 关键映射（方案 v5 §2 / 文档 3.x）：
+ * <ul>
+ *   <li>组 type：GroupTypeEnum.key 直接透传（1-8 零映射）</li>
+ *   <li>用户 status：NORMAL(0)→0正常 / DISABLED(1)→2禁用</li>
+ *   <li>groups[].schoolId：组所属学校范围 id（沿 parentId 向上最近 SCHOOL_GROUP）</li>
+ *   <li>roleList[].schId：用户主组所属学校范围 id（userbase 无角色-学校关联，统一取主校）</li>
+ * </ul>
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Service
+public class PushPayloadAssembler {
+
+    private static final int ROOT_PARENT_ID = 0;
+    private static final int IS_MAIN = 1;
+
+    @Autowired
+    private SysGroupRepository sysGroupRepository;
+    @Autowired
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+    @Autowired
+    private GroupScopeHelper groupScopeHelper;
+
+    // ===================== 组 =====================
+
+    /** 组节点（不含 children）。AddGroup / UpdateGroup 使用。 */
+    public PushGroupDTO toGroupDto(SysGroup g) {
+        if (g == null) {
+            return null;
+        }
+        PushGroupDTO d = new PushGroupDTO();
+        d.setId(g.getId());
+        d.setName(g.getName());
+        // 文档 code 为「机构代码」，userbase 的 sys_group 无此属性，按可选项留空（序列化后为 null）
+        d.setType(g.getType() == null ? null : g.getType().getKey());
+        d.setPid(g.getParentId());
+        d.setNo(g.getSort());
+        return d;
+    }
+
+    /** 组节点 + 递归 children（SyncGroup 使用）。 */
+    public PushGroupDTO toGroupDtoWithChildren(SysGroup g, Map<Integer, List<SysGroup>> childrenMap) {
+        PushGroupDTO d = toGroupDto(g);
+        List<SysGroup> children = childrenMap.get(g.getId());
+        if (children != null) {
+            d.setChildren(children.stream()
+                    .map(c -> toGroupDtoWithChildren(c, childrenMap))
+                    .collect(Collectors.toList()));
+        }
+        return d;
+    }
+
+    /** 多个组（AddGroup / UpdateGroup），无 children，带 pid。 */
+    public List<PushGroupDTO> toGroupDtoList(List<SysGroup> groups) {
+        if (groups == null) {
+            return Collections.emptyList();
+        }
+        return groups.stream().map(this::toGroupDto).collect(Collectors.toList());
+    }
+
+    // ===================== 用户 =====================
+
+    /** 单个用户 → PushUserDTO（含 groups / roleList，学校 id 已解析）。 */
+    public PushUserDTO toUserDto(SysUser u) {
+        if (u == null) {
+            return null;
+        }
+        PushUserDTO d = new PushUserDTO();
+        d.setId(u.getId());
+        d.setAccount(u.getAccount());
+        d.setName(u.getRealName());
+        d.setIdcard(u.getIdcard());
+        d.setPhone(u.getPhone());
+        d.setEmail(u.getEmail());
+        d.setGender(u.getGender());
+        d.setBirthday(u.getBirthday() == null ? null : u.getBirthday().toString());
+        // status：NORMAL(0)→0正常 / DISABLED(1)→2禁用
+        d.setStatus(u.getDisabled() == StatusEnum.NORMAL ? 0 : 2);
+        d.setProfilePicture(u.getProfilePicture());
+
+        List<SysUserGroupRel> rels = sysUserGroupRelRepository.findByUserId(u.getId());
+        Integer mainSchoolId = resolveMainSchoolId(rels);
+
+        // groups
+        List<PushUserDTO.PushUserGroupRef> groupRefs = new ArrayList<>();
+        for (SysUserGroupRel rel : rels) {
+            PushUserDTO.PushUserGroupRef ref = new PushUserDTO.PushUserGroupRef();
+            ref.setGroupId(rel.getGroupId());
+            ref.setNo(rel.getSortNo());
+            ref.setSchoolId(groupScopeHelper.resolveSchoolId(rel.getGroupId()));
+            groupRefs.add(ref);
+        }
+        d.setGroups(groupRefs);
+
+        // roleList：每个 roleId 一行，schId 取主组学校（userbase 无角色-学校关联）
+        List<PushUserDTO.PushUserRoleRef> roleRefs = new ArrayList<>();
+        if (u.getRoles() != null) {
+            for (Integer roleId : u.getRoles()) {
+                PushUserDTO.PushUserRoleRef ref = new PushUserDTO.PushUserRoleRef();
+                ref.setRoleId(roleId);
+                ref.setSchId(mainSchoolId);
+                roleRefs.add(ref);
+            }
+        }
+        d.setRoleList(roleRefs);
+        return d;
+    }
+
+    /** 多个用户（AddUser / UpdateUser / SyncUser）。 */
+    public List<PushUserDTO> toUserDtoList(List<SysUser> users) {
+        if (users == null) {
+            return Collections.emptyList();
+        }
+        return users.stream().map(this::toUserDto).collect(Collectors.toList());
+    }
+
+    /** 取用户主组（isMain=1，否则首个关联）所属学校范围 id。 */
+    private Integer resolveMainSchoolId(List<SysUserGroupRel> rels) {
+        if (rels == null || rels.isEmpty()) {
+            return null;
+        }
+        Integer mainGroupId = rels.stream()
+                .filter(r -> r.getIsMain() != null && r.getIsMain() == IS_MAIN)
+                .map(SysUserGroupRel::getGroupId)
+                .findFirst()
+                .orElse(rels.get(0).getGroupId());
+        return groupScopeHelper.resolveSchoolId(mainGroupId);
+    }
+
+    // ===================== 公共工具 =====================
+
+    /** 构建 parentId → 直接子节点列表（null 视为根 0），同层按 sort / id 升序。 */
+    public Map<Integer, List<SysGroup>> buildChildrenMap(List<SysGroup> all) {
+        Map<Integer, List<SysGroup>> childrenMap = new HashMap<>();
+        for (SysGroup g : all) {
+            Integer key = (g.getParentId() == null) ? ROOT_PARENT_ID : g.getParentId();
+            childrenMap.computeIfAbsent(key, k -> new ArrayList<>()).add(g);
+        }
+        Comparator<SysGroup> order = (a, b) -> {
+            int sa = a.getSort() == null ? 999 : a.getSort();
+            int sb = b.getSort() == null ? 999 : b.getSort();
+            if (sa != sb) {
+                return Integer.compare(sa, sb);
+            }
+            return Integer.compare(a.getId(), b.getId());
+        };
+        for (List<SysGroup> siblings : childrenMap.values()) {
+            siblings.sort(order);
+        }
+        return childrenMap;
+    }
+
+    /** 构建整棵组树（从根 pid=0 起），SyncGroup 全量同步入口。 */
+    public List<PushGroupDTO> buildFullGroupTree() {
+        List<SysGroup> all = sysGroupRepository.findAll();
+        if (all.isEmpty()) {
+            return Collections.emptyList();
+        }
+        Map<Integer, List<SysGroup>> childrenMap = buildChildrenMap(all);
+        List<SysGroup> roots = childrenMap.getOrDefault(ROOT_PARENT_ID, new ArrayList<>());
+        return roots.stream()
+                .map(r -> toGroupDtoWithChildren(r, childrenMap))
+                .collect(Collectors.toList());
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/PushRecordService.java b/src/main/java/com/yunhai/userbase/service/push/PushRecordService.java
new file mode 100644
index 0000000..c54ce9e
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/PushRecordService.java
@@ -0,0 +1,173 @@
+package com.yunhai.userbase.service.push;
+
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.config.PushMqConfig;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.model.push.PushRecordEntity;
+import com.yunhai.userbase.model.push.PushRecordListVo;
+import com.yunhai.userbase.model.push.PushRecordQuery;
+import com.yunhai.userbase.model.push.PushTaskMessage;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.PushRecordRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.amqp.rabbit.core.RabbitTemplate;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Sort;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+import javax.persistence.TypedQuery;
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.CriteriaQuery;
+import javax.persistence.criteria.Order;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 推送记录服务：日志查询 / 手动重试 / 定期清理（与操作日志同范式）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Slf4j
+@Service
+public class PushRecordService {
+
+    @Autowired
+    private PushRecordRepository pushRecordRepository;
+    @Autowired
+    private ApplicationInfoRepository applicationInfoRepository;
+    @Autowired
+    @Qualifier("pushRabbitTemplate")
+    private RabbitTemplate pushRabbitTemplate;
+
+    @PersistenceContext
+    private EntityManager em;
+
+    /** 分页查询（列表投影排除 payload，避免全量推送时数据量过大；默认按创建时间倒序）。 */
+    public Page<PushRecordListVo> query(PushRecordQuery q, Pageable pageable) {
+        CriteriaBuilder cb = em.getCriteriaBuilder();
+        // 列表投影：显式选择字段，不包含 payload（MEDIUMTEXT，全量同步可能非常大）
+        CriteriaQuery<PushRecordListVo> cq = cb.createQuery(PushRecordListVo.class);
+        Root<PushRecordEntity> root = cq.from(PushRecordEntity.class);
+        cq.select(cb.construct(PushRecordListVo.class,
+                root.get("id"), root.get("subscriberAppKey"), root.get("appName"),
+                root.get("interfacePath"), root.get("interfaceLabel"), root.get("requestUrl"),
+                root.get("signT"), root.get("httpStatus"), root.get("respCode"), root.get("respMsg"),
+                root.get("success"), root.get("attemptNo"), root.get("costMs"),
+                root.get("triggerType"), root.get("createdAt")));
+        List<Predicate> predicates = buildPredicates(cb, root, q);
+        cq.where(predicates.toArray(new Predicate[0]));
+        cq.orderBy(buildOrders(cb, root, pageable.getSort()));
+
+        // 总数查询
+        CriteriaQuery<Long> countCq = cb.createQuery(Long.class);
+        Root<PushRecordEntity> countRoot = countCq.from(PushRecordEntity.class);
+        countCq.select(cb.count(countRoot));
+        countCq.where(buildPredicates(cb, countRoot, q).toArray(new Predicate[0]));
+        long total = em.createQuery(countCq).getSingleResult();
+
+        TypedQuery<PushRecordListVo> typed = em.createQuery(cq);
+        int pageIndex = pageable.getPageNumber();
+        int pageSize = pageable.getPageSize();
+        typed.setFirstResult(pageIndex * pageSize);
+        typed.setMaxResults(pageSize);
+        List<PushRecordListVo> content = typed.getResultList();
+
+        return new org.springframework.data.domain.PageImpl<>(content, pageable, total);
+    }
+
+    /** 获取某条推送记录的请求体原文（payload）。无记录返回 null。 */
+    public String getPayload(Long id) {
+        PushRecordEntity rec = pushRecordRepository.findById(id).orElse(null);
+        return rec != null ? rec.getPayload() : null;
+    }
+
+    /** 手动重试：用原始 payload 重新签名（新时间戳）投递 MQ，由消费者再次落库。 */
+    @Transactional
+    public void retry(Long recordId) {
+        PushRecordEntity rec = pushRecordRepository.findById(recordId)
+                .orElseThrow(() -> new DException("推送记录不存在"));
+        if (rec.getSuccess() != null && rec.getSuccess() == 1) {
+            return; // 已成功无需重试
+        }
+        ApplicationInfo app = applicationInfoRepository.findByAppKey(rec.getSubscriberAppKey());
+        if (app == null) {
+            throw new DException("订阅方不存在");
+        }
+        String secret = (app.getPushSecret() != null && !app.getPushSecret().isEmpty())
+                ? app.getPushSecret() : app.getAppSecret();
+        String t = String.valueOf(System.currentTimeMillis());
+        String sign = PushSigner.sign(rec.getPayload(), secret, t);
+        PushTaskMessage msg = new PushTaskMessage(app.getAppKey(), rec.getInterfacePath(),
+                rec.getInterfaceLabel(), rec.getPayload(), t, sign, 1, "retry");
+        pushRabbitTemplate.convertAndSend(PushMqConfig.EXCHANGE_TOPIC, rec.getInterfacePath(), msg);
+    }
+
+    private List<Predicate> buildPredicates(CriteriaBuilder cb, Root<PushRecordEntity> root, PushRecordQuery q) {
+        List<Predicate> ps = new ArrayList<>();
+        if (q == null) {
+            return ps;
+        }
+        if (q.getAppKey() != null) {
+            ps.add(cb.equal(root.get("subscriberAppKey"), q.getAppKey()));
+        }
+        if (q.getInterfacePath() != null && !q.getInterfacePath().isEmpty()) {
+            ps.add(cb.equal(root.get("interfacePath"), q.getInterfacePath()));
+        }
+        if (q.getSuccess() != null) {
+            ps.add(cb.equal(root.get("success"), q.getSuccess()));
+        }
+        if (q.getStartTime() != null && !q.getStartTime().isEmpty()) {
+            ps.add(cb.greaterThanOrEqualTo(root.get("createdAt"), parseStart(q.getStartTime())));
+        }
+        if (q.getEndTime() != null && !q.getEndTime().isEmpty()) {
+            ps.add(cb.lessThanOrEqualTo(root.get("createdAt"), parseEnd(q.getEndTime())));
+        }
+        return ps;
+    }
+
+    private List<Order> buildOrders(CriteriaBuilder cb, Root<PushRecordEntity> root, Sort sort) {
+        List<Order> orders = new ArrayList<>();
+        if (sort != null && sort.isSorted()) {
+            for (Sort.Order o : sort) {
+                javax.persistence.criteria.Path<?> path = root.get(o.getProperty());
+                orders.add(o.isAscending() ? cb.asc(path) : cb.desc(path));
+            }
+        }
+        if (orders.isEmpty()) {
+            orders.add(cb.desc(root.get("createdAt")));
+        }
+        return orders;
+    }
+
+    /** 清理 1 年前的记录（每日 3 点由 PushRecordCleanupTask 调用）。 */
+    @Transactional
+    public long cleanupExpired() {
+        LocalDateTime cutoff = LocalDateTime.now().minusYears(1);
+        List<PushRecordEntity> expired = pushRecordRepository.findAll(
+                (root, cq, cb) -> cb.lessThan(root.get("createdAt"), cutoff));
+        long n = expired.size();
+        if (n > 0) {
+            pushRecordRepository.deleteAll(expired);
+        }
+        return n;
+    }
+
+    private LocalDateTime parseStart(String s) {
+        return LocalDateTime.parse(s + "T00:00:00", DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+    }
+
+    private LocalDateTime parseEnd(String s) {
+        return LocalDateTime.parse(s + "T23:59:59", DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/service/push/PushSigner.java b/src/main/java/com/yunhai/userbase/service/push/PushSigner.java
new file mode 100644
index 0000000..338956c
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/service/push/PushSigner.java
@@ -0,0 +1,50 @@
+package com.yunhai.userbase.service.push;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * 推送签名器：复刻文档 2.x 规范。<br><br>
+ * 签名串 DATA2 = 业务JSON(原始字符串) + 时间戳t；<br>
+ * sign = HMAC-SHA256(DATA2, secret)，UTF-8，hex 小写。<br><br>
+ * <b>关键</b>：签名与发送均基于「发送方实际写出的 body 原始字符串字节」，
+ * 订阅方须用接收到的原始 body 验签（不得反序列化后重新序列化，否则字节不一致导致验签失败）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+public final class PushSigner {
+
+    private PushSigner() {
+    }
+
+    /**
+     * 计算签名。
+     *
+     * @param body  业务数据原始 JSON 字符串（与发送 body 完全一致）
+     * @param secret 签名密钥（push_secret 优先，否则 app_secret）
+     * @param t      时间戳（毫秒或秒，与订阅方约定一致即可；本实现直接拼接字符串）
+     * @return hex 小写签名
+     */
+    public static String sign(String body, String secret, String t) {
+        try {
+            Mac mac = Mac.getInstance("HmacSHA256");
+            SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
+            mac.init(keySpec);
+            String data2 = body + t;
+            byte[] raw = mac.doFinal(data2.getBytes(StandardCharsets.UTF_8));
+            return toHex(raw);
+        } catch (Exception e) {
+            throw new RuntimeException("推送签名失败", e);
+        }
+    }
+
+    private static String toHex(byte[] bytes) {
+        StringBuilder sb = new StringBuilder(bytes.length * 2);
+        for (byte b : bytes) {
+            sb.append(String.format("%02x", b));
+        }
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/task/OapiLogCleanupTask.java b/src/main/java/com/yunhai/userbase/task/OapiLogCleanupTask.java
new file mode 100644
index 0000000..98bc783
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/task/OapiLogCleanupTask.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.task;
+
+import com.yunhai.userbase.service.ISysOapiLogService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/**
+ * 开放接口日志定时清理任务。<br>
+ * 每日凌晨 3 点执行：一般日志(level=3)保留一年、重要(level=1)/次要(level=2)日志保留三年。<br>
+ * 与管理端 OperationLogCleanupTask 同范式（@EnableScheduling 已在 UserBaseApplication 开启）。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Slf4j
+@Component
+public class OapiLogCleanupTask {
+
+    @Autowired
+    private ISysOapiLogService sysOapiLogService;
+
+    @Scheduled(cron = "0 0 3 * * ?")
+    public void run() {
+        try {
+            long deleted = sysOapiLogService.cleanupExpired();
+            log.info("开放接口日志定时清理完成, 删除{}条", deleted);
+        } catch (Exception e) {
+            log.error("开放接口日志定时清理失败", e);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/task/OperationLogCleanupTask.java b/src/main/java/com/yunhai/userbase/task/OperationLogCleanupTask.java
new file mode 100644
index 0000000..311822a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/task/OperationLogCleanupTask.java
@@ -0,0 +1,33 @@
+package com.yunhai.userbase.task;
+
+import com.yunhai.userbase.service.ISysOperationLogService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/**
+ * 操作日志定时清理任务。<br>
+ * 每日凌晨 3 点执行：一般日志(level=3)保留一年、重要(level=1)/次要(level=2)日志保留三年。<br>
+ * 如需「删除前归档」，可在 {@code ISysOperationLogService.cleanupExpired} 中扩展归档逻辑。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+@Slf4j
+@Component
+public class OperationLogCleanupTask {
+
+    @Autowired
+    private ISysOperationLogService sysOperationLogService;
+
+    @Scheduled(cron = "0 0 3 * * ?")
+    public void run() {
+        try {
+            long deleted = sysOperationLogService.cleanupExpired();
+            log.info("操作日志定时清理完成, 删除{}条", deleted);
+        } catch (Exception e) {
+            log.error("操作日志定时清理失败", e);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/task/PushRecordCleanupTask.java b/src/main/java/com/yunhai/userbase/task/PushRecordCleanupTask.java
new file mode 100644
index 0000000..d523fdd
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/task/PushRecordCleanupTask.java
@@ -0,0 +1,32 @@
+package com.yunhai.userbase.task;
+
+import com.yunhai.userbase.service.push.PushRecordService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/**
+ * 推送日志定时清理任务：每日凌晨 3 点清理 1 年前的推送记录。<br>
+ * 与 {@code OperationLogCleanupTask} 同范式（@EnableScheduling 已在 UserBaseApplication 开启）。
+ *
+ * @author chenx
+ * @date 2026/8/14
+ */
+@Slf4j
+@Component
+public class PushRecordCleanupTask {
+
+    @Autowired
+    private PushRecordService pushRecordService;
+
+    @Scheduled(cron = "0 0 3 * * ?")
+    public void run() {
+        try {
+            long deleted = pushRecordService.cleanupExpired();
+            log.info("推送日志定时清理完成, 删除{}条", deleted);
+        } catch (Exception e) {
+            log.error("推送日志定时清理失败", e);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/task/SignKeyCacheDailyTask.java b/src/main/java/com/yunhai/userbase/task/SignKeyCacheDailyTask.java
new file mode 100644
index 0000000..ccaf22f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/task/SignKeyCacheDailyTask.java
@@ -0,0 +1,48 @@
+package com.yunhai.userbase.task;
+
+import com.yunhai.userbase.service.impl.SignKeyCacheService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+/**
+ * 签名密钥共享缓存的对账/同步定时任务。<br>
+ * <br>
+ * 每天凌晨 3:05 执行（让 {@link OperationLogCleanupTask} 的 3:00 先跑完，避免同一时间打库）：
+ * <ol>
+ *   <li>把 application_info 表全量同步到共享 Redis；</li>
+ *   <li>清理 DB 已删除、但 Redis 残留的旧应用 key；</li>
+ *   <li>清空本机 AppSecretProvider / LocalAppIdentityProvider 的本地密钥缓存，
+ *       避免长驻进程本地缓存和 DB 不一致。</li>
+ * </ol>
+ * <p>
+ * 注：应用日常新增/删除/重置密钥会通过
+ * {@link com.yunhai.userbase.service.impl.ApplicationInfoService} 的事务事件
+ * 实时触发 {@link SignKeyCacheService} 的 syncOne/removeOne，
+ * 本任务仅作为「每日对账兜底」，防止 Redis 故障或人工介入导致的偏差。
+ */
+@Component
+public class SignKeyCacheDailyTask {
+
+    private static final Logger log = LoggerFactory.getLogger(SignKeyCacheDailyTask.class);
+
+    @Autowired
+    private SignKeyCacheService signKeyCacheService;
+
+    /**
+     * 每天凌晨 3:05 执行，错开 OperationLogCleanupTask 的 3:00。
+     */
+    @Scheduled(cron = "0 5 3 * * ?")
+    @Async
+    public void syncAll() {
+        try {
+            int n = signKeyCacheService.refreshAll();
+            log.info("[SignKeyCache] daily sync-all done, synced apps={}", n);
+        } catch (Exception e) {
+            log.warn("[SignKeyCache] daily sync-all failed: {}", e.getMessage());
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/BaseUtil.java b/src/main/java/com/yunhai/userbase/utils/BaseUtil.java
new file mode 100644
index 0000000..559cea0
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/BaseUtil.java
@@ -0,0 +1,155 @@
+package com.yunhai.userbase.utils;
+
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Component;
+
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * @ Description   :  基础工具类，不知道怎么分类放这里就对了
+ * @ Author        :  cls
+ * @ CreateDate    :  2020/2/8 16:38
+ * @ Company       :  bestsch
+ */
+@Component
+public class BaseUtil {
+
+    /**
+     * 为数字前面自动补充0
+     * @param number 待补充的数字
+     * @param length 结果总长度
+     *        若number为2，length为3，则返回的结果为002
+     * @return
+     */
+    public static String frontCompWithZore(int number,int length){
+        String newString = String.format("%0"+length+"d", number);
+        return newString;
+    }
+
+    /**
+     * 年级名称转换为年级编号
+     * @param grade
+     * @return
+     */
+    public static int gradeConverter(String grade){
+        if(StringUtils.isNotBlank(grade)){
+            if(grade.indexOf("一") != -1
+                    && grade.indexOf("初一") == -1
+                    && grade.indexOf("高一") == -1){
+                return 1;
+            }
+            if(grade.indexOf("二") != -1
+                    && grade.indexOf("初二") == -1
+                    && grade.indexOf("高二") == -1){
+                return 2;
+            }
+            if(grade.indexOf("三") != -1
+                    && grade.indexOf("初三") == -1
+                    && grade.indexOf("高三") == -1){
+                return 3;
+            }
+            if(grade.indexOf("四") != -1){
+                return 4;
+            }
+            if(grade.indexOf("五") != -1){
+                return 5;
+            }
+            if(grade.indexOf("六") != -1){
+                return 6;
+            }
+            if(grade.indexOf("七") != -1
+                    || grade.indexOf("初一") != -1){
+                return 7;
+            }
+            if(grade.indexOf("八") != -1
+                    || grade.indexOf("初二") != -1){
+                return 8;
+            }
+            if(grade.indexOf("九") != -1
+                    || grade.indexOf("初三") != -1){
+                return 9;
+            }
+            if(grade.indexOf("十") != -1
+                    || grade.indexOf("高一") != -1){
+                return 10;
+            }
+            if(grade.indexOf("十一") != -1
+                    || grade.indexOf("高二") != -1){
+                return 11;
+            }
+            if(grade.indexOf("十二") != -1
+                    || grade.indexOf("高三") != -1){
+                return 12;
+            }
+        }
+        return -1;
+    }
+
+    /**
+     * 学期名称转学期编号
+     * @param semester
+     * @return
+     */
+    public static int semesterConverter(String semester){
+        if(StringUtils.isNotBlank(semester)){
+            if(semester.indexOf("上") != -1
+                    || semester.indexOf("一") != -1
+                    || semester.indexOf("1") != -1){
+                return 0;
+            }
+            if(semester.indexOf("下") != -1
+                    || semester.indexOf("二") != -1
+                    || semester.indexOf("2") != -1){
+                return 1;
+            }
+        }
+        return -1;
+    }
+
+    public static String collectionToString(Collection<?> collection){
+        String string = "";
+        if(collection != null && !collection.isEmpty()){
+            Iterator<?> it = collection.iterator();
+            while (it.hasNext()){
+                Object obj = it.next();
+                if(obj != null && StringUtils.isNotBlank(obj.toString())){
+                    string += obj.toString() + ",";
+                }
+            }
+            if(string.lastIndexOf(",") == string.length()-1){
+                string = string.substring(0,string.length()-1);
+            }
+        }
+        return string;
+    }
+
+    /** 功能描述: List<String> 转 List<Integer>
+     * @param list
+    * @return:
+    * @Author: cls
+    * @Date: 2021/10/12 10:06
+    */
+    public static List<Integer> stringListToIntegerList(List<String> list){
+        return list.stream().map(Integer :: valueOf).collect(Collectors.toList());
+    }
+
+
+    /**
+     * 十六进制转字符串
+     * @param hex
+     * @return
+     */
+    public final static String hexToString(String hex) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < hex.length(); i += 2) {
+            String hexSubstring = hex.substring(i, i + 2);
+            int decimalValue = Integer.parseInt(hexSubstring, 16);
+            sb.append((char) decimalValue);
+        }
+        return sb.toString();
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/CacheKitUtils.java b/src/main/java/com/yunhai/userbase/utils/CacheKitUtils.java
new file mode 100644
index 0000000..e357906
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/CacheKitUtils.java
@@ -0,0 +1,57 @@
+package com.yunhai.userbase.utils;
+
+import java.util.function.Supplier;
+
+/**
+ * @author chenx
+ * @date 2026/1/6 20:54
+ * @description 通用缓存封装
+ */
+
+public final class CacheKitUtils {
+    private CacheKitUtils() {}
+
+    /**
+     * 泛型模板：先读缓存 → 没有则调用 loader → 回写缓存 → 返回结果
+     *
+     * @param redisUtil  你的 RedisUtil
+     * @param key        缓存键
+     * @param expireSec  过期秒数
+     * @param loader     实际业务加载器
+     * @param <T>        返回值类型
+     * @return           缓存值或加载值
+     */
+    public static <T> T getOrLoad(RedisUtil redisUtil,
+                                  String key,
+                                  int expireSec,
+                                  Supplier<T> loader) {
+        // 1. 读缓存
+        if (redisUtil.hasKey(key)) {
+            try {
+                @SuppressWarnings("unchecked")
+                T v = (T) redisUtil.get(key);
+                if (v != null) {
+                    return v;
+                }
+            } catch (Exception e) {
+                // 仅打印，继续走 loader
+                e.printStackTrace();
+            }
+        }
+
+        // 2. 加载
+        T value = loader.get();
+        if (value == null) {
+            return null;
+        }
+
+        // 3. 回写缓存
+        try {
+            redisUtil.set(key, value, expireSec);
+        } catch (Exception e) {
+            // 缓存失败不影响主流程
+            e.printStackTrace();
+        }
+        return value;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/utils/ConstantUtil.java b/src/main/java/com/yunhai/userbase/utils/ConstantUtil.java
new file mode 100644
index 0000000..b48c78a
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/ConstantUtil.java
@@ -0,0 +1,44 @@
+package com.yunhai.userbase.utils;
+
+import java.time.Duration;
+import java.util.HashMap;
+import java.util.Map;
+
+public class ConstantUtil {
+
+    /**
+    *  redis过期时间
+    */
+    public static final long EXPIRE_TIME=60*60*8;
+
+    /**
+     *  全局缓存时间：5分钟
+     */
+    public static final Duration CACHE_TTL = Duration.ofMinutes(5);
+
+    /**
+     *  redis前缀
+     */
+    public static final String PREFIX_KEY="bsch.bschlearn.";//redis前缀
+
+    /** 
+    * @Description: 提供AI参数常量
+    * @Author: chenx
+    * @Date: 2025/4/28
+    */
+    public static final Map<String, String> PARAMS_CONSTANT;
+
+    static {
+        PARAMS_CONSTANT = new HashMap<>();
+        /**  默认前两个数据为系统常量 */
+        PARAMS_CONSTANT.put("score", "分数");
+        PARAMS_CONSTANT.put("rating", "评级");
+
+        PARAMS_CONSTANT.put("polishLevel", "润色幅度");
+        PARAMS_CONSTANT.put("commentFont", "旁批字体");
+        PARAMS_CONSTANT.put("correctionStrictness", "批改严格程度");
+        PARAMS_CONSTANT.put("lineStyle", "句子划线样式");
+
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/DicUtil.java b/src/main/java/com/yunhai/userbase/utils/DicUtil.java
new file mode 100644
index 0000000..6db0f23
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/DicUtil.java
@@ -0,0 +1,179 @@
+package com.yunhai.userbase.utils;
+
+
+/**
+ * @ Description   :  存储魔法值
+ * @ Author        :  cls
+ * @ CreateDate    :  2020/2/1 9:24
+ * @ Company       :  bestsch
+ */
+public class DicUtil {
+
+    /**
+     * 超管id
+     */
+    public static final Integer SUPER_ADMIN_ID = 100000;
+
+    public static final String UNKNOWN = "未知";
+
+    /**
+     * 一般hashMap初始化大小
+     */
+    public static final int initialCapacity = 6;
+
+    /**
+     * 缓存时间，单位毫秒
+     */
+    public static final long ONE_DAY = 1000 * 60 * 60 * 24;
+    public static final long TEN_MINUTES = 1000 * 60 * 10;
+    public static final long FIVE_MINUTES = 1000 * 60 * 5;
+    public static final long ONE_MINUTE = 1000 * 60;
+    public static final long HALF_MINUTE = 1000 * 30;
+    public static final long THREE_SECONDS = 1000 * 3;
+
+
+    public static final int SORT_STEP = 10;
+    /**
+     * 节点最大层级，索引是9，代表是第10层
+     */
+    public static final int MAX_LEVEL = 9;
+
+    /**
+     * 默认的学科类型 6 代表其他
+     */
+    public static final String DEFAULT_RESOURCE_TYPE = "6";
+
+    /**
+     * 数据状态 1 有效
+     */
+    public static final Integer STATUS_VALID = 1;
+
+    /**
+     * 数据状态 0 无效
+     */
+    public static final Integer STATUS_INVALID = 0;
+
+    /**
+     * 审核状态 0 待审
+     */
+    public static final Integer REVIEW_STATUS_TODO = 0;
+
+    /**
+     * 审核状态 1 通过
+     */
+    public static final Integer REVIEW_STATUS_PASS = 1;
+
+    /**
+     * 审核状态 2 未通过
+     */
+    public static final Integer REVIEW_STATUS_NOPASS = 2;
+    /**
+     * 区间参数 不包括
+     */
+    public static final int SECTION_NO_INCLUDE = 0;
+
+    /**
+     * 区间参数 包括
+     */
+    public static final int SECTION_INCLUDE = 1;
+
+
+    /**
+     * 用户类别 用户中心数据，1 超级管理员
+     */
+    public static final Integer USER_TYPE_SUPER_MANAGER = 1;
+
+    /**
+     * 默认头像
+     */
+    public static final String DEFAULT_PIC = "http://base.bestsch.com/img/defprofilepic.png";
+
+    /**
+     * 排序 降序 0
+     */
+    public static final Integer ORDER_DESC = 0;
+
+    /**
+     * 排序 升序 1
+     */
+    public static final Integer ORDER_ASC = 1;
+
+    /**
+     * 错误信息，上传文件失败
+     */
+    public static final String ERROR_MSG_IMPORT_WRONG = "上传失败，请稍后再试";
+
+    /**
+     * 错误消息，数据不存在
+     */
+    public static final String ERROR_MSG_NOT_FOUND = "数据不存在，可能已被删除";
+
+    /**
+     * 错误消息，无操作权限
+     */
+    public static final String ERROR_MSG_NO_POWER = "您无操作权限";
+
+    /**
+     * 错误消息，无权删除资源
+     */
+    public static final String NO_POWER_TO_DEL_RESOURCE = "您无法删除此文件";
+
+    /**
+     * 错误消息，无权编辑资源
+     */
+    public static final String NO_POWER_TO_MODIFY_RESOURCE = "您无法编辑/移动此文件";
+
+    /**
+     * 错误消息，无权移动到根节点
+     */
+    public static final String NO_MOVE_TO_ROOT = "您无法把文件移至根节点";
+
+    /**
+     * 错误消息，无法删除此节点
+     */
+    public static final String NOT_DEL_NODE = "无法删除，请先移动或删除此节点下的文件";
+
+    /**
+     * 错误消息，没有可查看的节点
+     */
+    public static final String NO_NODE_BY_WATCH = "您暂无可查看的节点";
+
+    /**
+     * 错误消息，未知的教材来源
+     */
+    public static final String UNKNOWN_TEXTBOOK_SOURCE = "未知的教材来源";
+
+    /**
+     * 错误消息，无法对根节点进行操作
+     */
+    public static final String CANT_OPERATE_FOR_ROOT = "无法对根节点进行操作";
+
+
+    public static final String OVER_MAX_LEVEL = "层级超过上限，最多支持" + (MAX_LEVEL + 1) + "层";
+
+    /**
+     * 错误消息，未知的权限类型
+     */
+    public static final String UNKNOWN_AUTHORITY_TYPE = "未知的权限类型";
+
+    /**
+     * 错误消息，未知的根节点类型类型
+     */
+    public static final String UNKNOWN_ROOT_TYPE_TYPE = "未知的根节点类型";
+
+    /**
+     * 错误消息，节点不存在
+     */
+    public static final String NO_NODE = "节点不存在";
+
+    /**
+     * 错误消息，节点不存在
+     */
+    public static final String NO_TEXTBOOK = "教材不存在";
+
+    /**
+     * 错误消息，节点不存在
+     */
+    public static final String NO_AUTHORITY_NODE = "无权限操作该节点";
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/DownloadFileUtil.java b/src/main/java/com/yunhai/userbase/utils/DownloadFileUtil.java
new file mode 100644
index 0000000..e0d3aa6
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/DownloadFileUtil.java
@@ -0,0 +1,56 @@
+package com.yunhai.userbase.utils;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.core.io.InputStreamResource;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+
+import java.io.*;
+
+@Slf4j
+public class DownloadFileUtil {
+
+    public static final String separator = File.separator;
+
+    /**
+     * 下载样表
+     * @param filePath 文件上级目录
+     * @param fileName 文件名
+     * @param newName  下载的展示文件名
+     * @return 响应
+     */
+    public static ResponseEntity<InputStreamResource> download(String filePath, String fileName, String newName) {
+//        String route = "static" + separator + "templates" + separator;
+//        String path = null;
+        ResponseEntity<InputStreamResource> response = null;
+        try {
+//            path = route + filePath + separator + fileName;
+
+            File file = new File(filePath);
+
+            System.out.println(file.exists());
+
+
+//            ClassPathResource classPathResource = new ClassPathResource(filePath);
+            InputStream inputStream = new FileInputStream(file);
+
+            HttpHeaders headers = new HttpHeaders();
+            headers.add("Cache-Control", "no-cache, no-store, must-revalidate");
+            headers.add("Content-Disposition",
+                    "attachment; filename="
+                            + new String(newName.getBytes("gbk"), "iso8859-1"));
+            headers.add("Pragma", "no-cache");
+            headers.add("Expires", "0");
+            response = ResponseEntity.ok().headers(headers)
+                    .contentType(MediaType.parseMediaType("application/octet-stream"))
+                    .body(new InputStreamResource(inputStream));
+        } catch (FileNotFoundException e1) {
+            log.error("找不到指定的文件", e1);
+        } catch (IOException e) {
+            log.error("获取不到文件流", e);
+        }
+        return response;
+    }
+}
+
diff --git a/src/main/java/com/yunhai/userbase/utils/EasyPoiUtils.java b/src/main/java/com/yunhai/userbase/utils/EasyPoiUtils.java
new file mode 100644
index 0000000..12f57fb
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/EasyPoiUtils.java
@@ -0,0 +1,105 @@
+package com.yunhai.userbase.utils;
+
+import cn.afterturn.easypoi.excel.ExcelExportUtil;
+import cn.afterturn.easypoi.excel.entity.ExportParams;
+import cn.afterturn.easypoi.word.WordExportUtil;
+import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.xwpf.usermodel.XWPFDocument;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.URLEncoder;
+import java.util.List;
+import java.util.Map;
+
+public final class EasyPoiUtils {
+	
+	private EasyPoiUtils() {}
+
+	/**
+	 * 只能xls
+	 * @param fileName
+	 * @param response
+	 * @param workbook
+	 */
+    public static void downLoadExcel(String fileName, HttpServletResponse response, Workbook workbook) {
+        try {
+            response.setCharacterEncoding("UTF-8");
+            response.setHeader("content-Type", "application/vnd.ms-excel");
+            fileName = new String(fileName.getBytes("utf-8"), "iso-8859-1") + ".xls";
+            response.setHeader("Content-Disposition", "attachment;filename=" + fileName);
+            workbook.write(response.getOutputStream());
+        } catch (IOException e) {
+            throw new  RuntimeException(e);
+        }
+    }
+
+    private static<T> void defaultExport(List<T> dataList, Class<?> clz, String fileName, HttpServletResponse response, ExportParams exportParams) {
+        Workbook workbook = ExcelExportUtil.exportExcel(exportParams, clz, dataList);
+//        workbook.getSheetAt(0).getRow(0).setHeight((short) 0x25622);      // 设置行高
+        if (workbook != null) {
+            downLoadExcel(fileName, response, workbook);
+        }
+    }
+
+    public static<T> void exportExcel(List<T> dataList, String title, String sheetName, Class<?> clz, String fileName, boolean isCreateHeader, HttpServletResponse response) {
+        ExportParams exportParams = new ExportParams(title, sheetName);
+        exportParams.setCreateHeadRows(isCreateHeader);
+        defaultExport(dataList, clz, fileName, response, exportParams);
+    }
+
+    public static<T> void exportExcel(List<T> dataList, String title, String sheetName, Class<?> clz, String fileName, HttpServletResponse response) {
+        defaultExport(dataList, clz, fileName, response, new ExportParams(title, sheetName));
+    }
+    private static<T> void changeHeightExport(List<T> dataList, Class<?> clz, String fileName, HttpServletResponse response, ExportParams exportParams, Short height) {
+        Workbook workbook = ExcelExportUtil.exportExcel(exportParams, clz, dataList);
+        if (height != null) {
+            workbook.getSheetAt(0).getRow(0).setHeight(height);      // 设置行高
+        }
+        if (workbook != null) {
+            downLoadExcel(fileName, response, workbook);
+        }
+    }
+
+    public static StringBuffer changeStringTable(String spl,String string) {
+        StringBuffer buffer = new StringBuffer();
+        String[] split = string.split(spl);
+        for (int i = 0; i < split.length; i++) {
+            if (i < split.length - 1) {
+                buffer.append(split[i]+(char)11);
+            } else {
+                buffer.append(split[i]);
+            }
+        }
+        return buffer;
+    }
+
+    /**
+     * 导出word
+     */
+    public static void exportWord(String fileName, Map<String, Object> map, HttpServletRequest request, HttpServletResponse response) {
+
+        try {
+            String userAgent = request.getHeader("user-agent").toLowerCase();
+            if (userAgent.contains("msie") || userAgent.contains("like gecko")) {
+                fileName = URLEncoder.encode(fileName, "UTF-8");
+            } else {
+                fileName = new String(fileName.getBytes("utf-8"), "ISO-8859-1");
+            }
+            XWPFDocument doc = WordExportUtil.exportWord07(
+                    "/Users/luona/Downloads/模版.docx", map);
+            // 设置强制下载不打开
+            response.setContentType("application/force-download");
+            // 设置文件名
+            response.addHeader("Content-Disposition", "attachment;fileName=" + fileName);
+            OutputStream out = response.getOutputStream();
+            doc.write(out);
+            out.close();
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/FileUtil.java b/src/main/java/com/yunhai/userbase/utils/FileUtil.java
new file mode 100644
index 0000000..4efe128
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/FileUtil.java
@@ -0,0 +1,412 @@
+package com.yunhai.userbase.utils;
+
+
+import com.yunhai.platform.utils.exception.DException;
+import cn.hutool.core.io.IoUtil;
+import cn.hutool.core.util.IdUtil;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.servlet.ServletOutputStream;
+import javax.servlet.http.HttpServletResponse;
+import java.io.*;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.text.DecimalFormat;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * @author min
+ * @description File工具类，扩展 hutool 工具包
+ * @date 2019-07-05
+ */
+public class FileUtil {
+
+    /**
+     * 定义GB的计算常量（改为long避免int溢出）
+     */
+    private static final long GB = 1024L * 1024 * 1024;
+    /**
+     * 定义MB的计算常量
+     */
+    private static final long MB = 1024L * 1024;
+    /**
+     * 定义KB的计算常量
+     */
+    private static final long KB = 1024L;
+
+    /**
+     * 格式化小数
+     */
+    private static final DecimalFormat DF = new DecimalFormat("0.00");
+
+    /**
+     * 上传文件存储根目录（由 FileStorageConfig 在启动时注入）。<br>
+     */
+    private static String BASE_STORE_PATH;
+
+    /**
+     * 上传文件对外访问的 Web 根地址（由 FileStorageConfig 在启动时注入）。<br>
+     */
+    private static String BASE_WEB_PATH;
+
+    /**
+     * 危险后缀黑名单：命中则禁止上传，防止恶意文件被执行/访问。<br>
+     */
+    private static final Set<String> DANGEROUS_EXT = new HashSet<>(Arrays.asList(
+            "jsp", "jspx", "html", "htm", "js", "exe", "sh", "bat",
+            "php", "asp", "aspx", "jar", "war", "class", "htaccess"
+    ));
+
+    /**
+     * 由 Spring 启动时注入存储根目录与 Web 访问前缀。<br>
+     *
+     * @param storePath 磁盘存储根目录
+     * @param webPath   对外访问的 Web 根地址
+     */
+    public static void init(String storePath, String webPath) {
+        BASE_STORE_PATH = storePath;
+        BASE_WEB_PATH = webPath;
+    }
+
+    /**
+     * 校验文件后缀是否在危险黑名单中。<br>
+     *
+     * @param ext 文件后缀（可带或不带点）
+     * @throws DException 命中黑名单时抛出
+     */
+    private static void validateExt(String ext) {
+        if (ext == null || ext.isEmpty()) {
+            return;
+        }
+        String lower = ext.toLowerCase().replaceFirst("^\\.", "");
+        if (DANGEROUS_EXT.contains(lower)) {
+            throw new DException("不支持的文件类型: " + ext);
+        }
+    }
+
+    /**
+     * 净化文件名，防止路径穿越（../ 等）。<br>
+     *
+     * @param name 原始文件名
+     * @return 净化后的安全文件名
+     */
+    private static String sanitizeFileName(String name) {
+        if (name == null || name.trim().isEmpty()) {
+            return "file";
+        }
+        return name.replaceAll("[\\\\/]", "_")
+                .replaceAll("\\.{2,}", "_")
+                .replaceAll("\\s+", "_");
+    }
+
+    /**
+     * 拼接完整可访问的 Web URL（根地址 + 子目录 + 文件名）。<br>
+     *
+     * @param subDir  子目录（如 image/file/icon）
+     * @param fileName 文件名
+     * @return 完整访问 URL
+     */
+    private static String buildUrl(String subDir, String fileName) {
+        String web = (BASE_WEB_PATH == null) ? "" : BASE_WEB_PATH;
+        web = web.endsWith("/") ? web : web + "/";
+        return web + subDir + "/" + fileName;
+    }
+
+    /**
+     * 校验存储配置已注入。<br>
+     *
+     * @throws DException 未注入时抛出
+     */
+    private static void ensureStoreBase() {
+        if (BASE_STORE_PATH == null || BASE_WEB_PATH == null) {
+            throw new DException("文件存储路径未初始化，请检查 FILE_PATH / FILE_WEB_PATH 配置");
+        }
+    }
+
+    /**
+     * MultipartFile转File（临时文件）
+     * @param multipartFile 上传文件
+     * @return 临时文件对象，失败返回null
+     */
+    public static File toFile(MultipartFile multipartFile) {
+        if (multipartFile == null || multipartFile.isEmpty()) {
+            return null;
+        }
+        // 获取文件后缀
+        String ext = getExtensionName(multipartFile.getOriginalFilename());
+        String prefix = "." + ext;
+        File file = null;
+        try {
+            // 用uuid作为文件名，防止生成的临时文件重复
+            file = File.createTempFile(IdUtil.simpleUUID(), prefix);
+            multipartFile.transferTo(file);
+        } catch (IOException e) {
+            e.printStackTrace();
+        }
+        return file;
+    }
+
+    /**
+     * 删除文件/目录
+     * @param files 待删除文件数组
+     */
+    public static void deleteFile(File... files) {
+        if (files == null || files.length == 0) {
+            return;
+        }
+        for (File file : files) {
+            if (file != null && file.exists()) {
+                cn.hutool.core.io.FileUtil.del(file);
+            }
+        }
+    }
+
+    /**
+     * 获取文件扩展名（不带点）
+     * @param filename 文件名
+     * @return 扩展名，无后缀返回原文件名
+     */
+    public static String getExtensionName(String filename) {
+        return cn.hutool.core.io.FileUtil.extName(filename);
+    }
+
+    /**
+     * 获取不带扩展名的文件名
+     * @param filename 文件名
+     * @return 主文件名
+     */
+    public static String getFileNameNoEx(String filename) {
+        return cn.hutool.core.io.FileUtil.mainName(filename);
+    }
+
+    /**
+     * 文件大小转换（修复int溢出问题）
+     * @param size 文件字节数
+     * @return 格式化后的大小字符串
+     */
+    public static String getSize(int size) {
+        long sizeLong = size;
+        String resultSize;
+        if (sizeLong / GB >= 1) {
+            resultSize = DF.format(sizeLong / (double) GB) + "GB   ";
+        } else if (sizeLong / MB >= 1) {
+            resultSize = DF.format(sizeLong / (double) MB) + "MB   ";
+        } else if (sizeLong / KB >= 1) {
+            resultSize = DF.format(sizeLong / (double) KB) + "KB   ";
+        } else {
+            resultSize = sizeLong + "B   ";
+        }
+        return resultSize;
+    }
+
+    /**
+     * 字节数组上传图片（固定.png后缀，存 image 子目录）。<br>
+     *
+     * @param imgData 图片字节数组
+     * @return 完整可访问的 Web URL
+     */
+    public static String uploadImg(byte[] imgData) {
+        return uploadBytes(imgData, "image", ".png");
+    }
+
+    /**
+     * MultipartFile上传图片（按原后缀，存 image 子目录）。<br>
+     *
+     * @param file 上传文件
+     * @return 完整可访问的 Web URL
+     */
+    public static String uploadImg(MultipartFile file) {
+        return uploadMultipart(file, "image");
+    }
+
+    /**
+     * 字节数组上传文件（固定.png后缀，存 file 子目录）。<br>
+     *
+     * @param imgData 文件字节数组
+     * @return 完整可访问的 Web URL
+     */
+    public static String uploadFile(byte[] imgData) {
+        return uploadBytes(imgData, "file", ".png");
+    }
+
+    /**
+     * MultipartFile上传文件（按原后缀，存 file 子目录）。<br>
+     *
+     * @param file 上传文件
+     * @return 完整可访问的 Web URL
+     */
+    public static String uploadFile(MultipartFile file) {
+        return uploadMultipart(file, "file");
+    }
+
+    /**
+     * 通用上传：按原后缀保存到指定子目录，返回完整可访问的 Web URL。<br>
+     *
+     * @param file   上传文件
+     * @param subDir 子目录（如 image/file/icon/media/word/html）
+     * @return 完整可访问的 Web URL
+     */
+    public static String upload(MultipartFile file, String subDir) {
+        return uploadMultipart(file, subDir);
+    }
+
+    /**
+     * URL文件代理中转下载
+     * @param response 响应对象
+     * @param address 远程文件地址
+     * @param contentType 响应Content-Type，传null自动识别
+     * @param fileName 下载文件名，传null取远程响应头
+     * @throws IOException 网络/IO异常
+     */
+    public static void proxyUrlFile(HttpServletResponse response, String address, String contentType, String fileName) throws IOException {
+        // 原有https转http逻辑保留
+        if (address != null && address.toLowerCase().startsWith("https:")) {
+            address = address.replaceFirst("(?i)^https:", "http:")
+                    .replaceAll(":443(/|$)", ":80$1");
+        }
+
+        HttpURLConnection httpURLConnection = null;
+        InputStream inputStream = null;
+        ServletOutputStream outputStream = null;
+        try {
+            URL url = new URL(address);
+            httpURLConnection = (HttpURLConnection) url.openConnection();
+            httpURLConnection.setConnectTimeout(5000);
+            httpURLConnection.setReadTimeout(30000);
+            httpURLConnection.connect();
+            inputStream = httpURLConnection.getInputStream();
+            outputStream = response.getOutputStream();
+
+            // 设置Content-Type
+            if (contentType != null) {
+                response.setContentType(contentType);
+            } else {
+                response.setContentType("multipart/form-data");
+            }
+
+            // 设置下载文件名
+            if (fileName != null) {
+                response.setHeader("Content-disposition", "attachment; filename=\""
+                        + new String(fileName.getBytes("utf-8"), "ISO8859-1") + "\"");
+            } else {
+                String headerFileName = "";
+                String disposition = httpURLConnection.getHeaderField("Content-Disposition");
+                if (disposition != null) {
+                    headerFileName = new String(disposition.getBytes("ISO-8859-1"), "UTF-8");
+                }
+                if (headerFileName.contains("filename")) {
+                    headerFileName = headerFileName.substring(headerFileName.lastIndexOf("filename") + "filename".length());
+                    // 去除可能的=号和引号
+                    headerFileName = headerFileName.replaceFirst("=", "").replace("\"", "").trim();
+                }
+                response.setHeader("Content-disposition", "attachment; filename=" + headerFileName);
+            }
+
+            // 流式拷贝，8KB缓冲区提升性能
+            IoUtil.copy(inputStream, outputStream, IoUtil.DEFAULT_BUFFER_SIZE);
+
+        } catch (Exception e) {
+            throw e;
+        } finally {
+            IoUtil.close(inputStream);
+            if (outputStream != null) {
+                outputStream.flush();
+                IoUtil.close(outputStream);
+            }
+            if (httpURLConnection != null) {
+                httpURLConnection.disconnect();
+            }
+        }
+    }
+
+    /**
+     * 保存上传文件到指定完整路径
+     * @param mf 上传文件
+     * @param path 完整保存路径（含文件名）
+     */
+    public static void saveResource(MultipartFile mf, String path) {
+        if (mf == null || path == null || path.trim().length() == 0) {
+            throw new DException(DicUtil.ERROR_MSG_IMPORT_WRONG);
+        }
+        // 净化文件名，防止路径穿越（如 ../../evil）
+        File target = new File(path);
+        String safeName = sanitizeFileName(target.getName());
+        File safeFile = new File(target.getParentFile(), safeName);
+        // 自动创建父目录
+        cn.hutool.core.io.FileUtil.mkParentDirs(safeFile.getPath());
+        try (InputStream is = mf.getInputStream();
+             FileOutputStream fos = new FileOutputStream(safeFile)) {
+            IoUtil.copy(is, fos);
+        } catch (Exception e) {
+            throw new DException(DicUtil.ERROR_MSG_IMPORT_WRONG);
+        }
+    }
+
+    // ==================== 私有通用方法，消除重复代码 ====================
+
+    /**
+     * 字节数组通用上传（流式写入，返回完整 Web URL）。<br>
+     *
+     * @param data   字节数组
+     * @param subDir 子目录
+     * @param ext    固定后缀（带点）
+     * @return 完整可访问的 Web URL
+     */
+    private static String uploadBytes(byte[] data, String subDir, String ext) {
+        if (data == null || data.length == 0 || subDir == null || subDir.trim().length() == 0) {
+            throw new DException("上传内容为空");
+        }
+        // 后缀黑名单校验（固定后缀也走同一规则）
+        validateExt(ext);
+        ensureStoreBase();
+        try {
+            // 自动创建多级目录
+            String dirPath = BASE_STORE_PATH + File.separator + subDir;
+            cn.hutool.core.io.FileUtil.mkdir(dirPath);
+            String fileName = IdUtil.fastSimpleUUID() + ext;
+            File targetFile = new File(dirPath, fileName);
+            // Hutool写入，自动关流
+            cn.hutool.core.io.FileUtil.writeBytes(data, targetFile);
+            return buildUrl(subDir, fileName);
+        } catch (DException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new DException("文件上传失败: " + e.getMessage());
+        }
+    }
+
+    /**
+     * MultipartFile通用上传（流式写入，避免大文件OOM，返回完整 Web URL）。<br>
+     *
+     * @param file   上传文件
+     * @param subDir 子目录
+     * @return 完整可访问的 Web URL
+     */
+    private static String uploadMultipart(MultipartFile file, String subDir) {
+        if (file == null || file.isEmpty() || subDir == null || subDir.trim().length() == 0) {
+            throw new DException("上传文件不能为空");
+        }
+        // 提取后缀
+        String originalFilename = file.getOriginalFilename();
+        String ext = cn.hutool.core.io.FileUtil.extName(originalFilename);
+        ext = (ext == null || ext.trim().length() == 0) ? "" : "." + ext.toLowerCase();
+        // 后缀黑名单校验
+        validateExt(ext);
+        ensureStoreBase();
+        try {
+            String dirPath = BASE_STORE_PATH + File.separator + subDir;
+            cn.hutool.core.io.FileUtil.mkdir(dirPath);
+            String fileName = IdUtil.fastSimpleUUID() + ext;
+            File targetFile = new File(dirPath, fileName);
+            // 流式写入，不加载全文件到内存
+            cn.hutool.core.io.FileUtil.writeFromStream(file.getInputStream(), targetFile);
+            return buildUrl(subDir, fileName);
+        } catch (DException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new DException("文件上传失败: " + e.getMessage());
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/GzipUtil.java b/src/main/java/com/yunhai/userbase/utils/GzipUtil.java
new file mode 100644
index 0000000..0581d95
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/GzipUtil.java
@@ -0,0 +1,64 @@
+package com.yunhai.userbase.utils;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.zip.GZIPInputStream;
+import java.util.zip.GZIPOutputStream;
+
+/**
+ * GZIP 压缩/解压工具。<br>
+ * 用于操作日志响应结果（response_data）的压缩存储与下载解压。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+public class GzipUtil {
+
+    private static final int BUFFER_SIZE = 4096;
+
+    /**
+     * 将字符串按 UTF-8 压缩为 GZIP 字节数组。
+     *
+     * @param data 原始字符串，可为 null
+     * @return 压缩后字节数组，入参为空返回 null
+     */
+    public static byte[] compress(String data) {
+        if (data == null) {
+            return null;
+        }
+        try (ByteArrayOutputStream out = new ByteArrayOutputStream();
+             GZIPOutputStream gzip = new GZIPOutputStream(out)) {
+            gzip.write(data.getBytes(StandardCharsets.UTF_8));
+            gzip.finish();
+            return out.toByteArray();
+        } catch (IOException e) {
+            throw new RuntimeException("GZIP 压缩失败", e);
+        }
+    }
+
+    /**
+     * 将 GZIP 字节数组解压为原始字符串。
+     *
+     * @param data 压缩字节数组，可为 null 或空
+     * @return 解压后字符串，入参为空返回 null
+     */
+    public static String decompress(byte[] data) {
+        if (data == null || data.length == 0) {
+            return null;
+        }
+        try (ByteArrayInputStream in = new ByteArrayInputStream(data);
+             GZIPInputStream gzip = new GZIPInputStream(in);
+             ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            byte[] buf = new byte[BUFFER_SIZE];
+            int n;
+            while ((n = gzip.read(buf)) > 0) {
+                out.write(buf, 0, n);
+            }
+            return out.toString(StandardCharsets.UTF_8.name());
+        } catch (IOException e) {
+            throw new RuntimeException("GZIP 解压失败", e);
+        }
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/HttpUtils.java b/src/main/java/com/yunhai/userbase/utils/HttpUtils.java
new file mode 100644
index 0000000..9985365
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/HttpUtils.java
@@ -0,0 +1,142 @@
+package com.yunhai.userbase.utils;
+
+import com.yunhai.platform.utils.exception.DException;
+import javax.net.ssl.HttpsURLConnection;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.X509TrustManager;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.nio.ByteBuffer;
+import java.security.KeyManagementException;
+import java.security.NoSuchAlgorithmException;
+import java.security.cert.X509Certificate;
+
+public class HttpUtils {
+    static {
+        try {
+            trustAllHttpsCertificates();
+            HttpsURLConnection.setDefaultHostnameVerifier
+                    (
+                            (urlHostName, session) -> true
+                    );
+        } catch (Exception e) {
+        }
+    }
+    /**
+     * 跳过ssl证书
+     *
+     * @throws NoSuchAlgorithmException
+     * @throws KeyManagementException
+     */
+    private static void trustAllHttpsCertificates()
+            throws NoSuchAlgorithmException, KeyManagementException {
+        TrustManager[] trustAllCerts = new TrustManager[1];
+        trustAllCerts[0] = (TrustManager) new TrustAllManager();
+        SSLContext sc = SSLContext.getInstance("SSL");
+        sc.init(null, trustAllCerts, null);
+        HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
+    }
+
+    private static class TrustAllManager implements X509TrustManager {
+        public X509Certificate[] getAcceptedIssuers() {
+            return null;
+        }
+
+        public void checkServerTrusted(X509Certificate[] certs, String authType) {
+        }
+
+        public void checkClientTrusted(X509Certificate[] certs, String authType) {
+        }
+    }
+
+    public static  String get(String aUrl,Integer timeout){
+        int respCode = 0;
+        HttpURLConnection conn = null;
+        String var3;
+        try {
+            conn = getHttpURLConnection(aUrl, "GET",timeout);
+            conn.setDoInput(true);
+            respCode = conn.getResponseCode();
+            if (respCode != 301) {
+                InputStream is = conn.getInputStream();
+                int contentLen = conn.getContentLength();
+                byte[] resultData = read(is, contentLen);
+                is.close();
+                String var6 = new String(resultData, "utf-8");
+                return var6;
+            }
+            var3 = get(conn.getHeaderField("Location"),timeout);
+        } catch (Exception var10) {
+            throw new DException("网络连接失败");
+        } finally {
+            close(conn);
+        }
+        return var3;
+    }
+
+
+    private static HttpURLConnection getHttpURLConnection(String uri, String method,int timeout) throws IOException {
+            URL url = new URL(uri);
+            HttpURLConnection conn = (HttpURLConnection)url.openConnection();
+            conn.setRequestMethod(method);
+            conn.setConnectTimeout(timeout);
+            conn.setReadTimeout(timeout);
+            return conn;
+    }
+
+    private static byte[] read(InputStream is, int contentLen) throws IOException {
+        if (contentLen <= 0) {
+            int BUF_SIZE = 102400;
+            byte[] buf = new byte[102400];
+            ByteBuffer byteBuffer = ByteBuffer.allocate(102400);
+
+            int readed;
+            do {
+                if (byteBuffer.position() + 102400 > byteBuffer.capacity()) {
+                    byteBuffer = reallocByteBuffer(byteBuffer, byteBuffer.capacity() + 102400);
+                }
+
+                readed = is.read(buf, 0, 102400);
+                if (readed > 0) {
+                    byteBuffer.put(buf, 0, readed);
+                }
+            } while(readed != -1);
+
+            byte[] data = new byte[byteBuffer.position()];
+            System.arraycopy(byteBuffer.array(), 0, data, 0, byteBuffer.position());
+            return data;
+        } else {
+            byte[] data = new byte[contentLen];
+
+            int readed;
+            for(int remain = contentLen; remain > 0; remain -= readed) {
+                readed = is.read(data, contentLen - remain, remain);
+                if (readed == -1) {
+                    break;
+                }
+            }
+
+            return data;
+        }
+    }
+    private static ByteBuffer reallocByteBuffer(ByteBuffer buffer, int size) {
+        ByteBuffer newBuf = ByteBuffer.allocate(size);
+        newBuf.put(buffer.array(), 0, buffer.position());
+        return newBuf;
+    }
+    private static void close(HttpURLConnection conn) {
+        try {
+            if (conn == null) {
+                return;
+            }
+
+            conn.disconnect();
+        } catch (Exception var2) {
+            var2.printStackTrace();
+        }
+
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/IpUtils.java b/src/main/java/com/yunhai/userbase/utils/IpUtils.java
new file mode 100644
index 0000000..0235b0f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/IpUtils.java
@@ -0,0 +1,53 @@
+package com.yunhai.userbase.utils;
+
+import org.apache.commons.lang3.StringUtils;
+
+import javax.servlet.http.HttpServletRequest;
+
+/**
+ * 客户端 IP 获取工具。<br>
+ * 兼容反向代理场景：优先取 X-Forwarded-For 等代理头中的第一个真实 IP。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+public class IpUtils {
+
+    /** 常见的真实 IP 代理头。 */
+    private static final String[] PROXY_HEADERS = {
+            "X-Forwarded-For",
+            "Proxy-Client-IP",
+            "WL-Proxy-Client-IP",
+            "HTTP_CLIENT_IP",
+            "HTTP_X_FORWARDED_FOR",
+            "X-Real-IP"
+    };
+
+    private static final String UNKNOWN = "unknown";
+
+    /**
+     * 获取客户端真实 IP。<br>
+     * X-Forwarded-For 可能为逗号分隔的多级代理，取第一段。<br>
+     *
+     * @param request HTTP 请求
+     * @return 客户端 IP，获取失败返回 "unknown"
+     */
+    public static String getIpAddr(HttpServletRequest request) {
+        if (request == null) {
+            return UNKNOWN;
+        }
+        String ip = null;
+        for (String header : PROXY_HEADERS) {
+            ip = request.getHeader(header);
+            if (StringUtils.isNotBlank(ip) && !UNKNOWN.equalsIgnoreCase(ip)) {
+                int comma = ip.indexOf(',');
+                if (comma > 0) {
+                    ip = ip.substring(0, comma).trim();
+                }
+                return ip;
+            }
+        }
+        ip = request.getRemoteAddr();
+        return StringUtils.isBlank(ip) ? UNKNOWN : ip;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/NodeIdUtil.java b/src/main/java/com/yunhai/userbase/utils/NodeIdUtil.java
new file mode 100644
index 0000000..f8bd723
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/NodeIdUtil.java
@@ -0,0 +1,86 @@
+package com.yunhai.userbase.utils;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 课程节点 64 bit 复合 ID 工具类（无实体、纯静态）
+ * rootType  根节点类别【资源，辅导，题库，试卷，专项】
+ * nodeType  虚拟节点类型【根节点，教材（辅）目录节点，年级节点，教材知识树节点，真实节点】
+ * stage   学段【2小学 3初中 4高中】
+ * grade  年级 1-12
+ */
+
+public final class NodeIdUtil {
+
+    /* ===================== 位宽 ===================== */
+    private static final int ROOT_BITS  = 4;
+    private static final int TYPE_BITS  = 4;   // 原 biz
+    private static final int SUBJ_BITS  = 20;
+    private static final int STAGE_BITS = 4;
+    private static final int GRADE_BITS = 4;
+    private static final int NODE_BITS  = 28;
+
+    private static final long ROOT_MASK  = mask(ROOT_BITS);
+    private static final long TYPE_MASK  = mask(TYPE_BITS);
+    private static final long SUBJ_MASK  = mask(SUBJ_BITS);
+    private static final long STAGE_MASK = mask(STAGE_BITS);
+    private static final long GRADE_MASK = mask(GRADE_BITS);
+    private static final long NODE_MASK  = mask(NODE_BITS);
+
+    /* ===================== 编码 ===================== */
+    public static long encode(Integer rootType,
+                              String subject,
+                              Integer stage,
+                              Integer nodeType,
+                              Integer grade,
+                              Integer nodeId) {
+        int subNum = subjectToInt(subject);
+        long root  = (rootType == null ? 0 : rootType) & ROOT_MASK;
+        long type  = (nodeType == null ? 0 : nodeType) & TYPE_MASK;
+        long stageVal = (stage == null ? 0 : stage) & STAGE_MASK;
+        long gradeVal = (grade == null ? 0 : grade) & GRADE_MASK;
+        long nodeVal  = (nodeId == null ? 0 : nodeId) & NODE_MASK;
+
+        return root  << (TYPE_BITS + SUBJ_BITS + STAGE_BITS + GRADE_BITS + NODE_BITS)
+                | type  << (SUBJ_BITS + STAGE_BITS + GRADE_BITS + NODE_BITS)
+                | (long) subNum << (STAGE_BITS + GRADE_BITS + NODE_BITS)
+                | stageVal << (GRADE_BITS + NODE_BITS)
+                | gradeVal << NODE_BITS
+                | nodeVal;
+    }
+
+    /* ===================== 解码 ===================== */
+    public static Map<String, Object> decode(long compositeId) {
+        Map<String, Object> map = new HashMap<>(6);
+        int root   = (int) ((compositeId >>> (TYPE_BITS + SUBJ_BITS + STAGE_BITS + GRADE_BITS + NODE_BITS)) & ROOT_MASK);
+        int type   = (int) ((compositeId >>> (SUBJ_BITS + STAGE_BITS + GRADE_BITS + NODE_BITS)) & TYPE_MASK);
+        int subNum = (int) ((compositeId >>> (STAGE_BITS + GRADE_BITS + NODE_BITS)) & SUBJ_MASK);
+        int stage  = (int) ((compositeId >>> (GRADE_BITS + NODE_BITS)) & STAGE_MASK);
+        int grade  = (int) ((compositeId >>> (NODE_BITS)) & GRADE_MASK);
+        int nodeId = (int) (compositeId & NODE_MASK);
+
+        map.put("rootType", root == 0 ? null : root);
+        map.put("nodeType", type == 0 ? null : type);
+        map.put("subject",  intToSubject(subNum));
+        map.put("stage",    stage == 0 ? null : stage);
+        map.put("grade",    grade == 0 ? null : grade);
+        map.put("nodeId",   nodeId == 0 ? null : nodeId);
+        return map;
+    }
+
+    /* ===================== subject 工具 ===================== */
+    private static int subjectToInt(String subject) {
+        if (subject == null || !subject.startsWith("SUB")) return 0;
+        return Integer.parseUnsignedInt(subject.substring(3));
+    }
+
+    private static String intToSubject(int n) {
+        if (n == 0) return null;
+        return (n <= 6) ? "SUB0" + n : "SUB" + n;
+    }
+
+    private static long mask(int bits) { return (1L << bits) - 1; }
+
+    private NodeIdUtil() {}
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/utils/OperationLogResolver.java b/src/main/java/com/yunhai/userbase/utils/OperationLogResolver.java
new file mode 100644
index 0000000..7f493fd
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/OperationLogResolver.java
@@ -0,0 +1,85 @@
+package com.yunhai.userbase.utils;
+
+import com.yunhai.userbase.enums.LogLevel;
+
+import org.apache.commons.lang3.StringUtils;
+
+/**
+ * 操作日志级别与操作类型的自动判定。<br>
+ * 规则（贴合本项目的接口风格）：<br>
+ * - GET 一律记为「一般(查询)」、操作类型 QUERY；<br>
+ * - HTTP DELETE 方法或路径/方法名含 delete/del/remove 记为「重要(删除)」、操作类型 DELETE；<br>
+ * - 含 add/create/insert 记为操作类型 CREATE；<br>
+ * - 其余 POST/PUT 记为「次要(新增/编辑)」、操作类型 UPDATE。<br>
+ *
+ * @author chenx
+ * @date 2026/7/28
+ */
+public class OperationLogResolver {
+
+    private static final String[] DELETE_KEYWORDS = {"delete", "del", "remove"};
+    private static final String[] CREATE_KEYWORDS = {"add", "create", "insert"};
+
+    /**
+     * 判定日志级别。
+     *
+     * @param httpMethod  HTTP 方法（GET/POST/PUT/DELETE...）
+     * @param uri         请求路径
+     * @param methodName  被拦截的方法名
+     * @return 日志级别
+     */
+    public static LogLevel resolveLevel(String httpMethod, String uri, String methodName) {
+        if (StringUtils.isBlank(httpMethod)) {
+            return LogLevel.SECONDARY;
+        }
+        String method = httpMethod.toUpperCase();
+        if ("GET".equals(method)) {
+            return LogLevel.GENERAL;
+        }
+        if ("DELETE".equals(method)) {
+            return LogLevel.IMPORTANT;
+        }
+        if (containsAny(uri, methodName, DELETE_KEYWORDS)) {
+            return LogLevel.IMPORTANT;
+        }
+        return LogLevel.SECONDARY;
+    }
+
+    /**
+     * 判定操作类型（DELETE/CREATE/UPDATE/QUERY）。
+     *
+     * @param httpMethod  HTTP 方法
+     * @param uri         请求路径
+     * @param methodName  被拦截的方法名
+     * @return 操作类型字符串
+     */
+    public static String resolveOperationType(String httpMethod, String uri, String methodName) {
+        if (StringUtils.isBlank(httpMethod)) {
+            return "UPDATE";
+        }
+        String method = httpMethod.toUpperCase();
+        if ("GET".equals(method)) {
+            return "QUERY";
+        }
+        if ("DELETE".equals(method)) {
+            return "DELETE";
+        }
+        if (containsAny(uri, methodName, DELETE_KEYWORDS)) {
+            return "DELETE";
+        }
+        if (containsAny(uri, methodName, CREATE_KEYWORDS)) {
+            return "CREATE";
+        }
+        return "UPDATE";
+    }
+
+    private static boolean containsAny(String uri, String methodName, String[] keywords) {
+        String text = (StringUtils.lowerCase(uri) + " " + StringUtils.lowerCase(methodName));
+        for (String keyword : keywords) {
+            if (StringUtils.contains(text, keyword)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/OtherUtil.java b/src/main/java/com/yunhai/userbase/utils/OtherUtil.java
new file mode 100644
index 0000000..0945eb2
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/OtherUtil.java
@@ -0,0 +1,141 @@
+package com.yunhai.userbase.utils;
+
+import com.alibaba.fastjson.JSON;
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONException;
+import com.alibaba.fastjson.JSONObject;
+import com.yunhai.platform.utils.exception.DException;
+import com.yunhai.userbase.enums.SysRoleEnum;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+/*
+* 杂项公用方法集合
+* */
+public class OtherUtil {
+
+    /**
+     * 十六进制转字符串
+     * @param hex
+     * @return
+     */
+    public final static String hexToString(String hex) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < hex.length(); i += 2) {
+            String hexSubstring = hex.substring(i, i + 2);
+            int decimalValue = Integer.parseInt(hexSubstring, 16);
+            sb.append((char) decimalValue);
+        }
+        return sb.toString();
+    }
+    
+    /**
+    * @Description: 判断字符串能否序列化
+    * @Author: chenx
+    * @Date: 2023/4/20
+    */
+    public final static boolean isJSONValid(String str) {
+        try {
+            JSONObject.parse(str);
+        } catch (JSONException ex) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * @Description: 判断字符串能否序列化为json数组
+     * @Author: chenx
+     * @Date: 2023/4/20
+     */
+    public  final  static boolean isJsonArray(String str) {
+        if (!isJSONValid(str)) return false;
+        try {
+            Object object = JSON.parse(str);
+            return object instanceof JSONArray;
+        } catch (JSONException ex) {
+            return false;
+        }
+    }
+
+    /**
+     * @Description: 数组深拷贝
+     * @Author: chenx
+     * @Date: 2023/4/20
+     */
+    public  final  static <T> List<T> deepCopy(List<T> src, Class<T> clazz) {
+        String jsonStr=JSON.toJSONString(src);
+        if (!isJsonArray(jsonStr)) return src;
+        return  JSONArray.parseArray(jsonStr,clazz);
+    }
+
+    /**
+     * @Description: 逗号分隔字符串转List数组
+     * @Author: chenx
+     * @Date: 2023/4/20
+     */
+    public final static List<Integer> SplitToList(String idsStr) {
+        return Arrays.stream(idsStr.split(",")).map(s -> Integer.parseInt(s.trim())).collect(Collectors.toList());
+    }
+
+    /**
+     * 判断角色是否为管理员（SysRoleEnum.ADMIN = 7）。
+     * 注：方法名历史遗留为 isAdminById，语义即「是否具备管理员权限」。
+     */
+    public final static Boolean isAdminById(Integer roleId){
+        return roleId != null && SysRoleEnum.ADMIN.getKey().equals(roleId);
+    }
+
+
+    public static JSONObject getDataOrThrow(String result) {
+        JSONObject root = JSON.parseObject(result);
+        if (root.getIntValue("code") != 0) {
+            throw new DException("接口异常: " + root.getString("msg"));
+        }
+        return root.getJSONObject("data");
+    }
+
+    /**
+     * result 里 data 直接就是数组 []，返回 List<JSONObject>
+     */
+    public static List<JSONObject> getDataArray(String result) {
+        JSONObject root = JSON.parseObject(result);
+        if (root.getIntValue("code") != 0) {
+            throw new DException("接口异常: " + root.getString("msg"));
+        }
+        // data 本身就是 JSONArray
+        return root.getJSONArray("data").toJavaList(JSONObject.class);
+    }
+
+
+    /**
+     * 根据 code 最大值返回学段
+     * 1~6  → 2
+     * 7~9  → 3
+     * 10~12→ 4
+     */
+    public static int calcStage(List<Integer> codes) {
+        if (codes == null || codes.isEmpty()) {
+            throw new IllegalArgumentException("codes 不能为空");
+        }
+        int max = codes.stream().max(Integer::compareTo).get();
+        if (max <= 6) return 2;
+        if (max <= 9) return 3;
+        return 4;
+    }
+
+
+    public static String getUUID(){
+        return UUID.randomUUID().toString().replace("-","");
+    }
+
+
+    public static  Integer parseIntNullable(Object val) {
+        return val == null ? null : Integer.parseInt(val.toString());
+    }
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/PageUtils.java b/src/main/java/com/yunhai/userbase/utils/PageUtils.java
new file mode 100644
index 0000000..00b0c2f
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/PageUtils.java
@@ -0,0 +1,53 @@
+package com.yunhai.userbase.utils;
+
+
+import com.yunhai.userbase.model.BasePageQuery;
+import com.yunhai.userbase.model.BasePageResult;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Sort;
+
+/**
+ * @author chenx
+ * @date 2026/7/21 21:54
+ * @description 分页辅助类
+ */
+public class PageUtils {
+
+    private PageUtils() {
+    }
+
+    /**
+     * 将 BasePageQuery 转换为 Spring Data JPA 的 Pageable。<br>
+     *
+     * @param query 前端分页参数（pageIndex 从 1 开始）
+     * @param sort  排序规则
+     * @return Pageable
+     */
+    public static Pageable toPageable(BasePageQuery query, Sort sort) {
+        int page = Math.max(query.getPageIndex() - 1, 0);
+        int size = Math.max(query.getPageSize(), 1);
+        if(sort==null)sort=Sort.unsorted();
+        return PageRequest.of(page, size, sort);
+    }
+
+    /**
+     * 将 Spring Data 的 Page 装配为统一分页响应外壳 BasePageResult。<br>
+     * 页码约定：Spring Data 的 page 从 0 起，对外暴露的 pageIndex 从 1 起。<br>
+     *
+     * @param page 仓储/Service 返回的分页结果
+     * @param <T>  数据元素类型
+     * @return 统一分页响应
+     */
+    public static <T> BasePageResult<T> toResult(Page<T> page) {
+        return new BasePageResult<T>(
+                page.getContent(),
+                (int) page.getTotalElements(),
+                page.getNumber() + 1,
+                page.getSize(),
+                page.getTotalPages(),
+                page.hasNext()
+        );
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/PermissionBits.java b/src/main/java/com/yunhai/userbase/utils/PermissionBits.java
new file mode 100644
index 0000000..9f97727
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/PermissionBits.java
@@ -0,0 +1,43 @@
+package com.yunhai.userbase.utils;
+
+/**
+ * @author chenx
+ * @date 2025/12/29 9:47
+ * @description 权限bit类型许可帮助类
+ */
+public final class PermissionBits {
+
+    // 位掩码
+    public static final int CREATE = 1;   // 0001
+    public static final int UPDATE = 2;   // 0010
+    public static final int MOVE   = 4;   // 0100
+    public static final int DELETE = 8;   // 1000
+
+    /** 布尔数组→二进制 */
+    public static byte pack(boolean canCreate, boolean canUpdate,
+                            boolean canMove,   boolean canDelete) {
+        int value = 0;
+        if (canCreate) value |= CREATE;
+        if (canUpdate) value |= UPDATE;
+        if (canMove)   value |= MOVE;
+        if (canDelete) value |= DELETE;
+        return (byte) value;          // 范围 0~15，够用
+    }
+
+    /** 二进制→布尔数组，返回顺序与上面一致 */
+    public static boolean[] unpack(byte packed) {
+        boolean[] arr = new boolean[4];
+        arr[0] = (packed & CREATE) != 0;   // 新增
+        arr[1] = (packed & UPDATE) != 0;   // 编辑
+        arr[2] = (packed & MOVE)   != 0;   // 移动
+        arr[3] = (packed & DELETE) != 0;   // 删除
+        return arr;
+    }
+
+    /* 可选：校验是否拥有某权限 */
+    public static boolean has(int packed, int permission) {
+        return (packed & permission) == permission;
+    }
+
+    private PermissionBits() {}
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/RedisConstants.java b/src/main/java/com/yunhai/userbase/utils/RedisConstants.java
new file mode 100644
index 0000000..1e86452
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/RedisConstants.java
@@ -0,0 +1,10 @@
+package com.yunhai.userbase.utils;
+
+public class RedisConstants {
+
+    private static final String CachePrefix = "yunhai.userbase.";
+
+    //学校目录树
+    public static final String SCH_ROOT_TREE =CachePrefix + "sch_root_tree";
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/RedisUtil.java b/src/main/java/com/yunhai/userbase/utils/RedisUtil.java
new file mode 100644
index 0000000..b1abccc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/RedisUtil.java
@@ -0,0 +1,868 @@
+package com.yunhai.userbase.utils;
+
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.stereotype.Component;
+import org.springframework.util.CollectionUtils;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.TimeUnit;
+
+
+/**
+ * Redis工具类
+ */
+
+@Component
+public final class RedisUtil {
+
+
+    @Autowired
+    private RedisTemplate redisTemplate;
+
+
+    /**
+     * 指定缓存失效时间
+     *
+     * @param key  键
+     * @param time 时间(秒)
+     * @return
+     */
+
+    public boolean expire(String key, long time) {
+
+        try {
+
+            if (time > 0) {
+
+                redisTemplate.expire(key, time, TimeUnit.SECONDS);
+
+            }
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 根据key 获取过期时间
+     *
+     * @param key 键 不能为null
+     * @return 时间(秒) 返回0代表为永久有效
+     */
+
+    public long getExpire(String key) {
+
+        return redisTemplate.getExpire(key, TimeUnit.SECONDS);
+
+    }
+
+
+    /**
+     * 判断key是否存在
+     *
+     * @param key 键
+     * @return true 存在 false不存在
+     */
+
+    public boolean hasKey(String key) {
+
+        try {
+
+            return redisTemplate.hasKey(key);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 删除缓存
+     *
+     * @param key 可以传一个值 或多个
+     */
+
+    @SuppressWarnings("unchecked")
+
+    public void del(String... key) {
+
+        if (key != null && key.length > 0) {
+
+            if (key.length == 1) {
+
+                redisTemplate.delete(key[0]);
+
+            } else {
+
+                redisTemplate.delete(CollectionUtils.arrayToList(key));
+
+            }
+
+        }
+
+    }
+
+
+    // ============================String=============================
+
+    /**
+     * 普通缓存获取
+     *
+     * @param key 键
+     * @return 值
+     */
+
+    public Object get(String key) {
+
+        return key == null ? null : redisTemplate.opsForValue().get(key);
+
+    }
+
+
+    /**
+     * 普通缓存放入
+     *
+     * @param key   键
+     * @param value 值
+     * @return true成功 false失败
+     */
+
+    public boolean set(String key, Object value) {
+
+        try {
+
+            redisTemplate.opsForValue().set(key, value);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+
+    }
+
+
+    /**
+     * 普通缓存放入并设置时间
+     *
+     * @param key   键
+     * @param value 值
+     * @param time  时间(秒) time要大于0 如果time小于等于0 将设置无限期
+     * @return true成功 false 失败
+     */
+
+    public boolean set(String key, Object value, long time) {
+
+        try {
+
+            if (time > 0) {
+
+                redisTemplate.opsForValue().set(key, value, time, TimeUnit.SECONDS);
+
+            } else {
+
+                set(key, value);
+
+            }
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 递增
+     *
+     * @param key   键
+     * @param delta 要增加几(大于0)
+     * @return
+     */
+
+    public long incr(String key, long delta) {
+
+        if (delta < 0) {
+
+            throw new RuntimeException("递增因子必须大于");
+
+        }
+
+        return redisTemplate.opsForValue().increment(key, delta);
+
+    }
+
+
+    /**
+     * 递减
+     *
+     * @param key   键
+     * @param delta 要减少几(小于0)
+     * @return
+     */
+
+    public long decr(String key, long delta) {
+
+        if (delta < 0) {
+
+            throw new RuntimeException("递减因子必须大于");
+
+        }
+
+        return redisTemplate.opsForValue().increment(key, -delta);
+
+    }
+
+
+    // ================================Map=================================
+
+    /**
+     * HashGet
+     *
+     * @param key  键 不能为null
+     * @param item 项 不能为null
+     * @return 值
+     */
+
+    public Object hget(String key, String item) {
+
+        return redisTemplate.opsForHash().get(key, item);
+
+    }
+
+
+    /**
+     * 获取hashKey对应的所有键值
+     *
+     * @param key 键
+     * @return 对应的多个键值
+     */
+
+    public Map<Object, Object> hmget(String key) {
+
+        return redisTemplate.opsForHash().entries(key);
+
+    }
+
+
+    /**
+     * HashSet
+     *
+     * @param key 键
+     * @param map 对应多个键值
+     * @return true 成功 false 失败
+     */
+
+    public boolean hmset(String key, Map<String, Object> map) {
+
+        try {
+
+            redisTemplate.opsForHash().putAll(key, map);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+    /**
+     * HashSet 并设置时间
+     *
+     * @param key  键
+     * @param map  对应多个键值
+     * @param time 时间(秒)
+     * @return true成功 false失败
+     */
+
+    public boolean hmset(String key, Map<String, Object> map, long time) {
+
+        try {
+
+            redisTemplate.opsForHash().putAll(key, map);
+
+            if (time > 0) {
+
+                expire(key, time);
+
+            }
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 向一张hash表中放入数据,如果不存在将创建
+     *
+     * @param key   键
+     * @param item  项
+     * @param value 值
+     * @return true 成功 false失败
+     */
+
+    public boolean hset(String key, String item, Object value) {
+
+        try {
+
+            redisTemplate.opsForHash().put(key, item, value);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 向一张hash表中放入数据,如果不存在将创建
+     *
+     * @param key   键
+     * @param item  项
+     * @param value 值
+     * @param time  时间(秒) 注意:如果已存在的hash表有时间,这里将会替换原有的时间
+     * @return true 成功 false失败
+     */
+
+    public boolean hset(String key, String item, Object value, long time) {
+
+        try {
+
+            redisTemplate.opsForHash().put(key, item, value);
+
+            if (time > 0) {
+
+                expire(key, time);
+
+            }
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 删除hash表中的值
+     *
+     * @param key  键 不能为null
+     * @param item 项 可以使多个 不能为null
+     */
+
+    public void hdel(String key, Object... item) {
+
+        redisTemplate.opsForHash().delete(key, item);
+
+    }
+
+    /**
+     * 判断hash表中是否有该项的值
+     *
+     * @param key  键 不能为null
+     * @param item 项 不能为null
+     * @return true 存在 false不存在
+     */
+
+    public boolean hHasKey(String key, String item) {
+
+        return redisTemplate.opsForHash().hasKey(key, item);
+
+    }
+
+
+    /**
+     * hash递增 如果不存在,就会创建一个 并把新增后的值返回
+     *
+     * @param key  键
+     * @param item 项
+     * @param by   要增加几(大于)
+     * @return
+     */
+
+    public double hincr(String key, String item, double by) {
+
+        return redisTemplate.opsForHash().increment(key, item, by);
+
+    }
+
+
+    /**
+     * hash递减
+     *
+     * @param key  键
+     * @param item 项
+     * @param by   要减少记(小于)
+     * @return
+     */
+
+    public double hdecr(String key, String item, double by) {
+
+        return redisTemplate.opsForHash().increment(key, item, -by);
+
+    }
+
+
+    // ============================set=============================
+
+    /**
+     * 根据key获取Set中的所有值
+     *
+     * @param key 键
+     * @return
+     */
+
+    public Set<Object> sGet(String key) {
+
+        try {
+
+            return redisTemplate.opsForSet().members(key);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return null;
+
+        }
+
+    }
+
+
+    /**
+     * 根据value从一个set中查询,是否存在
+     *
+     * @param key   键
+     * @param value 值
+     * @return true 存在 false不存在
+     */
+
+    public boolean sHasKey(String key, Object value) {
+
+        try {
+
+            return redisTemplate.opsForSet().isMember(key, value);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 将数据放入set缓存
+     *
+     * @param key    键
+     * @param values 值 可以是多个
+     * @return 成功个数
+     */
+
+    public long sSet(String key, Object... values) {
+
+        try {
+
+            return redisTemplate.opsForSet().add(key, values);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+
+    /**
+     * 将set数据放入缓存
+     *
+     * @param key    键
+     * @param time   时间(秒)
+     * @param values 值 可以是多个
+     * @return 成功个数
+     */
+
+    public long sSetAndTime(String key, long time, Object... values) {
+
+        try {
+
+            Long count = redisTemplate.opsForSet().add(key, values);
+
+            if (time > 0)
+
+                expire(key, time);
+
+            return count;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+
+    /**
+     * 获取set缓存的长度
+     *
+     * @param key 键
+     * @return
+     */
+
+    public long sGetSetSize(String key) {
+
+        try {
+
+            return redisTemplate.opsForSet().size(key);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+
+    /**
+     * 移除值为value的
+     *
+     * @param key    键
+     * @param values 值 可以是多个
+     * @return 移除的个数
+     */
+
+    public long setRemove(String key, Object... values) {
+
+        try {
+
+            Long count = redisTemplate.opsForSet().remove(key, values);
+
+            return count;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+    // ===============================list=================================
+
+
+    /**
+     * 获取list缓存的内容
+     *
+     * @param key   键
+     * @param start 开始
+     * @param end   结束 0 到 -1代表所有值
+     * @return
+     */
+
+    public List<Object> lGet(String key, long start, long end) {
+
+        try {
+
+            return redisTemplate.opsForList().range(key, start, end);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return null;
+
+        }
+
+    }
+
+
+    /**
+     * 获取list缓存的长度
+     *
+     * @param key 键
+     * @return
+     */
+
+    public long lGetListSize(String key) {
+
+        try {
+
+            return redisTemplate.opsForList().size(key);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+
+    /**
+     * 通过索引 获取list中的值
+     *
+     * @param key   键
+     * @param index 索引 index>=0时， 0 表头，1 第二个元素，依次类推；index<0时，-1，表尾，-2倒数第二个元素，依次类推
+     *             * @return
+     */
+
+    public Object lGetIndex(String key, long index) {
+
+        try {
+
+            return redisTemplate.opsForList().index(key, index);
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return null;
+
+        }
+
+    }
+
+
+    /**
+     * 将list放入缓存
+     *
+     * @param key   键
+     * @param value 值
+     * @return
+     */
+
+    public boolean lSet(String key, Object value) {
+
+        try {
+
+            redisTemplate.opsForList().rightPush(key, value);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 将list放入缓存
+     *
+     * @param key   键
+     * @param value 值
+     * @param time  时间(秒)
+     * @return
+     */
+
+    public boolean lSet(String key, Object value, long time) {
+
+        try {
+
+            redisTemplate.opsForList().rightPush(key, value);
+
+            if (time > 0)
+
+                expire(key, time);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 将list放入缓存
+     *
+     * @param key   键
+     * @param value 值
+     * @return
+     */
+
+    public boolean lSet(String key, List<Object> value) {
+
+        try {
+
+            redisTemplate.opsForList().rightPushAll(key, value);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 将list放入缓存
+     *
+     * @param key   键
+     * @param value 值
+     * @param time  时间(秒)
+     * @return
+     */
+
+    public boolean lSet(String key, List<Object> value, long time) {
+
+        try {
+
+            redisTemplate.opsForList().rightPushAll(key, value);
+
+            if (time > 0)
+
+                expire(key, time);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 根据索引修改list中的某条数据
+     *
+     * @param key   键
+     * @param index 索引
+     * @param value 值
+     * @return
+     */
+
+    public boolean lUpdateIndex(String key, long index, Object value) {
+
+        try {
+
+            redisTemplate.opsForList().set(key, index, value);
+
+            return true;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return false;
+
+        }
+
+    }
+
+
+    /**
+     * 移除N个值为value
+     *
+     * @param key   键
+     * @param count 移除多少个
+     * @param value 值
+     * @return 移除的个数
+     */
+
+    public long lRemove(String key, long count, Object value) {
+
+        try {
+
+            Long remove = redisTemplate.opsForList().remove(key, count, value);
+
+            return remove;
+
+        } catch (Exception e) {
+
+            e.printStackTrace();
+
+            return 0;
+
+        }
+
+    }
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/SensitiveDataMasker.java b/src/main/java/com/yunhai/userbase/utils/SensitiveDataMasker.java
new file mode 100644
index 0000000..0f6a4dc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/SensitiveDataMasker.java
@@ -0,0 +1,119 @@
+package com.yunhai.userbase.utils;
+
+import com.alibaba.fastjson.JSON;
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
+import lombok.extern.slf4j.Slf4j;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Locale;
+
+/**
+ * 敏感字段脱敏工具。<br>
+ * 开放接口日志在入库前，请求参数与响应必须经过本工具：命中敏感字段名（忽略大小写）
+ * 的键值一律替换为 {@code ***}，防止明文密码/密钥/令牌写入日志库。<br>
+ * 实现基于 fastjson 递归遍历（不引新依赖）；非 JSON 文本原样返回并打 warn 日志。<br>
+ *
+ * @author chenx
+ * @date 2026/8/20
+ */
+@Slf4j
+public class SensitiveDataMasker {
+
+    /**
+     * 敏感字段名名单（按小写匹配，命中即掩码）。
+     */
+    private static final List<String> SENSITIVE_FIELDS = Arrays.asList(
+            "password", "oldpassword", "newpassword", "confirmpassword",
+            "appsecret", "secret", "token", "accesskey", "accesskeyid", "accesskeysecret");
+
+    /**
+     * 掩码占位符。
+     */
+    public static final String MASK = "***";
+
+    private SensitiveDataMasker() {
+    }
+
+    /**
+     * 对任意对象做脱敏：先序列化为 JSON 字符串，再递归掩码敏感字段。<br>
+     * 序列化失败或对象本身非 JSON 结构时，返回 null（由调用方决定降级处理）。
+     *
+     * @param source 待脱敏对象（可为 null）
+     * @return 脱敏后的 JSON 字符串；输入为 null 返回 null
+     */
+    public static String maskObject(Object source) {
+        if (source == null) {
+            return null;
+        }
+        String json = JSON.toJSONString(source);
+        if (json == null || json.isEmpty()) {
+            return json;
+        }
+        return maskJson(json);
+    }
+
+    /**
+     * 对 JSON 字符串递归脱敏（含嵌套对象/数组）。<br>
+     * 解析失败（非 JSON）时原样返回并 warn。
+     *
+     * @param json JSON 字符串（可为 null/空）
+     * @return 脱敏后的 JSON 字符串；输入为 null 返回 null
+     */
+    public static String maskJson(String json) {
+        if (json == null) {
+            return null;
+        }
+        try {
+            Object parsed = JSON.parse(json);
+            if (parsed == null) {
+                return json;
+            }
+            maskValue(parsed);
+            return JSON.toJSONString(parsed);
+        } catch (Exception e) {
+            // 非 JSON 文本（如错误消息）不脱敏，原样返回
+            log.warn("敏感字段脱敏跳过（非 JSON）, len={}", json.length());
+            return json;
+        }
+    }
+
+    /**
+     * 递归遍历 JSON 结构，命中敏感字段名的键值替换为掩码。
+     */
+    private static void maskValue(Object value) {
+        if (value instanceof JSONObject) {
+            JSONObject obj = (JSONObject) value;
+            for (String key : obj.keySet()) {
+                Object v = obj.get(key);
+                if (v instanceof JSONObject || v instanceof JSONArray) {
+                    maskValue(v);
+                } else if (isSensitive(key)) {
+                    obj.put(key, MASK);
+                }
+            }
+        } else if (value instanceof JSONArray) {
+            JSONArray arr = (JSONArray) value;
+            for (Object item : arr) {
+                maskValue(item);
+            }
+        }
+    }
+
+    /**
+     * 判断字段名是否命中敏感名单（忽略大小写）。
+     */
+    private static boolean isSensitive(String key) {
+        if (key == null || key.isEmpty()) {
+            return false;
+        }
+        String lower = key.toLowerCase(Locale.ROOT);
+        for (String field : SENSITIVE_FIELDS) {
+            if (lower.contains(field)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/SubjectDict.java b/src/main/java/com/yunhai/userbase/utils/SubjectDict.java
new file mode 100644
index 0000000..56ff016
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/SubjectDict.java
@@ -0,0 +1,78 @@
+package com.yunhai.userbase.utils;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * @author chenx
+ * @date 2025/12/23 9:26
+ * @description 学科Code映射表 静态字典
+ */
+
+public final class SubjectDict {
+
+    /* ---------- 只读缓存 ---------- */
+    private static final Map<String, String> NAME_TO_CODE;
+    private static final Map<String, String> CODE_TO_NAME;
+
+    /* ---------- 初始化 ---------- */
+    static {
+        Map<String, String> tmp =new LinkedHashMap<>(32);
+        tmp.put("语文", "SUB01");
+        tmp.put("数学", "SUB02");
+        tmp.put("英语", "SUB03");
+        tmp.put("物理", "SUB04");
+        tmp.put("化学", "SUB05");
+        tmp.put("生物", "SUB06");
+        tmp.put("信息", "SUB7");
+        tmp.put("品德", "SUB8");
+        tmp.put("体育", "SUB9");
+        tmp.put("美术", "SUB10");
+        tmp.put("科学", "SUB11");
+        tmp.put("劳技", "SUB12");
+        tmp.put("历史", "SUB13");
+        tmp.put("地理", "SUB14");
+        tmp.put("政治", "SUB15");
+        tmp.put("音乐", "SUB604741");
+        tmp.put("心理", "SUB605021");
+        tmp.put("艺术", "SUB605101");
+        tmp.put("道法", "SUB605341");
+        tmp.put("社会", "SUB605371");
+
+        NAME_TO_CODE = Collections.unmodifiableMap(tmp);
+        CODE_TO_NAME = Collections.unmodifiableMap(invert(tmp));
+    }
+
+    private static Map<String, String> invert(Map<String, String> source) {
+        Map<String, String> target = new HashMap<>(source.size());
+        source.forEach((k, v) -> target.put(v, k));
+        return target;
+    }
+
+    /* ---------- 工具方法 ---------- */
+
+    /** 中文名称 -> code */
+    public static String toCode(String name) {
+        return NAME_TO_CODE.get(name);
+    }
+
+    /** code -> 中文名称 */
+    public static String toName(String code) {
+        return CODE_TO_NAME.get(code);
+    }
+
+    public static boolean containsName(String name) {
+        return NAME_TO_CODE.containsKey(name);
+    }
+
+    /** 只读视图 */
+    public static Map<String, String> allName2Code() {
+        return NAME_TO_CODE;
+    }
+
+    private SubjectDict() {
+        // 禁止实例化
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/yunhai/userbase/utils/TimeUtils.java b/src/main/java/com/yunhai/userbase/utils/TimeUtils.java
new file mode 100644
index 0000000..88f6c61
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/TimeUtils.java
@@ -0,0 +1,273 @@
+package com.yunhai.userbase.utils;
+
+
+import cn.hutool.core.date.DateTime;
+import cn.hutool.core.date.DateUtil;
+import com.yunhai.userbase.model.StartEndDate;
+
+import java.text.DateFormat;
+import java.text.SimpleDateFormat;
+import java.util.ArrayList;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.List;
+
+public class TimeUtils {
+	private static SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
+	private static SimpleDateFormat format1 = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+	private static SimpleDateFormat format2 = new SimpleDateFormat("yyyy/MM/dd");
+
+
+	/*
+	 * 毫秒转化时分秒毫秒
+	 */
+	public static String formatTime(Long ms) {
+		Integer ss = 1000;
+		Integer mi = ss * 60;
+		Integer hh = mi * 60;
+		Integer dd = hh * 24;
+
+		Long day = ms / dd;
+		Long hour = (ms - day * dd) / hh;
+		Long minute = (ms - day * dd - hour * hh) / mi;
+		Long second = (ms - day * dd - hour * hh - minute * mi) / ss;
+		Long milliSecond = ms - day * dd - hour * hh - minute * mi - second * ss;
+
+		StringBuffer sb = new StringBuffer();
+		if(day > 0) {
+			sb.append(day+"天");
+		}
+		if(hour > 0) {
+			sb.append(hour+"小时");
+		}
+		if(minute > 0) {
+			sb.append(minute+"分");
+		}
+		if(second > 0) {
+			sb.append(second+"秒");
+		}
+		/*if(milliSecond > 0) {
+			sb.append(milliSecond+"毫秒");
+		}*/
+		return sb.toString();
+	}
+	/**
+	 * 获取过去几天内的日期数组
+	 * @param intervals      intervals天内
+	 * @return              日期数组
+	 */
+	public static ArrayList<String> getDays(int intervals) {
+		ArrayList<String> pastDaysList = new ArrayList<>();
+		for (int i = intervals -1; i >= 0; i--) {
+			pastDaysList.add(getPastDate(i));
+		}
+		return pastDaysList;
+	}
+	/**
+	 * 获取过去第几天的日期
+	 * @param past
+	 * @return
+	 */
+	public static String getPastDate(int past) {
+		Calendar calendar = Calendar.getInstance();
+		calendar.set(Calendar.DAY_OF_YEAR, calendar.get(Calendar.DAY_OF_YEAR) - past);
+		Date today = calendar.getTime();
+		SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
+		String result = format.format(today);
+		return result;
+	}
+
+	/**
+	 * 获取两个日期之间的天数
+	 * @param start
+	 * @param end
+	 * @return
+	 */
+	public static List<String> getBetweenDates(Date start, Date end) {
+		List<String> days = new ArrayList<String>();
+
+		DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
+		try {
+
+			Calendar tempStart = Calendar.getInstance();
+			tempStart.setTime(start);
+
+			Calendar tempEnd = Calendar.getInstance();
+			tempEnd.setTime(end);
+			tempEnd.add(Calendar.DATE, 0);// 日期加1(包含结束)
+			while (tempStart.before(tempEnd)) {
+				days.add(dateFormat.format(tempStart.getTime()));
+				tempStart.add(Calendar.DAY_OF_YEAR, 1);
+			}
+
+		} catch (Exception e) {
+			e.printStackTrace();
+		}
+		return days;
+	}
+
+
+	/**
+	 * 根据俩日期，获取中间存在某周的周一、周日
+	 */
+	public static List<StartEndDate> getMonAndSunWeek(Date startDate, Date endDate) {
+		List<StartEndDate> list = new ArrayList<>();
+		Date tmp = startDate;
+		int ii = 0;
+		try {
+			while (tmp.before(endDate)) {
+				StartEndDate pram = new StartEndDate();
+
+				Calendar calendar = Calendar.getInstance();
+				if (ii == 0) {
+					String dateStr = format.format(startDate);
+					Date date = format.parse(dateStr);
+					calendar.setTime(date);
+
+					if (calendar.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)
+						calendar.add(Calendar.DAY_OF_YEAR, -1);
+				} else {
+					calendar.setTime(tmp);
+					calendar.add(Calendar.DATE, 1);
+				}
+				int i = calendar.get(Calendar.DAY_OF_WEEK) - 1;
+				calendar.add(Calendar.DATE, -i + 1);
+				pram.setStartDate(format1.parse(format.format(calendar.getTime()) + " 00:00:00"));//周一
+
+				calendar.add(Calendar.DATE, 6);
+				Date dd = format1.parse(format.format(calendar.getTime()) + " 23:59:59");
+				pram.setEndDate(dd);//周日
+				tmp = dd;
+
+//				System.out.println("ii===========" + ii);
+				ii++;
+				list.add(pram);
+			}
+		} catch (Exception e) {
+		}
+		return list;
+	}
+
+	/**
+	 * 根据俩日期，获取中间存在某月的月初、月末
+	 */
+	public static List<StartEndDate> getBeginAndLastMonth(Date startDate,Date endDate) {
+		List<StartEndDate> list = new ArrayList<>();
+		Date tmp = startDate;
+		int ii = 0;
+		try {
+			while (tmp.before(endDate)) {
+				StartEndDate pram = new StartEndDate();
+
+				Calendar calendar = Calendar.getInstance();
+				if (ii == 0) {
+					String dateStr = format.format(startDate);
+					Date date = format.parse(dateStr);
+					calendar.setTime(date);
+				} else {
+					calendar.setTime(tmp);
+					calendar.add(Calendar.DATE, 1);
+				}
+
+				calendar.add(Calendar.MONTH, 0);
+				calendar.set(Calendar.DAY_OF_MONTH,1);//设置为1号,当前日期既为本月第一天
+				pram.setStartDate(format1.parse(format.format(calendar.getTime()) + " 00:00:00"));//周一
+
+
+				//获取当前月最后一天
+				calendar.set(Calendar.DAY_OF_MONTH, calendar.getActualMaximum(Calendar.DAY_OF_MONTH));
+				Date dd = format1.parse(format.format(calendar.getTime()) + " 23:59:59");
+				pram.setEndDate(dd);//月末
+				tmp = dd;
+
+				ii++;
+				list.add(pram);
+			}
+		} catch (Exception e) {
+		}
+		return list;
+	}
+	/**
+	 * 根据俩日期，获取中间存
+	 */
+	public static List<StartEndDate> getBeiginAndLastTerm(Date startDate,Date endDate) {
+		List<StartEndDate> list = new ArrayList<>();
+		StartEndDate _pram = new StartEndDate();
+
+		_pram.setStartDate(startDate);
+		_pram.setEndDate(endDate);
+
+		list.add(_pram);
+
+		return list;
+	}
+
+
+
+	/**
+	 * 指定某日期，在某段时间内是第几周
+	 */
+	public static Integer getWeek(String sDate1,String eDate1,String date1) {
+		DateTime sDate = DateUtil.parseDate(sDate1);
+		DateTime eDate = DateUtil.parseDate(eDate1);
+		DateTime date = DateUtil.parseDate(date1);
+		int week = 1;
+		if (DateUtil.isIn(date, sDate, eDate)) {
+			//获取某周的结束时间（周日）
+			Date endDateOfWeek = DateUtil.endOfWeek(sDate);
+			while (!DateUtil.isIn(date, sDate, endDateOfWeek)) {
+				++week;
+				//获取某周的结束时间（周日）
+				endDateOfWeek = DateUtil.endOfWeek(DateUtil.offsetDay(endDateOfWeek, 1));
+			}
+			return week;
+		}
+		return null;
+	}
+
+
+	/**
+	 * 指定某日期，在某段时间内是第几月
+	 */
+	public static Integer getMonth(String sDate1,String eDate1,String date1) {
+		DateTime sDate = DateUtil.parseDate(sDate1);
+		DateTime eDate = DateUtil.parseDate(eDate1);
+		DateTime date = DateUtil.parseDate(date1);
+		int month = 1;
+		if (DateUtil.isIn(date, sDate, eDate)) {
+			//获取某月的结束时间（月末）
+			Date endDateOfMonth = DateUtil.endOfMonth(sDate);
+			while (!DateUtil.isIn(date, sDate, endDateOfMonth)) {
+				++month;
+				endDateOfMonth = DateUtil.endOfMonth(DateUtil.offsetDay(endDateOfMonth, 1));
+			}
+			return month;
+		}
+		return null;
+	}
+
+	/**
+	 * 获取学年日期区间
+	 */
+	public  static  String getSchoolYear(Integer year) {
+		Calendar tempStart = Calendar.getInstance();
+		tempStart.set(year, 8, 1, 0, 0, 0);
+		Calendar tempStart2 =(Calendar)tempStart.clone();
+		tempStart2.add(Calendar.YEAR,1);
+		tempStart2.add(Calendar.DAY_OF_MONTH,-1);
+		return format2.format(tempStart.getTime()) + "-" + format2.format(tempStart2.getTime());
+	}
+	/**
+	 * 获取自然年日期区间
+	 */
+	public  static  String getNatureYear(Integer year) {
+		Calendar tempStart = Calendar.getInstance();
+		tempStart.set(year, 0, 1, 0, 0, 0);
+		Calendar tempStart2 =(Calendar)tempStart.clone();
+		tempStart2.add(Calendar.YEAR,1);
+		tempStart2.add(Calendar.DATE,-1);
+		return format2.format(tempStart.getTime()) + "-" + format2.format(tempStart2.getTime());
+	}
+
+
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/ValidatorUtil.java b/src/main/java/com/yunhai/userbase/utils/ValidatorUtil.java
new file mode 100644
index 0000000..cb42b09
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/ValidatorUtil.java
@@ -0,0 +1,134 @@
+package com.yunhai.userbase.utils;
+
+import org.apache.commons.lang3.StringUtils;
+
+import java.util.regex.Pattern;
+
+/**
+ * 统一校验工具：手机号、身份证、密码强度等基于正则的规则集中在此类维护。<br>
+ * 所有正则常量私有，只暴露语义化的校验方法，便于复用与统一调整。<br>
+ *
+ * @author chenx
+ * @date 2026/7/23
+ * @description 统一正则校验工具
+ */
+public final class ValidatorUtil {
+
+    /** 中国大陆手机号：1 开头，第二位 3-9，共 11 位。 */
+    private static final Pattern PHONE = Pattern.compile("^1[3-9]\\d{9}$");
+
+    /** 18 位居民身份证结构：6 位地址码 + 8 位出生日期(19/20xx) + 3 位顺序码 + 1 位校验位(数字或 X)。 */
+    private static final Pattern ID_CARD_18 = Pattern.compile(
+            "^[1-9]\\d{5}(18|19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[0-9Xx]$");
+
+    /** 是否包含字母。 */
+    private static final Pattern HAS_LETTER = Pattern.compile("[a-zA-Z]");
+
+    /** 是否包含数字。 */
+    private static final Pattern HAS_DIGIT = Pattern.compile("\\d");
+
+    /** 是否包含符号（非字母、非数字、非空白的可见字符）。 */
+    private static final Pattern HAS_SYMBOL = Pattern.compile("[^a-zA-Z0-9\\s]");
+
+    /** 身份证 18 位加权因子。 */
+    private static final int[] ID_CARD_WEIGHT = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2};
+
+    /** 身份证校验位对照表（余数 0-10 对应的校验码）。 */
+    private static final char[] ID_CARD_CHECK = {'1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'};
+
+    /** 密码最小长度。 */
+    private static final int PASSWORD_MIN_LENGTH = 8;
+
+    /** 密码最大长度。 */
+    private static final int PASSWORD_MAX_LENGTH = 32;
+
+    private ValidatorUtil() {
+    }
+
+    /**
+     * 校验手机号是否合规。<br>
+     *
+     * @param phone 手机号
+     * @return true=合规
+     */
+    public static boolean isPhone(String phone) {
+        return StringUtils.isNotBlank(phone) && PHONE.matcher(phone).matches();
+    }
+
+    /**
+     * 基础校验身份证是否合法：18 位结构正则 + 末位校验码。<br>
+     *
+     * @param idCard 身份证号
+     * @return true=合法
+     */
+    public static boolean isIdCard(String idCard) {
+        if (StringUtils.isBlank(idCard) || !ID_CARD_18.matcher(idCard).matches()) {
+            return false;
+        }
+        int sum = 0;
+        for (int i = 0; i < ID_CARD_WEIGHT.length; i++) {
+            sum += (idCard.charAt(i) - '0') * ID_CARD_WEIGHT[i];
+        }
+        char expected = ID_CARD_CHECK[sum % 11];
+        char actual = Character.toUpperCase(idCard.charAt(17));
+        return expected == actual;
+    }
+
+    /**
+     * 校验密码强度，不满足时返回具体原因；满足时返回 null。<br>
+     * 规则：长度 8-32；必须同时包含字母、数字、符号；不允许出现连续自然数序列（如 1234、6789）。<br>
+     *
+     * @param password 明文密码
+     * @return 不合规原因，合规返回 null
+     */
+    public static String checkPasswordStrength(String password) {
+        if (StringUtils.isBlank(password)) {
+            return "密码不能为空";
+        }
+        int length = password.length();
+        if (length < PASSWORD_MIN_LENGTH || length > PASSWORD_MAX_LENGTH) {
+            return "密码长度需为 " + PASSWORD_MIN_LENGTH + "-" + PASSWORD_MAX_LENGTH + " 位";
+        }
+        if (!HAS_LETTER.matcher(password).find()) {
+            return "密码必须包含字母";
+        }
+        if (!HAS_DIGIT.matcher(password).find()) {
+            return "密码必须包含数字";
+        }
+        if (!HAS_SYMBOL.matcher(password).find()) {
+            return "密码必须包含符号";
+        }
+        if (containsConsecutiveSequence(password)) {
+            return "密码不允许出现连续自然数序列（如 1234）";
+        }
+        return null;
+    }
+
+    /**
+     * 是否包含「连续自然数」序列：相邻数字逐位递增 1，且连续 4 位及以上（如 1234、6789）。<br>
+     * 仅拦截严格等差 +1 的序列；重复的（0000、8888）或非等差的（1121）均不被判定为连续自然数。
+     *
+     * @param s 待检测字符串（一般为密码）
+     * @return true=包含连续自然数序列
+     */
+    private static boolean containsConsecutiveSequence(String s) {
+        int run = 1;
+        for (int i = 1; i < s.length(); i++) {
+            char c = s.charAt(i);
+            if (c < '0' || c > '9') {
+                run = 1;
+                continue;
+            }
+            char prev = s.charAt(i - 1);
+            if (prev >= '0' && prev <= '9' && (c - prev) == 1) {
+                run++;
+                if (run >= 4) {
+                    return true;
+                }
+            } else {
+                run = 1;
+            }
+        }
+        return false;
+    }
+}
diff --git a/src/main/java/com/yunhai/userbase/utils/WarnInfoUtil.java b/src/main/java/com/yunhai/userbase/utils/WarnInfoUtil.java
new file mode 100644
index 0000000..18d9efc
--- /dev/null
+++ b/src/main/java/com/yunhai/userbase/utils/WarnInfoUtil.java
@@ -0,0 +1,8 @@
+package com.yunhai.userbase.utils;
+
+public class WarnInfoUtil {
+
+    public static String MORE_RATIO_CONDITIONS(Integer key){
+        return "占比设置已达" + key + "%，已超100%，请重新输入！";
+    }
+}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
new file mode 100644
index 0000000..a804672
--- /dev/null
+++ b/src/main/resources/application.yml
@@ -0,0 +1,88 @@
+server:
+    port: 8060
+
+spring:
+    mvc:
+        date-format: yyyy-MM-dd HH:mm:ss
+    servlet:
+        multipart:
+            max-file-size: 50MB # 单个文件大小
+            max-request-size: 200MB # 单次请求总大小（多文件/表单整体上限，避免单文件没超但整体被拒）
+    jackson:
+        time-zone: GMT+8
+        date-format: yyyy-MM-dd HH:mm:ss
+    redis:
+        host: 127.0.0.1
+        port: 6379
+        database: 0
+        password: 123456
+        # 连接/命令超时：让后台探活(不可达时)快速失败，避免阻塞定时器线程；不影响正常请求
+        timeout: 500ms
+    data:
+        redis:
+            repositories:
+                enabled: false
+    http:
+        encoding:
+            force: true
+            charset: utf-8
+            enabled: true
+
+    datasource:
+        url: jdbc:mysql://localhost:3306/bsch_userbase?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
+        username: root
+        password: 123456
+        driver-class-name: com.mysql.cj.jdbc.Driver
+        min-idle: 30
+        max-active: 30
+    #jpa
+    jpa:
+        database: MySQL
+        show-sql: true
+        hibernate:
+            # 生产环境设置成 none，避免程序运行时自动更新数据库结构
+            ddl-auto: update
+        database-platform: org.hibernate.dialect.MySQL5InnoDBDialect
+        properties:
+            hibernate.order_by.default_null_ordering: last
+            hibernate:
+                dialect: org.hibernate.dialect.MySQL5InnoDBDialect
+            open-in-view: true
+
+    #本地关闭rabbit
+    rabbitmq:
+        listener:
+            direct:
+                auto-startup: false
+            simple:
+                auto-startup: false
+
+# 单点登录 / 应用间签名鉴权（基础平台 yh-auth / yh-app-auth）
+yh:
+    sso:
+        server-url-prefix: http://sso.yunhaixingtong.com/cas/
+        client-host-url: http://localhost:8060
+        allow-headers: all
+        allow-origins: all
+        url-pattern: /api/*
+        mobi-api-pattern: /mobiapi/*
+    app-auth:
+        enabled: true
+    sign-key-internal:
+        enabled: true
+        ips:
+            - 10.0.0.0/8
+            - 172.16.0.0/12
+            - 192.168.10.0/200
+
+ADMIN_TAG_ID: 290
+
+# 上传文件本地存储根目录（Linux 部署请通过环境变量/配置中心外置，避免写死 Windows 盘符）
+FILE_PATH: D://bsch//bschlearn
+
+# 上传文件对外访问的 Web 根地址，须与 MyWebAppConfigurer 中的 /upload/{子目录}/ 映射保持一致
+FILE_WEB_PATH: http://localhost:8060/upload/
+
+ZIYUAN_WEB_PATH_HTTP: http://base.bestsch.com/ziyuanku/file/
+UPLOAD_WEB_PATH_HTTP: http://localhost:8060/upload/file/
+ORC_SERVICE_URL: http://oa.bestsch.com/OrcService/api/Ocr/Upload
diff --git a/src/main/resources/bootstrap.yml b/src/main/resources/bootstrap.yml
new file mode 100644
index 0000000..c1fd007
--- /dev/null
+++ b/src/main/resources/bootstrap.yml
@@ -0,0 +1,47 @@
+spring:
+  application:
+    name: userbase
+  # 本地默认 local（不连 nacos）；CI 注入 SPRING_PROFILES_ACTIVE=prod
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:local}
+  cloud:
+    nacos:
+      config:
+        # ⭐ 本地默认关闭 nacos（profile=local 时完全不连，无 403 噪音，纯走 application.yml）
+        #   CI 注入 NACOS_CONFIG_ENABLED=true 才启用，拉 prod namespace 配置覆盖 application.yml
+        enabled: ${NACOS_CONFIG_ENABLED:false}
+        # Nacos 配置中心地址；CI 注入 NACOS_ADDR=nacos:8848（容器内网别名）
+        server-addr: ${NACOS_ADDR:nacos.yunhaixingtong.com:8848}
+        # 默认指向 prod namespace UUID，避免本地误开时连到空的 dev 命名空间
+        # CI 用 SPRING_CLOUD_NACOS_CONFIG_NAMESPACE 覆盖（注意：NACOS_NAMESPACE 这个 env 名不生效，必须用 SPRING_CLOUD_NACOS_CONFIG_NAMESPACE）
+        namespace: ${SPRING_CLOUD_NACOS_CONFIG_NAMESPACE:6196f0de-a28d-4894-8f10-e2982b57c6bc}
+        # 主配置 group：userbase.yaml 在 USERBASE group（与下方 shared-configs 的 DEFAULT_GROUP 不同组，各自指定）
+        group: USERBASE
+        # 配置文件格式；最终主配置 dataId = ${spring.application.name}.${file-extension} = userbase.yaml
+        file-extension: yaml
+        encode: UTF-8
+        # nacos 不可达时不强制退出，回退到本地 application.yml 兜底
+        fail-fast: false
+        # 只读账号（仅读取配置权限）；CI 注入 SPRING_CLOUD_NACOS_USERNAME/PASSWORD
+        # 注意：凭据必须用顶层 SPRING_CLOUD_NACOS_* env，放在 spring.cloud.nacos.config.* 下不生效（403）
+        username: ${SPRING_CLOUD_NACOS_USERNAME:yh-reader}
+        password: ${SPRING_CLOUD_NACOS_PASSWORD:123456}
+
+        # ============================================================
+        # ⭐⭐⭐ 共享配置加载顺序（决定优先级！：排在数组越靠后 = 优先级越高 = 覆盖前面的同 key）
+        #   低  1) public 命名空间 application-default.yaml（跨环境公共：日期格式/上传大小等，所有应用都能继承）
+        #   中  2) prod   命名空间 application-infra.yaml（仅生产：mysql/redis/rabbitmq 中间件连接）
+        #   高  3) prod   命名空间 userbase.yaml（应用级主配置：上传路径/context-path/CAS等，覆盖前两个）
+        #   最高 4) 启动命令 -D 参数 / 环境变量（覆盖一切）
+        # ============================================================
+        shared-configs:
+          # ① 1 号（最低优先级）：public 命名空间（namespace="" 固定写空字符串）的 application-default.yaml
+          - data-id: application-default.yaml
+            group: DEFAULT_GROUP
+            namespace: ""         # ⭐ 固定 = ""，强制指向 Nacos "public" 命名空间，不读上面的全局 prod namespace
+            refresh: false
+
+          # ② 2 号（中等优先级）：prod 命名空间（不写 namespace = 继承顶部全局 prod namespace id）的 application-infra.yaml
+          - data-id: application-infra.yaml
+            group: DEFAULT_GROUP
+            refresh: false
\ No newline at end of file
diff --git a/src/main/resources/logback-spring.xml b/src/main/resources/logback-spring.xml
new file mode 100644
index 0000000..20612de
--- /dev/null
+++ b/src/main/resources/logback-spring.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <!-- 引入 Spring Boot 默认彩色日志变量 -->
+    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+
+    <!-- 控制台：所有环境都有，且带颜色2 -->
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
+            <charset>${CONSOLE_LOG_CHARSET}</charset>
+        </encoder>
+    </appender>
+
+    <!-- 文件日志：只有非 local 环境才启用 -->
+    <springProfile name="!local">
+        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+            <file>/app/logs/app.log</file>
+            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+                <fileNamePattern>/app/logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
+                <maxHistory>30</maxHistory>
+                <totalSizeCap>5GB</totalSizeCap>
+            </rollingPolicy>
+            <encoder>
+                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
+            </encoder>
+        </appender>
+    </springProfile>
+
+    <root level="INFO">
+        <appender-ref ref="CONSOLE" />
+        <springProfile name="!local">
+            <appender-ref ref="FILE" />
+        </springProfile>
+    </root>
+</configuration>
\ No newline at end of file
diff --git a/src/main/resources/sql/application_bootstrap.sql b/src/main/resources/sql/application_bootstrap.sql
new file mode 100644
index 0000000..c85223c
--- /dev/null
+++ b/src/main/resources/sql/application_bootstrap.sql
@@ -0,0 +1,37 @@
+-- ============================================================
+-- 用户中心自身应用身份初始化（appKey=100000，后续业务应用从 100001 起）
+-- ------------------------------------------------------------
+-- 适用数据库：MySQL 5.7 / 8.0
+-- 运行方式：
+--   mysql --default-character-set=utf8mb4 -u<user> -p<password> <db_name> < application_bootstrap.sql
+-- 前置：表结构由 Hibernate（ddl-auto=update）创建，请先启动一次应用生成
+--       application_info 表后再执行本脚本；如已执行请忽略（幂等）。
+-- 说明：
+--   1. 本脚本按 app_key=100000 做幂等判断，重复执行不会新增重复记录。
+--   2. 用户中心作为「应用平台基石/默认调用方」，自身也需要一个合法的应用身份，
+--      用于对外发起 yh-app-auth 签名的应用签名请求；因此固定占用 appKey=100000。
+--   3. appSecret 每次执行脚本若不存在时会重新生成一个 UUID（32 位十六进制）；
+--      已存在记录不会被修改，生产上如需重置请手动 UPDATE 或在应用管理界面点「重设密钥」。
+--   4. 业务应用新增时 ApplicationInfoService 会按 MAX(app_key)+1 分配：
+--      因此本脚本写入 100000 后，下一条业务应用 appKey=100001，与预期一致。
+--   5. AUTO_INCREMENT=100001 仅设置 application_info 表的主键 id（非 appKey），
+--      使后续新建行的主键 id 也从 100001 起，与 appKey 段对齐，便于排查。
+-- ============================================================
+
+SET NAMES utf8mb4;
+
+-- 1) 插入用户中心自身身份（appKey=100000），已存在则跳过
+INSERT INTO application_info (app_key, name, app_secret, app_desc, create_user, create_time, update_user, update_time)
+SELECT 100000,
+       '用户中心平台',
+       REPLACE(UUID(), '-', ''),
+       '用户中心自身应用身份（基石应用，不对外展示于应用管理列表）',
+       0,
+       NOW(),
+       0,
+       NOW()
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM application_info WHERE app_key = 100000);
+
+-- 2) 调整主键 id 自增起点，使其与 appKey 段对齐（100001 起）
+ALTER TABLE application_info AUTO_INCREMENT = 100001;
diff --git a/src/main/resources/sql/fix_roles_mapping.sql b/src/main/resources/sql/fix_roles_mapping.sql
new file mode 100644
index 0000000..b224e4b
--- /dev/null
+++ b/src/main/resources/sql/fix_roles_mapping.sql
@@ -0,0 +1,78 @@
+-- ============================================================
+-- 修复 sys_user.roles 旧映射 -> SysRoleEnum 新映射
+-- ------------------------------------------------------------
+-- 背景：
+--   前端表单与导出注释历史上使用「旧映射」：
+--       1=管理员 2=老师 3=校领导 4=局领导 5=学生 6=家长 7=工作号
+--   而后端权威枚举 SysRoleEnum 现为：
+--       1=老师 2=校领导 3=学生 4=家长 5=局领导 6=工作号 7=管理员
+--   旧表单勾选「老师」会提交 value=2，被后端按 SysRoleEnum 存成「校领导」，
+--   于是教师/校领导的 roles 出现 [2,3] 这类错位值。
+--
+--   本脚本把存量 roles 从「旧映射」逐值改写为 SysRoleEnum 真值。
+--   前端已改为直接吃 GetSysDict.sysrole（SysRoleEnum 真源），新数据不会再错位。
+--
+-- ⚠️ 重要前提（执行前必读）：
+--   1) 本脚本假设 sys_user.roles 的全部现有值都是「旧映射」格式。
+--      若部分用户曾通过「批量导入」创建（导入路径一直用 SysRoleEnum 新值），
+--      这些行已是新格式，执行本脚本会将其再次错位 —— 必须先跑下面的校验 SQL 确认。
+--   2) 必须先执行备份语句；本脚本不自动执行，请由人工在数据库上运行。
+--   3) roles 列在 MySQL 中存为 TEXT（内容为 JSON 数组串，如 "[2,3]"），
+--      下方 UPDATE 用 MySQL 8.0 的 JSON_TABLE / JSON_ARRAYAGG，请确认数据库为 8.0。
+-- ============================================================
+
+-- ---------- 第 0 步：备份（务必先执行，可逆） ----------
+CREATE TABLE sys_user_roles_bak_20260817 AS
+SELECT id, roles, type FROM sys_user;
+
+-- ---------- 第 1 步：只读校验，看清现有格式 ----------
+-- 重点看 distinct roles 的值：
+--   若看到 [2,3] / [1] / [7] 这类（旧映射含义：老师/管理员/工作号），说明是旧格式；
+--   若看到 [1,2]（新映射含义：老师+校领导），说明已是新格式。
+--   只有当所有行都符合「旧格式」语义时，才执行第 2 步。
+SELECT roles, COUNT(*) AS cnt
+FROM sys_user
+WHERE roles IS NOT NULL AND roles <> '' AND roles <> '[]'
+GROUP BY roles
+ORDER BY cnt DESC;
+
+-- ---------- 第 2 步：旧映射 -> SysRoleEnum 新映射 逐值替换 ----------
+-- 旧/新 双射：
+--   1(管理员)->7   2(老师)->1   3(校领导)->2   4(局领导)->5
+--   5(学生)->3     6(家长)->4   7(工作号)->6
+UPDATE sys_user u
+SET u.roles = (
+    SELECT JSON_ARRAYAGG(
+        CASE j.r
+            WHEN 1 THEN 7   -- 旧:管理员 -> 新:管理员
+            WHEN 2 THEN 1   -- 旧:老师   -> 新:老师
+            WHEN 3 THEN 2   -- 旧:校领导 -> 新:校领导
+            WHEN 4 THEN 5   -- 旧:局领导 -> 新:局领导
+            WHEN 5 THEN 3   -- 旧:学生   -> 新:学生
+            WHEN 6 THEN 4   -- 旧:家长   -> 新:家长
+            WHEN 7 THEN 6   -- 旧:工作号 -> 新:工作号
+            ELSE j.r
+        END
+    )
+    FROM JSON_TABLE(CAST(u.roles AS JSON), '$[*]' COLUMNS (r INT PATH '$')) AS j
+)
+WHERE u.roles IS NOT NULL AND u.roles <> '' AND u.roles <> '[]';
+
+-- ---------- 第 3 步（可选）：重算 type 列（用户类型） ----------
+-- type 由 resolveUserType 推导：含 ADMIN(7) -> 2(学校管理员)，否则 0(普通用户)；
+-- 超管账号(id 10000~10002, type=1)保持不变。旧数据里 type 曾被旧映射带偏，这里一并纠正。
+UPDATE sys_user
+SET type = 2
+WHERE type <> 1
+  AND JSON_CONTAINS(CAST(roles AS JSON), JSON_ARRAY(7));
+
+UPDATE sys_user
+SET type = 0
+WHERE type <> 1
+  AND NOT JSON_CONTAINS(CAST(roles AS JSON), JSON_ARRAY(7));
+
+-- ---------- 回滚（如需） ----------
+-- INSERT INTO sys_user (id, roles, type)
+-- SELECT id, roles, type FROM sys_user_roles_bak_20260817
+-- ON DUPLICATE KEY UPDATE roles = VALUES(roles), type = VALUES(type);
+-- DROP TABLE sys_user_roles_bak_20260817;
diff --git a/src/main/resources/sql/sys_group_root_init.sql b/src/main/resources/sql/sys_group_root_init.sql
new file mode 100644
index 0000000..5b000a3
--- /dev/null
+++ b/src/main/resources/sql/sys_group_root_init.sql
@@ -0,0 +1,27 @@
+-- ============================================================
+-- 组织架构根节点初始化（教育云中心）
+-- ------------------------------------------------------------
+-- 适用数据库：MySQL 5.7（用户所述“5.8”按 5.7 处理），同时兼容 MySQL 8.0。
+-- 运行方式（务必带字符集，避免中文名乱码）：
+--   mysql --default-character-set=utf8mb4 -u<user> -p<password> <db_name> < sys_group_root_init.sql
+-- 前置：表结构由 Hibernate（ddl-auto=update）创建，请先启动一次应用生成 sys_group 表再执行本脚本。
+-- 说明：本脚本只负责“幂等插入根节点”一条数据。
+--      根节点（parent_id=0）的“不可手动添加/编辑/删除/移动”保护由应用代码层
+--      SysGroupService 的守卫实现（禁止代码删改），本脚本不再建 DB 触发器，
+--      因此你随时可用手动 SQL 直接删/改根节点。
+-- ============================================================
+
+-- 统一会话字符集，保证后续中文（根节点名）正确写入
+SET NAMES utf8mb4;
+
+
+-- 幂等插入根节点：仅当不存在 parent_id = 0 的记录时才插入，重复执行不会生成多条根。
+--    parent_id = 0 即根节点唯一标识；type 为 NULL（根节点无业务类型）；
+--    create_user 列 NOT NULL，填系统哨兵 0；create_time/update_time 由 NOW() 填充。
+--    注：type 列可空性已由应用启动时 Hibernate(ddl-auto=update) 保证；若对“旧库曾为 NOT NULL”的库执行，
+--    可先手执行一次：ALTER TABLE sys_group MODIFY COLUMN type INT NULL;（本脚本不再内联该句以免字符集/权限干扰）
+--    重要：MySQL 的 SELECT 没有 FROM 子句时不能直接跟 WHERE，必须补 FROM DUAL（裸 SELECT+WHERE 会报 1064）。
+INSERT INTO sys_group (name, parent_id, type, sort, create_user, create_time, update_time)
+SELECT '教育云中心', 0, NULL, 0, 0, NOW(), NOW()
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM sys_group WHERE parent_id = 0);
diff --git a/src/main/resources/sql/sys_user_add_email_gender.sql b/src/main/resources/sql/sys_user_add_email_gender.sql
new file mode 100644
index 0000000..7217d43
--- /dev/null
+++ b/src/main/resources/sql/sys_user_add_email_gender.sql
@@ -0,0 +1,5 @@
+-- 为 sys_user 表新增 email、gender 字段，支撑批量导入模板中的邮箱与性别列
+-- 执行方式：由 DBA 手动在对应环境执行，AI 不代跑
+ALTER TABLE sys_user
+    ADD COLUMN email VARCHAR(255) NULL COMMENT '邮箱',
+    ADD COLUMN gender INT NULL COMMENT '性别：0女 1男';
diff --git a/src/main/resources/sql/sys_user_group_rel_add_sort_no.sql b/src/main/resources/sql/sys_user_group_rel_add_sort_no.sql
new file mode 100644
index 0000000..ae8b64a
--- /dev/null
+++ b/src/main/resources/sql/sys_user_group_rel_add_sort_no.sql
@@ -0,0 +1,11 @@
+-- 为 sys_user_group_rel 关联表新增 sort_no 字段，用于「按组维度」对用户排序
+-- 默认 null（未设置）→ 列表按 user_id 升序兜底；1~999 正整数，越小越靠前。
+-- 执行方式：由 DBA 在 dev / prod 各自手工执行，AI 不代跑（本地 dev 靠 ddl-auto=update 自动加列）。
+-- 注意：覆盖索引 (group_id, sort_no, user_id) 让「具体组 + 排序」的 JOIN 走索引、减少回表；
+--       表达式排序 (sort_no IS NULL) 无法完全命中索引，但仍能借助 group_id 前缀快速圈定组范围。
+
+ALTER TABLE sys_user_group_rel
+    ADD COLUMN sort_no INT NULL COMMENT '组内排序号，越小越靠前；null 按 user_id 兜底';
+
+ALTER TABLE sys_user_group_rel
+    ADD INDEX idx_group_sort_user (group_id, sort_no, user_id);
diff --git a/src/main/resources/sql/sys_user_init.sql b/src/main/resources/sql/sys_user_init.sql
new file mode 100644
index 0000000..62499db
--- /dev/null
+++ b/src/main/resources/sql/sys_user_init.sql
@@ -0,0 +1,76 @@
+-- ============================================================
+-- 超级管理员账号初始化（yunhaisch / yunhaisch2 / yunhaisch3）
+-- ------------------------------------------------------------
+-- 适用数据库：MySQL 5.7（用户所述“5.8”按 5.7 处理），同时兼容 MySQL 8.0。
+-- 运行方式（务必带字符集，避免中文名乱码）：
+--   mysql --default-character-set=utf8mb4 -u<user> -p<password> <db_name> < sys_user_init.sql
+-- 前置：表结构由 Hibernate（ddl-auto=update）创建，请先启动一次应用生成 sys_user 表再执行本脚本。
+-- 说明：
+--   1. 本脚本幂等插入 3 个超级管理员账号，重复执行不会生成重复账号（按 username 唯一去重）。
+--   2. 密码统一为 yunhai@1357，已使用 BCrypt（strength=10，前缀 $2a$，与后端
+--      org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder 默认一致）加密后写入 password 列。
+--   3. 超级管理员角色由 roles 列承载：本系统角色枚举（SysRoleEnum）最高为 ADMIN(7)，
+--      应用内 isAdminById 仅对 SysRoleEnum.ADMIN(7) 返回 true，故赋予 [7] 即具备管理员权限。
+--      若需“全角色”超级权限，可将 '[7]' 改为 '[1,2,3,4,5,6,7]'。
+--   4. type 列（用户类型枚举 UserTypeEnum）：0=普通用户，1=超级管理员，2=学校管理员。
+--      本脚本写入的 3 个种子账号均为 type=1（超级管理员）；应用层在新增/编辑用户时会自动推导：
+--      内置超级管理员账号 -> 1，其余含 ADMIN(7) 角色 -> 2（学校管理员），默认 0（普通用户）。
+--   5. disabled=0 表示“正常/未禁用”（StatusEnum.NORMAL）；expired=0 表示未过期；
+--      create_user=0 为系统哨兵值（同 sys_group_root_init.sql 约定）。
+--   6. 用户表 id 由 MySQL AUTO_INCREMENT 生成（实体使用 GenerationType.IDENTITY）。
+--      本脚本显式指定 3 个种子账号 id = 10000 / 10001 / 10002，使整张表 id 自 10000 段起；
+--      插入 10002 后，后续新增用户自增从 10003 起。
+--   7. MySQL 的 SELECT 没有 FROM 子句时不能直接跟 WHERE，必须补 FROM DUAL（裸 SELECT+WHERE 会报 1064）。
+-- ============================================================
+
+-- 统一会话字符集，保证后续中文（real_name）正确写入
+SET NAMES utf8mb4;
+
+
+-- 账号 1：yunhaisch（id=10000）
+INSERT INTO sys_user (id, username, password, real_name, roles, type, disabled, expired, create_user, create_time, update_time)
+SELECT 10000,
+       'yunhaisch',
+       '$2a$10$4dAsjZEyUVgYn/wsgaSUVOMcA/oykF8TT7FLptNkMf39H6.Bp8SZi',
+       '超级管理员',
+       '[7]',
+       1,
+       0,
+       0,
+       0,
+       NOW(),
+       NOW()
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM sys_user WHERE username = 'yunhaisch');
+
+-- 账号 2：yunhaisch2（id=10001）
+INSERT INTO sys_user (id, username, password, real_name, roles, type, disabled, expired, create_user, create_time, update_time)
+SELECT 10001,
+       'yunhaisch2',
+       '$2a$10$5kKs4Z3woPCnyq7mpdXvju3TkO/7t/lIuNR./ToAnsLiHBXCLBSDS',
+       '超级管理员',
+       '[7]',
+       1,
+       0,
+       0,
+       0,
+       NOW(),
+       NOW()
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM sys_user WHERE username = 'yunhaisch2');
+
+-- 账号 3：yunhaisch3（id=10002）
+INSERT INTO sys_user (id, username, password, real_name, roles, type, disabled, expired, create_user, create_time, update_time)
+SELECT 10002,
+       'yunhaisch3',
+       '$2a$10$JXjnk.qJR4Arh1J0hl0fFugN0OvUymApLDeipsK0ZLLv9a0/N1p1u',
+       '超级管理员',
+       '[7]',
+       1,
+       0,
+       0,
+       0,
+       NOW(),
+       NOW()
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM sys_user WHERE username = 'yunhaisch3');
diff --git a/src/test/java/com/yunhai/userbase/UserBaseApplicationTests.java b/src/test/java/com/yunhai/userbase/UserBaseApplicationTests.java
new file mode 100644
index 0000000..7683091
--- /dev/null
+++ b/src/test/java/com/yunhai/userbase/UserBaseApplicationTests.java
@@ -0,0 +1,14 @@
+package com.yunhai.userprofile;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+class UserBaseApplicationTests {
+
+    @Test
+    void contextLoads() {
+        System.out.println("test");
+    }
+
+}
diff --git a/src/test/java/com/yunhai/userbase/service/impl/GroupAuthzServiceTest.java b/src/test/java/com/yunhai/userbase/service/impl/GroupAuthzServiceTest.java
new file mode 100644
index 0000000..25ef956
--- /dev/null
+++ b/src/test/java/com/yunhai/userbase/service/impl/GroupAuthzServiceTest.java
@@ -0,0 +1,504 @@
+package com.yunhai.userbase.service.impl;
+
+import com.yunhai.userbase.entity.AppCategory;
+import com.yunhai.userbase.entity.AppModule;
+import com.yunhai.userbase.entity.ApplicationInfo;
+import com.yunhai.userbase.entity.SysGroup;
+import com.yunhai.userbase.entity.SysGroupAppRel;
+import com.yunhai.userbase.entity.SysGroupModulePerm;
+import com.yunhai.userbase.entity.SysUser;
+import com.yunhai.userbase.entity.SysUserGroupRel;
+import com.yunhai.userbase.enums.GroupTypeEnum;
+import com.yunhai.userbase.enums.UserTypeEnum;
+import com.yunhai.userbase.model.groupauthz.UserPermissionCategoryVo;
+import com.yunhai.userbase.model.groupauthz.UserPermissionModuleVo;
+import com.yunhai.userbase.repository.AppCategoryRepository;
+import com.yunhai.userbase.repository.AppModuleRepository;
+import com.yunhai.userbase.repository.ApplicationInfoRepository;
+import com.yunhai.userbase.repository.SysAppRoleModuleRelRepository;
+import com.yunhai.userbase.repository.SysAppRoleRepository;
+import com.yunhai.userbase.repository.SysGroupAppRelRepository;
+import com.yunhai.userbase.repository.SysGroupModulePermRepository;
+import com.yunhai.userbase.repository.SysGroupRepository;
+import com.yunhai.userbase.repository.SysUserAppRoleRelRepository;
+import com.yunhai.userbase.repository.SysUserGroupRelRepository;
+import com.yunhai.userbase.repository.SysUserRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.Mockito.when;
+
+/**
+ * GroupAuthzService 权限计算单元测试。
+ * 重点验证「就近原则 + 子组继承闸门」：沿组的祖先链向上，取<b>最近</b>的有显式模块配置的组作为该应用唯一权限来源，
+ * 只返回该来源组的模块集合（不向上合并更远的祖先）；且<b>来源组若为祖先，必须勾选子组继承(inheritFlag=true)才下放</b>
+ * （修复「子组只勾1个却继承学校全部」「返回3个而非最近祖先的2个」「父级未勾子组继承仍被继承」三类 bug）。
+ */
+class GroupAuthzServiceTest {
+
+    @InjectMocks
+    private GroupAuthzService groupAuthzService;
+
+    @Mock
+    private SysGroupAppRelRepository sysGroupAppRelRepository;
+    @Mock
+    private SysGroupModulePermRepository sysGroupModulePermRepository;
+    @Mock
+    private SysGroupRepository sysGroupRepository;
+    @Mock
+    private ApplicationInfoRepository applicationInfoRepository;
+    @Mock
+    private AppCategoryRepository appCategoryRepository;
+    @Mock
+    private AppModuleRepository appModuleRepository;
+    @Mock
+    private SysUserGroupRelRepository sysUserGroupRelRepository;
+    @Mock
+    private SysUserRepository sysUserRepository;
+    @Mock
+    private SysAppRoleRepository sysAppRoleRepository;
+    @Mock
+    private SysAppRoleModuleRelRepository sysAppRoleModuleRelRepository;
+    @Mock
+    private SysUserAppRoleRelRepository sysUserAppRoleRelRepository;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+        initGroups();
+    }
+
+    /**
+     * 构造一组固定层级：
+     * 5 教育云中心（根）
+     * └─ 27 信阳教育局
+     *    └─ 16 云海中学（学校）
+     *       ├─ 29 教师组
+     *       │  └─ 31 英语组
+     *       └─ 30 学生组
+     */
+    private void initGroups() {
+        when(sysGroupRepository.findAll()).thenReturn(Arrays.asList(
+                group(5, "教育云中心", 0, GroupTypeEnum.NORMAL_GROUP),
+                group(27, "信阳教育局", 5, GroupTypeEnum.AREA_GROUP),
+                group(16, "云海中学", 27, GroupTypeEnum.SCHOOL_GROUP),
+                group(28, "信阳高级中学", 27, GroupTypeEnum.SCHOOL_GROUP),
+                group(29, "教师组", 16, GroupTypeEnum.TEACHER_GROUP),
+                group(30, "学生组", 16, GroupTypeEnum.STUDENT_GROUP),
+                group(31, "英语组", 29, GroupTypeEnum.NORMAL_GROUP)
+        ));
+    }
+
+    @Test
+    void findUserPermissionTree_whenSelfGroupConfiguredApp_shouldNotInheritAncestorModules() {
+        // user 1 仅属于英语组 31
+        when(sysUserRepository.findById(1)).thenReturn(Optional.of(user(1, UserTypeEnum.NORMAL)));
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        // 祖先链上的应用开通：只有学校 16 开通了 100003
+        when(sysGroupAppRelRepository.findByGroupIdIn(anyList())).thenAnswer(inv -> {
+            List<Integer> ids = inv.getArgument(0);
+            if (ids.contains(16)) {
+                return Collections.singletonList(appRel(16, 100003));
+            }
+            return Collections.emptyList();
+        });
+
+        ApplicationInfo app = new ApplicationInfo();
+        app.setId(100003);
+        app.setName("通知公告");
+        app.setAppKey(100002);
+        app.setCategoryId(2);
+        when(applicationInfoRepository.findAllById(any())).thenReturn(Collections.singletonList(app));
+
+        AppCategory category = new AppCategory();
+        category.setId(2);
+        category.setName("家校互动");
+        category.setSortNo(2);
+        when(appCategoryRepository.findAllByOrderBySortNoAsc()).thenReturn(Collections.singletonList(category));
+
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findByAppIdIn(anyList())).thenReturn(Arrays.asList(m8, m9, m10));
+
+        // 权限记录：英语组 31 只有模块 8；学校 16 有 8/9/10 且都允许继承
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(anyList(), anyList()))
+                .thenReturn(Arrays.asList(
+                        perm(31, 8, true),
+                        perm(16, 8, true),
+                        perm(16, 9, true),
+                        perm(16, 10, true)));
+
+        List<UserPermissionCategoryVo> result = groupAuthzService.findUserPermissionTree(31, 1);
+
+        assertEquals(1, result.size(), "应只有一个分类");
+        assertEquals("家校互动", result.get(0).getName());
+        assertEquals(1, result.get(0).getApps().size(), "应只有一个应用");
+        assertEquals(1, result.get(0).getApps().get(0).getModules().size(), "只应返回模块 8");
+        assertEquals(8, result.get(0).getApps().get(0).getModules().get(0).getId());
+    }
+
+    @Test
+    void findUserPermissionTree_whenSelfGroupNotConfiguredApp_shouldInheritFromSchool() {
+        // user 2 仅属于学生组 30，学生组没有配置通知公告应用的任何模块
+        when(sysUserRepository.findById(2)).thenReturn(Optional.of(user(2, UserTypeEnum.NORMAL)));
+        when(sysUserGroupRelRepository.findByUserId(2)).thenReturn(
+                Collections.singletonList(rel(2, 30, 1)));
+
+        when(sysGroupAppRelRepository.findByGroupIdIn(anyList())).thenAnswer(inv -> {
+            List<Integer> ids = inv.getArgument(0);
+            if (ids.contains(16)) {
+                return Collections.singletonList(appRel(16, 100003));
+            }
+            return Collections.emptyList();
+        });
+
+        ApplicationInfo app = new ApplicationInfo();
+        app.setId(100003);
+        app.setName("通知公告");
+        app.setAppKey(100002);
+        app.setCategoryId(2);
+        when(applicationInfoRepository.findAllById(any())).thenReturn(Collections.singletonList(app));
+
+        AppCategory category = new AppCategory();
+        category.setId(2);
+        category.setName("家校互动");
+        category.setSortNo(2);
+        when(appCategoryRepository.findAllByOrderBySortNoAsc()).thenReturn(Collections.singletonList(category));
+
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findByAppIdIn(anyList())).thenReturn(Arrays.asList(m8, m9, m10));
+
+        // 学校 16 三个模块都开放继承；学生组 30 没有任何记录
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(anyList(), anyList()))
+                .thenReturn(Arrays.asList(
+                        perm(16, 8, true),
+                        perm(16, 9, true),
+                        perm(16, 10, true)));
+
+        List<UserPermissionCategoryVo> result = groupAuthzService.findUserPermissionTree(30, 2);
+
+        assertEquals(3, result.get(0).getApps().get(0).getModules().size(),
+                "未配置应用时，应继承学校的全部 3 个模块");
+    }
+
+    @Test
+    void hasModulePermission_whenSelfGroupConfiguredApp_onlySelfRecordsCount() {
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findById(9)).thenReturn(Optional.of(m9));
+        when(sysUserAppRoleRelRepository.findByUserId(1)).thenReturn(Collections.emptyList());
+
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        when(sysGroupAppRelRepository.existsByGroupIdAndAppId(31, 100003)).thenReturn(true);
+        when(appModuleRepository.findByAppIdIn(Collections.singletonList(100003))).thenReturn(Arrays.asList(m8, m9, m10));
+
+        // 英语组 31 配置了应用 100003（模块 8）；学校 16 有模块 9（但 31 已就近接管，不应继承）
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                Arrays.asList(8, 9, 10), Arrays.asList(31, 29, 16, 27, 5)))
+                .thenReturn(Arrays.asList(perm(31, 8, true), perm(16, 9, true)));
+
+        assertFalse(groupAuthzService.hasModulePermission(1, 9),
+                "英语组已配置通知公告应用（就近接管），不应再继承学校的已发通知模块");
+    }
+
+    @Test
+    void hasModulePermission_whenSelfGroupHasTheModule_shouldReturnTrue() {
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findById(8)).thenReturn(Optional.of(m8));
+        when(sysUserAppRoleRelRepository.findByUserId(1)).thenReturn(Collections.emptyList());
+
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        when(sysGroupAppRelRepository.existsByGroupIdAndAppId(31, 100003)).thenReturn(true);
+        when(appModuleRepository.findByAppIdIn(Collections.singletonList(100003))).thenReturn(Arrays.asList(m8, m9, m10));
+
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                Arrays.asList(8, 9, 10), Arrays.asList(31, 29, 16, 27, 5)))
+                .thenReturn(Arrays.asList(perm(31, 8, true), perm(16, 8, true)));
+
+        assertTrue(groupAuthzService.hasModulePermission(1, 8),
+                "英语组自身已配置模块 8，应返回 true");
+    }
+
+    @Test
+    void findUserPermissionTree_whenSelfGroupEmpty_shouldUseNearestAncestorTeacherGroup() {
+        // user 1 仅属于英语组 31；英语组(31)无任何模块授权，教师组(29)有模块9/10，学校(16)有8/9/10
+        when(sysUserRepository.findById(1)).thenReturn(Optional.of(user(1, UserTypeEnum.NORMAL)));
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        when(sysGroupAppRelRepository.findByGroupIdIn(anyList())).thenAnswer(inv -> {
+            List<Integer> ids = inv.getArgument(0);
+            if (ids.contains(16)) {
+                return Collections.singletonList(appRel(16, 100003));
+            }
+            return Collections.emptyList();
+        });
+
+        ApplicationInfo app = new ApplicationInfo();
+        app.setId(100003);
+        app.setName("通知公告");
+        app.setAppKey(100002);
+        app.setCategoryId(2);
+        when(applicationInfoRepository.findAllById(any())).thenReturn(Collections.singletonList(app));
+
+        AppCategory category = new AppCategory();
+        category.setId(2);
+        category.setName("家校互动");
+        category.setSortNo(2);
+        when(appCategoryRepository.findAllByOrderBySortNoAsc()).thenReturn(Collections.singletonList(category));
+
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findByAppIdIn(anyList())).thenReturn(Arrays.asList(m8, m9, m10));
+
+        // 英语组31空；教师组29有9/10；学校16有8/9/10
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(anyList(), anyList()))
+                .thenReturn(Arrays.asList(
+                        perm(29, 9, true),
+                        perm(29, 10, true),
+                        perm(16, 8, true),
+                        perm(16, 9, true),
+                        perm(16, 10, true)));
+
+        List<UserPermissionCategoryVo> result = groupAuthzService.findUserPermissionTree(31, 1);
+
+        assertEquals(1, result.size(), "应只有一个分类");
+        assertEquals(1, result.get(0).getApps().size(), "应只有一个应用");
+        assertEquals(2, result.get(0).getApps().get(0).getModules().size(),
+                "本组空→取最近教师组29的2个模块，不应合并学校组多出的模块8");
+        Set<Integer> moduleIds = new LinkedHashSet<>();
+        for (UserPermissionModuleVo mv : result.get(0).getApps().get(0).getModules()) {
+            moduleIds.add(mv.getId());
+        }
+        assertTrue(moduleIds.contains(9) && moduleIds.contains(10) && moduleIds.size() == 2,
+                "应仅含模块 9 和 10，不含学校组多出的模块 8");
+    }
+
+    @Test
+    void findUserPermissionTree_whenNearestAncestorAllNotInheritable_returnsEmpty() {
+        // 英语组31空；教师组29有9/10但 inheritFlag=false（未勾子组继承）；学校16有8/9/10
+        when(sysUserRepository.findById(1)).thenReturn(Optional.of(user(1, UserTypeEnum.NORMAL)));
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        when(sysGroupAppRelRepository.findByGroupIdIn(anyList())).thenAnswer(inv -> {
+            List<Integer> ids = inv.getArgument(0);
+            if (ids.contains(16)) {
+                return Collections.singletonList(appRel(16, 100003));
+            }
+            return Collections.emptyList();
+        });
+
+        ApplicationInfo app = new ApplicationInfo();
+        app.setId(100003);
+        app.setName("通知公告");
+        app.setAppKey(100002);
+        app.setCategoryId(2);
+        when(applicationInfoRepository.findAllById(any())).thenReturn(Collections.singletonList(app));
+
+        AppCategory category = new AppCategory();
+        category.setId(2);
+        category.setName("家校互动");
+        category.setSortNo(2);
+        when(appCategoryRepository.findAllByOrderBySortNoAsc()).thenReturn(Collections.singletonList(category));
+
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findByAppIdIn(anyList())).thenReturn(Arrays.asList(m8, m9, m10));
+
+        // 教师组29（最近来源）所有模块 inheritFlag=false；即便学校16开放，也不应被继承
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(anyList(), anyList()))
+                .thenReturn(Arrays.asList(
+                        perm(29, 9, false),
+                        perm(29, 10, false),
+                        perm(16, 8, true),
+                        perm(16, 9, true),
+                        perm(16, 10, true)));
+
+        List<UserPermissionCategoryVo> result = groupAuthzService.findUserPermissionTree(31, 1);
+
+        // 最近来源(教师组)对该应用所有模块都未勾子组继承 → 本组该应用为空，不应合并学校组
+        assertTrue(result.isEmpty(),
+                "最近祖先(教师组)未勾子组继承，应返回空，不应从学校组继承任何模块");
+    }
+
+    @Test
+    void findUserPermissionTree_whenNearestAncestorPartiallyInheritable_returnsOnlyInheritable() {
+        // 英语组31空；教师组29有9(inheritFlag=true)/10(inheritFlag=false)；学校16有8/9/10
+        when(sysUserRepository.findById(1)).thenReturn(Optional.of(user(1, UserTypeEnum.NORMAL)));
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+
+        when(sysGroupAppRelRepository.findByGroupIdIn(anyList())).thenAnswer(inv -> {
+            List<Integer> ids = inv.getArgument(0);
+            if (ids.contains(16)) {
+                return Collections.singletonList(appRel(16, 100003));
+            }
+            return Collections.emptyList();
+        });
+
+        ApplicationInfo app = new ApplicationInfo();
+        app.setId(100003);
+        app.setName("通知公告");
+        app.setAppKey(100002);
+        app.setCategoryId(2);
+        when(applicationInfoRepository.findAllById(any())).thenReturn(Collections.singletonList(app));
+
+        AppCategory category = new AppCategory();
+        category.setId(2);
+        category.setName("家校互动");
+        category.setSortNo(2);
+        when(appCategoryRepository.findAllByOrderBySortNoAsc()).thenReturn(Collections.singletonList(category));
+
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findByAppIdIn(anyList())).thenReturn(Arrays.asList(m8, m9, m10));
+
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(anyList(), anyList()))
+                .thenReturn(Arrays.asList(
+                        perm(29, 9, true),
+                        perm(29, 10, false),
+                        perm(16, 8, true),
+                        perm(16, 9, true),
+                        perm(16, 10, true)));
+
+        List<UserPermissionCategoryVo> result = groupAuthzService.findUserPermissionTree(31, 1);
+
+        assertEquals(1, result.size(), "应只有一个分类");
+        assertEquals(1, result.get(0).getApps().size(), "应只有一个应用");
+        assertEquals(1, result.get(0).getApps().get(0).getModules().size(),
+                "最近来源(教师组)只有模块9勾了子组继承，应只返回模块9，模块10与学校组模块8均不继承");
+        assertEquals(9, result.get(0).getApps().get(0).getModules().get(0).getId());
+    }
+
+    @Test
+    void hasModulePermission_whenSelfGroupEmpty_nearestAncestorIsTeacherGroup() {
+        // 英语组31空，教师组29有9/10，学校16有8/9/10
+        AppModule m8 = module(8, 100003, "已收通知");
+        AppModule m9 = module(9, 100003, "已发通知");
+        AppModule m10 = module(10, 100003, "全部通知");
+        when(appModuleRepository.findById(8)).thenReturn(Optional.of(m8));
+        when(appModuleRepository.findById(9)).thenReturn(Optional.of(m9));
+        when(appModuleRepository.findById(10)).thenReturn(Optional.of(m10));
+        when(sysUserAppRoleRelRepository.findByUserId(1)).thenReturn(Collections.emptyList());
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(
+                Collections.singletonList(rel(1, 31, 1)));
+        when(sysGroupAppRelRepository.existsByGroupIdAndAppId(31, 100003)).thenReturn(true);
+        when(appModuleRepository.findByAppIdIn(Collections.singletonList(100003))).thenReturn(Arrays.asList(m8, m9, m10));
+        when(sysGroupModulePermRepository.findByModuleIdInAndGroupIdIn(
+                Arrays.asList(8, 9, 10), Arrays.asList(31, 29, 16, 27, 5)))
+                .thenReturn(Arrays.asList(
+                        perm(29, 9, true), perm(29, 10, true),
+                        perm(16, 8, true), perm(16, 9, true), perm(16, 10, true)));
+
+        assertFalse(groupAuthzService.hasModulePermission(1, 8),
+                "英语组为空→最近来源是教师组29，学校组多勾的模块8不应被继承");
+        assertTrue(groupAuthzService.hasModulePermission(1, 9),
+                "教师组29勾选的模块9应可访问");
+        assertTrue(groupAuthzService.hasModulePermission(1, 10),
+                "教师组29勾选的模块10应可访问");
+    }
+
+    @Test
+    void hasModulePermission_whenSuperAdmin_shouldReturnTrueRegardlessOfGroup() {
+        // 超级管理员：type=SUPER_ADMIN，且不归属任何组（超管通常不在任何组下）
+        when(sysUserRepository.findById(1)).thenReturn(Optional.of(user(1, UserTypeEnum.SUPER_ADMIN)));
+        when(sysUserGroupRelRepository.findByUserId(1)).thenReturn(Collections.emptyList());
+
+        assertTrue(groupAuthzService.hasModulePermission(1, 8),
+                "超级管理员应直接拥有全部模块权限，无需归属组/角色（修复「超管无组→返回false」的 bug）");
+        assertTrue(groupAuthzService.hasModulePermission(1, 100),
+                "超级管理员对任意模块都应返回 true");
+    }
+
+    // ===================== helper =====================
+
+    private SysGroup group(Integer id, String name, Integer parentId, GroupTypeEnum type) {
+        SysGroup g = new SysGroup();
+        g.setId(id);
+        g.setName(name);
+        g.setParentId(parentId);
+        g.setType(type);
+        return g;
+    }
+
+    private SysUser user(Integer id, UserTypeEnum type) {
+        SysUser u = new SysUser();
+        u.setId(id);
+        u.setType(type);
+        u.setAccount("u" + id);
+        u.setRealName("用户" + id);
+        return u;
+    }
+
+    private SysUserGroupRel rel(Integer userId, Integer groupId, Integer isMain) {
+        SysUserGroupRel r = new SysUserGroupRel();
+        r.setUserId(userId);
+        r.setGroupId(groupId);
+        r.setIsMain(isMain);
+        return r;
+    }
+
+    private SysGroupAppRel appRel(Integer groupId, Integer appId) {
+        SysGroupAppRel r = new SysGroupAppRel();
+        r.setGroupId(groupId);
+        r.setAppId(appId);
+        return r;
+    }
+
+    private SysGroupModulePerm perm(Integer groupId, Integer moduleId, boolean inherit) {
+        SysGroupModulePerm p = new SysGroupModulePerm();
+        p.setGroupId(groupId);
+        p.setModuleId(moduleId);
+        p.setInheritFlag(inherit);
+        return p;
+    }
+
+    private ApplicationInfo app(Integer id, String name, Integer categoryId) {
+        ApplicationInfo a = new ApplicationInfo();
+        a.setId(id);
+        a.setName(name);
+        a.setCategoryId(categoryId);
+        return a;
+    }
+
+    private AppModule module(Integer id, Integer appId, String name) {
+        AppModule m = new AppModule();
+        m.setId(id);
+        m.setAppId(appId);
+        m.setName(name);
+        m.setCustomId(String.valueOf(id));
+        m.setLevel(1);
+        return m;
+    }
+}