lumina: Skill for Claude Code

Lumina 可观测性规范

功能概述

本技能包用于规范 Lumina 框架的日志、审计和指标埋点，包括 MDC 链路追踪注入、@Audit 声明式审计日志、Micrometer 指标采集（Prometheus），确保系统运行状态可观测、可追溯。

日志规范（MDC）

traceId 自动注入

LogContextInterceptor 拦截器在每个 HTTP 请求进入时自动注入 MDC 上下文：

MDC Key	来源	说明
traceId	自动生成（UUID 短格式）	链路追踪 ID，贯穿整个请求
tenantId	请求头 / Token	当前租户 ID
userId	Token 解析	当前用户 ID

日志 Pattern 配置

<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level [%X{traceId:--}] %logger{36} - %msg%n</pattern>

• 使用 %X{traceId:--} 输出 traceId，无值时显示 --
• 所有日志自动携带 traceId，便于全链路问题排查
• 业务日志中无需手动输出 traceId

日志使用规范

private static final Logger log = LoggerFactory.getLogger(UserService.class);

log.info("用户创建成功, userId={}, username={}", userId, username);
log.warn("租户配额即将用尽, tenantId={}, used={}/{}", tenantId, used, quota);
log.error("Agent 执行失败, agentId={}", agentId, e);

• 使用 SLF4J + 占位符（{}），禁止字符串拼接
• 关键操作记录 INFO，异常记录 ERROR（带异常堆栈）

审计日志（@Audit）

声明式审计标注

@Audit(module = "用户管理", action = "CREATE", description = "创建用户")
@PostMapping("/users")
public Result<UserVO> create(@RequestBody @Valid CreateUserDTO dto) {
    // ...
}

• 在 Controller 方法上标注 @Audit，声明模块、操作类型和描述
• AuditAspect AOP 切面自动采集审计信息，无需手动编码

审计采集内容

字段	来源	说明
operator	BaseContext.userId	操作人 ID
module	@Audit.module	功能模块
action	@Audit.action	操作类型（CREATE/UPDATE/DELETE）
description	@Audit.description	操作描述
httpMethod	请求信息	HTTP 方法
requestUri	请求信息	请求路径
duration	AOP 计时	方法耗时（毫秒）
result	返回值/异常	成功/失败

审计存储

• 审计事件通过事件驱动写入 lumina_audit_log 表
• 支持异步写入，不影响主流程性能
• 审计查询 API：GET /api/v1/audit-logs（支持分页、模块筛选）

指标规范（Micrometer）

指标采集

@Autowired(required = false)
private MeterRegistry meterRegistry;

public void recordExecution(String type, long durationMs, boolean success) {
    if (meterRegistry == null) return;
    meterRegistry.timer("agent.execution.duration",
            "type", type,
            "result", success ? "success" : "failure")
        .record(Duration.ofMillis(durationMs));
}