create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-audit-log/assets/AuditLogAspect.java

@@ -0,0 +1,262 @@
+package com.yss.cloud.audit.configuration;
+
+import cn.hutool.jwt.JWT;
+import cn.hutool.jwt.JWTUtil;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import com.yss.cloud.audit.AuditLog;
+import com.yss.cloud.audit.subscriber.YssAuditPublishService;
+import com.yss.cloud.dto.audit.message.AuditMessage;
+import com.yss.cloud.dto.audit.message.AuditResourceType;
+import com.yss.cloud.dto.audit.message.EventMessage;
+import com.yss.cloud.dto.user.UserInfo;
+import com.yss.cloud.user.AuthUserInfoUtil;
+import lombok.SneakyThrows;
+import lombok.extern.slf4j.Slf4j;
+import org.aspectj.lang.JoinPoint;
+import org.aspectj.lang.Signature;
+import org.aspectj.lang.annotation.AfterReturning;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.cglib.beans.BeanMap;
+import org.springframework.context.expression.EnvironmentAccessor;
+import org.springframework.context.expression.MapAccessor;
+import org.springframework.expression.Expression;
+import org.springframework.expression.ExpressionParser;
+import org.springframework.expression.ParserContext;
+import org.springframework.expression.spel.standard.SpelExpressionParser;
+import org.springframework.expression.spel.support.StandardEvaluationContext;
+import org.springframework.util.StringUtils;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import javax.servlet.http.HttpServletRequest;
+import java.io.File;
+import java.io.InputStream;
+import java.net.NetworkInterface;
+import java.security.Principal;
+import java.time.LocalDateTime;
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+@Aspect
+@Slf4j
+public class AuditLogAspect {
+    public static final String USER_AGENT = "User-Agent";
+    /**
+     * 引用来源
+     */
+    public static final String REFERER = "Referer";
+    public static final String UNKNOWN = "unknown";
+    private static final ExpressionParser parser = new SpelExpressionParser();
+    /**
+     * 正则表达式，匹配 #{xxx} 格式的变量表达式
+     */
+    private static final Pattern varPattern = Pattern.compile("#\\{[a-zA-Z0-9_\\[\\]\\?\\.]+\\}");
+    @Autowired
+    private YssAuditPublishService yssAuditPublishService;
+    private static final ObjectMapper OM = new ObjectMapper();
+    static {
+        OM.registerModule(new JavaTimeModule());
+        OM.setSerializationInclusion(JsonInclude.Include.NON_NULL);
+    }
+    private static boolean containsPattern(String text) {
+        Matcher matcher = varPattern.matcher(text);
+        return matcher.find();
+    }
+
+    private static String getMacAddr() {
+        try {
+            Enumeration<NetworkInterface> networkInterfaces = NetworkInterface.getNetworkInterfaces();
+            while (networkInterfaces.hasMoreElements()) {
+                NetworkInterface networkInterface = networkInterfaces.nextElement();
+                if (networkInterface.getName().startsWith("en")) {
+                    byte[] macAddress = networkInterface.getHardwareAddress();
+                    if (macAddress != null) {
+                        StringJoiner macAddressBuilder = new StringJoiner("-");
+                        for (byte b : macAddress) {
+                            macAddressBuilder.add(String.format("%02X", b));
+                        }
+                        return macAddressBuilder.toString();
+                    }
+                }
+            }
+        } catch (Exception e) {
+            return "";
+        }
+        return "";
+    }
+
+    @SneakyThrows
+    @AfterReturning(value = "@annotation(com.yss.cloud.audit.AuditLog)&&execution(public * *(..))", returning = "result")
+    public void logAudit(JoinPoint joinPoint, Object result) {
+        Signature signature = joinPoint.getSignature();
+
+        AuditMessage.AuditMessageBuilder builder = AuditMessage.builder();
+        Map<String, Object> referencedResources = new HashMap<>();
+
+        Class<?> declaringType = signature.getDeclaringType();
+        if (signature instanceof MethodSignature) {
+            AuditLog audit = ((MethodSignature) signature).getMethod().getAnnotation(AuditLog.class);
+            if (audit.isNeedArgs()) {
+                referencedResources.put("参数审计", buildLogArgsDetails(joinPoint));
+            }
+            if (audit.isNeedResult()) {
+                referencedResources.put("结果审计", result);
+            }
+            String summary = StringUtils.hasLength(audit.value()) ? audit.value() : audit.summary();
+
+            boolean containsVariableExpression = containsPattern(summary);
+
+            if (containsVariableExpression) {
+                log.info("文本中包含变量表达式。");
+                StandardEvaluationContext context = new StandardEvaluationContext(referencedResources);
+                context.addPropertyAccessor(new MapAccessor());
+                context.addPropertyAccessor(new EnvironmentAccessor());
+                try {
+                    Expression expression = parser.parseExpression(summary, ParserContext.TEMPLATE_EXPRESSION);
+                    summary = expression.getValue(context, String.class);
+                } catch (Exception e) {
+                    log.warn(e.getLocalizedMessage());
+                }
+
+            }
+
+            builder.operation(Objects.isNull(audit.operation())
+                            ? signature.getName()
+                            : audit.operation().getOperationType())
+                    .content(summary)
+                    .resourceType(audit.resource().getResourceType());
+        }
+
+        EventMessage.EventMessageBuilder eventMessageBuilder = EventMessage.builder()
+                .eventId(UUIDGenerator.generateUUID())
+                .serviceName(declaringType.getName())
+                .eventTime(LocalDateTime.now())
+                .userIdentity(AuthUserInfoUtil.currentUserJson())
+                .macAddr(getMacAddr());
+        if (result instanceof Principal){
+            //登录情况获取用户信息
+            BeanMap beanMap = BeanMap.create(result);
+            Object additionalParameters = beanMap.get("additionalParameters");
+            if (Objects.nonNull(additionalParameters)){
+                Map<String,String> additionalParametersMap = (Map<String,String>)additionalParameters;
+                log.info("[登录用户信息] additionalParametersMap=>{}",additionalParametersMap);
+                String idToken = additionalParametersMap.get("id_token");
+                final JWT jwt = JWTUtil.parseToken(idToken);
+                UserInfo userInfo = new UserInfo();
+                userInfo.setUserName(String.valueOf(jwt.getPayload("sub")));
+
+                String loginDisplayName = Objects.nonNull(jwt.getPayload("loginDisplayName"))?
+                        String.valueOf(jwt.getPayload("loginDisplayName")):
+                        String.valueOf(jwt.getPayload("sub"));
+                userInfo.setLoginDisplayName(loginDisplayName);
+                eventMessageBuilder.userIdentity(OM.writeValueAsString(userInfo));
+            }
+
+        }
+        try{
+            HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
+            String realIp = getIpAddr(request);
+            eventMessageBuilder.userAgent(request.getHeader(USER_AGENT))
+                    .sourceIpAddress(realIp)
+                    .eventName(signature.getName())
+                    .requestUrl(request.getRequestURL().toString())
+                    .eventSource(Objects.isNull(request.getHeader(REFERER)) ? request.getRequestURL().toString() : request.getHeader(REFERER));
+        }catch (Exception e){
+            log.warn("非rest请求无法获取客户端ip");
+            eventMessageBuilder.userAgent("")
+                    .sourceIpAddress("")
+                    .eventName(signature.getName())
+                    .requestUrl("")
+                    .eventSource("");
+        }
+
+        AuditMessage auditMessage = builder
+                .eventMessage(
+                        eventMessageBuilder.build()
+                )
+                .referencedResources(referencedResources)
+                .build();
+
+
+        auditMessage.setResourceName(AuditResourceType.valueOf(auditMessage.getResourceType()).getResourceName());
+
+        yssAuditPublishService.publish(auditMessage);
+    }
+
+    /**
+     * 辅助方法，构建日志详情
+     *
+     * @param joinPoint 参数点
+     */
+    @SneakyThrows
+    private List<Object> buildLogArgsDetails(JoinPoint joinPoint) {
+        Object[] args = joinPoint.getArgs();
+        return Arrays.stream(args)
+                .filter(arg -> !(arg instanceof ServletRequest || arg instanceof ServletResponse))
+                .map(arg -> {
+                    if (arg instanceof File) {
+                        return ((File) arg).getName();
+                    } else if (arg instanceof InputStream) {
+                        return "参数为输入流";
+                    } else {
+                        return arg;
+                    }
+                })
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * 获取真实ip地址,不返回内网地址
+     *
+     * @param request 请求对象
+     * @return 真实客户ip
+     */
+    public String getIpAddr(HttpServletRequest request) {
+        //目前则是网关ip
+        String ip = request.getHeader("X-Forwarded-For");
+        if (ip != null && !ip.isEmpty() && !UNKNOWN.equalsIgnoreCase(ip)) {
+            return getFirstIpAddr(ip);
+        }
+        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
+            ip = request.getHeader("Proxy-Client-IP");
+        }
+        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
+            ip = request.getHeader("WL-Proxy-Client-IP");
+        }
+        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
+            ip = request.getHeader("HTTP_CLIENT_IP");
+        }
+        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
+            ip = request.getHeader("HTTP_X_FORWARDED_FOR");
+        }
+        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
+            ip = request.getRemoteAddr();
+        }
+
+
+        return getFirstIpAddr(ip);
+    }
+
+    private static String getFirstIpAddr(String ip) {
+        if (ip != null && !ip.isEmpty() && !UNKNOWN.equalsIgnoreCase(ip)) {
+            int index = ip.indexOf(',');
+            if (index != -1) {
+                //只获取第一个值
+                return ip.substring(0, index);
+            } else {
+                return ip;
+            }
+        } else {
+            //取不到真实ip则返回空，不能返回内网地址。
+            return "";
+        }
+    }
+}

package/template/.cursor/skills/yss-audit-log/assets/YssAuditLogPrintSubscriberImpl.java

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.yss.cloud.audit.subscriber.impl;
+
+import com.yss.cloud.audit.subscriber.YssAuditSubscriber;
+import com.yss.cloud.dto.audit.message.AuditMessage;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * 日志打印操作日志订阅器
+ *
+ * @author zhudaoming
+ * @since 1.0.0
+ */
+@Slf4j
+public class YssAuditLogPrintSubscriberImpl implements YssAuditSubscriber {
+
+    @Override
+    public void execute(AuditMessage message) {
+        log.info("[AUDIT_MESSAGE] 审计日志 => {}",message.toString());
+    }
+}

package/template/.cursor/skills/yss-audit-log/assets/YssAuditLogSysManagerSubscriberImpl.java

@@ -0,0 +1,18 @@
+package com.yss.cloud.audit.subscriber.impl;
+
+import com.yss.cloud.audit.subscriber.YssAuditSubscriber;
+import com.yss.cloud.dto.audit.message.AuditMessage;
+import com.yss.datamiddle.feign.YssDmSystemManageFeign;
+import org.springframework.beans.factory.annotation.Autowired;
+
+/**
+ * @author zhudaoming
+ */
+public class YssAuditLogSysManagerSubscriberImpl implements YssAuditSubscriber {
+    @Autowired
+    private YssDmSystemManageFeign yssDmSystemManageFeign;
+    @Override
+    public void execute(AuditMessage message) {
+        yssDmSystemManageFeign.saveAuditLog(message);
+    }
+}

package/template/.cursor/skills/yss-audit-log/assets/YssAuditPublishService.java

@@ -0,0 +1,69 @@
+package com.yss.cloud.audit.subscriber;
+
+import com.yss.cloud.audit.configuration.AuditConfigurationProperties;
+import com.yss.cloud.dto.audit.message.AuditMessage;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import javax.annotation.PostConstruct;
+import java.util.List;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+@Slf4j
+public class YssAuditPublishService {
+
+    private final BlockingQueue<AuditMessage> auditMessageQueue = new ArrayBlockingQueue<>(1000);
+    private final ExecutorService executorService = Executors.newFixedThreadPool(10);
+    @Autowired
+    private List<YssAuditSubscriber> subscribers;
+    @Autowired
+    private AuditConfigurationProperties auditConfigurationProperties;
+
+    /**
+     * Initialize the service and start the message processing.
+     */
+    @PostConstruct
+    private void init() {
+        for (int i = 0; i < 10; i++) {
+            executorService.submit(this::doPublish);
+        }
+    }
+
+    /**
+     * Publish a new audit message.
+     *
+     * @param message audit message
+     */
+    public void publish(AuditMessage message) {
+        if (auditConfigurationProperties.getEnabled()) {
+            if (!auditMessageQueue.offer(message)) {
+                log.error("Publish audit message failed, message:{}", message);
+            }
+        }
+    }
+
+    /**
+     * Execute the message processor for each subscriber.
+     */
+    private void doPublish() {
+        while (true) {
+            try {
+                AuditMessage message = auditMessageQueue.take();
+                for (YssAuditSubscriber subscriber : subscribers) {
+                    try {
+                        subscriber.execute(message);
+                    } catch (Exception e) {
+                        log.error("Consume audit message failed, message:{}", message, e);
+                    }
+                }
+            } catch (InterruptedException e) {
+                log.error("Consume audit message failed", e);
+                Thread.currentThread().interrupt();
+                break;
+            }
+        }
+    }
+}

package/template/.cursor/skills/yss-audit-log/references/README.md

@@ -0,0 +1,69 @@
+# 参考资料
+
+本文档详细介绍了 `yss-component-audit-log` 组件的核心类和配置类。
+
+## 核心类 (Core Classes)
+
+### 1. AuditLogAspect.java
+
+**位置**: `../assets/AuditLogAspect.java`
+
+审计日志切面，是日志收集的核心入口。
+
+**拦截逻辑**:
+
+- **切点**: 拦截带有 `@AuditLog` 注解且为 public 的方法。
+- **处理流程**:
+  1. **解析注解**: 获取 `@AuditLog` 中的操作类型、描述、资源类型等信息。
+  2. **SpEL 解析**: 如果 `summary` 中包含 `#{...}` 表达式，会解析方法参数和返回值，动态生成日志内容。
+  3. **构建消息**:
+     - 收集用户信息（从 JWT 解析）。
+     - 收集请求信息（URL, IP, User-Agent）。
+     - 收集参数和结果（根据 `isNeedArgs` 和 `isNeedResult` 配置）。
+  4. **发布消息**: 调用 `YssAuditPublishService.publish` 将构建好的 `AuditMessage` 发布出去。
+
+### 2. YssAuditPublishService.java
+
+**位置**: `../assets/YssAuditPublishService.java`
+
+异步日志发布服务。
+
+**机制**:
+
+- 维护一个内部阻塞队列 `ArrayBlockingQueue` (容量1000)。
+- 启动固定线程池（10个线程）作为消费者，不断从队列中获取消息。
+- 将消息分发给所有注册的 `YssAuditSubscriber` 实现类。
+
+### 3. Subscriber 实现
+
+#### YssAuditLogPrintSubscriberImpl.java
+
+**位置**: `../assets/YssAuditLogPrintSubscriberImpl.java`
+
+- **功能**: 简单的控制台日志打印，用于开发调试。
+- **开关**: 通过 `yss.audit.auditLogPrintEnabled` 控制。
+
+#### YssAuditLogSysManagerSubscriberImpl.java
+
+**位置**: `../assets/YssAuditLogSysManagerSubscriberImpl.java`
+
+- **功能**: 调用 `YssDmSystemManageFeign` 将审计日志发送到系统管理服务进行持久化存储。
+- **开关**: 通过 `yss.audit.sendSysManageEnabled` 控制。
+
+## 关键注解
+
+### @AuditLog
+
+用于标记需要审计的方法。
+
+```java
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface AuditLog {
+    String summary() default ""; // 操作描述，支持 SpEL
+    AuditOperationType operation(); // 操作类型 (ADD, UPDATE, DELETE, QUERY, etc.)
+    AuditResourceType resource() default AuditResourceType.DM; // 资源类型
+    boolean isNeedResult() default false; // 是否记录返回值
+    boolean isNeedArgs() default true; // 是否记录参数
+}
+```

package/template/.cursor/skills/yss-audit-log/references/source-index.md

@@ -0,0 +1,43 @@
+# yss-audit-log Source Index
+
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
+Source worktree: `dirty`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+
+Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-audit-log` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-audit-log`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/AuditLog.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/EnableAuditLog.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditConfiguration.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditConfigurationProperties.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditLogAspect.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/EnableAuditLogImportSelector.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/UUIDGenerator.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/feign/YssDmSystemManageFeign.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/YssAuditPublishService.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/YssAuditSubscriber.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/impl/YssAuditLogPrintSubscriberImpl.java`
+- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/impl/YssAuditLogSysManagerSubscriberImpl.java`
+
+## Recommended Next Reads
+
+- Start with the documentation files above when learning component usage.
+- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
+- Prefer existing component extension points over rewriting framework logic in business modules.

package/template/.cursor/skills/yss-cache/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: yss-cache
+description: 用于 YSS 缓存框架的接入、配置、代码修改和故障诊断。Use when tasks involve QueryCache、UpdateCache、ClearCache、TTL、SpEL key、事务提交后缓存操作、Redis/Caffeine/Hazelcast 后端切换、Redis Standalone/Sentinel/Cluster、Jedis 连接池、Redis fallback、JetCache、多级缓存、序列化兼容、缓存不命中或失效不一致。
+---
+
+# yss-cache
+
+处理 `yss-component-cache-parent` 及其消费项目的缓存任务。
+
+## 工作流
+
+1. 按 `yss-source-index/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
+2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
+3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
+4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
+5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
+
+## 不变量
+
+- 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
+- key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
+- 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
+- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
+- 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
+- 不明确一致性要求时，不默认启用本地缓存或 fallback。
+
+## 按场景读取
+
+- 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.md)
+- 新增或修改缓存注解、SpEL、空 key、全量清理：[annotations.md](references/annotations.md)
+- 依赖、启动注解、TTL、Caffeine/Hazelcast、Bean backoff：[configuration.md](references/configuration.md)
+- Redis 单机、哨兵、集群、认证、SSL、超时、Jedis pool：[redis-topology.md](references/redis-topology.md)
+- Redis 故障、fallback、恢复清理和一致性：[redis-fallback.md](references/redis-fallback.md)
+- RedisTemplate/RedisCacheManager 数据格式或迁移：[serialization.md](references/serialization.md)
+- 缓存不生效、未失效、启动失败、Redis 异常：[troubleshooting.md](references/troubleshooting.md)
+- 完成修改后的组件与消费项目验收：[verification.md](references/verification.md)
+
+## 工具
+
+- `scripts/inspect-cache-usage.sh <project-root>`：只读扫描消费项目；发现阻断缺陷返回 1，输入或环境错误返回 2。
+- `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
+- `scripts/check-skill-freshness.sh [source-root]`：比较技能契约与当前组件源码；发现漂移返回 1。
+
+当组件源码变化后，用 `yss-source-index` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。

package/template/.cursor/skills/yss-cache/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Cache"
+  short_description: "YSS 缓存注解、Redis 拓扑、降级与序列化诊断"
+  default_prompt: "Use $yss-cache to configure or diagnose YSS cache annotations, Redis topology, fallback, TTL, and serialization behavior."

package/template/.cursor/skills/yss-cache/references/annotations.md

@@ -0,0 +1,39 @@
+# 注解契约
+
+## 映射
+
+- `@QueryCache` -> Spring `CacheableOperation`。
+- `@UpdateCache` -> Spring `CachePutOperation`。
+- `@ClearCache` -> Spring `CacheEvictOperation`。
+- `value` 与 `cacheNames` 是别名；非空 `cacheName` 会覆盖枚举 cache names。
+- 默认 resolver 是 `cacheComposeResolver`。
+- `key` 与 `keyGenerator` 互斥。
+
+## 参数语义
+
+- `condition`：调用前判断，false 时跳过缓存操作。
+- `unless`：结果产生后判断；Query/Update 支持。ClearCache 虽保留该字段，但当前解析器不映射它。
+- `sync`：QueryCache 映射到同步加载；UpdateCache 和 ClearCache 当前不映射该字段。
+- `allEntries=true`：明确清空整个 cache。
+- `beforeInvocation=true`：业务方法执行前清理；后续业务失败不会恢复旧缓存。
+
+## Key 与清理
+
+```java
+@QueryCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
+public PlanDTO get(String tenantId, Long planId) { ... }
+
+@ClearCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
+public void delete(String tenantId, Long planId) { ... }
+```
+
+- 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
+- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
+- 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
+- 集合参数先稳定排序；null、大小写和空白必须归一化。
+
+## AOP 与事务
+
+- 缓存方法必须通过 Spring 代理调用；同类 `this.method()` 自调用会绕过拦截。
+- private 方法不能作为代理入口；final 方法/类受代理方式限制。
+- `put`、`evict`、`clear` 在事务同步激活时延迟到 `afterCommit`；回滚不执行缓存变更。

package/template/.cursor/skills/yss-cache/references/architecture.md

@@ -0,0 +1,25 @@
+# 架构与选择
+
+## 三种模型
+
+| 模型 | 行为 | 一致性边界 |
+|---|---|---|
+| Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
+| Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
+| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
+
+## 模块
+
+- `yss-component-spring-cache`：注解、解析器、拦截器、路由和公共属性。
+- `yss-component-redis-cache`：Jedis 连接、RedisTemplate、RedisCacheManager、健康检查和 fallback。
+- `yss-component-caffeine-cache`：节点本地缓存。
+- `yss-component-hazelcast-cache`：显式依赖的集群内存后端。
+- `yss-component-cache-starter`：默认聚合 Spring Cache、Redis 和 Caffeine。
+- `yss-component-jetcache`：与 Spring Cache 路由模型分开分析。
+
+## 选择规则
+
+- 跨节点共享且不接受节点本地旧值：使用纯 Redis。
+- 读多写少并允许短暂节点差异：可选择 Caffeine。
+- Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
+- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。

package/template/.cursor/skills/yss-cache/references/configuration.md

@@ -0,0 +1,34 @@
+# 接入与配置
+
+## 推荐接入
+
+```xml
+<dependency>
+  <groupId>com.yss.cloud</groupId>
+  <artifactId>yss-component-cache-starter</artifactId>
+</dependency>
+```
+
+启动类使用 `@EnableYssCloudCache`。`@EnableYssCloudRedisCache` 仅为兼容保留并已废弃。
+
+## 公共属性
+
+```yaml
+yss:
+  cache:
+    active-type: redis       # redis | caffeine | hazelcast
+    default-ttl: 1h
+    redis:
+      fallback-enabled: false
+      fallback-type: caffeine
+      clear-fallback-on-recovery: true
+```
+
+- Redis 动态 cache 和 Caffeine 默认 TTL 使用 `yss.cache.default-ttl`。
+- `CacheKeyCode` 中声明的 TTL 覆盖默认 TTL。
+- Caffeine 的 `spring.cache.caffeine.spec` 可覆盖默认构建规格，修改前检查项目现有配置。
+- Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
+
+## 自定义 Bean
+
+默认配置会对用户提供的 `RedisProperties`、`RedisConnectionFactory`、`JedisClientConfiguration`、pool config、RedisCacheManager、resolver、provider、serializer、RedisTemplate 和 RedisMappingContext 回退。排障时按类型和名称检查实际 Bean，不能假设框架默认 Bean 一定生效。