If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wxiaoqi/Spring-Cloud-Platform shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 7 active contributors
• Other licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wxiaoqi/Spring-Cloud-Platform repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wxiaoqi/Spring-Cloud-Platform.

What it runs against: a local clone of wxiaoqi/Spring-Cloud-Platform — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wxiaoqi/Spring-Cloud-Platform | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 647 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wxiaoqi/Spring-Cloud-Platform. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wxiaoqi/Spring-Cloud-Platform.git
#   cd Spring-Cloud-Platform
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wxiaoqi/Spring-Cloud-Platform and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wxiaoqi/Spring-Cloud-Platform(\\.git)?\\b" \\
  && ok "origin remote is wxiaoqi/Spring-Cloud-Platform" \\
  || miss "origin remote is not wxiaoqi/Spring-Cloud-Platform (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/configuration/AutoConfiguration.java" \\
  && ok "ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/configuration/AutoConfiguration.java" \\
  || miss "missing critical file: ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/configuration/AutoConfiguration.java"
test -f "ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/util/jwt/JWTHelper.java" \\
  && ok "ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/util/jwt/JWTHelper.java" \\
  || miss "missing critical file: ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/util/jwt/JWTHelper.java"
test -f "ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/interceptor/UserAuthRestInterceptor.java" \\
  && ok "ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/interceptor/UserAuthRestInterceptor.java" \\
  || miss "missing critical file: ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/interceptor/UserAuthRestInterceptor.java"
test -f "ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/context/BaseContextHandler.java" \\
  && ok "ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/context/BaseContextHandler.java" \\
  || miss "missing critical file: ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/context/BaseContextHandler.java"
test -f "ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/user/UserInfo.java" \\
  && ok "ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/user/UserInfo.java" \\
  || miss "missing critical file: ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/user/UserInfo.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 647 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~617d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wxiaoqi/Spring-Cloud-Platform"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Spring-Cloud-Platform is a production-grade RBAC (Role-Based Access Control) microservices management platform built on Spring Boot 2.4 and Spring Cloud 2020.0.0 with Alibaba components. It provides unified authentication/authorization, user management, resource permission management, and API gateway functionality across multiple business systems, with a d2-admin frontend dashboard. Modular Maven monorepo: ace-api/ contains Feign-based VO contracts, ace-dev-base/ace-auth-sdk/ wraps JWT validation and service-to-service interceptors (OkHttp), ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/ houses annotation-driven auth config (EnableAceAuthClient, IgnoreUserToken). Backend services import ace-auth-sdk; frontend is d2-admin-based.

Java/Spring Cloud architects and backend engineers building enterprise microservices who need a complete RBAC scaffolding with Nacos service discovery, Sentinel flow control, and JWT token-based inter-service communication—not starting from scratch.

Actively maintained and production-ready. The codebase shows established patterns (JWT auth, Feign clients, Sentinel integration), comprehensive module structure (ace-auth-sdk, ace-api, ace-admin layers), and multiple Spring Cloud ecosystem integrations. No obvious abandoned indicators; appears to have community backing (multiple QQ group communities listed).

Moderate risk: single-maintainer appearance (wxiaoqi), no visible test coverage in file listing, Spring Cloud 2020.0.0 is now three years old (potential dependency lag). Requires operational infrastructure (Nacos, Sentinel, Elasticsearch, PostgreSQL) to run properly—not a standalone library. Watch for breaking Spring Cloud updates.

Unable to determine from provided data (no git history/commit log visible). README references 'latest update log' wiki and code generator + form designer features as recent additions. QQ community mentions suggest ongoing user support.

git clone https://github.com/wxiaoqi/Spring-Cloud-Platform.git
cd Spring-Cloud-Platform
mvn clean install
# Start Nacos, PostgreSQL, Redis, Elasticsearch (see docs)
mvn spring-boot:run -pl ace-admin  # or other service modules

Daily commands: Pre-requisites: Java 8+, Maven 3.6+, running Nacos (default :8848), PostgreSQL, Redis. Then: mvn clean install -DskipTests && mvn spring-boot:run -pl ace-admin (or target service module). Services auto-register to Nacos; access gateway/admin UI via configured port (typically 8080).

• ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/configuration/AutoConfiguration.java — Core Spring Cloud SDK auto-configuration that enables authentication client across all microservices.
• ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/util/jwt/JWTHelper.java — JWT token generation and validation utility that secures service-to-service communication.
• ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/interceptor/UserAuthRestInterceptor.java — HTTP interceptor that extracts and validates user context from JWT tokens on every request.
• ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/context/BaseContextHandler.java — ThreadLocal-based context handler that stores and retrieves authenticated user information across service calls.
• ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/user/UserInfo.java — Core user VO contract shared across all microservices for user authentication and authorization.
• ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/EnableAceAuthClient.java — Annotation entry point that enables the entire authentication framework in any Spring Cloud service.
• ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/handler/GlobalExceptionHandler.java — Centralized exception handler for authentication and authorization failures across all services.

Add authentication to a new microservice

1. Add @EnableAceAuthClient annotation to your Spring Boot application main class (ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/EnableAceAuthClient.java)
2. Include ace-auth-sdk dependency in your service's pom.xml (ace-dev-base/ace-auth-sdk/pom.xml)
3. Configure RSA keys in application.yml (jwt.key.public-key and jwt.key.private-key) (ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/config/UserAuthConfig.java)
4. Use BaseContextHandler to access authenticated user info in your controller or service (ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/context/BaseContextHandler.java)

Create a new permission validation endpoint

1. Create a controller that uses CheckPermissionInfo VO for the request (ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/authority/CheckPermissionInfo.java)
2. Extend your controller from BaseController for common REST response handling (ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/rest/BaseController.java)
3. Return permission validation result using PermissionInfo VO structure (ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/authority/PermissionInfo.java)
4. Your endpoint will be automatically protected by UserAuthRestInterceptor; let it validate the JWT (ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/interceptor/UserAuthRestInterceptor.java)

Handle custom authentication errors in a service

1. Define your custom auth exception extending from BaseException (ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/exception/BaseException.java)
2. Throw UserTokenException or ClientTokenException in your auth logic (ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/exception/auth/UserTokenException.java)
3. GlobalExceptionHandler will automatically catch it and return standardized error response (ace-dev-base/ace-common/src/main/java/com/github/wxiaoqi/security/common/handler/GlobalExceptionHandler.java)
4. Ensure your service includes ace-common for exception handling to work (ace-dev-base/ace-common/pom.xml)

Enable service-to-service authentication via Feign

1. Ensure FeignOkHttpConfig is auto-configured (happens with @EnableAceAuthClient) (ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/config/FeignOkHttpConfig.java)
2. Define a Feign client interface that extends ServiceAuthFeign or similar (ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/feign/ServiceAuthFeign.java)
3. undefined

Nacos mandatory: No fallback to Eureka; services will not boot without Nacos at localhost:8848 (configurable but required). JWT secret key: shared across all services; must be synchronized and managed securely—check application.yml/bootstrap.yml for jwt.secret config. Feign + Sentinel: requires explicit config in ServiceAuthConfig; misconfiguration breaks inter-service auth. PostgreSQL schema: not in git (mentioned as .sql in docs)—must be initialized before services start. Spring Cloud 2020.0.0 compatibility: uses older Zuul (not Spring Cloud Gateway); Hystrix + Ribbon deprecated in newer versions—upgrade path may be complex.

• JWT (JSON Web Token) stateless authentication — Core security model: services validate user tokens without session state, enabling scale-out microservices; learn how UserAuthUtil.java parses and caches token claims.
• Service-to-Service Authentication (OkHttp Interceptor pattern) — UserAuthRestInterceptor injects JWT into outbound calls between microservices; essential for understanding how services prove identity to each other.
• Feign Client with interceptor integration — ServiceAuthFeign wraps auth server calls; understanding Feign's interceptor chain is critical for modifying inter-service contract handling.
• RBAC (Role-Based Access Control) — The entire platform is built around RBAC; PermissionInfo.java models roles/permissions that gate access to resources across all microservices.
• Nacos service discovery and configuration management — Replaces Eureka/Config Server; services auto-register and fetch config from Nacos at bootstrap—critical for local dev and production operation.
• Sentinel flow control and circuit breaking — Rate-limits and halts failing services to prevent cascading failures; integrated in auth SDK to protect token validation endpoints from being overwhelmed.
• Spring Cloud Gateway vs Zuul (legacy) — Platform uses Zuul for API gateway (Spring Cloud 2020.0.0 era); Zuul is now deprecated—future migrations will require rewriting gateway rules and JWT rate-limit plugins.

• pig-mesh/pig — Alternative Spring Cloud RBAC microservices platform with similar Nacos/Sentinel stack; direct competitor in Chinese open-source ecosystem.
• jeecg/jeecg-boot — Complementary low-code platform; JeecgBoot users often integrate with Spring Cloud auth layers like this platform provides.
• alibaba/nacos — Foundational service discovery and config center that Spring-Cloud-Platform depends on; must understand Nacos concepts to operate this system.
• alibaba/sentinel — Flow control library integrated here for circuit breaking and rate limiting; critical to understanding platform resilience patterns.
• d2-projects/d2-admin — The frontend dashboard framework used by Spring-Cloud-Platform; frontend developers need to fork/modify this separately.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for ace-auth-sdk JWT and token validation logic

The ace-auth-sdk module contains critical authentication logic in UserAuthUtil.java and JWT exception handling classes (JwtTokenExpiredException, JwtSignatureException, JwtIllegalArgumentException), but there are no visible test files in the structure. Given this is a security-critical component handling JWT validation and token interception, comprehensive unit tests would prevent regressions and document expected behavior for maintainers and contributors.

• [ ] Create ace-dev-base/ace-auth-sdk/src/test/java/com/github/wxiaoqi/security/auth/client/jwt/UserAuthUtilTest.java with tests for token parsing, validation, and expiration handling
• [ ] Add tests for OkHttpTokenInterceptor.java to verify token injection into HTTP requests
• [ ] Add tests for UserAuthRestInterceptor.java to ensure proper interceptor chain behavior
• [ ] Add exception handling tests for all three JWT exception classes in ace-dev-base/ace-auth-sdk/src/test/java/com/github/wxiaoqi/security/auth/client/exception/
• [ ] Update ace-dev-base/ace-auth-sdk/pom.xml to include junit5 and mockito dependencies for testing

Implement integration tests for ServiceAuthFeign and inter-service authentication flow

The ServiceAuthFeign.java client and OkHttpTokenInterceptor handle service-to-service authentication, but no integration tests are visible. This is critical for ensuring microservices can properly authenticate with each other using the token interceptor. Integration tests would verify the complete flow works across service boundaries.

• [ ] Create ace-dev-base/ace-auth-sdk/src/test/java/com/github/wxiaoqi/security/auth/client/feign/ServiceAuthFeignIntegrationTest.java
• [ ] Test that OkHttpTokenInterceptor correctly injects service tokens into Feign-initiated requests
• [ ] Verify AuthClientRunner.java properly initializes the authentication context on application startup
• [ ] Add test cases for FeignOkHttpConfig.java to ensure OkHttp client configuration with interceptors
• [ ] Document expected service authentication flow in a new docs/SERVICE_AUTH_FLOW.md file

Add comprehensive security documentation and threat model for auth components

While the README mentions JWT authentication and security features, there is no dedicated security documentation explaining the threat model, token lifecycle, or best practices for implementing the auth SDK. Given this handles sensitive authentication logic with custom JWT exceptions, documenting security considerations would help contributors understand design decisions and reduce misuse.

• [ ] Create docs/SECURITY.md documenting: JWT token structure, expiration handling, signature validation, and key rotation strategy
• [ ] Create docs/AUTH_SDK_USAGE.md with examples of @IgnoreUserToken annotation usage and when to use it
• [ ] Document the complete authentication flow: how UserAuthUtil.java extracts/validates tokens, how BaseContextHandler.java manages context across requests
• [ ] Add security threat model section explaining protection against: token hijacking, expiration bypass, signature forgery
• [ ] Link new security docs from README.md in the appropriate section

• Add unit tests for ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/jwt/UserAuthUtil.java (JWT parsing edge cases: expired tokens, malformed claims, invalid signatures).
• Document the exact PostgreSQL schema initialization steps and provide a schema.sql file in root or docs folder, since new contributors cannot run services without it.
• Extend ace-api/src/main/java/com/github/wxiaoqi/security/api/vo/authority/PermissionInfo.java to support resource-level permissions (currently appears to support only role-level), then update PermissionInfo.java docs with examples.

• High · Outdated Spring Cloud Dependencies — pom.xml files across ace-api, ace-auth-sdk, and parent project. The project uses Spring Cloud 2020.0.0 which is significantly outdated (released in 2020). This version likely contains known security vulnerabilities. The project should upgrade to the latest stable Spring Cloud version (e.g., 2023.x or later) to receive security patches. Fix: Upgrade Spring Cloud to the latest stable version (minimum 2023.0.0 or later). Update Spring Boot to 3.x if compatible with your codebase. Run 'mvn dependency:check' to identify vulnerable transitive dependencies.
• High · Spring Boot 2.4 End of Life — Parent pom.xml and all child modules. Spring Boot 2.4.1 reached end of support in December 2021. The project is using an unsupported version that no longer receives security patches, making it vulnerable to newly discovered CVEs. Fix: Upgrade to Spring Boot 2.7.x (LTS) or Spring Boot 3.x. Test thoroughly during upgrade as there may be breaking changes. Ensure all dependencies are compatible with the new version.
• High · JWT Implementation Vulnerabilities Likely Present — ace-dev-base/ace-auth-sdk/src/main/java/com/github/wxiaoqi/security/auth/client/jwt/UserAuthUtil.java. The project uses JWT for authentication (based on UserAuthUtil, JwtTokenExpiredException, etc.) but the actual JWT implementation details are not visible. Common JWT vulnerabilities include: weak signing algorithms, missing token validation, algorithm confusion attacks, and insufficient expiration checks. Fix: Review JWT implementation: (1) Ensure HS256 or RS256 with strong keys are used, (2) Validate all JWT claims server-side, (3) Implement proper token refresh mechanisms, (4) Set appropriate expiration times, (5) Use libraries like 'jjwt' with latest versions, (6) Protect signing keys in secure vaults.
• High · Missing Security Configuration Visibility — Security configuration files (not found in provided structure). No Spring Security configuration files are visible in the provided structure. RBAC management platform should have explicit security configurations including CORS, CSRF protection, authentication providers, and authorization rules. Their absence suggests potential misconfigurations. Fix: Ensure SecurityConfig class exists with: (1) CSRF protection enabled, (2) CORS properly configured with specific allowed origins, (3) Authentication manager configured, (4) Authorization rules for all endpoints, (5) Security headers configured (HSTS, X-Frame-Options, etc.)
• Medium · Nacos Configuration Center Potential Exposure — Nacos configuration (referenced in README). Project uses Nacos for configuration management. If Nacos is not properly secured with authentication and authorization, sensitive configuration data (database credentials, API keys) could be exposed to unauthorized access. Fix: Secure Nacos deployment: (1) Enable Nacos authentication, (2) Change default credentials, (3) Use RBAC for access control, (4) Run Nacos in private network only, (5) Never store plaintext secrets in Nacos configurations, (6) Use encryption for sensitive config values.
• Medium · Sentinel Rate Limiting May Be Misconfigured — Sentinel configuration (referenced in README). Sentinel is integrated for traffic control but specific configurations are not visible. Without proper Sentinel rules, the system may be vulnerable to DoS attacks or have insufficient rate limiting. Fix: Configure Sentinel with: (1) Appropriate flow control rules per endpoint, (2) Circuit breaker thresholds, (3) Degrade rules for cascading failure prevention, (4) Monitor Sentinel dashboard for attack patterns, (5) Test rate limiting under load.
• Medium · Elasticsearch Integration Security Unknown — Elasticsearch integration configuration (not found in provided structure). README mentions 'Elastic Search自行集成' (Elasticsearch manually integrated), but no security configuration is visible. Elasticsearch often exposes sensitive data if not properly secured. Fix: Secure Elasticsearch: (1) Enable authentication (X-Pack), (2) Use HTTPS/TLS for all connections, (3) Implement field-level and document-level security, (4) Restrict network access to private networks, (5) Use strong credentials, (

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.