# 缓存序列化结构检测 — CI 集成说明

---

## 1. 集成概览

```text
开发者 push 代码
    ↓
Gitea Actions 触发
    ↓
浅克隆业务仓库（depth=2）
    ↓
从 Nexus 下载 cache-schema-checker.jar
    ↓
java -jar 执行（对比 HEAD~1 与 HEAD）
    ↓
有结构变更 → 企微通知（按 Key 骨架；删除橙/新增绿）
    ↓
mode=block 且含任意结构变更 → exit 1（流水线失败）
```

---

## 2. 前置条件

| 项 | 说明 |
|----|------|
| Gitea Runner | 标签 `jdk11`，已安装 Java 11 |
| Nexus 私库 | 可访问 `http://192.168.3.25:18081/nexus/repository/maven-releases` |
| 工具 JAR | `com.codechecker:cache-schema-checker:1.0.0` 已发布 |

---

## 3. 业务仓库文件清单

在 `jnpf-java-cloud` 中新增：

```text
jnpf-java-cloud/
├── .gitea/
│   ├── workflows/
│   │   └── cache-schema-check.yaml      # 流水线
│   └── config/
│       └── cache-schema-check-config.yaml  # 检测配置
```

---

## 4. 流水线模板

```yaml
name: 缓存序列化结构检查
run-name: ${{ gitea.actor }}的缓存结构检查

on:
  push:
  workflow_dispatch:

env:
  CACHE_SCHEMA_CHECKER_VERSION: "1.0.0"
  CACHE_SCHEMA_CHECKER_REPO_URL: "http://192.168.3.25:18081/nexus/repository/maven-releases"

jobs:
  cache-schema-check:
    if: ${{ gitea.ref != 'refs/heads/pre' && gitea.ref != 'refs/heads/dev' && gitea.ref != 'refs/heads/master-2.0' }}
    runs-on: jdk11
    steps:
      - name: 检出代码
        run: |
          git config --global http.sslVerify false
          git clone --depth 2 --single-branch --branch "${{ gitea.ref_name }}" \
            "https://${{ gitea.token }}@git.niujiekeji.com/${{ gitea.repository }}.git" .
          git checkout -B "${{ gitea.ref_name }}" "${{ gitea.sha }}"

      - name: 检查配置文件
        run: |
          if [ ! -f .gitea/config/cache-schema-check-config.yaml ]; then
            echo "错误: 缺少 .gitea/config/cache-schema-check-config.yaml"
            exit 1
          fi

      - name: 从 Nexus 下载检测工具
        run: |
          GROUP_PATH="com/codechecker/cache-schema-checker"
          JAR_NAME="cache-schema-checker-${CACHE_SCHEMA_CHECKER_VERSION}.jar"
          JAR_URL="${CACHE_SCHEMA_CHECKER_REPO_URL}/${GROUP_PATH}/${CACHE_SCHEMA_CHECKER_VERSION}/${JAR_NAME}"
          JAR_PATH="/tmp/${JAR_NAME}"

          echo "下载: ${JAR_URL}"
          if command -v curl >/dev/null 2>&1; then
            curl -fsSL -o "${JAR_PATH}" "${JAR_URL}"
          elif command -v wget >/dev/null 2>&1; then
            wget -q -O "${JAR_PATH}" "${JAR_URL}"
          else
            echo "错误: Runner 缺少 curl 或 wget"
            exit 1
          fi

          if [ ! -s "${JAR_PATH}" ]; then
            echo "错误: 下载失败或文件为空"
            exit 1
          fi

          ls -lh "${JAR_PATH}"

      - name: 验证 JDK
        run: java -version

      - name: 执行 缓存结构检测
        env:
          WECOM_ROBOT_WEBHOOK: ${{ secrets.WECOM_ROBOT_WEBHOOK }}
        run: |
          OLD_SHA=$(git rev-parse HEAD~1 2>/dev/null || echo "")
          if [ -z "$OLD_SHA" ]; then
            echo "首次提交，跳过检测"
            exit 0
          fi

          COMMIT_TIME=$(git log -1 --format=%cd --date=format:'%Y-%m-%d %H:%M:%S')

          java -jar "/tmp/cache-schema-checker-${CACHE_SCHEMA_CHECKER_VERSION}.jar" \
            --config .gitea/config/cache-schema-check-config.yaml \
            --repo-root . \
            --old-sha "$OLD_SHA" \
            --new-sha "$(git rev-parse HEAD)" \
            --branch "${{ gitea.ref_name }}" \
            --modifier "${{ gitea.actor }}" \
            --modify-time "$COMMIT_TIME"
```

---

## 5. 与现有流水线的关系

| 流水线 | 作用 | 关系 |
|--------|------|------|
| `demo.yaml` (AI代码质量分析) | AI Code Review | 并行，互不影响 |
| `code-check` (CodeChecker) | 通用变更检测 | **同模式**，可并列执行 |
| `cache-schema-check` | 缓存结构检测 | 新增 |


---

## 6. 工具发布流程（redisCheck 仓库）

```bash
# 在 redisCheck 仓库根目录
mvn clean package -DskipTests

# 发布到 Nexus（需配置 settings.xml，并开启 deploy-nexus profile）
mvn clean deploy -Dnexus.deploy.enabled=true -DskipTests
```

发布产物：

```text
com/codechecker/cache-schema-checker/1.0.0/
  ├── cache-schema-checker-1.0.0.jar          # 可执行 fat-jar
  └── cache-schema-checker-1.0.0.pom
```

---

## 7. 退出码约定

| 退出码 | 含义 | 流水线表现 |
|--------|------|------------|
| 0 | 通过（含 notify 模式下的告警） | 绿色 |
| 1 | 阻断（block 模式） | 红色 |
| 2 | 执行错误（配置缺失、jar 异常等） | 红色 |

---

## 8. 故障排查

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| 首次提交跳过 | 无 HEAD~1 | 正常行为 |
| 下载 jar 失败 | Nexus 地址/版本错误 | 检查 env 变量 |
| 未收到企微 | Secret 未配 / notify.enabled=false | 检查配置 |
| 大量误报 | 锁/计数器未过滤 | 补充 ignore.key_patterns |
| 漏报 | 写入模式未覆盖 / 模块过滤过窄 | 确认 W01~W05 已启用；检查 `include_modules` |
| 类型展开不完整 | 类型在依赖 jar 中 | 补充 `manual_mappings.value_type` |

---

## 9. 本地调试

```bash
# 在 jnpf-java-cloud 根目录
java -jar /path/to/cache-schema-checker-1.0.0.jar \
  --config .gitea/config/cache-schema-check-config.yaml \
  --repo-root . \
  --old-sha HEAD~1 \
  --new-sha HEAD \
  --branch $(git branch --show-current) \
  --modifier "$(git log -1 --format=%an)" \
  --modify-time "$(git log -1 --format=%cd --date=format:'%Y-%m-%d %H:%M:%S')"
```

可加 `--dry-run` 仅输出报告不发企微。