From 361dbe5fbdb47391d7ddecc175d160ef59e4f053 Mon Sep 17 00:00:00 2001
From: Hermes <hermes@local>
Date: Fri, 12 Jun 2026 11:02:11 +0800
Subject: [PATCH] =?UTF-8?q?feat(ci):=20T10.2=20codecov=20=E9=9B=86?=
 =?UTF-8?q?=E6=88=90=20+=20=E8=A6=86=E7=9B=96=E7=8E=87=E5=BE=BD=E7=AB=A0?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

完成 v2.1 实施计划 T10.2: codecov 集成与覆盖率徽章。

变更：
- .github/workflows/ci.yml: 新增 'Upload coverage to Codecov' 步骤
  - codecov/codecov-action@v4 (锁 major)
  - 3.11 单点上传，flag=python-3.11（避免矩阵多份报告冲突）
  - fail_ci_if_error: false（codecov 不可达不阻断 CI）
  - 不设 token: public repo 匿名上传即可
- codecov.yml: 配置文件
  - project target 60% / threshold 1% (与 T5.5 整体门槛对齐)
  - core (skills/gaokao-spec-checker + gaokao-college-advisor) target 80% / threshold 2%
  - patch target 70% / threshold 5%
  - ignore docs/tests/rules/scripts/gaokao-shortlink (非生产代码)
  - require_ci_to_pass: false (CI 失败不阻塞 codecov 上传)

本地验证:
- pytest 136/136 通过 (T7 修复后 test_route_short_link 已恢复)
- 整体覆盖率 59.55% (line-rate=0.5955, 2126/1266 lines)
- coverage.xml 是合法 Cobertura XML (codecov-action 可消费)
- ci.yml/codecov.yml YAML schema 解析通过

未在本任务范围: T5.5 --cov-fail-under 硬门槛启用、scripts/* 0% 覆盖率补齐、
core 模块 (gaokao-spec-checker 72%, 距 80% 差 8%) 补齐。
---
 .github/workflows/ci.yml | 15 ++++++++++++
 codecov.yml              | 52 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 codecov.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 77ffa84..c3f4d9f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -78,6 +78,21 @@ jobs:
           path: coverage.xml
           retention-days: 7
 
+      # T10.2: 上传 coverage.xml 到 codecov 渲染覆盖率徽章
+      # 关键决策：
+      # - 仅在 3.11 单点上传：避免多份报告名冲突（codecov 按文件名合并）
+      # - fail_ci_if_error: false: codecov 不可达时不影响 CI 通过（与个人项目 + 多镜像
+      #   仓库场景匹配；tksea/gitea 不被 codecov 官方支持，无 token 时仍能上传但不写 status）
+      # - 不设 token: public repo 可匿名上传；徽章正常渲染
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11' && hashFiles('coverage.xml') != ''
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          flags: python-3.11
+          fail_ci_if_error: false
+          verbose: false
+
       - name: Test summary
         if: always()
         run: |
diff --git a/codecov.yml b/codecov.yml
new file mode 100644
index 0000000..17a6f66
--- /dev/null
+++ b/codecov.yml
@@ -0,0 +1,52 @@
+# codecov 配置 — T10.2
+# 与 docs/IMPLEMENTATION_PLAN_v2.md T5.5 覆盖率门槛对齐：
+#   整体 ≥ 60% / 核心 ≥ 80%
+# PR 阶段加 1% 自动缓冲避免噪声红灯；T5.5 启用 --cov-fail-under 后 CI 仍守硬门槛
+codecov:
+  require_ci_to_pass: false # CI 失败不阻塞 codecov 上传（公网/镜像场景）
+  notify:
+    after_n_builds: 1 # 单点（3.11）上传即可，无需等矩阵全完
+  coverage:
+    precision: 2 # 徽章显示 2 位小数
+    round: down
+    range: "60...80" # 徽章颜色区间：红→黄→绿
+    status:
+      project:
+        default:
+          target: 60% # 整体目标（与 T5.5 --cov-fail-under 对齐）
+          threshold: 1% # PR 浮动容忍 1%（防噪声）
+          if_ci_failed: error # CI 失败时降级为 error（不阻断 PR）
+        # 核心模块单独门槛 — 与 T5.5 "核心 ≥80%" 对齐
+        core:
+          target: 80%
+          threshold: 2%
+          paths:
+            - "skills/gaokao-spec-checker/.*"
+            - "skills/gaokao-college-advisor/.*"
+      patch: # PR 新增代码的覆盖要求
+        default:
+          target: 70%
+          threshold: 5%
+    # 不参与覆盖率统计的目录（纯配置/文档/测试自身）
+    ignore:
+      - "docs/**"
+      - "tests/**"
+      - "data/examples/**"
+      - "rules/**" # 规则数据，非代码
+      - "scripts/gaokao-shortlink" # 已废弃的链接脚本
+      - "**/__pycache__/**"
+      - "**/tests.py"
+      - "**/test_*.py"
+
+# PR 评论与徽章展示策略
+comment:
+  layout: "header, diff, flags, components, files, footer"
+  behavior: default # 新 PR 评论、push 更新
+  require_changes: false # coverage 下降时不要求必须改
+  require_base: false # 没有 base 时也显示
+  require_head: true
+  hide_project_coverage: false
+
+# GitHub Checks 状态（无 token 时仅显示为 pending，但徽章仍渲染）
+github_checks:
+  annotations: true