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

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

---

## 1. 配置合并机制

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

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

### 1.1 业务仓最小配置示例

```yaml
# 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. 业务仓完整配置示例

```yaml
# 总开关：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 直写对象
    - W05   # opsForHash().put

  # 类型推断最低置信度，低于此值仅输出 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` 观察误报情况，确认稳定后再切换：

```yaml
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

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

```yaml
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. 企微消息格式示例

```markdown
## [缓存结构变更] 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 周，已确认策略）

业务仓默认配置：

```yaml
mode: notify

notify:
  enabled: true
  webhook_env: WECOM_ROBOT_WEBHOOK

include_modules:
  - jnpf-tenant
```

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

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

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

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