create-yss-spec 1.0.0

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/skills/yss-audit-log/references/source-index.md

@@ -0,0 +1,40 @@
+# yss-audit-log Source Index
+
+Generated: 2026-06-29T16:11:14+00:00
+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.py`. 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/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/.codex/skills/yss-cache/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: yss-cache
+description: 用于 YSS 缓存框架的接入、配置和排障。当用户提到 QueryCache、UpdateCache、ClearCache、多级缓存、Redis/Caffeine 切换、JetCache 或缓存不生效时调用。
+---
+
+# yss-cache
+
+用于处理 `yss-component-cache-parent` 相关的缓存接入、配置修复和使用规范问题。
+
+## 何时使用
+
+- 用户要新增或修改缓存注解。
+- 用户提到 `@QueryCache`、`@UpdateCache`、`@ClearCache`。
+- 用户在排查 Redis、Caffeine、JetCache、多级缓存切换问题。
+- 用户反馈缓存命中异常、缓存未失效、Redis 不可用时降级异常。
+
+## 工作方式
+
+1. 先识别项目当前用的是 Spring Cache 扩展、Redis/Caffeine/Hazelcast 后端还是 JetCache 扩展。
+2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
+3. 先查现有配置与注解用法，再决定是否改代码、改配置或两者都改。
+4. 只围绕当前问题解释缓存策略、key、失效与降级，不输出整套框架宣传材料。
+
+## 源码索引
+
+- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 当前技能索引：`references/source-index.md`
+- 重点源码入口通常包括 `EnableYssCloudCache`、`EnableYssCloudRedisCache`、`YssCacheInterceptor`、`YssCacheProperties`、`YssCacheAnnotationParser`、`QueryCache`、`UpdateCache`、`ClearCache`、各缓存后端 Provider/Resolver。
+
+当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+
+## 检查清单
+
+- 启动类是否开启了缓存能力。
+- 当前启用的是 `redis` 还是 `caffeine`。
+- 缓存 key 是否稳定且能表达业务唯一性。
+- 更新和删除路径是否同时处理了缓存刷新或失效。
+- 读方法是否被 Spring 代理调用，而不是类内自调用绕过 AOP。
+- Redis 异常时是否有预期中的降级路径。
+- 多级缓存场景下，本地缓存和远端缓存的一致性边界是否被业务接受。
+- key 中涉及用户、租户、机构、账套等上下文时，是否显式纳入 key 设计。
+
+## 实施建议
+
+- 查询接口优先用 `@QueryCache`。
+- 更新接口优先用 `@UpdateCache` 或显式失效。
+- 删除或状态变更接口优先用 `@ClearCache`。
+- 对跨节点一致性要求高的场景，优先确认是否需要 JetCache 或 Redis 广播。
+- 读多写少、允许短暂不一致的场景才考虑本地缓存。
+- 多服务共享缓存时，优先复用项目既有缓存 key 常量、枚举或命名约定。
+
+## 排障顺序
+
+1. 依赖和启动注解是否引入正确。
+2. 配置项是否启用了预期缓存后端。
+3. 目标方法是否能被 Spring AOP 代理。
+4. 注解 key 表达式是否能解析到方法参数。
+5. 更新/删除链路是否命中失效逻辑。
+6. Redis/Caffeine/JetCache 后端是否实际创建了缓存管理器。
+7. 降级行为是否与配置和业务预期一致。
+
+## 修改约束
+
+- 不要只加查询缓存而不处理更新失效。
+- 不要把缓存 key 绑定到不稳定对象序列化结果。
+- 不要在不明确一致性要求时默认启用本地缓存。
+- 如果项目已经有统一缓存 key 常量或枚举，沿用现有约定。
+
+## 按需读取
+
+- 源码索引：`references/source-index.md`
+- 注解定义：`assets/QueryCache.java`、`assets/UpdateCache.java`、`assets/ClearCache.java`
+- 复杂实现细节：`references/README.md`

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

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Cache"
+  short_description: "QueryCache、缓存更新、失效刷新与排障规范"
+  default_prompt: "Use $yss-cache to configure or debug QueryCache, UpdateCache, ClearCache, and Redis or Caffeine caching behavior."

package/template/.codex/skills/yss-cache/assets/ClearCache.java

@@ -0,0 +1,34 @@
+package com.yss.cloud.cache.annotation;
+
+import com.yss.cloud.cache.CacheKeyCode;
+import org.springframework.core.annotation.AliasFor;
+
+import java.lang.annotation.*;
+
+/**
+ * @author zhudaoming
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+@Documented
+public @interface ClearCache {
+
+  @AliasFor("cacheNames")
+  CacheKeyCode[] value() default {CacheKeyCode.DATA_MIDDLE_CACHE_DEFAULT};
+
+  @AliasFor("value")
+  CacheKeyCode[] cacheNames() default {CacheKeyCode.DATA_MIDDLE_CACHE_DEFAULT};
+  String cacheName() default "";
+  String key() default "";
+
+  String keyGenerator() default "";
+
+  String cacheResolver() default "cacheComposeResolver";
+
+  String condition() default "";
+
+  String unless() default "";
+
+  boolean sync() default false;
+}

package/template/.codex/skills/yss-cache/assets/QueryCache.java

@@ -0,0 +1,36 @@
+package com.yss.cloud.cache.annotation;
+
+import com.yss.cloud.cache.CacheKeyCode;
+import org.springframework.core.annotation.AliasFor;
+
+import java.lang.annotation.*;
+
+/**
+ * @author zhudaoming
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+@Documented
+public @interface QueryCache {
+
+  @AliasFor("cacheNames")
+  CacheKeyCode[] value() default {CacheKeyCode.DATA_MIDDLE_CACHE_DEFAULT};
+
+  @AliasFor("value")
+  CacheKeyCode[] cacheNames() default {CacheKeyCode.DATA_MIDDLE_CACHE_DEFAULT};
+
+  String cacheName() default "";
+
+  String key() default "";
+
+  String keyGenerator() default "";
+
+  String cacheResolver() default "cacheComposeResolver";
+
+  String condition() default "";
+
+  String unless() default "";
+
+  boolean sync() default false;
+}