From 3c8c9c5db6cc336a58cfe6530cb54598b9df0226 Mon Sep 17 00:00:00 2001
From: LiuXiaoLong <75962798+xcancloud@users.noreply.github.com>
Date: Wed, 29 Oct 2025 19:49:14 +0800
Subject: [PATCH 1/4] Update pom.xml

---
 plugin/pom.xml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/plugin/pom.xml b/plugin/pom.xml
index b419eb52..e85cec52 100644
--- a/plugin/pom.xml
+++ b/plugin/pom.xml
@@ -16,8 +16,7 @@
   <version>1.0.0</version>
   <packaging>pom</packaging>
   <description>Parent aggregator module for building extensible plugins; manages child modules,
-    versions and
-    dependencies.
+    versions and dependencies.
   </description>
 
   <modules>

From 87d08199110826d96b5dd223c64d14376b6d32f1 Mon Sep 17 00:00:00 2001
From: LiuXiaoLong <75962798+xcancloud@users.noreply.github.com>
Date: Wed, 29 Oct 2025 19:57:50 +0800
Subject: [PATCH 2/4] Add README documentation for the plugin module

---
 plugin/README.md    | 133 ++++++++++++++++++++++++++++++++++++++++++++
 plugin/README_zh.md | 132 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 265 insertions(+)
 create mode 100644 plugin/README.md
 create mode 100644 plugin/README_zh.md

diff --git a/plugin/README.md b/plugin/README.md
new file mode 100644
index 00000000..3b89ff40
--- /dev/null
+++ b/plugin/README.md
@@ -0,0 +1,133 @@
+# AngusInfra — Plugin Module
+
+[English](README.md) | [中文](README_zh.md)
+
+## Overview
+
+The `plugin` module provides an extensible plugin framework for AngusInfra. Key features include:
+
+- Storage and management of plugin artifacts (Disk or JPA storage backends)
+- Plugin lifecycle management (install, uninstall, load, unload)
+- Isolated class loading (`PluginClassLoader`) and a plugin runtime context
+- Dynamic registration of REST endpoints (plugins can expose APIs at runtime)
+- Management APIs for uploading, removing, listing and inspecting plugins
+
+## Module Layout
+
+- `api` — Public plugin interfaces and models (e.g. `Plugin`, `PluginContext`, `PluginManager`, `PluginInfo`).
+- `core` — Core runtime implementations (default manager, class loader, store interfaces and implementations).
+- `starter` — Spring Boot starter that provides auto-configuration, optional JPA store, and management controllers.
+- `examples` — Example plugin projects (e.g. `angus-plugin.github`, `angus-plugin.jenkins`).
+- `bom` — Dependency version management.
+
+## Key Interfaces / Classes (examples)
+
+- `cloud.xcan.angus.plugin.api.Plugin`
+- `cloud.xcan.angus.plugin.api.PluginManager`
+- `cloud.xcan.angus.plugin.api.PluginContext`
+- `cloud.xcan.angus.plugin.model.PluginInfo`, `PluginDescriptor`, `PluginState`
+- `cloud.xcan.angus.plugin.core.DefaultPluginManager`
+- `cloud.xcan.angus.plugin.core.PluginClassLoader`
+- `cloud.xcan.angus.plugin.store.PluginStore` (implementations: `DiskPluginStore`, `JpaPluginStore`)
+- `cloud.xcan.angus.plugin.core.DynamicRestEndpointManager`
+- `cloud.xcan.angus.plugin.autoconfigure.PluginProperties`
+
+## Quick Start
+
+### 1. Build the module
+
+From the project root or inside the `AngusInfra` module run:
+
+```bash
+mvn -pl plugin -am clean install
+```
+
+### 2. Add the starter to your Spring Boot application
+
+Maven dependency example:
+
+```xml
+<dependency>
+  <groupId>cloud.xcan.angus</groupId>
+  <artifactId>xcan-infra.plugin-starter</artifactId>
+  <version>${project.version}</version>
+</dependency>
+```
+
+### 3. Configuration (example `application.yml`)
+
+The starter binds configuration to `StarterPluginProperties` (which extends `PluginProperties`). Configuration prefix: `angus.plugin`.
+
+```yaml
+angus:
+  plugin:
+    storage-type: DISK          # DISK or JPA
+    directory: ./plugins       # Directory for plugin jars when using disk storage
+    data-directory: ./plugin-data
+    auto-load: true
+    max-upload-size: 52428800  # Max upload size (bytes)
+    enable-management-api: true
+    management-api-prefix: /api/plugins
+    enable-security-check: true
+    allowed-sources: ['*']
+    scan-interval: 30000
+    validate-on-startup: true
+
+spring:
+  datasource:
+    url: jdbc:h2:mem:angusdb;DB_CLOSE_DELAY=-1
+    driver-class-name: org.h2.Driver
+    username: sa
+    password: 
+  jpa:
+    hibernate:
+      ddl-auto: update
+```
+
+> Note: The property names in YAML use Spring Boot kebab-case (e.g. `storage-type`, `data-directory`) and map to fields in `PluginProperties`.
+
+## Management API
+
+The `starter` module includes `PluginManagementController` which is mapped by default under:
+
+`/api/v1/plugin-management`
+
+Main REST endpoints:
+
+- `POST /api/v1/plugin-management/install` — Upload and install a plugin (multipart/form-data with `pluginId` and `file` parameters)
+- `DELETE /api/v1/plugin-management/{pluginId}` — Uninstall a plugin; optional query parameter `removeFromStore` (default `true`)
+- `GET /api/v1/plugin-management/{pluginId}` — Get plugin details
+- `GET /api/v1/plugin-management/list` — List all plugins
+- `GET /api/v1/plugin-management/stats` — Get plugin system statistics
+
+Example: upload a plugin with curl (multipart):
+
+```bash
+curl -v \
+  -F "pluginId=my-plugin" \
+  -F "file=@./my-plugin.jar" \
+  http://localhost:8080/api/v1/plugin-management/install
+```
+
+## Building and Deploying Plugins
+
+1. See the example plugins under the `examples` submodule (for instance `angus-plugin.github`, `angus-plugin.jenkins`).
+2. Each example includes a `plugin.json` describing the plugin id, version and entry class. Build the plugin as a JAR.
+3. Place the plugin JAR into the configured plugin directory (`angus.plugin.directory`, e.g. `./plugins`), or upload and install it via the management API.
+4. After installation the `PluginManager` will manage the plugin lifecycle. If `auto-load=true`, plugins found in the directory will be automatically loaded on application startup.
+
+## Testing
+
+Run unit tests for the core module:
+
+```bash
+mvn -pl plugin/core test
+```
+
+## Contributing
+
+Contributions via issues and pull requests are welcome. Suggested guidelines:
+
+- Add unit tests that cover key logic
+- Follow existing coding style and Lombok usage patterns
+
diff --git a/plugin/README_zh.md b/plugin/README_zh.md
new file mode 100644
index 00000000..e870241f
--- /dev/null
+++ b/plugin/README_zh.md
@@ -0,0 +1,132 @@
+# AngusInfra — Plugin 模块
+
+[English](README.md) | [中文](README_zh.md)
+
+## 概述
+
+`plugin` 模块为 AngusInfra 提供可扩展的插件框架，主要支持：
+
+- 插件包的存储与管理（磁盘 / JPA 存储后端）
+- 插件生命周期管理（安装、卸载、加载、卸载）
+- 隔离类加载（`PluginClassLoader`）与插件运行上下文
+- 动态注册 REST 端点（插件可在运行时暴露 API）
+- 管理 API（上传、删除、列出、查询插件与统计信息）
+
+## 模块结构
+
+- `api` — 插件对外的接口与模型（例如 `Plugin`、`PluginContext`、`PluginManager`、`PluginInfo`）。
+- `core` — 插件运行时核心实现（默认管理器、插件类加载器、存储接口与实现等）。
+- `starter` — Spring Boot starter，包含自动配置、可选的 JPA 存储与管理控制器。
+- `examples` — 示例插件工程（例如 `angus-plugin.github`、`angus-plugin.jenkins`）。
+- `bom` — 依赖版本管理模块。
+
+## 关键类 / 接口（示例）
+
+- `cloud.xcan.angus.plugin.api.Plugin`
+- `cloud.xcan.angus.plugin.api.PluginManager`
+- `cloud.xcan.angus.plugin.api.PluginContext`
+- `cloud.xcan.angus.plugin.model.PluginInfo` / `PluginDescriptor` / `PluginState`
+- `cloud.xcan.angus.plugin.core.DefaultPluginManager`
+- `cloud.xcan.angus.plugin.core.PluginClassLoader`
+- `cloud.xcan.angus.plugin.store.PluginStore`（实现示例：`DiskPluginStore`、`JpaPluginStore`）
+- `cloud.xcan.angus.plugin.core.DynamicRestEndpointManager`
+- `cloud.xcan.angus.plugin.autoconfigure.PluginProperties`
+
+## 快速开始
+
+### 1. 构建模块
+
+在项目根目录或 `AngusInfra` 子模块目录运行：
+
+```bash
+mvn -pl plugin -am clean install
+```
+
+### 2. 在 Spring Boot 应用中引入 starter
+
+示例 Maven 依赖：
+
+```xml
+<dependency>
+  <groupId>cloud.xcan.angus</groupId>
+  <artifactId>xcan-infra.plugin-starter</artifactId>
+  <version>${project.version}</version>
+</dependency>
+```
+
+### 3. 配置（`application.yml` 示例）
+
+Starter 会将配置绑定到 `StarterPluginProperties`（继承自 `PluginProperties`），配置前缀为 `angus.plugin`。
+
+```yaml
+angus:
+  plugin:
+    storage-type: DISK          # DISK 或 JPA
+    directory: ./plugins       # 当使用磁盘存储时，插件 JAR 存放路径
+    data-directory: ./plugin-data
+    auto-load: true
+    max-upload-size: 52428800  # 最大上传大小（字节）
+    enable-management-api: true
+    management-api-prefix: /api/plugins
+    enable-security-check: true
+    allowed-sources: ['*']
+    scan-interval: 30000
+    validate-on-startup: true
+
+spring:
+  datasource:
+    url: jdbc:h2:mem:angusdb;DB_CLOSE_DELAY=-1
+    driver-class-name: org.h2.Driver
+    username: sa
+    password: 
+  jpa:
+    hibernate:
+      ddl-auto: update
+```
+
+> 注：属性名采用 Spring Boot 的 kebab-case（如 `storage-type`、`data-directory` 等），对应 `PluginProperties` 中的字段。
+
+## 管理 API
+
+`starter` 模块包含管理控制器 `PluginManagementController`，其默认映射为：
+
+`/api/v1/plugin-management`
+
+主要 REST 接口：
+
+- `POST /api/v1/plugin-management/install` — 上传并安装插件（multipart/form-data，参数：`pluginId`、`file`）
+- `DELETE /api/v1/plugin-management/{pluginId}` — 卸载插件；可选查询参数 `removeFromStore`（默认 `true`）
+- `GET /api/v1/plugin-management/{pluginId}` — 查询插件详情
+- `GET /api/v1/plugin-management/list` — 列出所有插件
+- `GET /api/v1/plugin-management/stats` — 获取插件系统统计信息
+
+示例：使用 curl 上传插件（multipart）：
+
+```bash
+curl -v \
+  -F "pluginId=my-plugin" \
+  -F "file=@./my-plugin.jar" \
+  http://localhost:8080/api/v1/plugin-management/install
+```
+
+## 插件构建与部署
+
+1. 参考 `examples` 子模块中的示例插件（例如 `angus-plugin.github`、`angus-plugin.jenkins`）。
+2. 每个示例插件包括 `plugin.json`（用于描述插件 id、版本、入口类等），将插件构建为 JAR。
+3. 将 JAR 放入配置的插件目录（`angus.plugin.directory`，如 `./plugins`），或通过管理 API 上传并安装。
+4. 插件安装后由 `PluginManager` 管理其生命周期；若 `auto-load=true`，服务启动时会自动加载目录下的插件。
+
+## 测试
+
+运行核心模块的单元测试：
+
+```bash
+mvn -pl plugin/core test
+```
+
+## 贡献
+
+欢迎提交 issue 与 PR。建议遵循：
+
+- 保持单元测试覆盖关键逻辑
+- 遵循现有代码风格与 Lombok 使用约定

From 9a5339def7ee460f707529f93c8261ca0b7be6da Mon Sep 17 00:00:00 2001
From: LiuXiaoLong <75962798+xcancloud@users.noreply.github.com>
Date: Wed, 29 Oct 2025 20:00:52 +0800
Subject: [PATCH 3/4] Add README and Chinese translation for cache module

---
 cache/README.md    | 95 ++++++++++++++++++++++++++++++++++++++++++++++
 cache/README_zh.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 190 insertions(+)
 create mode 100644 cache/README.md
 create mode 100644 cache/README_zh.md

diff --git a/cache/README.md b/cache/README.md
new file mode 100644
index 00000000..d1e85408
--- /dev/null
+++ b/cache/README.md
@@ -0,0 +1,95 @@
+# AngusInfra — Cache Module
+
+## Overview
+
+The `cache` module implements a hybrid two-level cache for AngusInfra combining in-memory caching and a persistent backing store. It is designed to provide:
+
+- Fast in-memory operations for hot data
+- Persistent storage for durability and sharing across instances (via JPA)
+- Unified management APIs for monitoring and administration
+- Transactional semantics via a proxy wrapper for safe persistence operations
+
+## Module Layout
+
+- `core` — Core cache interfaces and implementations (e.g. `HybridCacheManager`, `MemoryCache`, `CachePersistence` interfaces).
+- `starter` — Spring Boot starter providing auto-configuration, optional Spring Data JPA persistence adapter and management REST controllers.
+
+## Key Interfaces / Classes
+
+- `cloud.xcan.angus.cache.IDistributedCache` — Public cache API used by applications.
+- `cloud.xcan.angus.cache.HybridCacheManager` — Core implementation combining memory cache and persistence.
+- `cloud.xcan.angus.cache.MemoryCache` — In-memory cache implementation.
+- `cloud.xcan.angus.cache.CachePersistence` — Persistence abstraction for storing cache entries.
+- `cloud.xcan.angus.cache.entry.CacheEntry` / `CacheEntryRepository` — JPA entity and repository for persisted entries.
+- `cloud.xcan.angus.cache.jpa.SpringDataCacheEntryRepository` — Spring Data repository (starter).
+- `cloud.xcan.angus.cache.autoconfigure.HybridCacheAutoConfiguration` — Auto-configuration that wires persistence and management controller when appropriate.
+- `cloud.xcan.angus.cache.management.CacheManagementController` — Management REST controller exposing monitoring and admin endpoints.
+
+## Quick Start
+
+### 1. Build the module
+
+From the repository root run:
+
+```bash
+mvn -pl cache -am clean install
+```
+
+### 2. Add the starter to your Spring Boot application
+
+Example Maven dependency:
+
+```xml
+<dependency>
+  <groupId>cloud.xcan.angus</groupId>
+  <artifactId>xcan-infra.cache-starter</artifactId>
+  <version>${project.version}</version>
+</dependency>
+```
+
+### 3. Persistence (optional)
+
+The starter will auto-configure a `CachePersistence` adapter if a Spring Data `SpringDataCacheEntryRepository` bean is present (i.e. you include the JPA starter and repository). Otherwise the cache will run with in-memory persistence stub behavior.
+
+If you enable JPA persistence, configure a datasource in `application.yml`.
+
+## Management API
+
+The management controller is available under `/api/v1/cache` and provides the following endpoints:
+
+- `GET /api/v1/cache/stats` — Get aggregated cache statistics (entries, hits, misses, memory size, etc.)
+- `GET /api/v1/cache/{key}` — Get cache value for a key (returns business error wrapper if key not found)
+- `PUT /api/v1/cache/{key}` — Set value for a key (JSON body: value, optional `ttlSeconds`)
+- `DELETE /api/v1/cache/{key}` — Delete a cache entry
+- `GET /api/v1/cache/{key}/exists` — Check if key exists
+- `GET /api/v1/cache/{key}/ttl` — Get TTL in seconds for key (-1 = no timeout, -2 = not found)
+- `POST /api/v1/cache/{key}/expire` — Set TTL for an existing key (JSON body `ttlSeconds`)
+- `POST /api/v1/cache/clear` — Clear all cache entries (memory + persistence)
+- `POST /api/v1/cache/cleanup` — Remove expired entries from persistence and return deleted count
+
+Example: set a cache value via curl
+
+```bash
+curl -X PUT -H "Content-Type: application/json" -d '{"value":"hello","ttlSeconds":60}' http://localhost:8080/api/v1/cache/my-key
+```
+
+## Building and Deploying
+
+- Include the starter in your Spring Boot service to enable management endpoints and optional JPA persistence support.
+- If using persistent store, ensure the `entry` JPA entity is scanned and the repository bean is available.
+
+## Testing
+
+Run unit tests for the cache module core and starter:
+
+```bash
+mvn -pl cache/core test
+mvn -pl cache/starter test
+```
+
+## Contributing
+
+Contributions welcome. Please:
+
+- Add unit tests covering behavior changes
+- Keep APIs backward compatible where possible
diff --git a/cache/README_zh.md b/cache/README_zh.md
new file mode 100644
index 00000000..51a75134
--- /dev/null
+++ b/cache/README_zh.md
@@ -0,0 +1,95 @@
+# AngusInfra — 缓存模块
+
+## 概述
+
+`cache` 模块实现了一个混合两级缓存（内存 + 持久化），用于提供：
+
+- 对热数据的快速内存访问
+- 持久化后端（JPA）用于数据持久化与多实例共享
+- 统一的管理 API 用于监控与管理
+- 通过事务代理（TransactionalDistributedCache）保证与持久化交互的安全性
+
+## 模块结构
+
+- `core` — 核心缓存接口与实现（例如 `HybridCacheManager`、`MemoryCache`、`CachePersistence`）。
+- `starter` — Spring Boot starter，提供自动配置、Spring Data JPA 适配器和管理 REST 控制器。
+
+## 关键接口 / 类
+
+- `cloud.xcan.angus.cache.IDistributedCache` — 应用使用的公共缓存 API。
+- `cloud.xcan.angus.cache.HybridCacheManager` — 将内存缓存与持久化结合的核心实现。
+- `cloud.xcan.angus.cache.MemoryCache` — 内存缓存实现。
+- `cloud.xcan.angus.cache.CachePersistence` — 持久化抽象接口。
+- `cloud.xcan.angus.cache.entry.CacheEntry` / `CacheEntryRepository` — 持久化实体与仓库。
+- `cloud.xcan.angus.cache.jpa.SpringDataCacheEntryRepository` — Spring Data 仓库（starter 模块）。
+- `cloud.xcan.angus.cache.autoconfigure.HybridCacheAutoConfiguration` — 自动配置类，根据仓库是否存在装配持久化与管理控制器。
+- `cloud.xcan.angus.cache.management.CacheManagementController` — 管理 REST 控制器。
+
+## 快速开始
+
+### 1. 构建模块
+
+在仓库根目录运行：
+
+```bash
+mvn -pl cache -am clean install
+```
+
+### 2. 在 Spring Boot 应用中引入 starter
+
+示例 Maven 依赖：
+
+```xml
+<dependency>
+  <groupId>cloud.xcan.angus</groupId>
+  <artifactId>xcan-infra.cache-starter</artifactId>
+  <version>${project.version}</version>
+</dependency>
+```
+
+### 3. 持久化（可选）
+
+如果类路径中存在 `SpringDataCacheEntryRepository`（即启用 Spring Data JPA 并扫描实体），starter 会自动配置 `CachePersistence` 适配器。否则缓存仅以内存行为为主。
+
+若启用 JPA，请在 `application.yml` 中配置数据源。
+
+## 管理 API
+
+管理控制器映射在 `/api/v1/cache`，提供以下接口：
+
+- `GET /api/v1/cache/stats` — 获取缓存统计信息（条目数、命中、未命中、内存大小等）
+- `GET /api/v1/cache/{key}` — 获取缓存值（找不到时会以业务错误的形式在包装器中返回）
+- `PUT /api/v1/cache/{key}` — 设置缓存值（JSON body 包含 `value` 和可选的 `ttlSeconds`）
+- `DELETE /api/v1/cache/{key}` — 删除缓存键
+- `GET /api/v1/cache/{key}/exists` — 检查键是否存在
+- `GET /api/v1/cache/{key}/ttl` — 获取键的 TTL（秒），-1 = 永不过期，-2 = 未找到
+- `POST /api/v1/cache/{key}/expire` — 为存在的键设置 TTL（JSON body：`ttlSeconds`）
+- `POST /api/v1/cache/clear` — 清空所有缓存（内存 + 持久化）
+- `POST /api/v1/cache/cleanup` — 从持久化存储清理过期项并返回删除数量
+
+示例：通过 curl 设置缓存值
+
+```bash
+curl -X PUT -H "Content-Type: application/json" -d '{"value":"hello","ttlSeconds":60}' http://localhost:8080/api/v1/cache/my-key
+```
+
+## 构建与部署
+
+- 在 Spring Boot 服务中包含 starter 来启用管理端点与可选的 JPA 持久化支持。
+- 使用持久化存储时，确保 `entry` JPA 实体被扫描且仓库 bean 可用。
+
+## 测试
+
+运行模块的单元测试：
+
+```bash
+mvn -pl cache/core test
+mvn -pl cache/starter test
+```
+
+## 贡献
+
+欢迎提交 PR 与 issue。建议：
+
+- 为变更添加单元测试
+- 在可能的情况下保持 API 向后兼容

From b1d60de78ae94da0a6c2cfbb803bc83edc20c951 Mon Sep 17 00:00:00 2001
From: LiuXiaoLong <75962798+xcancloud@users.noreply.github.com>
Date: Wed, 29 Oct 2025 20:01:06 +0800
Subject: [PATCH 4/4] Update README to enhance contribution guidelines and add
 starter test command

---
 plugin/README.md    | 5 +++--
 plugin/README_zh.md | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/plugin/README.md b/plugin/README.md
index 3b89ff40..c66e3d99 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -122,12 +122,13 @@ Run unit tests for the core module:
 
 ```bash
 mvn -pl plugin/core test
+mvn -pl plugin/starter test
 ```
 
 ## Contributing
 
 Contributions via issues and pull requests are welcome. Suggested guidelines:
 
-- Add unit tests that cover key logic
-- Follow existing coding style and Lombok usage patterns
+- Add unit tests covering behavior changes
+- Keep APIs backward compatible where possible
 
diff --git a/plugin/README_zh.md b/plugin/README_zh.md
index e870241f..f8fac0ac 100644
--- a/plugin/README_zh.md
+++ b/plugin/README_zh.md
@@ -122,11 +122,12 @@ curl -v \
 
 ```bash
 mvn -pl plugin/core test
+mvn -pl plugin/starter test
 ```
 
 ## 贡献
 
 欢迎提交 issue 与 PR。建议遵循：
 
-- 保持单元测试覆盖关键逻辑
-- 遵循现有代码风格与 Lombok 使用约定
+- 为变更添加单元测试
+- 在可能的情况下保持 API 向后兼容