schemaCheck/docs/配置说明.md

缓存序列化结构检测 — 配置说明

双层配置：工具 jar 内置 default-config.yaml（默认） + 业务仓库 .gitea/config/cache-schema-check-config.yaml（覆盖）

---

1. 配置合并机制

jar 内 default-config.yaml（工具仓维护）
        ↓ 深度合并
业务仓 cache-schema-check-config.yaml（业务仓维护）
        ↓
最终生效配置

• 业务配置仅需写差异项，不必复制全部默认规则
• 升级 jar 时，默认忽略规则/检测模式自动跟随工具版本演进
• 业务仓必须存在 --config 指定的配置文件（可为仅含 mode 的最小文件）

1.1 业务仓最小配置示例

# jnpf-java-cloud/.gitea/config/cache-schema-check-config.yaml
mode: notify

notify:
  enabled: true
  webhook_env: WECOM_ROBOT_WEBHOOK

include_modules:
  - jnpf-tenant

1.2 工具内置默认配置（jar 内 default-config.yaml）

由 redisCheck 仓库维护，随 jar 发布，包含：

• detection.patterns（W01~W03）
• ignore.key_patterns（锁/计数器/token）
• detection.min_confidence、max_field_depth 等

---

2. 业务仓完整配置示例

# 总开关：false 时不执行检测、不发通知、流水线直接通过
enabled: true

# 运行模式
# notify - 仅通知，不阻断流水线
# block  - 检测到结构变更即阻断流水线（exit 1）
mode: notify

# 是否扫描测试代码（已确认：不扫描）
scan_test_sources: false

# 源码扫描根目录（仅 main，不含 test）
source_roots:
  - "src/main/java"

# 通知配置
notify:
  enabled: true
  # 从环境变量读取 Webhook URL
  webhook_env: WECOM_ROBOT_WEBHOOK
  # 无变更时是否也发通知（一般 false）
  notify_on_clean: false
  # 消息标题前缀
  title_prefix: "[缓存结构变更]"

# 忽略规则
ignore:
  # 忽略的 key 模式（glob）
  key_patterns:
    - "*:lock"
    - "*:lock:*"
    - "loginCount:*"
    - "Authorization:*"
    - "Authorization:login:session:*"

  # 忽略的文件路径模式
  file_patterns:
    - "**/test/**"

  # 忽略的写入方法（类全名#方法名）
  writer_methods: []

# 检测规则
detection:
  # 启用的写入模式
  patterns:
    - W01   # redisUtil.insert + JSON.toJSONString
    - W02   # redisTemplate.opsForValue().set + JSON.toJSONString
    - W03   # stringRedisTemplate + JsonUtil.getObjectToString
    # - W04  # redisTemplate 直写对象（Phase 2）
    # - W05  # opsForHash().put（Phase 2）

  # 类型推断最低置信度，低于此值仅输出 P2 提示
  min_confidence: 0.6

  # 字段展开最大深度（防止循环引用死循环）
  max_field_depth: 8

# 严重级别覆盖（可选）
severity_overrides:
  FIELD_ADDED: P1
  WRITE_POINT_ADDED: P2

# 人工补充映射（自动推断失败或需精确指定时使用）
manual_mappings:
  - id: tenant-db-content
    writer_method: "jnpf.util.TenantDbContentCacheHelper#cacheSuccess"
    key_pattern: "tenant:db:content:*"
    value_type: "jnpf.util.TenantDbContentCacheHelper.CacheEnvelope"
    description: "租户库信息缓存"

  - id: attendance-base-setting
    writer_method: "jnpf.attendance.service.impl.AttendanceBaseSettingServiceImpl#getStringAttendanceBaseSettingMap"
    key_pattern: "fbt:attendance:base_setting:cache:*"
    value_type: "java.util.Map"
    description: "考勤基础设置缓存（Map<String, AttendanceBaseSetting>）"

# 抑制规则（已知误报）
suppressions:
  - id: ignore-export-progress
    key_pattern: "file:download:user:progress:*"
    reason: "导出进度缓存，结构变更不影响业务读取"

# 模块过滤（可选，默认扫描全部模块）
include_modules:
  - jnpf-tenant
  - jnpf-ftb
  - jnpf-file
  - fantaibao-data-analysis

# exclude_modules: []

---

3. 配置项说明

3.1 enabled

总开关。默认 true。

值	行为
true	正常执行检测（再按 mode / notify 行为）
false	跳过检测与通知，流水线 exit 0（与 notify.enabled 无关）

临时关闭时可仅改此项，无需删除 workflow。

3.2 mode

值	行为
notify	检测到变更 → 发企微 → exit 0
block	检测到任意结构变更 → 发企微 → exit 1

建议上线初期仍使用 mode: notify 观察误报情况，确认稳定后再切换：

mode: block

3.3 notify

字段	类型	默认值	说明
enabled	boolean	true	是否发企微
webhook_env	string	WECOM_ROBOT_WEBHOOK	环境变量名
notify_on_clean	boolean	false	无变更时是否通知
title_prefix	string	[缓存结构变更]	消息标题前缀

3.4 ignore.key_patterns

支持 glob：

• * 匹配单层
• ** 匹配多层

常见内置忽略（代码层也有硬编码兜底）：

• 分布式锁 key
• 登录计数
• session/token

3.5 detection.patterns

模式	说明	阶段
W01	redisUtil.insert(key, JSON.toJSONString(x), ttl)	Phase 1
W02	redisTemplate.opsForValue().set(key, JSON.toJSONString(x), ...)	Phase 1
W03	stringRedisTemplate.opsForValue().set(key, JsonUtil.getObjectToString(x), ...)	Phase 1
W04	redisTemplate.opsForValue().set(key, obj, ...)	Phase 2
W05	redisTemplate.opsForHash().put(key, field, obj)	Phase 2

3.6 manual_mappings

当自动推断不准确时使用。匹配优先级 高于 自动推断。

字段	必填	说明
id	是	唯一标识
writer_method	否	类全名#方法名，精确匹配写入点
key_pattern	否	精确 key 模式
value_type	否	强制指定 value 类型
description	否	备注

3.7 suppressions

用于屏蔽已知可接受的变更：

suppressions:
  - id: my-suppression
    writer_method: "com.example.FooService#cacheBar"
    change_types:
      - FIELD_ADDED
    reason: "新增字段向后兼容"

---

4. 环境变量

变量	必填	说明
WECOM_ROBOT_WEBHOOK	notify.enabled=true 时必填	企微机器人 Webhook 完整 URL

在 Gitea 仓库 Settings → Secrets 中配置。

---

5. 企微消息格式示例

## [缓存结构变更] jnpf-java-cloud

> 分支: feature/tenant-cache
> 提交: a1b2c3d → e4f5g6h
> 提交人: zhangsan
> 时间: 2026-07-13 14:00:00
> 模式: notify

### P0 - 顶层结构包装变更
- **Key**: `tenant:db:content:*`
- **位置**: `TenantDbContentCacheHelper#cacheSuccess:92`
- **变更**:
  - `dbName` → `vo.dbName`（字段路径迁移）
  - `linkList` → `vo.linkList`（字段路径迁移）
  - 新增顶层字段 `expiresAtMs`
- **影响**: 旧缓存反序列化可能失败，需评估缓存刷新策略

---

6. 推荐上线配置

6.1 观察期（第 1 周，已确认策略）

业务仓默认配置：

mode: notify

notify:
  enabled: true
  webhook_env: WECOM_ROBOT_WEBHOOK

include_modules:
  - jnpf-tenant

观察满 1 周、确认误报可接受后，手动切换：

mode: block
include_modules: []  # 扩至全仓

6.2 全量启用（观察期结束后）

mode: block
include_modules: []  # 空表示全部模块
detection:
  patterns: [W01, W02, W03, W04, W05]