Dev/2.0.0

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

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 向后兼容

plugin/README.md

@@ -0,0 +1,134 @@
+# 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
+mvn -pl plugin/starter test
+```
+
+## Contributing
+
+Contributions via issues and pull requests are welcome. Suggested guidelines:
+
+- Add unit tests covering behavior changes
+- Keep APIs backward compatible where possible
+