用途：这是一份迭代式实践手册（playbook），用于把 Node 与 TypeScript 项目（NestJS + React 单体仓库）推进到满足 SonarQube Quality Gate 的状态，同时不破坏构建与流水线。核心思路是小步迭代、优先真实影响与低风险改动。
主要能力：1）给出必需输入清单，包括 SONAR_HOST_URL、具备分析权限的 SONAR_TOKEN、SONAR_PROJECT_KEY、SONAR_NEW_CODE_REFERENCE_BRANCH（默认 main）、单体仓库路径（apps/backend、apps/frontend、packages/*）、各应用带覆盖率的测试命令、各应用 lcov.info 报告路径、sonar-project.properties 或 CI 等价参数、覆盖率与分析的排除模式、质量门禁阈值，以及不可破坏的构建命令。2）优先级策略：New Code 优先，其次新 Bug 与漏洞、待审安全热点、关键与 PR 涉及模块的覆盖率、新 Code Smell、活跃区域重复与技术债，历史债仅在不妨碍冲刺目标时处理；并提供优先级打分启发式。3）反覆盖率虚高规则：新测试须覆盖正常、异常与边界，禁止仅用快照断言，避免无逻辑代码的琐碎测试。4）覆盖率不一致排查手册：当 SonarQube 覆盖率明显低于本地时，检查 lcov.info 中 SF: 路径是否含反斜杠、扫描日志是否有未映射文件、共享包覆盖率是否拖低全局，并给出路径规范化脚本（scripts/fix-lcov-paths.js）与 CI 守卫校验。5）分步流水线：检测现状、生成或更新 Sonar 配置、确保覆盖率真实读取、统一测试执行、按小批次迭代，并提供 sonar-scanner 与 Web API 查询命令。6）测试生成指引：识别未覆盖文件、选择单元/集成/组件/E2E 类型、Mock 策略、测试质量最低标准、命名与结构约定。7）Code Smell、Bug、安全整改清单；排除规则与权衡；完成定义与指标（如 new_coverage >= 80、new_bugs = 0 等）及所需证据。8）附 Sonar 属性、Jest、Vitest、GitHub Actions、GitLab CI 配置示例与 PR 检查清单。
使用方式：在 CI 与本地使用相同命令与参数运行测试并产出覆盖率，执行 sonar-scanner 时带上 -Dsonar.qualitygate.wait=true，再通过 API 拉取指标与问题列表进行分批修复，最后附上扫描输出、指标接口输出、分目录覆盖率与问题前后对比作为证据。
适用场景：NestJS + React 单体仓库的 SonarQube 质量门禁达标、CI 集成与覆盖率差异排查。
限制：若项目技术栈或流水线不同，相关配置需自行调整；资料未提供具体阈值以外的实际效果、收费信息或官方支持范围。