EvoCode 技术债监控机制与代码质量指标体系
定位：把《10-技术债管理方案》的量化评估落地为可采集、可对比、可门禁的指标体系与监控机制。
配套：《08-测试计划》§1 定义采集命令；《03-开发规范》定义 DoD；本文档定义"度量什么、阈值多少、何时告警"。
版本：v1.0 · 2026-08-11 · 指标台账起始基线 = v1.0 交付状态
1. 指标设计原则
- 可自动化采集：每个指标都有可重复执行的命令，禁止手工数数。
- 双阈值门禁：每指标设
警告线（黄）与 门禁线（红），门禁线即发版红线。
- 三端分层：backend / analyzer / frontend 各自成组，避免以总分掩盖单端退化。
- 趋势优先：绝对值意义有限，连续期对比（台账）才是监控本质。
- 与产品指标隔离：本体系衡量 EvoCode 自身代码；对被分析项目输出 healthScore（产品功能，见《09》§3.5），二者不混算。
2. 代码质量指标体系
2.1 总览表
| 组 |
指标 |
采集命令 |
基线(v1.0) |
警告线 |
门禁线 |
| B-backend |
单测通过率 |
mvn test |
120/120 |
<100% |
<97% |
| B-backend |
测试用例数 |
mvn test |
120 |
<115 |
<110 |
| B-backend |
ArchUnit 规则 |
mvn test（架构测试类） |
全过 |
任 1 失败 |
任 1 失败 |
| A-analyzer |
单测通过率 |
pytest -q |
119/119 |
<100% |
<97% |
| A-analyzer |
ruff 静态检查 |
ruff check . |
0 error |
>0 |
>5 |
| A-analyzer |
格式化检查 |
ruff format --check . |
通过 |
不通过 |
不通过 |
| A-analyzer |
import 依赖边界 |
import-linter enforce（待建：requirements-dev.txt 声明 + .importlinter 配置，当前未安装） |
通过 |
不通过 |
不通过 |
| A-analyzer |
契约测试 |
scripts/check-contract.ps1 |
通过 |
不通过 |
不通过 |
| F-frontend |
lint |
npm run lint |
0 error |
>0 |
>5 |
| F-frontend |
类型检查+build |
npm run build |
通过 |
不通过 |
不通过 |
| F-frontend |
单测（vitest，TD-06 落地后） |
npm run test |
待建 |
— |
覆盖率门禁后定 |
| X-全链路 |
冒烟回归 7 项 |
scripts/smoke.ps1 |
通过 |
任 1 失败 |
任 1 失败 |
| X-安全 |
安全冒烟 |
scripts/security-smoke.ps1（2026-08-13 落地：T-S-05 无执行路径 / T-S-08 端口暴露 静态 + -Dynamic 时 T-S-07 排序注入 / T-S-01 恶意 zip） |
通过 |
不通过 |
不通过 |
| X-契约 |
错误码一致性 |
08 §4 T-C-02 |
通过 |
不通过 |
不通过 |
2.2 技术债专项指标（自身工程债）
| 指标 |
定义 |
公式 |
门禁 |
| 技术债总数 |
台账未清条目数（《10》§1.2） |
count(open) |
<8 |
| 高优先级债 |
P0+P1 未清条目 |
count(P0)+count(P1) |
发版前必须 = 0 |
| 技术债密度 |
未清债 / 最近 3 个月新增行数 |
count(open) / lines_added_3m |
趋势不恶化 |
| 新债引入率 |
本期新增技术债条目 |
count(new) |
每期 ≤ 3 |
| 债龄分布 |
最长未处理债龄 |
max(age) |
< 3 个月 |
| 契约漂移数 |
契约 vs 实现偏差（T-C-01~03 检出） |
count(mismatch) |
= 0 |
2.3 研发质量辅助指标（非门禁，趋势参考）
| 指标 |
采集方式 |
用途 |
| 三端代码行数 |
PowerShell：(git ls-files | ForEach-Object { (Get-Content $_).Count } | Measure-Object -Sum).Sum |
规模基线，防膨胀 |
| 测试与实现行比 |
测试行 / 实现行 |
覆盖合理性粗判 |
| 提交粒度 |
每期 commit 数与单次改动文件数 |
评审负荷参考 |
| 重复代码率 |
ruff/评审抽查 |
长期观察（Sonar 可用时接入） |
3. 监控机制
3.1 指标台账（docs/metrics/）
docs/metrics/
├── README.md # 指标说明 + 采集手册（引用本文档）
└── YYYY-MM-DD-vX.Y.md # 每版本快照，如 2026-08-11-v1.0.md
每期快照固定模板：
# 质量指标快照 vX.Y · YYYY-MM-DD
## 三端门禁
| 端 | 命令 | 结果 | 用例数 |
|---|---|---|---|
| backend | mvn test | ✅ | 120 |
| analyzer | pytest -q | ✅ | 119 |
| frontend | npm run lint && npm run build | ✅ | — |
## 技术债台账
| 等级 | 本期 | 上期 | 趋势 |
|---|---|---|---|
| P0 | 0 | 0 | → |
## 新增/关闭
- 新增：无
- 关闭：TD-01（analyzer 补 explain 端点）
3.2 采集节奏与触发
| 时机 |
动作 |
| 每次发版/里程碑 |
跑全量门禁 → 写快照 → 更新趋势 |
| 每阶段收尾 |
05 架构审查 → 更新《10》清单 → 快照 |
| 契约/API 变更 |
跑 T-C-01~03 → 检出即记入台账 |
| 门禁红 |
立即回填《10》新债条目 + 指定负责人 + 排期 |
3.3 告警与升级
- 黄（警告线）：快照标注 ⚠️，下一期复查。
- 红（门禁线）：阻断发版；进入《10》§6.2 流程；升级到阶段负责人。
- 趋势恶化：连续 2 期同指标下滑 → 自动升级为高优先级债。
3.4 技术债雷达图（可选，答辩/汇报用）
每期用 6 个专项指标画雷达图：总数 / P0+P1 / 密度 / 新债率 / 债龄 / 契约漂移，六维归一化到 0–100 分（越靠外越好），直观展示"债在收敛还是累积"。
4. 与既有门禁的衔接
| 设施 |
分工 |
| 《03-开发规范》DoD |
提交级：个人改动自证 |
| 《08-测试计划》§7/§8 |
阶段级：用例组 + 回归清单 |
| 本文档 §2.1 |
发版级：指标红线 |
| 《10》§4 优先级矩阵 |
债处理排期依据 |
| 《04》§10 ArchUnit |
结构债防线（D-1~D-6） |
门禁层级：提交(DoD) → 阶段(08) → 发版(本文档) → 债清理(10)，逐级加严。
5. 起始基线（v1.0 实测）
| 指标 |
值 |
证据 |
| backend 单测 |
120/120 |
08 测试计划 / README 进度 |
| analyzer 单测 |
119/119 |
同上 |
| frontend lint+build |
全绿 |
同上 |
| 技术债总数 |
12（TD-01~12） |
《10》§1.2 审计 |
| P0 待清 |
3（TD-01/08/11） |
《10》§4.2 |
| 契约漂移/悬空 |
2（TD-01 explain 契约已入但 analyzer 无实现端点；TD-02 dependency 字典已定义但迁移未建表） |
本次审计 |
首期快照已生成：docs/metrics/2026-08-13-v1.1.md（P9 交付时，backend 153 / analyzer 141 / frontend 12，短期债 TD-01/02/03/04/06/07/08/11/12 全部列为关闭项，形成闭环演示）。