docs: README 改为双版本线简介，文档全面对齐实际代码

- README 仅保留 17.3.x（JDK 17/Spring Boot 3）与 8.2.x（JDK 8/Spring Boot 2）两条版本线简介；
  本分支无示例工程，不包含示例运行内容
- 移植与代码对齐后的文档体系：wiki（含新增 script 页）、conventions、capabilities
  （含 docs/agents 镜像），版本号适配为 8.2.x，servlet 命名空间说明适配 javax
- CLAUDE.md 重写：补充模块架构、核心模式、配置项，注明 javax 约束与无示例工程
- CONTRIBUTING 更新 JDK 要求（8）、分支模型与构建指引

Co-Authored-By: Claude <noreply@anthropic.com>

Author: xlorne

CLAUDE.md

@@ -2,70 +2,122 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## 项目概览
+## 项目概述
 
-`com.codingapi.springboot:springboot-parent`（当前开发版本 `8.2.0-SNAPSHOT`）是一套基于 Spring Boot 2.7.18 + JDK 8 的**领域驱动设计（DDD）落地框架**，围绕"事件风暴 + 数据权限 + 动态脚本"三大支柱提供可插拔的 starter 模块。框架代码本身即是规范，业务方按需引入 starter 即可获得对应能力，无需重复造轮子。
+springboot-framework 是一个基于 Spring Boot 2.7.18（Java 8）的多模块企业级开发框架，由 CodingApi 团队维护。核心定位是为领域驱动设计（DDD）与事件风暴提供开箱即用的基础设施。当前开发版本为 `8.2.0-SNAPSHOT`，采用 Maven `${revision}` CI-Friendly 版本机制，正式发布时通过 `-Drevision=x.y.z` 指定正式版本号。版本号含义：8 = 最低 JDK 版本，2 = Spring Boot 大版本，第三位为补丁版本。
 
-版本采用 CI-Friendly 机制：pom 版本声明为 `${revision}`，开发期锁定 `8.2.0-SNAPSHOT`（版本号含义：8 = JDK 8，2 = Spring Boot 2.x 大版本，第三位为补丁版本），正式发布时通过 `-Drevision=x.y.z` 指定正式版本号，无需修改 pom。
+**回复语言**：请使用中文进行回答。
 
-详细能力文档见 `docs/capabilities/index.md`（共 8 篇），开发规范见 `docs/conventions/index.md`。
+**版本线说明**：本仓库维护两条版本线——`17.3.x`（JDK 17 / Spring Boot 3.x）与 `8.2.x`（JDK 8 / Spring Boot 2.x，当前分支）。两条版本线功能基本一致，主要差异为 JDK 与 Spring Boot 代际：本分支使用 `javax.*` 命名空间（如 `javax.servlet`、`javax.persistence`），**禁止使用** `jakarta.*`。本分支不包含示例工程（example）与前端工程（frontend）。
 
-## 模块拓扑与依赖
+## 常用命令
+
+```bash
+# 全量构建
+./mvnw clean install
+
+# 仅运行测试（CI 使用）
+./mvnw clean test -P travis
+
+# 运行单个模块的测试
+./mvnw test -pl springboot-starter
+./mvnw test -pl springboot-starter-security
+
+# 运行单个测试类
+./mvnw test -pl springboot-starter -Dtest=SomeTestClass
+
+# 正式发布（通过 -Drevision 指定正式版本号，无需修改 pom）
+./mvnw clean deploy -P ossrh -Drevision=8.2.0
+```
+
+## 模块架构
+
+### Starter 模块（框架核心）
+
+| 模块 | 职责 |
+|------|------|
+| `springboot-starter` | 核心基础：统一 Response DTO、分页 PageRequest/Filter、事件系统、国际化异常、事务管理 |
+| `springboot-starter-security` | Spring Security + JWT 无状态认证 / Redis 有状态认证，加解密支持 |
+| `springboot-starter-data-fast` | JPA 增强：FastRepository 支持动态过滤查询、HQL 构建、SearchRequest |
+| `springboot-starter-data-authorization` | 数据权限：通过 JDBC Connection/Statement 代理拦截 SQL，透明注入权限条件 |
+| `springboot-starter-script` | Groovy 脚本引擎：运行时编译、LRU 缓存、热更新，提供 REST API |
+
+### 自动配置注册
+
+各 starter 模块同时维护 `META-INF/spring.factories`（兼容旧版）和 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`（Spring Boot 2.7+ 支持）。新增 starter 时需同时注册这两种文件。
 
-多模块项目，根 `pom.xml` 中只激活 `springboot-starter-data-authorization`；完整 5 模块通过 `dev` / `travis` / `ossrh` profile 激活。模块依赖**严格单向**，不得反向依赖：
+### 模块间依赖关系
 
 ```
-springboot-starter          (基础 DDD 框架：领域事件、代理、异常、加密、HTTP 代理)
-        │
-        ├─→ springboot-starter-script          (Groovy 脚本引擎，依赖 starter)
-        │       │
-        │       └─→ springboot-starter-data-fast   (JPA 增强 + 脚本映射，依赖 starter+script)
-        │
-        └─→ springboot-starter-security        (JWT/Redis 双模 Token 网关，依赖 starter)
-        │
-        └─→ springboot-starter-data-authorization (行+列数据权限，**仅在根 pom 直接声明**)
+springboot-starter (核心，无外部依赖)
+    ├── springboot-starter-security      (依赖 starter)
+    ├── springboot-starter-data-fast     (依赖 starter)
+    ├── springboot-starter-data-authorization (依赖 starter + JSqlParser)
+    └── springboot-starter-script        (依赖 starter + Groovy)
 ```
 
-⚠️ `springboot-starter-data-authorization` 不依赖 starter，自带 jsqlparser 解析 SQL，改写后通过 `AuthorizationJdbcDriver` 在结果集层做列权限脱敏。
+注意：根 `pom.xml` 默认 `<modules>` 中仅包含 `springboot-starter-data-authorization`，完整 5 模块通过 `dev` / `travis` / `ossrh` profile 激活。
 
-## 关键架构决策
+## 核心架构模式
 
-| 决策 | 体现位置 | 说明 |
-|------|---------|------|
-| **领域事件总线** | `framework/event/` | 自研 `EventPusher` + `DomainEvent`，支持同步/异步/事务后（`@TransactionalEventListener AFTER_COMMIT`），通过 `EventTraceContext` 检测循环事件 |
-| **CGLIB 实体代理** | `framework/domain/proxy/` | `DomainProxyFactory.create()` 在 setter 调用前后对比字段差异，自动发布 `DomainChangeEvent`，无需在业务 setter 中写事件代码 |
-| **脚本热加载** | `script/GroovyScript*` | 编译缓存用 SHA-256 做 key；`TempGroovyScript` 临时脚本由 `GroovyScriptEngineRunner` 在启动时从 DB 恢复、应用关闭时落盘 |
-| **双模 Token** | `security/gateway/TokenGateway` | 同一接口有 `JwtTokenGateway`（无状态）和 `RedisTokenGateway`（可踢人）两种实现，通过 `codingapi.security.token.type` 切换 |
-| **行+列双层权限** | `authorization/` | `DefaultSQLInterceptor` 在 SQL 执行前用 `JSqlParser` 递归改写 WHERE；`ResultSetProxy` 在结果集读取时通过 `ColumnHandlerContext` 脱敏 |
-| **泛型签名一致性** | `framework/utils/RandomGenerator` 等 | JDK 8 编译时必须显式声明 `LinkedHashMap<String,Script>` 等类型，依赖 IDE 推断会丢失泛型信息（见 git log 中 `GroovyScriptRuntime` 修复记录） |
-| **javax.persistence 适配** | 所有 `*Repository` 接口 | 项目基于 Spring Boot 2.7.18，对应 JPA 2.x；**禁止使用** `jakarta.persistence.*`（那是 Spring Boot 3.x / Jakarta EE 9+） |
+### 事件系统（Event System）
 
-## 常用命令
+框架自建的发布-订阅事件机制，是 DDD 领域事件的核心基础设施：
 
-```bash
-# 构建
-./mvnw clean install -DskipTests          # 跳过测试
-./mvnw clean test                         # 全量测试（默认 dev profile）
+- **`IEvent`** — 事件标记接口，分为 `ISyncEvent`（同步）和 `IAsyncEvent`（异步）
+- **`IHandler<T extends IEvent>`** — 事件处理器，支持 `order()` 排序和 `error()` 异常回调
+- **`EventPusher.push(event, sync)`** — 事件推送入口
+- **`DomainEvent`** — 领域实体事件基类，派生 `DomainCreateEvent`、`DomainChangeEvent`、`DomainDeleteEvent`
+- **`DomainChangeInterceptor`** — 通过代理拦截实体字段变更，自动推送 `DomainChangeEvent`
 
-# 单模块测试
-./mvnw -pl springboot-starter -am test
-./mvnw -pl springboot-starter-script -Dtest=GroovyScriptRuntimeContextTest test
+标注 `@Handler`（或 `@Component`/`@Service`）的处理器会被注册为 Spring Bean；`SpringHandlerConfiguration` 收集容器中所有 `IHandler` Bean，在构造事件处理器时通过 `addHandlers` 统一注册到 `ApplicationHandlerUtils`。
 
-# 部署 profile
-./mvnw clean test -P travis               # 启用 jacoco + clover
+### 统一响应封装
 
-# 正式发布（通过 -Drevision 指定正式版本号，无需修改 pom）
-./mvnw clean deploy -P ossrh -Drevision=8.2.0   # 推送到 Sonatype（需 GPG）
+```java
+Response          // 基础响应（success / errCode / errMessage）
+SingleResponse<T> // 单对象响应
+MultiResponse<T>  // 列表响应
+MapResponse       // Map 响应
+```
+
+### 数据查询（PageRequest + FastRepository）
+
+`PageRequest` 扩展了 Spring Data 的 `PageRequest`，增加了 `RequestFilter` 动态过滤条件：
+
+```java
+PageRequest request = PageRequest.of(0, 20);
+request.addFilter("name", "张三");
+request.addFilter("age", Relation.GREATER_THAN, 18);
+Page<User> page = userRepository.findAll(request);
 ```
 
-测试基于 H2 内存库（`com.h2database:h2` scope=test），无需外部 DB（H2 关闭时的告警是正常的）。
+`FastRepository.findAll(PageRequest)` 全部为等值条件时构建 Example 查询；包含 LIKE/范围/IN/OR 等复杂条件时自动切换 `DynamicSQLBuilder` 构建的 HQL 查询。
+
+### 数据权限（SQL 拦截）
+
+`ConnectionProxy` → `PreparedStatementProxy` / `StatementProxy` 代理链，在 SQL 执行前通过 `SQLRunningContext.intercept(sql)` 注入权限条件，实现透明的行级数据过滤。使用 JSqlParser 解析和改写 SQL。列级脱敏通过 `ResultSetProxy` + `ColumnHandlerContext` 在结果集读取时完成。
+
+## 框架配置项
+
+在 `application.properties` 中可用的配置前缀：
+
+```properties
+# 安全模块
+codingapi.security.jwt.enable=true               # 启用 JWT 认证（必须显式开启）
+codingapi.security.redis.enable=true             # 启用 Redis 有状态认证（必须显式开启）
+codingapi.security.ignore-urls=/open/**,/#/**    # 免认证 URL 列表
+
+# 框架核心
+codingapi.framework.handler-thread-pool-size=20  # 事件异步线程池大小
+
+# 数据权限
+codingapi.data-authorization.show-sql=false      # 打印拦截后的 SQL
+```
 
-## 文档与知识库
+## 关键依赖版本
 
-- `README.md` — 模块列表、maven 依赖、版本说明
-- `docs/capabilities/` — 8 篇核心能力文档（DDD 事件、领域代理、Groovy 脚本、JDBC 代理、SQL 拦截器、JPA 仓储、Token 网关、Spring Boot 基础）
-- `docs/conventions/` — 项目开发规范（待补全）
-- Wiki：https://github.com/codingapi/springboot-framework/wiki
+见根 `pom.xml` 的 `<properties>` 区块。主要版本：Groovy 4.0.24、JSqlParser 5.0、Fastjson 2.0.53、JJWT 0.12.6、H2 1.4.200。
 
 <!-- PKR-START -->
 ## PKR 知识查阅（编码前必须）

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 8 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. `8.2.x`, `17.3.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` and `8.2.x`.
+
+The project version (e.g. `8.2.0-SNAPSHOT`, where `8` is the minimum JDK version, `2` 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.