diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..6bd6a8a3a
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, dev, 2.x, 8.2.x, 17.3.x ]
+  pull_request:
+    branches: [ main, dev, 2.x, 8.2.x, 17.3.x ]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v5
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: maven
+
+      - name: Compile
+        run: ./mvnw clean compile -P travis
+
+      - name: Test
+        run: ./mvnw test -P travis
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: springboot-starter/target/site/jacoco/jacoco.xml,springboot-starter-script/target/site/jacoco/jacoco.xml,springboot-starter-security/target/site/jacoco/jacoco.xml,springboot-starter-data-fast/target/site/jacoco/jacoco.xml,springboot-starter-data-authorization/target/site/jacoco/jacoco.xml
+          fail_ci_if_error: true
+          verbose: true
+
+      - name: Install
+        run: ./mvnw install -P travis -DskipTests
diff --git a/.gitignore b/.gitignore
index 0d0422075..eeabb3e5c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,3 +52,4 @@ build/
 
 ### flatten-maven-plugin ###
 .flattened-pom.xml
+test.db*
diff --git a/.travis.yml b/.travis.yml
deleted file mode 100644
index cff239b5b..000000000
--- a/.travis.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-language: java
-
-jdk: openjdk20
-
-branches:
-  only:
-    - main
-    - dev
-
-before_install:
-  - pip install --user codecov
-
-script:
-  - mvn clean test -P travis
-
-after_success:
-  - bash <(curl -s https://codecov.io/bash)
-
-env:
-  global:
-    - CODECOV_TOKEN=eb1a776c-6802-4c65-90cd-6a8a2791e2f4
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c426dcc8..a1553681f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -106,7 +106,7 @@ MapResponse       // Map 响应
 ```java
 PageRequest request = PageRequest.of(0, 20);
 request.addFilter("name", "张三");
-request.addFilter("age", Relation.GT, 18);
+request.addFilter("age", Relation.GREATER_THAN, 18);
 Page<User> page = userRepository.findAll(request);
 ```
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a3b1b4b91..db3720422 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,7 +11,17 @@ Please make sure to read and observe our [Code of Conduct](./CODE_OF_CONDUCT.md)
 
 ### Setting up your development environment
 
-You should have JDK 1.8 or later installed in your system.
+You should have JDK 17 or later installed in your system.
+
+The project ships with the Maven Wrapper, so there is no need to install Maven separately.
+
+```bash
+# Full build
+./mvnw clean install
+
+# Run the tests only (the same command CI uses)
+./mvnw clean test -P travis
+```
 
 ## Contributing
 
@@ -23,7 +33,13 @@ We are very glad to accept improvements for these aspects.
 
 ### GitHub workflow
 
-We use the `dev` branch as the development branch, which indicates that this is a unstable branch.
+Development mainly happens on version branches (e.g. `17.3.x`, `8.2.x`) and on the `dev` branch,
+which is an unstable branch. The `main` branch stays stable, and CI runs on pushes and pull requests
+targeting `main`, `dev`, `2.x`, `8.2.x` and `17.3.x`.
+
+The project version (e.g. `17.3.0-SNAPSHOT`, where `17` is the JDK version, `3` is the Spring Boot
+major version and the last number is the patch version) is managed with the Maven `${revision}`
+CI-Friendly mechanism, so no `pom.xml` needs to be modified during development or for a release.
 
 Here are the workflow for contributors:
 
@@ -74,4 +90,4 @@ All code should be well reviewed by one or more committers. Some principles:
 
 #### Mailing list
 
-If you have any questions or advice, please contact 1991wangliang@gmail.com.
+If you have any questions or advice, please contact wangliang@codingapi.com.
diff --git a/DDD_CN.md b/DDD_CN.md
new file mode 100644
index 000000000..3cb9c36c4
--- /dev/null
+++ b/DDD_CN.md
@@ -0,0 +1,143 @@
+# 领域驱动设计（DDD）
+
+2026-08-18 lorne 
+
+中文 | [English](./DDD_EN.md)
+
+**DDD让业务决定模型，让模型组织软件，让数据与技术服务于业务。**
+
+## 它是什么？
+
+领域驱动设计是一种以业务为出发点、以领域模型为核心组织软件设计的方法论。它将业务问题抽象为领域模型，通过模型分析业务、表达规则和解决问题，并以此指导业务、数据与技术的组织方式。
+
+DDD提供的是软件设计的基本方向和判断标准，而不是一套固定的开发方法。它不规定必须采用某种架构、设计模式、技术框架或实现流程。判断是否符合DDD，关键不在于使用了哪些形式，而在于业务是否得到了准确表达，领域模型是否真正承担了业务职责，以及数据和技术是否围绕业务提供支撑。
+
+在本文采用的实践方式中，领域模型通过面向对象设计进行表达，并通过适当的架构设计将业务、数据与技术解耦。这样做不是为了遵守某种DDD规范，而是为了保护领域模型，使数据归数据、技术归技术、业务归业务，各司其职、低耦合协作。
+
+以“取消订单”为例，订单能否取消、取消后如何改变状态、是否需要退款，属于业务规则，应当由订单领域模型决定；如何查询和保存订单属于数据问题，应当由数据层负责；如何调用支付平台完成退款属于技术问题，应当由基础设施负责。
+
+因此，DDD并不是简单地将数据库表包装成类，而是让领域模型真正承担业务职责。订单不再只是一个保存数据的对象，而是一个能够判断是否允许取消、执行状态变化并产生相应业务结果的业务对象。
+
+## 它解决了什么？
+
+### 1. 更容易掌控业务复杂度
+
+领域驱动设计将业务、数据与技术进行解耦，减少彼此之间的依赖，使复杂度被限制在清晰的边界内。再通过面向对象设计对业务进行抽象和建模，使领域模型具备更好的表达力与适应能力，从而更容易应对复杂且持续变化的业务。
+
+例如，订单可能存在“待付款可以直接取消”“已付款取消需要退款”“已发货不能取消”等规则。如果这些判断分散在接口、数据库脚本和流程代码中，规则越多，系统就越难理解和修改。DDD将这些规则集中到订单模型中，使开发者可以直接围绕订单的状态和行为处理变化。
+
+DDD并没有消除业务本身的复杂度，而是将原本分散、隐藏的复杂度集中到业务模型中，使其能够被明确地表达、理解和控制。
+
+### 2. 更容易保障软件质量
+
+持续应对变化的前提，是建立完善的自动化回归测试机制。领域驱动设计将业务、数据和技术进行解耦，使每一部分都可以围绕自身职责进行独立、明确的测试，从而提高整个系统的可测试性。
+
+领域模型的测试专注于业务规则，只需要构造业务对象并验证其行为，不需要依赖数据库和外部系统；数据层剥离业务逻辑后，可以专注测试数据的存储、查询、映射和事务；技术层则可以专注测试接口调用、消息传递以及外部系统的集成。
+
+例如，在测试“取消订单”时，领域模型负责验证不同状态下是否允许取消；数据层负责验证取消后的订单状态能否被正确保存；技术层负责验证退款请求能否被正确发送到支付平台。
+
+这种设计不仅让业务规则更容易测试，也使数据和技术从复杂的业务场景中解放出来，转变为职责清晰的功能性测试。每一部分都能围绕自身职责进行验证，使问题更容易被发现和定位，并共同构成完整的自动化回归测试体系，从而保障软件持续演进的质量。
+
+### 3. 更容易沉淀和复用业务能力
+
+领域驱动设计在持续落地的过程中，沉淀的是包含业务规则和行为的领域模型，并可以进一步形成独立的业务组件。由于领域模型不直接依赖具体的数据结构和技术框架，因此更容易在业务语义相同的系统中复用和持续演进。
+
+例如，经过长期完善的订单模型，可能已经包含金额计算、状态流转、取消、退款和履约等能力。当其他系统需要相同的订单能力时，可以复用这些经过验证的模型和组件，再根据新系统使用的数据库、支付平台和消息系统实现相应的技术适配。
+
+需要注意的是，复用的前提是两个系统对业务的定义基本一致。DDD首先复用的是业务知识、模型和规则，在业务语义一致的情况下，才进一步复用具体代码。
+
+## 它不是什么？
+
+### 1. DDD不是一种技术框架
+
+DDD不是某个开发框架、类库或者固定的代码结构，而是一种以业务为核心组织软件的设计思想。
+
+技术框架负责解决程序如何运行，DDD负责解决业务如何被理解、建模和实现。框架可以被替换，数据库可以被更换，但领域模型所表达的业务规则应当保持相对稳定。
+
+因此，使用了某种分层框架不等于使用了DDD，没有使用特定框架也不代表无法实践DDD。
+
+### 2. DDD不是四层架构
+
+DDD经常采用用户界面层、应用层、领域层和基础设施层进行架构分层，但DDD本身并不等于四层架构。
+
+四层架构的作用，是划分系统职责并隔离技术细节：用户界面层负责接收请求，应用层负责组织业务流程，领域层负责实现业务规则，基础设施层负责数据库、消息和外部系统等技术能力。它是保护领域模型的一种架构手段，而不是DDD的定义。
+
+DDD也可以通过六边形架构、整洁架构或者其他架构形式实现。采用哪种架构并不重要，重要的是业务是否由领域模型表达，以及数据和技术是否被限制在清晰的边界之外。
+
+因此，项目采用了四层架构，不代表它实现了DDD；项目没有采用标准的四层结构，也不代表它不是DDD。
+
+### 3. DDD不是一套规范和标准
+
+DDD不是一套必须严格遵守的规范，也不存在一种唯一正确的实现方式。
+
+实体、值对象、聚合、仓储、领域服务、四层架构和六边形架构，都是帮助开发者建立或保护领域模型的可选工具，而不是判断一个项目是否采用DDD的标准答案。
+
+如果某种更简单的设计已经能够让业务得到准确表达，就没有必要为了形式完整而引入更多概念；如果现有设计无法承载不断增长的业务复杂度，就应当引入更合适的建模和架构手段。
+
+判断是否实践了DDD，不应当看项目使用了多少DDD术语，而应当看软件是否真正以业务模型为核心。
+
+### 4. DDD不是复杂系统的专属方案
+
+很多人认为，简单的CRUD应用不适合DDD，因为它会增加额外的设计和开发成本。我并不完全认同这种观点。
+
+无论项目大小，都需要面对代码耦合、质量保障和持续维护的问题。小项目今天可能只有简单的增删改查，但随着业务规则不断增加，如果代码始终围绕数据库组织，同样会逐渐变得难以理解和修改。
+
+掌握DDD并不意味着必须在每个项目中使用完全相同的设计。简单项目可以采用轻量的领域模型和分层方式，复杂项目则需要更明确的业务边界和更完整的建模方法。
+
+项目大小决定的是DDD落地的深度，而不是是否需要业务建模、职责分离和质量保障。
+
+### 5. DDD不是设计模式的堆积
+
+实体、值对象、聚合、仓储和领域服务都是实现领域模型的工具，但使用了这些概念并不代表真正实践了DDD。
+
+如果只是机械地增加类和接口，却没有用模型准确表达业务，那么这些设计只会增加系统的形式和复杂度。
+
+DDD的重点不是使用了多少设计模式，而是业务规则是否得到了清晰、准确和内聚的表达。需要什么就使用什么，不需要的设计不应为了形式完整而强行加入。
+
+### 6. DDD不是把数据库表转换成类
+
+将一张数据库表对应成一个实体类，本质上仍然是数据建模，而不是领域建模。
+
+数据对象表达的是数据如何存储，领域对象表达的是业务如何运行。领域对象不仅包含数据，还应当包含业务规则、状态变化和行为约束。
+
+DDD不是围绕数据库表编写业务代码，而是先建立业务模型，再决定如何保存模型产生的数据。
+
+### 7. DDD不是一次完成、永不变化的设计
+
+领域模型不是在项目开始时一次设计完成的静态产物。随着团队对业务理解的加深，以及业务本身不断变化，领域模型也需要持续调整和演进。
+
+因此，DDD不是追求一开始就设计出完美模型，而是在开发过程中不断发现业务、验证模型和修正表达，逐步让软件结构接近真实业务。
+
+## Vibe Coding时代，DDD的价值在哪里？
+
+Vibe Coding解决了代码快速生成的问题，但要真正用于复杂系统，还必须解决生成结果如何验证、已有能力如何复用，以及系统如何持续演进的问题。
+
+DDD在Vibe coding时代提供的核心价值，正是让Vibe Coding具备可测试、可复用和可持续的开发能力。
+
+### 1. 可测试：建立自我检测机制
+
+Vibe Coding生成的代码是否正确，不能只依赖人工阅读或功能是否能够运行，而需要通过自动化测试进行验证。
+
+DDD将业务规则集中在独立的领域模型中，使AI可以针对业务行为生成和执行测试，并根据测试结果持续修正代码。测试由此成为Vibe Coding的自我检测机制，为代码生成建立稳定的质量反馈闭环。
+
+### 2. 可复用：同时提升效率与质量
+
+如果每次开发都让AI重新生成相同的业务逻辑，不仅浪费效率，也容易产生不同的实现和新的错误。
+
+DDD将业务规则沉淀为领域模型和业务组件。经过测试验证的模型可以被重复使用，使AI能够基于已有能力进行组合和扩展。复用减少了重复开发，也减少了重复犯错，因此能够同时提升开发效率和软件质量。
+
+### 3. 可持续：支撑复杂系统开发
+
+复杂系统不是一次生成完成的，而是在持续变化中逐步演进形成的。
+
+DDD通过稳定的领域模型、清晰的业务边界以及业务与技术的分离，控制代码持续生成所带来的混乱和复杂度。它使AI能够在明确的范围内理解、修改和扩展系统，避免局部变化不断影响整体。
+
+因此，可持续性是Vibe Coding进入复杂系统开发的关键。没有可持续的模型和边界，Vibe Coding只能快速完成局部功能；具备可持续能力之后，它才可能参与长期、复杂的软件建设。
+
+## 总结
+
+DDD不是一种固定的架构、规范或者开发流程，而是一种以业务为出发点、以领域模型为核心组织软件设计的方法论。
+
+DDD本身不限定具体的实现方式。在工程实践中，可以通过面向对象设计实现领域模型，通过适当的架构设计将业务、数据与技术解耦，并通过自动化测试分别验证各自的职责，从而使业务模型能够被理解、验证、复用和持续演进。
+
+进入Vibe Coding时代以后，代码生成会越来越容易，但如何判断代码是否正确、如何避免重复生成，以及如何支撑复杂系统长期演进，将变得更加重要。代码可以快速生成，但经过验证、可以复用并能够持续演进的业务模型，才是软件真正能够长期积累的核心资产。
\ No newline at end of file
diff --git a/DDD_EN.md b/DDD_EN.md
new file mode 100644
index 000000000..e1039d189
--- /dev/null
+++ b/DDD_EN.md
@@ -0,0 +1,143 @@
+# Domain-Driven Design (DDD)
+
+2026-08-18 lorne
+
+[中文](./DDD_CN.md) | English
+
+**DDD lets the business define the model, the model organize the software, and data and technology serve the business.**
+
+## What Is It?
+
+Domain-Driven Design is a methodology that starts from the business and uses the domain model as the core around which software design is organized. It abstracts business problems into a domain model, uses the model to analyze the business, express rules and solve problems, and thereby guides how business, data and technology are organized.
+
+DDD provides a fundamental direction and criteria of judgment for software design, not a fixed development method. It does not mandate any particular architecture, design pattern, technical framework or implementation process. Whether a design conforms to DDD is not determined by which forms are used, but by whether the business is accurately expressed, whether the domain model genuinely carries business responsibilities, and whether data and technology are organized around the business to provide support.
+
+In the practice described in this article, the domain model is expressed through object-oriented design, and appropriate architectural design is used to decouple business, data and technology. This is not done to comply with some DDD specification, but to protect the domain model — so that data stays data, technology stays technology, and business stays business, each fulfilling its own role and collaborating with low coupling.
+
+Take "cancel order" as an example: whether an order can be cancelled, how its state changes after cancellation, and whether a refund is required are business rules and should be decided by the order domain model; how orders are queried and persisted is a data concern and should be handled by the data layer; how the payment platform is invoked to complete a refund is a technical concern and should be handled by the infrastructure.
+
+Therefore, DDD is not simply wrapping database tables as classes, but letting the domain model genuinely carry business responsibilities. An order is no longer just an object that stores data, but a business object that can decide whether cancellation is allowed, execute state transitions, and produce the corresponding business outcomes.
+
+## What Does It Solve?
+
+### 1. Business Complexity Becomes Manageable
+
+Domain-Driven Design decouples business, data and technology, reduces the dependencies among them, and confines complexity within clear boundaries. Through object-oriented design, the business is abstracted and modeled so that the domain model gains better expressiveness and adaptability, making it easier to cope with complex and continuously changing business.
+
+For example, an order may have rules such as "unpaid orders can be cancelled directly", "paid orders require a refund when cancelled", and "shipped orders cannot be cancelled". If these decisions are scattered across APIs, database scripts and process code, the more rules there are, the harder the system becomes to understand and modify. DDD centralizes these rules in the order model, so developers can handle changes directly around the order's states and behaviors.
+
+DDD does not eliminate the complexity of the business itself; rather, it concentrates complexity that was previously scattered and hidden into the business model, where it can be explicitly expressed, understood and controlled.
+
+### 2. Software Quality Becomes Easier to Guarantee
+
+The prerequisite for continuously coping with change is a solid automated regression testing mechanism. Domain-Driven Design decouples business, data and technology so that each part can be tested independently and explicitly around its own responsibility, improving the testability of the whole system.
+
+Tests of the domain model focus on business rules: they only need to construct business objects and verify their behavior, with no dependency on databases or external systems. Once the data layer is stripped of business logic, it can focus on testing storage, querying, mapping and transactions. The technology layer can focus on testing API calls, message passing and external system integration.
+
+For example, when testing "cancel order", the domain model verifies whether cancellation is allowed in each state; the data layer verifies that the order state after cancellation can be persisted correctly; the technology layer verifies that the refund request can be sent to the payment platform correctly.
+
+This design not only makes business rules easier to test, but also frees data and technology from complex business scenarios, turning them into clearly scoped functional tests. Each part can be verified around its own responsibility, making problems easier to find and locate, and together they form a complete automated regression testing system that safeguards quality as the software continuously evolves.
+
+### 3. Business Capabilities Can Be Accumulated and Reused
+
+As Domain-Driven Design is continuously practiced, what gets accumulated are domain models containing business rules and behaviors, which can further evolve into independent business components. Because domain models do not directly depend on concrete data structures or technical frameworks, they are easier to reuse and continuously evolve in systems with the same business semantics.
+
+For example, an order model refined over a long period may already include capabilities such as amount calculation, state transitions, cancellation, refund and fulfillment. When another system needs the same order capabilities, it can reuse these proven models and components, and then implement the corresponding technical adaptations for its own database, payment platform and messaging system.
+
+Note that the premise of reuse is that the two systems define the business in essentially the same way. What DDD reuses first is business knowledge, models and rules; only when business semantics are consistent does it proceed to reuse concrete code.
+
+## What Is It Not?
+
+### 1. DDD Is Not a Technical Framework
+
+DDD is not some development framework, class library or fixed code structure, but a way of thinking about organizing software with the business at the core.
+
+Technical frameworks solve how a program runs; DDD solves how the business is understood, modeled and implemented. Frameworks can be replaced and databases can be swapped, but the business rules expressed by the domain model should remain relatively stable.
+
+Therefore, using a certain layered framework does not mean using DDD, and not using a specific framework does not mean DDD cannot be practiced.
+
+### 2. DDD Is Not a Four-Layer Architecture
+
+DDD often adopts a layered architecture of user interface, application, domain and infrastructure, but DDD itself is not equivalent to a four-layer architecture.
+
+The role of a four-layer architecture is to divide system responsibilities and isolate technical details: the user interface layer receives requests, the application layer orchestrates business processes, the domain layer implements business rules, and the infrastructure layer provides technical capabilities such as databases, messaging and external systems. It is an architectural means of protecting the domain model, not the definition of DDD.
+
+DDD can also be realized through hexagonal architecture, clean architecture, or other architectural forms. Which architecture is adopted is not what matters; what matters is whether the business is expressed by the domain model, and whether data and technology are kept outside clear boundaries.
+
+Therefore, a project adopting a four-layer architecture does not mean it has implemented DDD; a project not adopting the standard four-layer structure does not mean it is not DDD either.
+
+### 3. DDD Is Not a Set of Specifications and Standards
+
+DDD is not a set of rules that must be strictly followed, nor is there a single correct implementation.
+
+Entities, value objects, aggregates, repositories, domain services, four-layer architecture and hexagonal architecture are all optional tools that help developers establish or protect the domain model, not standard answers for judging whether a project adopts DDD.
+
+If a simpler design can already express the business accurately, there is no need to introduce more concepts for the sake of formal completeness; if the current design can no longer carry the growing business complexity, more suitable modeling and architectural means should be introduced.
+
+Whether DDD is practiced should not be judged by how much DDD terminology a project uses, but by whether the software is genuinely centered on the business model.
+
+### 4. DDD Is Not Exclusive to Complex Systems
+
+Many people believe that simple CRUD applications are not suitable for DDD because it adds extra design and development cost. I do not fully agree with this view.
+
+Regardless of project size, one must face the problems of code coupling, quality assurance and continuous maintenance. A small project may only have simple CRUD today, but as business rules keep growing, if the code is always organized around the database, it will gradually become hard to understand and modify as well.
+
+Mastering DDD does not mean using exactly the same design in every project. Simple projects can adopt lightweight domain models and layering, while complex projects need more explicit business boundaries and more complete modeling methods.
+
+Project size determines the depth at which DDD is applied, not whether business modeling, separation of responsibilities and quality assurance are needed.
+
+### 5. DDD Is Not an Accumulation of Design Patterns
+
+Entities, value objects, aggregates, repositories and domain services are all tools for implementing the domain model, but using these concepts does not mean truly practicing DDD.
+
+If classes and interfaces are added mechanically while the model fails to express the business accurately, such designs only add formality and complexity to the system.
+
+The point of DDD is not how many design patterns are used, but whether business rules are expressed clearly, accurately and cohesively. Use what is needed; designs that are not needed should not be forced in for the sake of formal completeness.
+
+### 6. DDD Is Not Converting Database Tables into Classes
+
+Mapping one database table to one entity class is essentially still data modeling, not domain modeling.
+
+Data objects express how data is stored; domain objects express how the business operates. A domain object contains not only data, but also business rules, state transitions and behavioral constraints.
+
+DDD is not writing business code around database tables, but first establishing the business model and then deciding how to persist the data the model produces.
+
+### 7. DDD Is Not a One-Time, Never-Changing Design
+
+The domain model is not a static artifact designed once at the beginning of a project. As the team's understanding of the business deepens and the business itself keeps changing, the domain model also needs continuous adjustment and evolution.
+
+Therefore, DDD is not about pursuing a perfect model from the start, but about continuously discovering the business, validating the model and correcting its expression during development, gradually bringing the software structure closer to the real business.
+
+## In the Era of Vibe Coding, Where Is the Value of DDD?
+
+Vibe Coding solves the problem of rapid code generation, but to be truly used in complex systems, it must also solve how generated results are verified, how existing capabilities are reused, and how the system continuously evolves.
+
+The core value DDD provides in the era of Vibe Coding is precisely making Vibe Coding testable, reusable and sustainable.
+
+### 1. Testable: Establishing a Self-Verification Mechanism
+
+Whether the code generated by Vibe Coding is correct cannot rely solely on manual reading or on whether the functionality runs; it must be verified through automated tests.
+
+DDD centralizes business rules in independent domain models, allowing AI to generate and execute tests against business behavior and continuously correct the code based on test results. Tests thus become the self-verification mechanism of Vibe Coding, establishing a stable quality feedback loop for code generation.
+
+### 2. Reusable: Improving Both Efficiency and Quality
+
+If every development session lets AI regenerate the same business logic from scratch, it not only wastes efficiency but also easily produces divergent implementations and new errors.
+
+DDD accumulates business rules into domain models and business components. Models verified by tests can be reused, enabling AI to compose and extend based on existing capabilities. Reuse reduces repeated development and repeated mistakes, thus improving both development efficiency and software quality.
+
+### 3. Sustainable: Supporting Complex System Development
+
+Complex systems are not generated in one shot, but evolve gradually amid continuous change.
+
+Through stable domain models, clear business boundaries, and the separation of business from technology, DDD controls the chaos and complexity brought by continuous code generation. It enables AI to understand, modify and extend the system within explicit boundaries, preventing local changes from constantly affecting the whole.
+
+Therefore, sustainability is the key for Vibe Coding to enter complex system development. Without sustainable models and boundaries, Vibe Coding can only quickly complete isolated features; only with sustainable capabilities can it participate in long-term, complex software construction.
+
+## Conclusion
+
+DDD is not a fixed architecture, specification or development process, but a methodology that starts from the business and organizes software design around the domain model.
+
+DDD itself does not prescribe concrete implementation approaches. In engineering practice, the domain model can be realized through object-oriented design, business, data and technology can be decoupled through appropriate architectural design, and each responsibility can be verified separately through automated tests, so that the business model can be understood, verified, reused and continuously evolved.
+
+In the era of Vibe Coding, generating code will become ever easier, but judging whether code is correct, avoiding repeated generation, and supporting the long-term evolution of complex systems will become ever more important. Code can be generated quickly, but business models that are verified, reusable and capable of continuous evolution are the true core assets that software can accumulate over the long term.
diff --git a/README.md b/README.md
index 1375155d0..88f22aa01 100644
--- a/README.md
+++ b/README.md
@@ -1,146 +1,115 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/codingapi/springboot-framework/blob/main/LICENSE)
 [![Maven Central](https://img.shields.io/maven-central/v/com.codingapi.springboot/springboot-starter.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.codingapi.springboot%22%20AND%20a:%22springboot-starter%22)
-[![Build Status](https://app.travis-ci.com/codingapi/springboot-framework.svg?branch=main)](https://app.travis-ci.com/codingapi/springboot-framework)
-[![codecov](https://codecov.io/gh/codingapi/springboot-framework/branch/main/graph/badge.svg?token=Gl9LjJV6y4)](https://codecov.io/gh/codingapi/springboot-framework)
+[![Build](https://img.shields.io/github/actions/workflow/status/codingapi/springboot-framework/ci.yml?label=Build&logo=github)](https://github.com/codingapi/springboot-framework/actions)
+[![Codecov](https://codecov.io/gh/codingapi/springboot-framework/branch/17.3.x/graph/badge.svg)](https://codecov.io/gh/codingapi/springboot-framework)
 
-# springboot-framework | Springboot领域驱动开发
+# springboot-framework | Spring Boot 领域驱动开发框架
 
 > 当你无意间推开这一扇门，将会感叹原来生活可以如此的美好。
 
-本框架基于springboot为提供领域驱动设计与事件风暴开发落地，提供的范式开源框架。
+springboot-framework 是基于 Spring Boot 的领域驱动设计（DDD）与事件风暴落地框架，提供统一响应封装、动态分页查询、领域事件、数据权限、脚本引擎、认证授权等开箱即用能力。
 
-## Project Version | 项目版本说明
+## DDD 观点分享 | DDD Perspectives
 
-自 `17.3.0` 起，项目采用 CI-Friendly 版本管理方式（与 [flow-engine](https://github.com/codingapi/flow-engine) 相同）：pom 中的版本声明为 `${revision}`，开发期锁定为 SNAPSHOT 版本（当前为 `17.3.0-SNAPSHOT`），正式发布时通过 `-Drevision=x.y.z` 指定正式版本号，无需修改 pom。
+本框架以领域驱动设计为核心方法论。我们沉淀了一篇关于 DDD 的实践思考，欢迎交流：
 
-版本号含义：第一位为 JDK 版本，第二位为 Spring Boot 大版本，第三位为补丁版本。例如 `17.3.0` 表示基于 JDK 17、Spring Boot 3.x 的第 0 个补丁版本。
+> **DDD 让业务决定模型，让模型组织软件，让数据与技术服务于业务。**
 
-（历史版本线：v.2.x 对应 Spring Boot 2.x / JDK 8；v.3.x 对应 Spring Boot 3.x / JDK 17。）
+核心观点：
 
-Since `17.3.0`, the project uses a CI-Friendly versioning scheme (same approach as [flow-engine](https://github.com/codingapi/flow-engine)): the pom declares its version as `${revision}`, which is pinned to a SNAPSHOT during development (currently `17.3.0-SNAPSHOT`); the release version is supplied via `-Drevision=x.y.z` at release time, with no pom changes needed.
+* DDD 不是技术框架、不是四层架构、也不是一套规范，而是一种以业务为出发点、以领域模型为核心组织软件设计的方法论；
+* 通过业务、数据、技术解耦，让业务复杂度可控、软件质量可测、业务能力可复用；
+* DDD 不是复杂系统的专属方案，项目大小决定的是落地深度，而不是是否需要业务建模与职责分离；
+* 在 Vibe Coding 时代，代码可以快速生成，但经过验证、可以复用并能够持续演进的业务模型，才是软件真正能够长期积累的核心资产。
 
-Version number convention: first segment = JDK version, second segment = Spring Boot major version, third segment = patch version. For example, `17.3.0` targets JDK 17 and Spring Boot 3.x, patch 0.
+阅读完整文章：[中文版](./DDD_CN.md) | [English](./DDD_EN.md)
 
-(Legacy lines: v.2.x for Spring Boot 2.x on JDK 8; v.3.x for Spring Boot 3.x on JDK 17.)
+## 版本说明 | Versions
 
-## Frontend Framework Version | 前端框架版本说明
+项目当前维护两条版本线：
 
-| Package                                                               | Description  | Version                                                                                                                   |
-|-----------------------------------------------------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------|
-| [@codingapi/ui-framework](https://github.com/codingapi/ui-compoments)  | UI-Framework | [![npm](https://img.shields.io/npm/v/@codingapi/ui-framework.svg)](https://www.npmjs.com/package/@codingapi/ui-framework) |
-| [@codingapi/form-pc](https://github.com/codingapi/ui-compoments)            | Form-PC      | [![npm](https://img.shields.io/npm/v/@codingapi/form-pc.svg)](https://www.npmjs.com/package/@codingapi/form-pc)           |
-| [@codingapi/form-mobile](https://github.com/codingapi/ui-compoments)    | Form-Mobile  | [![npm](https://img.shields.io/npm/v/@codingapi/form-mobile.svg)](https://www.npmjs.com/package/@codingapi/form-mobile)   |
+| 版本线 | 最低 JDK 要求 | Spring Boot 版本 | 开发版本号 |
+|--------|--------------|------------------|-----------|
+| [17.3.x](https://github.com/codingapi/springboot-framework/tree/17.3.x) | JDK 17 | Spring Boot 3.x | `17.3.0-SNAPSHOT` |
+| [8.2.x](https://github.com/codingapi/springboot-framework/tree/8.2.x) | JDK 8 | Spring Boot 2.x | `8.2.0-SNAPSHOT` |
 
-前端代码位于 [frontend](./frontend) 目录，采用 pnpm workspace 管理：包含 `apps/pc`（原 admin-ui）与 `apps/mobile`（原 mobile-ui）两个应用，公共代码抽取在 `packages/shared`（@springboot-framework/shared）。
+版本号含义：第一位为最低 JDK 版本，第二位为 Spring Boot 大版本，第三位为补丁版本。项目采用 Maven `${revision}` CI-Friendly 版本机制，正式发布时通过 `-Drevision=x.y.z` 指定版本号，无需修改 pom。
 
-The frontend code lives in the [frontend](./frontend) directory, managed as a pnpm workspace: it contains two apps `apps/pc` (formerly admin-ui) and `apps/mobile` (formerly mobile-ui), with shared code extracted into `packages/shared` (@springboot-framework/shared).
+Version lines: **17.3.x** requires JDK 17+ and Spring Boot 3.x; **8.2.x** requires JDK 8+ and Spring Boot 2.x.
 
-```bash
-cd frontend
-pnpm install
-pnpm dev:pc        # PC 端开发模式（代理后端） / PC dev mode (proxies backend)
-pnpm dev:mobile    # 移动端开发模式（代理后端） / Mobile dev mode (proxies backend)
-pnpm build:pc      # PC 端生产构建 / PC production build
-pnpm build:mobile  # 移动端生产构建 / Mobile production build
-```
-
-更多指令见 [frontend/README.md](./frontend/README.md)。
-
-See [frontend/README.md](./frontend/README.md) for more scripts.
-
-
-## Project Modules Description | 项目模块介绍
+## 核心模块 | Modules
 
-* springboot-starter | Springboot领域驱动框架
-* springboot-starter-script | 脚本引擎框架
-* springboot-starter-data-fast | 快速数据呈现框架
-* springboot-starter-data-authorization | 数据权限框架
-* springboot-starter-security | security权限框架支持基于JWT的无状态权限认证与Redis的有状态权限认证
-* example | 示例DDD项目
-* frontend | 前端 monorepo（pnpm workspace），包含 apps/pc（原 admin-ui）管理后台UI脚手架、apps/mobile（原 mobile-ui）移动端UI脚手架与 packages/shared 公共代码
+| 模块 | 说明 |
+|------|------|
+| `springboot-starter` | DDD 核心：统一响应封装、动态分页查询、领域事件系统、国际化异常、事务管理 |
+| `springboot-starter-script` | Groovy 脚本引擎（运行时编译、缓存、热更新、REST API） |
+| `springboot-starter-data-fast` | JPA 增强，动态过滤查询与 HQL 构建 |
+| `springboot-starter-data-authorization` | 数据权限，SQL 拦截透明注入行级/列级权限条件 |
+| `springboot-starter-security` | JWT 无状态认证 / Redis 有状态认证 |
 
-## Flow Engine Migration | 流程引擎迁移说明
+> 仓库中的 `example`（DDD 示例后端）与 `frontend`（前端示例 monorepo）均为**示例工程**，不属于框架核心内容，仅供学习参考。前端 UI 组件库由独立仓库 [ui-compoments](https://github.com/codingapi/ui-compoments) 维护，与本项目无关。
 
-工作流引擎（springboot-starter-flow）已从本框架移除，重构为独立仓库维护，新地址：[https://github.com/codingapi/flow-engine](https://github.com/codingapi/flow-engine)。需要使用流程引擎的项目请改用独立仓库。
+## 快速开始 | Getting Started
 
-The workflow engine (springboot-starter-flow) has been removed from this framework and refactored into an independently maintained repository: [https://github.com/codingapi/flow-engine](https://github.com/codingapi/flow-engine). Projects that need the workflow engine should migrate to the standalone repository.
+Maven 引入（以正式发布版本为例，最新版本见上方 Maven Central 徽章；开发快照请使用 `17.3.0-SNAPSHOT`）：
 
-## SpringBoot DDD Architecture | SpringBoot DDD 框架图
+```xml
+<!-- Spring Boot 领域驱动框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter</artifactId>
+    <version>17.3.0</version>
+</dependency>
 
-![](./docs/img/ddd_architecture.png)
-
-## maven install
+<!-- 脚本引擎框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter-script</artifactId>
+    <version>17.3.0</version>
+</dependency>
 
-以下示例使用正式发布版本（如 `17.3.0`，最新发布版见上方 Maven Central 徽章）；如需体验开发快照版本，请使用 `17.3.0-SNAPSHOT`。
+<!-- 快速数据呈现框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter-data-fast</artifactId>
+    <version>17.3.0</version>
+</dependency>
 
-The examples below use an official release version (e.g. `17.3.0`; see the Maven Central badge above for the latest release). Use `17.3.0-SNAPSHOT` for the development snapshot.
+<!-- 数据权限框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter-data-authorization</artifactId>
+    <version>17.3.0</version>
+</dependency>
 
-```
-    <!-- Springboot领域驱动框架 -->
-    <dependency>
-        <groupId>com.codingapi.springboot</groupId>
-        <artifactId>springboot-starter</artifactId>
-        <version>17.3.0</version>
-    </dependency>
-    
-    <!-- 脚本引擎框架 -->
-    <dependency>
-        <groupId>com.codingapi.springboot</groupId>
-        <artifactId>springboot-starter-script</artifactId>
-        <version>17.3.0</version>
-    </dependency>
-    
-     <!-- 快速数据呈现框架 -->
-     <dependency>
-        <groupId>com.codingapi.springboot</groupId>
-        <artifactId>springboot-starter-data-fast</artifactId>
-        <version>17.3.0</version>
-    </dependency>
-    
-     <!-- 数据权限框架 -->
-     <dependency>
-        <groupId>com.codingapi.springboot</groupId>
-        <artifactId>springboot-starter-data-authorization</artifactId>
-        <version>17.3.0</version>
-    </dependency>
-
-     <!-- security&jwt权限框架 -->
-     <dependency>
-        <groupId>com.codingapi.springboot</groupId>
-        <artifactId>springboot-starter-security</artifactId>
-        <version>17.3.0</version>
-     </dependency>
-     
+<!-- security & jwt 权限框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter-security</artifactId>
+    <version>17.3.0</version>
+</dependency>
 ```
 
-## CONTRIBUTING
+## SpringBoot DDD Architecture | 框架结构图
+
+![](./docs/img/ddd_architecture.png)
 
-Welcome to springboot-framework ! This document is a guideline about how to contribute to springboot-framework.
-If you find something incorrect or missing, please leave comments / suggestions.
+## 示例工程 | Example
 
-[CONTRIBUTING](./CONTRIBUTING.md)
+示例工程的运行与使用见 [示例工程手册](./docs/example-guide.md)。
 
-## Documentation
+## 文档 | Documentation
 
-https://github.com/codingapi/springboot-framework/wiki
+* [Wiki](https://github.com/codingapi/springboot-framework/wiki)
+* [开发规范](./docs/conventions/index.md)
+* [能力清单](./docs/capabilities/index.md)
 
-## Example
+## 流程引擎迁移说明 | Flow Engine Migration
 
-见 [example](./example)
+工作流引擎（springboot-starter-flow）已从本框架移除，重构为独立仓库维护：[codingapi/flow-engine](https://github.com/codingapi/flow-engine)。需要使用流程引擎的项目请改用独立仓库。
 
-## Reference Documentation
+The workflow engine (springboot-starter-flow) has been moved to a standalone repository: [codingapi/flow-engine](https://github.com/codingapi/flow-engine).
 
-For further reference, please consider the following sections:
+## 贡献 | Contributing
 
-* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
-* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/2.7.1/maven-plugin/reference/html/)
-* [Create an OCI image](https://docs.spring.io/spring-boot/docs/2.7.1/maven-plugin/reference/html/#build-image)
-* [Spring Security](https://docs.spring.io/spring-boot/docs/2.7.1/reference/htmlsingle/#web.security)
-* [Spring Configuration Processor](https://docs.spring.io/spring-boot/docs/2.7.1/reference/htmlsingle/#appendix.configuration-metadata.annotation-processor)
-* [Spring Web](https://docs.spring.io/spring-boot/docs/2.7.1/reference/htmlsingle/#web)
-* [securing-web](https://spring.io/guides/gs/securing-web/)
-* [spring-security-without-the-websecurityconfigureradapter](https://spring.io/blog/2022/02/21/spring-security-without-the-websecurityconfigureradapter)
-* [springboot-security&jwt](https://blog.csdn.net/u014553029/article/details/112759382)
-* [Meituan-Dianping/Leaf](https://github.com/Meituan-Dianping/Leaf)
-* [SpringBoot Test](https://spring.io/guides/gs/testing-web/)
-* [SpringBoot Web Test](https://spring.io/guides/gs/testing-web/)  
+详见 [CONTRIBUTING](./CONTRIBUTING.md)。
diff --git a/docs/agents/capabilities/springboot-starter-data-authorization/sql-interception.md b/docs/agents/capabilities/springboot-starter-data-authorization/sql-interception.md
index 78cf7c9b8..0fce07af6 100644
--- a/docs/agents/capabilities/springboot-starter-data-authorization/sql-interception.md
+++ b/docs/agents/capabilities/springboot-starter-data-authorization/sql-interception.md
@@ -42,17 +42,23 @@ SQL 拦截数据权限通过 JDBC 代理层实现了完全透明的权限注入
 整个拦截链路由以下组件构成：
 
 ```
-DataSource → ConnectionProxy → PreparedStatementProxy / StatementProxy
-                                        ↓
-                               SQLRunningContext.intercept(sql)
-                                        ↓
-                               SQLInterceptor (DefaultSQLInterceptor)
-                                        ↓
-                               DataPermissionSQLEnhancer (JSqlParser)
-                                        ↓
-                               RowHandler.handler(tableName, alias)
-                                        ↓
-                               Condition (WHERE / JOIN 条件注入)
+JDBC Driver(AuthorizationJdbcDriver) → ConnectionProxy → PreparedStatementProxy / StatementProxy
+                                                                  ↓
+                                                         SQLRunningContext.intercept(sql)
+                                                                  ↓
+                                                         SQLInterceptor (DefaultSQLInterceptor)
+                                                                  ↓
+                                                         DataPermissionSQLEnhancer (JSqlParser)
+                                                                  ↓
+                                                         RowHandler.handler(tableName, alias)
+                                                                  ↓
+                                                         Condition (WHERE / JOIN 条件注入)
+```
+
+Connection 的包装实际发生在 `AuthorizationJdbcDriver.connect()`。该类是一个 JDBC Driver 装饰器，类加载时自动向 `DriverManager` 注册；建立连接时根据 JDBC URL 查找真实的数据库驱动并委托建连，再将返回的 `Connection` 包装为 `ConnectionProxy`。使用时需将数据源的 driver 指向该类（JDBC URL 保持不变）：
+
+```properties
+spring.datasource.driver-class-name=com.codingapi.springboot.authorization.jdbc.AuthorizationJdbcDriver
 ```
 
 ### 3. 核心组件说明
@@ -79,7 +85,7 @@ SQL 拦截的核心调度器（单例模式），负责：
 默认的 SQL 拦截器实现，包含三个阶段的处理：
 - `beforeHandler(sql)`：通过 `SQLUtils.isQuerySql()` 判断是否为查询语句，仅 SELECT 会被拦截
 - `postHandler(sql)`：创建 `DataPermissionSQLEnhancer`，使用 JSqlParser 解析 SQL 并通过 `RowHandler` 获取权限条件，返回增强后的 SQL
-- `afterHandler(sql, newSql, exception)`：日志记录，当配置 `showSql=true` 时输出改写后的 SQL
+- `afterHandler(sql, newSql, exception)`：日志记录，当配置 `codingapi.data-authorization.show-sql=true` 时输出改写后的 SQL
 
 #### RowHandler
 
@@ -156,9 +162,11 @@ public class ProjectRowHandler implements RowHandler {
         if ("project".equalsIgnoreCase(tableName)) {
             Condition condition = new Condition();
             // 通过 JOIN 关联成员表，只查询当前用户参与的项目
+            // 构造器参数顺序：(Type type, String tableName, String tableAlias, String onCondition)
             JoinConditionSQL joinSQL = new JoinConditionSQL(
-                "project_member pm",
                 JoinConditionSQL.Type.INNER,
+                "project_member",
+                "pm",
                 String.format("pm.project_id = %s.id AND pm.user_id = %d",
                     tableAlias, SecurityContext.getCurrentUserId())
             );
@@ -208,7 +216,7 @@ public class AuditSQLInterceptor implements SQLInterceptor {
 
 ### 内部工作原理
 
-1. **连接代理**：DataSource 返回的 `Connection` 被包装为 `ConnectionProxy`
+1. **连接代理**：`AuthorizationJdbcDriver.connect()` 将真实驱动返回的 `Connection` 包装为 `ConnectionProxy`
 2. **SQL 拦截时机**：当调用 `connection.prepareStatement(sql)` 时，`ConnectionProxy` 立即调用 `SQLRunningContext.intercept(sql)` 对 SQL 进行改写
 3. **递归解析**：`DataPermissionSQLEnhancer` 使用 JSqlParser 解析 SQL AST，深度遍历 PlainSelect、SetOperationList（UNION）、子查询、JOIN 中的子 Select，对每个涉及的表调用 `RowHandler`
 4. **条件注入**：`WhereConditionSQLHandler` 将 WHERE 条件通过 AND 拼接到原有 WHERE 子句；`JoinConditionSQLHandler` 向 FROM 子句追加 JOIN 关联
diff --git a/docs/agents/capabilities/springboot-starter-data-fast/fast-repository.md b/docs/agents/capabilities/springboot-starter-data-fast/fast-repository.md
index 84104d236..3050e5363 100644
--- a/docs/agents/capabilities/springboot-starter-data-fast/fast-repository.md
+++ b/docs/agents/capabilities/springboot-starter-data-fast/fast-repository.md
@@ -15,8 +15,8 @@ framework_version: "17.3.0-SNAPSHOT"
 
 `FastRepository` 通过扩展 `JpaRepository` 和 `JpaSpecificationExecutor`，提供了基于 `PageRequest` 的声明式动态查询能力：
 
-- **自动 Example 查询**：当 Filter 条件均为简单等值匹配时，自动转换为 Spring Data `Example` 查询，零额外代码
-- **HQL 动态构建**：当包含模糊、范围、IN 等复杂条件时，自动构建参数化 HQL，避免 SQL 注入风险
+- **findAll → Example/HQL 自动切换**：`findAll(PageRequest)` 有 Filter 条件时，全部为简单等值条件则构建 Spring Data `Example` 查询；包含 LIKE/范围/IN/OR 等复杂条件时自动切换参数化 HQL，零额外代码
+- **pageRequest → HQL 动态构建**：需要 LIKE、范围、IN、OR 等复杂条件时，必须显式调用 `pageRequest(PageRequest)`，由 `DynamicSQLBuilder` 构建参数化 HQL，避免 SQL 注入风险
 - **SearchRequest 集成**：支持从 HTTP 请求参数中自动解析 filter、sort 条件，适用于前端列表页的通用查询接口
 - **OR/AND 组合过滤**：支持嵌套的 OR/AND 条件组合，满足复杂业务筛选需求
 
@@ -36,29 +36,31 @@ public interface UserEntityRepository extends FastRepository<UserEntity, Long> {
 ### 2. 使用 PageRequest 进行动态过滤查询
 
 ```java
-// 创建分页请求并添加过滤条件
+// 创建分页请求并添加等值过滤条件
 PageRequest request = PageRequest.of(0, 20);
-request.addFilter("name", "张三");              // 等值匹配
-request.addFilter("age", Relation.GT, 18);      // 大于
-request.addFilter("email", Relation.LIKE, "gmail"); // 模糊查询
+request.addFilter("name", "张三");              // 等值匹配（默认 EQUAL）
+request.addFilter("status", "active");          // 等值匹配
 
-// 方式一：自动选择 Example 或 HQL（推荐）
+// 方式一：findAll —— 等值条件走 Example 查询，复杂条件自动切换 HQL
 Page<UserEntity> page = repository.findAll(request);
 
-// 方式二：强制使用 HQL 查询（适合复杂条件）
-Page<UserEntity> page2 = repository.pageRequest(request);
+// 方式二：pageRequest —— 需要 LIKE/范围/IN/OR 等复杂条件时必须显式调用，走 HQL
+PageRequest hqlRequest = PageRequest.of(0, 20);
+hqlRequest.addFilter("age", Relation.GREATER_THAN, 18);       // 大于
+hqlRequest.addFilter("email", Relation.LIKE, "gmail");        // 模糊查询
+Page<UserEntity> page2 = repository.pageRequest(hqlRequest);
 ```
 
 ### 3. 支持的过滤关系（Relation）
 
 | Relation | 说明 | HQL 示例 |
 |----------|------|----------|
-| EQ（默认） | 等于 | `name = ?1` |
-| NEQ | 不等于 | `name != ?1` |
-| GT | 大于 | `age > ?1` |
-| LT | 小于 | `age < ?1` |
-| GTE | 大于等于 | `age >= ?1` |
-| LTE | 小于等于 | `age <= ?1` |
+| EQUAL（默认） | 等于 | `name = ?1` |
+| NOT_EQUAL | 不等于 | `name != ?1` |
+| GREATER_THAN | 大于 | `age > ?1` |
+| LESS_THAN | 小于 | `age < ?1` |
+| GREATER_THAN_EQUAL | 大于等于 | `age >= ?1` |
+| LESS_THAN_EQUAL | 小于等于 | `age <= ?1` |
 | LIKE | 全模糊 | `name LIKE ?1`（自动加 `%value%`） |
 | LEFT_LIKE | 左模糊 | `name LIKE ?1`（自动加 `%value`） |
 | RIGHT_LIKE | 右模糊 | `name LIKE ?1`（自动加 `value%`） |
@@ -68,6 +70,8 @@ Page<UserEntity> page2 = repository.pageRequest(request);
 | IS_NULL | 为空 | `name IS NULL` |
 | IS_NOT_NULL | 非空 | `name IS NOT NULL` |
 
+> 注意：以上 Relation 在 `pageRequest()` / `searchRequest()` 中完整生效；`findAll()` 会按条件类型自动选择——全部等值条件走 Example 查询，包含 LIKE/范围/IN/OR 等复杂条件时自动切换 HQL。
+
 ### 4. 使用 SearchRequest 从 HTTP 请求自动解析
 
 ```java
@@ -98,7 +102,7 @@ request.orFilters(
 
 // AND 条件组
 request.andFilter(
-    new Filter("age", Relation.GTE, 18),
+    new Filter("age", Relation.GREATER_THAN_EQUAL, 18),
     new Filter("status", "active")
 );
 ```
@@ -115,7 +119,7 @@ public class UserQueryService {
     private UserEntityRepository userRepository;
 
     /**
-     * 基础动态查询 - 自动 Example/HQL
+     * 基础动态查询 - 包含 LIKE/范围条件，显式使用 pageRequest 走 HQL
      */
     public Page<UserEntity> findUsers(String name, Integer minAge, String status) {
         PageRequest request = PageRequest.of(0, 20);
@@ -123,12 +127,12 @@ public class UserQueryService {
             request.addFilter("name", Relation.LIKE, name);
         }
         if (minAge != null) {
-            request.addFilter("age", Relation.GTE, minAge);
+            request.addFilter("age", Relation.GREATER_THAN_EQUAL, minAge);
         }
         if (status != null) {
             request.addFilter("status", status);
         }
-        return userRepository.findAll(request);
+        return userRepository.pageRequest(request);
     }
 
     /**
@@ -158,8 +162,11 @@ public class UserQueryService {
 `FastRepository.findAll(PageRequest)` 的执行流程：
 
 1. 检查 `request.hasFilter()` — 无过滤条件时直接委托给 Spring Data 的标准 `findAll(PageRequest)`
-2. 有过滤条件时，通过 `ExampleBuilder` 尝试构建 `Example` 对象（仅处理等值匹配的属性）
-3. 将 Example 与 PageRequest 一起传入 `findAll(Example, Pageable)` 执行查询
+2. 有过滤条件时，通过 `RequestFilter.isAllEqualFilter()` 判断是否全部为简单等值条件
+3. 全部等值条件：通过 `ExampleBuilder` 构建 `Example` 对象（按实体属性名匹配 Filter，取 `value[0]` 写入实体字段），传入 `findAll(Example, Pageable)` 执行查询
+4. 包含复杂条件（LIKE、范围、IN、NOT_EQUAL、IS_NULL、OR/AND 组合等）：自动转发 `pageRequest()`，由 `DynamicSQLBuilder` 构建参数化 HQL 执行查询
+
+> 说明：`ExampleBuilder` 只处理 EQUAL 等值条件；过滤条件写入实体属性失败（如类型转换失败）时显式抛出 `IllegalStateException`，不再静默忽略。
 
 `FastRepository.pageRequest(PageRequest)` 的执行流程：
 
diff --git a/docs/agents/capabilities/springboot-starter/event-system.md b/docs/agents/capabilities/springboot-starter/event-system.md
index b244a9a6e..b07b3e410 100644
--- a/docs/agents/capabilities/springboot-starter/event-system.md
+++ b/docs/agents/capabilities/springboot-starter/event-system.md
@@ -73,7 +73,7 @@ EventPusher.push(new MyEvent(data), true);
 # 启用事务事件模式（事件在事务提交后触发）
 codingapi.framework.event.transaction.enable=true
 
-# 异步事件线程池大小（默认值见 PropertiesContext）
+# 异步事件线程池大小（默认值 20）
 codingapi.framework.handler-thread-pool-size=20
 ```
 
diff --git a/docs/agents/conventions/springboot-starter-data-fast/dynamic-query-convention.md b/docs/agents/conventions/springboot-starter-data-fast/dynamic-query-convention.md
index cd4250b5c..e7d73ccc9 100644
--- a/docs/agents/conventions/springboot-starter-data-fast/dynamic-query-convention.md
+++ b/docs/agents/conventions/springboot-starter-data-fast/dynamic-query-convention.md
@@ -29,12 +29,13 @@ framework_version: "17.3.0-SNAPSHOT"
    - 禁止直接使用 Spring Data 原生 `org.springframework.data.domain.PageRequest` 来承载业务过滤条件。
 
 2. **动态过滤条件通过 `PageRequest.addFilter()` 方法添加**
-   - 简单等值过滤：`pageRequest.addFilter("name", "张三")`，默认使用 `Relation.EQ`。
-   - 指定关系过滤：`pageRequest.addFilter("age", Relation.GT, 18)`。
+   - 简单等值过滤：`pageRequest.addFilter("name", "张三")`，默认使用 `Relation.EQUAL`。
+   - 指定关系过滤：`pageRequest.addFilter("age", Relation.GREATER_THAN, 18)`。
    - 组合过滤：使用 `andFilter(Filter...)` 和 `orFilters(Filter...)` 构建复杂条件。
 
 3. **过滤关系使用 `Relation` 枚举**
-   - 可用关系包括：`EQ`、`GT`、`LT`、`GTE`、`LTE`、`LIKE`、`IN` 等。
+   - 枚举位于 `com.codingapi.springboot.framework.dto.request.Relation`，使用前必须显式导入（`import com.codingapi.springboot.framework.dto.request.Relation;`）。
+   - 可用关系共 14 种：`EQUAL`、`NOT_EQUAL`、`LIKE`、`LEFT_LIKE`、`RIGHT_LIKE`、`BETWEEN`、`IN`、`NOT_IN`、`IS_NULL`、`IS_NOT_NULL`、`GREATER_THAN`、`LESS_THAN`、`GREATER_THAN_EQUAL`、`LESS_THAN_EQUAL`。
    - 所有过滤关系必须通过枚举表达，禁止硬编码字符串比较运算符。
 
 4. **Repository 接口需继承 `FastRepository`**
@@ -66,6 +67,9 @@ framework_version: "17.3.0-SNAPSHOT"
 ### ✅ 正确示例
 
 ```java
+import com.codingapi.springboot.framework.dto.request.Relation;
+import com.codingapi.springboot.framework.dto.response.MultiResponse;
+
 // 1. Repository 继承 FastRepository
 public interface UserRepository extends FastRepository<User, Long> {
 }
@@ -85,7 +89,7 @@ public class UserQueryService {
             request.addFilter("name", Relation.LIKE, name);
         }
         if (minAge != null) {
-            request.addFilter("age", Relation.GTE, minAge);
+            request.addFilter("age", Relation.GREATER_THAN_EQUAL, minAge);
         }
 
         // 委托 FastRepository 自动构建查询
@@ -101,7 +105,7 @@ public MultiResponse<User> list(
         @RequestParam(defaultValue = "0") int page,
         @RequestParam(defaultValue = "20") int size) {
     Page<User> result = userQueryService.listUsers(name, minAge, page, size);
-    return ResponseUtils.toMultiResponse(result);
+    return MultiResponse.of(result);
 }
 ```
 
diff --git a/docs/agents/conventions/springboot-starter/event-driven-convention.md b/docs/agents/conventions/springboot-starter/event-driven-convention.md
index 03cafa12f..4200df1d2 100644
--- a/docs/agents/conventions/springboot-starter/event-driven-convention.md
+++ b/docs/agents/conventions/springboot-starter/event-driven-convention.md
@@ -38,7 +38,7 @@ framework_version: "17.3.0-SNAPSHOT"
 
 ### 规则 2：事件处理器必须实现 IHandler<T extends IEvent> 接口
 
-Handler 通过泛型参数声明订阅的事件类型。框架在启动时通过 `HandlerBeanDefinitionRegistrar` 自动扫描所有 `IHandler` 实现并注册到 `ApplicationHandlerUtils`。
+Handler 通过泛型参数声明订阅的事件类型。框架的 Handler 注册机制分为两个阶段：① `HandlerBeanDefinitionRegistrar` 只扫描带 `@Handler` 注解的类并注册为 Spring BeanDefinition（使用 `@Component`/`@Service` 标注的 Handler 则由 Spring 组件扫描注册为 Bean）；② `SpringHandlerConfiguration` 收集容器中所有 `IHandler` Bean，在构造 `SpringDefaultEventHandler`/`SpringTransactionEventHandler` 时通过 `addHandlers` 统一注册到 `ApplicationHandlerUtils`。
 
 ```java
 public interface IHandler<T extends IEvent> {
diff --git a/docs/agents/conventions/springboot-starter/exception-handling-convention.md b/docs/agents/conventions/springboot-starter/exception-handling-convention.md
index f1041b0ea..c54cf5ad5 100644
--- a/docs/agents/conventions/springboot-starter/exception-handling-convention.md
+++ b/docs/agents/conventions/springboot-starter/exception-handling-convention.md
@@ -26,20 +26,23 @@ framework_version: "17.3.0-SNAPSHOT"
 所有业务校验失败、参数非法、权限不足等场景，必须抛出 `LocaleMessageException`，禁止直接使用 `RuntimeException`、`IllegalArgumentException` 等原生异常。
 
 ```java
-// 构造方式一：errCode + 默认消息（推荐用于简单场景）
-throw new LocaleMessageException("user.not.found", "用户不存在");
-
-// 构造方式二：仅 errCode，消息从 message.properties 自动解析
+// 构造方式一（推荐）：仅 errCode，消息从 message.properties 中按当前 Locale 自动解析
 throw new LocaleMessageException("user.not.found");
 
-// 构造方式三：带占位符参数，对应 properties 中 user.duplicate=用户名 {0} 已存在
+// 构造方式二：errCode + 占位符参数，对应 properties 中 user.duplicate=用户名 {0} 已存在
 throw LocaleMessageException.of("user.duplicate", username);
+
+// 构造方式三：errCode + 自定义消息，第二个参数直接使用、不走国际化（仅用于无需 i18n 的场景）
+throw new LocaleMessageException("custom.error", "自定义错误描述");
 ```
 
-### 规则 2：异常消息采用 message key + 默认消息格式
+**需要国际化消息时，必须使用单参构造 `LocaleMessageException(errCode)` 或静态工厂 `LocaleMessageException.of(errCode, args)`**，消息由框架从 message.properties 中按请求 Locale 解析。
+
+### 规则 2：异常消息通过 message key 国际化解析
 
 - 第一个参数为 **errCode**（即 i18n message key），用于前端匹配和国际化查找。
-- 第二个参数为 **默认消息**（defaultMessage），当 message.properties 中未配置该 key 时作为兜底展示。
+- 需要国际化的消息使用单参构造 `LocaleMessageException(errCode)` 或 `LocaleMessageException.of(errCode, args)`，消息从 message.properties 中按当前请求 Locale 解析。
+- 两参构造 `LocaleMessageException(errCode, errMessage)` 的第二个参数是**直接使用、不走国际化的自定义消息**：该构造函数直接以 errMessage 构造异常，**不会查询 MessageSource / message.properties，也不随 Locale 切换**，并非 "key 未配置时的兜底默认消息"。仅在确定无需国际化的场景使用。
 - errCode 命名采用 **点分隔小写** 格式，如 `order.status.invalid`、`auth.token.expired`。
 
 ### 规则 3：依赖 ExceptionConfiguration 全局拦截
@@ -83,7 +86,8 @@ public class UserService {
 
     public User getUser(Long id) {
         return userRepository.findById(id)
-                .orElseThrow(() -> new LocaleMessageException("user.not.found", "用户不存在"));
+                // 单参构造：消息从 messages.properties 中按 Locale 自动解析
+                .orElseThrow(() -> new LocaleMessageException("user.not.found"));
     }
 
     public void createUser(String username) {
@@ -147,6 +151,6 @@ public ResponseEntity<?> getUser(@PathVariable Long id) {
     }
 }
 
-// 错误 4：硬编码中文消息，不支持国际化
+// 错误 4：硬编码中文消息，两参构造的第二个参数直接使用、不走国际化
 throw new LocaleMessageException("err001", "这个用户找不到啊");
 ```
diff --git a/docs/agents/conventions/springboot-starter/response-convention.md b/docs/agents/conventions/springboot-starter/response-convention.md
index 3b6d46877..9f05d16e9 100644
--- a/docs/agents/conventions/springboot-starter/response-convention.md
+++ b/docs/agents/conventions/springboot-starter/response-convention.md
@@ -31,13 +31,13 @@ framework_version: "17.3.0-SNAPSHOT"
 4. **无数据操作成功返回**：使用 `Response.buildSuccess()`。
 5. **失败返回**：使用 `Response.buildFailure(errCode, errMessage)`。
 6. **禁止直接返回 Map 或自定义 DTO 作为 API 响应**。
-7. **响应 JSON 结构固定包含**：`success`（boolean）、`errCode`（string）、`errMessage`（string）、`data`（业务数据，仅 SingleResponse/MultiResponse 携带）。
+7. **响应 JSON 结构固定包含**：`success`（boolean）、`errCode`（string）、`errMessage`（string）、`data`（业务数据，仅 SingleResponse/MultiResponse/MapResponse 携带，`Response` 本身不携带）。
 
 ### 补充说明
 
 - `SingleResponse.empty()` 用于查询可能为空但语义上成功的场景，返回 `{ success: true, data: null }`。
 - `MultiResponse.of(collection, total)` 用于手动分页场景；`MultiResponse.of(page)` 自动从 Spring Data Page 提取 total。
-- `MultiResponse.empty()` 返回空列表 `{ success: true, data: { total: 0, list: [] } }`。
+- `MultiResponse.empty()` 返回空结果 `{ success: true, data: { total: 0, list: null } }`（注意：内部 `Content.list` 未初始化，序列化结果为 `null` 而非空数组；如需空数组语义，可改用 `MultiResponse.of(Collections.emptyList())`）。
 - 异常处理应通过全局异常处理器统一转换为 `Response.buildFailure(...)`，Controller 内不要 try-catch 后自行拼装错误响应。
 
 ## 使用实例
diff --git a/docs/capabilities/springboot-starter-data-authorization/sql-interception.md b/docs/capabilities/springboot-starter-data-authorization/sql-interception.md
index eab7667c5..b2584477a 100644
--- a/docs/capabilities/springboot-starter-data-authorization/sql-interception.md
+++ b/docs/capabilities/springboot-starter-data-authorization/sql-interception.md
@@ -48,17 +48,23 @@ SQL 拦截数据权限通过 JDBC 代理层实现了完全透明的权限注入
 整个拦截链路由以下组件构成：
 
 ```
-DataSource → ConnectionProxy → PreparedStatementProxy / StatementProxy
-                                        ↓
-                               SQLRunningContext.intercept(sql)
-                                        ↓
-                               SQLInterceptor (DefaultSQLInterceptor)
-                                        ↓
-                               DataPermissionSQLEnhancer (JSqlParser)
-                                        ↓
-                               RowHandler.handler(tableName, alias)
-                                        ↓
-                               Condition (WHERE / JOIN 条件注入)
+JDBC Driver(AuthorizationJdbcDriver) → ConnectionProxy → PreparedStatementProxy / StatementProxy
+                                                                  ↓
+                                                         SQLRunningContext.intercept(sql)
+                                                                  ↓
+                                                         SQLInterceptor (DefaultSQLInterceptor)
+                                                                  ↓
+                                                         DataPermissionSQLEnhancer (JSqlParser)
+                                                                  ↓
+                                                         RowHandler.handler(tableName, alias)
+                                                                  ↓
+                                                         Condition (WHERE / JOIN 条件注入)
+```
+
+Connection 的包装实际发生在 `AuthorizationJdbcDriver.connect()`。该类是一个 JDBC Driver 装饰器，类加载时自动向 `DriverManager` 注册；建立连接时根据 JDBC URL 查找真实的数据库驱动并委托建连，再将返回的 `Connection` 包装为 `ConnectionProxy`。使用时需将数据源的 driver 指向该类（JDBC URL 保持不变）：
+
+```properties
+spring.datasource.driver-class-name=com.codingapi.springboot.authorization.jdbc.AuthorizationJdbcDriver
 ```
 
 ### 3. 核心组件说明
@@ -85,7 +91,7 @@ SQL 拦截的核心调度器（单例模式），负责：
 默认的 SQL 拦截器实现，包含三个阶段的处理：
 - `beforeHandler(sql)`：通过 `SQLUtils.isQuerySql()` 判断是否为查询语句，仅 SELECT 会被拦截
 - `postHandler(sql)`：创建 `DataPermissionSQLEnhancer`，使用 JSqlParser 解析 SQL 并通过 `RowHandler` 获取权限条件，返回增强后的 SQL
-- `afterHandler(sql, newSql, exception)`：日志记录，当配置 `showSql=true` 时输出改写后的 SQL
+- `afterHandler(sql, newSql, exception)`：日志记录，当配置 `codingapi.data-authorization.show-sql=true` 时输出改写后的 SQL
 
 #### RowHandler
 
@@ -162,9 +168,11 @@ public class ProjectRowHandler implements RowHandler {
         if ("project".equalsIgnoreCase(tableName)) {
             Condition condition = new Condition();
             // 通过 JOIN 关联成员表，只查询当前用户参与的项目
+            // 构造器参数顺序：(Type type, String tableName, String tableAlias, String onCondition)
             JoinConditionSQL joinSQL = new JoinConditionSQL(
-                "project_member pm",
                 JoinConditionSQL.Type.INNER,
+                "project_member",
+                "pm",
                 String.format("pm.project_id = %s.id AND pm.user_id = %d",
                     tableAlias, SecurityContext.getCurrentUserId())
             );
@@ -214,7 +222,7 @@ public class AuditSQLInterceptor implements SQLInterceptor {
 
 ### 内部工作原理
 
-1. **连接代理**：DataSource 返回的 `Connection` 被包装为 `ConnectionProxy`
+1. **连接代理**：`AuthorizationJdbcDriver.connect()` 将真实驱动返回的 `Connection` 包装为 `ConnectionProxy`
 2. **SQL 拦截时机**：当调用 `connection.prepareStatement(sql)` 时，`ConnectionProxy` 立即调用 `SQLRunningContext.intercept(sql)` 对 SQL 进行改写
 3. **递归解析**：`DataPermissionSQLEnhancer` 使用 JSqlParser 解析 SQL AST，深度遍历 PlainSelect、SetOperationList（UNION）、子查询、JOIN 中的子 Select，对每个涉及的表调用 `RowHandler`
 4. **条件注入**：`WhereConditionSQLHandler` 将 WHERE 条件通过 AND 拼接到原有 WHERE 子句；`JoinConditionSQLHandler` 向 FROM 子句追加 JOIN 关联
diff --git a/docs/capabilities/springboot-starter-data-fast/fast-repository.md b/docs/capabilities/springboot-starter-data-fast/fast-repository.md
index 6643f6ef0..d58486bdb 100644
--- a/docs/capabilities/springboot-starter-data-fast/fast-repository.md
+++ b/docs/capabilities/springboot-starter-data-fast/fast-repository.md
@@ -17,8 +17,8 @@ content_hash: f840da63a739c7b4e23172d900dd2347480547290e1f947bc45f54f3e9916a53
 
 `FastRepository` 通过扩展 `JpaRepository` 和 `JpaSpecificationExecutor`，提供了基于 `PageRequest` 的声明式动态查询能力：
 
-- **自动 Example 查询**：当 Filter 条件均为简单等值匹配时，自动转换为 Spring Data `Example` 查询，零额外代码
-- **HQL 动态构建**：当包含模糊、范围、IN 等复杂条件时，自动构建参数化 HQL，避免 SQL 注入风险
+- **findAll → Example/HQL 自动切换**：`findAll(PageRequest)` 有 Filter 条件时，全部为简单等值条件则构建 Spring Data `Example` 查询；包含 LIKE/范围/IN/OR 等复杂条件时自动切换参数化 HQL，零额外代码
+- **pageRequest → HQL 动态构建**：需要 LIKE、范围、IN、OR 等复杂条件时，必须显式调用 `pageRequest(PageRequest)`，由 `DynamicSQLBuilder` 构建参数化 HQL，避免 SQL 注入风险
 - **SearchRequest 集成**：支持从 HTTP 请求参数中自动解析 filter、sort 条件，适用于前端列表页的通用查询接口
 - **OR/AND 组合过滤**：支持嵌套的 OR/AND 条件组合，满足复杂业务筛选需求
 
@@ -38,29 +38,31 @@ public interface UserEntityRepository extends FastRepository<UserEntity, Long> {
 ### 2. 使用 PageRequest 进行动态过滤查询
 
 ```java
-// 创建分页请求并添加过滤条件
+// 创建分页请求并添加等值过滤条件
 PageRequest request = PageRequest.of(0, 20);
-request.addFilter("name", "张三");              // 等值匹配
-request.addFilter("age", Relation.GT, 18);      // 大于
-request.addFilter("email", Relation.LIKE, "gmail"); // 模糊查询
+request.addFilter("name", "张三");              // 等值匹配（默认 EQUAL）
+request.addFilter("status", "active");          // 等值匹配
 
-// 方式一：自动选择 Example 或 HQL（推荐）
+// 方式一：findAll —— 等值条件走 Example 查询，复杂条件自动切换 HQL
 Page<UserEntity> page = repository.findAll(request);
 
-// 方式二：强制使用 HQL 查询（适合复杂条件）
-Page<UserEntity> page2 = repository.pageRequest(request);
+// 方式二：pageRequest —— 需要 LIKE/范围/IN/OR 等复杂条件时必须显式调用，走 HQL
+PageRequest hqlRequest = PageRequest.of(0, 20);
+hqlRequest.addFilter("age", Relation.GREATER_THAN, 18);       // 大于
+hqlRequest.addFilter("email", Relation.LIKE, "gmail");        // 模糊查询
+Page<UserEntity> page2 = repository.pageRequest(hqlRequest);
 ```
 
 ### 3. 支持的过滤关系（Relation）
 
 | Relation | 说明 | HQL 示例 |
 |----------|------|----------|
-| EQ（默认） | 等于 | `name = ?1` |
-| NEQ | 不等于 | `name != ?1` |
-| GT | 大于 | `age > ?1` |
-| LT | 小于 | `age < ?1` |
-| GTE | 大于等于 | `age >= ?1` |
-| LTE | 小于等于 | `age <= ?1` |
+| EQUAL（默认） | 等于 | `name = ?1` |
+| NOT_EQUAL | 不等于 | `name != ?1` |
+| GREATER_THAN | 大于 | `age > ?1` |
+| LESS_THAN | 小于 | `age < ?1` |
+| GREATER_THAN_EQUAL | 大于等于 | `age >= ?1` |
+| LESS_THAN_EQUAL | 小于等于 | `age <= ?1` |
 | LIKE | 全模糊 | `name LIKE ?1`（自动加 `%value%`） |
 | LEFT_LIKE | 左模糊 | `name LIKE ?1`（自动加 `%value`） |
 | RIGHT_LIKE | 右模糊 | `name LIKE ?1`（自动加 `value%`） |
@@ -70,6 +72,8 @@ Page<UserEntity> page2 = repository.pageRequest(request);
 | IS_NULL | 为空 | `name IS NULL` |
 | IS_NOT_NULL | 非空 | `name IS NOT NULL` |
 
+> 注意：以上 Relation 在 `pageRequest()` / `searchRequest()` 中完整生效；`findAll()` 会按条件类型自动选择——全部等值条件走 Example 查询，包含 LIKE/范围/IN/OR 等复杂条件时自动切换 HQL。
+
 ### 4. 使用 SearchRequest 从 HTTP 请求自动解析
 
 ```java
@@ -100,7 +104,7 @@ request.orFilters(
 
 // AND 条件组
 request.andFilter(
-    new Filter("age", Relation.GTE, 18),
+    new Filter("age", Relation.GREATER_THAN_EQUAL, 18),
     new Filter("status", "active")
 );
 ```
@@ -117,7 +121,7 @@ public class UserQueryService {
     private UserEntityRepository userRepository;
 
     /**
-     * 基础动态查询 - 自动 Example/HQL
+     * 基础动态查询 - 包含 LIKE/范围条件，显式使用 pageRequest 走 HQL
      */
     public Page<UserEntity> findUsers(String name, Integer minAge, String status) {
         PageRequest request = PageRequest.of(0, 20);
@@ -125,12 +129,12 @@ public class UserQueryService {
             request.addFilter("name", Relation.LIKE, name);
         }
         if (minAge != null) {
-            request.addFilter("age", Relation.GTE, minAge);
+            request.addFilter("age", Relation.GREATER_THAN_EQUAL, minAge);
         }
         if (status != null) {
             request.addFilter("status", status);
         }
-        return userRepository.findAll(request);
+        return userRepository.pageRequest(request);
     }
 
     /**
@@ -160,8 +164,11 @@ public class UserQueryService {
 `FastRepository.findAll(PageRequest)` 的执行流程：
 
 1. 检查 `request.hasFilter()` — 无过滤条件时直接委托给 Spring Data 的标准 `findAll(PageRequest)`
-2. 有过滤条件时，通过 `ExampleBuilder` 尝试构建 `Example` 对象（仅处理等值匹配的属性）
-3. 将 Example 与 PageRequest 一起传入 `findAll(Example, Pageable)` 执行查询
+2. 有过滤条件时，通过 `RequestFilter.isAllEqualFilter()` 判断是否全部为简单等值条件
+3. 全部等值条件：通过 `ExampleBuilder` 构建 `Example` 对象（按实体属性名匹配 Filter，取 `value[0]` 写入实体字段），传入 `findAll(Example, Pageable)` 执行查询
+4. 包含复杂条件（LIKE、范围、IN、NOT_EQUAL、IS_NULL、OR/AND 组合等）：自动转发 `pageRequest()`，由 `DynamicSQLBuilder` 构建参数化 HQL 执行查询
+
+> 说明：`ExampleBuilder` 只处理 EQUAL 等值条件；过滤条件写入实体属性失败（如类型转换失败）时显式抛出 `IllegalStateException`，不再静默忽略。
 
 `FastRepository.pageRequest(PageRequest)` 的执行流程：
 
diff --git a/docs/capabilities/springboot-starter/event-system.md b/docs/capabilities/springboot-starter/event-system.md
index 1c5256f7f..e50a945f6 100644
--- a/docs/capabilities/springboot-starter/event-system.md
+++ b/docs/capabilities/springboot-starter/event-system.md
@@ -84,7 +84,7 @@ EventPusher.push(new MyEvent(data), true);
 # 启用事务事件模式（事件在事务提交后触发）
 codingapi.framework.event.transaction.enable=true
 
-# 异步事件线程池大小（默认值见 PropertiesContext）
+# 异步事件线程池大小（默认值 20）
 codingapi.framework.handler-thread-pool-size=20
 ```
 
diff --git a/docs/conventions/springboot-starter-data-fast/dynamic-query-convention.md b/docs/conventions/springboot-starter-data-fast/dynamic-query-convention.md
index f4617ca49..54039a8c7 100644
--- a/docs/conventions/springboot-starter-data-fast/dynamic-query-convention.md
+++ b/docs/conventions/springboot-starter-data-fast/dynamic-query-convention.md
@@ -29,12 +29,13 @@ content_hash: 0369b4e3ba19d679dea69480cf4c5f6e4687c186c515e56883c004884711ab83
    - 禁止直接使用 Spring Data 原生 `org.springframework.data.domain.PageRequest` 来承载业务过滤条件。
 
 2. **动态过滤条件通过 `PageRequest.addFilter()` 方法添加**
-   - 简单等值过滤：`pageRequest.addFilter("name", "张三")`，默认使用 `Relation.EQ`。
-   - 指定关系过滤：`pageRequest.addFilter("age", Relation.GT, 18)`。
+   - 简单等值过滤：`pageRequest.addFilter("name", "张三")`，默认使用 `Relation.EQUAL`。
+   - 指定关系过滤：`pageRequest.addFilter("age", Relation.GREATER_THAN, 18)`。
    - 组合过滤：使用 `andFilter(Filter...)` 和 `orFilters(Filter...)` 构建复杂条件。
 
 3. **过滤关系使用 `Relation` 枚举**
-   - 可用关系包括：`EQ`、`GT`、`LT`、`GTE`、`LTE`、`LIKE`、`IN` 等。
+   - 枚举位于 `com.codingapi.springboot.framework.dto.request.Relation`，使用前必须显式导入（`import com.codingapi.springboot.framework.dto.request.Relation;`）。
+   - 可用关系共 14 种：`EQUAL`、`NOT_EQUAL`、`LIKE`、`LEFT_LIKE`、`RIGHT_LIKE`、`BETWEEN`、`IN`、`NOT_IN`、`IS_NULL`、`IS_NOT_NULL`、`GREATER_THAN`、`LESS_THAN`、`GREATER_THAN_EQUAL`、`LESS_THAN_EQUAL`。
    - 所有过滤关系必须通过枚举表达，禁止硬编码字符串比较运算符。
 
 4. **Repository 接口需继承 `FastRepository`**
@@ -66,6 +67,9 @@ content_hash: 0369b4e3ba19d679dea69480cf4c5f6e4687c186c515e56883c004884711ab83
 ### ✅ 正确示例
 
 ```java
+import com.codingapi.springboot.framework.dto.request.Relation;
+import com.codingapi.springboot.framework.dto.response.MultiResponse;
+
 // 1. Repository 继承 FastRepository
 public interface UserRepository extends FastRepository<User, Long> {
 }
@@ -85,7 +89,7 @@ public class UserQueryService {
             request.addFilter("name", Relation.LIKE, name);
         }
         if (minAge != null) {
-            request.addFilter("age", Relation.GTE, minAge);
+            request.addFilter("age", Relation.GREATER_THAN_EQUAL, minAge);
         }
 
         // 委托 FastRepository 自动构建查询
@@ -101,7 +105,7 @@ public MultiResponse<User> list(
         @RequestParam(defaultValue = "0") int page,
         @RequestParam(defaultValue = "20") int size) {
     Page<User> result = userQueryService.listUsers(name, minAge, page, size);
-    return ResponseUtils.toMultiResponse(result);
+    return MultiResponse.of(result);
 }
 ```
 
diff --git a/docs/conventions/springboot-starter/event-driven-convention.md b/docs/conventions/springboot-starter/event-driven-convention.md
index 3cfb076bc..267f9e5c4 100644
--- a/docs/conventions/springboot-starter/event-driven-convention.md
+++ b/docs/conventions/springboot-starter/event-driven-convention.md
@@ -38,7 +38,7 @@ content_hash: 02975087ebd599ed5978c834297c16c37ae4e31ec37d964d753353b1de9fb07d
 
 ### 规则 2：事件处理器必须实现 IHandler<T extends IEvent> 接口
 
-Handler 通过泛型参数声明订阅的事件类型。框架在启动时通过 `HandlerBeanDefinitionRegistrar` 自动扫描所有 `IHandler` 实现并注册到 `ApplicationHandlerUtils`。
+Handler 通过泛型参数声明订阅的事件类型。框架的 Handler 注册机制分为两个阶段：① `HandlerBeanDefinitionRegistrar` 只扫描带 `@Handler` 注解的类并注册为 Spring BeanDefinition（使用 `@Component`/`@Service` 标注的 Handler 则由 Spring 组件扫描注册为 Bean）；② `SpringHandlerConfiguration` 收集容器中所有 `IHandler` Bean，在构造 `SpringDefaultEventHandler`/`SpringTransactionEventHandler` 时通过 `addHandlers` 统一注册到 `ApplicationHandlerUtils`。
 
 ```java
 public interface IHandler<T extends IEvent> {
diff --git a/docs/conventions/springboot-starter/exception-handling-convention.md b/docs/conventions/springboot-starter/exception-handling-convention.md
index 6f6146175..b96238e83 100644
--- a/docs/conventions/springboot-starter/exception-handling-convention.md
+++ b/docs/conventions/springboot-starter/exception-handling-convention.md
@@ -26,20 +26,23 @@ content_hash: 669e54861ccb844ae926652bdd6b30a9a1b8bbc9f9a55ce145d19c283d499596
 所有业务校验失败、参数非法、权限不足等场景，必须抛出 `LocaleMessageException`，禁止直接使用 `RuntimeException`、`IllegalArgumentException` 等原生异常。
 
 ```java
-// 构造方式一：errCode + 默认消息（推荐用于简单场景）
-throw new LocaleMessageException("user.not.found", "用户不存在");
-
-// 构造方式二：仅 errCode，消息从 message.properties 自动解析
+// 构造方式一（推荐）：仅 errCode，消息从 message.properties 中按当前 Locale 自动解析
 throw new LocaleMessageException("user.not.found");
 
-// 构造方式三：带占位符参数，对应 properties 中 user.duplicate=用户名 {0} 已存在
+// 构造方式二：errCode + 占位符参数，对应 properties 中 user.duplicate=用户名 {0} 已存在
 throw LocaleMessageException.of("user.duplicate", username);
+
+// 构造方式三：errCode + 自定义消息，第二个参数直接使用、不走国际化（仅用于无需 i18n 的场景）
+throw new LocaleMessageException("custom.error", "自定义错误描述");
 ```
 
-### 规则 2：异常消息采用 message key + 默认消息格式
+**需要国际化消息时，必须使用单参构造 `LocaleMessageException(errCode)` 或静态工厂 `LocaleMessageException.of(errCode, args)`**，消息由框架从 message.properties 中按请求 Locale 解析。
+
+### 规则 2：异常消息通过 message key 国际化解析
 
 - 第一个参数为 **errCode**（即 i18n message key），用于前端匹配和国际化查找。
-- 第二个参数为 **默认消息**（defaultMessage），当 message.properties 中未配置该 key 时作为兜底展示。
+- 需要国际化的消息使用单参构造 `LocaleMessageException(errCode)` 或 `LocaleMessageException.of(errCode, args)`，消息从 message.properties 中按当前请求 Locale 解析。
+- 两参构造 `LocaleMessageException(errCode, errMessage)` 的第二个参数是**直接使用、不走国际化的自定义消息**：该构造函数直接以 errMessage 构造异常，**不会查询 MessageSource / message.properties，也不随 Locale 切换**，并非 "key 未配置时的兜底默认消息"。仅在确定无需国际化的场景使用。
 - errCode 命名采用 **点分隔小写** 格式，如 `order.status.invalid`、`auth.token.expired`。
 
 ### 规则 3：依赖 ExceptionConfiguration 全局拦截
@@ -83,7 +86,8 @@ public class UserService {
 
     public User getUser(Long id) {
         return userRepository.findById(id)
-                .orElseThrow(() -> new LocaleMessageException("user.not.found", "用户不存在"));
+                // 单参构造：消息从 messages.properties 中按 Locale 自动解析
+                .orElseThrow(() -> new LocaleMessageException("user.not.found"));
     }
 
     public void createUser(String username) {
@@ -147,6 +151,6 @@ public ResponseEntity<?> getUser(@PathVariable Long id) {
     }
 }
 
-// 错误 4：硬编码中文消息，不支持国际化
+// 错误 4：硬编码中文消息，两参构造的第二个参数直接使用、不走国际化
 throw new LocaleMessageException("err001", "这个用户找不到啊");
 ```
diff --git a/docs/conventions/springboot-starter/response-convention.md b/docs/conventions/springboot-starter/response-convention.md
index 1c5c30712..bbb739d63 100644
--- a/docs/conventions/springboot-starter/response-convention.md
+++ b/docs/conventions/springboot-starter/response-convention.md
@@ -31,13 +31,13 @@ content_hash: f34034d99b0e32ca0ef9f72cf98793135fd15e335facfaca548ab3caa9e14cc1
 4. **无数据操作成功返回**：使用 `Response.buildSuccess()`。
 5. **失败返回**：使用 `Response.buildFailure(errCode, errMessage)`。
 6. **禁止直接返回 Map 或自定义 DTO 作为 API 响应**。
-7. **响应 JSON 结构固定包含**：`success`（boolean）、`errCode`（string）、`errMessage`（string）、`data`（业务数据，仅 SingleResponse/MultiResponse 携带）。
+7. **响应 JSON 结构固定包含**：`success`（boolean）、`errCode`（string）、`errMessage`（string）、`data`（业务数据，仅 SingleResponse/MultiResponse/MapResponse 携带，`Response` 本身不携带）。
 
 ### 补充说明
 
 - `SingleResponse.empty()` 用于查询可能为空但语义上成功的场景，返回 `{ success: true, data: null }`。
 - `MultiResponse.of(collection, total)` 用于手动分页场景；`MultiResponse.of(page)` 自动从 Spring Data Page 提取 total。
-- `MultiResponse.empty()` 返回空列表 `{ success: true, data: { total: 0, list: [] } }`。
+- `MultiResponse.empty()` 返回空结果 `{ success: true, data: { total: 0, list: null } }`（注意：内部 `Content.list` 未初始化，序列化结果为 `null` 而非空数组；如需空数组语义，可改用 `MultiResponse.of(Collections.emptyList())`）。
 - 异常处理应通过全局异常处理器统一转换为 `Response.buildFailure(...)`，Controller 内不要 try-catch 后自行拼装错误响应。
 
 ## 使用实例
diff --git a/docs/example-guide.md b/docs/example-guide.md
new file mode 100644
index 000000000..fdd0154d8
--- /dev/null
+++ b/docs/example-guide.md
@@ -0,0 +1,155 @@
+# 示例工程手册 | Example Guide
+
+> 本手册仅适用于 `17.3.x` 版本线（JDK 17 / Spring Boot 3.x）。`8.2.x` 版本线不提供示例工程。
+
+仓库中的 `example`（DDD 示例后端）与 `frontend`（前端示例 monorepo）均为**示例工程**，不属于框架核心内容，仅用于演示框架各能力的落地方式，可直接删除不影响框架本身。
+
+## 一、环境要求
+
+| 依赖 | 版本要求 | 说明 |
+|------|---------|------|
+| JDK | 17+ | 17.3.x 版本线最低要求 |
+| Maven | 3.6+ | 仓库自带 `mvnw` Wrapper，无需单独安装 |
+| Node.js | 20+ | 仅运行前端示例时需要 |
+| pnpm | 10+ | 仅运行前端示例时需要 |
+
+默认配置下**无需**安装数据库与 Redis：后端使用 H2 文件数据库、JWT 无状态认证。
+
+## 二、示例后端（example）
+
+### 2.1 模块结构
+
+`example` 是一个遵循 DDD 分层（`interface → app → domain ← infra`）的多模块工程：
+
+```
+example/
+├── example-server           # Spring Boot 启动入口（端口 8090）
+├── example-interface        # 接口层：Controller（API）、事件 Handler、ApplicationRunner
+├── example-app              # 应用层
+│   ├── example-app-query        # 查询服务（CQRS Query 侧）
+│   ├── example-app-cmd-domain   # 命令服务（CQRS Command 侧，领域编排）
+│   └── example-app-cmd-meta     # 元数据命令服务
+├── example-domain           # 领域层
+│   └── example-domain-user      # 用户领域（Entity、Repository 接口、Service、Event、Gateway）
+└── example-infra            # 基础设施层
+    ├── example-infra-jpa        # JPA 持久化实现（实现 domain 层 Repository 接口）
+    └── example-infra-security   # 安全配置（UserDetailsService、PasswordEncoder 实现）
+```
+
+### 2.2 启动后端
+
+在仓库根目录执行：
+
+```bash
+# 首次运行建议先安装所有模块
+./mvnw clean install -DskipTests
+
+# 启动示例应用（端口 8090）
+./mvnw spring-boot:run -pl example/example-server
+```
+
+启动说明：
+
+* 数据源为 H2 文件数据库（`jdbc:h2:file:./example.db`），`ddl-auto=update` 自动建表，无需初始化脚本；
+* 应用启动时 `UserRunner` 会自动初始化内置管理员账号：**用户名 `admin`，密码 `admin`**；
+* 已启用 JWT 无状态认证（`codingapi.security.jwt.enable=true`）。
+
+### 2.3 登录获取 Token
+
+框架的登录地址默认为 `POST /user/login`（可通过 `codingapi.security.login-processing-url` 修改），请求体为 JSON：
+
+```bash
+curl -X POST http://localhost:8090/user/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"admin"}'
+```
+
+响应示例（`SingleResponse<LoginResponse>`）：
+
+```json
+{
+  "success": true,
+  "errCode": null,
+  "errMessage": null,
+  "data": {
+    "username": "admin",
+    "token": "eyJhbGciOi...",
+    "authorities": [],
+    "data": null
+  }
+}
+```
+
+### 2.4 携带 Token 调用业务接口
+
+除 `codingapi.security.ignore-urls` 配置的免认证地址（默认 `/open/**` 等）外，业务接口需在请求头 `Authorization` 中携带登录返回的 `token`：
+
+```bash
+TOKEN="<登录返回的 token>"
+
+# 分页查询用户列表（GET /api/query/user/list）
+curl 'http://localhost:8090/api/query/user/list?current=0&pageSize=20' \
+  -H "Authorization: $TOKEN"
+
+# 按字段动态过滤（RequestFilter：等值查询）
+curl 'http://localhost:8090/api/query/user/list?current=0&pageSize=20&username=admin' \
+  -H "Authorization: $TOKEN"
+
+# 新增/修改用户（id>0 为修改，id=0 为新增）
+curl -X POST http://localhost:8090/api/cmd/user/save \
+  -H "Authorization: $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"id":0,"name":"张三","username":"zhangsan","password":"123456"}'
+
+# 删除用户
+curl -X POST http://localhost:8090/api/cmd/user/remove \
+  -H "Authorization: $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"id":1}'
+
+# 免认证接口示例（框架内置）
+curl http://localhost:8090/open/version
+```
+
+### 2.5 可选配置
+
+`example/example-server/src/main/resources/application.properties` 中提供了注释形式的可选配置：
+
+* **切换 MySQL**：取消注释 `com.mysql.cj.jdbc.Driver` 相关配置，注释 H2 配置，并自行创建 `example` 数据库；
+* **切换 Redis 有状态认证**：取消注释 `codingapi.security.redis.enable=true` 与 `spring.data.redis.*` 配置，并启动本地 Redis。
+
+常用框架配置项：
+
+```properties
+# 免认证 URL 列表
+codingapi.security.ignore-urls=/open/**,/#/**,/,/**.css,/**.js,/**.svg,/**.png,/**.ico
+# 事件异步线程池大小
+codingapi.framework.handler-thread-pool-size=20
+```
+
+## 三、示例前端（frontend）
+
+前端示例为 pnpm workspace monorepo，包含 `apps/pc`（PC 端管理后台）与 `apps/mobile`（移动端）两个应用，详细脚本说明见 [frontend/README.md](../frontend/README.md)。
+
+```bash
+cd frontend
+pnpm install
+
+pnpm dev:pc        # PC 端开发模式（代理后端 8090）
+pnpm dev:mobile    # 移动端开发模式（代理后端 8090）
+pnpm mock:pc       # PC 端 Mock 模式（无需后端）
+pnpm mock:mobile   # 移动端 Mock 模式（无需后端）
+pnpm build:pc      # PC 端生产构建
+pnpm build:mobile  # 移动端生产构建
+```
+
+运行 `dev:*` 前请先启动示例后端（见 2.2），开发服务会将 `/api`、`/user` 等请求代理到 `http://localhost:8090`。
+
+## 四、常见问题
+
+**Q1：启动报端口占用？**
+示例默认使用 `8090` 端口，可通过 `server.port` 修改。
+
+**Q2：请求业务接口返回 `token must not null` / `token expire`？**
+请求头未携带 `Authorization`，或 Token 已过期，请重新调用 `/user/login` 获取。
+
+**Q3：如何清理 H2 数据？**
+停止应用后删除运行目录下的 `example.db*` 文件，重启即自动重建。
diff --git a/docs/wiki/home.md b/docs/wiki/home.md
index b5aa5f33e..3b28b0ea7 100644
--- a/docs/wiki/home.md
+++ b/docs/wiki/home.md
@@ -16,6 +16,13 @@ The examples below use an official release version (e.g. `17.3.0`; see the Maven
         <version>17.3.0</version>
     </dependency>
     
+     <!-- 脚本引擎框架 -->
+     <dependency>
+        <groupId>com.codingapi.springboot</groupId>
+        <artifactId>springboot-starter-script</artifactId>
+        <version>17.3.0</version>
+     </dependency>
+    
      <!-- 快速数据呈现框架 -->
      <dependency>
         <groupId>com.codingapi.springboot</groupId>
@@ -39,7 +46,8 @@ The examples below use an official release version (e.g. `17.3.0`; see the Maven
 ```
 
 
-[springboot-starter](./springboot-starter)  
-[springboot-starter-security](./springboot-starter-security)  
+[springboot-starter](./springboot-starter.md)  
+[springboot-starter-script](./springboot-starter-script.md)  
+[springboot-starter-security](./springboot-starter-security.md)  
 [springboot-starter-data-fast](./springboot-starter-data-fast.md)   
 [springboot-starter-data-authorization](./springboot-starter-data-authorization.md)   
diff --git a/docs/wiki/springboot-starter-data-authorization.md b/docs/wiki/springboot-starter-data-authorization.md
index 26d08a4c0..978a153f0 100644
--- a/docs/wiki/springboot-starter-data-authorization.md
+++ b/docs/wiki/springboot-starter-data-authorization.md
@@ -101,3 +101,57 @@ DataAuthorizationContext.getInstance().addDataAuthorizationFilter(new DataAuthor
 实现的拦截器，需要添加到DataAuthorizationContext.getInstance()中才可以使用。可以通过上述实例的手动模式添加，
 也可以通过定义DataAuthorizationFilter的@Bean方式添加，当设置为@Bean时既可以自动加入到DataAuthorizationContext.getInstance()中。
 
+## 配置项
+
+在`application.properties`中可用的配置项（配置前缀为`codingapi.data-authorization`）：
+
+```properties
+# 是否打印拦截后的SQL，便于调试数据权限条件，默认false
+codingapi.data-authorization.show-sql=false
+```
+
+| 配置项 | 对应字段 | 默认值 | 说明 |
+|--------|----------|--------|------|
+| `codingapi.data-authorization.show-sql` | `DataAuthorizationProperties.showSql` | `false` | 设置为`true`时，SQL被拦截改写后会以INFO日志打印拦截后的SQL（`newSql`），便于调试数据权限条件 |
+
+## 扩展点
+
+### 跳过特定SQL的拦截
+
+`DataAuthorizationContext`支持设置跳过拦截时的SQL处理器`SkipAuthorizationFilter`，默认为`DefaultSkipAuthorizationFilter`（原样返回SQL不做任何处理）。
+配合`SQLRunningContext.getInstance().skipDataAuthorization()`使用时，被跳过拦截的SQL会先经过`SkipAuthorizationFilter.filter(sql)`处理，
+可以通过自定义实现跳过特定SQL的拦截或对SQL进行改写，例如：
+
+```java
+DataAuthorizationContext.getInstance().setSkipAuthorizationFilter(sql -> sql);
+
+SQLRunningContext.getInstance().skipDataAuthorization(() -> {
+    // 该代码块内的SQL查询不会经过数据权限拦截
+    List<Map<String, Object>> data = jdbcTemplate.queryForList(sql);
+});
+```
+
+### 自定义处理器（@Bean自动注册）
+
+在`DataAuthorizationConfiguration`中，通过定义以下类型的`@Bean`即可自动替换框架的默认实现（均以`@Autowired(required = false)`方式注入，未提供时使用默认实现）：
+
+| Bean类型 | 默认实现 | 职责 |
+|----------|----------|------|
+| `RowHandler` | `DefaultRowHandler` | 行权限处理器，负责为查询SQL构建行级权限过滤条件 |
+| `ColumnHandler` | `DefaultColumnHandler` | 列权限处理器，负责对结果集（ResultSet）的列值进行拦截处理 |
+| `SQLInterceptor` | `DefaultSQLInterceptor` | SQL拦截器，负责SQL的前置判断（`beforeHandler`）、改写（`postHandler`）与后置处理（`afterHandler`） |
+
+示例：
+
+```java
+@Bean
+public RowHandler rowHandler() {
+    return (subSql, tableName, tableAlias) -> {
+        if (tableName.equalsIgnoreCase("t_user")) {
+            return Condition.formatCondition("%s.id > 1 ", tableAlias);
+        }
+        return null;
+    };
+}
+```
+
diff --git a/docs/wiki/springboot-starter-data-fast.md b/docs/wiki/springboot-starter-data-fast.md
index 02a43ecd0..e915b3ac7 100644
--- a/docs/wiki/springboot-starter-data-fast.md
+++ b/docs/wiki/springboot-starter-data-fast.md
@@ -9,7 +9,7 @@ springboot-starter-data-fast
 
 
 import com.codingapi.springboot.fast.entity.Demo;
-import com.codingapi.springboot.fast.query.FastRepository;
+import com.codingapi.springboot.fast.jpa.repository.FastRepository;
 
 public interface DemoRepository extends FastRepository<Demo,Integer> {
 
@@ -17,6 +17,21 @@ public interface DemoRepository extends FastRepository<Demo,Integer> {
 
 
 ```
+
+> 注：示例中的 `com.codingapi.springboot.fast.entity.Demo` 是模块的测试用示例实体，位于 `springboot-starter-data-fast` 的 `src/test/java` 目录下（对应表 `t_demo`）。实际使用时请定义自己的 `@Entity` 实体类并替换。
+
+### FastRepository 能力概览
+
+`FastRepository<T, ID>` 继承了 `JpaRepository`、`JpaSpecificationExecutor`、`DynamicRepository`（HQL 动态查询）与 `DynamicNativeRepository`（原生 SQL 查询），除 JPA 标准能力外还提供：
+
+| 能力 | 方法 | 说明 |
+|------|------|------|
+| 条件过滤查询 | `findAll(PageRequest)` / `pageRequest(PageRequest)` | 根据 Filter 自动构建 Example 或动态 HQL 查询 |
+| 高级搜索 | `searchRequest(SearchRequest)` | 基于 `SearchRequest`（前端检索条件对象）的分页查询 |
+| 动态 HQL 查询 | `dynamicListQuery(...)` / `dynamicPageQuery(...)` | HQL 列表 / 分页查询，可配合 `SQLBuilder` 映射 DTO |
+| Map 视图查询 | `dynamicMapListQuery(QueryColumns, sql, params...)` / `dynamicMapPageQuery(QueryColumns, sql, countSql, request, params...)` | 通过 `QueryColumns` 指定投影列，返回 `MapViewResult` |
+| 原生 SQL 查询 | `dynamicNativeListQuery(...)` / `dynamicNativePageQuery(...)` / `dynamicNativeListMapQuery(...)` / `dynamicNativeMapPageMapQuery(...)` | `DynamicNativeRepository` 提供的原生 SQL 查询，支持实体映射或 `Map` 结果 |
+
 动态FastRepository的能力展示
 
 ```
@@ -58,7 +73,7 @@ public interface DemoRepository extends FastRepository<Demo,Integer> {
             PageRequest request = new PageRequest();
             request.setCurrent(1);
             request.setPageSize(10);
-            request.addFilter("name", PageRequest.FilterRelation.LIKE, "%2%");
+            request.addFilter("name", Relation.LIKE, "%2%");
             //sql: select demo0_.id as id1_0_, demo0_.name as name2_0_, demo0_.sort as sort3_0_ from t_demo demo0_ where demo0_.name like ? limit ?
 
             Page<Demo> page = demoRepository.pageRequest(request);
@@ -145,19 +160,44 @@ public interface DemoRepository extends FastRepository<Demo,Integer> {
 
 ```
 
+> 说明：示例中的 `PageRequest`、`Relation`、`Filter` 均来自核心模块 `springboot-starter`，需导入
+> `com.codingapi.springboot.framework.dto.request.PageRequest` / `Relation` / `Filter`。
+> 条件关系使用独立枚举 `com.codingapi.springboot.framework.dto.request.Relation`（如 `Relation.LIKE`、`Relation.IN`），
+> 而非 `PageRequest` 的内部枚举。
+
 ## ScriptMapping 教程
 
 通过动态添加mvc mapping实现查询功能.
 
 
-```
-ScriptMapping scriptMapping = new ScriptMapping({mapinggUrl}, {mapinggMethod}, {mappingGrovvry});
-scriptMappingRegister.addMapping(scriptMapping);
+构造签名：`ScriptMapping(String mapping, ScriptMethod scriptMethod, String script)`
 
+* mapping 是mvc接口的访问地址
+* scriptMethod 是mvc接口的请求方式，为枚举 `ScriptMethod.GET` / `ScriptMethod.POST`
+* script 是接口执行的 Groovy 查询脚本内容
+
+```java
+import com.codingapi.springboot.fast.script.ScriptMapping;
+import com.codingapi.springboot.fast.script.ScriptMethod;
+
+// 定义接口执行的 Groovy 脚本
+String script = """
+        var name = $request.getParameter("name","");
+        var sql = "select * from api_mapping where 1=1 ";
+        var params = [];
+        if(!"".equals(name)){
+            sql += " and name = ? ";
+            params.add(name);
+        }
+        return $jdbc.queryForMapList(sql, params.toArray());
+        """;
+
+// 注册一个 GET 方式的 /api/demo/list 查询接口
+ScriptMapping scriptMapping = new ScriptMapping("/api/demo/list", ScriptMethod.GET, script);
+fastScriptMappingRegister.addMapping(scriptMapping);
 ```
-mapinggUrl 是mvc接口的地址    
-mapinggMethod 是mvc接口的请求方式  
-mappingGrovvry 是执行的查询脚本  
+
+其中 `fastScriptMappingRegister` 为 `FastScriptMappingRegister` Bean，`addMapping(ScriptMapping)` 会将脚本动态注册为 MVC 接口；脚本执行结果会自动封装为 `Response`（List / Page 结果返回 `MultiResponse`，其余返回 `SingleResponse`）。
 
 脚本实例代码： 
 * 动态分页查询
@@ -182,8 +222,8 @@ sql += " limit ?,?";
 // 添加分页参数
 params.add(pageRequest.getOffset());
 params.add(pageRequest.getPageSize());
-// 执行分页查询
-return $jdbc.queryForPage(sql,countSql,pageRequest,params.toArray());
+// 执行分页查询（结果为 Map 列表，使用 queryForMapPage）
+return $jdbc.queryForMapPage(sql,countSql,pageRequest,params.toArray());
 ```
 * 动态条件查询
 ```
@@ -197,8 +237,8 @@ if(!"".equals(name)){
     sql += " and name = ? ";
     params.add(name);
 }
-// 执行查询
-return $jdbc.queryForList(sql,params.toArray());
+// 执行查询（结果为 Map 列表，使用 queryForMapList）
+return $jdbc.queryForMapList(sql,params.toArray());
 ```
 
 脚本语法介绍：  
@@ -215,20 +255,26 @@ var pageSize = pageRequest.getPageSize();
 // 获取分页对象的偏移量
 var offset = pageRequest.getOffset();
 ```
-* $jdbc
+* $jdbc（`JdbcQuery` 实例，常用方法签名）
 ```
-// 查询jdbcSQL $jdbc.queryForList({sql},{params})
+// Map 列表查询：$jdbc.queryForMapList({sql}, {params}...)，结果列名自动转驼峰
+// 实体映射列表查询：$jdbc.queryForList({sql}, {clazz}, {params}...)
+// Map 分页查询：$jdbc.queryForMapPage({sql}, {countSql}, {pageRequest}, {params}...)
+// 实体映射分页查询：$jdbc.queryForPage({sql}, {countSql}, {clazz}, {pageRequest}, {params}...)
 
-// 查询无条件的数据
-var res = $jdbc.queryForList("select * from api_mapping");
+// 查询无条件的数据（返回 List<Map<String,Object>>）
+var res = $jdbc.queryForMapList("select * from api_mapping");
 // 查询有条件的数据
-var res = $jdbc.queryForList("select * from api_mapping where name = ?",name);
+var res = $jdbc.queryForMapList("select * from api_mapping where name = ?",name);
 // 查询多条件的数据
-var res = $jdbc.queryForList("select * from api_mapping where name = ? and url = ?",name,url);
+var res = $jdbc.queryForMapList("select * from api_mapping where name = ? and url = ?",name,url);
+
+// 需要将结果映射为实体类时，使用 queryForList(sql, Class, params...)
+var res = $jdbc.queryForList("select * from api_mapping where name = ?",com.example.entity.ApiMapping.class,name);
 
-// 分页查询 $jdbc.queryForPage({sql},{countSql},{pageRequest},{params})
-var res = $jdbc.queryForPage("select * from api_mapping where name = ? and url = ?",
-"select count(1) from api_mapping where name = ? and url = ?",pageRequest,params.toArray());
+// 分页查询（Map 结果） $jdbc.queryForMapPage({sql},{countSql},{pageRequest},{params}...)
+var res = $jdbc.queryForMapPage("select * from api_mapping where name = ? and url = ?",
+"select count(1) from api_mapping where name = ? and url = ?",pageRequest,name,url);
 ```
 * $jpa
 ```
diff --git a/docs/wiki/springboot-starter-script.md b/docs/wiki/springboot-starter-script.md
new file mode 100644
index 000000000..fae22e211
--- /dev/null
+++ b/docs/wiki/springboot-starter-script.md
@@ -0,0 +1,416 @@
+springboot-starter-script 功能介绍
+
+## 模块定位
+
+`springboot-starter-script` 是框架的 Groovy 脚本引擎模块，提供以下核心能力：
+
+1. **运行时编译**：基于 `GroovyShell` 在应用运行时动态编译 Groovy 脚本，无需重启即可变更业务逻辑；
+2. **缓存**：编译后的脚本对象按脚本内容的 SHA256 摘要做 LRU 缓存，重复执行时直接命中缓存，避免重复编译；
+3. **热更新**：通过 REST API 或 `GroovyScript.save()` 更新脚本内容并重新编译，实现脚本的热更新；
+4. **REST API**：内置 `GroovyScriptController`，提供脚本编译、查询、保存（热更新）的 HTTP 端点；
+5. **元数据扫描**：通过注解（`@ScriptType`/`@ScriptField`/`@ScriptFunction`/`@ScriptParameter`）自动扫描脚本的请求参数、绑定对象与返回类型，生成结构化的元数据，便于前端渲染脚本调用表单；
+6. **事务支持**：脚本执行支持 `DEFAULT`/`COMMIT`/`READONLY` 三种事务模式。
+
+Maven 依赖：
+
+```xml
+<!-- 脚本引擎框架 -->
+<dependency>
+    <groupId>com.codingapi.springboot</groupId>
+    <artifactId>springboot-starter-script</artifactId>
+    <version>17.3.0</version>
+</dependency>
+```
+
+模块依赖 `springboot-starter`、`spring-boot-starter-web` 以及 Groovy 4.x（`groovy`、`groovy-json`、`groovy-xml`）。自动配置类为 `com.codingapi.springboot.script.AutoConfiguration`，同时注册在 `META-INF/spring.factories` 与 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中。
+
+### 配置项
+
+配置前缀为 `codingapi.script`（绑定 `GroovyScriptProperties`）：
+
+```properties
+# 临时脚本到期时间（毫秒），默认15分钟 1000*60*15=900000
+codingapi.script.temp-valid-time=900000
+# 脚本执行对象（编译后的Script）最大缓存大小，默认 10*1024
+codingapi.script.shell-max-cache-size=10240
+```
+
+## 核心类与用法
+
+### GroovyScriptRuntime（脚本运行时）
+
+`GroovyScriptRuntime` 是脚本的编译与执行入口，内部持有 `GroovyShell` 与一个 LRU 缓存（基于 `LinkedHashMap` 的访问顺序模式，容量由构造参数 `maxCacheSize` 控制，超出容量时自动淘汰最久未访问的条目）。
+
+主要方法：
+
+```java
+// 按最大缓存容量构造运行时
+public GroovyScriptRuntime(int maxCacheSize)
+
+// 编译脚本；cache=true 时以脚本内容的 SHA256 为 key 缓存编译结果
+public void compile(String script, boolean cache)
+public void compile(String script)
+
+// 执行脚本中的函数（method），binds 为绑定对象，args 为函数参数
+public <T> T invoke(String method, String script, Class<T> returnType,
+                    Map<String,Object> binds, Object... args)
+public <T> T invoke(String method, String script, Class<T> returnType, Object... args)
+public <T> T invoke(String method, String script, Class<T> returnType,
+                    TransactionMode transactionMode, Map<String,Object> binds, Object... args)
+
+// 直接执行整个脚本（脚本顶层语句作为执行体）
+public <T> T run(String script, Class<T> returnType, Map<String,Object> binds)
+public <T> T run(String script, Class<T> returnType, TransactionMode transactionMode, Map<String,Object> binds)
+
+// 缓存维护
+public void clearCache()
+public int cacheSize()
+public int getMaxCacheSize()
+```
+
+说明：
+
+- `invoke`/`run` 执行时会先按 SHA256 查找缓存，未命中则编译并写入缓存，因此执行路径天然具备编译缓存能力；
+- `binds` 中的每个键值会通过 `Script.setProperty(key, value)` 注入脚本，脚本中可直接以该键名访问（如 `$request`、`$repository`）；
+- 事务模式由 `TransactionMode` 枚举控制，底层委托 `springboot-starter` 的 `TransactionManagerContext` 实现：
+  - `DEFAULT`：不做事务处理；
+  - `COMMIT`：在新事务（`PROPAGATION_REQUIRES_NEW`）中执行，正常结束提交、异常回滚；
+  - `READONLY`：以只读新事务执行，结束时回滚，保证数据不被修改。
+
+`GroovyScriptRuntimeContext` 是 `GroovyScriptRuntime` 的单例持有者（`GroovyScriptRuntimeContext.getInstance()`），运行时容量取自配置项 `codingapi.script.shell-max-cache-size`，并对外暴露 `compile`/`invoke`/`run`/`clearCache`/`cacheSize` 等委托方法。
+
+### GroovyScript 与 Builder（脚本对象）
+
+`GroovyScript` 是脚本的领域对象，字段如下：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `key` | `String`（final） | 脚本唯一编码 |
+| `script` | `String` | 脚本内容 |
+| `description` | `String` | 脚本描述信息 |
+| `method` | `String` | 脚本主函数名称 |
+| `returnType` | `Class<?>` | 返回数据类型 |
+| `binds` | `Map<String, Class<?>>` | 绑定对象（键为脚本内变量名，值为类型） |
+| `requests` | `Map<String, Class<?>>` | 请求参数对象（键为参数名，值为类型） |
+| `typeOne` / `typeTwo` | `String` | 一级 / 二级分类 |
+| `tag` | `String` | 标记参数 |
+| `remark` | `String` | 备注信息 |
+| `createTime` / `updateTime` | `long` | 创建 / 更新时间戳 |
+
+通过 `GroovyScript.builder(String key)` 链式构建：
+
+```java
+String script = """
+        def run(request){
+            return request;
+        }
+        """;
+
+GroovyScript groovyScript =
+        GroovyScript.builder("invoke")
+                .script(script)
+                .description("返回入参本身")
+                .method("run")
+                .tag("123")
+                .returnType(Integer.class)
+                .requests(Map.of("request", Integer.class))
+                .binds(Map.of("$repository", SomeRepository.class))
+                .typeOne("demo").typeTwo("test").remark("备注")
+                .build();
+```
+
+行为方法：
+
+```java
+// 编译（委托 GroovyScriptRuntimeContext）
+groovyScript.compile();           // 编译，不缓存
+groovyScript.compile(true);       // 编译并缓存
+
+// 执行整个脚本
+groovyScript.run();
+groovyScript.run(Map.of("$request", 100));
+groovyScript.run(TransactionMode.READONLY);
+
+// 执行脚本主函数（method 字段指定的函数）
+groovyScript.invoke(100);
+groovyScript.invoke(Map.of("$repository", repository), request);
+groovyScript.invoke(TransactionMode.COMMIT, Map.of("$repository", repository), request);
+
+// 生命周期
+groovyScript.temp();              // 存入临时缓存，到期自动清理
+groovyScript.save();              // 持久化到仓储（并清理对应的临时数据）
+groovyScript.remove();            // 从仓储与临时缓存中删除
+GroovyScript copy = groovyScript.copy("newKey");  // 复制为新 key 的脚本对象
+
+// 生成元数据
+GroovyMetadata metadata = groovyScript.toMetadata();
+```
+
+### GroovyScriptCacheContext（脚本数据 LRU 缓存）
+
+`GroovyScriptCacheContext` 是 `GroovyScript` 脚本对象的内存缓存上下文（单例），内部同样是基于访问顺序的 LRU `LinkedHashMap`，容量上限为常量 `MAX_CACHE_SIZE = 10 * 1024`，超出后自动淘汰最久未访问的脚本。
+
+获取脚本时的查找链路为：**内存缓存 → 临时缓存（TempGroovyScriptContext） → 仓储（GroovyScriptRepositoryContext）**；从仓储命中后会回填内存缓存（临时数据不回填）。
+
+主要方法：
+
+```java
+GroovyScriptCacheContext.getInstance().getGroovyScript(key);   // 按查找链路获取脚本
+GroovyScriptCacheContext.getInstance().getScript(key);         // 获取脚本内容，不存在返回 ""
+GroovyScriptCacheContext.getInstance().getGroovyMetadata(key); // 获取脚本元数据
+GroovyScriptCacheContext.getInstance().save(script);           // 写入缓存
+GroovyScriptCacheContext.getInstance().cache(script);          // 写入缓存
+GroovyScriptCacheContext.getInstance().remove(key);            // 删除缓存
+GroovyScriptCacheContext.getInstance().keys();                 // 所有缓存 key
+GroovyScriptCacheContext.getInstance().count();                // 缓存数量
+GroovyScriptCacheContext.getInstance().setBatchCache(list);    // 批量写入缓存
+GroovyScriptCacheContext.getInstance().compileAll(true);       // 批量编译缓存中的脚本
+GroovyScriptCacheContext.getInstance().clear();                // 清空缓存
+```
+
+### TempGroovyScriptContext（临时脚本）
+
+临时脚本用于"编辑中尚未保存"的草稿场景：脚本通过 `groovyScript.temp()` 进入临时缓存后，会在到期时间（配置项 `codingapi.script.temp-valid-time`，默认 15 分钟）后被自动清理。
+
+实现要点：
+
+- `TempGroovyScript` 包装了 `GroovyScript` 与到期时间戳 `clearTime`，提供 `isExpired()` 判断；
+- `TempGroovyScriptContext` 所有临时脚本共用**一个** daemon 调度线程（`temp-groovy-script-clear` 的 `ScheduledExecutorService`）执行到期清理，避免为每个脚本创建线程造成线程泄漏；
+- 重复 `save` 同一 key 时会取消旧的清理任务、重新计时；到期清理采用原子的 `remove(key, value)` 判断，防止误删已被刷新的脚本。
+
+主要方法：
+
+```java
+TempGroovyScriptContext.getInstance().save(groovyScript);  // 写入临时缓存并开始计时
+TempGroovyScriptContext.getInstance().getGroovyScript(key); // 获取临时脚本（不存在或已过期返回 null）
+TempGroovyScriptContext.getInstance().count();              // 当前临时脚本数量
+TempGroovyScriptContext.getInstance().findAll();            // 所有临时脚本（含到期时间）
+TempGroovyScriptContext.getInstance().remove(key);          // 删除临时脚本（并取消清理任务）
+TempGroovyScriptContext.getInstance().loadAll(list);        // 启动时批量加载（过期的直接剔除）
+TempGroovyScriptContext.getInstance().clear();              // 清空
+```
+
+### GroovyMetadataScannerUtils（元数据与注解扫描）
+
+`GroovyMetadataScannerUtils.scanner(GroovyScript)` 用于为脚本生成元数据 `GroovyMetadata`，`GroovyScript.toMetadata()` 即委托该工具。扫描流程：
+
+1. 先尝试自定义元数据策略 `GroovyMetadataGenerateStrategyContext`，若存在匹配策略则直接返回策略生成的元数据；
+2. 否则通过反射扫描 `requests`（请求参数）、`binds`（绑定对象）、`returnType`（返回类型）涉及的 Java 类型，递归收集类型上声明的脚本注解信息；简单类型（如 `Integer`、`String`）不展开，并通过扫描历史防止循环引用。
+
+扫描依赖的注解（位于 `com.codingapi.springboot.script.annotation` 包）：
+
+| 注解 | 作用目标 | 属性 | 说明 |
+|------|----------|------|------|
+| `@ScriptType` | 类型（TYPE） | `description` | 描述一个参与脚本交互的 Java 类型 |
+| `@ScriptField` | 字段 / 方法（FIELD, METHOD） | `name`、`description` | 声明该字段可被脚本访问 |
+| `@ScriptFunction` | 方法（METHOD） | `name`（必填）、`description` | 声明该方法可被脚本调用 |
+| `@ScriptParameter` | 参数（PARAMETER） | `name`、`description` | 描述 `@ScriptFunction` 方法的参数 |
+
+注解使用示例（取自模块测试代码）：
+
+```java
+@ScriptType(description = "test")
+public class MyTest {
+
+    @ScriptField(name = "id", description = "id")
+    private Long id;
+
+    @ScriptField(name = "name", description = "name")
+    private String name;
+}
+
+public class MyScriptRequest extends BaseRequest {
+
+    @ScriptField(name = "count", description = "总数量")
+    private final int count;
+
+    @ScriptFunction(name = "isSupport", description = "是否匹配")
+    public boolean isSupport(@ScriptParameter(description = "总数") int count) {
+        return this.count == count;
+    }
+}
+```
+
+生成的 `GroovyMetadata` 结构：
+
+```java
+public class GroovyMetadata {
+    private final List<GroovyField> requests;    // 请求参数列表
+    private final List<GroovyField> binds;       // 绑定对象列表
+    private final String mainMethod;             // 主函数名称
+    private final String returnType;             // 返回类型名称
+    private final Map<String, GroovyType> types; // 涉及的数据类型（含 fields 与 functions）
+    private final String description;            // 脚本说明
+}
+```
+
+其中 `GroovyType` 描述一个数据类型（含 `fields` 字段列表与 `functions` 函数列表），`GroovyField` 描述单个字段/参数（`name`、`description`、`dataType`），`GroovyFunction` 描述可调用的函数（`name`、`description`、`returnType`、`parameters`）。
+
+元数据扫描提供三个扩展点（均为单例上下文 + 策略接口）：
+
+| 扩展点 | 接口 | 注册方法 | 用途 |
+|--------|------|----------|------|
+| 类型映射 | `ScriptTypeMapping`（`support` / `mapping`） | `ScriptTypeMappingContext.getInstance().addMapping(...)` | 将元数据中的类型映射为其他类型，例如把 `Integer` 显示为 `int` |
+| 元数据调整 | `GroovyTypeFixStrategy`（`support` / `fix(GroovyScript, GroovyType)`） | `GroovyTypeFixStrategyContext.getInstance().addFixStrategy(...)` | 在类型扫描完成后调整/补充该类型的元数据 |
+| 元数据生成 | `GroovyMetadataGenerateStrategy`（`support` / `generate`） | `GroovyMetadataGenerateStrategyContext.getInstance().addGenerateStrategy(...)` | 完全自定义元数据，命中后跳过注解扫描 |
+
+### @GroovyScript 注解与字段扫描
+
+`@GroovyScript`（作用于字段）用于标记对象中"存放脚本 key"的字段。`GroovyScriptAnnotationScannerUtils.findGroovyScriptFields(Object target)` 可以递归收集对象下所有被 `@GroovyScript` 标记字段的值（即脚本 key 列表），并支持批量更新：
+
+```java
+// Node.script 字段标注了 @GroovyScript
+List<String> keys = GroovyScriptAnnotationScannerUtils
+        .findGroovyScriptFields(workflow).getKeys();
+
+// 批量更新脚本 key
+GroovyScriptFieldResult result = GroovyScriptAnnotationScannerUtils
+        .findGroovyScriptFields(workflow);
+result.update(value -> "K123456");
+```
+
+该能力可用于工作流等场景：业务对象持有若干脚本 key 引用，保存/复制业务对象时可以整体迁移其关联的脚本。
+
+### GroovyScriptEngineRunner（启动加载与停机持久化）
+
+`GroovyScriptEngineRunner` 实现了 `InitializingBean` 与 `DisposableBean`，由 `AutoConfiguration` 以 `tempClearRunner` 名称注册为 Bean：
+
+- **启动时**（`afterPropertiesSet`）：从 `TempGroovyScriptRepositoryContext` 分页读取临时脚本数据，批量加载到 `TempGroovyScriptContext`（已过期的数据在加载时剔除），恢复停机前的临时脚本；
+- **停机时**（`destroy`）：将 `TempGroovyScriptContext` 中仍有效的临时脚本写回仓储，保证临时脚本跨重启不丢失。
+
+## REST API
+
+`GroovyScriptController` 提供脚本管理的 HTTP 端点，基础路径为 `/api/groovy-script`：
+
+| 端点 | 方法 | 请求 | 响应 | 说明 |
+|------|------|------|------|------|
+| `/api/groovy-script/compile` | POST | `ScriptCompileRequest`：`{"cache": true, "script": "脚本内容"}` | `Response` | 编译脚本；`cache=true` 时缓存编译结果。编译失败抛出 `LocaleMessageException("script.compile.error")` |
+| `/api/groovy-script/getScript` | GET | Query 参数 `key` | `SingleResponse<String>` | 按 key 获取脚本内容；不存在抛出 `LocaleMessageException("script.null")` |
+| `/api/groovy-script/getMetadata` | GET | Query 参数 `key` | `SingleResponse<GroovyMetadata>` | 按 key 获取脚本元数据；不存在抛出 `LocaleMessageException("script.null")` |
+| `/api/groovy-script/save` | POST | `ScriptSaveRequest`：`{"key": "脚本key", "script": "新脚本内容"}` | `Response` | 热更新脚本（见下文流程） |
+
+`save` 接口的热更新流程：
+
+1. 先在临时缓存中查找该 key：命中则更新脚本内容 → `compile(true)` 编译并缓存 → `temp()` 继续作为临时脚本保存；
+2. 临时缓存未命中则在脚本缓存/仓储中查找：命中则更新脚本内容 → `compile(true)` → `save()` 持久化；
+3. 两处均未命中则抛出 `LocaleMessageException("script.null", "脚本对象不存在")`；编译异常统一抛出 `LocaleMessageException("script.compile.error")`。
+
+## 仓储扩展
+
+脚本的持久化通过仓储接口抽象，默认提供内存实现，可按需替换为数据库等自定义实现。
+
+### GroovyScriptRepository（正式脚本仓储）
+
+```java
+public interface GroovyScriptRepository {
+
+    void save(GroovyScript groovyScript);
+
+    void delete(String key);
+
+    GroovyScript get(String key);
+}
+```
+
+默认实现 `DefaultGroovyScriptRepository` 基于内存 `HashMap` 存储。通过 `GroovyScriptRepositoryContext`（单例）访问与替换：
+
+```java
+// 获取脚本（GroovyScript.save()/remove() 内部也走该上下文）
+GroovyScript script = GroovyScriptRepositoryContext.getInstance().get(key);
+
+// 替换为自定义实现（如 JPA 持久化）
+GroovyScriptRepositoryContext.getInstance()
+        .setGroovyScriptRepository(new MyJpaGroovyScriptRepository());
+```
+
+### TempGroovyScriptRepository（临时脚本仓储）
+
+```java
+public interface TempGroovyScriptRepository {
+
+    void save(TempGroovyScript tempGroovyScript);
+
+    void delete(String key);
+
+    TempGroovyScript get(String key);
+
+    Page<TempGroovyScript> find(PageRequest request);
+}
+```
+
+默认实现 `DefaultTempGroovyScriptRepository` 基于内存 `HashMap` 存储，`find` 按 `clearTime` 排序并返回 `PageImpl` 分页结果。通过 `TempGroovyScriptRepositoryContext`（单例）访问与替换：
+
+```java
+TempGroovyScriptRepositoryContext.getInstance()
+        .setTempGroovyScriptRepository(new MyTempGroovyScriptRepository());
+```
+
+`GroovyScriptEngineRunner` 启动时即通过该上下文分页加载临时脚本（每页 100 条）。
+
+## 与其他模块的关系
+
+- 依赖 `springboot-starter`：统一响应封装（`Response`/`SingleResponse`）、国际化异常（`LocaleMessageException`）、分页（`PageRequest`）、事务管理（`TransactionManagerContext`）、SHA256 摘要与反射注解扫描工具等基础能力均来自核心模块；
+- `springboot-starter-data-fast` 模块中的 `ScriptRuntime` 会为本模块的脚本运行时绑定 `$request`/`$jdbc`/`$jpa` 等数据访问对象，属于 data-fast 的能力范畴，此处不再展开。
+
+## 完整示例
+
+以下示例参考模块测试代码（`GroovyScriptRuntimeContextTest`），无需 Spring 上下文即可编译运行：
+
+```java
+import com.codingapi.springboot.script.GroovyScript;
+
+public class GroovyScriptDemo {
+
+    public static void main(String[] args) {
+        // 1. 函数式脚本：通过 invoke 调用脚本中的 run 函数
+        String invokeScript = """
+                def run(request){
+                    return request;
+                }
+                """;
+
+        GroovyScript invokeDemo =
+                GroovyScript.builder("invoke-demo")
+                        .script(invokeScript)
+                        .description("返回入参本身")
+                        .method("run")
+                        .returnType(Integer.class)
+                        .build();
+
+        int result = invokeDemo.invoke(100);
+        System.out.println(result);  // 100
+
+        // 2. 直接执行脚本：通过 run 执行整个脚本，binds 注入变量
+        String runScript = " return $request; ";
+
+        GroovyScript runDemo =
+                GroovyScript.builder("run-demo")
+                        .script(runScript)
+                        .returnType(Integer.class)
+                        .build();
+
+        int value = runDemo.run(java.util.Map.of("$request", 100));
+        System.out.println(value);   // 100
+    }
+}
+```
+
+在 Spring Boot 环境中（例如需要事务模式或 JPA 仓储绑定时），可参考测试类 `TransactionGroovyScriptRuntimeContextTest` 的写法：
+
+```java
+GroovyScript groovyScript =
+        GroovyScript.builder("transactionCommitRun")
+                .script("""
+                        def run(request){
+                            request.addData($repository);
+                        }
+                        """)
+                .method("run")
+                .returnType(Void.class)
+                .binds(Map.of("$repository", myTestRepository.getClass()))
+                .requests(Map.of("request", MyScriptRequest.class))
+                .build();
+
+// 在新事务中提交执行
+groovyScript.invoke(TransactionMode.COMMIT, Map.of("$repository", myTestRepository), request);
+```
diff --git a/docs/wiki/springboot-starter-security.md b/docs/wiki/springboot-starter-security.md
index 9e46eba3e..37b482fcb 100644
--- a/docs/wiki/springboot-starter-security.md
+++ b/docs/wiki/springboot-starter-security.md
@@ -2,9 +2,9 @@ springboot-starter-security 功能介绍
 
 支持无状态的JWT和有状态的redis两种不同的token机制
 
-配置文件,默认参数即说明
+配置文件及默认参数说明
 ```properties
-# JWT开关
+# JWT开关，必须显式配置为true才会启用JWT认证（默认不开启）
 codingapi.security.jwt.enable=true
 # JWT密钥 需大于32位的字符串
 codingapi.security.jwt.secret-key=codingapi.security.jwt.secretkey
@@ -19,8 +19,12 @@ codingapi.security.ase-key=QUNEWCQlXiYqJCNYQ1phc0FDRFgkJV4mKiQjWENaYXM=
 # JWT AES IV
 codingapi.security.ase-iv=QUNYRkdIQEVEUyNYQ1phcw==
 
-# Redis开关
+# Redis开关，必须显式配置为true才会启用Redis有状态认证（默认不开启）
 #codingapi.security.redis.enable=true
+# Redis token 有效时间(毫秒)，默认15分钟 1000*60*15=900000
+#codingapi.security.redis.valid-time=900000
+# Redis 更换令牌时间(毫秒)，默认10分钟后更换令牌 1000*60*10=600000
+#codingapi.security.redis.rest-time=600000
 #spring.data.redis.host=localhost
 #spring.data.redis.port=6379
 
@@ -32,14 +36,27 @@ codingapi.security.login-processing-url=/user/login
 codingapi.security.logout-url=/user/logout
 # Security 配置 不拦截的地址
 codingapi.security.ignore-urls=/open/**
-# 禁用CSRF
+# 禁用CSRF（默认true）
 codingapi.security.disable-csrf=true
-# 禁用CORS
+# 禁用CORS（默认true）
 codingapi.security.disable-cors=true
+# 禁用Basic Auth（默认true）
+codingapi.security.disable-basic-auth=true
+# 禁用FrameOptions（默认true）
+codingapi.security.disable-frame-options=true
 ```
 
+> **注意**：JWT 与 Redis 两种认证模式均通过 `@ConditionalOnProperty(havingValue = "true")` 条件装配，且未设置 `matchIfMissing`，因此**必须显式配置** `codingapi.security.jwt.enable=true` 或 `codingapi.security.redis.enable=true` 才会启用对应的认证方式，默认均不开启。
+
 ## 默认账户密码
-security默认的账户密码为admin/admin，可以通过重写UserDetailsService来实现自定义账户密码
+security默认创建了两个账户（见 `AutoConfiguration.userDetailsService()`，仅在未自定义 `UserDetailsService` 时生效）：
+
+| 账户 | 密码 | 角色 |
+|------|------|------|
+| admin | admin | ADMIN |
+| user | admin | USER |
+
+可以通过重写UserDetailsService来实现自定义账户密码
 ```java
     @Bean
     public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) {
@@ -61,24 +78,48 @@ security默认的账户密码为admin/admin，可以通过重写UserDetailsServi
 也可以通过数据库账户获取账户数据，请自己实现UserDetailsService接口
 
 ## 登录拦截
-可以通过重写SecurityLoginHandler来实现自定义登录拦截，preHandle登录前的拦截处理，postHandle登录后的拦截处理
-```
+可以通过重写SecurityLoginHandler来实现自定义登录拦截，preHandle登录前的拦截处理，postHandle登录后的拦截处理（返回值为登录响应对象）。
+
+> 说明：Spring Boot 3 使用 `jakarta.servlet` 命名空间，以下 import 为 `jakarta.servlet.http.*`；Spring Boot 2（框架 8.2.x 及以下版本）需替换为 `javax.servlet.http.*`。
+
+```java
+import com.codingapi.springboot.security.dto.request.LoginRequest;
+import com.codingapi.springboot.security.dto.response.LoginResponse;
+import com.codingapi.springboot.security.filter.SecurityLoginHandler;
+import com.codingapi.springboot.security.gateway.Token;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.core.userdetails.UserDetails;
+
+@Configuration
+public class SecurityConfiguration {
+
     @Bean
     public SecurityLoginHandler securityLoginHandler() {
         return new SecurityLoginHandler() {
             @Override
-            public void preHandle(HttpServletRequest request, HttpServletResponse response, LoginRequest handler) throws Exception {
+            public void preHandle(HttpServletRequest request, HttpServletResponse response, LoginRequest loginRequest) throws Exception {
 
             }
 
             @Override
-            public void postHandle(HttpServletRequest request, HttpServletResponse response, LoginRequest handler, Token token) {
-
-        }
-    };
+            public LoginResponse postHandle(HttpServletRequest request, HttpServletResponse response,
+                                            LoginRequest loginRequest, UserDetails user, Token token) {
+                LoginResponse loginResponse = new LoginResponse();
+                loginResponse.setToken(token.getToken());
+                loginResponse.setUsername(token.getUsername());
+                loginResponse.setAuthorities(token.getAuthorities());
+                return loginResponse;
+            }
+        };
+    }
 }
 ```
 
+以上 `postHandle` 即框架默认实现（见 `AutoConfiguration.securityLoginHandler()`），自定义时可在此基础上补充业务数据（通过 `loginResponse.setData(...)` 返回）。
+
 ## 获取当前用户
 
 通过TokenContext获取当前用户信息
@@ -89,10 +130,21 @@ security默认的账户密码为admin/admin，可以通过重写UserDetailsServi
     }
 ```
 
-可以通过Token的extra字段来存储用户的更多信息，然后通过TokenContext获取
+可以通过Token的extra字段来存储用户的更多信息（extra 存储的是 JSON 字符串），然后通过TokenContext获取：
+
+- `TokenContext.current().getExtra()` 获取原始的 extra JSON 字符串
+- `TokenContext.current().parseExtra(UserInfo.class)` 将 extra JSON 字符串反序列化为指定类型的对象
+
 ```java
     @GetMapping("/user")
     public String user(){
-        return TokenContext.current().getExtra("user");
+        // 获取原始的 extra JSON 字符串
+        return TokenContext.current().getExtra();
+    }
+
+    @GetMapping("/user/info")
+    public UserInfo userInfo(){
+        // 将 extra JSON 字符串反序列化为 UserInfo 对象
+        return TokenContext.current().parseExtra(UserInfo.class);
     }
 ```
diff --git a/docs/wiki/springboot-starter.md b/docs/wiki/springboot-starter.md
index 1cd9fd047..7bed37594 100644
--- a/docs/wiki/springboot-starter.md
+++ b/docs/wiki/springboot-starter.md
@@ -177,11 +177,11 @@ class DomainProxyFactoryTest {
     void createEntity() {
         // 在domain对象创建的时候会触发DomainCreateEvent事件
         Demo demo = DomainProxyFactory.create(Demo.class, "test");
-        //这里将会抛出FieldChangeEvent事件
+        //这里将会抛出DomainChangeEvent事件
         demo.changeAnimalName("123");
         //这里将不会触发事件，因为name值还是test
         demo.changeName("test");
-        //这里将会抛出FieldChangeEvent事件
+        //这里将会抛出DomainChangeEvent事件
         demo.changeName("test123");
         //这里将会抛出DomainPersistEvent事件
         demo.persist();
@@ -195,12 +195,13 @@ class DomainProxyFactoryTest {
 执行的打印如下：
 ```
 2023-05-28T08:57:00.505+08:00  INFO 13748 --- [           main] c.c.s.f.handler.DemoCreateHandler        : create domain -> com.codingapi.springboot.framework.domain.Demo@4cc12db2
-2023-05-28T08:57:00.507+08:00  INFO 13748 --- [           main] c.c.s.f.h.EntityFiledChangeHandler       : field change event -> FieldChangeEvent(simpleName=Demo, timestamp=1685235420507, fieldName=animal.name, oldValue=cat, newValue=123)
-2023-05-28T08:57:00.512+08:00  INFO 13748 --- [           main] c.c.s.f.h.EntityFiledChangeHandler       : field change event -> FieldChangeEvent(simpleName=Demo, timestamp=1685235420512, fieldName=name, oldValue=test, newValue=test123)
-2023-05-28T08:57:00.513+08:00  INFO 13748 --- [           main] c.c.s.f.handler.DemoPersistEventHandler  : DomainPersistEvent handler DomainPersistEvent(entity=com.codingapi.springboot.framework.domain.Demo@4cc12db2, simpleName=Demo, timestamp=1685235420513)
+2023-05-28T08:57:00.507+08:00  INFO 13748 --- [           main] c.c.s.f.h.EntityFiledChangeHandler       : field change event -> DomainChangeEvent(super=DomainEvent(entityClass=class com.codingapi.springboot.framework.domain.Demo, timestamp=1685235420507), fieldName=animal.name, oldValue=cat, newValue=123)
+2023-05-28T08:57:00.512+08:00  INFO 13748 --- [           main] c.c.s.f.h.EntityFiledChangeHandler       : field change event -> DomainChangeEvent(super=DomainEvent(entityClass=class com.codingapi.springboot.framework.domain.Demo, timestamp=1685235420512), fieldName=name, oldValue=test, newValue=test123)
+2023-05-28T08:57:00.513+08:00  INFO 13748 --- [           main] c.c.s.f.handler.DemoPersistEventHandler  : DomainPersistEvent handler DomainEvent(entityClass=class com.codingapi.springboot.framework.domain.Demo, timestamp=1685235420513)
 2023-05-28T08:57:00.516+08:00  INFO 13748 --- [           main] c.c.s.f.handler.DemoDeleteHandler        : delete domain -> com.codingapi.springboot.framework.domain.Demo@4cc12db2
 
 ```
+以上输出与事件的`toString()`行为一致：`DomainEvent`基类包含`entityClass`、`timestamp`、`entity`三个字段，且通过`@ToString(exclude = "entity")`排除了`entity`；`DomainChangeEvent`在此基础上通过`@ToString(callSuper = true)`追加了`fieldName`、`oldValue`、`newValue`字段，因此输出形如`DomainChangeEvent(super=DomainEvent(entityClass=class ...Demo, timestamp=...), fieldName=..., oldValue=..., newValue=...)`。`DomainCreateEvent`、`DomainPersistEvent`、`DomainDeleteEvent`未重写`toString()`，输出继承自`DomainEvent`。
 
 ## 转换工具
 该框架提供了一系列的转换工具，将BeanA转换为BeanB，转换工具的使用方式如下：
@@ -210,12 +211,24 @@ class DomainProxyFactoryTest {
 ```
 
 ## 序列化能力
-该框架提供了一系列的序列化工具，将对象转换为JSON对象，序列化工具的使用方式如下：
+该框架提供了一系列的序列化工具，将对象转换为JSON对象。`toJson()`是`com.codingapi.springboot.framework.serializable.JsonSerializable`接口提供的默认方法（基于Fastjson实现），`Demo`类需要实现该接口后才可调用，如下：
+```java
+public class Demo implements JsonSerializable {
+    // ...
+}
+```
+使用方式如下：
 ```java
   Demo demo = new Demo("xiaoming");
   JSONObject json = JSONObject.parseObject(demo.toJson());
 ```
-将对象转换为Map对象，序列化工具的使用方式如下：
+将对象转换为Map对象。`toMap()`是`com.codingapi.springboot.framework.serializable.MapSerializable`接口提供的默认方法，`Demo`类需要实现该接口后才可调用，如下：
+```java
+public class Demo implements MapSerializable {
+    // ...
+}
+```
+使用方式如下：
 ```java
   Demo demo = new Demo("xiaoming");
   Map<String, Object> map = demo.toMap();
@@ -432,7 +445,7 @@ class ArithmeticTest {
 
     @Test
     void test() {
-        // 1 + 1 x 3 / 4 = 1.25
+        // ((1 + 1) x 3) / 4 = 1.5
         assertEquals(Arithmetic.one().add(1).mul(3).div(4).getDoubleValue(),1.5);
 
         // 0.1+0.2=0.3
@@ -516,3 +529,12 @@ public class FrameWorkApplication {
 ```
 
 只要当前运行环境的./jars路径下存在第三方的jar，可以通过执行`DynamicApplication.restart()`方法，动态的加载第三方的jar包，实现动态的服务能力。
+
+## 框架配置项
+
+在`application.properties`中可用的配置项如下：
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `codingapi.framework.handler-thread-pool-size` | 事件异步线程池大小，对应`FrameworkProperties.handlerThreadPoolSize`（绑定前缀`codingapi.framework`） | 20 |
+| `codingapi.framework.event.transaction.enable` | 开启事务事件处理器。配置为`true`时，`SpringHandlerConfiguration`通过`@ConditionalOnProperty`注册`SpringTransactionEventHandler`，否则使用默认的`SpringDefaultEventHandler` | 不开启 |
diff --git a/frontend/README.md b/frontend/README.md
index e2dbab93c..96522bc87 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -22,7 +22,7 @@ frontend/
 
 ## 环境要求 | Prerequisites
 
-- Node.js >= 20
+- Node.js >= 18.12（pnpm 10 要求），推荐 Node.js 20+
 - pnpm >= 10（仓库已通过 `packageManager` 字段锁定 pnpm@10.32.1）
 
 ## 快速开始 | Getting Started
diff --git a/pom.xml b/pom.xml
index b2b49d39f..2bfdf3be0 100644
--- a/pom.xml
+++ b/pom.xml
@@ -354,8 +354,8 @@
         </profile>
 
         <profile>
-            <!-- mvn clean deploy -P ossrh  -->
-            <!-- mvn clean deploy -P ossrh -Dgpg.passphrase="你的GPG密码" -->
+            <!-- mvn clean deploy -P ossrh  -Drevision=0.1.0 -Dgpg.passphrase="你的GPG密码" -->
+            <!-- mvn clean deploy -P ossrh  -Drevision=version -Dgpg.passphrase="你的GPG密码" -->
             <!-- gpg: signing failed: Inappropriate ioctl for device -->
             <!-- fix command : export GPG_TTY=$(tty)  -->
             <!-- https://github.com/keybase/keybase-issues/issues/2798 -->
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/exception/NotAuthorizationExceptionTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/exception/NotAuthorizationExceptionTest.java
new file mode 100644
index 000000000..7ab129c9d
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/exception/NotAuthorizationExceptionTest.java
@@ -0,0 +1,29 @@
+package com.codingapi.springboot.authorization.exception;
+
+import org.junit.jupiter.api.Test;
+
+import java.sql.SQLException;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * NotAuthorizationException 单元测试
+ */
+class NotAuthorizationExceptionTest {
+
+    @Test
+    void testDefaultConstructor() {
+        NotAuthorizationException exception = new NotAuthorizationException();
+        assertTrue(exception instanceof SQLException);
+        assertNull(exception.getMessage());
+    }
+
+    @Test
+    void testConstructorWithReason() {
+        NotAuthorizationException exception = new NotAuthorizationException("no permission");
+        assertTrue(exception instanceof SQLException);
+        assertEquals("no permission", exception.getMessage());
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ColumnHandlerContextTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ColumnHandlerContextTest.java
new file mode 100644
index 000000000..7413c1024
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ColumnHandlerContextTest.java
@@ -0,0 +1,153 @@
+package com.codingapi.springboot.authorization.handler;
+
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.io.Reader;
+import java.math.BigDecimal;
+import java.net.URL;
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.Clob;
+import java.sql.Date;
+import java.sql.NClob;
+import java.sql.Ref;
+import java.sql.RowId;
+import java.sql.SQLXML;
+import java.sql.Time;
+import java.sql.Timestamp;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyBoolean;
+import static org.mockito.ArgumentMatchers.anyByte;
+import static org.mockito.ArgumentMatchers.anyDouble;
+import static org.mockito.ArgumentMatchers.anyFloat;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyShort;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * ColumnHandlerContext 单元测试
+ * 验证上下文将各类 get 请求委托给注册的 ColumnHandler
+ */
+class ColumnHandlerContextTest {
+
+    private ColumnHandler columnHandler;
+    private SQLExecuteState state;
+
+    @BeforeEach
+    void setUp() {
+        columnHandler = mock(ColumnHandler.class);
+        ColumnHandlerContext.getInstance().setColumnHandler(columnHandler);
+        state = SQLExecuteState.unIntercept("select 1");
+    }
+
+    @AfterEach
+    void tearDown() {
+        // 恢复默认处理器，避免影响其他测试
+        ColumnHandlerContext.getInstance().setColumnHandler(new DefaultColumnHandler());
+    }
+
+    @Test
+    void testDelegatesToColumnHandler() throws Exception {
+        when(columnHandler.getString(any(), anyInt(), anyString(), anyString(), anyString())).thenReturn("s");
+        when(columnHandler.getShort(any(), anyInt(), anyString(), anyString(), anyShort())).thenReturn((short) 1);
+        when(columnHandler.getBoolean(any(), anyInt(), anyString(), anyString(), anyBoolean())).thenReturn(true);
+        when(columnHandler.getByte(any(), anyInt(), anyString(), anyString(), anyByte())).thenReturn((byte) 2);
+        when(columnHandler.getInt(any(), anyInt(), anyString(), anyString(), anyInt())).thenReturn(3);
+        when(columnHandler.getLong(any(), anyInt(), anyString(), anyString(), anyLong())).thenReturn(4L);
+        when(columnHandler.getFloat(any(), anyInt(), anyString(), anyString(), anyFloat())).thenReturn(5.0f);
+        when(columnHandler.getDouble(any(), anyInt(), anyString(), anyString(), anyDouble())).thenReturn(6.0d);
+        when(columnHandler.getBigDecimal(any(), anyInt(), anyString(), anyString(), any(BigDecimal.class)))
+                .thenReturn(BigDecimal.ONE);
+        when(columnHandler.getBytes(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(new byte[]{1});
+        Timestamp timestamp = new Timestamp(1000L);
+        when(columnHandler.getTimestamp(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(timestamp);
+        Time time = new Time(1000L);
+        when(columnHandler.getTime(any(), anyInt(), anyString(), anyString(), any())).thenReturn(time);
+        Date date = new Date(1000L);
+        when(columnHandler.getDate(any(), anyInt(), anyString(), anyString(), any())).thenReturn(date);
+        InputStream inputStream = mock(InputStream.class);
+        when(columnHandler.getAsciiStream(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(inputStream);
+        when(columnHandler.getUnicodeStream(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(inputStream);
+        when(columnHandler.getBinaryStream(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(inputStream);
+        when(columnHandler.getObject(any(), anyInt(), anyString(), anyString(), any())).thenReturn("obj");
+        Reader reader = mock(Reader.class);
+        when(columnHandler.getCharacterStream(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(reader);
+        when(columnHandler.getNCharacterStream(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(reader);
+        Ref ref = mock(Ref.class);
+        when(columnHandler.getRef(any(), anyInt(), anyString(), anyString(), any())).thenReturn(ref);
+        Blob blob = mock(Blob.class);
+        when(columnHandler.getBlob(any(), anyInt(), anyString(), anyString(), any())).thenReturn(blob);
+        Clob clob = mock(Clob.class);
+        when(columnHandler.getClob(any(), anyInt(), anyString(), anyString(), any())).thenReturn(clob);
+        Array array = mock(Array.class);
+        when(columnHandler.getArray(any(), anyInt(), anyString(), anyString(), any())).thenReturn(array);
+        URL url = mock(URL.class);
+        when(columnHandler.getURL(any(), anyInt(), anyString(), anyString(), any())).thenReturn(url);
+        NClob nClob = mock(NClob.class);
+        when(columnHandler.getNClob(any(), anyInt(), anyString(), anyString(), any())).thenReturn(nClob);
+        SQLXML sqlxml = mock(SQLXML.class);
+        when(columnHandler.getSQLXML(any(), anyInt(), anyString(), anyString(), any()))
+                .thenReturn(sqlxml);
+        when(columnHandler.getNString(any(), anyInt(), anyString(), anyString(), anyString())).thenReturn("ns");
+        RowId rowId = mock(RowId.class);
+        when(columnHandler.getRowId(any(), anyInt(), anyString(), anyString(), any())).thenReturn(rowId);
+        when(columnHandler.getObject(any(), anyInt(), anyString(), anyString(), any(), eq(String.class)))
+                .thenReturn("typed");
+
+        ColumnHandlerContext context = ColumnHandlerContext.getInstance();
+
+        assertEquals("s", context.getString(state, 1, "t", "c", "v"));
+        assertEquals((short) 1, context.getShort(state, 1, "t", "c", (short) 0));
+        assertEquals(true, context.getBoolean(state, 1, "t", "c", false));
+        assertEquals((byte) 2, context.getByte(state, 1, "t", "c", (byte) 0));
+        assertEquals(3, context.getInt(state, 1, "t", "c", 0));
+        assertEquals(4L, context.getLong(state, 1, "t", "c", 0L));
+        assertEquals(5.0f, context.getFloat(state, 1, "t", "c", 0f));
+        assertEquals(6.0d, context.getDouble(state, 1, "t", "c", 0d));
+        assertEquals(BigDecimal.ONE, context.getBigDecimal(state, 1, "t", "c", BigDecimal.ZERO));
+        assertSame(timestamp, context.getTimestamp(state, 1, "t", "c", null));
+        assertSame(time, context.getTime(state, 1, "t", "c", null));
+        assertSame(date, context.getDate(state, 1, "t", "c", null));
+        assertSame(inputStream, context.getAsciiStream(state, 1, "t", "c", null));
+        assertSame(inputStream, context.getUnicodeStream(state, 1, "t", "c", null));
+        assertSame(inputStream, context.getBinaryStream(state, 1, "t", "c", null));
+        assertEquals("obj", context.getObject(state, 1, "t", "c", null));
+        assertSame(reader, context.getCharacterStream(state, 1, "t", "c", null));
+        assertSame(reader, context.getNCharacterStream(state, 1, "t", "c", null));
+        assertSame(ref, context.getRef(state, 1, "t", "c", null));
+        assertSame(blob, context.getBlob(state, 1, "t", "c", null));
+        assertSame(clob, context.getClob(state, 1, "t", "c", null));
+        assertSame(array, context.getArray(state, 1, "t", "c", null));
+        assertSame(url, context.getURL(state, 1, "t", "c", null));
+        assertSame(nClob, context.getNClob(state, 1, "t", "c", null));
+        assertSame(sqlxml, context.getSQLXML(state, 1, "t", "c", null));
+        assertEquals("ns", context.getNString(state, 1, "t", "c", "v"));
+        assertSame(rowId, context.getRowId(state, 1, "t", "c", null));
+        assertEquals("typed", context.getObject(state, 1, "t", "c", "v", String.class));
+        assertEquals(1, context.getBytes(state, 1, "t", "c", null).length);
+
+        // 验证委托时参数透传
+        verify(columnHandler).getString(state, 1, "t", "c", "v");
+        verify(columnHandler).getInt(state, 1, "t", "c", 0);
+        verify(columnHandler).getObject(state, 1, "t", "c", "v", String.class);
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ConditionTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ConditionTest.java
new file mode 100644
index 000000000..a896f37c9
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/ConditionTest.java
@@ -0,0 +1,68 @@
+package com.codingapi.springboot.authorization.handler;
+
+import com.codingapi.springboot.authorization.condition.IConditionSQL;
+import com.codingapi.springboot.authorization.condition.JoinConditionSQL;
+import com.codingapi.springboot.authorization.condition.WhereConditionSQL;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Condition 单元测试
+ */
+class ConditionTest {
+
+    @Test
+    void testEmptyConstructor() {
+        Condition condition = new Condition();
+        assertNotNull(condition.getConditionList());
+        assertEquals(0, condition.getConditionList().size());
+    }
+
+    @Test
+    void testConditionWithWhereSql() {
+        Condition condition = new Condition("t.id = 1");
+        assertEquals(1, condition.getConditionList().size());
+        IConditionSQL conditionSQL = condition.getConditionList().get(0);
+        assertTrue(conditionSQL instanceof WhereConditionSQL);
+        assertEquals("t.id = 1", ((WhereConditionSQL) conditionSQL).getCondition());
+    }
+
+    @Test
+    void testAddConditionSql() {
+        Condition condition = new Condition();
+        condition.addConditionSQL(new WhereConditionSQL("t.id = 1"));
+        condition.addConditionSQL(new JoinConditionSQL(JoinConditionSQL.Type.INNER, "t_unit", "u", "u.id = t.id"));
+        assertEquals(2, condition.getConditionList().size());
+    }
+
+    @Test
+    void testCustomCondition() {
+        Condition condition = Condition.customCondition("t.id = 1");
+        assertEquals(1, condition.getConditionList().size());
+        WhereConditionSQL whereConditionSQL = (WhereConditionSQL) condition.getConditionList().get(0);
+        assertEquals("t.id = 1", whereConditionSQL.getCondition());
+    }
+
+    @Test
+    void testFormatCondition() {
+        Condition condition = Condition.formatCondition("%s.id = %d", "u", 10);
+        WhereConditionSQL whereConditionSQL = (WhereConditionSQL) condition.getConditionList().get(0);
+        assertEquals("u.id = 10", whereConditionSQL.getCondition());
+    }
+
+    @Test
+    void testEmptyConditionReturnsNull() {
+        assertNull(Condition.emptyCondition());
+    }
+
+    @Test
+    void testDefaultCondition() {
+        Condition condition = Condition.defaultCondition();
+        WhereConditionSQL whereConditionSQL = (WhereConditionSQL) condition.getConditionList().get(0);
+        assertEquals("1=1", whereConditionSQL.getCondition());
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/DefaultColumnHandlerTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/DefaultColumnHandlerTest.java
new file mode 100644
index 000000000..3a2077633
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/handler/DefaultColumnHandlerTest.java
@@ -0,0 +1,140 @@
+package com.codingapi.springboot.authorization.handler;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.filter.DefaultDataAuthorizationFilter;
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import com.codingapi.springboot.authorization.interceptor.SQLRunningContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.io.Reader;
+import java.math.BigDecimal;
+import java.net.URL;
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.Clob;
+import java.sql.Date;
+import java.sql.NClob;
+import java.sql.Ref;
+import java.sql.RowId;
+import java.sql.SQLXML;
+import java.sql.Time;
+import java.sql.Timestamp;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+
+/**
+ * DefaultColumnHandler 单元测试
+ * 验证默认列处理器将请求委托给 DataAuthorizationContext.columnAuthorization：
+ * 未拦截时原值返回；拦截且过滤器支持时返回加工后的值
+ */
+class DefaultColumnHandlerTest {
+
+    private DefaultColumnHandler handler;
+
+    @BeforeEach
+    void setUp() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        handler = new DefaultColumnHandler();
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    @Test
+    void testUnInterceptStateReturnsOriginalValues() throws Exception {
+        SQLExecuteState state = SQLExecuteState.unIntercept("select 1");
+        InputStream inputStream = mock(InputStream.class);
+        Reader reader = mock(Reader.class);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        URL url = mock(URL.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        Date date = new Date(1000L);
+        Time time = new Time(1000L);
+        Timestamp timestamp = new Timestamp(1000L);
+        byte[] bytes = new byte[]{1};
+
+        assertEquals("v", handler.getString(state, 1, "t", "c", "v"));
+        assertEquals(true, handler.getBoolean(state, 1, "t", "c", true));
+        assertEquals((byte) 1, handler.getByte(state, 1, "t", "c", (byte) 1));
+        assertEquals((short) 1, handler.getShort(state, 1, "t", "c", (short) 1));
+        assertEquals(1, handler.getInt(state, 1, "t", "c", 1));
+        assertEquals(1L, handler.getLong(state, 1, "t", "c", 1L));
+        assertEquals(1.0f, handler.getFloat(state, 1, "t", "c", 1.0f));
+        assertEquals(1.0d, handler.getDouble(state, 1, "t", "c", 1.0d));
+        assertEquals(BigDecimal.ONE, handler.getBigDecimal(state, 1, "t", "c", BigDecimal.ONE));
+        assertSame(bytes, handler.getBytes(state, 1, "t", "c", bytes));
+        assertSame(date, handler.getDate(state, 1, "t", "c", date));
+        assertSame(time, handler.getTime(state, 1, "t", "c", time));
+        assertSame(timestamp, handler.getTimestamp(state, 1, "t", "c", timestamp));
+        assertSame(inputStream, handler.getAsciiStream(state, 1, "t", "c", inputStream));
+        assertSame(inputStream, handler.getUnicodeStream(state, 1, "t", "c", inputStream));
+        assertSame(inputStream, handler.getBinaryStream(state, 1, "t", "c", inputStream));
+        assertEquals("obj", handler.getObject(state, 1, "t", "c", "obj"));
+        assertSame(reader, handler.getCharacterStream(state, 1, "t", "c", reader));
+        assertSame(ref, handler.getRef(state, 1, "t", "c", ref));
+        assertSame(blob, handler.getBlob(state, 1, "t", "c", blob));
+        assertSame(clob, handler.getClob(state, 1, "t", "c", clob));
+        assertSame(array, handler.getArray(state, 1, "t", "c", array));
+        assertSame(url, handler.getURL(state, 1, "t", "c", url));
+        assertSame(nClob, handler.getNClob(state, 1, "t", "c", nClob));
+        assertSame(sqlxml, handler.getSQLXML(state, 1, "t", "c", sqlxml));
+        assertEquals("nv", handler.getNString(state, 1, "t", "c", "nv"));
+        assertSame(reader, handler.getNCharacterStream(state, 1, "t", "c", reader));
+        assertSame(rowId, handler.getRowId(state, 1, "t", "c", rowId));
+        assertEquals("typed", handler.getObject(state, 1, "t", "c", "typed", String.class));
+    }
+
+    @Test
+    void testInterceptStateAppliesColumnAuthorization() throws Exception {
+        DataAuthorizationContext.getInstance().addDataAuthorizationFilter(new DefaultDataAuthorizationFilter() {
+            @Override
+            public boolean supportRowAuthorization(String tableName, String tableAlias) {
+                return "t_user".equalsIgnoreCase(tableName);
+            }
+
+            @Override
+            public Condition rowAuthorization(String tableName, String tableAlias) {
+                return Condition.formatCondition("%s.id > 100", tableAlias);
+            }
+
+            @Override
+            public boolean supportColumnAuthorization(String tableName, String columnName, Object value) {
+                return "t_user".equalsIgnoreCase(tableName);
+            }
+
+            @SuppressWarnings("unchecked")
+            @Override
+            public <T> T columnAuthorization(String tableName, String columnName, T value) {
+                if (value instanceof String) {
+                    return (T) ("MASKED-" + value);
+                }
+                if (value instanceof Integer) {
+                    return (T) Integer.valueOf(-1);
+                }
+                return value;
+            }
+        });
+
+        SQLExecuteState state = SQLRunningContext.getInstance().intercept("select name from t_user");
+        assertTrue(state.hasIntercept());
+
+        assertEquals("MASKED-raw", handler.getString(state, 1, "t_user", "name", "raw"));
+        assertEquals(Integer.valueOf(-1), Integer.valueOf(handler.getInt(state, 1, "t_user", "id", 1)));
+        assertEquals("MASKED-nv", handler.getNString(state, 1, "t_user", "name", "nv"));
+        assertEquals("MASKED-obj", handler.getObject(state, 1, "t_user", "name", "obj"));
+        assertEquals("MASKED-typed", handler.getObject(state, 1, "t_user", "name", "typed", String.class));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/AuthorizationJdbcDriverTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/AuthorizationJdbcDriverTest.java
new file mode 100644
index 000000000..63d581d0a
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/AuthorizationJdbcDriverTest.java
@@ -0,0 +1,121 @@
+package com.codingapi.springboot.authorization.jdbc;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.jdbc.proxy.ConnectionProxy;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.sql.Connection;
+import java.sql.Driver;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.Properties;
+import java.util.logging.Logger;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * AuthorizationJdbcDriver 单元测试
+ * 验证代理驱动的查找、包装与元信息行为（使用 H2 内存库，无外网依赖）
+ */
+class AuthorizationJdbcDriverTest {
+
+    private AuthorizationJdbcDriver driver;
+
+    @BeforeAll
+    static void loadH2Driver() throws ClassNotFoundException {
+        // 确保 H2 驱动已注册到 DriverManager
+        Class.forName("org.h2.Driver");
+    }
+
+    @BeforeEach
+    void setUp() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        driver = new AuthorizationJdbcDriver();
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    @Test
+    void testAcceptsUrl() throws SQLException {
+        assertEquals(false, driver.acceptsURL(null));
+        assertTrue(driver.acceptsURL("jdbc:h2:mem:acceptsUrlTest"));
+        assertEquals(false, driver.acceptsURL("jdbc:not-exists:xyz"));
+    }
+
+    @Test
+    void testConnectWithNullUrl() {
+        SQLException exception = assertThrows(SQLException.class, () -> driver.connect(null, new Properties()));
+        assertTrue(exception.getMessage().contains("URL cannot be null"));
+    }
+
+    @Test
+    void testConnectWithNoSuitableDriver() {
+        SQLException exception = assertThrows(SQLException.class,
+                () -> driver.connect("jdbc:not-exists:xyz", new Properties()));
+        assertTrue(exception.getMessage().contains("No suitable driver"));
+    }
+
+    @Test
+    void testConnectReturnsConnectionProxyAndWorks() throws SQLException {
+        String url = "jdbc:h2:mem:authorizationDriverTest";
+        Connection connection = driver.connect(url, new Properties());
+        try {
+            assertNotNull(connection);
+            assertTrue(connection instanceof ConnectionProxy);
+
+            // 第二次使用相同 URL，命中驱动缓存分支
+            Connection cachedConnection = driver.connect(url, new Properties());
+            assertTrue(cachedConnection instanceof ConnectionProxy);
+            cachedConnection.close();
+
+            // 通过代理连接执行真实查询
+            Statement statement = connection.createStatement();
+            ResultSet resultSet = statement.executeQuery("SELECT 1");
+            assertTrue(resultSet.next());
+            assertEquals(1, resultSet.getInt(1));
+            resultSet.close();
+            statement.close();
+        } finally {
+            connection.close();
+        }
+    }
+
+    @Test
+    void testGetPropertyInfo() throws SQLException {
+        assertNotNull(driver.getPropertyInfo("jdbc:h2:mem:propertyInfoTest", new Properties()));
+        assertThrows(SQLException.class, () -> driver.getPropertyInfo("jdbc:not-exists:xyz", new Properties()));
+    }
+
+    @Test
+    void testDriverMetaInfo() throws SQLException {
+        assertEquals(1, driver.getMajorVersion());
+        assertEquals(0, driver.getMinorVersion());
+        assertEquals(false, driver.jdbcCompliant());
+        Logger parentLogger = driver.getParentLogger();
+        assertNotNull(parentLogger);
+    }
+
+    @Test
+    void testDriverRegisteredInDriverManager() {
+        boolean found = false;
+        java.util.Enumeration<Driver> drivers = java.sql.DriverManager.getDrivers();
+        while (drivers.hasMoreElements()) {
+            Driver candidate = drivers.nextElement();
+            if (candidate instanceof AuthorizationJdbcDriver) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found);
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/CallableStatementProxyTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/CallableStatementProxyTest.java
new file mode 100644
index 000000000..4842593ae
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/CallableStatementProxyTest.java
@@ -0,0 +1,633 @@
+package com.codingapi.springboot.authorization.jdbc.proxy;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.io.Reader;
+import java.io.StringReader;
+import java.math.BigDecimal;
+import java.net.URL;
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.CallableStatement;
+import java.sql.Clob;
+import java.sql.Connection;
+import java.sql.Date;
+import java.sql.JDBCType;
+import java.sql.NClob;
+import java.sql.ParameterMetaData;
+import java.sql.Ref;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.RowId;
+import java.sql.SQLException;
+import java.sql.SQLType;
+import java.sql.SQLWarning;
+import java.sql.SQLXML;
+import java.sql.Time;
+import java.sql.Timestamp;
+import java.sql.Types;
+import java.util.Calendar;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * CallableStatementProxy 单元测试
+ * 验证方法委托以及 SQL 拦截行为
+ */
+class CallableStatementProxyTest {
+
+    private CallableStatement callableStatement;
+    private CallableStatementProxy proxy;
+
+    @BeforeEach
+    void setUp() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        ResultSetProxyTest.registerTestFilter();
+
+        callableStatement = mock(CallableStatement.class);
+        proxy = new CallableStatementProxy(callableStatement, SQLExecuteState.unIntercept("select 1"));
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    private ResultSet mockEmptyResultSet() throws SQLException {
+        ResultSet resultSet = mock(ResultSet.class);
+        ResultSetMetaData metaData = mock(ResultSetMetaData.class);
+        when(resultSet.getMetaData()).thenReturn(metaData);
+        when(metaData.getColumnCount()).thenReturn(0);
+        return resultSet;
+    }
+
+    @Test
+    void testRegisterOutParameterDelegates() throws SQLException {
+        SQLType sqlType = JDBCType.VARCHAR;
+
+        proxy.registerOutParameter(1, Types.VARCHAR);
+        proxy.registerOutParameter(1, Types.VARCHAR, 2);
+        proxy.registerOutParameter(1, Types.VARCHAR, "VARCHAR");
+        proxy.registerOutParameter("p", Types.VARCHAR);
+        proxy.registerOutParameter("p", Types.VARCHAR, 2);
+        proxy.registerOutParameter("p", Types.VARCHAR, "VARCHAR");
+        proxy.registerOutParameter(1, sqlType);
+        proxy.registerOutParameter(1, sqlType, 2);
+        proxy.registerOutParameter(1, sqlType, "VARCHAR");
+        proxy.registerOutParameter("p", sqlType);
+        proxy.registerOutParameter("p", sqlType, 2);
+        proxy.registerOutParameter("p", sqlType, "VARCHAR");
+
+        verify(callableStatement).registerOutParameter(1, Types.VARCHAR);
+        verify(callableStatement).registerOutParameter(1, Types.VARCHAR, 2);
+        verify(callableStatement).registerOutParameter(1, Types.VARCHAR, "VARCHAR");
+        verify(callableStatement).registerOutParameter("p", Types.VARCHAR);
+        verify(callableStatement).registerOutParameter("p", Types.VARCHAR, 2);
+        verify(callableStatement).registerOutParameter("p", Types.VARCHAR, "VARCHAR");
+        verify(callableStatement).registerOutParameter(1, sqlType);
+        verify(callableStatement).registerOutParameter(1, sqlType, 2);
+        verify(callableStatement).registerOutParameter(1, sqlType, "VARCHAR");
+        verify(callableStatement).registerOutParameter("p", sqlType);
+        verify(callableStatement).registerOutParameter("p", sqlType, 2);
+        verify(callableStatement).registerOutParameter("p", sqlType, "VARCHAR");
+    }
+
+    @Test
+    void testGettersByIndexDelegate() throws SQLException {
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        Reader reader = new StringReader("x");
+        Map<String, Class<?>> map = new HashMap<>();
+
+        when(callableStatement.wasNull()).thenReturn(true);
+        when(callableStatement.getString(1)).thenReturn("v");
+        when(callableStatement.getBoolean(1)).thenReturn(true);
+        when(callableStatement.getByte(1)).thenReturn((byte) 1);
+        when(callableStatement.getShort(1)).thenReturn((short) 2);
+        when(callableStatement.getInt(1)).thenReturn(3);
+        when(callableStatement.getLong(1)).thenReturn(4L);
+        when(callableStatement.getFloat(1)).thenReturn(5.0f);
+        when(callableStatement.getDouble(1)).thenReturn(6.0d);
+        when(callableStatement.getBigDecimal(1, 2)).thenReturn(BigDecimal.ONE);
+        when(callableStatement.getBigDecimal(1)).thenReturn(BigDecimal.TEN);
+        when(callableStatement.getBytes(1)).thenReturn(new byte[]{1});
+        when(callableStatement.getDate(1)).thenReturn(date);
+        when(callableStatement.getTime(1)).thenReturn(time);
+        when(callableStatement.getTimestamp(1)).thenReturn(timestamp);
+        when(callableStatement.getObject(1)).thenReturn("obj");
+        when(callableStatement.getObject(1, map)).thenReturn("mapObj");
+        when(callableStatement.getRef(1)).thenReturn(ref);
+        when(callableStatement.getBlob(1)).thenReturn(blob);
+        when(callableStatement.getClob(1)).thenReturn(clob);
+        when(callableStatement.getArray(1)).thenReturn(array);
+        when(callableStatement.getDate(1, calendar)).thenReturn(date);
+        when(callableStatement.getTime(1, calendar)).thenReturn(time);
+        when(callableStatement.getTimestamp(1, calendar)).thenReturn(timestamp);
+        when(callableStatement.getURL(1)).thenReturn(url);
+        when(callableStatement.getRowId(1)).thenReturn(rowId);
+        when(callableStatement.getNClob(1)).thenReturn(nClob);
+        when(callableStatement.getSQLXML(1)).thenReturn(sqlxml);
+        when(callableStatement.getNString(1)).thenReturn("ns");
+        when(callableStatement.getNCharacterStream(1)).thenReturn(reader);
+        when(callableStatement.getCharacterStream(1)).thenReturn(reader);
+        when(callableStatement.getObject(1, String.class)).thenReturn("typed");
+
+        assertTrue(proxy.wasNull());
+        assertEquals("v", proxy.getString(1));
+        assertTrue(proxy.getBoolean(1));
+        assertEquals((byte) 1, proxy.getByte(1));
+        assertEquals((short) 2, proxy.getShort(1));
+        assertEquals(3, proxy.getInt(1));
+        assertEquals(4L, proxy.getLong(1));
+        assertEquals(5.0f, proxy.getFloat(1));
+        assertEquals(6.0d, proxy.getDouble(1));
+        assertEquals(BigDecimal.ONE, proxy.getBigDecimal(1, 2));
+        assertEquals(BigDecimal.TEN, proxy.getBigDecimal(1));
+        assertEquals(1, proxy.getBytes(1).length);
+        assertSame(date, proxy.getDate(1));
+        assertSame(time, proxy.getTime(1));
+        assertSame(timestamp, proxy.getTimestamp(1));
+        assertEquals("obj", proxy.getObject(1));
+        assertEquals("mapObj", proxy.getObject(1, map));
+        assertSame(ref, proxy.getRef(1));
+        assertSame(blob, proxy.getBlob(1));
+        assertSame(clob, proxy.getClob(1));
+        assertSame(array, proxy.getArray(1));
+        assertSame(date, proxy.getDate(1, calendar));
+        assertSame(time, proxy.getTime(1, calendar));
+        assertSame(timestamp, proxy.getTimestamp(1, calendar));
+        assertSame(url, proxy.getURL(1));
+        assertSame(rowId, proxy.getRowId(1));
+        assertSame(nClob, proxy.getNClob(1));
+        assertSame(sqlxml, proxy.getSQLXML(1));
+        assertEquals("ns", proxy.getNString(1));
+        assertSame(reader, proxy.getNCharacterStream(1));
+        assertSame(reader, proxy.getCharacterStream(1));
+        assertEquals("typed", proxy.getObject(1, String.class));
+    }
+
+    @Test
+    void testGettersByNameDelegate() throws SQLException {
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        Reader reader = new StringReader("x");
+        Map<String, Class<?>> map = new HashMap<>();
+
+        when(callableStatement.getString("p")).thenReturn("v");
+        when(callableStatement.getBoolean("p")).thenReturn(true);
+        when(callableStatement.getByte("p")).thenReturn((byte) 1);
+        when(callableStatement.getShort("p")).thenReturn((short) 2);
+        when(callableStatement.getInt("p")).thenReturn(3);
+        when(callableStatement.getLong("p")).thenReturn(4L);
+        when(callableStatement.getFloat("p")).thenReturn(5.0f);
+        when(callableStatement.getDouble("p")).thenReturn(6.0d);
+        when(callableStatement.getBytes("p")).thenReturn(new byte[]{1});
+        when(callableStatement.getDate("p")).thenReturn(date);
+        when(callableStatement.getTime("p")).thenReturn(time);
+        when(callableStatement.getTimestamp("p")).thenReturn(timestamp);
+        when(callableStatement.getObject("p")).thenReturn("obj");
+        when(callableStatement.getBigDecimal("p")).thenReturn(BigDecimal.TEN);
+        when(callableStatement.getObject("p", map)).thenReturn("mapObj");
+        when(callableStatement.getRef("p")).thenReturn(ref);
+        when(callableStatement.getBlob("p")).thenReturn(blob);
+        when(callableStatement.getClob("p")).thenReturn(clob);
+        when(callableStatement.getArray("p")).thenReturn(array);
+        when(callableStatement.getDate("p", calendar)).thenReturn(date);
+        when(callableStatement.getTime("p", calendar)).thenReturn(time);
+        when(callableStatement.getTimestamp("p", calendar)).thenReturn(timestamp);
+        when(callableStatement.getURL("p")).thenReturn(url);
+        when(callableStatement.getRowId("p")).thenReturn(rowId);
+        when(callableStatement.getNClob("p")).thenReturn(nClob);
+        when(callableStatement.getSQLXML("p")).thenReturn(sqlxml);
+        when(callableStatement.getNString("p")).thenReturn("ns");
+        when(callableStatement.getNCharacterStream("p")).thenReturn(reader);
+        when(callableStatement.getCharacterStream("p")).thenReturn(reader);
+        when(callableStatement.getObject("p", String.class)).thenReturn("typed");
+
+        assertEquals("v", proxy.getString("p"));
+        assertTrue(proxy.getBoolean("p"));
+        assertEquals((byte) 1, proxy.getByte("p"));
+        assertEquals((short) 2, proxy.getShort("p"));
+        assertEquals(3, proxy.getInt("p"));
+        assertEquals(4L, proxy.getLong("p"));
+        assertEquals(5.0f, proxy.getFloat("p"));
+        assertEquals(6.0d, proxy.getDouble("p"));
+        assertEquals(1, proxy.getBytes("p").length);
+        assertSame(date, proxy.getDate("p"));
+        assertSame(time, proxy.getTime("p"));
+        assertSame(timestamp, proxy.getTimestamp("p"));
+        assertEquals("obj", proxy.getObject("p"));
+        assertEquals(BigDecimal.TEN, proxy.getBigDecimal("p"));
+        assertEquals("mapObj", proxy.getObject("p", map));
+        assertSame(ref, proxy.getRef("p"));
+        assertSame(blob, proxy.getBlob("p"));
+        assertSame(clob, proxy.getClob("p"));
+        assertSame(array, proxy.getArray("p"));
+        assertSame(date, proxy.getDate("p", calendar));
+        assertSame(time, proxy.getTime("p", calendar));
+        assertSame(timestamp, proxy.getTimestamp("p", calendar));
+        assertSame(url, proxy.getURL("p"));
+        assertSame(rowId, proxy.getRowId("p"));
+        assertSame(nClob, proxy.getNClob("p"));
+        assertSame(sqlxml, proxy.getSQLXML("p"));
+        assertEquals("ns", proxy.getNString("p"));
+        assertSame(reader, proxy.getNCharacterStream("p"));
+        assertSame(reader, proxy.getCharacterStream("p"));
+        assertEquals("typed", proxy.getObject("p", String.class));
+    }
+
+    @Test
+    void testSettersByNameDelegate() throws SQLException {
+        InputStream inputStream = new ByteArrayInputStream(new byte[]{1});
+        Reader reader = new StringReader("x");
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        SQLType sqlType = JDBCType.VARCHAR;
+
+        proxy.setURL("p", url);
+        proxy.setNull("p", Types.VARCHAR);
+        proxy.setBoolean("p", true);
+        proxy.setByte("p", (byte) 1);
+        proxy.setShort("p", (short) 1);
+        proxy.setInt("p", 1);
+        proxy.setLong("p", 1L);
+        proxy.setFloat("p", 1.0f);
+        proxy.setDouble("p", 1.0d);
+        proxy.setBigDecimal("p", BigDecimal.ONE);
+        proxy.setString("p", "x");
+        proxy.setBytes("p", new byte[]{1});
+        proxy.setDate("p", date);
+        proxy.setTime("p", time);
+        proxy.setTimestamp("p", timestamp);
+        proxy.setAsciiStream("p", inputStream, 1);
+        proxy.setBinaryStream("p", inputStream, 1);
+        proxy.setObject("p", "x", Types.VARCHAR, 1);
+        proxy.setObject("p", "x", Types.VARCHAR);
+        proxy.setObject("p", "x");
+        proxy.setCharacterStream("p", reader, 1);
+        proxy.setDate("p", date, calendar);
+        proxy.setTime("p", time, calendar);
+        proxy.setTimestamp("p", timestamp, calendar);
+        proxy.setNull("p", Types.VARCHAR, "VARCHAR");
+        proxy.setRowId("p", rowId);
+        proxy.setNString("p", "x");
+        proxy.setNCharacterStream("p", reader, 1L);
+        proxy.setNClob("p", nClob);
+        proxy.setClob("p", reader, 1L);
+        proxy.setBlob("p", inputStream, 1L);
+        proxy.setNClob("p", reader, 1L);
+        proxy.setSQLXML("p", sqlxml);
+        proxy.setBlob("p", blob);
+        proxy.setClob("p", clob);
+        proxy.setAsciiStream("p", inputStream, 1L);
+        proxy.setBinaryStream("p", inputStream, 1L);
+        proxy.setCharacterStream("p", reader, 1L);
+        proxy.setAsciiStream("p", inputStream);
+        proxy.setBinaryStream("p", inputStream);
+        proxy.setCharacterStream("p", reader);
+        proxy.setNCharacterStream("p", reader);
+        proxy.setClob("p", reader);
+        proxy.setBlob("p", inputStream);
+        proxy.setNClob("p", reader);
+        proxy.setObject("p", "x", sqlType, 1);
+        proxy.setObject("p", "x", sqlType);
+
+        verify(callableStatement).setURL("p", url);
+        verify(callableStatement).setNull("p", Types.VARCHAR);
+        verify(callableStatement).setBoolean("p", true);
+        verify(callableStatement).setByte("p", (byte) 1);
+        verify(callableStatement).setShort("p", (short) 1);
+        verify(callableStatement).setInt("p", 1);
+        verify(callableStatement).setLong("p", 1L);
+        verify(callableStatement).setFloat("p", 1.0f);
+        verify(callableStatement).setDouble("p", 1.0d);
+        verify(callableStatement).setBigDecimal("p", BigDecimal.ONE);
+        verify(callableStatement).setString("p", "x");
+        verify(callableStatement).setDate("p", date);
+        verify(callableStatement).setTime("p", time);
+        verify(callableStatement).setTimestamp("p", timestamp);
+        verify(callableStatement).setAsciiStream("p", inputStream, 1);
+        verify(callableStatement).setBinaryStream("p", inputStream, 1);
+        verify(callableStatement).setObject("p", "x", Types.VARCHAR, 1);
+        verify(callableStatement).setObject("p", "x", Types.VARCHAR);
+        verify(callableStatement).setObject("p", "x");
+        verify(callableStatement).setCharacterStream("p", reader, 1);
+        verify(callableStatement).setDate("p", date, calendar);
+        verify(callableStatement).setTime("p", time, calendar);
+        verify(callableStatement).setTimestamp("p", timestamp, calendar);
+        verify(callableStatement).setNull("p", Types.VARCHAR, "VARCHAR");
+        verify(callableStatement).setRowId("p", rowId);
+        verify(callableStatement).setNString("p", "x");
+        verify(callableStatement).setNCharacterStream("p", reader, 1L);
+        verify(callableStatement).setNClob("p", nClob);
+        verify(callableStatement).setClob("p", reader, 1L);
+        verify(callableStatement).setBlob("p", inputStream, 1L);
+        verify(callableStatement).setNClob("p", reader, 1L);
+        verify(callableStatement).setSQLXML("p", sqlxml);
+        verify(callableStatement).setBlob("p", blob);
+        verify(callableStatement).setClob("p", clob);
+        verify(callableStatement).setAsciiStream("p", inputStream, 1L);
+        verify(callableStatement).setBinaryStream("p", inputStream, 1L);
+        verify(callableStatement).setCharacterStream("p", reader, 1L);
+        verify(callableStatement).setAsciiStream("p", inputStream);
+        verify(callableStatement).setBinaryStream("p", inputStream);
+        verify(callableStatement).setCharacterStream("p", reader);
+        verify(callableStatement).setNCharacterStream("p", reader);
+        verify(callableStatement).setClob("p", reader);
+        verify(callableStatement).setBlob("p", inputStream);
+        verify(callableStatement).setNClob("p", reader);
+        verify(callableStatement).setObject("p", "x", sqlType, 1);
+        verify(callableStatement).setObject("p", "x", sqlType);
+    }
+
+    @Test
+    void testPreparedStatementLevelSettersDelegate() throws SQLException {
+        InputStream inputStream = new ByteArrayInputStream(new byte[]{1});
+        Reader reader = new StringReader("x");
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        SQLType sqlType = JDBCType.VARCHAR;
+
+        proxy.setNull(1, Types.VARCHAR);
+        proxy.setBoolean(1, true);
+        proxy.setByte(1, (byte) 1);
+        proxy.setShort(1, (short) 1);
+        proxy.setInt(1, 1);
+        proxy.setLong(1, 1L);
+        proxy.setFloat(1, 1.0f);
+        proxy.setDouble(1, 1.0d);
+        proxy.setBigDecimal(1, BigDecimal.ONE);
+        proxy.setString(1, "x");
+        proxy.setBytes(1, new byte[]{1});
+        proxy.setDate(1, date);
+        proxy.setTime(1, time);
+        proxy.setTimestamp(1, timestamp);
+        proxy.setAsciiStream(1, inputStream, 1);
+        proxy.setUnicodeStream(1, inputStream, 1);
+        proxy.setBinaryStream(1, inputStream, 1);
+        proxy.clearParameters();
+        proxy.setObject(1, "x", Types.VARCHAR);
+        proxy.setObject(1, "x");
+        proxy.setCharacterStream(1, reader, 1);
+        proxy.setRef(1, ref);
+        proxy.setBlob(1, blob);
+        proxy.setClob(1, clob);
+        proxy.setArray(1, array);
+        proxy.setDate(1, date, calendar);
+        proxy.setTime(1, time, calendar);
+        proxy.setTimestamp(1, timestamp, calendar);
+        proxy.setNull(1, Types.VARCHAR, "VARCHAR");
+        proxy.setURL(1, url);
+        proxy.setRowId(1, rowId);
+        proxy.setNString(1, "x");
+        proxy.setNCharacterStream(1, reader, 1L);
+        proxy.setNClob(1, nClob);
+        proxy.setClob(1, reader, 1L);
+        proxy.setBlob(1, inputStream, 1L);
+        proxy.setNClob(1, reader, 1L);
+        proxy.setSQLXML(1, sqlxml);
+        proxy.setObject(1, "x", Types.VARCHAR, 1);
+        proxy.setAsciiStream(1, inputStream, 1L);
+        proxy.setBinaryStream(1, inputStream, 1L);
+        proxy.setCharacterStream(1, reader, 1L);
+        proxy.setAsciiStream(1, inputStream);
+        proxy.setBinaryStream(1, inputStream);
+        proxy.setCharacterStream(1, reader);
+        proxy.setNCharacterStream(1, reader);
+        proxy.setClob(1, reader);
+        proxy.setBlob(1, inputStream);
+        proxy.setNClob(1, reader);
+        proxy.setObject(1, "x", sqlType, 1);
+        proxy.setObject(1, "x", sqlType);
+        proxy.addBatch();
+
+        verify(callableStatement).setNull(1, Types.VARCHAR);
+        verify(callableStatement).setBoolean(1, true);
+        verify(callableStatement).setInt(1, 1);
+        verify(callableStatement).setString(1, "x");
+        verify(callableStatement).setUnicodeStream(1, inputStream, 1);
+        verify(callableStatement).clearParameters();
+        verify(callableStatement).setRef(1, ref);
+        verify(callableStatement).setBlob(1, blob);
+        verify(callableStatement).setClob(1, clob);
+        verify(callableStatement).setArray(1, array);
+        verify(callableStatement).setSQLXML(1, sqlxml);
+        verify(callableStatement).setObject(1, "x", sqlType, 1);
+        verify(callableStatement).setObject(1, "x", sqlType);
+        verify(callableStatement).addBatch();
+    }
+
+    @Test
+    void testExecuteMethods() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(callableStatement.executeQuery()).thenReturn(resultSet);
+        when(callableStatement.executeUpdate()).thenReturn(1);
+        when(callableStatement.execute()).thenReturn(true);
+        when(callableStatement.executeLargeUpdate()).thenReturn(2L);
+        ResultSetMetaData metaData = mock(ResultSetMetaData.class);
+        ParameterMetaData parameterMetaData = mock(ParameterMetaData.class);
+        when(callableStatement.getMetaData()).thenReturn(metaData);
+        when(callableStatement.getParameterMetaData()).thenReturn(parameterMetaData);
+        ResultSet generatedKeys = mockEmptyResultSet();
+        when(callableStatement.getGeneratedKeys()).thenReturn(generatedKeys);
+
+        assertTrue(proxy.executeQuery() instanceof ResultSetProxy);
+        assertEquals(1, proxy.executeUpdate());
+        assertTrue(proxy.execute());
+        assertEquals(2L, proxy.executeLargeUpdate());
+        assertSame(metaData, proxy.getMetaData());
+        assertSame(parameterMetaData, proxy.getParameterMetaData());
+        assertSame(generatedKeys, proxy.getGeneratedKeys());
+    }
+
+    @Test
+    void testStatementLevelSqlMethodsIntercept() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(callableStatement.executeQuery(anyString())).thenReturn(resultSet);
+        when(callableStatement.executeUpdate(anyString())).thenReturn(1);
+        when(callableStatement.executeUpdate(anyString(), anyInt())).thenReturn(1);
+        when(callableStatement.executeUpdate(anyString(), (int[]) any())).thenReturn(1);
+        when(callableStatement.executeUpdate(anyString(), (String[]) any())).thenReturn(1);
+        when(callableStatement.execute(anyString())).thenReturn(true);
+        when(callableStatement.execute(anyString(), anyInt())).thenReturn(true);
+        when(callableStatement.execute(anyString(), (int[]) any())).thenReturn(true);
+        when(callableStatement.execute(anyString(), (String[]) any())).thenReturn(true);
+        when(callableStatement.executeLargeUpdate(anyString())).thenReturn(2L);
+        when(callableStatement.executeLargeUpdate(anyString(), anyInt())).thenReturn(2L);
+        when(callableStatement.executeLargeUpdate(anyString(), (int[]) any())).thenReturn(2L);
+        when(callableStatement.executeLargeUpdate(anyString(), (String[]) any())).thenReturn(2L);
+        ResultSet rawResultSet = mockEmptyResultSet();
+        when(callableStatement.getResultSet()).thenReturn(rawResultSet);
+        Connection connection = mock(Connection.class);
+        when(callableStatement.getConnection()).thenReturn(connection);
+
+        String sql = "select name from t_user";
+
+        assertTrue(proxy.executeQuery(sql) instanceof ResultSetProxy);
+        assertEquals(1, proxy.executeUpdate(sql));
+        assertTrue(proxy.execute(sql));
+        proxy.addBatch(sql);
+        assertEquals(2L, proxy.executeLargeUpdate(sql));
+        assertEquals(1, proxy.executeUpdate(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertEquals(1, proxy.executeUpdate(sql, new int[]{1}));
+        assertEquals(1, proxy.executeUpdate(sql, new String[]{"id"}));
+        assertTrue(proxy.execute(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertTrue(proxy.execute(sql, new int[]{1}));
+        assertTrue(proxy.execute(sql, new String[]{"id"}));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, new int[]{1}));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, new String[]{"id"}));
+        assertTrue(proxy.getResultSet() instanceof ResultSetProxy);
+        assertTrue(proxy.getConnection() instanceof ConnectionProxy);
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(callableStatement).executeQuery(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testAttributeDelegates() throws SQLException {
+        when(callableStatement.getMaxFieldSize()).thenReturn(1);
+        when(callableStatement.getMaxRows()).thenReturn(2);
+        when(callableStatement.getQueryTimeout()).thenReturn(3);
+        SQLWarning warning = mock(SQLWarning.class);
+        when(callableStatement.getWarnings()).thenReturn(warning);
+        when(callableStatement.getUpdateCount()).thenReturn(4);
+        when(callableStatement.getMoreResults()).thenReturn(true);
+        when(callableStatement.getFetchDirection()).thenReturn(ResultSet.FETCH_FORWARD);
+        when(callableStatement.getFetchSize()).thenReturn(5);
+        when(callableStatement.getResultSetConcurrency()).thenReturn(ResultSet.CONCUR_READ_ONLY);
+        when(callableStatement.getResultSetType()).thenReturn(ResultSet.TYPE_FORWARD_ONLY);
+        when(callableStatement.getMoreResults(java.sql.Statement.CLOSE_CURRENT_RESULT)).thenReturn(false);
+        when(callableStatement.getResultSetHoldability()).thenReturn(ResultSet.HOLD_CURSORS_OVER_COMMIT);
+        when(callableStatement.isClosed()).thenReturn(false);
+        when(callableStatement.isPoolable()).thenReturn(true);
+        when(callableStatement.isCloseOnCompletion()).thenReturn(false);
+        when(callableStatement.getLargeUpdateCount()).thenReturn(6L);
+        when(callableStatement.getLargeMaxRows()).thenReturn(7L);
+        when(callableStatement.executeBatch()).thenReturn(new int[]{1});
+        when(callableStatement.executeLargeBatch()).thenReturn(new long[]{2L});
+
+        assertEquals(1, proxy.getMaxFieldSize());
+        assertEquals(2, proxy.getMaxRows());
+        assertEquals(3, proxy.getQueryTimeout());
+        assertSame(warning, proxy.getWarnings());
+        assertEquals(4, proxy.getUpdateCount());
+        assertTrue(proxy.getMoreResults());
+        assertEquals(ResultSet.FETCH_FORWARD, proxy.getFetchDirection());
+        assertEquals(5, proxy.getFetchSize());
+        assertEquals(ResultSet.CONCUR_READ_ONLY, proxy.getResultSetConcurrency());
+        assertEquals(ResultSet.TYPE_FORWARD_ONLY, proxy.getResultSetType());
+        assertEquals(false, proxy.getMoreResults(java.sql.Statement.CLOSE_CURRENT_RESULT));
+        assertEquals(ResultSet.HOLD_CURSORS_OVER_COMMIT, proxy.getResultSetHoldability());
+        assertEquals(false, proxy.isClosed());
+        assertTrue(proxy.isPoolable());
+        assertEquals(false, proxy.isCloseOnCompletion());
+        assertEquals(6L, proxy.getLargeUpdateCount());
+        assertEquals(7L, proxy.getLargeMaxRows());
+        assertEquals(1, proxy.executeBatch().length);
+        assertEquals(1, proxy.executeLargeBatch().length);
+
+        proxy.setMaxFieldSize(10);
+        proxy.setMaxRows(20);
+        proxy.setEscapeProcessing(true);
+        proxy.setQueryTimeout(30);
+        proxy.setFetchDirection(ResultSet.FETCH_REVERSE);
+        proxy.setFetchSize(40);
+        proxy.setPoolable(false);
+        proxy.setLargeMaxRows(50L);
+        proxy.clearWarnings();
+        proxy.clearBatch();
+        proxy.closeOnCompletion();
+        proxy.close();
+        proxy.cancel();
+        proxy.setCursorName("cursor");
+
+        verify(callableStatement).setMaxFieldSize(10);
+        verify(callableStatement).setMaxRows(20);
+        verify(callableStatement).setEscapeProcessing(true);
+        verify(callableStatement).setQueryTimeout(30);
+        verify(callableStatement).setFetchDirection(ResultSet.FETCH_REVERSE);
+        verify(callableStatement).setFetchSize(40);
+        verify(callableStatement).setPoolable(false);
+        verify(callableStatement).setLargeMaxRows(50L);
+        verify(callableStatement).clearWarnings();
+        verify(callableStatement).clearBatch();
+        verify(callableStatement).closeOnCompletion();
+        verify(callableStatement).close();
+        verify(callableStatement).cancel();
+        verify(callableStatement).setCursorName("cursor");
+    }
+
+    @Test
+    void testEnquoteAndWrapperDelegates() throws SQLException {
+        when(callableStatement.enquoteLiteral("v")).thenReturn("'v'");
+        when(callableStatement.enquoteIdentifier("id", true)).thenReturn("\"id\"");
+        when(callableStatement.isSimpleIdentifier("id")).thenReturn(true);
+        when(callableStatement.enquoteNCharLiteral("v")).thenReturn("N'v'");
+        when(callableStatement.unwrap(String.class)).thenReturn("unwrapped");
+        when(callableStatement.isWrapperFor(String.class)).thenReturn(true);
+
+        assertEquals("'v'", proxy.enquoteLiteral("v"));
+        assertEquals("\"id\"", proxy.enquoteIdentifier("id", true));
+        assertTrue(proxy.isSimpleIdentifier("id"));
+        assertEquals("N'v'", proxy.enquoteNCharLiteral("v"));
+        assertEquals("unwrapped", proxy.unwrap(String.class));
+        assertTrue(proxy.isWrapperFor(String.class));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ConnectionProxyTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ConnectionProxyTest.java
new file mode 100644
index 000000000..ab3e8938a
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ConnectionProxyTest.java
@@ -0,0 +1,281 @@
+package com.codingapi.springboot.authorization.jdbc.proxy;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.CallableStatement;
+import java.sql.Clob;
+import java.sql.Connection;
+import java.sql.DatabaseMetaData;
+import java.sql.NClob;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.SQLWarning;
+import java.sql.Savepoint;
+import java.sql.ShardingKey;
+import java.sql.SQLXML;
+import java.sql.Statement;
+import java.sql.Struct;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Properties;
+import java.util.concurrent.Executor;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * ConnectionProxy 单元测试
+ * 验证方法委托以及 prepareStatement/prepareCall 的 SQL 拦截行为
+ */
+class ConnectionProxyTest {
+
+    private Connection connection;
+    private ConnectionProxy proxy;
+
+    @BeforeEach
+    void setUp() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        ResultSetProxyTest.registerTestFilter();
+
+        connection = mock(Connection.class);
+        proxy = new ConnectionProxy(connection);
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    @Test
+    void testCreateStatementReturnsStatementProxy() throws SQLException {
+        Statement statement = mock(Statement.class);
+        when(connection.createStatement()).thenReturn(statement);
+        when(connection.createStatement(anyInt(), anyInt())).thenReturn(statement);
+        when(connection.createStatement(anyInt(), anyInt(), anyInt())).thenReturn(statement);
+
+        assertTrue(proxy.createStatement() instanceof StatementProxy);
+        assertTrue(proxy.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY) instanceof StatementProxy);
+        assertTrue(proxy.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY,
+                ResultSet.HOLD_CURSORS_OVER_COMMIT) instanceof StatementProxy);
+
+        verify(connection).createStatement();
+        verify(connection).createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY);
+        verify(connection).createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY,
+                ResultSet.HOLD_CURSORS_OVER_COMMIT);
+    }
+
+    @Test
+    void testPrepareStatementInterceptsSql() throws SQLException {
+        PreparedStatement preparedStatement = mock(PreparedStatement.class);
+        when(connection.prepareStatement(anyString())).thenReturn(preparedStatement);
+        when(connection.prepareStatement(anyString(), anyInt())).thenReturn(preparedStatement);
+        when(connection.prepareStatement(anyString(), (int[]) org.mockito.ArgumentMatchers.any())).thenReturn(preparedStatement);
+        when(connection.prepareStatement(anyString(), (String[]) org.mockito.ArgumentMatchers.any())).thenReturn(preparedStatement);
+        when(connection.prepareStatement(anyString(), anyInt(), anyInt())).thenReturn(preparedStatement);
+        when(connection.prepareStatement(anyString(), anyInt(), anyInt(), anyInt())).thenReturn(preparedStatement);
+
+        String sql = "select name from t_user";
+
+        assertTrue(proxy.prepareStatement(sql) instanceof PreparedStatementProxy);
+        assertTrue(proxy.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS) instanceof PreparedStatementProxy);
+        assertTrue(proxy.prepareStatement(sql, new int[]{1}) instanceof PreparedStatementProxy);
+        assertTrue(proxy.prepareStatement(sql, new String[]{"id"}) instanceof PreparedStatementProxy);
+        assertTrue(proxy.prepareStatement(sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY)
+                instanceof PreparedStatementProxy);
+        assertTrue(proxy.prepareStatement(sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY,
+                ResultSet.HOLD_CURSORS_OVER_COMMIT) instanceof PreparedStatementProxy);
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(connection).prepareStatement(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testPrepareCallInterceptsSql() throws SQLException {
+        CallableStatement callableStatement = mock(CallableStatement.class);
+        when(connection.prepareCall(anyString())).thenReturn(callableStatement);
+        when(connection.prepareCall(anyString(), anyInt(), anyInt())).thenReturn(callableStatement);
+        when(connection.prepareCall(anyString(), anyInt(), anyInt(), anyInt())).thenReturn(callableStatement);
+
+        String sql = "select name from t_user";
+
+        assertTrue(proxy.prepareCall(sql) instanceof CallableStatementProxy);
+        assertTrue(proxy.prepareCall(sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY)
+                instanceof CallableStatementProxy);
+        assertTrue(proxy.prepareCall(sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY,
+                ResultSet.HOLD_CURSORS_OVER_COMMIT) instanceof CallableStatementProxy);
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(connection).prepareCall(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testNativeSqlInterceptsSql() throws SQLException {
+        when(connection.nativeSQL(anyString())).thenReturn("native");
+        assertEquals("native", proxy.nativeSQL("select name from t_user"));
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(connection).nativeSQL(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testTransactionDelegates() throws SQLException {
+        when(connection.getAutoCommit()).thenReturn(true);
+        when(connection.isClosed()).thenReturn(false);
+        when(connection.isReadOnly()).thenReturn(false);
+        when(connection.getTransactionIsolation()).thenReturn(Connection.TRANSACTION_READ_COMMITTED);
+        SQLWarning warning = mock(SQLWarning.class);
+        when(connection.getWarnings()).thenReturn(warning);
+        Savepoint savepoint = mock(Savepoint.class);
+        when(connection.setSavepoint()).thenReturn(savepoint);
+        when(connection.setSavepoint("sp")).thenReturn(savepoint);
+
+        proxy.setAutoCommit(false);
+        verify(connection).setAutoCommit(false);
+        assertTrue(connection.getAutoCommit());
+        assertEquals(true, proxy.getAutoCommit());
+
+        proxy.commit();
+        verify(connection).commit();
+        proxy.rollback();
+        verify(connection).rollback();
+        proxy.rollback(savepoint);
+        verify(connection).rollback(savepoint);
+        proxy.releaseSavepoint(savepoint);
+        verify(connection).releaseSavepoint(savepoint);
+
+        proxy.close();
+        verify(connection).close();
+        assertEquals(false, proxy.isClosed());
+
+        DatabaseMetaData metaData = mock(DatabaseMetaData.class);
+        when(connection.getMetaData()).thenReturn(metaData);
+        assertSame(metaData, proxy.getMetaData());
+
+        proxy.setReadOnly(true);
+        verify(connection).setReadOnly(true);
+        assertEquals(false, proxy.isReadOnly());
+
+        proxy.setCatalog("catalog");
+        verify(connection).setCatalog("catalog");
+        when(connection.getCatalog()).thenReturn("catalog");
+        assertEquals("catalog", proxy.getCatalog());
+
+        proxy.setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE);
+        verify(connection).setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE);
+        assertEquals(Connection.TRANSACTION_READ_COMMITTED, proxy.getTransactionIsolation());
+
+        assertSame(warning, proxy.getWarnings());
+        proxy.clearWarnings();
+        verify(connection).clearWarnings();
+
+        assertSame(savepoint, proxy.setSavepoint());
+        assertSame(savepoint, proxy.setSavepoint("sp"));
+    }
+
+    @Test
+    void testTypeMapAndHoldabilityDelegates() throws SQLException {
+        Map<String, Class<?>> typeMap = new HashMap<>();
+        when(connection.getTypeMap()).thenReturn(typeMap);
+        when(connection.getHoldability()).thenReturn(ResultSet.HOLD_CURSORS_OVER_COMMIT);
+
+        assertSame(typeMap, proxy.getTypeMap());
+        proxy.setTypeMap(typeMap);
+        verify(connection).setTypeMap(typeMap);
+
+        proxy.setHoldability(ResultSet.CLOSE_CURSORS_AT_COMMIT);
+        verify(connection).setHoldability(ResultSet.CLOSE_CURSORS_AT_COMMIT);
+        assertEquals(ResultSet.HOLD_CURSORS_OVER_COMMIT, proxy.getHoldability());
+    }
+
+    @Test
+    void testLobAndMiscDelegates() throws SQLException {
+        Clob clob = mock(Clob.class);
+        Blob blob = mock(Blob.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        Array array = mock(Array.class);
+        Struct struct = mock(Struct.class);
+
+        when(connection.createClob()).thenReturn(clob);
+        when(connection.createBlob()).thenReturn(blob);
+        when(connection.createNClob()).thenReturn(nClob);
+        when(connection.createSQLXML()).thenReturn(sqlxml);
+        when(connection.isValid(1)).thenReturn(true);
+        when(connection.getClientInfo("k")).thenReturn("v");
+        Properties properties = new Properties();
+        when(connection.getClientInfo()).thenReturn(properties);
+        when(connection.createArrayOf("VARCHAR", new Object[]{"a"})).thenReturn(array);
+        when(connection.createStruct("STRUCT", new Object[]{"a"})).thenReturn(struct);
+        when(connection.getSchema()).thenReturn("schema");
+        when(connection.getNetworkTimeout()).thenReturn(100);
+
+        assertSame(clob, proxy.createClob());
+        assertSame(blob, proxy.createBlob());
+        assertSame(nClob, proxy.createNClob());
+        assertSame(sqlxml, proxy.createSQLXML());
+        assertTrue(proxy.isValid(1));
+
+        proxy.setClientInfo("k", "v");
+        verify(connection).setClientInfo("k", "v");
+        proxy.setClientInfo(properties);
+        verify(connection).setClientInfo(properties);
+        assertEquals("v", proxy.getClientInfo("k"));
+        assertSame(properties, proxy.getClientInfo());
+
+        assertSame(array, proxy.createArrayOf("VARCHAR", new Object[]{"a"}));
+        assertSame(struct, proxy.createStruct("STRUCT", new Object[]{"a"}));
+
+        proxy.setSchema("schema");
+        verify(connection).setSchema("schema");
+        assertEquals("schema", proxy.getSchema());
+
+        Executor executor = mock(Executor.class);
+        proxy.abort(executor);
+        verify(connection).abort(executor);
+        proxy.setNetworkTimeout(executor, 100);
+        verify(connection).setNetworkTimeout(executor, 100);
+        assertEquals(100, proxy.getNetworkTimeout());
+
+        proxy.beginRequest();
+        verify(connection).beginRequest();
+        proxy.endRequest();
+        verify(connection).endRequest();
+
+        ShardingKey shardingKey = mock(ShardingKey.class);
+        ShardingKey superShardingKey = mock(ShardingKey.class);
+        when(connection.setShardingKeyIfValid(shardingKey, superShardingKey, 1)).thenReturn(true);
+        when(connection.setShardingKeyIfValid(shardingKey, 1)).thenReturn(true);
+
+        assertTrue(proxy.setShardingKeyIfValid(shardingKey, superShardingKey, 1));
+        assertTrue(proxy.setShardingKeyIfValid(shardingKey, 1));
+        proxy.setShardingKey(shardingKey, superShardingKey);
+        verify(connection).setShardingKey(shardingKey, superShardingKey);
+        proxy.setShardingKey(shardingKey);
+        verify(connection).setShardingKey(shardingKey);
+    }
+
+    @Test
+    void testWrapperDelegates() throws SQLException {
+        when(connection.unwrap(String.class)).thenReturn("unwrapped");
+        when(connection.isWrapperFor(String.class)).thenReturn(true);
+
+        assertEquals("unwrapped", proxy.unwrap(String.class));
+        assertTrue(proxy.isWrapperFor(String.class));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/PreparedStatementProxyTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/PreparedStatementProxyTest.java
new file mode 100644
index 000000000..fdc25f807
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/PreparedStatementProxyTest.java
@@ -0,0 +1,381 @@
+package com.codingapi.springboot.authorization.jdbc.proxy;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.io.Reader;
+import java.io.StringReader;
+import java.math.BigDecimal;
+import java.net.URL;
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.Clob;
+import java.sql.Connection;
+import java.sql.Date;
+import java.sql.JDBCType;
+import java.sql.NClob;
+import java.sql.ParameterMetaData;
+import java.sql.PreparedStatement;
+import java.sql.Ref;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.RowId;
+import java.sql.SQLException;
+import java.sql.SQLType;
+import java.sql.SQLWarning;
+import java.sql.SQLXML;
+import java.sql.Time;
+import java.sql.Timestamp;
+import java.util.Calendar;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * PreparedStatementProxy 单元测试
+ * 验证方法委托以及 SQL 拦截行为
+ */
+class PreparedStatementProxyTest {
+
+    private PreparedStatement preparedStatement;
+    private PreparedStatementProxy proxy;
+
+    @BeforeEach
+    void setUp() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        ResultSetProxyTest.registerTestFilter();
+
+        preparedStatement = mock(PreparedStatement.class);
+        proxy = new PreparedStatementProxy(preparedStatement, SQLExecuteState.unIntercept("select 1"));
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    private ResultSet mockEmptyResultSet() throws SQLException {
+        ResultSet resultSet = mock(ResultSet.class);
+        ResultSetMetaData metaData = mock(ResultSetMetaData.class);
+        when(resultSet.getMetaData()).thenReturn(metaData);
+        when(metaData.getColumnCount()).thenReturn(0);
+        return resultSet;
+    }
+
+    @Test
+    void testExecuteMethods() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(preparedStatement.executeQuery()).thenReturn(resultSet);
+        when(preparedStatement.executeUpdate()).thenReturn(1);
+        when(preparedStatement.execute()).thenReturn(true);
+        when(preparedStatement.executeLargeUpdate()).thenReturn(2L);
+
+        assertTrue(proxy.executeQuery() instanceof ResultSetProxy);
+        assertEquals(1, proxy.executeUpdate());
+        assertTrue(proxy.execute());
+        assertEquals(2L, proxy.executeLargeUpdate());
+
+        verify(preparedStatement).executeQuery();
+        verify(preparedStatement).executeUpdate();
+        verify(preparedStatement).execute();
+        verify(preparedStatement).executeLargeUpdate();
+    }
+
+    @Test
+    void testParameterSettersDelegate() throws SQLException {
+        InputStream inputStream = new ByteArrayInputStream(new byte[]{1});
+        Reader reader = new StringReader("x");
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+
+        proxy.setNull(1, java.sql.Types.VARCHAR);
+        proxy.setBoolean(1, true);
+        proxy.setByte(1, (byte) 1);
+        proxy.setShort(1, (short) 1);
+        proxy.setInt(1, 1);
+        proxy.setLong(1, 1L);
+        proxy.setFloat(1, 1.0f);
+        proxy.setDouble(1, 1.0d);
+        proxy.setBigDecimal(1, BigDecimal.ONE);
+        proxy.setString(1, "x");
+        proxy.setBytes(1, new byte[]{1});
+        proxy.setDate(1, date);
+        proxy.setTime(1, time);
+        proxy.setTimestamp(1, timestamp);
+        proxy.setAsciiStream(1, inputStream, 1);
+        proxy.setUnicodeStream(1, inputStream, 1);
+        proxy.setBinaryStream(1, inputStream, 1);
+        proxy.clearParameters();
+        proxy.setObject(1, "x", java.sql.Types.VARCHAR);
+        proxy.setObject(1, "x");
+        proxy.setCharacterStream(1, reader, 1);
+        proxy.setRef(1, ref);
+        proxy.setBlob(1, blob);
+        proxy.setClob(1, clob);
+        proxy.setArray(1, array);
+        proxy.setDate(1, date, calendar);
+        proxy.setTime(1, time, calendar);
+        proxy.setTimestamp(1, timestamp, calendar);
+        proxy.setNull(1, java.sql.Types.VARCHAR, "VARCHAR");
+        proxy.setURL(1, url);
+        proxy.setRowId(1, rowId);
+        proxy.setNString(1, "x");
+        proxy.setNCharacterStream(1, reader, 1L);
+        proxy.setNClob(1, nClob);
+        proxy.setClob(1, reader, 1L);
+        proxy.setBlob(1, inputStream, 1L);
+        proxy.setNClob(1, reader, 1L);
+        proxy.setSQLXML(1, sqlxml);
+        proxy.setObject(1, "x", java.sql.Types.VARCHAR, 1);
+        proxy.setAsciiStream(1, inputStream, 1L);
+        proxy.setBinaryStream(1, inputStream, 1L);
+        proxy.setCharacterStream(1, reader, 1L);
+        proxy.setAsciiStream(1, inputStream);
+        proxy.setBinaryStream(1, inputStream);
+        proxy.setCharacterStream(1, reader);
+        proxy.setNCharacterStream(1, reader);
+        proxy.setClob(1, reader);
+        proxy.setBlob(1, inputStream);
+        proxy.setNClob(1, reader);
+        SQLType sqlType = JDBCType.VARCHAR;
+        proxy.setObject(1, "x", sqlType, 1);
+        proxy.setObject(1, "x", sqlType);
+        proxy.addBatch();
+
+        verify(preparedStatement).setNull(1, java.sql.Types.VARCHAR);
+        verify(preparedStatement).setBoolean(1, true);
+        verify(preparedStatement).setByte(1, (byte) 1);
+        verify(preparedStatement).setShort(1, (short) 1);
+        verify(preparedStatement).setInt(1, 1);
+        verify(preparedStatement).setLong(1, 1L);
+        verify(preparedStatement).setFloat(1, 1.0f);
+        verify(preparedStatement).setDouble(1, 1.0d);
+        verify(preparedStatement).setBigDecimal(1, BigDecimal.ONE);
+        verify(preparedStatement).setString(1, "x");
+        verify(preparedStatement).setDate(1, date);
+        verify(preparedStatement).setTime(1, time);
+        verify(preparedStatement).setTimestamp(1, timestamp);
+        verify(preparedStatement).setAsciiStream(1, inputStream, 1);
+        verify(preparedStatement).setUnicodeStream(1, inputStream, 1);
+        verify(preparedStatement).setBinaryStream(1, inputStream, 1);
+        verify(preparedStatement).clearParameters();
+        verify(preparedStatement).setObject(1, "x", java.sql.Types.VARCHAR);
+        verify(preparedStatement).setObject(1, "x");
+        verify(preparedStatement).setCharacterStream(1, reader, 1);
+        verify(preparedStatement).setRef(1, ref);
+        verify(preparedStatement).setBlob(1, blob);
+        verify(preparedStatement).setClob(1, clob);
+        verify(preparedStatement).setArray(1, array);
+        verify(preparedStatement).setDate(1, date, calendar);
+        verify(preparedStatement).setTime(1, time, calendar);
+        verify(preparedStatement).setTimestamp(1, timestamp, calendar);
+        verify(preparedStatement).setNull(1, java.sql.Types.VARCHAR, "VARCHAR");
+        verify(preparedStatement).setURL(1, url);
+        verify(preparedStatement).setRowId(1, rowId);
+        verify(preparedStatement).setNString(1, "x");
+        verify(preparedStatement).setNCharacterStream(1, reader, 1L);
+        verify(preparedStatement).setNClob(1, nClob);
+        verify(preparedStatement).setClob(1, reader, 1L);
+        verify(preparedStatement).setBlob(1, inputStream, 1L);
+        verify(preparedStatement).setNClob(1, reader, 1L);
+        verify(preparedStatement).setSQLXML(1, sqlxml);
+        verify(preparedStatement).setObject(1, "x", java.sql.Types.VARCHAR, 1);
+        verify(preparedStatement).setAsciiStream(1, inputStream, 1L);
+        verify(preparedStatement).setBinaryStream(1, inputStream, 1L);
+        verify(preparedStatement).setCharacterStream(1, reader, 1L);
+        verify(preparedStatement).setAsciiStream(1, inputStream);
+        verify(preparedStatement).setBinaryStream(1, inputStream);
+        verify(preparedStatement).setCharacterStream(1, reader);
+        verify(preparedStatement).setNCharacterStream(1, reader);
+        verify(preparedStatement).setClob(1, reader);
+        verify(preparedStatement).setBlob(1, inputStream);
+        verify(preparedStatement).setNClob(1, reader);
+        verify(preparedStatement).setObject(1, "x", sqlType, 1);
+        verify(preparedStatement).setObject(1, "x", sqlType);
+        verify(preparedStatement).addBatch();
+    }
+
+    @Test
+    void testMetaDataDelegates() throws SQLException {
+        ResultSetMetaData resultSetMetaData = mock(ResultSetMetaData.class);
+        ParameterMetaData parameterMetaData = mock(ParameterMetaData.class);
+        when(preparedStatement.getMetaData()).thenReturn(resultSetMetaData);
+        when(preparedStatement.getParameterMetaData()).thenReturn(parameterMetaData);
+
+        assertSame(resultSetMetaData, proxy.getMetaData());
+        assertSame(parameterMetaData, proxy.getParameterMetaData());
+    }
+
+    @Test
+    void testStatementLevelSqlMethodsIntercept() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(preparedStatement.executeQuery(anyString())).thenReturn(resultSet);
+        when(preparedStatement.executeUpdate(anyString())).thenReturn(1);
+        when(preparedStatement.executeUpdate(anyString(), anyInt())).thenReturn(1);
+        when(preparedStatement.executeUpdate(anyString(), (int[]) any())).thenReturn(1);
+        when(preparedStatement.executeUpdate(anyString(), (String[]) any())).thenReturn(1);
+        when(preparedStatement.execute(anyString())).thenReturn(true);
+        when(preparedStatement.execute(anyString(), anyInt())).thenReturn(true);
+        when(preparedStatement.execute(anyString(), (int[]) any())).thenReturn(true);
+        when(preparedStatement.execute(anyString(), (String[]) any())).thenReturn(true);
+        when(preparedStatement.executeLargeUpdate(anyString())).thenReturn(2L);
+        when(preparedStatement.executeLargeUpdate(anyString(), anyInt())).thenReturn(2L);
+        when(preparedStatement.executeLargeUpdate(anyString(), (int[]) any())).thenReturn(2L);
+        when(preparedStatement.executeLargeUpdate(anyString(), (String[]) any())).thenReturn(2L);
+
+        String sql = "select name from t_user";
+
+        assertTrue(proxy.executeQuery(sql) instanceof ResultSetProxy);
+        assertEquals(1, proxy.executeUpdate(sql));
+        assertTrue(proxy.execute(sql));
+        proxy.addBatch(sql);
+        assertEquals(2L, proxy.executeLargeUpdate(sql));
+        assertEquals(1, proxy.executeUpdate(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertEquals(1, proxy.executeUpdate(sql, new int[]{1}));
+        assertEquals(1, proxy.executeUpdate(sql, new String[]{"id"}));
+        assertTrue(proxy.execute(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertTrue(proxy.execute(sql, new int[]{1}));
+        assertTrue(proxy.execute(sql, new String[]{"id"}));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, java.sql.Statement.RETURN_GENERATED_KEYS));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, new int[]{1}));
+        assertEquals(2L, proxy.executeLargeUpdate(sql, new String[]{"id"}));
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(preparedStatement).executeQuery(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+        verify(preparedStatement).addBatch(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testResultSetWrapping() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        ResultSet generatedKeys = mockEmptyResultSet();
+        when(preparedStatement.getResultSet()).thenReturn(resultSet);
+        when(preparedStatement.getGeneratedKeys()).thenReturn(generatedKeys);
+
+        assertTrue(proxy.getResultSet() instanceof ResultSetProxy);
+        assertTrue(proxy.getGeneratedKeys() instanceof ResultSetProxy);
+    }
+
+    @Test
+    void testGetConnectionReturnsConnectionProxy() throws SQLException {
+        Connection connection = mock(Connection.class);
+        when(preparedStatement.getConnection()).thenReturn(connection);
+        assertTrue(proxy.getConnection() instanceof ConnectionProxy);
+    }
+
+    @Test
+    void testAttributeDelegates() throws SQLException {
+        when(preparedStatement.getMaxFieldSize()).thenReturn(1);
+        when(preparedStatement.getMaxRows()).thenReturn(2);
+        when(preparedStatement.getQueryTimeout()).thenReturn(3);
+        SQLWarning warning = mock(SQLWarning.class);
+        when(preparedStatement.getWarnings()).thenReturn(warning);
+        when(preparedStatement.getUpdateCount()).thenReturn(4);
+        when(preparedStatement.getMoreResults()).thenReturn(true);
+        when(preparedStatement.getFetchDirection()).thenReturn(ResultSet.FETCH_FORWARD);
+        when(preparedStatement.getFetchSize()).thenReturn(5);
+        when(preparedStatement.getResultSetConcurrency()).thenReturn(ResultSet.CONCUR_READ_ONLY);
+        when(preparedStatement.getResultSetType()).thenReturn(ResultSet.TYPE_FORWARD_ONLY);
+        when(preparedStatement.getMoreResults(java.sql.Statement.CLOSE_CURRENT_RESULT)).thenReturn(false);
+        when(preparedStatement.getResultSetHoldability()).thenReturn(ResultSet.HOLD_CURSORS_OVER_COMMIT);
+        when(preparedStatement.isClosed()).thenReturn(false);
+        when(preparedStatement.isPoolable()).thenReturn(true);
+        when(preparedStatement.isCloseOnCompletion()).thenReturn(false);
+        when(preparedStatement.getLargeUpdateCount()).thenReturn(6L);
+        when(preparedStatement.getLargeMaxRows()).thenReturn(7L);
+        when(preparedStatement.executeBatch()).thenReturn(new int[]{1});
+        when(preparedStatement.executeLargeBatch()).thenReturn(new long[]{2L});
+
+        assertEquals(1, proxy.getMaxFieldSize());
+        assertEquals(2, proxy.getMaxRows());
+        assertEquals(3, proxy.getQueryTimeout());
+        assertSame(warning, proxy.getWarnings());
+        assertEquals(4, proxy.getUpdateCount());
+        assertTrue(proxy.getMoreResults());
+        assertEquals(ResultSet.FETCH_FORWARD, proxy.getFetchDirection());
+        assertEquals(5, proxy.getFetchSize());
+        assertEquals(ResultSet.CONCUR_READ_ONLY, proxy.getResultSetConcurrency());
+        assertEquals(ResultSet.TYPE_FORWARD_ONLY, proxy.getResultSetType());
+        assertEquals(false, proxy.getMoreResults(java.sql.Statement.CLOSE_CURRENT_RESULT));
+        assertEquals(ResultSet.HOLD_CURSORS_OVER_COMMIT, proxy.getResultSetHoldability());
+        assertEquals(false, proxy.isClosed());
+        assertTrue(proxy.isPoolable());
+        assertEquals(false, proxy.isCloseOnCompletion());
+        assertEquals(6L, proxy.getLargeUpdateCount());
+        assertEquals(7L, proxy.getLargeMaxRows());
+        assertEquals(1, proxy.executeBatch().length);
+        assertEquals(1, proxy.executeLargeBatch().length);
+
+        proxy.setMaxFieldSize(10);
+        proxy.setMaxRows(20);
+        proxy.setEscapeProcessing(true);
+        proxy.setQueryTimeout(30);
+        proxy.setFetchDirection(ResultSet.FETCH_REVERSE);
+        proxy.setFetchSize(40);
+        proxy.setPoolable(false);
+        proxy.setLargeMaxRows(50L);
+        proxy.clearWarnings();
+        proxy.clearBatch();
+        proxy.closeOnCompletion();
+        proxy.close();
+        proxy.cancel();
+        proxy.setCursorName("cursor");
+
+        verify(preparedStatement).setMaxFieldSize(10);
+        verify(preparedStatement).setMaxRows(20);
+        verify(preparedStatement).setEscapeProcessing(true);
+        verify(preparedStatement).setQueryTimeout(30);
+        verify(preparedStatement).setFetchDirection(ResultSet.FETCH_REVERSE);
+        verify(preparedStatement).setFetchSize(40);
+        verify(preparedStatement).setPoolable(false);
+        verify(preparedStatement).setLargeMaxRows(50L);
+        verify(preparedStatement).clearWarnings();
+        verify(preparedStatement).clearBatch();
+        verify(preparedStatement).closeOnCompletion();
+        verify(preparedStatement).close();
+        verify(preparedStatement).cancel();
+        verify(preparedStatement).setCursorName("cursor");
+    }
+
+    @Test
+    void testEnquoteAndWrapperDelegates() throws SQLException {
+        when(preparedStatement.enquoteLiteral("v")).thenReturn("'v'");
+        when(preparedStatement.enquoteIdentifier("id", true)).thenReturn("\"id\"");
+        when(preparedStatement.isSimpleIdentifier("id")).thenReturn(true);
+        when(preparedStatement.enquoteNCharLiteral("v")).thenReturn("N'v'");
+        when(preparedStatement.unwrap(String.class)).thenReturn("unwrapped");
+        when(preparedStatement.isWrapperFor(String.class)).thenReturn(true);
+
+        assertEquals("'v'", proxy.enquoteLiteral("v"));
+        assertEquals("\"id\"", proxy.enquoteIdentifier("id", true));
+        assertTrue(proxy.isSimpleIdentifier("id"));
+        assertEquals("N'v'", proxy.enquoteNCharLiteral("v"));
+        assertEquals("unwrapped", proxy.unwrap(String.class));
+        assertTrue(proxy.isWrapperFor(String.class));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ResultSetProxyTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ResultSetProxyTest.java
new file mode 100644
index 000000000..41214415a
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/ResultSetProxyTest.java
@@ -0,0 +1,636 @@
+package com.codingapi.springboot.authorization.jdbc.proxy;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.filter.DefaultDataAuthorizationFilter;
+import com.codingapi.springboot.authorization.handler.Condition;
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import com.codingapi.springboot.authorization.interceptor.SQLRunningContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.io.Reader;
+import java.io.StringReader;
+import java.math.BigDecimal;
+import java.net.URL;
+import java.sql.Array;
+import java.sql.Blob;
+import java.sql.Clob;
+import java.sql.Date;
+import java.sql.NClob;
+import java.sql.Ref;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.RowId;
+import java.sql.SQLException;
+import java.sql.SQLWarning;
+import java.sql.SQLXML;
+import java.sql.Statement;
+import java.sql.Time;
+import java.sql.Timestamp;
+import java.util.Calendar;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * ResultSetProxy 单元测试
+ * 验证所有方法正确委托到底层 ResultSet，以及列权限拦截逻辑生效
+ */
+class ResultSetProxyTest {
+
+    private ResultSet resultSet;
+    private ResultSetMetaData metaData;
+    private ResultSetProxy proxy;
+
+    /**
+     * 构造一个 t_user 表的行权限过滤器（id > 100）以及 name 列的列权限过滤器
+     */
+    static void registerTestFilter() {
+        DataAuthorizationContext.getInstance().addDataAuthorizationFilter(new DefaultDataAuthorizationFilter() {
+            @Override
+            public boolean supportRowAuthorization(String tableName, String tableAlias) {
+                return "t_user".equalsIgnoreCase(tableName);
+            }
+
+            @Override
+            public Condition rowAuthorization(String tableName, String tableAlias) {
+                return Condition.formatCondition("%s.id > 100", tableAlias);
+            }
+
+            @Override
+            public boolean supportColumnAuthorization(String tableName, String columnName, Object value) {
+                return "t_user".equalsIgnoreCase(tableName) && "name".equalsIgnoreCase(columnName);
+            }
+
+            @SuppressWarnings("unchecked")
+            @Override
+            public <T> T columnAuthorization(String tableName, String columnName, T value) {
+                if (value instanceof String) {
+                    return (T) ("MASKED-" + value);
+                }
+                return value;
+            }
+        });
+    }
+
+    @BeforeEach
+    void setUp() throws SQLException {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        registerTestFilter();
+
+        resultSet = mock(ResultSet.class);
+        metaData = mock(ResultSetMetaData.class);
+        when(resultSet.getMetaData()).thenReturn(metaData);
+        when(metaData.getColumnCount()).thenReturn(1);
+        when(metaData.getColumnLabel(1)).thenReturn("name");
+        when(metaData.getTableName(1)).thenReturn("t_user");
+        when(metaData.getColumnName(1)).thenReturn("name");
+        // 默认使用未拦截状态，列权限不生效，直接透传底层值
+        proxy = new ResultSetProxy(resultSet, SQLExecuteState.unIntercept("select 1"));
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    @Test
+    void testNavigationAndCloseDelegates() throws SQLException {
+        when(resultSet.next()).thenReturn(true);
+        when(resultSet.wasNull()).thenReturn(true);
+        when(resultSet.isBeforeFirst()).thenReturn(true);
+        when(resultSet.isAfterLast()).thenReturn(false);
+        when(resultSet.isFirst()).thenReturn(true);
+        when(resultSet.isLast()).thenReturn(false);
+        when(resultSet.first()).thenReturn(true);
+        when(resultSet.last()).thenReturn(true);
+        when(resultSet.getRow()).thenReturn(5);
+        when(resultSet.absolute(3)).thenReturn(true);
+        when(resultSet.relative(2)).thenReturn(true);
+        when(resultSet.previous()).thenReturn(false);
+        when(resultSet.isClosed()).thenReturn(false);
+        when(resultSet.getHoldability()).thenReturn(ResultSet.HOLD_CURSORS_OVER_COMMIT);
+        when(resultSet.getType()).thenReturn(ResultSet.TYPE_FORWARD_ONLY);
+        when(resultSet.getConcurrency()).thenReturn(ResultSet.CONCUR_READ_ONLY);
+        when(resultSet.getFetchDirection()).thenReturn(ResultSet.FETCH_FORWARD);
+        when(resultSet.getFetchSize()).thenReturn(10);
+        when(resultSet.rowUpdated()).thenReturn(true);
+        when(resultSet.rowInserted()).thenReturn(false);
+        when(resultSet.rowDeleted()).thenReturn(false);
+
+        assertTrue(proxy.next());
+        verify(resultSet).next();
+        assertTrue(proxy.wasNull());
+        verify(resultSet).wasNull();
+
+        proxy.close();
+        verify(resultSet).close();
+
+        assertTrue(proxy.isBeforeFirst());
+        assertFalseNoImport(proxy.isAfterLast());
+        assertTrue(proxy.isFirst());
+        assertFalseNoImport(proxy.isLast());
+        assertTrue(proxy.first());
+        assertTrue(proxy.last());
+        assertEquals(5, proxy.getRow());
+        assertTrue(proxy.absolute(3));
+        assertTrue(proxy.relative(2));
+        assertFalseNoImport(proxy.previous());
+        assertFalseNoImport(proxy.isClosed());
+        assertEquals(ResultSet.HOLD_CURSORS_OVER_COMMIT, proxy.getHoldability());
+        assertEquals(ResultSet.TYPE_FORWARD_ONLY, proxy.getType());
+        assertEquals(ResultSet.CONCUR_READ_ONLY, proxy.getConcurrency());
+        assertEquals(ResultSet.FETCH_FORWARD, proxy.getFetchDirection());
+        assertEquals(10, proxy.getFetchSize());
+        assertTrue(proxy.rowUpdated());
+        assertFalseNoImport(proxy.rowInserted());
+        assertFalseNoImport(proxy.rowDeleted());
+
+        proxy.beforeFirst();
+        verify(resultSet).beforeFirst();
+        proxy.afterLast();
+        verify(resultSet).afterLast();
+        proxy.setFetchDirection(ResultSet.FETCH_REVERSE);
+        verify(resultSet).setFetchDirection(ResultSet.FETCH_REVERSE);
+        proxy.setFetchSize(20);
+        verify(resultSet).setFetchSize(20);
+    }
+
+    private static void assertFalseNoImport(boolean value) {
+        assertEquals(false, value);
+    }
+
+    @Test
+    void testGettersByColumnIndexDelegate() throws SQLException {
+        when(resultSet.getString(1)).thenReturn("value");
+        when(resultSet.getBoolean(1)).thenReturn(true);
+        when(resultSet.getByte(1)).thenReturn((byte) 1);
+        when(resultSet.getShort(1)).thenReturn((short) 2);
+        when(resultSet.getInt(1)).thenReturn(3);
+        when(resultSet.getLong(1)).thenReturn(4L);
+        when(resultSet.getFloat(1)).thenReturn(5.0f);
+        when(resultSet.getDouble(1)).thenReturn(6.0d);
+        when(resultSet.getBigDecimal(1)).thenReturn(BigDecimal.ONE);
+        when(resultSet.getBigDecimal(1, 2)).thenReturn(BigDecimal.TEN);
+        when(resultSet.getBytes(1)).thenReturn(new byte[]{1, 2});
+        Date date = new Date(1000L);
+        when(resultSet.getDate(1)).thenReturn(date);
+        Time time = new Time(2000L);
+        when(resultSet.getTime(1)).thenReturn(time);
+        Timestamp timestamp = new Timestamp(3000L);
+        when(resultSet.getTimestamp(1)).thenReturn(timestamp);
+        InputStream asciiStream = new ByteArrayInputStream(new byte[]{1});
+        when(resultSet.getAsciiStream(1)).thenReturn(asciiStream);
+        InputStream unicodeStream = new ByteArrayInputStream(new byte[]{2});
+        when(resultSet.getUnicodeStream(1)).thenReturn(unicodeStream);
+        InputStream binaryStream = new ByteArrayInputStream(new byte[]{3});
+        when(resultSet.getBinaryStream(1)).thenReturn(binaryStream);
+        when(resultSet.getObject(1)).thenReturn("object");
+        Reader characterReader = new StringReader("char");
+        when(resultSet.getCharacterStream(1)).thenReturn(characterReader);
+
+        // 未拦截状态下，所有值原样返回
+        assertEquals("value", proxy.getString(1));
+        assertEquals(true, proxy.getBoolean(1));
+        assertEquals((byte) 1, proxy.getByte(1));
+        assertEquals((short) 2, proxy.getShort(1));
+        assertEquals(3, proxy.getInt(1));
+        assertEquals(4L, proxy.getLong(1));
+        assertEquals(5.0f, proxy.getFloat(1));
+        assertEquals(6.0d, proxy.getDouble(1));
+        assertEquals(BigDecimal.ONE, proxy.getBigDecimal(1));
+        assertEquals(BigDecimal.TEN, proxy.getBigDecimal(1, 2));
+        assertSame(date, proxy.getDate(1));
+        assertSame(time, proxy.getTime(1));
+        assertSame(timestamp, proxy.getTimestamp(1));
+        assertSame(asciiStream, proxy.getAsciiStream(1));
+        assertSame(unicodeStream, proxy.getUnicodeStream(1));
+        assertSame(binaryStream, proxy.getBinaryStream(1));
+        assertEquals("object", proxy.getObject(1));
+        assertSame(characterReader, proxy.getCharacterStream(1));
+
+        verify(resultSet).getString(1);
+        verify(resultSet).getInt(1);
+    }
+
+    @Test
+    void testGettersByColumnLabelDelegate() throws SQLException {
+        when(resultSet.getString(1)).thenReturn("value");
+        when(resultSet.getBoolean(1)).thenReturn(true);
+        when(resultSet.getByte(1)).thenReturn((byte) 1);
+        when(resultSet.getShort(1)).thenReturn((short) 2);
+        when(resultSet.getInt(1)).thenReturn(3);
+        when(resultSet.getLong(1)).thenReturn(4L);
+        when(resultSet.getFloat(1)).thenReturn(5.0f);
+        when(resultSet.getDouble(1)).thenReturn(6.0d);
+        when(resultSet.getBigDecimal(1)).thenReturn(BigDecimal.ONE);
+        when(resultSet.getBigDecimal(1, 2)).thenReturn(BigDecimal.TEN);
+        when(resultSet.getBytes(1)).thenReturn(new byte[]{1});
+        Date date = new Date(1000L);
+        when(resultSet.getDate(1)).thenReturn(date);
+        Time time = new Time(2000L);
+        when(resultSet.getTime(1)).thenReturn(time);
+        Timestamp timestamp = new Timestamp(3000L);
+        when(resultSet.getTimestamp(1)).thenReturn(timestamp);
+        InputStream asciiStream = new ByteArrayInputStream(new byte[]{1});
+        when(resultSet.getAsciiStream(1)).thenReturn(asciiStream);
+        InputStream unicodeStream = new ByteArrayInputStream(new byte[]{2});
+        when(resultSet.getUnicodeStream(1)).thenReturn(unicodeStream);
+        InputStream binaryStream = new ByteArrayInputStream(new byte[]{3});
+        when(resultSet.getBinaryStream(1)).thenReturn(binaryStream);
+        when(resultSet.getObject(1)).thenReturn("object");
+        Reader characterReader = new StringReader("char");
+        when(resultSet.getCharacterStream(1)).thenReturn(characterReader);
+
+        // 通过列标签访问，内部根据 columnLabelMap 转换为索引 1
+        assertEquals("value", proxy.getString("name"));
+        assertEquals("value", proxy.getString("NAME"));
+        assertEquals(true, proxy.getBoolean("name"));
+        assertEquals((byte) 1, proxy.getByte("name"));
+        assertEquals((short) 2, proxy.getShort("name"));
+        assertEquals(3, proxy.getInt("name"));
+        assertEquals(4L, proxy.getLong("name"));
+        assertEquals(5.0f, proxy.getFloat("name"));
+        assertEquals(6.0d, proxy.getDouble("name"));
+        assertEquals(BigDecimal.ONE, proxy.getBigDecimal("name"));
+        assertEquals(BigDecimal.TEN, proxy.getBigDecimal("name", 2));
+        assertSame(date, proxy.getDate("name"));
+        assertSame(time, proxy.getTime("name"));
+        assertSame(timestamp, proxy.getTimestamp("name"));
+        assertSame(asciiStream, proxy.getAsciiStream("name"));
+        assertSame(unicodeStream, proxy.getUnicodeStream("name"));
+        assertSame(binaryStream, proxy.getBinaryStream("name"));
+        assertEquals("object", proxy.getObject("name"));
+        assertSame(characterReader, proxy.getCharacterStream("name"));
+    }
+
+    @Test
+    void testColumnAuthorizationWithInterceptState() throws SQLException {
+        // 使用真实拦截流程构造拦截状态：select name from t_user 会被注入 t_user.id > 100
+        SQLExecuteState interceptState = SQLRunningContext.getInstance().intercept("select name from t_user");
+        assertTrue(interceptState.hasIntercept());
+        ResultSetProxy interceptProxy = new ResultSetProxy(resultSet, interceptState);
+
+        when(resultSet.getString(1)).thenReturn("raw");
+        // 列权限过滤器生效，t_user.name 的值被加工
+        assertEquals("MASKED-raw", interceptProxy.getString(1));
+        assertEquals("MASKED-raw", interceptProxy.getString("name"));
+
+        when(resultSet.getNString(1)).thenReturn("nraw");
+        assertEquals("MASKED-nraw", interceptProxy.getNString(1));
+        assertEquals("MASKED-nraw", interceptProxy.getNString("name"));
+
+        when(resultSet.getObject(1)).thenReturn("oraw");
+        assertEquals("MASKED-oraw", interceptProxy.getObject(1));
+        assertEquals("MASKED-oraw", interceptProxy.getObject("name"));
+    }
+
+    @Test
+    void testSimpleDelegates() throws SQLException {
+        SQLWarning warning = mock(SQLWarning.class);
+        when(resultSet.getWarnings()).thenReturn(warning);
+        when(resultSet.getCursorName()).thenReturn("cursor");
+        when(resultSet.findColumn("name")).thenReturn(1);
+        Statement statement = mock(Statement.class);
+        when(resultSet.getStatement()).thenReturn(statement);
+
+        assertSame(warning, proxy.getWarnings());
+        proxy.clearWarnings();
+        verify(resultSet).clearWarnings();
+        assertEquals("cursor", proxy.getCursorName());
+        assertSame(metaData, proxy.getMetaData());
+        assertEquals(1, proxy.findColumn("name"));
+        assertSame(statement, proxy.getStatement());
+    }
+
+    @Test
+    void testObjectAndLobGettersByIndex() throws SQLException {
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        Date date = new Date(1000L);
+
+        when(resultSet.getRef(1)).thenReturn(ref);
+        when(resultSet.getBlob(1)).thenReturn(blob);
+        when(resultSet.getClob(1)).thenReturn(clob);
+        when(resultSet.getArray(1)).thenReturn(array);
+        when(resultSet.getNClob(1)).thenReturn(nClob);
+        when(resultSet.getSQLXML(1)).thenReturn(sqlxml);
+        when(resultSet.getRowId(1)).thenReturn(rowId);
+        when(resultSet.getURL(1)).thenReturn(url);
+        when(resultSet.getDate(1)).thenReturn(date);
+        when(resultSet.getObject(1)).thenReturn("obj");
+        when(resultSet.getObject(1, String.class)).thenReturn("typed");
+
+        Map<String, Class<?>> map = new HashMap<>();
+        // 注意：getObject(int, Map) 当前实现内部调用的是 resultSet.getDate(columnIndex)
+        // 此处断言的是当前（有缺陷的）行为，详见测试报告
+        assertSame(date, proxy.getObject(1, map));
+        assertSame(ref, proxy.getRef(1));
+        assertSame(blob, proxy.getBlob(1));
+        assertSame(clob, proxy.getClob(1));
+        assertSame(array, proxy.getArray(1));
+        assertSame(nClob, proxy.getNClob(1));
+        assertSame(sqlxml, proxy.getSQLXML(1));
+        assertSame(rowId, proxy.getRowId(1));
+        assertSame(url, proxy.getURL(1));
+        assertEquals("typed", proxy.getObject(1, String.class));
+    }
+
+    @Test
+    void testObjectAndLobGettersByLabel() throws SQLException {
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+        RowId rowId = mock(RowId.class);
+        URL url = mock(URL.class);
+        Date date = new Date(1000L);
+
+        when(resultSet.getRef(1)).thenReturn(ref);
+        when(resultSet.getBlob(1)).thenReturn(blob);
+        when(resultSet.getClob(1)).thenReturn(clob);
+        when(resultSet.getArray(1)).thenReturn(array);
+        when(resultSet.getNClob(1)).thenReturn(nClob);
+        when(resultSet.getSQLXML(1)).thenReturn(sqlxml);
+        when(resultSet.getRowId(1)).thenReturn(rowId);
+        when(resultSet.getURL(1)).thenReturn(url);
+        when(resultSet.getDate(1)).thenReturn(date);
+        when(resultSet.getObject(1)).thenReturn("obj");
+        when(resultSet.getObject(1, String.class)).thenReturn("typed");
+
+        Map<String, Class<?>> map = new HashMap<>();
+        // getObject(String, Map) 内部调用的是 getObject(columnIndex)，忽略了 map 参数
+        assertEquals("obj", proxy.getObject("name", map));
+        assertSame(ref, proxy.getRef("name"));
+        assertSame(blob, proxy.getBlob("name"));
+        assertSame(clob, proxy.getClob("name"));
+        assertSame(array, proxy.getArray("name"));
+        assertSame(nClob, proxy.getNClob("name"));
+        assertSame(sqlxml, proxy.getSQLXML("name"));
+        assertSame(rowId, proxy.getRowId("name"));
+        assertSame(url, proxy.getURL("name"));
+        assertEquals("typed", proxy.getObject("name", String.class));
+    }
+
+    @Test
+    void testCalendarGetters() throws SQLException {
+        Calendar calendar = Calendar.getInstance();
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+
+        when(resultSet.getDate(1, calendar)).thenReturn(date);
+        when(resultSet.getTime(1, calendar)).thenReturn(time);
+        when(resultSet.getTimestamp(1, calendar)).thenReturn(timestamp);
+
+        assertSame(date, proxy.getDate(1, calendar));
+        assertSame(date, proxy.getDate("name", calendar));
+        assertSame(time, proxy.getTime(1, calendar));
+        assertSame(time, proxy.getTime("name", calendar));
+        assertSame(timestamp, proxy.getTimestamp(1, calendar));
+        assertSame(timestamp, proxy.getTimestamp("name", calendar));
+    }
+
+    @Test
+    void testNCharacterStreamGetters() throws SQLException {
+        Reader reader = new StringReader("nchar");
+        when(resultSet.getNCharacterStream(1)).thenReturn(reader);
+        assertSame(reader, proxy.getNCharacterStream(1));
+        assertSame(reader, proxy.getNCharacterStream("name"));
+    }
+
+    @Test
+    void testUpdateMethodsByIndex() throws SQLException {
+        InputStream inputStream = new ByteArrayInputStream(new byte[]{1});
+        Reader reader = new StringReader("x");
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        RowId rowId = mock(RowId.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+
+        proxy.updateNull(1);
+        proxy.updateBoolean(1, true);
+        proxy.updateByte(1, (byte) 1);
+        proxy.updateShort(1, (short) 1);
+        proxy.updateInt(1, 1);
+        proxy.updateLong(1, 1L);
+        proxy.updateFloat(1, 1.0f);
+        proxy.updateDouble(1, 1.0d);
+        proxy.updateBigDecimal(1, BigDecimal.ONE);
+        proxy.updateString(1, "x");
+        proxy.updateBytes(1, new byte[]{1});
+        proxy.updateDate(1, date);
+        proxy.updateTime(1, time);
+        proxy.updateTimestamp(1, timestamp);
+        proxy.updateAsciiStream(1, inputStream, 1);
+        proxy.updateBinaryStream(1, inputStream, 1);
+        proxy.updateCharacterStream(1, reader, 1);
+        proxy.updateObject(1, "x", 1);
+        proxy.updateObject(1, "x");
+        proxy.updateRef(1, ref);
+        proxy.updateBlob(1, blob);
+        proxy.updateClob(1, clob);
+        proxy.updateArray(1, array);
+        proxy.updateRowId(1, rowId);
+        proxy.updateNString(1, "x");
+        proxy.updateNClob(1, nClob);
+        proxy.updateSQLXML(1, sqlxml);
+        proxy.updateNCharacterStream(1, reader, 1L);
+        proxy.updateAsciiStream(1, inputStream, 1L);
+        proxy.updateBinaryStream(1, inputStream, 1L);
+        proxy.updateCharacterStream(1, reader, 1L);
+        proxy.updateBlob(1, inputStream, 1L);
+        proxy.updateClob(1, reader, 1L);
+        proxy.updateNClob(1, reader, 1L);
+        proxy.updateNCharacterStream(1, reader);
+        proxy.updateAsciiStream(1, inputStream);
+        proxy.updateBinaryStream(1, inputStream);
+        proxy.updateCharacterStream(1, reader);
+        proxy.updateBlob(1, inputStream);
+        proxy.updateClob(1, reader);
+        proxy.updateNClob(1, reader);
+        proxy.updateObject(1, "x", java.sql.JDBCType.VARCHAR, 1);
+        proxy.updateObject(1, "x", java.sql.JDBCType.VARCHAR);
+
+        verify(resultSet).updateNull(1);
+        verify(resultSet).updateBoolean(1, true);
+        verify(resultSet).updateByte(1, (byte) 1);
+        verify(resultSet).updateShort(1, (short) 1);
+        verify(resultSet).updateInt(1, 1);
+        verify(resultSet).updateLong(1, 1L);
+        verify(resultSet).updateFloat(1, 1.0f);
+        verify(resultSet).updateDouble(1, 1.0d);
+        verify(resultSet).updateBigDecimal(1, BigDecimal.ONE);
+        verify(resultSet).updateString(1, "x");
+        verify(resultSet).updateDate(1, date);
+        verify(resultSet).updateTime(1, time);
+        verify(resultSet).updateTimestamp(1, timestamp);
+        verify(resultSet).updateAsciiStream(1, inputStream, 1);
+        verify(resultSet).updateBinaryStream(1, inputStream, 1);
+        verify(resultSet).updateCharacterStream(1, reader, 1);
+        verify(resultSet).updateObject(1, "x", 1);
+        verify(resultSet).updateObject(1, "x");
+        verify(resultSet).updateRef(1, ref);
+        verify(resultSet).updateBlob(1, blob);
+        verify(resultSet).updateClob(1, clob);
+        verify(resultSet).updateArray(1, array);
+        verify(resultSet).updateRowId(1, rowId);
+        verify(resultSet).updateNString(1, "x");
+        verify(resultSet).updateNClob(1, nClob);
+        verify(resultSet).updateSQLXML(1, sqlxml);
+        verify(resultSet).updateNCharacterStream(1, reader, 1L);
+        verify(resultSet).updateAsciiStream(1, inputStream, 1L);
+        verify(resultSet).updateBinaryStream(1, inputStream, 1L);
+        verify(resultSet).updateCharacterStream(1, reader, 1L);
+        verify(resultSet).updateBlob(1, inputStream, 1L);
+        verify(resultSet).updateClob(1, reader, 1L);
+        verify(resultSet).updateNClob(1, reader, 1L);
+        verify(resultSet).updateNCharacterStream(1, reader);
+        verify(resultSet).updateAsciiStream(1, inputStream);
+        verify(resultSet).updateBinaryStream(1, inputStream);
+        verify(resultSet).updateCharacterStream(1, reader);
+        verify(resultSet).updateBlob(1, inputStream);
+        verify(resultSet).updateClob(1, reader);
+        verify(resultSet).updateNClob(1, reader);
+        verify(resultSet).updateObject(1, "x", java.sql.JDBCType.VARCHAR, 1);
+        verify(resultSet).updateObject(1, "x", java.sql.JDBCType.VARCHAR);
+    }
+
+    @Test
+    void testUpdateMethodsByLabel() throws SQLException {
+        InputStream inputStream = new ByteArrayInputStream(new byte[]{1});
+        Reader reader = new StringReader("x");
+        Date date = new Date(1000L);
+        Time time = new Time(2000L);
+        Timestamp timestamp = new Timestamp(3000L);
+        Ref ref = mock(Ref.class);
+        Blob blob = mock(Blob.class);
+        Clob clob = mock(Clob.class);
+        Array array = mock(Array.class);
+        RowId rowId = mock(RowId.class);
+        NClob nClob = mock(NClob.class);
+        SQLXML sqlxml = mock(SQLXML.class);
+
+        proxy.updateNull("name");
+        proxy.updateBoolean("name", true);
+        proxy.updateByte("name", (byte) 1);
+        proxy.updateShort("name", (short) 1);
+        proxy.updateInt("name", 1);
+        proxy.updateLong("name", 1L);
+        proxy.updateFloat("name", 1.0f);
+        proxy.updateDouble("name", 1.0d);
+        proxy.updateBigDecimal("name", BigDecimal.ONE);
+        proxy.updateString("name", "x");
+        proxy.updateBytes("name", new byte[]{1});
+        proxy.updateDate("name", date);
+        proxy.updateTime("name", time);
+        proxy.updateTimestamp("name", timestamp);
+        proxy.updateAsciiStream("name", inputStream, 1);
+        proxy.updateBinaryStream("name", inputStream, 1);
+        proxy.updateCharacterStream("name", reader, 1);
+        proxy.updateObject("name", "x", 1);
+        proxy.updateObject("name", "x");
+        proxy.updateRef("name", ref);
+        proxy.updateBlob("name", blob);
+        proxy.updateClob("name", clob);
+        proxy.updateArray("name", array);
+        proxy.updateRowId("name", rowId);
+        proxy.updateNString("name", "x");
+        proxy.updateNClob("name", nClob);
+        proxy.updateSQLXML("name", sqlxml);
+        proxy.updateNCharacterStream("name", reader, 1L);
+        proxy.updateAsciiStream("name", inputStream, 1L);
+        proxy.updateBinaryStream("name", inputStream, 1L);
+        proxy.updateCharacterStream("name", reader, 1L);
+        proxy.updateBlob("name", inputStream, 1L);
+        proxy.updateClob("name", reader, 1L);
+        proxy.updateNClob("name", reader, 1L);
+        proxy.updateNCharacterStream("name", reader);
+        proxy.updateAsciiStream("name", inputStream);
+        proxy.updateBinaryStream("name", inputStream);
+        proxy.updateCharacterStream("name", reader);
+        proxy.updateBlob("name", inputStream);
+        proxy.updateClob("name", reader);
+        proxy.updateNClob("name", reader);
+        proxy.updateObject("name", "x", java.sql.JDBCType.VARCHAR, 1);
+        proxy.updateObject("name", "x", java.sql.JDBCType.VARCHAR);
+
+        verify(resultSet).updateNull("name");
+        verify(resultSet).updateBoolean("name", true);
+        verify(resultSet).updateString("name", "x");
+        verify(resultSet).updateDate("name", date);
+        verify(resultSet).updateTime("name", time);
+        verify(resultSet).updateTimestamp("name", timestamp);
+        verify(resultSet).updateRef("name", ref);
+        verify(resultSet).updateBlob("name", blob);
+        verify(resultSet).updateClob("name", clob);
+        verify(resultSet).updateArray("name", array);
+        verify(resultSet).updateRowId("name", rowId);
+        verify(resultSet).updateNString("name", "x");
+        verify(resultSet).updateNClob("name", nClob);
+        verify(resultSet).updateSQLXML("name", sqlxml);
+        verify(resultSet).updateObject("name", "x", java.sql.JDBCType.VARCHAR, 1);
+        verify(resultSet).updateObject("name", "x", java.sql.JDBCType.VARCHAR);
+    }
+
+    @Test
+    void testRowManipulationDelegates() throws SQLException {
+        proxy.insertRow();
+        proxy.updateRow();
+        proxy.deleteRow();
+        proxy.refreshRow();
+        proxy.cancelRowUpdates();
+        proxy.moveToInsertRow();
+        proxy.moveToCurrentRow();
+
+        verify(resultSet).insertRow();
+        verify(resultSet).updateRow();
+        verify(resultSet).deleteRow();
+        verify(resultSet).refreshRow();
+        verify(resultSet).cancelRowUpdates();
+        verify(resultSet).moveToInsertRow();
+        verify(resultSet).moveToCurrentRow();
+    }
+
+    @Test
+    void testWrapperDelegates() throws SQLException {
+        when(resultSet.unwrap(String.class)).thenReturn("unwrapped");
+        when(resultSet.isWrapperFor(String.class)).thenReturn(true);
+
+        assertEquals("unwrapped", proxy.unwrap(String.class));
+        assertTrue(proxy.isWrapperFor(String.class));
+    }
+
+    @Test
+    void testGetStringWithUnrelatedColumnNotMasked() throws SQLException {
+        // 拦截状态下，非受管列（columnName 非 name）不触发列权限，值原样返回
+        SQLExecuteState interceptState = SQLRunningContext.getInstance().intercept("select name from t_user");
+        when(metaData.getColumnName(1)).thenReturn("other_column");
+        when(resultSet.getString(1)).thenReturn("plain");
+        ResultSetProxy interceptProxy = new ResultSetProxy(resultSet, interceptState);
+        assertEquals("plain", interceptProxy.getString(1));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/StatementProxyTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/StatementProxyTest.java
new file mode 100644
index 000000000..aa1fafab3
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/jdbc/proxy/StatementProxyTest.java
@@ -0,0 +1,246 @@
+package com.codingapi.springboot.authorization.jdbc.proxy;
+
+import com.codingapi.springboot.authorization.DataAuthorizationContext;
+import com.codingapi.springboot.authorization.interceptor.SQLExecuteState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.SQLException;
+import java.sql.SQLWarning;
+import java.sql.Statement;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * StatementProxy 单元测试
+ * 验证方法委托以及 SQL 拦截行为
+ */
+class StatementProxyTest {
+
+    private Statement statement;
+    private StatementProxy proxy;
+
+    @BeforeEach
+    void setUp() throws SQLException {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+        ResultSetProxyTest.registerTestFilter();
+
+        statement = mock(Statement.class);
+        proxy = new StatementProxy(statement, SQLExecuteState.unIntercept("select 1"));
+    }
+
+    @AfterEach
+    void tearDown() {
+        DataAuthorizationContext.getInstance().clearDataAuthorizationFilters();
+    }
+
+    private ResultSet mockEmptyResultSet() throws SQLException {
+        ResultSet resultSet = mock(ResultSet.class);
+        ResultSetMetaData metaData = mock(ResultSetMetaData.class);
+        when(resultSet.getMetaData()).thenReturn(metaData);
+        when(metaData.getColumnCount()).thenReturn(0);
+        return resultSet;
+    }
+
+    @Test
+    void testExecuteQueryInterceptsSql() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(statement.executeQuery(anyString())).thenReturn(resultSet);
+
+        ResultSet result = proxy.executeQuery("select name from t_user");
+
+        assertTrue(result instanceof ResultSetProxy);
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(statement).executeQuery(captor.capture());
+        // SQL 被注入了行权限条件
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testExecuteQueryWithoutInterception() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        when(statement.executeQuery(anyString())).thenReturn(resultSet);
+
+        // t_other 表未配置权限条件, 不会注入过滤条件; 但 SQL 仍会经 JSqlParser 解析并重新序列化(大小写可能变化)
+        proxy.executeQuery("select name from t_other");
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(statement).executeQuery(captor.capture());
+        assertEquals("SELECT name FROM t_other", captor.getValue());
+    }
+
+    @Test
+    void testExecuteUpdateVariantsInterceptSql() throws SQLException {
+        when(statement.executeUpdate(anyString())).thenReturn(1);
+        when(statement.executeUpdate(anyString(), anyInt())).thenReturn(2);
+        when(statement.executeUpdate(anyString(), (int[]) org.mockito.ArgumentMatchers.any())).thenReturn(3);
+        when(statement.executeUpdate(anyString(), (String[]) org.mockito.ArgumentMatchers.any())).thenReturn(4);
+        when(statement.executeLargeUpdate(anyString())).thenReturn(5L);
+        when(statement.executeLargeUpdate(anyString(), anyInt())).thenReturn(6L);
+        when(statement.executeLargeUpdate(anyString(), (int[]) org.mockito.ArgumentMatchers.any())).thenReturn(7L);
+        when(statement.executeLargeUpdate(anyString(), (String[]) org.mockito.ArgumentMatchers.any())).thenReturn(8L);
+
+        String sql = "select name from t_user";
+        assertEquals(1, proxy.executeUpdate(sql));
+        assertEquals(2, proxy.executeUpdate(sql, Statement.RETURN_GENERATED_KEYS));
+        assertEquals(3, proxy.executeUpdate(sql, new int[]{1}));
+        assertEquals(4, proxy.executeUpdate(sql, new String[]{"id"}));
+        assertEquals(5L, proxy.executeLargeUpdate(sql));
+        assertEquals(6L, proxy.executeLargeUpdate(sql, Statement.RETURN_GENERATED_KEYS));
+        assertEquals(7L, proxy.executeLargeUpdate(sql, new int[]{1}));
+        assertEquals(8L, proxy.executeLargeUpdate(sql, new String[]{"id"}));
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(statement).executeUpdate(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testExecuteVariantsInterceptSql() throws SQLException {
+        when(statement.execute(anyString())).thenReturn(true);
+        when(statement.execute(anyString(), anyInt())).thenReturn(true);
+        when(statement.execute(anyString(), (int[]) org.mockito.ArgumentMatchers.any())).thenReturn(true);
+        when(statement.execute(anyString(), (String[]) org.mockito.ArgumentMatchers.any())).thenReturn(true);
+
+        String sql = "select name from t_user";
+        assertTrue(proxy.execute(sql));
+        assertTrue(proxy.execute(sql, Statement.RETURN_GENERATED_KEYS));
+        assertTrue(proxy.execute(sql, new int[]{1}));
+        assertTrue(proxy.execute(sql, new String[]{"id"}));
+
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(statement).execute(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testAddBatchInterceptsSql() throws SQLException {
+        proxy.addBatch("select name from t_user");
+        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+        verify(statement).addBatch(captor.capture());
+        assertTrue(captor.getValue().contains("id > 100"));
+    }
+
+    @Test
+    void testResultSetWrapping() throws SQLException {
+        ResultSet resultSet = mockEmptyResultSet();
+        ResultSet generatedKeys = mockEmptyResultSet();
+        when(statement.getResultSet()).thenReturn(resultSet);
+        when(statement.getGeneratedKeys()).thenReturn(generatedKeys);
+
+        assertTrue(proxy.getResultSet() instanceof ResultSetProxy);
+        assertTrue(proxy.getGeneratedKeys() instanceof ResultSetProxy);
+        verify(statement).getResultSet();
+        verify(statement).getGeneratedKeys();
+    }
+
+    @Test
+    void testGetConnectionReturnsConnectionProxy() throws SQLException {
+        Connection connection = mock(Connection.class);
+        when(statement.getConnection()).thenReturn(connection);
+        assertTrue(proxy.getConnection() instanceof ConnectionProxy);
+    }
+
+    @Test
+    void testAttributeDelegates() throws SQLException {
+        when(statement.getMaxFieldSize()).thenReturn(1);
+        when(statement.getMaxRows()).thenReturn(2);
+        when(statement.getQueryTimeout()).thenReturn(3);
+        SQLWarning warning = mock(SQLWarning.class);
+        when(statement.getWarnings()).thenReturn(warning);
+        when(statement.getUpdateCount()).thenReturn(4);
+        when(statement.getMoreResults()).thenReturn(true);
+        when(statement.getFetchDirection()).thenReturn(ResultSet.FETCH_FORWARD);
+        when(statement.getFetchSize()).thenReturn(5);
+        when(statement.getResultSetConcurrency()).thenReturn(ResultSet.CONCUR_READ_ONLY);
+        when(statement.getResultSetType()).thenReturn(ResultSet.TYPE_FORWARD_ONLY);
+        when(statement.getMoreResults(Statement.CLOSE_CURRENT_RESULT)).thenReturn(false);
+        when(statement.getResultSetHoldability()).thenReturn(ResultSet.HOLD_CURSORS_OVER_COMMIT);
+        when(statement.isClosed()).thenReturn(false);
+        when(statement.isPoolable()).thenReturn(true);
+        when(statement.isCloseOnCompletion()).thenReturn(false);
+        when(statement.getLargeUpdateCount()).thenReturn(6L);
+        when(statement.getLargeMaxRows()).thenReturn(7L);
+        when(statement.executeBatch()).thenReturn(new int[]{1, 2});
+        when(statement.executeLargeBatch()).thenReturn(new long[]{3L, 4L});
+
+        assertEquals(1, proxy.getMaxFieldSize());
+        assertEquals(2, proxy.getMaxRows());
+        assertEquals(3, proxy.getQueryTimeout());
+        assertSame(warning, proxy.getWarnings());
+        assertEquals(4, proxy.getUpdateCount());
+        assertTrue(proxy.getMoreResults());
+        assertEquals(ResultSet.FETCH_FORWARD, proxy.getFetchDirection());
+        assertEquals(5, proxy.getFetchSize());
+        assertEquals(ResultSet.CONCUR_READ_ONLY, proxy.getResultSetConcurrency());
+        assertEquals(ResultSet.TYPE_FORWARD_ONLY, proxy.getResultSetType());
+        assertEquals(false, proxy.getMoreResults(Statement.CLOSE_CURRENT_RESULT));
+        assertEquals(ResultSet.HOLD_CURSORS_OVER_COMMIT, proxy.getResultSetHoldability());
+        assertEquals(false, proxy.isClosed());
+        assertTrue(proxy.isPoolable());
+        assertEquals(false, proxy.isCloseOnCompletion());
+        assertEquals(6L, proxy.getLargeUpdateCount());
+        assertEquals(7L, proxy.getLargeMaxRows());
+        assertEquals(2, proxy.executeBatch().length);
+        assertEquals(2, proxy.executeLargeBatch().length);
+
+        proxy.setMaxFieldSize(10);
+        proxy.setMaxRows(20);
+        proxy.setEscapeProcessing(true);
+        proxy.setQueryTimeout(30);
+        proxy.setFetchDirection(ResultSet.FETCH_REVERSE);
+        proxy.setFetchSize(40);
+        proxy.setPoolable(false);
+        proxy.setLargeMaxRows(50L);
+        proxy.clearWarnings();
+        proxy.clearBatch();
+        proxy.closeOnCompletion();
+        proxy.close();
+        proxy.cancel();
+        proxy.setCursorName("cursor");
+
+        verify(statement).setMaxFieldSize(10);
+        verify(statement).setMaxRows(20);
+        verify(statement).setEscapeProcessing(true);
+        verify(statement).setQueryTimeout(30);
+        verify(statement).setFetchDirection(ResultSet.FETCH_REVERSE);
+        verify(statement).setFetchSize(40);
+        verify(statement).setPoolable(false);
+        verify(statement).setLargeMaxRows(50L);
+        verify(statement).clearWarnings();
+        verify(statement).clearBatch();
+        verify(statement).closeOnCompletion();
+        verify(statement).close();
+        verify(statement).cancel();
+        verify(statement).setCursorName("cursor");
+    }
+
+    @Test
+    void testEnquoteAndWrapperDelegates() throws SQLException {
+        when(statement.enquoteLiteral("v")).thenReturn("'v'");
+        when(statement.enquoteIdentifier("id", true)).thenReturn("\"id\"");
+        when(statement.isSimpleIdentifier("id")).thenReturn(true);
+        when(statement.enquoteNCharLiteral("v")).thenReturn("N'v'");
+        when(statement.unwrap(String.class)).thenReturn("unwrapped");
+        when(statement.isWrapperFor(String.class)).thenReturn(true);
+
+        assertEquals("'v'", proxy.enquoteLiteral("v"));
+        assertEquals("\"id\"", proxy.enquoteIdentifier("id", true));
+        assertTrue(proxy.isSimpleIdentifier("id"));
+        assertEquals("N'v'", proxy.enquoteNCharLiteral("v"));
+        assertEquals("unwrapped", proxy.unwrap(String.class));
+        assertTrue(proxy.isWrapperFor(String.class));
+    }
+}
diff --git a/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/utils/SQLUtilsTest.java b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/utils/SQLUtilsTest.java
new file mode 100644
index 000000000..2b8531c75
--- /dev/null
+++ b/springboot-starter-data-authorization/src/test/java/com/codingapi/springboot/authorization/utils/SQLUtilsTest.java
@@ -0,0 +1,37 @@
+package com.codingapi.springboot.authorization.utils;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * SQLUtils 单元测试
+ */
+class SQLUtilsTest {
+
+    @Test
+    void testIsQuerySqlWithSelect() {
+        assertTrue(SQLUtils.isQuerySql("select * from t_user"));
+        assertTrue(SQLUtils.isQuerySql("SELECT id, name FROM t_user WHERE id = 1"));
+    }
+
+    @Test
+    void testIsQuerySqlWithNonSelect() {
+        assertFalse(SQLUtils.isQuerySql("update t_user set name = 'x'"));
+        assertFalse(SQLUtils.isQuerySql("delete from t_user"));
+        assertFalse(SQLUtils.isQuerySql("insert into t_user(name) values('x')"));
+    }
+
+    @Test
+    void testIsQuerySqlWithNullOrBlank() {
+        assertFalse(SQLUtils.isQuerySql(null));
+        assertFalse(SQLUtils.isQuerySql(""));
+        assertFalse(SQLUtils.isQuerySql("   "));
+    }
+
+    @Test
+    void testIsQuerySqlWithInvalidSql() {
+        assertFalse(SQLUtils.isQuerySql("this is not a sql"));
+    }
+}
diff --git a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jdbc/JdbcQuery.java b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jdbc/JdbcQuery.java
index b28743d40..8c05221da 100644
--- a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jdbc/JdbcQuery.java
+++ b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jdbc/JdbcQuery.java
@@ -32,7 +32,8 @@ public Map<String, Object> mapRow(ResultSet rs, int rowNum) throws SQLException
             Map<String, Object> map = new HashMap<>(columnCount);
             for (int i = 1; i <= columnCount; i++) {
                 String columnName = metaData.getColumnLabel(i);
-                map.put(CaseUtils.toCamelCase(columnName, false), rs.getObject(i));
+                // 修复：必须显式指定下划线分隔符，否则 CaseUtils 不做任何驼峰转换
+                map.put(CaseUtils.toCamelCase(columnName, false, '_'), rs.getObject(i));
             }
             return map;
         }
@@ -86,12 +87,16 @@ public Page<Map<String, Object>> queryForMapPage(String sql, PageRequest pageReq
 
 
     private long countQuery(String sql, Object... params) {
-        int paramsLength = params.length;
-        int countSqlParamsLength = sql.split("\\?").length - 1;
-        Object[] newParams = new Object[countSqlParamsLength];
-        if (paramsLength > countSqlParamsLength) {
-            System.arraycopy(params, 0, newParams, 0, countSqlParamsLength);
+        int countSqlParamsLength = sql.split("\\?", -1).length - 1;
+        Long count;
+        if (countSqlParamsLength <= 0) {
+            count = jdbcTemplate.queryForObject(sql, Long.class);
+        } else {
+            Object[] newParams = new Object[countSqlParamsLength];
+            // 修复：原实现仅在 params 数量大于占位符数量时才拷贝，数量相等时参数全部丢失导致 SQL 参数未绑定
+            System.arraycopy(params, 0, newParams, 0, Math.min(params.length, countSqlParamsLength));
+            count = jdbcTemplate.queryForObject(sql, Long.class, newParams);
         }
-        return jdbcTemplate.queryForObject(sql, Long.class, newParams);
+        return count == null ? 0L : count;
     }
 }
diff --git a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilder.java b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilder.java
index cc496f48a..7e159a840 100644
--- a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilder.java
+++ b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilder.java
@@ -44,13 +44,16 @@ private void build() {
         RequestFilter requestFilter = request.getRequestFilter();
         if (requestFilter.hasFilter()) {
             List<Filter> filters = requestFilter.getFilters();
-            for (int i = 0; i < filters.size(); i++) {
-                Filter filter = filters.get(i);
-                this.buildSQL(filter, querySQL);
-                if (i != filters.size() - 1) {
-                    querySQL.append(" AND ");
+            // 逐条构建后过滤空片段（如空的 OR/AND 组合），避免拼出 "WHERE  AND " 这类非法 HQL
+            List<String> segments = new ArrayList<>();
+            for (Filter filter : filters) {
+                StringBuilder segmentSQL = new StringBuilder();
+                this.buildSQL(filter, segmentSQL);
+                if (segmentSQL.length() > 0) {
+                    segments.add(segmentSQL.toString());
                 }
             }
+            querySQL.append(String.join(" AND ", segments));
         }
 
         Sort sort = request.getSort();
diff --git a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilder.java b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilder.java
index 6b72dec31..743f23139 100644
--- a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilder.java
+++ b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilder.java
@@ -36,10 +36,12 @@ public <T> Example<T> getExample() {
         for (PropertyDescriptor descriptor : descriptors) {
             String name = descriptor.getName();
             Filter value = requestFilter.getFilter(name);
-            if (value != null) {
+            if (value != null && descriptor.getWriteMethod() != null) {
                 try {
                     descriptor.getWriteMethod().invoke(entity, value.getFilterValue(descriptor.getPropertyType()));
                 } catch (Exception e) {
+                    // 不再静默吞掉异常：过滤条件写入失败会导致查询结果错误，必须显式暴露
+                    throw new IllegalStateException("Build Example filter failed for property '" + name + "': " + e.getMessage(), e);
                 }
             }
         }
diff --git a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/FastRepository.java b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/FastRepository.java
index e56218dbc..6d0057566 100644
--- a/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/FastRepository.java
+++ b/springboot-starter-data-fast/src/main/java/com/codingapi/springboot/fast/jpa/repository/FastRepository.java
@@ -18,9 +18,14 @@ public interface FastRepository<T, ID> extends JpaRepository<T, ID>, JpaSpecific
 
     default Page<T> findAll(PageRequest request) {
         if (request.hasFilter()) {
-            Class<T> clazz = getEntityClass();
-            ExampleBuilder exampleBuilder = new ExampleBuilder(request, clazz);
-            return findAll(exampleBuilder.getExample(), request);
+            // 全部为简单等值条件时走 Example 查询；包含 LIKE/范围/IN/OR 等复杂条件时自动切换 HQL 动态查询，
+            // 避免非等值条件被 Example 静默降级为等值匹配
+            if (request.getRequestFilter().isAllEqualFilter()) {
+                Class<T> clazz = getEntityClass();
+                ExampleBuilder exampleBuilder = new ExampleBuilder(request, clazz);
+                return findAll(exampleBuilder.getExample(), request);
+            }
+            return pageRequest(request);
         }
         return findAll((org.springframework.data.domain.PageRequest) request);
     }
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/DemoRepositoryTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/DemoRepositoryTest.java
index 434d6c9c9..1b0a0dd29 100644
--- a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/DemoRepositoryTest.java
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/DemoRepositoryTest.java
@@ -57,6 +57,87 @@ void findAll() {
         assertEquals(1, page.getTotalElements());
     }
 
+    /**
+     * findAll 遇到 LIKE 等复杂条件时自动切换 HQL 查询，而非被 Example 降级为等值匹配
+     */
+    @Test
+    void findAllWithLikeFilterSwitchesToHql() {
+        demoRepository.deleteAll();
+        Demo demo1 = new Demo();
+        demo1.setName("123");
+        demoRepository.save(demo1);
+
+        Demo demo2 = new Demo();
+        demo2.setName("456");
+        demoRepository.save(demo2);
+
+        PageRequest request = new PageRequest();
+        request.setCurrent(0);
+        request.setPageSize(10);
+        request.addFilter("name", Relation.LIKE, "%2%");
+
+        Page<Demo> page = demoRepository.findAll(request);
+        assertEquals(1, page.getTotalElements());
+        assertEquals("123", page.getContent().get(0).getName());
+    }
+
+    /**
+     * findAll 遇到范围条件时自动切换 HQL 查询
+     */
+    @Test
+    void findAllWithGreaterThanFilterSwitchesToHql() {
+        demoRepository.deleteAll();
+        Demo demo1 = new Demo();
+        demo1.setName("a");
+        demo1.setSort(10);
+        demoRepository.save(demo1);
+
+        Demo demo2 = new Demo();
+        demo2.setName("b");
+        demo2.setSort(20);
+        demoRepository.save(demo2);
+
+        Demo demo3 = new Demo();
+        demo3.setName("c");
+        demo3.setSort(30);
+        demoRepository.save(demo3);
+
+        PageRequest request = new PageRequest();
+        request.setCurrent(0);
+        request.setPageSize(10);
+        request.addFilter("sort", Relation.GREATER_THAN, 15);
+
+        Page<Demo> page = demoRepository.findAll(request);
+        assertEquals(2, page.getTotalElements());
+    }
+
+    /**
+     * findAll 遇到 OR 组合条件时自动切换 HQL 查询
+     */
+    @Test
+    void findAllWithOrFiltersSwitchesToHql() {
+        demoRepository.deleteAll();
+        Demo demo1 = new Demo();
+        demo1.setName("123");
+        demoRepository.save(demo1);
+
+        Demo demo2 = new Demo();
+        demo2.setName("456");
+        demoRepository.save(demo2);
+
+        Demo demo3 = new Demo();
+        demo3.setName("789");
+        demoRepository.save(demo3);
+
+        PageRequest request = new PageRequest();
+        request.setCurrent(0);
+        request.setPageSize(10);
+        request.orFilters(Filter.as("name", "123"), Filter.as("name", "456"));
+
+        Page<Demo> page = demoRepository.findAll(request);
+        assertEquals(2, page.getTotalElements());
+    }
+
     @Test
     void pageRequestIsNull() {
         demoRepository.deleteAll();
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/UserRepositoryTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/UserRepositoryTest.java
index ce5ad0a62..698bd22d8 100644
--- a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/UserRepositoryTest.java
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/UserRepositoryTest.java
@@ -10,6 +10,8 @@
 import com.codingapi.springboot.fast.repository.UserRepository;
 import com.codingapi.springboot.framework.dto.request.PageRequest;
 import lombok.extern.slf4j.Slf4j;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
@@ -32,6 +34,27 @@ public class UserRepositoryTest {
     @Autowired
     private ProfileRepository profileRepository;
 
+    /**
+     * 测试数据与其他测试类共享同一个 H2 库（user→profile→demo 存在外键链），
+     * 必须按外键顺序清理，且前后都要清理，避免测试类执行顺序不同导致
+     * DemoRepositoryTest/JdbcQueryTest 的 deleteAll 触发外键约束冲突。
+     */
+    @BeforeEach
+    void cleanBefore() {
+        cleanAll();
+    }
+
+    @AfterEach
+    void cleanAfter() {
+        cleanAll();
+    }
+
+    private void cleanAll() {
+        userRepository.deleteAll();
+        profileRepository.deleteAll();
+        demoRepository.deleteAll();
+    }
+
 
     @Test
     void test1() {
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jdbc/JdbcQueryUnitTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jdbc/JdbcQueryUnitTest.java
new file mode 100644
index 000000000..3a1f17845
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jdbc/JdbcQueryUnitTest.java
@@ -0,0 +1,241 @@
+package com.codingapi.springboot.fast.jdbc;
+
+import com.codingapi.springboot.fast.jpa.SQLBuilder;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentMatchers;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.jdbc.core.BeanPropertyRowMapper;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.RowMapper;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+/**
+ * JdbcQuery 单元测试：基于独立的 H2 内存库，不依赖 Spring 上下文，
+ * 与其他测试类的数据完全隔离。
+ */
+class JdbcQueryUnitTest {
+
+    /**
+     * 查询结果行映射 Bean（列 user_name 映射到 userName）
+     */
+    public static class JqRow {
+        private Integer id;
+        private String userName;
+        private Integer sort;
+
+        public Integer getId() {
+            return id;
+        }
+
+        public void setId(Integer id) {
+            this.id = id;
+        }
+
+        public String getUserName() {
+            return userName;
+        }
+
+        public void setUserName(String userName) {
+            this.userName = userName;
+        }
+
+        public Integer getSort() {
+            return sort;
+        }
+
+        public void setSort(Integer sort) {
+            this.sort = sort;
+        }
+    }
+
+    private JdbcTemplate jdbcTemplate;
+    private JdbcQuery jdbcQuery;
+
+    @BeforeEach
+    void setUp() {
+        JdbcDataSource dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:jdbc_query_unit;DB_CLOSE_DELAY=-1");
+        jdbcTemplate = new JdbcTemplate(dataSource);
+        jdbcTemplate.execute("drop table if exists jq_demo");
+        jdbcTemplate.execute("create table jq_demo(id int primary key, user_name varchar(50), sort int)");
+        jdbcTemplate.update("insert into jq_demo(id, user_name, sort) values (?, ?, ?)", 1, "alice", 10);
+        jdbcTemplate.update("insert into jq_demo(id, user_name, sort) values (?, ?, ?)", 2, "bob", 20);
+        jdbcQuery = new JdbcQuery(jdbcTemplate);
+    }
+
+    /**
+     * Map 查询，验证下划线列名转驼峰
+     */
+    @Test
+    void queryForMapList() {
+        List<Map<String, Object>> list = jdbcQuery.queryForMapList("select * from jq_demo order by id");
+        assertEquals(2, list.size());
+        assertEquals("alice", list.get(0).get("userName"));
+        assertEquals("bob", list.get(1).get("userName"));
+        assertTrue(list.get(0).containsKey("id"));
+        assertTrue(list.get(0).containsKey("sort"));
+    }
+
+    @Test
+    void queryForMapListWithParams() {
+        List<Map<String, Object>> list = jdbcQuery.queryForMapList(
+                "select * from jq_demo where sort > ?", 15);
+        assertEquals(1, list.size());
+        assertEquals("bob", list.get(0).get("userName"));
+    }
+
+    @Test
+    void queryForMapListWithBuilder() {
+        SQLBuilder<Object> builder = new SQLBuilder<>(
+                "select * from jq_demo where 1=1", "select count(1) from jq_demo where 1=1");
+        builder.append("and id = ?", 1);
+        List<Map<String, Object>> list = jdbcQuery.queryForMapList(builder);
+        assertEquals(1, list.size());
+        assertEquals("alice", list.get(0).get("userName"));
+    }
+
+    /**
+     * Bean 查询
+     */
+    @Test
+    void queryForList() {
+        List<JqRow> list = jdbcQuery.queryForList(
+                "select * from jq_demo where id = ?", JqRow.class, 2);
+        assertEquals(1, list.size());
+        assertEquals("bob", list.get(0).getUserName());
+        assertEquals(Integer.valueOf(20), list.get(0).getSort());
+    }
+
+    @Test
+    void queryForListWithBuilder() {
+        SQLBuilder<JqRow> builder = new SQLBuilder<>(
+                JqRow.class, "select * from jq_demo where 1=1", "select count(1) from jq_demo where 1=1");
+        builder.append("and sort <= ?", 10);
+        List<JqRow> list = jdbcQuery.queryForList(builder);
+        assertEquals(1, list.size());
+        assertEquals("alice", list.get(0).getUserName());
+    }
+
+    /**
+     * 分页查询（显式 count SQL）
+     */
+    @Test
+    void queryForPageWithCountSql() {
+        Page<JqRow> page = jdbcQuery.queryForPage(
+                "select * from jq_demo where sort > ?",
+                "select count(1) from jq_demo where sort > ?",
+                JqRow.class, PageRequest.of(0, 10), 5);
+        assertEquals(2, page.getTotalElements());
+        assertEquals(2, page.getContent().size());
+    }
+
+    @Test
+    void queryForPageWithBuilder() {
+        SQLBuilder<JqRow> builder = new SQLBuilder<>(
+                JqRow.class, "select * from jq_demo where 1=1", "select count(1) from jq_demo where 1=1");
+        builder.append("and sort > ?", 15);
+        Page<JqRow> page = jdbcQuery.queryForPage(builder, PageRequest.of(0, 10));
+        assertEquals(1, page.getTotalElements());
+        assertEquals("bob", page.getContent().get(0).getUserName());
+    }
+
+    /**
+     * Map 分页查询（显式 count SQL）
+     */
+    @Test
+    void queryForMapPageWithCountSql() {
+        Page<Map<String, Object>> page = jdbcQuery.queryForMapPage(
+                "select * from jq_demo where sort > ?",
+                "select count(1) from jq_demo where sort > ?",
+                PageRequest.of(0, 10), 5);
+        assertEquals(2, page.getTotalElements());
+        assertEquals(2, page.getContent().size());
+    }
+
+    @Test
+    void queryForMapPageWithBuilder() {
+        SQLBuilder<Object> builder = new SQLBuilder<>(
+                "select * from jq_demo where 1=1", "select count(1) from jq_demo where 1=1");
+        builder.append("and id = ?", 2);
+        Page<Map<String, Object>> page = jdbcQuery.queryForMapPage(builder, PageRequest.of(0, 10));
+        assertEquals(1, page.getTotalElements());
+        assertEquals("bob", page.getContent().get(0).get("userName"));
+    }
+
+    /**
+     * count SQL 占位符数量少于查询参数时，内部 arraycopy 截断参数
+     */
+    @Test
+    void queryForMapPageTruncatesParamsForCountSql() {
+        Page<Map<String, Object>> page = jdbcQuery.queryForMapPage(
+                "select * from jq_demo where sort > ?",
+                "select count(1) from jq_demo",
+                PageRequest.of(0, 10), 5);
+        assertEquals(2, page.getTotalElements());
+        assertEquals(2, page.getContent().size());
+    }
+
+    /**
+     * 自动拼接 count SQL 的两个方法：countSql = "SELECT COUNT(1) " + sql，
+     * 要求 sql 以 from 开头。原生 SQL 无法同时满足两种形态，
+     * 因此用 mock 的 JdbcTemplate 验证其 count SQL 拼装与调用逻辑。
+     */
+    @Test
+    void queryForPageAutoCountSql() {
+        JqRow row = new JqRow();
+        row.setId(1);
+        row.setUserName("alice");
+        List<JqRow> rows = new ArrayList<>();
+        rows.add(row);
+        // 空参数数组的 varargs 调用无法被 Mockito 桩匹配, 改用 default answer 直接返回数据
+        JdbcTemplate mockTemplate = mock(JdbcTemplate.class, invocation -> {
+            String methodName = invocation.getMethod().getName();
+            if ("query".equals(methodName)) {
+                return rows;
+            }
+            if ("queryForObject".equals(methodName)) {
+                return 1L;
+            }
+            return null;
+        });
+
+        JdbcQuery query = new JdbcQuery(mockTemplate);
+        Page<JqRow> page = query.queryForPage("from jq_demo", JqRow.class, PageRequest.of(0, 10));
+
+        assertEquals(1, page.getTotalElements());
+        assertEquals(1, page.getContent().size());
+        verify(mockTemplate).queryForObject(eq("SELECT COUNT(1) from jq_demo"), eq(Long.class));
+    }
+
+    @Test
+    void queryForMapPageAutoCountSql() {
+        JdbcTemplate mockTemplate = mock(JdbcTemplate.class);
+        List<Map<String, Object>> rows = new ArrayList<>();
+        doReturn(rows).when(mockTemplate).query(anyString(), any(RowMapper.class), (Object[]) any());
+        // 自动 count SQL 无占位符, countQuery 以空参数数组调用; 不带 varargs 参数的桩恰好匹配零长 varargs 调用
+        doReturn(0L).when(mockTemplate).queryForObject(anyString(), eq(Long.class));
+
+        JdbcQuery query = new JdbcQuery(mockTemplate);
+        Page<Map<String, Object>> page = query.queryForMapPage("from jq_demo", PageRequest.of(0, 10));
+
+        assertEquals(0, page.getTotalElements());
+        assertTrue(page.getContent().isEmpty());
+        verify(mockTemplate).queryForObject(eq("SELECT COUNT(1) from jq_demo"), eq(Long.class));
+    }
+}
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/SQLBuilderTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/SQLBuilderTest.java
new file mode 100644
index 000000000..316c6eeb9
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/SQLBuilderTest.java
@@ -0,0 +1,88 @@
+package com.codingapi.springboot.fast.jpa;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+/**
+ * SQLBuilder 单元测试（覆盖全部构造器与追加方法）
+ */
+class SQLBuilderTest {
+
+    @Test
+    void constructorWithSqlOnly() {
+        SQLBuilder<Object> builder = new SQLBuilder<>("select * from t_demo where 1=1");
+        assertEquals("select * from t_demo where 1=1", builder.getSQL());
+        assertEquals("select count(1) from select * from t_demo where 1=1", builder.getCountSQL());
+        assertEquals(1, builder.getIndex());
+        assertNull(builder.getClazz());
+        assertEquals(0, builder.getParams().length);
+    }
+
+    @Test
+    void constructorWithSqlAndCountSql() {
+        SQLBuilder<Object> builder = new SQLBuilder<>("select * from t_demo", "select count(1) from t_demo");
+        assertEquals("select * from t_demo", builder.getSQL());
+        assertEquals("select count(1) from t_demo", builder.getCountSQL());
+    }
+
+    @Test
+    void constructorWithClassAndSql() {
+        SQLBuilder<String> builder = new SQLBuilder<>(String.class, "select name from t_demo");
+        assertEquals(String.class, builder.getClazz());
+        assertEquals("select name from t_demo", builder.getSQL());
+        assertEquals("select count(1) from select name from t_demo", builder.getCountSQL());
+    }
+
+    @Test
+    void constructorWithClassSqlAndCountSql() {
+        SQLBuilder<String> builder = new SQLBuilder<>(String.class, "select name from t_demo", "select count(1) from t_demo");
+        assertEquals(String.class, builder.getClazz());
+        assertEquals("select name from t_demo", builder.getSQL());
+        assertEquals("select count(1) from t_demo", builder.getCountSQL());
+    }
+
+    /**
+     * append 非空值时拼接带序号的占位符，null 值时忽略
+     */
+    @Test
+    void append() {
+        SQLBuilder<Object> builder = new SQLBuilder<>("select * from t_demo where 1=1", "select count(1) from t_demo where 1=1");
+        builder.append("and name = ?", "tom");
+        assertEquals("select * from t_demo where 1=1 and name = ?1 ", builder.getSQL());
+        assertEquals("select count(1) from t_demo where 1=1 and name = ?1 ", builder.getCountSQL());
+        assertEquals(2, builder.getIndex());
+        assertArrayEquals(new Object[]{"tom"}, builder.getParams());
+
+        // null 值不追加
+        builder.append("and id = ?", null);
+        assertEquals("select * from t_demo where 1=1 and name = ?1 ", builder.getSQL());
+        assertEquals(2, builder.getIndex());
+        assertEquals(1, builder.getParams().length);
+
+        builder.append("and sort > ?", 10);
+        assertEquals("select * from t_demo where 1=1 and name = ?1  and sort > ?2 ", builder.getSQL());
+        assertEquals(3, builder.getIndex());
+        assertArrayEquals(new Object[]{"tom", 10}, builder.getParams());
+    }
+
+    @Test
+    void addParam() {
+        SQLBuilder<Object> builder = new SQLBuilder<>("select * from t_demo");
+        builder.addParam("a");
+        assertEquals(2, builder.getIndex());
+        builder.addParam("b", 9);
+        assertEquals(9, builder.getIndex());
+        assertArrayEquals(new Object[]{"a", "b"}, builder.getParams());
+    }
+
+    @Test
+    void appendSql() {
+        SQLBuilder<Object> builder = new SQLBuilder<>("select * from t_demo", "select count(1) from t_demo");
+        builder.appendSql("order by id desc");
+        assertEquals("select * from t_demo order by id desc ", builder.getSQL());
+        assertEquals("select count(1) from t_demo order by id desc ", builder.getCountSQL());
+    }
+}
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/MapViewResultTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/MapViewResultTest.java
new file mode 100644
index 000000000..d553b7f62
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/MapViewResultTest.java
@@ -0,0 +1,111 @@
+package com.codingapi.springboot.fast.jpa.map;
+
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Constructor;
+import java.util.Arrays;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+/**
+ * MapViewResult 拥有 253 个构造器重载（1~253 个值参数），
+ * 通过反射逐个 arity 调用，确保每个构造器与 build 逻辑都被覆盖。
+ *
+ * 注意：build(key, values) 按 QueryColumns 的列数量遍历取值，
+ * 因此每个 arity 需要注册一个列数量与之匹配的 QueryColumns。
+ */
+class MapViewResultTest {
+
+    private static final int MAX_ARITY = 253;
+
+    private String[] buildColumns(int count) {
+        String[] columns = new String[count];
+        for (int i = 0; i < count; i++) {
+            columns[i] = "c" + i;
+        }
+        return columns;
+    }
+
+    private Object[] buildValues(int count) {
+        Object[] values = new Object[count];
+        for (int i = 0; i < count; i++) {
+            values[i] = "v" + i;
+        }
+        return values;
+    }
+
+    /**
+     * 参数化遍历全部 253 个构造器重载
+     */
+    @Test
+    void allConstructorOverloads() throws Exception {
+        for (int arity = 1; arity <= MAX_ARITY; arity++) {
+            QueryColumns queryColumns = QueryColumnsContext.build(buildColumns(arity));
+            String key = queryColumns.getKey();
+            try {
+                Class<?>[] parameterTypes = new Class<?>[arity + 1];
+                parameterTypes[0] = String.class;
+                Arrays.fill(parameterTypes, 1, arity + 1, Object.class);
+                Constructor<MapViewResult> constructor = MapViewResult.class.getConstructor(parameterTypes);
+
+                Object[] args = new Object[arity + 1];
+                args[0] = key;
+                Object[] values = buildValues(arity);
+                System.arraycopy(values, 0, args, 1, arity);
+
+                MapViewResult result = constructor.newInstance(args);
+
+                assertEquals(arity, result.size(), "arity=" + arity);
+                assertEquals("v0", result.get("c0"), "arity=" + arity);
+                assertEquals("v" + (arity - 1), result.get("c" + (arity - 1)), "arity=" + arity);
+                assertNull(result.get("not-exist"), "arity=" + arity);
+            } finally {
+                QueryColumnsContext.getInstance().clearCache(key);
+            }
+        }
+    }
+
+    /**
+     * 直接调用部分常用构造器，验证列名映射与值顺序
+     */
+    @Test
+    void directConstructors() {
+        QueryColumns two = QueryColumnsContext.build("u.id as iii", "u.name");
+        MapViewResult result2 = new MapViewResult(two.getKey(), 1, "tom");
+        assertEquals(2, result2.size());
+        assertEquals(1, result2.get("iii"));
+        assertEquals("tom", result2.get("name"));
+        QueryColumnsContext.getInstance().clearCache(two.getKey());
+
+        QueryColumns three = QueryColumnsContext.build("a", "b", "c");
+        MapViewResult result3 = new MapViewResult(three.getKey(), 1, 2L, 3.5);
+        assertEquals(3, result3.size());
+        assertEquals(1, result3.get("a"));
+        assertEquals(2L, result3.get("b"));
+        assertEquals(3.5, result3.get("c"));
+        QueryColumnsContext.getInstance().clearCache(three.getKey());
+
+        QueryColumns five = QueryColumnsContext.build("a", "b", "c", "d", "e");
+        MapViewResult result5 = new MapViewResult(five.getKey(), "1", "2", "3", "4", "5");
+        assertEquals(5, result5.size());
+        assertEquals("5", result5.get("e"));
+        QueryColumnsContext.getInstance().clearCache(five.getKey());
+    }
+
+    /**
+     * MapViewResult 本身是一个 Map，验证 Map 的基础行为
+     */
+    @Test
+    void mapBehavior() {
+        QueryColumns columns = QueryColumnsContext.build("name", "age");
+        MapViewResult result = new MapViewResult(columns.getKey(), "tom", 18);
+        assertEquals(true, result.containsKey("name"));
+        assertEquals(true, result.containsValue(18));
+        result.put("extra", "value");
+        assertEquals(3, result.size());
+        result.remove("extra");
+        assertEquals(2, result.size());
+        QueryColumnsContext.getInstance().clearCache(columns.getKey());
+    }
+}
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/QueryColumnsTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/QueryColumnsTest.java
new file mode 100644
index 000000000..09aedae2d
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/map/QueryColumnsTest.java
@@ -0,0 +1,92 @@
+package com.codingapi.springboot.fast.jpa.map;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * QueryColumns / QueryColumnsContext 单元测试
+ */
+class QueryColumnsTest {
+
+    /**
+     * 列别名解析：覆盖 小写as、大写AS、表前缀(.)、普通列 四种分支
+     */
+    @Test
+    void getColumnAlias() {
+        QueryColumns columns = QueryColumnsContext.build(
+                "u.id as iii",
+                "u.name AS userName",
+                "t_demo.sort",
+                "plain_column",
+                "  spaced  "
+        );
+        List<String> aliases = columns.getColumnAlias();
+        assertEquals(Arrays.asList("iii", "userName", "sort", "plain_column", "spaced"), aliases);
+        QueryColumnsContext.getInstance().clearCache(columns.getKey());
+    }
+
+    /**
+     * 多个 as/AS 时取最后一段
+     */
+    @Test
+    void getColumnAliasWithMultipleAs() {
+        QueryColumns columns = QueryColumnsContext.build("concat(a,b) as x as y");
+        List<String> aliases = columns.getColumnAlias();
+        assertEquals(1, aliases.size());
+        assertEquals("y", aliases.get(0));
+        QueryColumnsContext.getInstance().clearCache(columns.getKey());
+    }
+
+    @Test
+    void getColumnSql() {
+        QueryColumns columns = QueryColumnsContext.build("u.id as iii", "u.name");
+        assertEquals("u.id as iii,u.name", columns.getColumnSql());
+        assertEquals(2, columns.getColumns().size());
+        QueryColumnsContext.getInstance().clearCache(columns.getKey());
+    }
+
+    /**
+     * addColumn 支持链式调用
+     */
+    @Test
+    void addColumnChaining() {
+        QueryColumns columns = new QueryColumns();
+        assertNotNull(columns.getKey());
+        assertEquals(8, columns.getKey().length());
+        QueryColumns same = columns.addColumn("a").addColumn("b");
+        assertSame(columns, same);
+        assertEquals("a,b", columns.getColumnSql());
+    }
+
+    /**
+     * context 注册、查询与清理
+     */
+    @Test
+    void contextBuildAndClear() {
+        QueryColumns columns = QueryColumnsContext.build("id");
+        String key = columns.getKey();
+        assertSame(columns, QueryColumnsContext.getInstance().getQueryColumns(key));
+        QueryColumnsContext.getInstance().clearCache(key);
+        assertNull(QueryColumnsContext.getInstance().getQueryColumns(key));
+    }
+
+    /**
+     * 每次 build 生成的 key 不同，互不影响
+     */
+    @Test
+    void contextKeysAreIndependent() {
+        QueryColumns c1 = QueryColumnsContext.build("a");
+        QueryColumns c2 = QueryColumnsContext.build("b");
+        assertNotNull(QueryColumnsContext.getInstance().getQueryColumns(c1.getKey()));
+        assertNotNull(QueryColumnsContext.getInstance().getQueryColumns(c2.getKey()));
+        QueryColumnsContext.getInstance().clearCache(c1.getKey());
+        QueryColumnsContext.getInstance().clearCache(c2.getKey());
+    }
+}
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilderTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilderTest.java
new file mode 100644
index 000000000..2718580ff
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/DynamicSQLBuilderTest.java
@@ -0,0 +1,210 @@
+package com.codingapi.springboot.fast.jpa.repository;
+
+import com.codingapi.springboot.fast.entity.Demo;
+import com.codingapi.springboot.framework.dto.request.Filter;
+import com.codingapi.springboot.framework.dto.request.PageRequest;
+import com.codingapi.springboot.framework.dto.request.Relation;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.domain.Sort;
+
+import java.util.Arrays;
+import java.util.Collections;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * DynamicSQLBuilder 单元测试：覆盖全部过滤关系、or/and 嵌套与排序拼装。
+ * （DynamicSQLBuilder 为包级私有，测试类置于同一包下）
+ */
+class DynamicSQLBuilderTest {
+
+    @Test
+    void emptyRequest() {
+        PageRequest request = new PageRequest();
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE ", builder.getHQL());
+        assertEquals("SELECT COUNT(1) FROM Demo WHERE ", builder.getCountHQL());
+        assertEquals(0, builder.getParams().length);
+    }
+
+    @Test
+    void equalFilter() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", "tom");
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name = ?1", builder.getHQL());
+        assertEquals("SELECT COUNT(1) FROM Demo WHERE name = ?1", builder.getCountHQL());
+        assertArrayEquals(new Object[]{"tom"}, builder.getParams());
+    }
+
+    @Test
+    void nullFilters() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", Relation.IS_NULL);
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name IS NULL ", builder.getHQL());
+        assertEquals(0, builder.getParams().length);
+    }
+
+    @Test
+    void notNullFilter() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", Relation.IS_NOT_NULL);
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name IS NOT NULL ", builder.getHQL());
+        assertEquals(0, builder.getParams().length);
+    }
+
+    @Test
+    void notEqualFilter() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", Relation.NOT_EQUAL, "tom");
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name != ?1", builder.getHQL());
+        assertArrayEquals(new Object[]{"tom"}, builder.getParams());
+    }
+
+    @Test
+    void likeFilters() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", Relation.LIKE, "to");
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name LIKE ?1", builder.getHQL());
+        assertArrayEquals(new Object[]{"%to%"}, builder.getParams());
+
+        PageRequest left = new PageRequest();
+        left.addFilter("name", Relation.LEFT_LIKE, "to");
+        DynamicSQLBuilder leftBuilder = new DynamicSQLBuilder(left, Demo.class);
+        assertEquals("FROM Demo WHERE name LIKE ?1", leftBuilder.getHQL());
+        assertArrayEquals(new Object[]{"%to"}, leftBuilder.getParams());
+
+        PageRequest right = new PageRequest();
+        right.addFilter("name", Relation.RIGHT_LIKE, "to");
+        DynamicSQLBuilder rightBuilder = new DynamicSQLBuilder(right, Demo.class);
+        assertEquals("FROM Demo WHERE name LIKE ?1", rightBuilder.getHQL());
+        assertArrayEquals(new Object[]{"to%"}, rightBuilder.getParams());
+    }
+
+    @Test
+    void inAndNotInFilters() {
+        PageRequest request = new PageRequest();
+        request.addFilter("id", Relation.IN, 1, 2, 3);
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE id IN (?1)", builder.getHQL());
+        assertEquals(1, builder.getParams().length);
+        assertEquals(Arrays.asList(1, 2, 3), builder.getParams()[0]);
+
+        PageRequest notIn = new PageRequest();
+        notIn.addFilter("id", Relation.NOT_IN, 4);
+        DynamicSQLBuilder notInBuilder = new DynamicSQLBuilder(notIn, Demo.class);
+        assertEquals("FROM Demo WHERE id NOT IN (?1)", notInBuilder.getHQL());
+        assertEquals(Collections.singletonList(4), notInBuilder.getParams()[0]);
+    }
+
+    @Test
+    void compareFilters() {
+        PageRequest request = new PageRequest();
+        request.addFilter("sort", Relation.GREATER_THAN, 1);
+        assertEquals("FROM Demo WHERE sort > ?1", new DynamicSQLBuilder(request, Demo.class).getHQL());
+
+        PageRequest lt = new PageRequest();
+        lt.addFilter("sort", Relation.LESS_THAN, 2);
+        assertEquals("FROM Demo WHERE sort < ?1", new DynamicSQLBuilder(lt, Demo.class).getHQL());
+
+        PageRequest gte = new PageRequest();
+        gte.addFilter("sort", Relation.GREATER_THAN_EQUAL, 3);
+        assertEquals("FROM Demo WHERE sort >= ?1", new DynamicSQLBuilder(gte, Demo.class).getHQL());
+
+        PageRequest lte = new PageRequest();
+        lte.addFilter("sort", Relation.LESS_THAN_EQUAL, 4);
+        assertEquals("FROM Demo WHERE sort <= ?1", new DynamicSQLBuilder(lte, Demo.class).getHQL());
+    }
+
+    /**
+     * BETWEEN 使用两个占位符，且后续参数序号连续
+     */
+    @Test
+    void betweenFilterWithFollowingFilter() {
+        PageRequest request = new PageRequest();
+        request.addFilter("sort", Relation.BETWEEN, 1, 10);
+        request.addFilter("name", "tom");
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE sort BETWEEN ?1 AND ?2 AND name = ?3", builder.getHQL());
+        assertArrayEquals(new Object[]{1, 10, "tom"}, builder.getParams());
+    }
+
+    /**
+     * or 过滤组装
+     */
+    @Test
+    void orFilters() {
+        PageRequest request = new PageRequest();
+        request.orFilters(Filter.as("name", "a"), Filter.as("name", "b"));
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE  ( name = ?1 OR name = ?2 )", builder.getHQL());
+        assertArrayEquals(new Object[]{"a", "b"}, builder.getParams());
+    }
+
+    /**
+     * and 过滤组装
+     */
+    @Test
+    void andFilters() {
+        PageRequest request = new PageRequest();
+        request.andFilter(Filter.as("name", "a"), Filter.as("sort", Relation.GREATER_THAN, 1));
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE  ( name = ?1 AND sort > ?2 )", builder.getHQL());
+        assertArrayEquals(new Object[]{"a", 1}, builder.getParams());
+    }
+
+    /**
+     * or 嵌套 and 的递归组装
+     */
+    @Test
+    void nestedOrAndFilters() {
+        PageRequest request = new PageRequest();
+        request.orFilters(Filter.and(Filter.as("name", "a"), Filter.as("name", "b")), Filter.as("name", "c"));
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE  (  ( name = ?1 AND name = ?2 ) OR name = ?3 )", builder.getHQL());
+        assertArrayEquals(new Object[]{"a", "b", "c"}, builder.getParams());
+    }
+
+    /**
+     * 空的 or/and 过滤组不产生任何 SQL
+     */
+    @Test
+    void emptyOrAndFilters() {
+        PageRequest request = new PageRequest();
+        request.orFilters();
+        request.andFilter();
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE ", builder.getHQL());
+        assertEquals(0, builder.getParams().length);
+    }
+
+    /**
+     * 多字段排序拼装（通过构造器传入多字段 Sort）
+     */
+    @Test
+    void sortBuild() {
+        Sort sort = Sort.by("id").descending().and(Sort.by("name").ascending());
+        PageRequest request = new PageRequest(0, 10, sort);
+        request.addFilter("name", "tom");
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE name = ?1 ORDER BY id DESC,name ASC", builder.getHQL());
+        // count HQL 不包含排序
+        assertEquals("SELECT COUNT(1) FROM Demo WHERE name = ?1", builder.getCountHQL());
+    }
+
+    /**
+     * 仅排序无过滤
+     */
+    @Test
+    void sortOnly() {
+        PageRequest request = new PageRequest();
+        request.addSort(Sort.by("id").ascending());
+        DynamicSQLBuilder builder = new DynamicSQLBuilder(request, Demo.class);
+        assertEquals("FROM Demo WHERE  ORDER BY id ASC", builder.getHQL());
+    }
+}
diff --git a/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilderTest.java b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilderTest.java
new file mode 100644
index 000000000..1255a026e
--- /dev/null
+++ b/springboot-starter-data-fast/src/test/java/com/codingapi/springboot/fast/jpa/repository/ExampleBuilderTest.java
@@ -0,0 +1,96 @@
+package com.codingapi.springboot.fast.jpa.repository;
+
+import com.codingapi.springboot.fast.entity.Demo;
+import com.codingapi.springboot.framework.dto.request.PageRequest;
+import com.codingapi.springboot.framework.dto.request.Relation;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.domain.Example;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/**
+ * ExampleBuilder 单元测试（包级私有类，测试置于同一包下）
+ */
+class ExampleBuilderTest {
+
+    /**
+     * 无过滤条件时返回 null
+     */
+    @Test
+    void noFilterReturnsNull() {
+        PageRequest request = new PageRequest();
+        ExampleBuilder builder = new ExampleBuilder(request, Demo.class);
+        assertNull(builder.getExample());
+    }
+
+    /**
+     * 过滤条件命中实体属性时构建 Example，
+     * 同时覆盖字符串值向 Integer 类型属性的转换分支
+     */
+    @Test
+    void buildExampleWithFilters() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", "tom");
+        request.addFilter("sort", "18");
+        ExampleBuilder builder = new ExampleBuilder(request, Demo.class);
+        Example<Demo> example = builder.getExample();
+        assertNotNull(example);
+        Demo probe = example.getProbe();
+        assertEquals("tom", probe.getName());
+        assertEquals(Integer.valueOf(18), probe.getSort());
+    }
+
+    /**
+     * 过滤条件未命中任何属性时，Example 的 probe 为空白对象
+     */
+    @Test
+    void filterNotMatchAnyProperty() {
+        PageRequest request = new PageRequest();
+        request.addFilter("notExistField", "value");
+        ExampleBuilder builder = new ExampleBuilder(request, Demo.class);
+        Example<Demo> example = builder.getExample();
+        assertNotNull(example);
+        assertNull(example.getProbe().getName());
+    }
+
+    /**
+     * 命中只读属性（如 class）时写入失败被内部吞掉，不影响整体构建
+     */
+    @Test
+    void readOnlyPropertyFailureIsIgnored() {
+        PageRequest request = new PageRequest();
+        request.addFilter("class", "ignored");
+        request.addFilter("name", "tom");
+        ExampleBuilder builder = new ExampleBuilder(request, Demo.class);
+        Example<Demo> example = builder.getExample();
+        assertNotNull(example);
+        assertEquals("tom", example.getProbe().getName());
+    }
+
+    /**
+     * 实体类无默认构造器时抛出 RuntimeException
+     */
+    @Test
+    void entityWithoutDefaultConstructor() {
+        PageRequest request = new PageRequest();
+        request.addFilter("value", "1");
+        ExampleBuilder builder = new ExampleBuilder(request, Integer.class);
+        assertThrows(RuntimeException.class, builder::getExample);
+    }
+
+    /**
+     * 非 EQUAL 关系同样参与 Example 组装（仅取值填充 probe）
+     */
+    @Test
+    void relationFilterAlsoFillsProbe() {
+        PageRequest request = new PageRequest();
+        request.addFilter("name", Relation.LIKE, "to");
+        ExampleBuilder builder = new ExampleBuilder(request, Demo.class);
+        Example<Demo> example = builder.getExample();
+        assertNotNull(example);
+        assertEquals("to", example.getProbe().getName());
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeContextCoverageTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeContextCoverageTest.java
new file mode 100644
index 000000000..e123abe54
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeContextCoverageTest.java
@@ -0,0 +1,70 @@
+package com.codingapi.springboot.script;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * GroovyScriptRuntimeContext 单元测试
+ * 覆盖单例上下文对 GroovyScriptRuntime 的委托方法
+ */
+class GroovyScriptRuntimeContextCoverageTest {
+
+    @AfterEach
+    void tearDown() {
+        GroovyScriptRuntimeContext.getInstance().clearCache();
+    }
+
+    @Test
+    void instanceShouldBeSingletonWithDefaultConfig() {
+        GroovyScriptRuntimeContext context = GroovyScriptRuntimeContext.getInstance();
+        assertSame(context, GroovyScriptRuntimeContext.getInstance());
+        // 默认配置 shellMaxCacheSize = 10 * 1024
+        assertTrue(context.getMaxCacheSize() > 0);
+        assertEquals(GroovyScriptRuntimeContext.getInstance().getMaxCacheSize(), context.getMaxCacheSize());
+    }
+
+    @Test
+    void compileWithAndWithoutCache() {
+        GroovyScriptRuntimeContext context = GroovyScriptRuntimeContext.getInstance();
+
+        context.compile("return 1;");
+        assertEquals(0, context.cacheSize());
+
+        context.compile("return 2;", true);
+        assertEquals(1, context.cacheSize());
+
+        context.clearCache();
+        assertEquals(0, context.cacheSize());
+    }
+
+    @Test
+    void runShouldDelegateToRuntime() {
+        GroovyScriptRuntimeContext context = GroovyScriptRuntimeContext.getInstance();
+
+        Integer result = context.run("return 7;", Integer.class, TransactionMode.DEFAULT, null);
+        assertEquals(7, result);
+
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("$x", 1);
+        Integer bound = context.run("return $x + 1;", Integer.class, TransactionMode.DEFAULT, binds);
+        assertEquals(2, bound);
+    }
+
+    @Test
+    void invokeShouldDelegateToRuntime() {
+        GroovyScriptRuntimeContext context = GroovyScriptRuntimeContext.getInstance();
+
+        String script = "def run(request){\n"
+                + "    return request;\n"
+                + "}\n";
+        Integer result = context.invoke("run", script, Integer.class, TransactionMode.DEFAULT, null, 100);
+        assertEquals(100, result);
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeUnitTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeUnitTest.java
new file mode 100644
index 000000000..7e047aa1d
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptRuntimeUnitTest.java
@@ -0,0 +1,208 @@
+package com.codingapi.springboot.script;
+
+import com.codingapi.springboot.framework.transaction.TransactionManagerContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.TransactionStatus;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.ArgumentMatchers.any;
+
+/**
+ * GroovyScriptRuntime 单元测试
+ * 覆盖编译缓存、LRU 淘汰、invoke/run 各重载以及事务模式分支
+ */
+class GroovyScriptRuntimeUnitTest {
+
+    private GroovyScriptRuntime runtime;
+
+    private PlatformTransactionManager originalTransactionManager;
+
+    @BeforeEach
+    void setUp() {
+        runtime = new GroovyScriptRuntime(10);
+        originalTransactionManager = TransactionManagerContext.getInstance().getPlatformTransactionManager();
+    }
+
+    @AfterEach
+    void tearDown() {
+        // 恢复事务管理器，避免影响其他测试
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(originalTransactionManager);
+    }
+
+    private PlatformTransactionManager mockTransactionManager() {
+        PlatformTransactionManager txManager = Mockito.mock(PlatformTransactionManager.class);
+        TransactionStatus status = Mockito.mock(TransactionStatus.class);
+        Mockito.when(txManager.getTransaction(any(TransactionDefinition.class))).thenReturn(status);
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(txManager);
+        return txManager;
+    }
+
+    @Test
+    void maxCacheSizeShouldBeConstructorValue() {
+        assertEquals(10, runtime.getMaxCacheSize());
+    }
+
+    @Test
+    void compileWithoutCacheShouldNotStoreEntry() {
+        runtime.compile("return 1;", false);
+        runtime.compile("return 1;");
+        assertEquals(0, runtime.cacheSize());
+    }
+
+    @Test
+    void compileWithCacheShouldReuseCompiledEntry() {
+        runtime.compile("return 1;", true);
+        assertEquals(1, runtime.cacheSize());
+        // 相同脚本再次编译命中缓存，数量不变
+        runtime.compile("return 1;", true);
+        assertEquals(1, runtime.cacheSize());
+        // 不同脚本新增缓存
+        runtime.compile("return 2;", true);
+        assertEquals(2, runtime.cacheSize());
+    }
+
+    @Test
+    void cacheShouldEvictEldestWhenOverMaxSize() {
+        GroovyScriptRuntime smallRuntime = new GroovyScriptRuntime(2);
+        smallRuntime.run("return 1;", Integer.class, TransactionMode.DEFAULT, null);
+        smallRuntime.run("return 2;", Integer.class, TransactionMode.DEFAULT, null);
+        smallRuntime.run("return 3;", Integer.class, TransactionMode.DEFAULT, null);
+        assertEquals(2, smallRuntime.cacheSize());
+    }
+
+    @Test
+    void clearCacheShouldRemoveAllCompiledScripts() {
+        runtime.compile("return 1;", true);
+        runtime.compile("return 2;", true);
+        assertEquals(2, runtime.cacheSize());
+
+        runtime.clearCache();
+        assertEquals(0, runtime.cacheSize());
+    }
+
+    @Test
+    void invokeMethodWithArguments() {
+        String script = "def run(request){\n"
+                + "    return request;\n"
+                + "}\n";
+        Integer result = runtime.invoke("run", script, Integer.class, 100);
+        assertEquals(100, result);
+    }
+
+    @Test
+    void invokeMethodWithBindsOverload() {
+        String script = "def run(request){\n"
+                + "    return request + $base;\n"
+                + "}\n";
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("$base", 100);
+        Integer result = runtime.invoke("run", script, Integer.class, binds, 23);
+        assertEquals(123, result);
+    }
+
+    @Test
+    void invokeMethodWithDefaultTransactionModeAndBinds() {
+        // 脚本体本身即 run() 方法，不能再定义无参 run()（重复签名）
+        String script = "return $name;\n";
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("$name", "hello");
+        String result = runtime.invoke("run", script, String.class, TransactionMode.DEFAULT, binds);
+        assertEquals("hello", result);
+    }
+
+    @Test
+    void invokeReadonlyShouldUseTransactionAndRollback() {
+        PlatformTransactionManager txManager = mockTransactionManager();
+        String script = "def run(request){\n"
+                + "    return request;\n"
+                + "}\n";
+
+        Integer result = runtime.invoke("run", script, Integer.class, TransactionMode.READONLY, null, 5);
+        assertEquals(5, result);
+        Mockito.verify(txManager).getTransaction(any(TransactionDefinition.class));
+        // 只读模式执行完成后以回滚结束
+        Mockito.verify(txManager).rollback(any(TransactionStatus.class));
+        Mockito.verify(txManager, Mockito.never()).commit(any(TransactionStatus.class));
+    }
+
+    @Test
+    void invokeCommitShouldUseTransactionAndCommit() {
+        PlatformTransactionManager txManager = mockTransactionManager();
+        String script = "def run(request){\n"
+                + "    return request * 2;\n"
+                + "}\n";
+
+        Integer result = runtime.invoke("run", script, Integer.class, TransactionMode.COMMIT, null, 4);
+        assertEquals(8, result);
+        Mockito.verify(txManager).commit(any(TransactionStatus.class));
+        Mockito.verify(txManager, Mockito.never()).rollback(any(TransactionStatus.class));
+    }
+
+    @Test
+    void runScriptWithBinds() {
+        String script = "return $x + 1;";
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("$x", 41);
+        Integer result = runtime.run(script, Integer.class, binds);
+        assertEquals(42, result);
+    }
+
+    @Test
+    void runScriptWithoutBindsReturnsNullSafely() {
+        String script = "return 7;";
+        Integer result = runtime.run(script, Integer.class, TransactionMode.DEFAULT, null);
+        assertEquals(7, result);
+        // binds 为空 Map 同样安全
+        Integer result2 = runtime.run(script, Integer.class, TransactionMode.DEFAULT, new HashMap<>());
+        assertEquals(7, result2);
+    }
+
+    @Test
+    void runReadonlyShouldUseTransactionAndRollback() {
+        PlatformTransactionManager txManager = mockTransactionManager();
+
+        Integer result = runtime.run("return 9;", Integer.class, TransactionMode.READONLY, null);
+        assertEquals(9, result);
+        Mockito.verify(txManager).rollback(any(TransactionStatus.class));
+        Mockito.verify(txManager, Mockito.never()).commit(any(TransactionStatus.class));
+    }
+
+    @Test
+    void runCommitShouldUseTransactionAndCommit() {
+        PlatformTransactionManager txManager = mockTransactionManager();
+
+        Integer result = runtime.run("return 9;", Integer.class, TransactionMode.COMMIT, null);
+        assertEquals(9, result);
+        Mockito.verify(txManager).commit(any(TransactionStatus.class));
+        Mockito.verify(txManager, Mockito.never()).rollback(any(TransactionStatus.class));
+    }
+
+    @Test
+    void runShouldReuseCachedScriptInstance() {
+        String script = "return 3;";
+        Integer first = runtime.run(script, Integer.class, TransactionMode.DEFAULT, null);
+        assertEquals(3, first);
+        assertEquals(1, runtime.cacheSize());
+
+        Integer second = runtime.run(script, Integer.class, TransactionMode.DEFAULT, null);
+        assertEquals(3, second);
+        assertEquals(1, runtime.cacheSize());
+    }
+
+    @Test
+    void invokeResultCanBeNull() {
+        // 脚本体本身即 run() 方法，不能再定义无参 run()（重复签名）
+        String script = "return null;\n";
+        Object result = runtime.invoke("run", script, Object.class);
+        assertNull(result);
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptTest.java
new file mode 100644
index 000000000..63bbb90f9
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyScriptTest.java
@@ -0,0 +1,215 @@
+package com.codingapi.springboot.script;
+
+import com.codingapi.springboot.script.meta.GroovyMetadata;
+import com.codingapi.springboot.script.repository.GroovyScriptRepositoryContext;
+import com.codingapi.springboot.script.temp.TempGroovyScriptContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * GroovyScript 单元测试
+ * 覆盖 Builder 全字段、copy、temp/save/remove 生命周期以及 run/invoke 各重载
+ */
+class GroovyScriptTest {
+
+    @BeforeEach
+    void setUp() {
+        TempGroovyScriptContext.getInstance().clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        TempGroovyScriptContext.getInstance().clear();
+        GroovyScriptRepositoryContext.getInstance().delete("lifecycle-key");
+    }
+
+    @Test
+    void builderShouldSetAllFields() {
+        Map<String, Class<?>> binds = new HashMap<>();
+        binds.put("$x", Integer.class);
+        Map<String, Class<?>> requests = new HashMap<>();
+        requests.put("request", String.class);
+
+        long before = System.currentTimeMillis();
+        GroovyScript script = GroovyScript.builder("builder-key")
+                .script("return 1;")
+                .description("desc")
+                .method("run")
+                .returnType(Integer.class)
+                .binds(binds)
+                .requests(requests)
+                .typeOne("one")
+                .typeTwo("two")
+                .tag("tag")
+                .remark("remark")
+                .build();
+
+        assertEquals("builder-key", script.getKey());
+        assertEquals("return 1;", script.getScript());
+        assertEquals("desc", script.getDescription());
+        assertEquals("run", script.getMethod());
+        assertEquals(Integer.class, script.getReturnType());
+        assertSame(binds, script.getBinds());
+        assertSame(requests, script.getRequests());
+        assertEquals("one", script.getTypeOne());
+        assertEquals("two", script.getTypeTwo());
+        assertEquals("tag", script.getTag());
+        assertEquals("remark", script.getRemark());
+        assertTrue(script.getCreateTime() >= before);
+        assertEquals(0, script.getUpdateTime());
+    }
+
+    @Test
+    void singleArgConstructorShouldOnlySetKeyAndCreateTime() {
+        GroovyScript script = new GroovyScript("ctor-key");
+        assertEquals("ctor-key", script.getKey());
+        assertTrue(script.getCreateTime() > 0);
+        assertNull(script.getScript());
+    }
+
+    @Test
+    void copyShouldKeepAllFieldsWithNewKey() {
+        Map<String, Class<?>> binds = new HashMap<>();
+        binds.put("$x", Integer.class);
+
+        GroovyScript origin = GroovyScript.builder("origin-key")
+                .script("return 1;")
+                .description("desc")
+                .method("run")
+                .returnType(Integer.class)
+                .binds(binds)
+                .typeOne("one")
+                .typeTwo("two")
+                .tag("tag")
+                .remark("remark")
+                .build();
+        origin.setUpdateTime(123L);
+
+        GroovyScript copy = origin.copy("copy-key");
+
+        assertEquals("copy-key", copy.getKey());
+        assertEquals(origin.getScript(), copy.getScript());
+        assertEquals(origin.getDescription(), copy.getDescription());
+        assertEquals(origin.getMethod(), copy.getMethod());
+        assertEquals(origin.getReturnType(), copy.getReturnType());
+        assertSame(origin.getBinds(), copy.getBinds());
+        assertEquals(origin.getTypeOne(), copy.getTypeOne());
+        assertEquals(origin.getTypeTwo(), copy.getTypeTwo());
+        assertEquals(origin.getTag(), copy.getTag());
+        assertEquals(origin.getRemark(), copy.getRemark());
+        assertEquals(origin.getCreateTime(), copy.getCreateTime());
+        assertEquals(origin.getUpdateTime(), copy.getUpdateTime());
+    }
+
+    @Test
+    void tempSaveRemoveLifecycle() {
+        GroovyScript script = GroovyScript.builder("lifecycle-key")
+                .script("return 1;")
+                .build();
+
+        // 临时存储
+        script.temp();
+        assertNotNull(TempGroovyScriptContext.getInstance().getGroovyScript("lifecycle-key"));
+
+        // 保存后进入仓储，临时数据被清理
+        script.save();
+        assertTrue(script.getUpdateTime() > 0);
+        assertSame(script, GroovyScriptRepositoryContext.getInstance().get("lifecycle-key"));
+        assertNull(TempGroovyScriptContext.getInstance().getGroovyScript("lifecycle-key"));
+
+        // 删除后仓储与临时均无数据
+        script.remove();
+        assertNull(GroovyScriptRepositoryContext.getInstance().get("lifecycle-key"));
+        assertNull(TempGroovyScriptContext.getInstance().getGroovyScript("lifecycle-key"));
+    }
+
+    @Test
+    void runOverloads() {
+        GroovyScript plain = GroovyScript.builder("run-key")
+                .script("return 7;")
+                .returnType(Integer.class)
+                .build();
+
+        assertEquals(Integer.valueOf(7), plain.<Integer>run());
+        assertEquals(Integer.valueOf(7), plain.<Integer>run(TransactionMode.DEFAULT));
+
+        GroovyScript bound = GroovyScript.builder("run-bind-key")
+                .script("return $x + 1;")
+                .returnType(Integer.class)
+                .build();
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("$x", 41);
+        assertEquals(Integer.valueOf(42), bound.<Integer>run(binds));
+        assertEquals(Integer.valueOf(42), bound.<Integer>run(TransactionMode.DEFAULT, binds));
+    }
+
+    @Test
+    void invokeOverloads() {
+        String script = "def run(request){\n"
+                + "    return request + offset;\n"
+                + "}\n";
+        GroovyScript groovyScript = GroovyScript.builder("invoke-key")
+                .script(script)
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+
+        // invoke(requests...)
+        Map<String, Object> binds = new HashMap<>();
+        binds.put("offset", 0);
+        assertEquals(Integer.valueOf(10), groovyScript.<Integer>invoke(binds, 10));
+        // invoke(transactionMode, requests...)
+        assertEquals(Integer.valueOf(11), groovyScript.<Integer>invoke(TransactionMode.DEFAULT, binds, 11));
+        // invoke(transactionMode, binds, requests...)
+        assertEquals(Integer.valueOf(12),
+                groovyScript.<Integer>invoke(TransactionMode.DEFAULT, binds, 12));
+
+        // 无参数函数：脚本体本身即 run() 方法，不能再定义无参 run()（重复签名）
+        String noArgScript = "return 99;\n";
+        GroovyScript noArg = GroovyScript.builder("invoke-noarg-key")
+                .script(noArgScript)
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+        assertEquals(Integer.valueOf(99), noArg.<Integer>invoke());
+        assertEquals(Integer.valueOf(99), noArg.<Integer>invoke(TransactionMode.DEFAULT));
+    }
+
+    @Test
+    void compileShouldDelegateToRuntimeContext() {
+        GroovyScript script = GroovyScript.builder("compile-key")
+                .script("return 5;")
+                .build();
+
+        script.compile();
+        script.compile(true);
+        assertTrue(GroovyScriptRuntimeContext.getInstance().cacheSize() >= 1);
+        GroovyScriptRuntimeContext.getInstance().clearCache();
+    }
+
+    @Test
+    void toMetadataShouldReturnScannedMetadata() {
+        GroovyScript script = GroovyScript.builder("meta-key")
+                .script("return 1;")
+                .description("desc")
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+
+        GroovyMetadata metadata = script.toMetadata();
+        assertNotNull(metadata);
+        assertEquals("run", metadata.getMainMethod());
+        assertEquals("Integer", metadata.getReturnType());
+        assertEquals("desc", metadata.getDescription());
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyStrategyTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyStrategyTest.java
index 8a50c254d..e38f8b553 100644
--- a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyStrategyTest.java
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/GroovyStrategyTest.java
@@ -6,6 +6,7 @@
 import com.codingapi.springboot.script.meta.GroovyType;
 import com.codingapi.springboot.script.request.MyScriptRequest;
 import com.codingapi.springboot.script.strategy.*;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
@@ -22,6 +23,14 @@ void beforeRun(){
         ScriptTypeMappingContext.getInstance().clear();
     }
 
+    @AfterEach
+    void afterRun(){
+        // 避免自定义策略泄漏到其他测试类（跨类共享单例上下文）
+        GroovyMetadataGenerateStrategyContext.getInstance().clear();
+        GroovyTypeFixStrategyContext.getInstance().clear();
+        ScriptTypeMappingContext.getInstance().clear();
+    }
+
 
     @Test
     void test1(){
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/cache/GroovyScriptCacheContextTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/cache/GroovyScriptCacheContextTest.java
new file mode 100644
index 000000000..14abcb67c
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/cache/GroovyScriptCacheContextTest.java
@@ -0,0 +1,184 @@
+package com.codingapi.springboot.script.cache;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.meta.GroovyMetadata;
+import com.codingapi.springboot.script.repository.GroovyScriptRepositoryContext;
+import com.codingapi.springboot.script.temp.TempGroovyScriptContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * GroovyScriptCacheContext 单元测试
+ * 覆盖 LRU 缓存的存取、回源（临时缓存/仓储）、批量加载、编译与淘汰逻辑
+ */
+class GroovyScriptCacheContextTest {
+
+    private final GroovyScriptCacheContext context = GroovyScriptCacheContext.getInstance();
+
+    private GroovyScript script(String key) {
+        return GroovyScript.builder(key)
+                .script("return 1;")
+                .description("desc-" + key)
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+    }
+
+    @BeforeEach
+    void setUp() {
+        context.clear();
+        TempGroovyScriptContext.getInstance().clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        context.clear();
+        TempGroovyScriptContext.getInstance().clear();
+        // 清理回源测试写入仓储的数据
+        GroovyScriptRepositoryContext.getInstance().delete("cache-repo-key");
+        GroovyScriptRepositoryContext.getInstance().delete("cache-save-key");
+    }
+
+    @Test
+    void saveAndCacheShouldPutScriptIntoCache() {
+        GroovyScript s1 = script("cache-key-1");
+        GroovyScript s2 = script("cache-key-2");
+
+        context.save(s1);
+        context.cache(s2);
+        // null 入参直接忽略
+        context.save(null);
+        context.cache(null);
+
+        assertEquals(2, context.count());
+        List<String> keys = context.keys();
+        assertEquals(2, keys.size());
+        assertTrue(keys.contains("cache-key-1"));
+        assertTrue(keys.contains("cache-key-2"));
+        assertSame(s1, context.getGroovyScript("cache-key-1"));
+    }
+
+    @Test
+    void removeShouldDeleteExistingKeyAndIgnoreMissingKey() {
+        context.save(script("cache-remove-key"));
+        assertEquals(1, context.count());
+
+        context.remove("cache-remove-key");
+        assertEquals(0, context.count());
+
+        // 删除不存在的key不抛异常
+        context.remove("cache-remove-key-missing");
+        assertEquals(0, context.count());
+    }
+
+    @Test
+    void getGroovyScriptShouldFallbackToTempContextWithoutCaching() {
+        GroovyScript tempScript = script("cache-temp-key");
+        TempGroovyScriptContext.getInstance().save(tempScript);
+
+        GroovyScript result = context.getGroovyScript("cache-temp-key");
+        assertSame(tempScript, result);
+        // 临时数据不回写到缓存
+        assertEquals(0, context.count());
+    }
+
+    @Test
+    void getGroovyScriptShouldFallbackToRepositoryAndCacheResult() {
+        GroovyScript repoScript = script("cache-repo-key");
+        GroovyScriptRepositoryContext.getInstance().save(repoScript);
+
+        GroovyScript result = context.getGroovyScript("cache-repo-key");
+        assertSame(repoScript, result);
+        // 仓储数据会回写到缓存
+        assertEquals(1, context.count());
+
+        // 再次获取直接命中缓存
+        assertSame(repoScript, context.getGroovyScript("cache-repo-key"));
+    }
+
+    @Test
+    void getGroovyScriptShouldReturnNullWhenMissingEverywhere() {
+        assertNull(context.getGroovyScript("cache-no-such-key"));
+    }
+
+    @Test
+    void getGroovyMetadataShouldReturnMetadataOrNull() {
+        context.save(script("cache-meta-key"));
+        GroovyMetadata metadata = context.getGroovyMetadata("cache-meta-key");
+        assertNotNull(metadata);
+        assertEquals("run", metadata.getMainMethod());
+        assertEquals("Integer", metadata.getReturnType());
+
+        assertNull(context.getGroovyMetadata("cache-no-such-key"));
+    }
+
+    @Test
+    void getScriptShouldReturnContentOrEmptyString() {
+        context.save(script("cache-script-key"));
+        assertEquals("return 1;", context.getScript("cache-script-key"));
+        assertEquals("", context.getScript("cache-no-such-key"));
+    }
+
+    @Test
+    void setBatchCacheShouldIgnoreNullListAndNullElements() {
+        context.setBatchCache(null);
+        assertEquals(0, context.count());
+
+        List<GroovyScript> list = new ArrayList<>();
+        list.add(script("cache-batch-1"));
+        list.add(null);
+        list.add(script("cache-batch-2"));
+        context.setBatchCache(list);
+
+        assertEquals(2, context.count());
+        assertNotNull(context.getGroovyScript("cache-batch-1"));
+        assertNotNull(context.getGroovyScript("cache-batch-2"));
+    }
+
+    @Test
+    void compileAllShouldCompileEveryCachedScript() {
+        context.save(script("cache-compile-1"));
+        context.save(script("cache-compile-2"));
+
+        // 非缓存模式编译全部脚本
+        context.compileAll(false);
+        assertEquals(2, context.count());
+    }
+
+    @Test
+    void lruCacheShouldEvictEldestEntryWhenOverMaxSize() {
+        // MAX_CACHE_SIZE = 10 * 1024，写入超出一条即触发 LRU 淘汰
+        int total = 10 * 1024 + 1;
+        for (int i = 0; i < total; i++) {
+            context.save(GroovyScript.builder("cache-lru-" + i).script("return 1;").build());
+        }
+
+        assertEquals(10 * 1024, context.count());
+        // 最早写入的被淘汰（缓存/临时/仓储均无，返回 null）
+        assertNull(context.getGroovyScript("cache-lru-0"));
+        // 其后写入的仍然存在
+        assertNotNull(context.getGroovyScript("cache-lru-1"));
+        assertEquals(10 * 1024, context.count());
+    }
+
+    @Test
+    void clearShouldRemoveAllEntries() {
+        context.save(script("cache-clear-1"));
+        context.save(script("cache-clear-2"));
+        assertEquals(2, context.count());
+
+        context.clear();
+        assertEquals(0, context.count());
+        assertTrue(context.keys().isEmpty());
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/controller/GroovyScriptControllerTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/controller/GroovyScriptControllerTest.java
new file mode 100644
index 000000000..85d9677bf
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/controller/GroovyScriptControllerTest.java
@@ -0,0 +1,184 @@
+package com.codingapi.springboot.script.controller;
+
+import com.codingapi.springboot.framework.dto.response.Response;
+import com.codingapi.springboot.framework.dto.response.SingleResponse;
+import com.codingapi.springboot.framework.exception.LocaleMessageException;
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.GroovyScriptRuntimeContext;
+import com.codingapi.springboot.script.cache.GroovyScriptCacheContext;
+import com.codingapi.springboot.script.meta.GroovyMetadata;
+import com.codingapi.springboot.script.pojo.ScriptCompileRequest;
+import com.codingapi.springboot.script.pojo.ScriptSaveRequest;
+import com.codingapi.springboot.script.repository.GroovyScriptRepositoryContext;
+import com.codingapi.springboot.script.temp.TempGroovyScriptContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * GroovyScriptController 单元测试
+ * 直接调用 Controller 方法，覆盖编译/查询/保存 REST 接口逻辑
+ */
+class GroovyScriptControllerTest {
+
+    private final GroovyScriptController controller = new GroovyScriptController();
+
+    private GroovyScript script(String key, String content) {
+        return GroovyScript.builder(key)
+                .script(content)
+                .description("desc-" + key)
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+    }
+
+    @BeforeEach
+    void setUp() {
+        GroovyScriptCacheContext.getInstance().clear();
+        TempGroovyScriptContext.getInstance().clear();
+        GroovyScriptRuntimeContext.getInstance().clearCache();
+        // 防御其他测试类泄漏的全局元数据策略
+        com.codingapi.springboot.script.strategy.GroovyMetadataGenerateStrategyContext.getInstance().clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        GroovyScriptCacheContext.getInstance().clear();
+        TempGroovyScriptContext.getInstance().clear();
+        GroovyScriptRuntimeContext.getInstance().clearCache();
+        GroovyScriptRepositoryContext.getInstance().delete("ctrl-save-key");
+        GroovyScriptRepositoryContext.getInstance().delete("ctrl-repo-save-key");
+    }
+
+    @Test
+    void compileSuccessWithoutCache() {
+        ScriptCompileRequest request = new ScriptCompileRequest();
+        request.setScript("return 1;");
+        request.setCache(false);
+
+        Response response = controller.compile(request);
+        assertTrue(response.isSuccess());
+    }
+
+    @Test
+    void compileSuccessWithCache() {
+        ScriptCompileRequest request = new ScriptCompileRequest();
+        request.setScript("return 2;");
+        request.setCache(true);
+
+        Response response = controller.compile(request);
+        assertTrue(response.isSuccess());
+        assertEquals(1, GroovyScriptRuntimeContext.getInstance().cacheSize());
+    }
+
+    @Test
+    void compileFailureShouldThrowCompileErrorException() {
+        ScriptCompileRequest request = new ScriptCompileRequest();
+        request.setScript("def {{{");
+        request.setCache(false);
+
+        LocaleMessageException exception =
+                assertThrows(LocaleMessageException.class, () -> controller.compile(request));
+        assertEquals("script.compile.error", exception.getErrCode());
+        assertTrue(exception.getErrMessage().contains("脚本编译异常"));
+    }
+
+    @Test
+    void getScriptShouldReturnContentWhenScriptExists() {
+        GroovyScriptCacheContext.getInstance().save(script("ctrl-get-key", "return 3;"));
+
+        SingleResponse<String> response = controller.getScript("ctrl-get-key");
+        assertTrue(response.isSuccess());
+        assertEquals("return 3;", response.getData());
+    }
+
+    @Test
+    void getScriptShouldThrowWhenScriptMissing() {
+        LocaleMessageException exception =
+                assertThrows(LocaleMessageException.class, () -> controller.getScript("ctrl-no-such-key"));
+        assertEquals("script.null", exception.getErrCode());
+    }
+
+    @Test
+    void getMetadataShouldReturnMetadataWhenScriptExists() {
+        GroovyScriptCacheContext.getInstance().save(script("ctrl-meta-key", "return 4;"));
+
+        SingleResponse<GroovyMetadata> response = controller.getMetadata("ctrl-meta-key");
+        assertTrue(response.isSuccess());
+        assertNotNull(response.getData());
+        assertEquals("run", response.getData().getMainMethod());
+        assertEquals("Integer", response.getData().getReturnType());
+    }
+
+    @Test
+    void getMetadataShouldThrowWhenScriptMissing() {
+        LocaleMessageException exception =
+                assertThrows(LocaleMessageException.class, () -> controller.getMetadata("ctrl-no-such-key"));
+        assertEquals("script.null", exception.getErrCode());
+    }
+
+    @Test
+    void saveShouldUpdateTempScript() {
+        GroovyScript tempScript = script("ctrl-save-key", "return 1;");
+        tempScript.temp();
+
+        ScriptSaveRequest request = new ScriptSaveRequest();
+        request.setKey("ctrl-save-key");
+        request.setScript("return 10;");
+
+        Response response = controller.save(request);
+        assertTrue(response.isSuccess());
+        assertEquals("return 10;",
+                TempGroovyScriptContext.getInstance().getGroovyScript("ctrl-save-key").getScript());
+    }
+
+    @Test
+    void saveShouldUpdatePersistentScriptWhenNotInTemp() {
+        // 仅存在于仓储中的脚本（经由缓存上下文回源获取）
+        GroovyScriptRepositoryContext.getInstance().save(script("ctrl-repo-save-key", "return 1;"));
+
+        ScriptSaveRequest request = new ScriptSaveRequest();
+        request.setKey("ctrl-repo-save-key");
+        request.setScript("return 20;");
+
+        Response response = controller.save(request);
+        assertTrue(response.isSuccess());
+
+        GroovyScript saved = GroovyScriptRepositoryContext.getInstance().get("ctrl-repo-save-key");
+        assertNotNull(saved);
+        assertEquals("return 20;", saved.getScript());
+        assertTrue(saved.getUpdateTime() > 0);
+    }
+
+    @Test
+    void saveShouldThrowWhenScriptMissing() {
+        ScriptSaveRequest request = new ScriptSaveRequest();
+        request.setKey("ctrl-no-such-key");
+        request.setScript("return 30;");
+
+        // 注意：源码中 script.null 异常被外层 catch 捕获后重新包装为 script.compile.error
+        LocaleMessageException exception =
+                assertThrows(LocaleMessageException.class, () -> controller.save(request));
+        assertEquals("script.compile.error", exception.getErrCode());
+        assertTrue(exception.getErrMessage().contains("脚本对象不存在"));
+    }
+
+    @Test
+    void saveShouldThrowCompileErrorWhenNewScriptInvalid() {
+        GroovyScript tempScript = script("ctrl-save-key", "return 1;");
+        tempScript.temp();
+
+        ScriptSaveRequest request = new ScriptSaveRequest();
+        request.setKey("ctrl-save-key");
+        request.setScript("def {{{");
+
+        LocaleMessageException exception =
+                assertThrows(LocaleMessageException.class, () -> controller.save(request));
+        assertEquals("script.compile.error", exception.getErrCode());
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/GroovyScriptRepositoryContextTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/GroovyScriptRepositoryContextTest.java
new file mode 100644
index 000000000..304c83163
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/GroovyScriptRepositoryContextTest.java
@@ -0,0 +1,70 @@
+package com.codingapi.springboot.script.repository;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.repository.impl.DefaultGroovyScriptRepository;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.Mockito.verify;
+
+/**
+ * GroovyScriptRepositoryContext 与 DefaultGroovyScriptRepository 单元测试
+ */
+class GroovyScriptRepositoryContextTest {
+
+    private final GroovyScriptRepositoryContext context = GroovyScriptRepositoryContext.getInstance();
+
+    @AfterEach
+    void tearDown() {
+        // 恢复默认仓储实现，避免 mock 泄漏到其他测试
+        context.setGroovyScriptRepository(new DefaultGroovyScriptRepository());
+    }
+
+    private GroovyScript script(String key) {
+        return GroovyScript.builder(key).script("return 1;").build();
+    }
+
+    @Test
+    void defaultRepositoryShouldSupportSaveGetDelete() {
+        context.save(script("repo-key-1"));
+
+        GroovyScript result = context.get("repo-key-1");
+        assertNotNull(result);
+        assertSame("repo-key-1", result.getKey());
+
+        context.delete("repo-key-1");
+        assertNull(context.get("repo-key-1"));
+        // 删除不存在的key不抛异常
+        context.delete("repo-key-missing");
+    }
+
+    @Test
+    void instanceShouldBeSingletonWithDefaultRepository() {
+        assertSame(context, GroovyScriptRepositoryContext.getInstance());
+        // 默认仓储可用：保存后可读取
+        context.save(script("repo-default-key"));
+        assertNotNull(context.get("repo-default-key"));
+        context.delete("repo-default-key");
+    }
+
+    @Test
+    void contextShouldDelegateToCustomRepository() {
+        GroovyScriptRepository mockRepository = Mockito.mock(GroovyScriptRepository.class);
+        GroovyScript groovyScript = script("repo-mock-key");
+        Mockito.when(mockRepository.get("repo-mock-key")).thenReturn(groovyScript);
+
+        context.setGroovyScriptRepository(mockRepository);
+
+        context.save(groovyScript);
+        assertSame(groovyScript, context.get("repo-mock-key"));
+        context.delete("repo-mock-key");
+
+        verify(mockRepository).save(groovyScript);
+        verify(mockRepository).get("repo-mock-key");
+        verify(mockRepository).delete("repo-mock-key");
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/TempGroovyScriptRepositoryContextTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/TempGroovyScriptRepositoryContextTest.java
new file mode 100644
index 000000000..becee0430
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/repository/TempGroovyScriptRepositoryContextTest.java
@@ -0,0 +1,106 @@
+package com.codingapi.springboot.script.repository;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.repository.impl.DefaultTempGroovyScriptRepository;
+import com.codingapi.springboot.script.temp.TempGroovyScript;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.verify;
+
+/**
+ * TempGroovyScriptRepositoryContext 与 DefaultTempGroovyScriptRepository 单元测试
+ * 覆盖分页查询的三个分支（整页/尾页/越界）以及上下文委托
+ */
+class TempGroovyScriptRepositoryContextTest {
+
+    private final TempGroovyScriptRepositoryContext context = TempGroovyScriptRepositoryContext.getInstance();
+
+    @AfterEach
+    void tearDown() {
+        for (int i = 0; i < 5; i++) {
+            context.delete("temp-page-" + i);
+        }
+        context.delete("temp-single");
+        context.delete("temp-mock-key");
+        // 恢复默认仓储实现，避免 mock 泄漏到其他测试
+        context.setTempGroovyScriptRepository(new DefaultTempGroovyScriptRepository());
+    }
+
+    private TempGroovyScript tempScript(String key, long clearTime) {
+        return new TempGroovyScript(GroovyScript.builder(key).script("return 1;").build(), clearTime);
+    }
+
+    @Test
+    void defaultRepositoryShouldSupportSaveGetDelete() {
+        TempGroovyScript tempGroovyScript = tempScript("temp-single", System.currentTimeMillis() + 60000);
+
+        context.save(tempGroovyScript);
+        assertSame(tempGroovyScript, context.get("temp-single"));
+
+        context.delete("temp-single");
+        assertNull(context.get("temp-single"));
+        // 删除不存在的key不抛异常
+        context.delete("temp-single-missing");
+    }
+
+    @Test
+    void findShouldReturnSortedPages() {
+        long now = System.currentTimeMillis();
+        // clearTime 乱序写入，查询应按 clearTime 升序返回
+        context.save(tempScript("temp-page-0", now + 5000));
+        context.save(tempScript("temp-page-1", now + 4000));
+        context.save(tempScript("temp-page-2", now + 3000));
+        context.save(tempScript("temp-page-3", now + 2000));
+        context.save(tempScript("temp-page-4", now + 1000));
+
+        // 第一页：满页（size > to 分支）
+        Page<TempGroovyScript> firstPage = context.find(PageRequest.of(0, 2));
+        assertEquals(5, firstPage.getTotalElements());
+        assertTrue(firstPage.hasNext());
+        List<TempGroovyScript> firstContent = firstPage.getContent();
+        assertEquals(2, firstContent.size());
+        assertEquals("temp-page-4", firstContent.get(0).getKey());
+        assertEquals("temp-page-3", firstContent.get(1).getKey());
+
+        // 尾页：不足一页（subList(form, list.size()) 分支）
+        Page<TempGroovyScript> lastPage = context.find(PageRequest.of(2, 2));
+        assertEquals(1, lastPage.getContent().size());
+        assertEquals("temp-page-0", lastPage.getContent().get(0).getKey());
+
+        // 越界页：空数据（form > list.size() 分支）
+        Page<TempGroovyScript> beyondPage = context.find(PageRequest.of(5, 2));
+        assertTrue(beyondPage.getContent().isEmpty());
+    }
+
+    @Test
+    void contextShouldDelegateToCustomRepository() {
+        TempGroovyScriptRepository mockRepository = Mockito.mock(TempGroovyScriptRepository.class);
+        TempGroovyScript tempGroovyScript = tempScript("temp-mock-key", System.currentTimeMillis() + 60000);
+        Mockito.when(mockRepository.get("temp-mock-key")).thenReturn(tempGroovyScript);
+
+        context.setTempGroovyScriptRepository(mockRepository);
+
+        context.save(tempGroovyScript);
+        assertSame(tempGroovyScript, context.get("temp-mock-key"));
+        context.delete("temp-mock-key");
+        PageRequest pageRequest = PageRequest.of(0, 10);
+        context.find(pageRequest);
+
+        verify(mockRepository).save(tempGroovyScript);
+        verify(mockRepository).get("temp-mock-key");
+        verify(mockRepository).delete("temp-mock-key");
+        verify(mockRepository).find(pageRequest);
+        assertNotNull(context);
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/runner/GroovyScriptEngineRunnerTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/runner/GroovyScriptEngineRunnerTest.java
new file mode 100644
index 000000000..fc77eacd1
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/runner/GroovyScriptEngineRunnerTest.java
@@ -0,0 +1,82 @@
+package com.codingapi.springboot.script.runner;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.repository.TempGroovyScriptRepositoryContext;
+import com.codingapi.springboot.script.temp.TempGroovyScript;
+import com.codingapi.springboot.script.temp.TempGroovyScriptContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+/**
+ * GroovyScriptEngineRunner 单元测试
+ * 覆盖启动时从仓储分页加载临时脚本、销毁时持久化临时脚本
+ */
+class GroovyScriptEngineRunnerTest {
+
+    private final GroovyScriptEngineRunner runner = new GroovyScriptEngineRunner();
+
+    private GroovyScript script(String key) {
+        return GroovyScript.builder(key).script("return 1;").build();
+    }
+
+    @BeforeEach
+    void setUp() {
+        TempGroovyScriptContext.getInstance().clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        TempGroovyScriptContext.getInstance().clear();
+        for (int i = 0; i < 150; i++) {
+            TempGroovyScriptRepositoryContext.getInstance().delete("runner-key-" + i);
+        }
+        TempGroovyScriptRepositoryContext.getInstance().delete("destroy-key-1");
+        TempGroovyScriptRepositoryContext.getInstance().delete("destroy-key-2");
+    }
+
+    @Test
+    void afterPropertiesSetShouldLoadTempScriptsFromRepository() throws Exception {
+        // 写入 150 条数据（超过单页 100 条，触发分页加载逻辑）
+        // clearTime 递增，保证按 clearTime 排序后 runner-key-0 必然在首页
+        long clearTime = System.currentTimeMillis() + 60000;
+        for (int i = 0; i < 150; i++) {
+            TempGroovyScriptRepositoryContext.getInstance()
+                    .save(new TempGroovyScript(script("runner-key-" + i), clearTime + i));
+        }
+
+        runner.afterPropertiesSet();
+
+        // 注意：源码仅在 page.hasNext() 时加载当前页，最后一页（50 条）不会加载，
+        // 疑似 bug（详见测试报告），此处按实际行为断言
+        assertEquals(100, TempGroovyScriptContext.getInstance().count());
+        assertNotNull(TempGroovyScriptContext.getInstance().getGroovyScript("runner-key-0"));
+    }
+
+    @Test
+    void afterPropertiesSetWithEmptyRepositoryShouldLoadNothing() throws Exception {
+        runner.afterPropertiesSet();
+        assertEquals(0, TempGroovyScriptContext.getInstance().count());
+    }
+
+    @Test
+    void destroyShouldSaveTempScriptsToRepository() throws Exception {
+        TempGroovyScriptContext.getInstance().save(script("destroy-key-1"));
+        TempGroovyScriptContext.getInstance().save(script("destroy-key-2"));
+
+        runner.destroy();
+
+        assertNotNull(TempGroovyScriptRepositoryContext.getInstance().get("destroy-key-1"));
+        assertNotNull(TempGroovyScriptRepositoryContext.getInstance().get("destroy-key-2"));
+    }
+
+    @Test
+    void destroyWithoutTempScriptsShouldDoNothing() throws Exception {
+        runner.destroy();
+        assertNull(TempGroovyScriptRepositoryContext.getInstance().get("destroy-key-1"));
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/DemoScriptRequest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/DemoScriptRequest.java
new file mode 100644
index 000000000..191e8ae5a
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/DemoScriptRequest.java
@@ -0,0 +1,38 @@
+package com.codingapi.springboot.script.scanner;
+
+import com.codingapi.springboot.script.annotation.ScriptField;
+import com.codingapi.springboot.script.annotation.ScriptFunction;
+import com.codingapi.springboot.script.annotation.ScriptParameter;
+import com.codingapi.springboot.script.annotation.ScriptType;
+
+/**
+ * 元数据扫描测试 fixture
+ * 覆盖 @ScriptType / @ScriptField / @ScriptFunction / @ScriptParameter 的各注解分支
+ */
+@ScriptType(description = "demo request type")
+public class DemoScriptRequest {
+
+    /**
+     * 无 name/description 覆盖的字段
+     */
+    @ScriptField
+    private String plain;
+
+    /**
+     * 有 name/description 覆盖的字段
+     */
+    @ScriptField(name = "age", description = "age description")
+    private int age;
+
+    @ScriptFunction(name = "calc", description = "calc description")
+    public int calc(@ScriptParameter(name = "num", description = "num description") int num) {
+        return num;
+    }
+
+    /**
+     * 无 description 的函数
+     */
+    @ScriptFunction(name = "noDesc")
+    public void noDesc() {
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/GroovyMetadataScannerTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/GroovyMetadataScannerTest.java
new file mode 100644
index 000000000..c437c36eb
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/scanner/GroovyMetadataScannerTest.java
@@ -0,0 +1,218 @@
+package com.codingapi.springboot.script.scanner;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.meta.GroovyField;
+import com.codingapi.springboot.script.meta.GroovyFunction;
+import com.codingapi.springboot.script.meta.GroovyMetadata;
+import com.codingapi.springboot.script.meta.GroovyType;
+import com.codingapi.springboot.script.strategy.GroovyMetadataGenerateStrategy;
+import com.codingapi.springboot.script.strategy.GroovyMetadataGenerateStrategyContext;
+import com.codingapi.springboot.script.strategy.GroovyTypeFixStrategy;
+import com.codingapi.springboot.script.strategy.GroovyTypeFixStrategyContext;
+import com.codingapi.springboot.script.strategy.ScriptTypeMapping;
+import com.codingapi.springboot.script.strategy.ScriptTypeMappingContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * GroovyMetadataScannerUtils 补充测试
+ * 覆盖注解扫描各分支、简单类型处理、策略不匹配回退等场景
+ */
+class GroovyMetadataScannerTest {
+
+    @BeforeEach
+    void setUp() {
+        GroovyMetadataGenerateStrategyContext.getInstance().clear();
+        GroovyTypeFixStrategyContext.getInstance().clear();
+        ScriptTypeMappingContext.getInstance().clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        GroovyMetadataGenerateStrategyContext.getInstance().clear();
+        GroovyTypeFixStrategyContext.getInstance().clear();
+        ScriptTypeMappingContext.getInstance().clear();
+    }
+
+    private GroovyField fieldByName(java.util.List<GroovyField> fields, String name) {
+        for (GroovyField field : fields) {
+            if (name.equals(field.getName())) {
+                return field;
+            }
+        }
+        return null;
+    }
+
+    private GroovyFunction functionByName(GroovyType type, String name) {
+        for (GroovyFunction function : type.getFunctions()) {
+            if (name.equals(function.getName())) {
+                return function;
+            }
+        }
+        return null;
+    }
+
+    @Test
+    void scannerShouldResolveAnnotationsOfComplexRequestType() {
+        Map<String, Class<?>> requests = new HashMap<>();
+        requests.put("demo", DemoScriptRequest.class);
+        // 简单类型：不会注册为 GroovyType，字段描述为空
+        requests.put("num", Integer.class);
+        Map<String, Class<?>> binds = new HashMap<>();
+        binds.put("flag", Boolean.class);
+
+        GroovyScript groovyScript = GroovyScript.builder("scanner-key")
+                .script("return 1;")
+                .description("scanner desc")
+                .method("run")
+                .returnType(String.class)
+                .requests(requests)
+                .binds(binds)
+                .build();
+
+        GroovyMetadata metadata = groovyScript.toMetadata();
+
+        assertEquals("run", metadata.getMainMethod());
+        assertEquals("scanner desc", metadata.getDescription());
+        assertEquals("String", metadata.getReturnType());
+
+        // 请求参数
+        assertEquals(2, metadata.getRequests().size());
+        GroovyField demoField = fieldByName(metadata.getRequests(), "demo");
+        assertNotNull(demoField);
+        assertEquals("DemoScriptRequest", demoField.getDataType());
+        // 类型已注册，描述取自 @ScriptType
+        assertEquals("demo request type", demoField.getDescription());
+        GroovyField numField = fieldByName(metadata.getRequests(), "num");
+        assertNotNull(numField);
+        assertEquals("Integer", numField.getDataType());
+        // 简单类型未注册，描述为空
+        assertNull(numField.getDescription());
+
+        // 绑定参数
+        assertEquals(1, metadata.getBinds().size());
+        GroovyField flagField = fieldByName(metadata.getBinds(), "flag");
+        assertNotNull(flagField);
+        assertEquals("Boolean", flagField.getDataType());
+
+        // 复合类型元数据
+        GroovyType demoType = metadata.getType("DemoScriptRequest");
+        assertNotNull(demoType);
+        assertEquals("demo request type", demoType.getDescription());
+
+        // 字段：无覆盖的 plain 保留字段名，age 使用注解 name
+        assertEquals(2, demoType.getFields().size());
+        GroovyField plain = fieldByName(demoType.getFields(), "plain");
+        assertNotNull(plain);
+        assertEquals("String", plain.getDataType());
+        assertNull(plain.getDescription());
+        GroovyField age = fieldByName(demoType.getFields(), "age");
+        assertNotNull(age);
+        assertEquals("int", age.getDataType());
+        assertEquals("age description", age.getDescription());
+
+        // 函数：calc 带描述与参数覆盖，noDesc 仅有名称
+        assertEquals(2, demoType.getFunctions().size());
+        GroovyFunction calc = functionByName(demoType, "calc");
+        assertNotNull(calc);
+        assertEquals("calc description", calc.getDescription());
+        assertEquals("int", calc.getReturnType());
+        assertEquals(1, calc.getParameters().size());
+        assertEquals("num", calc.getParameters().get(0).getName());
+        assertEquals("num description", calc.getParameters().get(0).getDescription());
+        GroovyFunction noDesc = functionByName(demoType, "noDesc");
+        assertNotNull(noDesc);
+        assertNull(noDesc.getDescription());
+        assertEquals("void", noDesc.getReturnType());
+        assertTrue(noDesc.getParameters().isEmpty());
+    }
+
+    @Test
+    void scannerShouldHandleScriptWithoutRequestBindAndReturnScanGracefully() {
+        // GroovyMetadata 构造器对 null returnType 未做防护，toMetadata 抛 NPE，
+        // 疑似 bug：GroovyMetadataHolder.scannerReturnType 有 null 判断但永远无法到达
+        GroovyScript groovyScript = GroovyScript.builder("scanner-null-return")
+                .script("return 1;")
+                .build();
+        assertThrows(NullPointerException.class, groovyScript::toMetadata);
+    }
+
+    @Test
+    void scannerShouldFallbackWhenGenerateStrategyNotSupported() {
+        GroovyMetadataGenerateStrategyContext.getInstance().addGenerateStrategy(new GroovyMetadataGenerateStrategy() {
+            @Override
+            public boolean support(GroovyScript script) {
+                return false;
+            }
+
+            @Override
+            public GroovyMetadata generate(GroovyScript script) {
+                return new GroovyMetadata("never", "never", "never");
+            }
+        });
+
+        GroovyScript groovyScript = GroovyScript.builder("scanner-fallback")
+                .script("return 1;")
+                .method("run")
+                .returnType(Integer.class)
+                .build();
+
+        GroovyMetadata metadata = groovyScript.toMetadata();
+        // 策略不匹配时走扫描逻辑
+        assertEquals("run", metadata.getMainMethod());
+        assertEquals("Integer", metadata.getReturnType());
+    }
+
+    @Test
+    void scannerShouldIgnoreNotSupportedFixStrategyAndMapping() {
+        GroovyTypeFixStrategyContext.getInstance().addFixStrategy(new GroovyTypeFixStrategy() {
+            @Override
+            public boolean support(Class<?> clazz) {
+                return false;
+            }
+
+            @Override
+            public void fix(GroovyScript groovyScript, GroovyType groovyType) {
+                groovyType.setDescription("should not happen");
+            }
+        });
+        ScriptTypeMappingContext.getInstance().addMapping(new ScriptTypeMapping() {
+            @Override
+            public boolean support(Class<?> target) {
+                return false;
+            }
+
+            @Override
+            public Class<?> mapping(Class<?> target) {
+                return Object.class;
+            }
+        });
+
+        Map<String, Class<?>> requests = new HashMap<>();
+        requests.put("demo", DemoScriptRequest.class);
+
+        GroovyScript groovyScript = GroovyScript.builder("scanner-ignore-strategy")
+                .script("return 1;")
+                .method("run")
+                .returnType(Integer.class)
+                .requests(requests)
+                .build();
+
+        GroovyMetadata metadata = groovyScript.toMetadata();
+        GroovyType demoType = metadata.getType("DemoScriptRequest");
+        assertNotNull(demoType);
+        // fix 策略未匹配，描述保持 @ScriptType 的值
+        assertEquals("demo request type", demoType.getDescription());
+        assertEquals("Integer", metadata.getReturnType());
+    }
+}
diff --git a/springboot-starter-script/src/test/java/com/codingapi/springboot/script/temp/TempGroovyScriptContextLoadTest.java b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/temp/TempGroovyScriptContextLoadTest.java
new file mode 100644
index 000000000..4feec04bb
--- /dev/null
+++ b/springboot-starter-script/src/test/java/com/codingapi/springboot/script/temp/TempGroovyScriptContextLoadTest.java
@@ -0,0 +1,126 @@
+package com.codingapi.springboot.script.temp;
+
+import com.codingapi.springboot.script.GroovyScript;
+import com.codingapi.springboot.script.repository.TempGroovyScriptRepositoryContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * TempGroovyScriptContext 补充测试
+ * 覆盖 getGroovyScript 回源仓储、loadAll 批量加载、findAll 查询
+ */
+class TempGroovyScriptContextLoadTest {
+
+    private final TempGroovyScriptContext context = TempGroovyScriptContext.getInstance();
+
+    private GroovyScript script(String key) {
+        return GroovyScript.builder(key).script("return 1;").build();
+    }
+
+    @BeforeEach
+    void setUp() {
+        context.clear();
+    }
+
+    @AfterEach
+    void tearDown() {
+        context.clear();
+        // 清理直接写入仓储的数据
+        TempGroovyScriptRepositoryContext.getInstance().delete("temp-repo-valid");
+        TempGroovyScriptRepositoryContext.getInstance().delete("temp-repo-expired");
+        TempGroovyScriptRepositoryContext.getInstance().delete("temp-load-expired");
+    }
+
+    @Test
+    void getGroovyScriptShouldReturnNullWhenAbsent() {
+        assertNull(context.getGroovyScript("temp-no-such-key"));
+    }
+
+    @Test
+    void getGroovyScriptShouldReturnSavedScript() {
+        GroovyScript groovyScript = script("temp-get-key");
+        context.save(groovyScript);
+
+        assertSame(groovyScript, context.getGroovyScript("temp-get-key"));
+        assertEquals(1, context.count());
+    }
+
+    @Test
+    void getGroovyScriptShouldReloadValidScriptFromRepository() {
+        TempGroovyScript repositoryScript =
+                new TempGroovyScript(script("temp-repo-valid"), System.currentTimeMillis() + 60000);
+        TempGroovyScriptRepositoryContext.getInstance().save(repositoryScript);
+
+        GroovyScript result = context.getGroovyScript("temp-repo-valid");
+        assertNotNull(result);
+        assertEquals("temp-repo-valid", result.getKey());
+        // 重新加载后进入内存缓存
+        assertEquals(1, context.count());
+    }
+
+    @Test
+    void getGroovyScriptShouldRemoveExpiredScriptFromRepository() {
+        TempGroovyScript expiredScript =
+                new TempGroovyScript(script("temp-repo-expired"), System.currentTimeMillis() - 1);
+        TempGroovyScriptRepositoryContext.getInstance().save(expiredScript);
+
+        assertNull(context.getGroovyScript("temp-repo-expired"));
+        assertEquals(0, context.count());
+        // 过期数据同时从仓储清理
+        assertNull(TempGroovyScriptRepositoryContext.getInstance().get("temp-repo-expired"));
+    }
+
+    @Test
+    void loadAllShouldSkipExpiredAndKeepValidScripts() {
+        // 预写一条过期数据到仓储，loadAll 时应被删除
+        TempGroovyScript expiredInRepo =
+                new TempGroovyScript(script("temp-load-expired"), System.currentTimeMillis() - 1);
+        TempGroovyScriptRepositoryContext.getInstance().save(expiredInRepo);
+
+        List<TempGroovyScript> list = new ArrayList<>();
+        list.add(new TempGroovyScript(script("temp-load-1"), System.currentTimeMillis() + 60000));
+        list.add(new TempGroovyScript(script("temp-load-2"), System.currentTimeMillis() + 60000));
+        list.add(new TempGroovyScript(script("temp-load-expired"), System.currentTimeMillis() - 1));
+
+        context.loadAll(list);
+
+        assertEquals(2, context.count());
+        assertNotNull(context.getGroovyScript("temp-load-1"));
+        assertNotNull(context.getGroovyScript("temp-load-2"));
+        assertNull(TempGroovyScriptRepositoryContext.getInstance().get("temp-load-expired"));
+    }
+
+    @Test
+    void loadAllWithNullListShouldDoNothing() {
+        context.loadAll(null);
+        assertEquals(0, context.count());
+    }
+
+    @Test
+    void findAllShouldReturnCurrentTempScripts() {
+        context.save(script("temp-find-1"));
+        context.save(script("temp-find-2"));
+
+        List<TempGroovyScript> all = context.findAll();
+        assertEquals(2, all.size());
+    }
+
+    @Test
+    void overwriteSameKeyShouldKeepSingleEntry() {
+        context.save(script("temp-overwrite"));
+        context.save(script("temp-overwrite"));
+        assertEquals(1, context.count());
+
+        context.remove("temp-overwrite");
+        assertEquals(0, context.count());
+    }
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/configurer/WebSecurityConfigurerTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/configurer/WebSecurityConfigurerTest.java
new file mode 100644
index 000000000..e84db4141
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/configurer/WebSecurityConfigurerTest.java
@@ -0,0 +1,29 @@
+package com.codingapi.springboot.security.configurer;
+
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+import org.springframework.security.config.annotation.web.builders.WebSecurity;
+
+import static org.mockito.Mockito.verify;
+
+/**
+ * WebSecurityConfigurer 单元测试
+ * <p>
+ * 通过 mock WebSecurity 验证 ignoreUrls 被注册到 ignoring 列表。
+ */
+class WebSecurityConfigurerTest {
+
+    @Test
+    void customizeRegistersIgnoreUrls() {
+        CodingApiSecurityProperties properties = new CodingApiSecurityProperties();
+        properties.setIgnoreUrls("/open/**,/public/**");
+        WebSecurityConfigurer configurer = new WebSecurityConfigurer(properties);
+
+        WebSecurity webSecurity = Mockito.mock(WebSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        configurer.customize(webSecurity);
+
+        verify(webSecurity.ignoring()).requestMatchers("/open/**", "/public/**");
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/crypto/AESToolsTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/crypto/AESToolsTest.java
new file mode 100644
index 000000000..89622feae
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/crypto/AESToolsTest.java
@@ -0,0 +1,70 @@
+package com.codingapi.springboot.security.crypto;
+
+import com.codingapi.springboot.framework.crypto.AES;
+import com.codingapi.springboot.framework.crypto.AESUtils;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * AESTools 单元测试
+ * <p>
+ * 覆盖字符串与字节数组的加解密往返逻辑。
+ * 测试类与 AESTools 同包，可调用包级私有的 init 方法。
+ */
+class AESToolsTest {
+
+    @BeforeEach
+    void setUp() throws Exception {
+        AES aes = new AES(Base64.getDecoder().decode(AESUtils.key), Base64.getDecoder().decode(AESUtils.iv));
+        AESTools.getInstance().init(aes);
+    }
+
+    @Test
+    void getInstanceReturnsSingleton() {
+        assertSame(AESTools.getInstance(), AESTools.getInstance());
+    }
+
+    @Test
+    void encodeAndDecodeStringRoundTrip() {
+        String input = "hello-世界-123456";
+
+        String encoded = AESTools.getInstance().encode(input);
+        assertNotNull(encoded);
+        assertNotEquals(input, encoded);
+
+        String decoded = AESTools.getInstance().decode(encoded);
+        assertEquals(input, decoded);
+    }
+
+    @Test
+    void encodeAndDecodeBytesRoundTrip() {
+        byte[] input = "byte-array-input-字节".getBytes(StandardCharsets.UTF_8);
+
+        byte[] encoded = AESTools.getInstance().encode(input);
+        assertNotNull(encoded);
+
+        byte[] decoded = AESTools.getInstance().decode(encoded);
+        assertArrayEquals(input, decoded);
+    }
+
+    @Test
+    void securityCryptoConfigurationInitializesTools() throws Exception {
+        AES aes = new SecurityCryptoConfiguration().aes(new CodingApiSecurityProperties());
+        assertNotNull(aes);
+
+        // 配置类初始化后 AESTools 可正常完成加解密往返
+        String encoded = AESTools.getInstance().encode("config-init");
+        assertEquals("config-init", AESTools.getInstance().decode(encoded));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/customer/DefaultHttpSecurityCustomerTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/customer/DefaultHttpSecurityCustomerTest.java
new file mode 100644
index 000000000..0b130f8be
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/customer/DefaultHttpSecurityCustomerTest.java
@@ -0,0 +1,115 @@
+package com.codingapi.springboot.security.customer;
+
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mockito;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configurers.CorsConfigurer;
+import org.springframework.security.config.annotation.web.configurers.CsrfConfigurer;
+import org.springframework.security.config.annotation.web.configurers.HeadersConfigurer;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * DefaultHttpSecurityCustomer 单元测试
+ * <p>
+ * 通过 mock HttpSecurity 覆盖 customize 中各开关的 true/false 分支，
+ * 并手动触发 cors/csrf/headers 的 Customizer lambda 以覆盖其内部分支。
+ */
+class DefaultHttpSecurityCustomerTest {
+
+    @Test
+    void customizeWithAllDisableFlagsTrue() throws Exception {
+        HttpSecurity security = mock(HttpSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        CodingApiSecurityProperties properties = new CodingApiSecurityProperties();
+
+        new DefaultHttpSecurityCustomer(properties).customize(security);
+
+        verify(security).httpBasic(any());
+        verify(security).headers(any());
+        verify(security).cors(any());
+        verify(security).csrf(any());
+    }
+
+    @Test
+    void customizeWithBasicAuthAndFrameOptionsEnabled() throws Exception {
+        HttpSecurity security = mock(HttpSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        CodingApiSecurityProperties properties = new CodingApiSecurityProperties();
+        properties.setDisableBasicAuth(false);
+        properties.setDisableFrameOptions(false);
+
+        new DefaultHttpSecurityCustomer(properties).customize(security);
+
+        verify(security, never()).httpBasic(any());
+        verify(security, never()).headers(any());
+        // cors/csrf 的 Customizer 始终会被调用，内部再根据开关决定是否 disable
+        verify(security).cors(any());
+        verify(security).csrf(any());
+    }
+
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    @Test
+    void corsAndCsrfCustomizerDisableWhenFlagsTrue() throws Exception {
+        HttpSecurity security = mock(HttpSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        CodingApiSecurityProperties properties = new CodingApiSecurityProperties();
+        new DefaultHttpSecurityCustomer(properties).customize(security);
+
+        ArgumentCaptor<Customizer> corsCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(security).cors(corsCaptor.capture());
+        CorsConfigurer corsConfigurer = mock(CorsConfigurer.class);
+        corsCaptor.getValue().customize(corsConfigurer);
+        verify(corsConfigurer).disable();
+
+        ArgumentCaptor<Customizer> csrfCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(security).csrf(csrfCaptor.capture());
+        CsrfConfigurer csrfConfigurer = mock(CsrfConfigurer.class);
+        csrfCaptor.getValue().customize(csrfConfigurer);
+        verify(csrfConfigurer).disable();
+    }
+
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    @Test
+    void corsAndCsrfCustomizerKeepEnabledWhenFlagsFalse() throws Exception {
+        HttpSecurity security = mock(HttpSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        CodingApiSecurityProperties properties = new CodingApiSecurityProperties();
+        properties.setDisableCors(false);
+        properties.setDisableCsrf(false);
+        new DefaultHttpSecurityCustomer(properties).customize(security);
+
+        ArgumentCaptor<Customizer> corsCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(security).cors(corsCaptor.capture());
+        CorsConfigurer corsConfigurer = mock(CorsConfigurer.class);
+        corsCaptor.getValue().customize(corsConfigurer);
+        verify(corsConfigurer, never()).disable();
+
+        ArgumentCaptor<Customizer> csrfCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(security).csrf(csrfCaptor.capture());
+        CsrfConfigurer csrfConfigurer = mock(CsrfConfigurer.class);
+        csrfCaptor.getValue().customize(csrfConfigurer);
+        verify(csrfConfigurer, never()).disable();
+    }
+
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    @Test
+    void headersCustomizerDisablesFrameOptions() throws Exception {
+        HttpSecurity security = mock(HttpSecurity.class, Mockito.RETURNS_DEEP_STUBS);
+        new DefaultHttpSecurityCustomer(new CodingApiSecurityProperties()).customize(security);
+
+        ArgumentCaptor<Customizer> headersCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(security).headers(headersCaptor.capture());
+        HeadersConfigurer headersConfigurer = mock(HeadersConfigurer.class);
+        headersCaptor.getValue().customize(headersConfigurer);
+
+        ArgumentCaptor<Customizer> frameOptionsCaptor = ArgumentCaptor.forClass(Customizer.class);
+        verify(headersConfigurer).frameOptions(frameOptionsCaptor.capture());
+        HeadersConfigurer.FrameOptionsConfig frameOptionsConfig = mock(HeadersConfigurer.FrameOptionsConfig.class);
+        frameOptionsCaptor.getValue().customize(frameOptionsConfig);
+        verify(frameOptionsConfig).disable();
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestContextTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestContextTest.java
new file mode 100644
index 000000000..eaf352f85
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestContextTest.java
@@ -0,0 +1,39 @@
+package com.codingapi.springboot.security.dto.request;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * LoginRequestContext 单元测试
+ * <p>
+ * 覆盖单例获取与 ThreadLocal 的 set/get/clean 行为。
+ */
+class LoginRequestContextTest {
+
+    @AfterEach
+    void tearDown() {
+        LoginRequestContext.getInstance().clean();
+    }
+
+    @Test
+    void getInstanceReturnsSingleton() {
+        assertSame(LoginRequestContext.getInstance(), LoginRequestContext.getInstance());
+    }
+
+    @Test
+    void setGetAndClean() {
+        LoginRequestContext context = LoginRequestContext.getInstance();
+        LoginRequest request = new LoginRequest();
+        request.put("username", "admin");
+
+        context.set(request);
+        assertSame(request, context.get());
+
+        context.clean();
+        assertNull(context.get());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestTest.java
new file mode 100644
index 000000000..d7cb735d3
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/dto/request/LoginRequestTest.java
@@ -0,0 +1,58 @@
+package com.codingapi.springboot.security.dto.request;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * LoginRequest 单元测试
+ * <p>
+ * 覆盖 isEmpty 校验、字符串取值以及 getBoolean 的默认值回退逻辑。
+ */
+class LoginRequestTest {
+
+    @Test
+    void isEmptyChecksUsernameAndPassword() {
+        LoginRequest request = new LoginRequest();
+        assertTrue(request.isEmpty());
+
+        request.put("username", "admin");
+        assertTrue(request.isEmpty());
+
+        request.put("password", "123456");
+        assertFalse(request.isEmpty());
+        assertEquals("admin", request.getUsername());
+        assertEquals("123456", request.getPassword());
+        assertEquals("admin", request.getString("username"));
+        assertNull(request.getString("missing"));
+    }
+
+    @Test
+    void getBooleanReturnsValueWhenPresent() {
+        LoginRequest request = new LoginRequest();
+        request.put("remember", Boolean.TRUE);
+
+        assertTrue(request.getBoolean("remember", false));
+    }
+
+    @Test
+    void getBooleanReturnsDefaultWhenTypeMismatch() {
+        LoginRequest request = new LoginRequest();
+        request.put("text", "not-a-boolean");
+
+        assertFalse(request.getBoolean("text", false));
+        assertTrue(request.getBoolean("text", true));
+    }
+
+    @Test
+    void getBooleanReturnsDefaultWhenKeyMissing() {
+        LoginRequest request = new LoginRequest();
+
+        assertTrue(request.getBoolean("missing", true));
+        assertFalse(request.getBoolean("missing", false));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAccessDeniedHandlerTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAccessDeniedHandlerTest.java
new file mode 100644
index 000000000..6925dd1ce
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAccessDeniedHandlerTest.java
@@ -0,0 +1,37 @@
+package com.codingapi.springboot.security.filter;
+
+import com.alibaba.fastjson.JSONObject;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.security.access.AccessDeniedException;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+/**
+ * MyAccessDeniedHandler 单元测试
+ * <p>
+ * 直接调用 handle 方法，验证 403 场景下写出的 JSON 响应内容。
+ */
+class MyAccessDeniedHandlerTest {
+
+    @Test
+    void handleWritesAccessDeniedJsonResponse() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        new MyAccessDeniedHandler().handle(request, response, new AccessDeniedException("denied"));
+
+        assertEquals("application/json;charset=UTF-8", response.getContentType());
+        assertEquals("UTF-8", response.getCharacterEncoding());
+
+        JSONObject json = JSONObject.parseObject(response.getContentAsString(StandardCharsets.UTF_8));
+        assertEquals("not.access", json.getString("errCode"));
+        assertEquals("please check user authentication.", json.getString("errMessage"));
+        assertFalse(json.getBooleanValue("success"));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAuthenticationFilterTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAuthenticationFilterTest.java
new file mode 100644
index 000000000..bcbc776c4
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyAuthenticationFilterTest.java
@@ -0,0 +1,177 @@
+package com.codingapi.springboot.security.filter;
+
+import com.alibaba.fastjson.JSONObject;
+import com.codingapi.springboot.security.gateway.Token;
+import com.codingapi.springboot.security.gateway.TokenGateway;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import jakarta.servlet.FilterChain;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * MyAuthenticationFilter 单元测试
+ * <p>
+ * 通过 mock TokenGateway 覆盖 doFilterInternal 的各分支：
+ * 缺少 token、token 解析为 null、解析异常、正常通过、token 重置、过期 token 等。
+ */
+class MyAuthenticationFilterTest {
+
+    private TokenGateway tokenGateway;
+    private AuthenticationTokenFilter authenticationTokenFilter;
+    private MyAuthenticationFilter filter;
+
+    @BeforeEach
+    void setUp() {
+        tokenGateway = mock(TokenGateway.class);
+        authenticationTokenFilter = mock(AuthenticationTokenFilter.class);
+        filter = new MyAuthenticationFilter(mock(AuthenticationManager.class),
+                new CodingApiSecurityProperties(), tokenGateway, authenticationTokenFilter);
+        SecurityContextHolder.clearContext();
+    }
+
+    @AfterEach
+    void tearDown() {
+        SecurityContextHolder.clearContext();
+    }
+
+    private JSONObject bodyJson(MockHttpServletResponse response) throws Exception {
+        return JSONObject.parseObject(response.getContentAsString(StandardCharsets.UTF_8));
+    }
+
+    @Test
+    void missingAuthorizationHeaderWritesTokenError() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+
+        filter.doFilterInternal(request, response, chain);
+
+        assertEquals("token.error", bodyJson(response).getString("errCode"));
+        verify(chain, never()).doFilter(any(), any());
+    }
+
+    @Test
+    void parserReturnsNullWritesTokenExpire() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        request.addHeader("Authorization", "token-value");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+        when(tokenGateway.parser("token-value")).thenReturn(null);
+
+        filter.doFilterInternal(request, response, chain);
+
+        assertEquals("token.expire", bodyJson(response).getString("errCode"));
+        verify(chain, never()).doFilter(any(), any());
+    }
+
+    @Test
+    void parserThrowsExceptionWritesTokenExpire() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        request.addHeader("Authorization", "bad-token");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+        when(tokenGateway.parser("bad-token")).thenThrow(new RuntimeException("parser fail"));
+
+        filter.doFilterInternal(request, response, chain);
+
+        assertEquals("token.expire", bodyJson(response).getString("errCode"));
+        verify(chain, never()).doFilter(any(), any());
+    }
+
+    @Test
+    void expiredTokenWritesTokenExpire() throws Exception {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        Token token = new Token("admin", null, null, authorities, -1000, -1000);
+        token.setToken("expired-token");
+
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        request.addHeader("Authorization", "expired-token");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+        when(tokenGateway.parser("expired-token")).thenReturn(token);
+
+        filter.doFilterInternal(request, response, chain);
+
+        assertEquals("token.expire", bodyJson(response).getString("errCode"));
+        verify(chain, never()).doFilter(any(), any());
+    }
+
+    @Test
+    void validTokenSetsSecurityContextAndContinuesChain() throws Exception {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        Token token = new Token("admin", null, "{\"channel\":\"pc\"}", authorities, 900000, 600000);
+        token.setToken("token-value");
+
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        request.addHeader("Authorization", "token-value");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+        when(tokenGateway.parser("token-value")).thenReturn(token);
+
+        filter.doFilterInternal(request, response, chain);
+
+        verify(chain).doFilter(request, response);
+        verify(authenticationTokenFilter).doFilter(request, response);
+        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+        assertNotNull(authentication);
+        assertSame(token, authentication.getPrincipal());
+        assertEquals(1, authentication.getAuthorities().size());
+    }
+
+    @Test
+    void restableTokenTriggersResetAndSetsResponseHeader() throws Exception {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        // remindTime 已过期而 token 未过期 -> canRestToken() 返回 true
+        Token token = new Token("admin", null, null, authorities, 900000, -1000);
+        token.setToken("old-token");
+        Token newToken = new Token("admin", null, null, authorities, 900000, 600000);
+        newToken.setToken("new-token");
+
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/api/hello");
+        request.addHeader("Authorization", "old-token");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+        when(tokenGateway.parser("old-token")).thenReturn(token);
+        when(tokenGateway.create(eq("admin"), isNull(), eq(authorities), isNull())).thenReturn(newToken);
+
+        filter.doFilterInternal(request, response, chain);
+
+        assertEquals("new-token", response.getHeader("Authorization"));
+        verify(chain).doFilter(request, response);
+    }
+
+    @Test
+    void notMatchedUrlSkipsTokenCheck() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest("GET", "/open/hello");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        FilterChain chain = mock(FilterChain.class);
+
+        filter.doFilterInternal(request, response, chain);
+
+        verify(chain).doFilter(request, response);
+        verify(tokenGateway, never()).parser(anyString());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLoginFilterTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLoginFilterTest.java
new file mode 100644
index 000000000..24a59b56a
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLoginFilterTest.java
@@ -0,0 +1,121 @@
+package com.codingapi.springboot.security.filter;
+
+import com.codingapi.springboot.security.dto.request.LoginRequest;
+import com.codingapi.springboot.security.dto.request.LoginRequestContext;
+import com.codingapi.springboot.security.gateway.TokenGateway;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import jakarta.servlet.http.HttpServletRequest;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.authentication.AuthenticationServiceException;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * MyLoginFilter 单元测试
+ * <p>
+ * 覆盖 attemptAuthentication 的各异常分支（空请求体、空登录参数、
+ * 流读取失败、preHandle 异常）以及正常认证路径。
+ */
+class MyLoginFilterTest {
+
+    private AuthenticationManager authenticationManager;
+    private SecurityLoginHandler loginHandler;
+    private MyLoginFilter filter;
+
+    @BeforeEach
+    void setUp() {
+        authenticationManager = mock(AuthenticationManager.class);
+        TokenGateway tokenGateway = mock(TokenGateway.class);
+        loginHandler = mock(SecurityLoginHandler.class);
+        filter = new MyLoginFilter(authenticationManager, tokenGateway, loginHandler,
+                new CodingApiSecurityProperties());
+    }
+
+    @AfterEach
+    void tearDown() {
+        LoginRequestContext.getInstance().clean();
+    }
+
+    private MockHttpServletRequest jsonRequest(String body) {
+        MockHttpServletRequest request = new MockHttpServletRequest("POST", "/user/login");
+        request.setContent(body.getBytes(StandardCharsets.UTF_8));
+        return request;
+    }
+
+    @Test
+    void attemptAuthenticationWithNullBodyThrowsServiceException() {
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        assertThrows(AuthenticationServiceException.class,
+                () -> filter.attemptAuthentication(jsonRequest("null"), response));
+    }
+
+    @Test
+    void attemptAuthenticationWithEmptyLoginRequestThrowsServiceException() {
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        assertThrows(AuthenticationServiceException.class,
+                () -> filter.attemptAuthentication(jsonRequest("{}"), response));
+    }
+
+    @Test
+    void attemptAuthenticationWhenStreamReadFailsThrowsServiceException() throws Exception {
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getInputStream()).thenThrow(new IOException("stream read fail"));
+
+        assertThrows(AuthenticationServiceException.class,
+                () -> filter.attemptAuthentication(request, new MockHttpServletResponse()));
+    }
+
+    @Test
+    void attemptAuthenticationWhenPreHandleFailsThrowsServiceException() throws Exception {
+        doThrow(new IllegalStateException("pre handle fail"))
+                .when(loginHandler).preHandle(any(), any(), any(LoginRequest.class));
+        String body = "{\"username\":\"admin\",\"password\":\"123456\"}";
+
+        assertThrows(AuthenticationServiceException.class,
+                () -> filter.attemptAuthentication(jsonRequest(body), new MockHttpServletResponse()));
+    }
+
+    @Test
+    void attemptAuthenticationSuccessDelegatesToAuthenticationManager() {
+        Authentication authentication = mock(Authentication.class);
+        when(authenticationManager.authenticate(any(Authentication.class))).thenReturn(authentication);
+        String body = "{\"username\":\"admin\",\"password\":\"123456\"}";
+
+        Authentication result = filter.attemptAuthentication(jsonRequest(body), new MockHttpServletResponse());
+
+        assertSame(authentication, result);
+
+        ArgumentCaptor<UsernamePasswordAuthenticationToken> captor =
+                ArgumentCaptor.forClass(UsernamePasswordAuthenticationToken.class);
+        verify(authenticationManager).authenticate(captor.capture());
+        assertEquals("admin", captor.getValue().getName());
+        assertEquals("123456", captor.getValue().getCredentials());
+
+        // 登录请求被放入线程上下文
+        LoginRequest context = LoginRequestContext.getInstance().get();
+        assertNotNull(context);
+        assertEquals("admin", context.getUsername());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutHandlerTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutHandlerTest.java
new file mode 100644
index 000000000..c48f9f9aa
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutHandlerTest.java
@@ -0,0 +1,22 @@
+package com.codingapi.springboot.security.filter;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+
+/**
+ * MyLogoutHandler 单元测试
+ * <p>
+ * logout 为空实现，仅验证调用不抛异常。
+ */
+class MyLogoutHandlerTest {
+
+    @Test
+    void logoutDoesNotThrow() {
+        assertDoesNotThrow(() -> new MyLogoutHandler()
+                .logout(new MockHttpServletRequest(), new MockHttpServletResponse(), null));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutSuccessHandlerTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutSuccessHandlerTest.java
new file mode 100644
index 000000000..2583f5816
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyLogoutSuccessHandlerTest.java
@@ -0,0 +1,34 @@
+package com.codingapi.springboot.security.filter;
+
+import com.alibaba.fastjson.JSONObject;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * MyLogoutSuccessHandler 单元测试
+ * <p>
+ * 直接调用 onLogoutSuccess 方法，验证退出成功后写出的 JSON 响应内容。
+ */
+class MyLogoutSuccessHandlerTest {
+
+    @Test
+    void onLogoutSuccessWritesSuccessJsonResponse() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        new MyLogoutSuccessHandler().onLogoutSuccess(request, response, null);
+
+        assertEquals("application/json;charset=UTF-8", response.getContentType());
+        assertEquals("UTF-8", response.getCharacterEncoding());
+
+        JSONObject json = JSONObject.parseObject(response.getContentAsString(StandardCharsets.UTF_8));
+        assertTrue(json.getBooleanValue("success"));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyUnAuthenticationEntryPointTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyUnAuthenticationEntryPointTest.java
new file mode 100644
index 000000000..92ded9fdf
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/filter/MyUnAuthenticationEntryPointTest.java
@@ -0,0 +1,48 @@
+package com.codingapi.springboot.security.filter;
+
+import com.alibaba.fastjson.JSONObject;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+/**
+ * MyUnAuthenticationEntryPoint 单元测试
+ * <p>
+ * 直接调用 commence 方法，验证 401 场景下写出的 JSON 响应内容。
+ */
+class MyUnAuthenticationEntryPointTest {
+
+    @Test
+    void commenceWritesNotLoginJsonResponse() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        new MyUnAuthenticationEntryPoint().commence(request, response,
+                new InsufficientAuthenticationExceptionForTest("not authenticated"));
+
+        assertEquals("application/json;charset=UTF-8", response.getContentType());
+        assertEquals("UTF-8", response.getCharacterEncoding());
+
+        JSONObject json = JSONObject.parseObject(response.getContentAsString(StandardCharsets.UTF_8));
+        assertEquals("not.login", json.getString("errCode"));
+        assertEquals("please to login.", json.getString("errMessage"));
+        assertFalse(json.getBooleanValue("success"));
+    }
+
+    /**
+     * 简单的 AuthenticationException 实现，用于触发 commence 逻辑
+     */
+    private static class InsufficientAuthenticationExceptionForTest
+            extends org.springframework.security.core.AuthenticationException {
+
+        InsufficientAuthenticationExceptionForTest(String msg) {
+            super(msg);
+        }
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenContextTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenContextTest.java
new file mode 100644
index 000000000..c5b74110c
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenContextTest.java
@@ -0,0 +1,45 @@
+package com.codingapi.springboot.security.gateway;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+import java.util.Collections;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * TokenContext 单元测试
+ * <p>
+ * 覆盖 ThreadLocal extra 的读写以及从 SecurityContext 中获取当前 Token。
+ */
+class TokenContextTest {
+
+    @AfterEach
+    void tearDown() {
+        SecurityContextHolder.clearContext();
+    }
+
+    @Test
+    void pushExtraAndGetExtra() {
+        TokenContext.pushExtra("extra-value");
+        assertEquals("extra-value", TokenContext.getExtra());
+
+        TokenContext.pushExtra(null);
+        assertNull(TokenContext.getExtra());
+    }
+
+    @Test
+    void currentReturnsTokenFromSecurityContext() {
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+        UsernamePasswordAuthenticationToken authentication =
+                new UsernamePasswordAuthenticationToken(token, null, Collections.emptyList());
+        SecurityContextHolder.getContext().setAuthentication(authentication);
+
+        assertSame(token, TokenContext.current());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenUnitTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenUnitTest.java
new file mode 100644
index 000000000..b509da058
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/gateway/TokenUnitTest.java
@@ -0,0 +1,118 @@
+package com.codingapi.springboot.security.gateway;
+
+import com.codingapi.springboot.security.crypto.SecurityCryptoConfiguration;
+import com.codingapi.springboot.security.exception.TokenExpiredException;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Token 单元测试
+ * <p>
+ * 覆盖构造、iv 加解密往返、过期校验、重置判断、extra 解析、
+ * 认证凭据转换等逻辑。
+ */
+class TokenUnitTest {
+
+    @BeforeAll
+    static void initCrypto() throws Exception {
+        // Token 构造时会通过 AESTools 加密 iv，单元测试环境需要先完成初始化
+        new SecurityCryptoConfiguration().aes(new CodingApiSecurityProperties());
+    }
+
+    @AfterEach
+    void tearDown() {
+        SecurityContextHolder.clearContext();
+    }
+
+    @Test
+    void constructorWithIvEncryptsAndDecodeRoundTrip() {
+        List<String> authorities = Arrays.asList("ADMIN", "USER");
+        Token token = new Token("admin", "123456", "{\"name\":\"test\"}", authorities, 900000, 600000);
+
+        assertEquals("admin", token.getUsername());
+        assertEquals("123456", token.decodeIv());
+        assertEquals(authorities, token.getAuthorities());
+        assertFalse(token.isExpire());
+        assertEquals("test", token.parseExtra(Map.class).get("name"));
+    }
+
+    @Test
+    void nullIvAndNullExtraReturnNull() {
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+
+        assertNull(token.decodeIv());
+        assertNull(token.parseExtra(Map.class));
+    }
+
+    @Test
+    void expiredTokenVerifyThrowsException() {
+        Token expired = new Token("admin", null, null, Collections.singletonList("ADMIN"), -1000, -1000);
+
+        assertTrue(expired.isExpire());
+        assertFalse(expired.canRestToken());
+        TokenExpiredException exception = assertThrows(TokenExpiredException.class, expired::verify);
+        assertEquals("token expired.", exception.getMessage());
+    }
+
+    @Test
+    void validTokenVerifyPassesAndCannotRest() throws TokenExpiredException {
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+
+        token.verify();
+        assertFalse(token.canRestToken());
+    }
+
+    @Test
+    void restableTokenWhenRemindTimeReached() {
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, -1000);
+
+        assertFalse(token.isExpire());
+        assertTrue(token.canRestToken());
+    }
+
+    @Test
+    void getAuthenticationTokenBuildsAuthoritiesAndPushesExtra() {
+        Token token = new Token("admin", "iv-value", "{\"channel\":\"pc\"}",
+                Arrays.asList("ADMIN", "USER"), 900000, 600000);
+
+        UsernamePasswordAuthenticationToken authentication = token.getAuthenticationToken();
+
+        assertSame(token, authentication.getPrincipal());
+        assertEquals(2, authentication.getAuthorities().size());
+        assertEquals("{\"channel\":\"pc\"}", TokenContext.getExtra());
+    }
+
+    @Test
+    void defaultConstructorAndSetters() {
+        Token token = new Token();
+        token.setUsername("user");
+        token.setToken("token-value");
+        token.setExtra("{}");
+        token.setAuthorities(Collections.singletonList("USER"));
+        token.setExpireTime(System.currentTimeMillis() + 900000);
+        token.setRemindTime(System.currentTimeMillis() + 600000);
+
+        assertEquals("user", token.getUsername());
+        assertEquals("token-value", token.getToken());
+        assertEquals("{}", token.getExtra());
+        assertFalse(token.isExpire());
+        assertFalse(token.canRestToken());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JWTSecurityConfigurationTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JWTSecurityConfigurationTest.java
new file mode 100644
index 000000000..4aee284a5
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JWTSecurityConfigurationTest.java
@@ -0,0 +1,32 @@
+package com.codingapi.springboot.security.jwt;
+
+import com.codingapi.springboot.security.gateway.TokenGateway;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * JWTSecurityConfiguration 单元测试
+ * <p>
+ * 直接调用配置类的 Bean 工厂方法，验证各 Bean 的创建逻辑。
+ */
+class JWTSecurityConfigurationTest {
+
+    @Test
+    void beanFactoryMethodsCreateExpectedBeans() {
+        JWTSecurityConfiguration configuration = new JWTSecurityConfiguration();
+
+        SecurityJWTProperties properties = configuration.securityJWTProperties();
+        assertNotNull(properties);
+        assertTrue(properties.isEnable());
+
+        JwtTokenGateway jwtTokenGateway = configuration.jwtTokenGateway(properties);
+        assertNotNull(jwtTokenGateway);
+
+        TokenGateway tokenGateway = configuration.jwtTokenGatewayImpl(jwtTokenGateway);
+        assertNotNull(tokenGateway);
+        assertTrue(tokenGateway instanceof JWTTokenGatewayImpl);
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JwtTokenGatewayTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JwtTokenGatewayTest.java
new file mode 100644
index 000000000..69e14955e
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/JwtTokenGatewayTest.java
@@ -0,0 +1,105 @@
+package com.codingapi.springboot.security.jwt;
+
+import com.codingapi.springboot.framework.exception.LocaleMessageException;
+import com.codingapi.springboot.security.crypto.SecurityCryptoConfiguration;
+import com.codingapi.springboot.security.exception.TokenExpiredException;
+import com.codingapi.springboot.security.gateway.Token;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/**
+ * JwtTokenGateway 单元测试
+ * <p>
+ * 覆盖各 create 重载与 JWT 签发/解析的往返逻辑，以及非法 token 的异常分支。
+ */
+class JwtTokenGatewayTest {
+
+    private JwtTokenGateway gateway;
+
+    @BeforeAll
+    static void initCrypto() throws Exception {
+        // Token 构造时会通过 AESTools 加密 iv，单元测试环境需要先完成初始化
+        new SecurityCryptoConfiguration().aes(new CodingApiSecurityProperties());
+    }
+
+    @BeforeEach
+    void setUp() {
+        gateway = new JwtTokenGateway(new SecurityJWTProperties());
+    }
+
+    @Test
+    void createWithAllParamsAndParserRoundTrip() throws TokenExpiredException {
+        List<String> authorities = Arrays.asList("ADMIN", "USER");
+        TestVO extra = new TestVO("test-name");
+
+        Token token = gateway.create("admin", "123456", authorities, extra.toJson());
+        assertNotNull(token.getToken());
+        token.verify();
+
+        Token parsed = gateway.parser(token.getToken());
+        assertEquals("admin", parsed.getUsername());
+        assertEquals("123456", parsed.decodeIv());
+        assertEquals(authorities, parsed.getAuthorities());
+        assertEquals("test-name", parsed.parseExtra(TestVO.class).getName());
+    }
+
+    @Test
+    void createOverloadWithAuthoritiesOnly() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+
+        Token token = gateway.create("admin", authorities);
+
+        Token parsed = gateway.parser(token.getToken());
+        assertEquals("admin", parsed.getUsername());
+        assertEquals(authorities, parsed.getAuthorities());
+    }
+
+    @Test
+    void createOverloadWithAuthoritiesAndExtra() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        TestVO extra = new TestVO("extra-name");
+
+        Token token = gateway.create("admin", authorities, extra.toJson());
+
+        Token parsed = gateway.parser(token.getToken());
+        assertEquals("admin", parsed.getUsername());
+        assertEquals("extra-name", parsed.parseExtra(TestVO.class).getName());
+    }
+
+    @Test
+    void createOverloadWithIvAndAuthorities() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+
+        Token token = gateway.create("admin", "123456", authorities);
+
+        Token parsed = gateway.parser(token.getToken());
+        assertEquals("admin", parsed.getUsername());
+        assertEquals("123456", parsed.decodeIv());
+    }
+
+    @Test
+    void parserWithInvalidTokenThrowsLocaleMessageException() {
+        assertThrows(LocaleMessageException.class, () -> gateway.parser("invalid.jwt.token"));
+    }
+
+    @Test
+    void parserWithTokenSignedByOtherKeyThrowsException() {
+        SecurityJWTProperties otherProperties = new SecurityJWTProperties();
+        otherProperties.setSecretKey("another-secret-key-must-longer-than-32-chars");
+        JwtTokenGateway otherGateway = new JwtTokenGateway(otherProperties);
+        Token token = otherGateway.create("admin", Collections.singletonList("ADMIN"));
+
+        assertThrows(LocaleMessageException.class, () -> gateway.parser(token.getToken()));
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/SecurityJWTPropertiesTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/SecurityJWTPropertiesTest.java
new file mode 100644
index 000000000..1ce6b6b76
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/jwt/SecurityJWTPropertiesTest.java
@@ -0,0 +1,40 @@
+package com.codingapi.springboot.security.jwt;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * SecurityJWTProperties 单元测试
+ * <p>
+ * 校验默认值与 setter/getter 行为。
+ */
+class SecurityJWTPropertiesTest {
+
+    @Test
+    void defaultValues() {
+        SecurityJWTProperties properties = new SecurityJWTProperties();
+
+        assertTrue(properties.isEnable());
+        assertEquals("codingapi.security.jwt.secretkey", properties.getSecretKey());
+        assertEquals(900000, properties.getValidTime());
+        assertEquals(600000, properties.getRestTime());
+    }
+
+    @Test
+    void settersAndGetters() {
+        SecurityJWTProperties properties = new SecurityJWTProperties();
+        properties.setEnable(false);
+        properties.setSecretKey("changed-secret-key");
+        properties.setValidTime(1000);
+        properties.setRestTime(500);
+
+        assertFalse(properties.isEnable());
+        assertEquals("changed-secret-key", properties.getSecretKey());
+        assertEquals(1000, properties.getValidTime());
+        assertEquals(500, properties.getRestTime());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisSecurityConfigurationTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisSecurityConfigurationTest.java
new file mode 100644
index 000000000..059d5e5d4
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisSecurityConfigurationTest.java
@@ -0,0 +1,37 @@
+package com.codingapi.springboot.security.redis;
+
+import com.codingapi.springboot.security.gateway.TokenGateway;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.redis.core.RedisTemplate;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+
+/**
+ * RedisSecurityConfiguration 单元测试
+ * <p>
+ * 直接调用配置类的 Bean 工厂方法（RedisTemplate 使用 mock），
+ * 验证各 Bean 的创建逻辑。
+ */
+class RedisSecurityConfigurationTest {
+
+    @SuppressWarnings("unchecked")
+    @Test
+    void beanFactoryMethodsCreateExpectedBeans() {
+        RedisSecurityConfiguration configuration = new RedisSecurityConfiguration();
+
+        SecurityRedisProperties properties = configuration.securityRedisProperties();
+        assertNotNull(properties);
+        assertTrue(properties.isEnable());
+
+        RedisTemplate<String, String> redisTemplate = mock(RedisTemplate.class);
+        RedisTokenGateway redisTokenGateway = configuration.redisTokenGateway(redisTemplate, properties);
+        assertNotNull(redisTokenGateway);
+
+        TokenGateway tokenGateway = configuration.redisTokenGatewayImpl(redisTokenGateway);
+        assertNotNull(tokenGateway);
+        assertTrue(tokenGateway instanceof RedisTokenGatewayImpl);
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayImplTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayImplTest.java
new file mode 100644
index 000000000..c9593f78b
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayImplTest.java
@@ -0,0 +1,67 @@
+package com.codingapi.springboot.security.redis;
+
+import com.codingapi.springboot.security.gateway.Token;
+import com.codingapi.springboot.security.gateway.TokenGateway;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * RedisTokenGatewayImpl 单元测试
+ * <p>
+ * 验证其对 RedisTokenGateway 的委托行为以及 TokenGateway 默认方法。
+ */
+class RedisTokenGatewayImplTest {
+
+    private RedisTokenGateway redisTokenGateway;
+    private RedisTokenGatewayImpl gatewayImpl;
+
+    @BeforeEach
+    void setUp() {
+        redisTokenGateway = mock(RedisTokenGateway.class);
+        gatewayImpl = new RedisTokenGatewayImpl(redisTokenGateway);
+    }
+
+    @Test
+    void createDelegatesToRedisTokenGateway() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        Token expected = new Token("admin", null, null, authorities, 900000, 600000);
+        when(redisTokenGateway.create("admin", "123456", authorities, "extra")).thenReturn(expected);
+
+        Token token = gatewayImpl.create("admin", "123456", authorities, "extra");
+
+        assertSame(expected, token);
+    }
+
+    @Test
+    void parserDelegatesToGetToken() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        Token expected = new Token("admin", null, null, authorities, 900000, 600000);
+        when(redisTokenGateway.getToken("token-sign")).thenReturn(expected);
+
+        Token token = gatewayImpl.parser("token-sign");
+
+        assertSame(expected, token);
+    }
+
+    @Test
+    void tokenGatewayDefaultMethodsDelegateToFullCreate() {
+        List<String> authorities = Collections.singletonList("ADMIN");
+        Token expected = new Token("user", null, null, authorities, 900000, 600000);
+        when(redisTokenGateway.create("user", null, authorities, null)).thenReturn(expected);
+
+        TokenGateway gateway = gatewayImpl;
+        assertSame(expected, gateway.create("user", authorities));
+        assertSame(expected, gateway.create("user", authorities, null));
+        assertSame(expected, gateway.create("user", null, authorities));
+        assertTrue(gateway instanceof RedisTokenGatewayImpl);
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayTest.java
new file mode 100644
index 000000000..025a0e027
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/RedisTokenGatewayTest.java
@@ -0,0 +1,200 @@
+package com.codingapi.springboot.security.redis;
+
+import com.codingapi.springboot.framework.crypto.AESUtils;
+import com.codingapi.springboot.security.crypto.SecurityCryptoConfiguration;
+import com.codingapi.springboot.security.gateway.Token;
+import com.codingapi.springboot.security.properties.CodingApiSecurityProperties;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.core.ValueOperations;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.TimeUnit;
+import java.util.function.Predicate;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyCollection;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * RedisTokenGateway 单元测试
+ * <p>
+ * 通过 mock RedisTemplate/ValueOperations 验证 token 的创建、解析、删除、
+ * 重置以及按用户名清理等逻辑，不依赖真实 Redis 连接。
+ */
+class RedisTokenGatewayTest {
+
+    private RedisTemplate<String, String> redisTemplate;
+    private ValueOperations<String, String> valueOperations;
+    private SecurityRedisProperties properties;
+    private RedisTokenGateway gateway;
+
+    @BeforeAll
+    static void initCrypto() throws Exception {
+        // Token 构造时会通过 AESTools 加密 iv，单元测试环境需要先完成初始化
+        new SecurityCryptoConfiguration().aes(new CodingApiSecurityProperties());
+    }
+
+    @SuppressWarnings("unchecked")
+    @BeforeEach
+    void setUp() {
+        redisTemplate = mock(RedisTemplate.class);
+        valueOperations = mock(ValueOperations.class);
+        when(redisTemplate.opsForValue()).thenReturn(valueOperations);
+        properties = new SecurityRedisProperties();
+        gateway = new RedisTokenGateway(redisTemplate, properties);
+    }
+
+    @Test
+    void createTokenStoresJsonWithValidTime() throws Exception {
+        List<String> authorities = Arrays.asList("ADMIN", "USER");
+
+        Token token = gateway.create("admin", "123456", authorities, "{\"name\":\"test\"}");
+
+        assertNotNull(token.getToken());
+        assertEquals("admin", token.getUsername());
+        assertEquals("123456", token.decodeIv());
+        assertEquals(authorities, token.getAuthorities());
+        // key 由 AES 加密后的用户名 + ":" + 随机 UUID 组成
+        String encodedUsername = AESUtils.getInstance().encode("admin");
+        assertTrue(token.getToken().startsWith(encodedUsername + ":"));
+
+        verify(valueOperations).set(eq(token.getToken()), eq(token.toJson()),
+                eq((long) properties.getValidTime()), eq(TimeUnit.MILLISECONDS));
+    }
+
+    @Test
+    void getTokenWhenPresent() {
+        Token source = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+        source.setToken("token-key");
+        when(valueOperations.get("token-key")).thenReturn(source.toJson());
+
+        Token token = gateway.getToken("token-key");
+
+        assertNotNull(token);
+        assertEquals("admin", token.getUsername());
+        assertEquals(source.getAuthorities(), token.getAuthorities());
+        assertEquals(source.getExpireTime(), token.getExpireTime());
+    }
+
+    @Test
+    void getTokenWhenAbsentReturnsNull() {
+        when(valueOperations.get("no-such-key")).thenReturn(null);
+
+        assertNull(gateway.getToken("no-such-key"));
+    }
+
+    @Test
+    void removeTokenDeletesKey() {
+        gateway.removeToken("token-key");
+
+        verify(redisTemplate).delete("token-key");
+    }
+
+    @Test
+    void resetTokenWritesAgainWithValidTime() {
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+        token.setToken("token-key");
+
+        gateway.resetToken(token);
+
+        verify(valueOperations).set(eq("token-key"), eq(token.toJson()),
+                eq((long) properties.getValidTime()), eq(TimeUnit.MILLISECONDS));
+    }
+
+    @Test
+    void removeUsernameDeletesMatchedKeys() {
+        Set<String> keys = new HashSet<String>(Arrays.asList("key-1", "key-2"));
+        when(redisTemplate.keys(anyString())).thenReturn(keys);
+
+        gateway.removeUsername("admin");
+
+        ArgumentCaptor<String> patternCaptor = ArgumentCaptor.forClass(String.class);
+        verify(redisTemplate).keys(patternCaptor.capture());
+        assertTrue(patternCaptor.getValue().endsWith(":*"));
+        verify(redisTemplate).delete(keys);
+    }
+
+    @Test
+    void removeUsernameSkipsDeleteWhenNoKeys() {
+        when(redisTemplate.keys(anyString())).thenReturn(Collections.<String>emptySet());
+
+        gateway.removeUsername("admin");
+
+        verify(redisTemplate, never()).delete(anyCollection());
+    }
+
+    @Test
+    void getTokensByUsernameReturnsAllKeys() {
+        Set<String> keys = new HashSet<String>(Arrays.asList("key-1", "key-2"));
+        when(redisTemplate.keys(anyString())).thenReturn(keys);
+
+        List<String> tokens = gateway.getTokensByUsername("admin");
+
+        assertEquals(2, tokens.size());
+        assertTrue(tokens.containsAll(keys));
+    }
+
+    @Test
+    void removeUsernameWithPredicateDeletesMatchedToken() {
+        String key = "key-1";
+        when(redisTemplate.keys(anyString())).thenReturn(new HashSet<String>(Collections.singletonList(key)));
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+        when(valueOperations.get(key)).thenReturn(token.toJson());
+
+        Predicate<Token> predicate = t -> "admin".equals(t.getUsername());
+        gateway.removeUsername("admin", predicate);
+
+        verify(redisTemplate).delete(key);
+    }
+
+    @Test
+    void removeUsernameWithPredicateKeepsNotMatchedToken() {
+        String key = "key-1";
+        when(redisTemplate.keys(anyString())).thenReturn(new HashSet<String>(Collections.singletonList(key)));
+        Token token = new Token("admin", null, null, Collections.singletonList("ADMIN"), 900000, 600000);
+        when(valueOperations.get(key)).thenReturn(token.toJson());
+
+        Predicate<Token> predicate = t -> "other".equals(t.getUsername());
+        gateway.removeUsername("admin", predicate);
+
+        verify(redisTemplate, never()).delete(anyString());
+    }
+
+    @Test
+    void removeUsernameWithPredicateSkipsMissingToken() {
+        String key = "key-1";
+        when(redisTemplate.keys(anyString())).thenReturn(new HashSet<String>(Collections.singletonList(key)));
+        when(valueOperations.get(key)).thenReturn(null);
+
+        gateway.removeUsername("admin", t -> true);
+
+        verify(redisTemplate, never()).delete(anyString());
+    }
+
+    @Test
+    void removeUsernameWithPredicateSkipsWhenNoKeys() {
+        when(redisTemplate.keys(anyString())).thenReturn(Collections.<String>emptySet());
+
+        gateway.removeUsername("admin", t -> true);
+
+        verify(redisTemplate, never()).delete(anyString());
+        verify(valueOperations, never()).get(anyString());
+    }
+
+}
diff --git a/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/SecurityRedisPropertiesTest.java b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/SecurityRedisPropertiesTest.java
new file mode 100644
index 000000000..38438f62a
--- /dev/null
+++ b/springboot-starter-security/src/test/java/com/codingapi/springboot/security/redis/SecurityRedisPropertiesTest.java
@@ -0,0 +1,37 @@
+package com.codingapi.springboot.security.redis;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * SecurityRedisProperties 单元测试
+ * <p>
+ * 校验默认值与 setter/getter 行为。
+ */
+class SecurityRedisPropertiesTest {
+
+    @Test
+    void defaultValues() {
+        SecurityRedisProperties properties = new SecurityRedisProperties();
+
+        assertTrue(properties.isEnable());
+        assertEquals(900000, properties.getValidTime());
+        assertEquals(600000, properties.getRestTime());
+    }
+
+    @Test
+    void settersAndGetters() {
+        SecurityRedisProperties properties = new SecurityRedisProperties();
+        properties.setEnable(false);
+        properties.setValidTime(1000);
+        properties.setRestTime(500);
+
+        assertFalse(properties.isEnable());
+        assertEquals(1000, properties.getValidTime());
+        assertEquals(500, properties.getRestTime());
+    }
+
+}
diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/RequestFilter.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/RequestFilter.java
index 0773eac86..6e6a8d601 100644
--- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/RequestFilter.java
+++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/RequestFilter.java
@@ -84,6 +84,22 @@ public boolean hasFilter() {
         return !this.filterMap.isEmpty();
     }
 
+    /**
+     * 判断所有过滤条件是否均为简单等值匹配（无 OR/AND 组合、无 LIKE/范围/IN 等复杂条件），
+     * 用于决定走 Example 查询还是 HQL 动态查询
+     */
+    public boolean isAllEqualFilter() {
+        if (filterList.isEmpty()) {
+            return false;
+        }
+        for (Filter filter : filterList) {
+            if (!filter.isEqual()) {
+                return false;
+            }
+        }
+        return true;
+    }
+
 
     public Filter getFilter(String name) {
         return this.filterMap.get(name);
diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/SearchRequest.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/SearchRequest.java
index 4603f5a76..9bd166669 100644
--- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/SearchRequest.java
+++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/dto/request/SearchRequest.java
@@ -95,8 +95,15 @@ public PageRequest orFilters(Filter... filters) {
     }
 
 
+    /**
+     * Base64 解码，非法的 Base64 输入返回 null（由调用方按未消费参数处理），避免抛出 IllegalArgumentException
+     */
     private String decode(String value) {
-        return new String(Base64.getDecoder().decode(value));
+        try {
+            return new String(Base64.getDecoder().decode(value));
+        } catch (IllegalArgumentException e) {
+            return null;
+        }
     }
 
 
@@ -184,7 +191,7 @@ private List<ParamOperation> loadParamOperations() {
         String params = request.getParameter("params");
         if (StringUtils.hasLength(params)) {
             params = decode(params);
-            if (JSON.isValid(params)) {
+            if (params != null && JSON.isValid(params)) {
                 removeKeys.add("params");
                 return JSON.parseArray(params, ParamOperation.class);
             }
@@ -203,7 +210,7 @@ public PageRequest toPageRequest(Class<?> clazz) {
         String sort = request.getParameter("sort");
         if (StringUtils.hasLength(sort)) {
             sort = decode(sort);
-            if (JSON.isValid(sort)) {
+            if (sort != null && JSON.isValid(sort)) {
                 removeKeys.add("sort");
                 JSONObject jsonObject = JSON.parseObject(sort);
                 for (String key : jsonObject.keySet()) {
@@ -221,7 +228,7 @@ public PageRequest toPageRequest(Class<?> clazz) {
         String filter = request.getParameter("filter");
         if (StringUtils.hasLength(filter)) {
             filter = decode(filter);
-            if (JSON.isValid(filter)) {
+            if (filter != null && JSON.isValid(filter)) {
                 removeKeys.add("filter");
                 JSONObject jsonObject = JSON.parseObject(filter);
                 if(jsonObject!=null) {
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/FilterTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/FilterTest.java
new file mode 100644
index 000000000..2aaabce58
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/FilterTest.java
@@ -0,0 +1,110 @@
+package com.codingapi.springboot.framework.dto.request;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Filter 单元测试
+ */
+class FilterTest {
+
+    @Test
+    void constructors() {
+        Filter equalFilter = new Filter("name", "zhang");
+        assertEquals("name", equalFilter.getKey());
+        assertEquals(Relation.EQUAL, equalFilter.getRelation());
+        assertEquals(1, equalFilter.getValue().length);
+        assertEquals("zhang", equalFilter.getValue()[0]);
+
+        Filter relationFilter = new Filter("age", Relation.GREATER_THAN, 18);
+        assertEquals(Relation.GREATER_THAN, relationFilter.getRelation());
+
+        Filter groupFilter = new Filter(Filter.FILTER_AND_KEY,
+                new Filter("a", "1"), new Filter("b", "2"));
+        assertNull(groupFilter.getRelation());
+        assertEquals(2, groupFilter.getValue().length);
+        assertTrue(groupFilter.isAndFilters());
+        assertFalse(groupFilter.isOrFilters());
+    }
+
+    @Test
+    void staticFactories() {
+        Filter as1 = Filter.as("name", "zhang");
+        assertTrue(as1.isEqual());
+
+        Filter as2 = Filter.as("age", Relation.LESS_THAN, 30);
+        assertTrue(as2.isLessThan());
+
+        Filter and = Filter.and(Filter.as("a", "1"), Filter.as("b", "2"));
+        assertEquals(Filter.FILTER_AND_KEY, and.getKey());
+        assertTrue(and.isAndFilters());
+
+        Filter or = Filter.or(Filter.as("c", "3"), Filter.as("d", "4"));
+        assertEquals(Filter.FILTER_OR_KEY, or.getKey());
+        assertTrue(or.isOrFilters());
+        assertFalse(or.isAndFilters());
+    }
+
+    @Test
+    void settersAndGetters() {
+        Filter filter = new Filter("name", "zhang");
+        filter.setKey("newName");
+        filter.setRelation(Relation.NOT_EQUAL);
+        filter.setValue(new Object[]{"li"});
+        assertEquals("newName", filter.getKey());
+        assertEquals(Relation.NOT_EQUAL, filter.getRelation());
+        assertEquals("li", filter.getValue()[0]);
+    }
+
+    @Test
+    void relationChecks() {
+        assertTrue(new Filter("k", Relation.EQUAL, "v").isEqual());
+        assertTrue(new Filter("k", Relation.NOT_EQUAL, "v").isNotEqual());
+        assertTrue(new Filter("k", Relation.LIKE, "v").isLike());
+        assertTrue(new Filter("k", Relation.LEFT_LIKE, "v").isLeftLike());
+        assertTrue(new Filter("k", Relation.RIGHT_LIKE, "v").isRightLike());
+        assertTrue(new Filter("k", Relation.BETWEEN, 1, 2).isBetween());
+        assertTrue(new Filter("k", Relation.IN, 1, 2).isIn());
+        assertTrue(new Filter("k", Relation.NOT_IN, 1, 2).isNotIn());
+        assertTrue(new Filter("k", Relation.IS_NULL).isNull());
+        assertTrue(new Filter("k", Relation.IS_NOT_NULL).isNotNull());
+        assertTrue(new Filter("k", Relation.GREATER_THAN, 1).isGreaterThan());
+        assertTrue(new Filter("k", Relation.LESS_THAN, 1).isLessThan());
+        assertTrue(new Filter("k", Relation.GREATER_THAN_EQUAL, 1).isGreaterThanEqual());
+        assertTrue(new Filter("k", Relation.LESS_THAN_EQUAL, 1).isLessThanEqual());
+
+        Filter filter = new Filter("k", Relation.EQUAL, "v");
+        assertFalse(filter.isNull());
+        assertFalse(filter.isNotNull());
+        assertFalse(filter.isIn());
+        assertFalse(filter.isNotIn());
+        assertFalse(filter.isLike());
+        assertFalse(filter.isLeftLike());
+        assertFalse(filter.isRightLike());
+        assertFalse(filter.isBetween());
+        assertFalse(filter.isGreaterThan());
+        assertFalse(filter.isLessThan());
+        assertFalse(filter.isGreaterThanEqual());
+        assertFalse(filter.isLessThanEqual());
+        assertFalse(filter.isNotEqual());
+    }
+
+    @Test
+    void getFilterValueWithStringConversion() {
+        assertEquals(1, new Filter("k", "1").getFilterValue(Integer.class));
+        assertEquals(2L, new Filter("k", "2").getFilterValue(Long.class));
+        assertEquals(3.5d, new Filter("k", "3.5").getFilterValue(Double.class));
+        assertEquals(4.5f, new Filter("k", "4.5").getFilterValue(Float.class));
+        assertEquals("text", new Filter("k", "text").getFilterValue(String.class));
+        // 非字符串值原样返回
+        assertEquals(9, new Filter("k", 9).getFilterValue(Integer.class));
+    }
+
+    @Test
+    void relationEnum() {
+        assertEquals(14, Relation.values().length);
+        assertEquals(Relation.EQUAL, Relation.valueOf("EQUAL"));
+        assertEquals(Relation.LESS_THAN_EQUAL, Relation.valueOf("LESS_THAN_EQUAL"));
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/PageRequestFullTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/PageRequestFullTest.java
new file mode 100644
index 000000000..0bbba267f
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/PageRequestFullTest.java
@@ -0,0 +1,94 @@
+package com.codingapi.springboot.framework.dto.request;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.data.domain.Sort;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * PageRequest 单元测试(补充现有 PageRequestTest)
+ */
+class PageRequestFullTest {
+
+    @Test
+    void staticFactories() {
+        PageRequest pageRequest = PageRequest.of(2, 10);
+        assertEquals(2, pageRequest.getCurrent());
+        assertEquals(2, pageRequest.getPageNumber());
+        assertEquals(10, pageRequest.getPageSize());
+        assertEquals(20L, pageRequest.getOffset());
+        assertTrue(pageRequest.hasPrevious());
+        assertEquals(Sort.unsorted(), pageRequest.getSort());
+
+        PageRequest firstPage = PageRequest.of(0, 10);
+        assertFalse(firstPage.hasPrevious());
+        assertEquals(0L, firstPage.getOffset());
+
+        Sort sort = Sort.by("id").descending();
+        PageRequest sorted = PageRequest.of(1, 10, sort);
+        assertNotNull(sorted.getSort().getOrderFor("id"));
+    }
+
+    @Test
+    void addSort() {
+        PageRequest pageRequest = new PageRequest();
+        assertEquals(Sort.unsorted(), pageRequest.getSort());
+
+        pageRequest.addSort(Sort.by("name").ascending());
+        assertNotNull(pageRequest.getSort().getOrderFor("name"));
+
+        // 已有排序时再次添加
+        pageRequest.addSort(Sort.by("id").descending());
+        assertNotNull(pageRequest.getSort());
+    }
+
+    @Test
+    void filterDelegation() {
+        PageRequest pageRequest = PageRequest.of(0, 20);
+        assertFalse(pageRequest.hasFilter());
+
+        pageRequest.addFilter("name", "zhang");
+        pageRequest.addFilter("age", Relation.GREATER_THAN, 18);
+        pageRequest.andFilter(Filter.as("a", "1"));
+        pageRequest.orFilters(Filter.as("b", "2"));
+
+        assertTrue(pageRequest.hasFilter());
+        assertEquals("zhang", pageRequest.getStringFilter("name"));
+        assertEquals("default", pageRequest.getStringFilter("missing", "default"));
+        assertEquals(0, pageRequest.getIntFilter("missing"));
+        assertEquals(3, pageRequest.getIntFilter("missing", 3));
+        assertNotNull(pageRequest.getRequestFilter().getFilter(Filter.FILTER_AND_KEY));
+        assertNotNull(pageRequest.getRequestFilter().getFilter(Filter.FILTER_OR_KEY));
+
+        pageRequest.removeFilter("name");
+        assertNull(pageRequest.getStringFilter("name"));
+    }
+
+    @Test
+    void setPageSizeAndCurrent() {
+        PageRequest pageRequest = new PageRequest();
+        pageRequest.setPageSize(50);
+        pageRequest.setCurrent(3);
+        assertEquals(50, pageRequest.getPageSize());
+        assertEquals(3, pageRequest.getCurrent());
+        assertEquals(150L, pageRequest.getOffset());
+    }
+
+    @Test
+    void idRequest() {
+        IdRequest idRequest = new IdRequest();
+        idRequest.setId("12");
+        assertEquals("12", idRequest.getStringId());
+        assertEquals(12, idRequest.getIntId());
+        assertEquals(Long.valueOf(12L), idRequest.getLongId());
+        assertEquals(12f, idRequest.getFloatId());
+        assertEquals(12d, idRequest.getDoubleId());
+    }
+
+    @Test
+    void sortRequest() {
+        SortRequest sortRequest = new SortRequest();
+        sortRequest.setIds(java.util.Arrays.asList("1", "2"));
+        assertEquals(2, sortRequest.getIds().size());
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/RequestFilterTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/RequestFilterTest.java
new file mode 100644
index 000000000..124264413
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/RequestFilterTest.java
@@ -0,0 +1,125 @@
+package com.codingapi.springboot.framework.dto.request;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * RequestFilter 单元测试
+ */
+class RequestFilterTest {
+
+    @Test
+    void addFilters() {
+        RequestFilter requestFilter = new RequestFilter();
+        assertFalse(requestFilter.hasFilter());
+
+        requestFilter.addFilter("name", "zhang");
+        requestFilter.addFilter("age", Relation.GREATER_THAN, "18");
+
+        assertTrue(requestFilter.hasFilter());
+        assertEquals(2, requestFilter.getFilters().size());
+        assertEquals("zhang", requestFilter.getStringFilter("name"));
+        assertTrue(requestFilter.getFilter("age").isGreaterThan());
+    }
+
+    @Test
+    void groupFilters() {
+        RequestFilter requestFilter = new RequestFilter();
+        requestFilter.andFilters(Filter.as("a", "1"), Filter.as("b", "2"));
+        requestFilter.orFilters(Filter.as("c", "3"));
+
+        Filter andFilter = requestFilter.getFilter(Filter.FILTER_AND_KEY);
+        assertNotNull(andFilter);
+        assertTrue(andFilter.isAndFilters());
+        assertEquals(2, andFilter.getValue().length);
+
+        Filter orFilter = requestFilter.getFilter(Filter.FILTER_OR_KEY);
+        assertNotNull(orFilter);
+        assertTrue(orFilter.isOrFilters());
+    }
+
+    @Test
+    void pushFilterReplacesSameKey() {
+        RequestFilter requestFilter = new RequestFilter();
+        requestFilter.addFilter("name", "zhang");
+        requestFilter.addFilter("name", Relation.LIKE, "li");
+
+        assertEquals(1, requestFilter.getFilters().size());
+        assertTrue(requestFilter.getFilter("name").isLike());
+        assertEquals("li", requestFilter.getFilter("name").getValue()[0]);
+    }
+
+    @Test
+    void removeFilter() {
+        RequestFilter requestFilter = new RequestFilter();
+        requestFilter.addFilter("name", "zhang");
+        requestFilter.removeFilter("name");
+
+        assertFalse(requestFilter.hasFilter());
+        assertNull(requestFilter.getFilter("name"));
+        assertTrue(requestFilter.getFilters().isEmpty());
+    }
+
+    @Test
+    void stringFilterWithDefault() {
+        RequestFilter requestFilter = new RequestFilter();
+        assertNull(requestFilter.getStringFilter("missing"));
+        assertEquals("default", requestFilter.getStringFilter("missing", "default"));
+
+        requestFilter.addFilter("blank", "");
+        assertEquals("default", requestFilter.getStringFilter("blank", "default"));
+
+        requestFilter.addFilter("name", "zhang");
+        assertEquals("zhang", requestFilter.getStringFilter("name", "default"));
+    }
+
+    @Test
+    void intFilter() {
+        RequestFilter requestFilter = new RequestFilter();
+        assertEquals(0, requestFilter.getIntFilter("missing"));
+        assertEquals(5, requestFilter.getIntFilter("missing", 5));
+
+        requestFilter.addFilter("age", "18");
+        assertEquals(18, requestFilter.getIntFilter("age"));
+        assertEquals(18, requestFilter.getIntFilter("age", 5));
+
+        requestFilter.addFilter("zero", "");
+        assertEquals(0, requestFilter.getIntFilter("zero"));
+        assertEquals(5, requestFilter.getIntFilter("zero", 5));
+    }
+
+    @Test
+    void isAllEqualFilter() {
+        RequestFilter requestFilter = new RequestFilter();
+        // 无条件时返回 false
+        assertFalse(requestFilter.isAllEqualFilter());
+
+        // 全部为等值条件
+        requestFilter.addFilter("name", "zhang");
+        requestFilter.addFilter("age", Relation.EQUAL, 18);
+        assertTrue(requestFilter.isAllEqualFilter());
+
+        // 包含 LIKE 条件
+        requestFilter.addFilter("title", Relation.LIKE, "%a%");
+        assertFalse(requestFilter.isAllEqualFilter());
+        requestFilter.removeFilter("title");
+        assertTrue(requestFilter.isAllEqualFilter());
+
+        // 包含范围条件
+        requestFilter.addFilter("age", Relation.GREATER_THAN, 20);
+        assertFalse(requestFilter.isAllEqualFilter());
+        requestFilter.removeFilter("age");
+        assertTrue(requestFilter.isAllEqualFilter());
+
+        // 包含 OR 组合条件
+        requestFilter.orFilters(Filter.as("name", "a"), Filter.as("name", "b"));
+        assertFalse(requestFilter.isAllEqualFilter());
+        requestFilter.removeFilter(Filter.FILTER_OR_KEY);
+        assertTrue(requestFilter.isAllEqualFilter());
+
+        // 包含 AND 组合条件
+        requestFilter.andFilters(Filter.as("name", "a"), Filter.as("age", 1));
+        assertFalse(requestFilter.isAllEqualFilter());
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/SearchRequestParseTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/SearchRequestParseTest.java
new file mode 100644
index 000000000..f6cd1a9bc
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/dto/request/SearchRequestParseTest.java
@@ -0,0 +1,297 @@
+package com.codingapi.springboot.framework.dto.request;
+
+import lombok.Getter;
+import lombok.Setter;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.domain.Sort;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Base64;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * SearchRequest 及其内部类 ClassContent、ParamOperation 的单元测试
+ */
+class SearchRequestParseTest {
+
+    private MockHttpServletRequest httpRequest;
+
+    @BeforeEach
+    void setUp() {
+        httpRequest = new MockHttpServletRequest();
+        RequestContextHolder.setRequestAttributes(new ServletRequestAttributes(httpRequest));
+    }
+
+    @AfterEach
+    void tearDown() {
+        RequestContextHolder.resetRequestAttributes();
+    }
+
+    private static String encode(String json) {
+        return Base64.getEncoder().encodeToString(json.getBytes(StandardCharsets.UTF_8));
+    }
+
+    @Setter
+    @Getter
+    static class Address {
+        private String city;
+    }
+
+    @Setter
+    @Getter
+    static class BaseQuery {
+        private int state;
+    }
+
+    @Setter
+    @Getter
+    static class UserQuery extends BaseQuery {
+        private long id;
+        private String name;
+        private int age;
+        private boolean deleted;
+        private Address address;
+    }
+
+    @Setter
+    @Getter
+    static class RawQuery {
+        private String params;
+        private String sort;
+        private String filter;
+    }
+
+    @Test
+    void toPageRequestWithSortFilterAndParams() {
+        httpRequest.setParameter("current", "2");
+        httpRequest.setParameter("pageSize", "15");
+        httpRequest.setParameter("name", "zhang");
+        httpRequest.setParameter("age", "18");
+        httpRequest.setParameter("empty", "");
+        httpRequest.setParameter("sort", encode("{\"name\":\"ascend\"}"));
+        httpRequest.setParameter("filter", encode("{\"id\":[\"1\",\"2\"]}"));
+        httpRequest.setParameter("params", encode("[{\"key\":\"age\",\"type\":\"GREATER_THAN\"}]"));
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(2);
+        searchRequest.setPageSize(15);
+
+        assertEquals("zhang", searchRequest.getParameter("name"));
+        assertArrayEquals(new String[]{"zhang"}, searchRequest.getParameterValues("name"));
+        List<String> parameterNames = searchRequest.getParameterNames();
+        assertTrue(parameterNames.contains("name"));
+        assertTrue(parameterNames.contains("age"));
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+
+        // SearchRequest 不是 PageRequest, 默认分页偏移规则会减一
+        assertEquals(1, searchRequest.getCurrent());
+        assertEquals(1, pageRequest.getCurrent());
+        assertEquals(15, pageRequest.getPageSize());
+
+        Filter nameFilter = pageRequest.getRequestFilter().getFilter("name");
+        assertNotNull(nameFilter);
+        assertTrue(nameFilter.isEqual());
+        assertEquals("zhang", nameFilter.getValue()[0]);
+
+        Filter ageFilter = pageRequest.getRequestFilter().getFilter("age");
+        assertNotNull(ageFilter);
+        assertTrue(ageFilter.isGreaterThan());
+        assertEquals(18, ageFilter.getValue()[0]);
+
+        Filter idFilter = pageRequest.getRequestFilter().getFilter("id");
+        assertNotNull(idFilter);
+        assertTrue(idFilter.isIn());
+        assertEquals(2, idFilter.getValue().length);
+        assertEquals(1L, idFilter.getValue()[0]);
+        assertEquals(2L, idFilter.getValue()[1]);
+
+        Sort sort = pageRequest.getSort();
+        assertNotNull(sort.getOrderFor("name"));
+        assertTrue(sort.getOrderFor("name").isAscending());
+
+        // filter/sort/params 已从查询参数中移除, 不会再作为过滤条件
+        assertNull(pageRequest.getRequestFilter().getFilter("sort"));
+        assertNull(pageRequest.getRequestFilter().getFilter("filter"));
+        assertNull(pageRequest.getRequestFilter().getFilter("params"));
+    }
+
+    @Test
+    void toPageRequestWithDescendSort() {
+        httpRequest.setParameter("sort", encode("{\"id\":\"descend\"}"));
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+        assertNotNull(pageRequest.getSort().getOrderFor("id"));
+        assertTrue(pageRequest.getSort().getOrderFor("id").isDescending());
+    }
+
+    @Test
+    void toPageRequestWithEmptyFilterArrayAndBooleanField() {
+        httpRequest.setParameter("filter", encode("{\"name\":[],\"deleted\":[\"true\"]}"));
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+        // 空数组的 filter 被忽略
+        assertNull(pageRequest.getRequestFilter().getFilter("name"));
+        Filter deletedFilter = pageRequest.getRequestFilter().getFilter("deleted");
+        assertNotNull(deletedFilter);
+        assertTrue(deletedFilter.isIn());
+        assertEquals(true, deletedFilter.getValue()[0]);
+    }
+
+    @Test
+    void toPageRequestWithoutOperations() {
+        httpRequest.setParameter("name", "li");
+        httpRequest.setParameter("state", "1");
+        httpRequest.setParameter("address.city", "hangzhou");
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+
+        assertTrue(pageRequest.getRequestFilter().getFilter("name").isEqual());
+        assertEquals("li", pageRequest.getRequestFilter().getFilter("name").getValue()[0]);
+        // state 字段定义在父类 BaseQuery 中
+        assertEquals(1, pageRequest.getRequestFilter().getFilter("state").getValue()[0]);
+        // 嵌套对象字段
+        assertEquals("hangzhou", pageRequest.getRequestFilter().getFilter("address.city").getValue()[0]);
+    }
+
+    @Test
+    void toPageRequestWithInvalidJsonParams() {
+        // 合法 Base64 但非法 JSON 时不会加入 removeKeys, 原始(未解码)值将作为普通过滤条件处理
+        String raw = encode("not-a-json");
+        httpRequest.setParameter("params", raw);
+        httpRequest.setParameter("sort", raw);
+        httpRequest.setParameter("filter", raw);
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        PageRequest pageRequest = searchRequest.toPageRequest(RawQuery.class);
+        assertEquals(raw, pageRequest.getRequestFilter().getFilter("params").getValue()[0]);
+        assertEquals(raw, pageRequest.getRequestFilter().getFilter("sort").getValue()[0]);
+        assertEquals(raw, pageRequest.getRequestFilter().getFilter("filter").getValue()[0]);
+    }
+
+    @Test
+    void toPageRequestWithInvalidBase64Params() {
+        // 非法 Base64 不应抛出 IllegalArgumentException, 参数按原始值作为普通过滤条件处理
+        httpRequest.setParameter("params", "%%%not-base64%%%");
+        httpRequest.setParameter("sort", "%%%not-base64%%%");
+        httpRequest.setParameter("filter", "%%%not-base64%%%");
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        PageRequest pageRequest = assertDoesNotThrow(() -> searchRequest.toPageRequest(RawQuery.class));
+        assertEquals("%%%not-base64%%%", pageRequest.getRequestFilter().getFilter("params").getValue()[0]);
+        assertEquals("%%%not-base64%%%", pageRequest.getRequestFilter().getFilter("sort").getValue()[0]);
+        assertEquals("%%%not-base64%%%", pageRequest.getRequestFilter().getFilter("filter").getValue()[0]);
+    }
+
+    @Test
+    void toPageRequestWithUnknownFieldThrowsException() {
+        httpRequest.setParameter("unknownField", "value");
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+
+        assertThrows(IllegalArgumentException.class, () -> searchRequest.toPageRequest(UserQuery.class));
+    }
+
+    @Test
+    void removeFilterAddsRemoveKey() {
+        httpRequest.setParameter("name", "wang");
+
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.setCurrent(1);
+        searchRequest.setPageSize(10);
+        searchRequest.removeFilter("name");
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+        assertNull(pageRequest.getRequestFilter().getFilter("name"));
+    }
+
+    @Test
+    void delegateMethods() {
+        SearchRequest searchRequest = new SearchRequest();
+        searchRequest.addSort(Sort.by("id").descending());
+        searchRequest.addFilter("name", "zhang");
+        searchRequest.addFilter("age", Relation.GREATER_THAN, 18);
+        searchRequest.andFilter(Filter.as("a", "1"), Filter.as("b", "2"));
+        searchRequest.orFilters(Filter.as("c", "3"), Filter.as("d", "4"));
+
+        PageRequest pageRequest = searchRequest.toPageRequest(UserQuery.class);
+        assertNotNull(pageRequest.getSort().getOrderFor("id"));
+        assertEquals("zhang", pageRequest.getStringFilter("name"));
+        assertTrue(pageRequest.getRequestFilter().getFilter("age").isGreaterThan());
+        assertNotNull(pageRequest.getRequestFilter().getFilter(Filter.FILTER_AND_KEY));
+        assertNotNull(pageRequest.getRequestFilter().getFilter(Filter.FILTER_OR_KEY));
+    }
+
+    @Test
+    void classContentDirectly() {
+        PageRequest pageRequest = new PageRequest();
+        SearchRequest.ClassContent content = new SearchRequest.ClassContent(UserQuery.class, pageRequest);
+
+        content.addFilter("name", "zhang");
+        content.addFilter("age", Relation.LESS_THAN, "30");
+        content.addFilter("id", Arrays.asList("1", "2"));
+        content.addFilter("address.city", Relation.LIKE, "hz");
+
+        RequestFilter requestFilter = pageRequest.getRequestFilter();
+        assertTrue(requestFilter.getFilter("name").isEqual());
+        assertTrue(requestFilter.getFilter("age").isLessThan());
+        assertEquals(30, requestFilter.getFilter("age").getValue()[0]);
+        assertTrue(requestFilter.getFilter("id").isIn());
+        assertTrue(requestFilter.getFilter("address.city").isLike());
+    }
+
+    @Test
+    void classContentWithSameTypeValue() {
+        PageRequest pageRequest = new PageRequest();
+        SearchRequest.ClassContent content = new SearchRequest.ClassContent(UserQuery.class, pageRequest);
+        // String 类型字段直接返回原始值, 不需要 JSON 转换
+        content.addFilter("name", Relation.EQUAL, "direct");
+        assertEquals("direct", pageRequest.getRequestFilter().getFilter("name").getValue()[0]);
+    }
+
+    @Test
+    void classContentUnknownField() {
+        PageRequest pageRequest = new PageRequest();
+        SearchRequest.ClassContent content = new SearchRequest.ClassContent(UserQuery.class, pageRequest);
+        assertThrows(IllegalArgumentException.class, () -> content.addFilter("notExist", "value"));
+        assertThrows(IllegalArgumentException.class, () -> content.addFilter("address.notExist", "value"));
+    }
+
+    @Test
+    void paramOperation() {
+        SearchRequest.ParamOperation operation = new SearchRequest.ParamOperation();
+        operation.setKey("age");
+        operation.setType("GREATER_THAN");
+        assertEquals("age", operation.getKey());
+        assertEquals("GREATER_THAN", operation.getType());
+        assertEquals(Relation.GREATER_THAN, operation.getOperation());
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/math/ArithmeticFullTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/math/ArithmeticFullTest.java
new file mode 100644
index 000000000..2077a39f0
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/math/ArithmeticFullTest.java
@@ -0,0 +1,99 @@
+package com.codingapi.springboot.framework.math;
+
+import org.junit.jupiter.api.Test;
+
+import java.math.BigDecimal;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * Arithmetic 全量重载方法单元测试
+ */
+class ArithmeticFullTest {
+
+    @Test
+    void factoriesAndConstructors() {
+        assertEquals(0, Arithmetic.zero().getIntValue());
+        assertEquals(1, Arithmetic.one().getIntValue());
+
+        assertEquals(5, Arithmetic.parse(5).getIntValue());
+        assertEquals(5, Arithmetic.parse(5L).getIntValue());
+        assertEquals(1.5, Arithmetic.parse(1.5d).getDoubleValue(), 0.0001);
+        assertEquals(1.5, Arithmetic.parse(1.5f).getDoubleValue(), 0.0001);
+        assertEquals(2.5, Arithmetic.parse("2.5").getDoubleValue(), 0.0001);
+
+        assertEquals(3, new Arithmetic(3).getIntValue());
+        assertEquals(3, new Arithmetic(3L).getIntValue());
+        assertEquals(0.5, new Arithmetic(0.5d).getDoubleValue(), 0.0001);
+        assertEquals(0.5, new Arithmetic(0.5f).getDoubleValue(), 0.0001);
+        assertEquals(4.5, new Arithmetic("4.5").getDoubleValue(), 0.0001);
+    }
+
+    @Test
+    void addOverloads() {
+        assertEquals(3, Arithmetic.one().add(Arithmetic.parse(2)).getIntValue());
+        assertEquals(3, Arithmetic.one().add("2").getIntValue());
+        assertEquals(3, Arithmetic.one().add(2).getIntValue());
+        assertEquals(3, Arithmetic.one().add(2.0d).getIntValue());
+        assertEquals(3, Arithmetic.one().add(2.0f).getIntValue());
+        assertEquals(3, Arithmetic.one().add(2L).getIntValue());
+    }
+
+    @Test
+    void subOverloads() {
+        assertEquals(1, Arithmetic.parse(3).sub(Arithmetic.parse(2)).getIntValue());
+        assertEquals(1, Arithmetic.parse(3).sub("2").getIntValue());
+        assertEquals(1, Arithmetic.parse(3).sub(2).getIntValue());
+        assertEquals(1, Arithmetic.parse(3).sub(2.0d).getIntValue());
+        assertEquals(1, Arithmetic.parse(3).sub(2.0f).getIntValue());
+        assertEquals(1, Arithmetic.parse(3).sub(2L).getIntValue());
+    }
+
+    @Test
+    void mulOverloads() {
+        assertEquals(6, Arithmetic.parse(3).mul(Arithmetic.parse(2)).getIntValue());
+        assertEquals(6, Arithmetic.parse(3).mul("2").getIntValue());
+        assertEquals(6, Arithmetic.parse(3).mul(2).getIntValue());
+        assertEquals(6, Arithmetic.parse(3).mul(2.0d).getIntValue());
+        assertEquals(6, Arithmetic.parse(3).mul(2.0f).getIntValue());
+        assertEquals(6, Arithmetic.parse(3).mul(2L).getIntValue());
+    }
+
+    @Test
+    void divOverloads() {
+        assertEquals(3, Arithmetic.parse(6).div(Arithmetic.parse(2)).getIntValue());
+        assertEquals(3, Arithmetic.parse(6).div("2").getIntValue());
+        assertEquals(3, Arithmetic.parse(6).div(2).getIntValue());
+        assertEquals(3, Arithmetic.parse(6).div(2.0d).getIntValue());
+        assertEquals(3, Arithmetic.parse(6).div(2.0f).getIntValue());
+        assertEquals(3, Arithmetic.parse(6).div(2L).getIntValue());
+    }
+
+    @Test
+    void valueGetters() {
+        Arithmetic value = Arithmetic.parse("12.34");
+        assertEquals(new BigDecimal("12.34"), value.getValue());
+        assertEquals("12.34", value.getStringValue());
+        assertEquals(12, value.getIntValue());
+        assertEquals(12L, value.getLongValue());
+        assertEquals(12.34, value.getDoubleValue(), 0.0001);
+        assertEquals(12.34f, value.getFloatValue(), 0.0001);
+        assertEquals(12, value.getBigIntegerValue().intValue());
+    }
+
+    @Test
+    void halfUpScale() {
+        // 1.005 保留两位四舍五入 -> 1.01(half up)
+        assertEquals("1.01", Arithmetic.parse("1.005").halfUpScale2().getStringValue());
+        assertEquals("1.005", Arithmetic.parse("1.0051").halfUpScale(3).getStringValue());
+        assertEquals("3.14", Arithmetic.parse("3.14159").halfUpScale2().getStringValue());
+    }
+
+    @Test
+    void chainedCalculation() {
+        // ((10 - 2) x 3) / 4 = 6
+        assertEquals(6, Arithmetic.parse(10).sub(2).mul(3).div(4).getIntValue());
+        // 0.1 + 0.2 精确等于 0.3
+        assertEquals("0.3", Arithmetic.parse("0.1").add("0.2").getStringValue());
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/LocalHttpServerRestTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/LocalHttpServerRestTest.java
new file mode 100644
index 000000000..68573ec0b
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/LocalHttpServerRestTest.java
@@ -0,0 +1,218 @@
+package com.codingapi.springboot.framework.rest;
+
+import com.alibaba.fastjson.JSONObject;
+import com.codingapi.springboot.framework.rest.param.RestParam;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.HttpHeaders;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 基于 JDK 内置 HttpServer 的本地回环 HTTP 测试, 无外部网络依赖,
+ * 覆盖 HttpRequest / RestClient / SessionClient 的 GET/POST 主要路径
+ */
+class LocalHttpServerRestTest {
+
+    private static HttpServer server;
+    private static String baseUrl;
+
+    @BeforeAll
+    static void startServer() throws IOException {
+        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        // 固定 JSON 响应
+        server.createContext("/json", exchange ->
+                respond(exchange, "{\"name\":\"codingapi\"}"));
+        // 回显请求体
+        server.createContext("/echo", exchange ->
+                respond(exchange, new String(readBody(exchange.getRequestBody()), StandardCharsets.UTF_8)));
+        // 回显查询字符串
+        server.createContext("/query", exchange -> {
+            String query = exchange.getRequestURI().getRawQuery();
+            respond(exchange, query == null ? "" : query);
+        });
+        server.start();
+        baseUrl = "http://127.0.0.1:" + server.getAddress().getPort();
+    }
+
+    @AfterAll
+    static void stopServer() {
+        if (server != null) {
+            server.stop(0);
+        }
+    }
+
+    private static byte[] readBody(InputStream in) throws IOException {
+        ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+        byte[] chunk = new byte[2048];
+        int len;
+        while ((len = in.read(chunk)) != -1) {
+            buffer.write(chunk, 0, len);
+        }
+        return buffer.toByteArray();
+    }
+
+    private static void respond(HttpExchange exchange, String body) throws IOException {
+        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
+        exchange.getResponseHeaders().set("Content-Type", "application/json;charset=UTF-8");
+        exchange.sendResponseHeaders(200, bytes.length);
+        try (OutputStream out = exchange.getResponseBody()) {
+            out.write(bytes);
+        }
+        exchange.close();
+    }
+
+    @Test
+    void restClientGetJson() {
+        RestClient restClient = new RestClient(baseUrl);
+        String response = restClient.get("/json");
+        JSONObject json = JSONObject.parseObject(response);
+        assertNotNull(json);
+        assertEquals("codingapi", json.getString("name"));
+    }
+
+    @Test
+    void restClientGetWithQueryParams() {
+        RestClient restClient = new RestClient(baseUrl);
+        String response = restClient.get("/query", RestParam.create()
+                .add("name", "zhang")
+                .add("age", "18"));
+        assertTrue(response.contains("name=zhang"));
+        assertTrue(response.contains("age=18"));
+    }
+
+    @Test
+    void restClientGetWithHeaders() {
+        RestClient restClient = new RestClient(baseUrl);
+        HttpHeaders headers = new HttpHeaders();
+        String response = restClient.get("/json", headers);
+        assertNotNull(response);
+    }
+
+    @Test
+    void restClientPostJson() {
+        RestClient restClient = new RestClient(baseUrl);
+        JSONObject body = new JSONObject();
+        body.put("username", "admin");
+        String response = restClient.post("/echo", body);
+        JSONObject echo = JSONObject.parseObject(response);
+        assertNotNull(echo);
+        assertEquals("admin", echo.getString("username"));
+    }
+
+    @Test
+    void restClientPostWithRestParam() {
+        RestClient restClient = new RestClient(baseUrl);
+        String response = restClient.post("/echo", RestParam.create().add("k", "v"));
+        JSONObject echo = JSONObject.parseObject(response);
+        assertNotNull(echo);
+        assertEquals("v", echo.getString("k"));
+    }
+
+    @Test
+    void sessionClientGetJson() {
+        SessionClient sessionClient = new SessionClient();
+        String response = sessionClient.getJson(baseUrl + "/json");
+        JSONObject json = JSONObject.parseObject(response);
+        assertNotNull(json);
+        assertEquals("codingapi", json.getString("name"));
+    }
+
+    @Test
+    void sessionClientGetJsonWithParams() {
+        SessionClient sessionClient = new SessionClient();
+        String response = sessionClient.getJson(baseUrl + "/query", RestParam.create().add("q", "1"));
+        assertTrue(response.contains("q=1"));
+    }
+
+    @Test
+    void sessionClientPostJson() {
+        SessionClient sessionClient = new SessionClient();
+        String response = sessionClient.postJson(baseUrl + "/echo", RestParam.create().add("action", "login"));
+        JSONObject echo = JSONObject.parseObject(response);
+        assertNotNull(echo);
+        assertEquals("login", echo.getString("action"));
+    }
+
+    @Test
+    void sessionClientPostJsonBody() {
+        SessionClient sessionClient = new SessionClient();
+        JSONObject body = new JSONObject();
+        body.put("from", "body");
+        String response = sessionClient.postJson(baseUrl + "/echo", body);
+        JSONObject echo = JSONObject.parseObject(response);
+        assertNotNull(echo);
+        assertEquals("body", echo.getString("from"));
+    }
+
+    @Test
+    void sessionClientPostForm() {
+        SessionClient sessionClient = new SessionClient();
+        String response = sessionClient.postForm(baseUrl + "/echo", RestParam.create().add("f", "1"));
+        assertTrue(response.contains("f=1"));
+    }
+
+    @Test
+    void sessionClientGetHtml() {
+        SessionClient sessionClient = new SessionClient();
+        String response = sessionClient.getHtml(baseUrl + "/json");
+        assertNotNull(response);
+    }
+
+    @Test
+    void sessionClientAddHeader() {
+        SessionClient sessionClient = new SessionClient();
+        sessionClient.addHeader("X-Test", "1");
+        assertEquals("1", sessionClient.getHttpHeaders().getFirst("X-Test"));
+    }
+
+    @Test
+    void httpRequestGetRequestExecute() {
+        HttpRequest httpRequest = new HttpRequest();
+        MultiValueMap<String, String> variables = new LinkedMultiValueMap<>();
+        variables.add("a", "1");
+        String response = httpRequest.getGetRequest(baseUrl + "/query", new HttpHeaders(), variables).execute();
+        assertTrue(response.contains("a=1"));
+    }
+
+    @Test
+    void httpRequestGetWithoutVariables() {
+        HttpRequest httpRequest = new HttpRequest();
+        String response = httpRequest.getGetRequest(baseUrl + "/json", new HttpHeaders(), null).execute();
+        assertNotNull(response);
+    }
+
+    @Test
+    void httpRequestPostJsonRequest() {
+        HttpRequest httpRequest = new HttpRequest();
+        JSONObject body = new JSONObject();
+        body.put("via", "request");
+        String response = httpRequest.getPostRequest(baseUrl + "/echo", new HttpHeaders(), (com.alibaba.fastjson.JSON) body).execute();
+        JSONObject echo = JSONObject.parseObject(response);
+        assertNotNull(echo);
+        assertEquals("request", echo.getString("via"));
+    }
+
+    @Test
+    void httpRequestPostFormRequest() {
+        HttpRequest httpRequest = new HttpRequest();
+        MultiValueMap<String, Object> form = new LinkedMultiValueMap<>();
+        form.add("field", "x");
+        String response = httpRequest.getPostRequest(baseUrl + "/echo", new HttpHeaders(), form).execute();
+        assertTrue(response.contains("field=x"));
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/RestClientTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/RestClientTest.java
index c6a48d792..e8b796985 100644
--- a/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/RestClientTest.java
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/rest/RestClientTest.java
@@ -1,9 +1,11 @@
 package com.codingapi.springboot.framework.rest;
 
+import com.alibaba.fastjson.JSONArray;
 import com.alibaba.fastjson.JSONObject;
 import com.codingapi.springboot.framework.rest.param.RestParam;
 import com.codingapi.springboot.framework.rest.properties.HttpProxyProperties;
 import lombok.extern.slf4j.Slf4j;
+import org.junit.jupiter.api.Assumptions;
 import org.junit.jupiter.api.Test;
 
 import java.net.Proxy;
@@ -13,6 +15,10 @@
 @Slf4j
 class RestClientTest {
 
+    /**
+     * 依赖外部网络与本地代理（127.0.0.1:7890）的集成用例：
+     * 代理缺失、网络受限或外部接口限流时跳过，不作为 CI 强制断言。
+     */
     @Test
     void okxTest() {
         String baseUrl = "https://www.okx.com/";
@@ -22,13 +28,24 @@ void okxTest() {
         proxyProperties.setProxyHost("127.0.0.1");
         proxyProperties.setProxyPort(7890);
         RestClient restClient = new RestClient(proxyProperties,baseUrl,5,"{}",null,null);
-        String response = restClient.get("api/v5/market/candles", RestParam.create()
-                .add("instId","BTC-USDT")
-                .add("bar","1m")
-                .add("limit","300")
-        );
+        String response;
+        try {
+            response = restClient.get("api/v5/market/candles", RestParam.create()
+                    .add("instId","BTC-USDT")
+                    .add("bar","1m")
+                    .add("limit","300")
+            );
+        } catch (Exception e) {
+            Assumptions.assumeTrue(false, "OKX 外部接口不可用（本地代理 127.0.0.1:7890 缺失或网络受限），跳过用例: " + e.getMessage());
+            return;
+        }
         log.info("response:{}",response);
         JSONObject jsonObject = JSONObject.parseObject(response);
-        assertEquals(jsonObject.getJSONArray("data").size(),300);
+        JSONArray data = jsonObject == null ? null : jsonObject.getJSONArray("data");
+        if (data == null) {
+            Assumptions.assumeTrue(false, "OKX 外部接口响应无 data 数据（网络受限或限流），跳过用例");
+            return;
+        }
+        assertEquals(300, data.size());
     }
-}
\ No newline at end of file
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/transaction/TransactionManagerContextTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/transaction/TransactionManagerContextTest.java
new file mode 100644
index 000000000..c0344b96a
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/transaction/TransactionManagerContextTest.java
@@ -0,0 +1,114 @@
+package com.codingapi.springboot.framework.transaction;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.TransactionStatus;
+import org.springframework.transaction.support.DefaultTransactionDefinition;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * TransactionManagerContext 单元测试
+ */
+class TransactionManagerContextTest {
+
+    private PlatformTransactionManager transactionManager;
+    private TransactionStatus transactionStatus;
+
+    @BeforeEach
+    void setUp() {
+        transactionManager = mock(PlatformTransactionManager.class);
+        transactionStatus = mock(TransactionStatus.class);
+        when(transactionManager.getTransaction(any(TransactionDefinition.class))).thenReturn(transactionStatus);
+    }
+
+    @AfterEach
+    void tearDown() {
+        // 恢复为空, 避免影响其他测试
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(null);
+    }
+
+    @Test
+    void commitWithTransactionManager() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(transactionManager);
+
+        String result = TransactionManagerContext.getInstance().commit(() -> "ok");
+
+        assertEquals("ok", result);
+        ArgumentCaptor<TransactionDefinition> captor = ArgumentCaptor.forClass(TransactionDefinition.class);
+        verify(transactionManager).getTransaction(captor.capture());
+        assertEquals(TransactionDefinition.PROPAGATION_REQUIRES_NEW, captor.getValue().getPropagationBehavior());
+        verify(transactionManager).commit(transactionStatus);
+        verify(transactionManager, never()).rollback(transactionStatus);
+    }
+
+    @Test
+    void commitRollsBackOnException() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(transactionManager);
+
+        assertThrows(IllegalStateException.class,
+                () -> TransactionManagerContext.getInstance().commit(() -> {
+                    throw new IllegalStateException("boom");
+                }));
+
+        verify(transactionManager).rollback(transactionStatus);
+        verify(transactionManager, never()).commit(transactionStatus);
+    }
+
+    @Test
+    void commitWithoutTransactionManager() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(null);
+
+        String result = TransactionManagerContext.getInstance().commit(() -> "direct");
+
+        assertEquals("direct", result);
+    }
+
+    @Test
+    void readOnlyEndsWithRollback() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(transactionManager);
+
+        String result = TransactionManagerContext.getInstance().readOnly(() -> "read");
+
+        assertEquals("read", result);
+        ArgumentCaptor<TransactionDefinition> captor = ArgumentCaptor.forClass(TransactionDefinition.class);
+        verify(transactionManager).getTransaction(captor.capture());
+        DefaultTransactionDefinition definition = (DefaultTransactionDefinition) captor.getValue();
+        assertEquals(TransactionDefinition.PROPAGATION_REQUIRES_NEW, definition.getPropagationBehavior());
+        assertEquals(true, definition.isReadOnly());
+        // 只读模式以回滚结束
+        verify(transactionManager).rollback(transactionStatus);
+        verify(transactionManager, never()).commit(transactionStatus);
+    }
+
+    @Test
+    void readOnlyRollsBackOnException() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(transactionManager);
+
+        assertThrows(IllegalStateException.class,
+                () -> TransactionManagerContext.getInstance().readOnly(() -> {
+                    throw new IllegalStateException("boom");
+                }));
+
+        verify(transactionManager).rollback(transactionStatus);
+    }
+
+    @Test
+    void readOnlyWithoutTransactionManager() {
+        TransactionManagerContext.getInstance().setPlatformTransactionManager(null);
+
+        String result = TransactionManagerContext.getInstance().readOnly(() -> "direct");
+
+        assertEquals("direct", result);
+    }
+}
diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/utils/ClassLoaderUtilsTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/utils/ClassLoaderUtilsTest.java
new file mode 100644
index 000000000..0171e8627
--- /dev/null
+++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/utils/ClassLoaderUtilsTest.java
@@ -0,0 +1,103 @@
+package com.codingapi.springboot.framework.utils;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.net.URLClassLoader;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.jar.JarEntry;
+import java.util.jar.JarOutputStream;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * ClassLoaderUtils 单元测试
+ */
+class ClassLoaderUtilsTest {
+
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void createClassLoaderThrowsWhenJarNotFound() {
+        assertThrows(RuntimeException.class, () -> ClassLoaderUtils.createClassLoader("/no/such/file.jar"));
+    }
+
+    @Test
+    void findAllClassesInDirectory() throws Exception {
+        // 构造目录结构: root/com/demo/A.class, root/com/demo/sub/B.class
+        File root = tempDir.toFile();
+        File pkg = new File(root, "com/demo/sub");
+        assertTrue(pkg.mkdirs());
+        assertTrue(new File(pkg.getParentFile(), "A.class").createNewFile());
+        assertTrue(new File(pkg, "B.class").createNewFile());
+        // 非 class 文件应被忽略
+        assertTrue(new File(pkg, "readme.txt").createNewFile());
+
+        URLClassLoader classLoader = new URLClassLoader(new java.net.URL[]{root.toURI().toURL()});
+        List<String> classes = ClassLoaderUtils.findAllClasses(classLoader);
+
+        assertTrue(classes.contains("com.demo.A"));
+        assertTrue(classes.contains("com.demo.sub.B"));
+        assertEquals(2, classes.size());
+        classLoader.close();
+    }
+
+    @Test
+    void findAllClassesInJar() throws Exception {
+        File jarFile = tempDir.resolve("demo.jar").toFile();
+        try (JarOutputStream jar = new JarOutputStream(new FileOutputStream(jarFile))) {
+            jar.putNextEntry(new JarEntry("com/demo/Inner.class"));
+            jar.write(new byte[]{(byte) 0xCA, (byte) 0xFE, (byte) 0xBA, (byte) 0xBE});
+            jar.closeEntry();
+            // 非 class 条目应被忽略
+            jar.putNextEntry(new JarEntry("META-INF/MANIFEST.MF"));
+            jar.write("Manifest-Version: 1.0".getBytes());
+            jar.closeEntry();
+        }
+
+        URLClassLoader classLoader = ClassLoaderUtils.createClassLoader(jarFile.getAbsolutePath());
+        List<String> classes = ClassLoaderUtils.findAllClasses(classLoader);
+
+        assertEquals(1, classes.size());
+        assertEquals("com.demo.Inner", classes.get(0));
+        classLoader.close();
+    }
+
+    @Test
+    void findJarClassesLoadsRealClasses() throws Exception {
+        // 将当前测试类所在的 classes 目录打包成 jar, 验证类可被真实加载
+        String classFilePath = ClassLoaderUtilsTest.class.getName().replace('.', '/') + ".class";
+        java.net.URL classUrl = ClassLoaderUtilsTest.class.getClassLoader().getResource(classFilePath);
+        assertFalse(classUrl == null);
+
+        File jarFile = tempDir.resolve("real.jar").toFile();
+        try (JarOutputStream jar = new JarOutputStream(new FileOutputStream(jarFile))) {
+            jar.putNextEntry(new JarEntry(classFilePath));
+            try (java.io.InputStream in = classUrl.openStream()) {
+                byte[] buffer = new byte[4096];
+                int len;
+                while ((len = in.read(buffer)) != -1) {
+                    jar.write(buffer, 0, len);
+                }
+            }
+            jar.closeEntry();
+        }
+
+        List<Class<?>> classes = ClassLoaderUtils.findJarClasses(jarFile.getAbsolutePath());
+        assertFalse(classes.isEmpty());
+
+        List<Class<?>> filtered = ClassLoaderUtils.findJarClass(jarFile.getAbsolutePath(), Object.class);
+        assertFalse(filtered.isEmpty());
+
+        // 指定不可能匹配的接口类型时返回空
+        List<Class<?>> none = ClassLoaderUtils.findJarClass(jarFile.getAbsolutePath(), Runnable.class);
+        assertTrue(none.isEmpty() || none.stream().allMatch(Runnable.class::isAssignableFrom));
+    }
+}