feat: first commit

2026-07-13 15:34:28 +08:00
commit 603a047203
48 changed files with 4646 additions and 0 deletions
--- a/docs/CI集成说明.md
+++ b/docs/CI集成说明.md
@@ -0,0 +1,204 @@
+# Redis 序列化结构检测 — CI 集成说明
+
+---
+
+## 1. 集成概览
+
+```text
+开发者 push 代码
+    ↓
+Gitea Actions 触发
+    ↓
+浅克隆业务仓库（depth=2）
+    ↓
+从 Nexus 下载 redis-schema-checker.jar
+    ↓
+java -jar 执行（对比 HEAD~1 与 HEAD）
+    ↓
+有 P0/P1 变更 → 企微通知
+    ↓
+mode=block 且含 P0/P1/P2 任一变更 → exit 1（流水线失败）
+```
+
+---
+
+## 2. 前置条件
+
+| 项 | 说明 |
+|----|------|
+| Gitea Runner | 标签 `jdk11`，已安装 Java 11 |
+| Nexus 私库 | 可访问 `http://192.168.3.25:18081/nexus/repository/maven-releases` |
+| 工具 JAR | `com.codechecker:redis-schema-checker:1.0.0` 已发布 |
+| 仓库 Secret | `WECOM_ROBOT_WEBHOOK` 已配置 |
+
+---
+
+## 3. 业务仓库文件清单
+
+在 `jnpf-java-cloud` 中新增：
+
+```text
+jnpf-java-cloud/
+├── .gitea/
+│   ├── workflows/
+│   │   └── redis-schema-check.yaml      # 流水线
+│   └── config/
+│       └── redis-schema-check-config.yaml  # 检测配置
+```
+
+---
+
+## 4. 流水线模板
+
+```yaml
+name: Redis序列化结构检查
+run-name: ${{ gitea.actor }}的Redis结构检查
+
+on:
+  push:
+  workflow_dispatch:
+
+env:
+  REDIS_SCHEMA_CHECKER_VERSION: "1.0.0"
+  REDIS_SCHEMA_CHECKER_REPO_URL: "http://192.168.3.25:18081/nexus/repository/maven-releases"
+
+jobs:
+  redis-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/redis-schema-check-config.yaml ]; then
+            echo "错误: 缺少 .gitea/config/redis-schema-check-config.yaml"
+            exit 1
+          fi
+
+      - name: 从 Nexus 下载检测工具
+        run: |
+          GROUP_PATH="com/codechecker/redis-schema-checker"
+          JAR_NAME="redis-schema-checker-${REDIS_SCHEMA_CHECKER_VERSION}.jar"
+          JAR_URL="${REDIS_SCHEMA_CHECKER_REPO_URL}/${GROUP_PATH}/${REDIS_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: 执行 Redis 结构检测
+        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/redis-schema-checker-${REDIS_SCHEMA_CHECKER_VERSION}.jar" \
+            --config .gitea/config/redis-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) | 通用变更检测 | **同模式**，可并列执行 |
+| `redis-schema-check` | Redis 结构检测 | 新增 |
+
+建议：三个 job 独立并行，各自 exit code 独立。
+
+---
+
+## 6. 工具发布流程（redisCheck 仓库）
+
+```bash
+# 在 redisCheck 仓库
+mvn clean package -DskipTests
+
+# 发布到 Nexus（需配置 settings.xml）
+mvn deploy -DskipTests
+```
+
+发布产物：
+
+```text
+com/codechecker/redis-schema-checker/1.0.0/
+  ├── redis-schema-checker-1.0.0.jar          # 可执行 fat-jar
+  └── redis-schema-checker-1.0.0.pom
+```
+
+---
+
+## 7. 退出码约定
+
+| 退出码 | 含义 | 流水线表现 |
+|--------|------|------------|
+| 0 | 通过（含 notify 模式下的告警） | 绿色 |
+| 1 | 阻断（block 模式 + P0/P1/P2 任一变更） | 红色 |
+| 2 | 执行错误（配置缺失、jar 异常等） | 红色 |
+
+---
+
+## 8. 故障排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 首次提交跳过 | 无 HEAD~1 | 正常行为 |
+| 下载 jar 失败 | Nexus 地址/版本错误 | 检查 env 变量 |
+| 未收到企微 | Secret 未配 / notify.enabled=false | 检查配置 |
+| 大量误报 | 锁/计数器未过滤 | 补充 ignore.key_patterns |
+| 漏报 | 写入模式未覆盖 | 启用 W04/W05 或补充 manual_mappings |
+| 类型展开不完整 | 类型在依赖 jar 中 | 补充 manual_mappings.value_type |
+
+---
+
+## 9. 本地调试
+
+```bash
+# 在 jnpf-java-cloud 根目录
+java -jar /path/to/redis-schema-checker-1.0.0.jar \
+  --config .gitea/config/redis-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`（Phase 2 实现）仅输出报告不发企微。